From 965014dcc8d83a8fab78777cf30dc1abbe75a0e0 Mon Sep 17 00:00:00 2001 From: Gerald Fruhmann Date: Thu, 3 Sep 2026 15:13:24 +0200 Subject: [PATCH] feat: add design-ux-artifacts skill (29 total, part 1/2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Structural, artifact-driven UX design skill grounded in Jesse James Garrett's "The Elements of User Experience" (5-plane model) and Rosenfeld/Morville/Arango's "Information Architecture for the Web and Beyond": problem brief, task/domain model, information architecture, user flows, interaction pattern decisions, low-fi wireframe, and anti-generic-AI visual design constraints — before any visual styling. Distinct from dev-design-ux, which covers Human-AI-Interaction trust/ onboarding/feedback design (HAX/PAIR/CHI2024/NNG) for AI-powered features — this skill owns information architecture and anti-generic-visual-design for business/enterprise UI. This is part 1/2: SKILL.md + command + housekeeping. The reference/ template files (referenced by relative path in SKILL.md prose, not markdown links, so the link checker is unaffected) land in a follow-up PR to stay under the 400-line PR size limit. Housekeeping: meta-help renumbered, plugin.json v3.1.0 -> v3.2.0, README/marketplace skill count 28 -> 29. Co-Authored-By: Claude Sonnet 5 --- .claude-plugin/marketplace.json | 2 +- README.md | 5 +- plugins/dev/.claude-plugin/plugin.json | 4 +- plugins/dev/commands/design-ux-artifacts.md | 10 + .../dev/skills/design-ux-artifacts/SKILL.md | 255 ++++++++++++++++++ plugins/dev/skills/meta-help/SKILL.md | 45 ++-- 6 files changed, 294 insertions(+), 27 deletions(-) create mode 100644 plugins/dev/commands/design-ux-artifacts.md create mode 100644 plugins/dev/skills/design-ux-artifacts/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 7f9eadf..6c3f45a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ { "name": "dev", "source": "./plugins/dev", - "description": "28 skills for software projects: Design (App, Secure, API, Data, Migration, UX, LLM, Observability, CI/CD, IaC, Public), Review (App, Architecture, Security, UX, UX Artifacts, LLM, Public), Tools (Debug, Test, Style, Accessibility, Performance), Meta. Grounded in MIT, CMU, Stanford curricula. Works with Claude Code and GitHub Copilot CLI.", + "description": "29 skills for software projects: Design (App, Secure, API, Data, Migration, UX, UX Artifacts, LLM, Observability, CI/CD, IaC, Public), Review (App, Architecture, Security, UX, UX Artifacts, LLM, Public), Tools (Debug, Test, Style, Accessibility, Performance), Meta. Grounded in MIT, CMU, Stanford curricula. Works with Claude Code and GitHub Copilot CLI.", "category": "development", "tags": ["best-practices", "security", "architecture", "llm", "accessibility", "performance", "ci-cd", "iac", "copilot-cli"] } diff --git a/README.md b/README.md index 0aedfde..660ceb7 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Opinionated best-practice rules for software projects — RAG systems, AI agents, data pipelines, full-stack web apps. Three detail levels: compact essential rules for `CLAUDE.md`, thematic rule files, and detailed reference docs. -Also a **Claude Code plugin**: install once, get 28 skills in every project. Also works as a **GitHub Copilot CLI plugin** — same repo, same skills. +Also a **Claude Code plugin**: install once, get 29 skills in every project. Also works as a **GitHub Copilot CLI plugin** — same repo, same skills. --- @@ -60,6 +60,7 @@ Or just describe what you need in natural language — Claude picks the right sk | `/dev:design-data` | Schema, normalization, indexes, CQRS / Event Sourcing | | `/dev:design-migration` | Zero-downtime strategy: Expand-Contract, Strangler Fig, Saga | | `/dev:design-ux` | UX/UI design: interaction model, trust, AI features, anti-patterns | +| `/dev:design-ux-artifacts` | Structural UX design: problem brief, task/domain model, IA, wireframe, anti-generic-AI visual design | | `/dev:design-llm` | LLM system: RAG, fine-tune vs. prompt, agents, evals, guardrails | | `/dev:design-observability` | SLO/SLI, Golden Signals, tracing, alerting, incident response | | `/dev:design-cicd` | CI/CD pipeline, deployment strategies (Blue-Green, Canary), DORA | @@ -90,7 +91,7 @@ Or just describe what you need in natural language — Claude picks the right sk | Skill | What it does | |---|---| -| `/dev:meta-help` | Navigation menu — shows all 28 skills, launches chosen one | +| `/dev:meta-help` | Navigation menu — shows all 29 skills, launches chosen one | | `/dev:meta-install` | Insert `essential-rules.md` into project `CLAUDE.md` (detects install vs. update) | | `/dev:meta-drift` | Compare installed rules block against current rule files | | `/dev:meta-sync` | Repo-internal: check if `claude/*.md` still reflects `reference/*.md` | diff --git a/plugins/dev/.claude-plugin/plugin.json b/plugins/dev/.claude-plugin/plugin.json index 264747c..3dedcf5 100644 --- a/plugins/dev/.claude-plugin/plugin.json +++ b/plugins/dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "dev", - "version": "3.1.0", - "description": "28 Skills für Design (inkl. LLM-Engineering/RAG/Agents, Observability/SRE, CI/CD, IaC/GitOps, UX/Human-AI Interaction, Repo-Publication), Security-Review (ISEC/Stanford/MIT, OWASP LLM Top 10), App-Audit (OWASP ASVS 5.0, DORA), Architektur-Review, Debug, Test, Styling, Accessibility (WCAG 2.2), Performance Engineering (MIT 6.172, USE Method) und Skill-Erstellung. Funktioniert mit Claude Code und GitHub Copilot CLI.", + "version": "3.2.0", + "description": "29 Skills für Design (inkl. LLM-Engineering/RAG/Agents, Observability/SRE, CI/CD, IaC/GitOps, UX/Human-AI Interaction, UX-Informationsarchitektur, Repo-Publication), Security-Review (ISEC/Stanford/MIT, OWASP LLM Top 10), App-Audit (OWASP ASVS 5.0, DORA), Architektur-Review, Debug, Test, Styling, Accessibility (WCAG 2.2), Performance Engineering (MIT 6.172, USE Method) und Skill-Erstellung. Funktioniert mit Claude Code und GitHub Copilot CLI.", "author": { "name": "Gerald" } } diff --git a/plugins/dev/commands/design-ux-artifacts.md b/plugins/dev/commands/design-ux-artifacts.md new file mode 100644 index 0000000..f9e002d --- /dev/null +++ b/plugins/dev/commands/design-ux-artifacts.md @@ -0,0 +1,10 @@ +--- +description: Structural, artifact-driven UX design based on Garrett's Elements of UX and Information Architecture for the Web — problem brief, task/domain model, IA, wireframe, anti-generic-AI visual design. +argument-hint: "[optional: context, e.g. 'project management dashboard' or 'admin settings screen']" +--- + +Design a screen, feature, or application through a traceable chain of +structural artifacts, before any visual styling. +Follow exactly the workflow definition in `${CLAUDE_PLUGIN_ROOT}/skills/design-ux-artifacts/SKILL.md`. + +Context: $ARGUMENTS diff --git a/plugins/dev/skills/design-ux-artifacts/SKILL.md b/plugins/dev/skills/design-ux-artifacts/SKILL.md new file mode 100644 index 0000000..558bc4e --- /dev/null +++ b/plugins/dev/skills/design-ux-artifacts/SKILL.md @@ -0,0 +1,255 @@ +--- +name: dev-design-ux-artifacts +description: > + Structural, artifact-driven UX/UI design workflow grounded in Jesse James + Garrett's "The Elements of User Experience" (5-plane model: Strategy, Scope, + Structure, Skeleton, Surface) and Rosenfeld/Morville/Arango's "Information + Architecture for the Web and Beyond". Produces a traceable chain of + intermediate artifacts (problem brief, task inventory, domain model, + information architecture, user flows, wireframes) BEFORE any visual styling, + and applies an anti-generic-AI-visual-design discipline for enterprise/ + business software. Use this skill when the user wants to design a new + screen, feature, or application structurally — or asks "design this + properly, not just make it look nice", "what's the information architecture + here", "plan the screens/navigation before we build", "avoid a generic + AI-generated look", "structure before styling". Distinct from dev-design-ux, + which covers Human-AI-Interaction trust/onboarding/feedback design for + AI-powered features (HAX/PAIR/CHI2024/NNG) — this skill owns information + architecture, task/domain modeling, and anti-generic-visual-design for + business and enterprise UI. +--- + +# UX Design — Structural Artifacts (IA-based) + +Turns a feature idea into a traceable chain of design artifacts before any +visual design happens. Standard: Garrett's 5-plane model + IA for the Web +and Beyond. No screen gets styled until its structure is validated. + +--- + +## Core Philosophy (Garrett · Rosenfeld/Morville/Arango) + +> "Each plane depends on the plane below it ... You can't build the skeleton +> of a product until you know what its structure will be." — Jesse James Garrett + +Design for the workflow, not for the screenshot. Structure before styling. +Every UI element must trace back to a user task, an information requirement, +a workflow, or a system constraint — never to "making it look modern." + +--- + +## Step 0 — Problem Brief (Strategy plane) + +Gather, or ask **once** if missing: + +```text +Product / Feature: +Primary Users: +Primary Goal: +Main Tasks: +Business Constraints: +Technical Constraints: +Known Problems: +Open Questions: +Success Criteria: +``` + +Separate confirmed requirements from assumptions from open questions. +Do not propose any UI solution in this step. Mark gaps as `[Assumption]`. + +--- + +## Step 1 — Model the Domain (Scope plane) + +Produce, as applicable: + +1. **User/Role Matrix** — if more than one role uses the product, check + early whether a single interface can even serve all of them. +2. **Task Inventory** — actor, goal, frequency, criticality, required data, + starting point, expected outcome. Rank by UX importance. +3. **Domain/Entity Model** — entities, key attributes, relationships, + important actions. + +Templates: `references/ia-artifact-templates.md` (sections 2–4). + +--- + +## Step 2 — Structure the Information (Structure plane) + +1. **Content Inventory** — every piece of information that must actually be + displayed, grouped per screen/object (more granular than the entity model). +2. **Information Hierarchy** — Level 1 (always visible) through Level 4 + (on demand). This is what stops AI-generated layouts from rendering + everything with equal visual weight. +3. **Navigation Map** — classify each nav item as Global / Local / + Contextual / Utility. +4. **Screen Inventory** — screen, purpose, primary task, entry point. Guards + against unnecessary screens/dialogs before wireframing. + +Templates: `references/ia-artifact-templates.md` (sections 5–8). + +--- + +## Step 3 — Map Flows and Decide Patterns + +1. **User Flows** for every critical task — entry point, happy path, + alternative path, error path, exit state. Check: how many steps, any + unnecessary navigation or context switches, is the user always oriented. +2. **Interaction Pattern Decision** — for each nontrivial UI decision, + document candidate patterns, the choice, the reason, and the trade-off. + Do not invent a new pattern when an established one + (master-detail, split view, tabs, faceted search, progressive disclosure, + wizard, inline editing, bulk actions, command palette, drawer) fits. +3. **UX Decision Log** (`DEC-NNN`) — decision, reason, rejected alternatives + and why. Do not contradict a prior entry without stating why it changed. + +Templates: `references/ia-artifact-templates.md` (sections 9–11). + +--- + +## Step 4 — Research (only if patterns are non-obvious) + +Search for the **UX problem**, not for visual inspiration: + +- Good: "master detail interface pattern", "enterprise project detail page + UX", "faceted search UX", "bulk actions UX", "settings navigation pattern" +- Bad: "beautiful dashboard", "modern SaaS UI", "cool admin dashboard" + +Analyze structural patterns in mature products (GitHub, Jira, Linear, Notion, +Slack, Figma, Stripe Dashboard) — how they navigate between objects, separate +list/detail, expose frequent actions. Extract the pattern, do not copy the +visual appearance. + +Design systems worth consulting for concrete guidance on when (not) to use a +component: see `references/anti-ai-visual-checklist.md`. + +--- + +## Step 5 — Low-Fidelity Wireframe (Skeleton plane) + +Text/ASCII schematic only. No color, shadow, radius, illustration, or +branding. A wireframe must answer: + +- Where am I? Where do I find X? How do I move between areas? +- What is important vs. secondary? What actions can I take here? + +If these questions can't be answered at wireframe fidelity, visual design +will not fix it — go back to Step 2/3. + +Also produce at this stage, as applicable: + +- **Component Inventory** — check for unnecessary special-purpose components. +- **State Matrix** — loading/empty/error/permission-denied/partial-data/ + success/offline, plus element states (default/hover/focus/selected/ + disabled/read-only/validation-error). +- **Permission Matrix** — action × role, drives visible/disabled UI. +- **Data Density Specification** — target environment, viewport, expected + visible rows, interaction mode, density. + +Templates: `references/ia-artifact-templates.md` (sections 12–16). + +--- + +## Step 6 — Validate Structure Before Styling + +Explicitly confirm: + +- Does the user find everything they need? +- Is navigation understandable without explanation? +- Are frequent actions reachable quickly? +- Are relationships between objects clear? +- Are there unnecessary steps? +- Is information density appropriate for the target environment? + +Do not proceed to visual design until these hold. + +--- + +## Step 7 — Visual Design Constraints (Surface plane, structure-driven) + +State constraints before applying any actual color/spacing/component styling: +typography, spacing, containers, radius, shadows, color, icons, animation — +each grounded in a functional reason (see `references/ia-artifact-templates.md` +section 17). + +Then apply the anti-generic-AI-visual-design discipline: avoid oversized hero +sections, cards for everything, glassmorphism, decorative gradients/blobs, +giant typography for ordinary content, repeated "title+subtitle+3 cards" +sections, fake metrics, excessive badges/pills. Full checklist: +`references/anti-ai-visual-checklist.md`. + +For AI-powered features specifically (trust calibration, onboarding, feedback +design, dark-pattern-free AI UX) — see `dev:design-ux`, which owns that axis. + +--- + +## Step 8 — Requirement → UI Traceability + +For every UI element in the resulting design, confirm it traces to a row in: + +| Requirement | User Task | Screen | UI Element | +|---|---|---|---| + +Any element with no traceable reason is a candidate for removal — flag it +rather than keeping it "because it looks complete." + +--- + +## Output — Design File + +Write the result to `./design-ux-artifacts.md`: + +```markdown +# UX Artifacts: [Product / Feature Name] +Date: YYYY-MM-DD + +## Problem Brief +[confirmed requirements / assumptions / open questions / constraints / success criteria] + +## Role Matrix +| Role | Main Goal | Frequent Tasks | Required Information | Permissions | + +## Task Inventory +[ranked by UX importance] + +## Domain / Entity Model +[entities, attributes, relationships, actions] + +## Information Architecture +### Content Inventory +### Information Hierarchy +### Navigation Map +### Screen Inventory + +## User Flows +[per critical task: entry point / happy path / alternative path / error path / exit state] + +## Interaction Pattern Decisions +[problem / candidates / decision / reason / trade-off] + +## UX Decision Log +[DEC-NNN entries] + +## Low-Fidelity Wireframe +[ASCII/text, no styling] + +## Component Inventory / State Matrix / Permission Matrix / Data Density + +## Visual Design Constraints +[stated before applying visual styling] + +## Requirement -> UI Traceability +| Requirement | User Task | Screen | UI Element | + +## Assumptions & Open Questions +- [Assumption]: ... +- [to verify]: ... + +## Next Steps (prioritized) +1. ... +``` + +## Reference Files + +- `references/ia-artifact-templates.md` — concrete template for each of the 18 artifacts +- `references/anti-ai-visual-checklist.md` — generic-AI/SaaS visual anti-patterns to avoid, and what to prefer instead diff --git a/plugins/dev/skills/meta-help/SKILL.md b/plugins/dev/skills/meta-help/SKILL.md index 1d06c60..66b67b2 100644 --- a/plugins/dev/skills/meta-help/SKILL.md +++ b/plugins/dev/skills/meta-help/SKILL.md @@ -23,35 +23,36 @@ Which skill should start? 4 design-data Schema, normalization, indexes, CQRS / Event Sourcing 5 design-migration Migration strategy: zero-downtime, Strangler Fig, Saga 6 design-ux UX/UI design: interaction, trust, AI features, anti-patterns - 7 design-llm LLM system: RAG, fine-tune, agent, eval strategy, guardrails - 8 design-observability Observability: SLO/SLI, golden signals, tracing, alerting, incident response - 9 design-cicd CI/CD pipeline: deployment strategies, DORA metrics, trunk-based dev - 10 design-iac Infrastructure as Code: Terraform, GitOps, state management, drift detection + 7 design-ux-artifacts Structural UX design: problem brief, task/domain model, IA, wireframe, anti-generic-AI visual design + 8 design-llm LLM system: RAG, fine-tune, agent, eval strategy, guardrails + 9 design-observability Observability: SLO/SLI, golden signals, tracing, alerting, incident response + 10 design-cicd CI/CD pipeline: deployment strategies, DORA metrics, trunk-based dev + 11 design-iac Infrastructure as Code: Terraform, GitOps, state management, drift detection 🔍 REVIEW - 11 review-app Full audit: architecture, security, tests, CI/CD, observability - 12 review-arch Architecture: coupling, anti-patterns, quality attributes, ADR - 13 review-secure Security: crypto, injection, memory safety, GDPR/ISO/EU AI Act - 14 review-ux UX audit: AI anti-patterns, dark patterns, trust design - 15 review-ux-artifacts Structural UX audit: information architecture, requirement-to-UI traceability, generic-AI template detection - 16 review-llm LLM audit: architecture, evals, prompt injection, OWASP LLM Top 10 - 17 review-public Repo public scan: secrets in history, PII in tests, governance files, CI/CD hardening + 12 review-app Full audit: architecture, security, tests, CI/CD, observability + 13 review-arch Architecture: coupling, anti-patterns, quality attributes, ADR + 14 review-secure Security: crypto, injection, memory safety, GDPR/ISO/EU AI Act + 15 review-ux UX audit: AI anti-patterns, dark patterns, trust design + 16 review-ux-artifacts Structural UX audit: information architecture, requirement-to-UI traceability, generic-AI template detection + 17 review-llm LLM audit: architecture, evals, prompt injection, OWASP LLM Top 10 + 18 review-public Repo public scan: secrets in history, PII in tests, governance files, CI/CD hardening 🏗️ DESIGN (continued) - 18 design-public Publication plan: secrets audit, license, governance docs, branch protection, supply chain + 19 design-public Publication plan: secrets audit, license, governance docs, branch protection, supply chain 🛠️ TOOLS - 19 tool-debug Stack-aware root cause analysis with fix suggestions - 20 tool-test Write, improve, or plan tests - 21 tool-style CSS / design system + visual basics (color, typography, spacing, loading) - 22 tool-a11y Accessibility audit: WCAG 2.2, screen reader, EU Accessibility Act - 23 tool-perf Performance engineering: USE Method, flamegraph, bottleneck, Bentley Rules + 20 tool-debug Stack-aware root cause analysis with fix suggestions + 21 tool-test Write, improve, or plan tests + 22 tool-style CSS / design system + visual basics (color, typography, spacing, loading) + 23 tool-a11y Accessibility audit: WCAG 2.2, screen reader, EU Accessibility Act + 24 tool-perf Performance engineering: USE Method, flamegraph, bottleneck, Bentley Rules 📁 META - 24 meta-install Add best-practice rules to a project CLAUDE.md - 25 meta-drift Compare project CLAUDE.md against current rule files - 26 meta-sync Keep reference/*.md and claude/*.md in sync - 27 meta-create-skill Build a new skill: research, structure, all files + 25 meta-install Add best-practice rules to a project CLAUDE.md + 26 meta-drift Compare project CLAUDE.md against current rule files + 27 meta-sync Keep reference/*.md and claude/*.md in sync + 28 meta-create-skill Build a new skill: research, structure, all files → Enter a number, or directly describe what you need. ``` @@ -67,4 +68,4 @@ Load and follow exactly: `..//SKILL.md` ## Rules - Show menu immediately, no intro - After the choice: start directly, do not explain or ask again -- Never load all 27 skills at once — always only the chosen one +- Never load all 29 skills at once — always only the chosen one