From d9e0eba7a239f1f5149ce037c7cd1f96e589b17a Mon Sep 17 00:00:00 2001 From: Gerald Fruhmann Date: Thu, 3 Sep 2026 14:45:14 +0200 Subject: [PATCH] feat: add review-ux-artifacts skill (28 total) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Structural UX review skill grounded in Jesse James Garrett's "Elements of User Experience" and Rosenfeld/Morville/Arango's "Information Architecture for the Web and Beyond": anti-generic-AI visual audit (classify every card/ gradient/badge as necessary vs. decorative), requirement-to-UI traceability check, and detection of generic AI/SaaS template signatures (card-only dashboards, hero-logo-strip-3-cards marketing pages). Distinct from dev-review-ux, which audits Human-AI-Interaction trust/ onboarding design (HAX/PAIR/CHI2024/NNG) for AI-powered features — this skill owns information architecture and anti-generic-visual-design audits. Housekeeping: meta-help renumbered, plugin.json v3.1.0, README/marketplace skill count 27 -> 28. Co-Authored-By: Claude Sonnet 5 --- .claude-plugin/marketplace.json | 2 +- README.md | 5 +- plugins/dev/.claude-plugin/plugin.json | 4 +- plugins/dev/commands/review-ux-artifacts.md | 10 + plugins/dev/skills/meta-help/SKILL.md | 25 +-- .../dev/skills/review-ux-artifacts/SKILL.md | 199 ++++++++++++++++++ .../anti-ai-audit-classification.md | 63 ++++++ .../generic-ai-template-signatures.md | 49 +++++ 8 files changed, 340 insertions(+), 17 deletions(-) create mode 100644 plugins/dev/commands/review-ux-artifacts.md create mode 100644 plugins/dev/skills/review-ux-artifacts/SKILL.md create mode 100644 plugins/dev/skills/review-ux-artifacts/references/anti-ai-audit-classification.md create mode 100644 plugins/dev/skills/review-ux-artifacts/references/generic-ai-template-signatures.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 4aeb9d9..7f9eadf 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,7 +6,7 @@ { "name": "dev", "source": "./plugins/dev", - "description": "27 skills for software projects: Design (App, Secure, API, Data, Migration, UX, LLM, Observability, CI/CD, IaC, Public), Review (App, Architecture, Security, UX, LLM, Public), Tools (Debug, Test, Style, Accessibility, Performance), Meta. Grounded in MIT, CMU, Stanford curricula. Works with Claude Code and GitHub Copilot CLI.", + "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.", "category": "development", "tags": ["best-practices", "security", "architecture", "llm", "accessibility", "performance", "ci-cd", "iac", "copilot-cli"] } diff --git a/README.md b/README.md index c4dfa78..0aedfde 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 27 skills in every project. Also works as a **GitHub Copilot CLI plugin** — same repo, same skills. +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. --- @@ -73,6 +73,7 @@ Or just describe what you need in natural language — Claude picks the right sk | `/dev:review-arch` | Coupling, anti-patterns, quality attributes, ADR recommendations | | `/dev:review-secure` | Crypto, injection, memory safety, GDPR / ISO 27001 / EU AI Act | | `/dev:review-ux` | UX audit based on HAX, PAIR, CHI 2024 and Nielsen Norman | +| `/dev:review-ux-artifacts` | Structural UX audit: information architecture, requirement-to-UI traceability, generic-AI template detection | | `/dev:review-llm` | LLM audit: architecture, evals, prompt injection, OWASP LLM Top 10 | ### Tools @@ -89,7 +90,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 27 skills, launches chosen one | +| `/dev:meta-help` | Navigation menu — shows all 28 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 354a557..264747c 100644 --- a/plugins/dev/.claude-plugin/plugin.json +++ b/plugins/dev/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "dev", - "version": "3.0.0", - "description": "27 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.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.", "author": { "name": "Gerald" } } diff --git a/plugins/dev/commands/review-ux-artifacts.md b/plugins/dev/commands/review-ux-artifacts.md new file mode 100644 index 0000000..c631fad --- /dev/null +++ b/plugins/dev/commands/review-ux-artifacts.md @@ -0,0 +1,10 @@ +--- +description: Structural UX audit — information architecture, requirement-to-UI traceability, and anti-generic-AI visual design detection. +argument-hint: "[optional: context, e.g. 'dashboard screenshot' or 'describe this admin UI']" +--- + +Audit an existing design or interface for structural soundness and +generic-AI/SaaS-template visual patterns. +Follow exactly the workflow definition in `${CLAUDE_PLUGIN_ROOT}/skills/review-ux-artifacts/SKILL.md`. + +Context: $ARGUMENTS diff --git a/plugins/dev/skills/meta-help/SKILL.md b/plugins/dev/skills/meta-help/SKILL.md index d7ddd12..1d06c60 100644 --- a/plugins/dev/skills/meta-help/SKILL.md +++ b/plugins/dev/skills/meta-help/SKILL.md @@ -33,24 +33,25 @@ Which skill should start? 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-llm LLM audit: architecture, evals, prompt injection, OWASP LLM Top 10 - 16 review-public Repo public scan: secrets in history, PII in tests, governance files, CI/CD hardening + 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 🏗️ DESIGN (continued) - 17 design-public Publication plan: secrets audit, license, governance docs, branch protection, supply chain + 18 design-public Publication plan: secrets audit, license, governance docs, branch protection, supply chain 🛠️ TOOLS - 18 tool-debug Stack-aware root cause analysis with fix suggestions - 19 tool-test Write, improve, or plan tests - 20 tool-style CSS / design system + visual basics (color, typography, spacing, loading) - 21 tool-a11y Accessibility audit: WCAG 2.2, screen reader, EU Accessibility Act - 22 tool-perf Performance engineering: USE Method, flamegraph, bottleneck, Bentley Rules + 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 📁 META - 23 meta-install Add best-practice rules to a project CLAUDE.md - 24 meta-drift Compare project CLAUDE.md against current rule files - 25 meta-sync Keep reference/*.md and claude/*.md in sync - 26 meta-create-skill Build a new skill: research, structure, all files + 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 → Enter a number, or directly describe what you need. ``` diff --git a/plugins/dev/skills/review-ux-artifacts/SKILL.md b/plugins/dev/skills/review-ux-artifacts/SKILL.md new file mode 100644 index 0000000..935add9 --- /dev/null +++ b/plugins/dev/skills/review-ux-artifacts/SKILL.md @@ -0,0 +1,199 @@ +--- +name: dev-review-ux-artifacts +description: > + Structural UX/UI audit 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", plus a practice-based + anti-generic-AI-visual-design checklist. Audits whether an existing design + or interface has a traceable information architecture behind it, whether + every UI element traces back to a requirement/task/workflow, and whether + the visual layer defaulted to a generic AI-generator/SaaS-template look + (glassmorphism, card-for-everything dashboards, hero-logo-strip-3-cards + marketing pages) instead of a structure-driven design. Use this skill when + the user asks "does this look AI-generated", "review the information + architecture", "why does every screen look like a generic dashboard", + "audit this UI for unnecessary elements", "is this structurally sound or + just styled". Distinct from dev-review-ux, which audits Human-AI-Interaction + trust/onboarding/feedback design for AI-powered features (HAX/PAIR/CHI2024/ + NNG) — this skill owns information architecture and anti-generic-visual- + design audits for business and enterprise UI. +--- + +# UX Review — Structural Artifacts & Anti-AI Visual Audit + +Evaluates whether an interface has a traceable structure behind it, and +whether its visual layer is a deliberate, structure-driven design or a +generic AI/SaaS-template default. Every finding cites the specific element, +signature, or missing artifact. + +--- + +## Core Philosophy (Garrett · Rosenfeld/Morville/Arango) + +> "You can't build the skeleton of a product until you know what its +> structure will be." — Jesse James Garrett + +If everything is visually important, nothing is. A mature interface makes +work easier, not a demonstration that it was designed. This review checks +both structure (is there a defensible information architecture) and surface +(does the visual layer serve that structure, or override it with decoration). + +--- + +## Step 0 — Determine Context & Audit Scope + +**Auto-discovery: what has been provided?** + +| Input Type | Approach | +|---|---| +| Screenshot / mockup | Analyze directly; describe UI elements and structure | +| Code (HTML/JSX/templates) | Read and derive structure and component usage | +| Design spec / existing `design-ux-artifacts.md` | Compare implementation against the documented artifacts | +| Verbally described feature | Use description as basis; mark assumptions | + +Report concisely what was detected: +`Type: Enterprise dashboard | Structural artifacts found: none | Phase: Production`. + +If a `design-ux-artifacts.md` exists in the project, read it first — it is +the source of truth for what each element is supposed to trace back to. + +--- + +## Step 1 — Four Audit Dimensions + +Work through all four dimensions. Findings in this format: + +```text +[Dimension] Title · Severity (Critical/High/Medium/Low) · Finding · Fix +``` + +Severity definition: +- **Critical** — Interface has no discoverable structure, or is a wholesale + generic-template copy with no adaptation to actual content +- **High** — Significant structural gap or template signature that will + visibly hurt daily usability or credibility +- **Medium** — Improvement recommended; no immediate harm +- **Low** — Cosmetic, or only relevant at scale + +### Dimension 1 — Anti-AI Visual Audit + +Classify every card, rounded container, icon, badge, pill, gradient, large +heading, decorative element, and shadow as: structurally necessary / +functionally useful / informational / branding / decorative only. Recommend +removing or simplifying decorative-only elements unless a strong reason is +given. Format and classification rules: `references/anti-ai-audit-classification.md`. + +### Dimension 2 — Requirement → UI Traceability + +For each significant UI element, attempt to trace it to a task, information +requirement, workflow, or constraint. Elements with no traceable reason are +flagged as likely unnecessary — recommend confirming before removal, not +auto-deleting. Rules: `references/anti-ai-audit-classification.md`. + +### Dimension 3 — Generic AI/SaaS Template Detection + +Check for the tell-tale signatures: dashboards built entirely from floating +rounded cards, hero→logo-strip→3-feature-cards→stats→testimonials→CTA→footer +marketing pages, repeated "title+subtitle+3 cards" sections, fake/placeholder +metrics. Full signature list with severity: `references/generic-ai-template-signatures.md`. + +### Dimension 4 — Structure-Before-Styling Check + +Determine whether structural artifacts (information architecture, user +flows, wireframe) exist or were evidently followed before visual polish was +applied. Signals that structure was skipped: everything rendered with equal +visual weight (no information hierarchy), ad hoc navigation not traceable to +a navigation model, screens/dialogs with no clear primary task. When +combined with a Dimension 3 finding, escalate to a single Critical finding +per `references/generic-ai-template-signatures.md`. + +--- + +## Step 2 — UX Critique for Non-Trivial Issues + +For findings beyond a simple classification table, use: + +```text +Issue: ... +Impact: ... +Severity: Critical / High / Medium / Low +Recommendation: ... +``` + +Evaluate by: severity of consequence · frequency · user impact · fix +complexity. + +--- + +## Step 3 — Consolidate Findings + +1. Sort all findings by severity (Critical → Low) +2. Assign a traffic light per dimension: 🟢 / 🟡 / 🔴 +3. List Top-3 Quick Wins separately (high impact, low effort) +4. Mark findings without a concrete file/screen reference as `[Assumption - to be verified]` + +--- + +## Step 4 — Write Report + +Output to `./review-ux-artifacts-report.md`: + +```markdown +# UX Structural Review: [Product / Feature Name] +Date: YYYY-MM-DD +Framework basis: Garrett 5-plane model · IA for the Web and Beyond · Anti-AI visual checklist + +## Detected Context +[Type, structural artifacts found (if any), phase] + +## Traffic Light Overview +| Dimension | Status | #Critical | #High | Most notable finding | +|---|---|---|---|---| +| Anti-AI Visual Audit | ... | ... | ... | ... | +| Requirement -> UI Traceability | ... | ... | ... | ... | +| Generic AI/SaaS Template Detection | ... | ... | ... | ... | +| Structure-Before-Styling | ... | ... | ... | ... | + +## Top-3 Quick Wins +1. [Title] · Effort: S (<30min) · [concrete fix] +2. ... +3. ... + +## Full Finding List + +### Critical +- **Title** · Finding: ... · Fix: ... · Reference: [dimension/signature] + +### High +### Medium +### Low + +## Element Classification Table +| Element | Classification | Keep? | Reason | + +## Not Evaluated / Assumptions +- [To be verified]: ... + +--- +*Generated with AI assistance (Claude Code + dev-best-practices plugin). +Structural findings should be validated with actual users before large-scale rework.* +``` + +--- + +## Rules + +- No speculative findings — only with a concrete reference to the submitted + design/code or a clearly demonstrable gap. Mark uncertain items as + `[to be verified]`. +- Do not auto-remove flagged elements — report first, implement on request. +- For AI-feature trust/onboarding/dark-pattern findings (chat vs. GUI + validation, confidence display, ELIZA effect, etc.) — defer to + `dev:review-ux`; do not duplicate that scope here. +- Explicitly mention what works well — this is a structural review, not a + pure defect list. + +## Reference Files + +- `references/anti-ai-audit-classification.md` — element classification scheme, UX critique format, traceability check +- `references/generic-ai-template-signatures.md` — concrete generic-template signatures with severity, structural-skip detection diff --git a/plugins/dev/skills/review-ux-artifacts/references/anti-ai-audit-classification.md b/plugins/dev/skills/review-ux-artifacts/references/anti-ai-audit-classification.md new file mode 100644 index 0000000..4efa9d7 --- /dev/null +++ b/plugins/dev/skills/review-ux-artifacts/references/anti-ai-audit-classification.md @@ -0,0 +1,63 @@ +# Anti-AI Visual Audit — Element Classification + +Classification scheme for the per-element Anti-AI Audit (Dimension 1 of the +review). Apply to every card, rounded container, icon, badge, pill, gradient, +large heading, decorative element, and shadow found in the design. + +--- + +## Classification Categories + +| Category | Definition | Recommended Action | +|---|---|---| +| Structurally necessary | Removing it breaks layout comprehension or grouping that reflects the domain model | Keep | +| Functionally useful | Enables or clarifies an action or interaction | Keep | +| Informational | Conveys data the user needs (status, count, relationship) | Keep, but check it's not over-styled | +| Branding | Deliberate, consistent brand expression (not filler) | Keep if consistent with a documented brand system | +| Decorative only | No functional, informational, or brand reason found | Remove or simplify unless a strong reason is given | + +## Audit Table Format + +| Element | Classification | Keep? | Reason | +|---|---|---|---| +| Project card | Informational | Keep | Represents one distinct entity from the domain model | +| Gradient header | Decorative only | Remove | No status or branding meaning | +| Status pill | Informational | Keep | Encodes state that changes and matters | +| Risk icon | Decorative only (low value) | Remove | Icon doesn't aid recognition beyond the label | + +--- + +## UX Critique Entry Format + +```text +Issue: [what is wrong] +Impact: [consequence for the user or the interface] +Severity: Critical / High / Medium / Low +Recommendation: [concrete fix] +``` + +Evaluate severity by combining: Severity of consequence · Frequency of +occurrence · User impact · Fix complexity. A low-severity, high-frequency +issue can outrank a high-severity, rare one for prioritization purposes — +call this out explicitly when it applies. + +--- + +## Requirement -> UI Traceability Check + +For each UI element under review, attempt to find a row that justifies it: + +| Requirement | User Task | Screen | UI Element | +|---|---|---|---| + +If no row can be constructed for an element even after checking the product's +stated requirements and tasks, flag it explicitly: + +```text +[UI Element] has no traceable requirement, task, workflow, or constraint. +Likely candidate for removal — confirm with the team before deleting. +``` + +Do not flag elements required for legal/accessibility/compliance reasons +even if no product requirement mentions them explicitly (e.g. focus +indicators, skip links). diff --git a/plugins/dev/skills/review-ux-artifacts/references/generic-ai-template-signatures.md b/plugins/dev/skills/review-ux-artifacts/references/generic-ai-template-signatures.md new file mode 100644 index 0000000..3ff3ed2 --- /dev/null +++ b/plugins/dev/skills/review-ux-artifacts/references/generic-ai-template-signatures.md @@ -0,0 +1,49 @@ +# Generic AI/SaaS Template Signatures + +Concrete signatures that indicate a design jumped straight to visual polish +without a structural design pass, or defaulted to a generic AI-generator +template. Flag any match as a finding. + +--- + +## Application / Dashboard Signature + +| Signature | Test | Severity | +|---|---|---| +| Dashboard built entirely from floating rounded cards | Is there any grouping, division, or hierarchy beyond "put it in a card"? | High | +| Every content type wrapped in an identical card component | Do unrelated content types (text, table, single metric) get the same container? | Medium | +| Oversized hero/header area with no functional content | Does the top of the screen show identity/status data, or just decoration? | Medium | +| Heavy use of glassmorphism / translucent panels | Any functional reason (e.g. overlay context) or purely decorative? | Medium | +| Icon in front of every heading/label | Does the icon aid recognition, or is it decorative padding? | Low | +| Large gradient accents with no status/branding meaning | Does the gradient encode information, or is it filler? | Medium | +| Excessive whitespace with no hierarchy purpose | Is whitespace used to separate meaning, or just to look "clean"? | Low | +| Numerous badges/pills with low information value | Does the badge state change and matter to the user? | Low | +| Fake or placeholder metrics presented as real data | Would removing the metric change any user decision? | High | + +## Marketing/Content Page Signature + +| Signature | Test | Severity | +|---|---|---| +| Hero -> Logo Strip -> 3 Feature Cards -> Stats -> Testimonials -> CTA -> Footer | Does the page follow this exact generic sequence regardless of actual content? | High | +| Every section in its own rounded container | Is there deliberate variation in section density/layout, or a repeated template block? | Medium | +| Section content genuinely determined by communication goal | Or could sections be reordered/removed without loss of meaning? | Medium | + +--- + +## Structural-Skip Detection + +Independent of visual signatures, check whether structure was skipped entirely: + +- No evidence of an information hierarchy (everything rendered with equal + visual weight) → structure phase likely skipped. +- Navigation model not traceable to a Navigation Map (items feel ad hoc) + → structure phase likely skipped. +- Screens/dialogs exist with no clear primary task → Screen Inventory likely + skipped. +- UI elements present with no traceable requirement, task, or workflow behind + them → see traceability check. + +When several structural-skip signals combine with a generic-template +signature, report a single **Critical** finding: "design appears to have +skipped the structural phase and gone directly to visual template +application," with the specific signatures as supporting evidence.