uiux-storybook-architect 2.0.2 → 3.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 # UI/UX Storybook Architect
 
-### Design direction before code—not another generic AI landing page.
+### Design reasoning before code—not another interchangeable AI interface.
 
 An interview-driven design skill for Claude Code, OpenAI Codex, Google Antigravity, Cursor, Windsurf, and GitHub Copilot.
 
@@ -18,31 +18,26 @@ An interview-driven design skill for Claude Code, OpenAI Codex, Google Antigravi
 
 ## In one sentence
 
-You describe the product; the skill interviews you with easy multiple-choice questions, proposes three genuinely different design directions, turns your choice into a complete design specification, and helps your coding agent build it accurately.
+You describe the product; the skill interviews you with easy multiple-choice questions, reasons from your users, tasks, content, and business goal before choosing any look, proposes three strategically different directions, turns your choice into a complete design specification in which every decision is traceable, and helps your coding agent build it accurately.
 
 No design vocabulary is required.
 
 ## Why this exists
 
-AI can generate a polished interface quickly, but unconstrained output often converges on the same defaults:
+AI can generate a polished interface quickly, but unconstrained output converges on whatever is most probable. First it was centered heroes, indigo, Inter, three feature cards, and uniform spacing. Then it became asymmetric editorial heroes, warm paper with one burnt accent, oversized type, bento grids, and hairline rules. Both are the same failure: an interface that could be reused for an unrelated company by changing only the logo, headline, accent color, and images.
 
-- centered hero copy;
-- blue or purple accent colors;
-- Inter everywhere;
-- three feature cards;
-- identical spacing between every section;
-- vague copy about “transforming your workflow.”
-
-This skill adds the missing design process before implementation. It grounds decisions in the audience and product, forces meaningful visual divergence, records the chosen direction, and checks the build for accessibility and fidelity.
+This skill treats that interchangeability as the defect. It reasons from users, tasks, content, business goal, trust, and accessibility before choosing any visual value; it separates marketing surfaces (persuasion, proof, conversion) from product surfaces (workflows, data, states, keyboard); it presents three strategically different directions; and it requires every decision to trace back to the brief. Familiar patterns are allowed when they fit. Unreasoned repetition is not.
 
 | Without the skill | With the skill |
 |---|---|
-| The agent guesses what “premium” means | The agent offers three concrete art directions |
-| Design decisions change while coding | Decisions are recorded before implementation |
-| Pages follow a familiar template | Page order follows the buyer’s belief sequence |
-| Colors and spacing drift between components | Values come from shared design tokens |
-| Motion is added for decoration | Motion has a purpose, budget, and reduced-motion fallback |
-| Accessibility is checked at the end | Accessibility is part of the specification and audit |
+| The agent guesses what “premium” means | The agent resolves “premium” for this audience and category, then designs from context |
+| Dashboards get landing-page layouts | Marketing and product surfaces are reasoned separately |
+| Three directions are three color schemes | Three directions differ in strategy: what the user sees and does first |
+| Design decisions change while coding | Decisions are recorded with a reason before implementation |
+| Pages follow a category template | Section order follows the reader’s decision journey; screens follow the task model |
+| Colors and spacing drift between components | Values come from shared design tokens, organized in layers |
+| Motion is added for decoration | Motion has a job, a budget, and a reduced-motion fallback |
+| Accessibility is checked at the end | WCAG 2.2 AA shapes decisions at every stage and is gated with evidence |
 
 ## Who it is for
 
@@ -126,11 +121,11 @@ Discover → Choose direction → Specify → Write copy → Plan motion → Bui
 
 ### 1. Discovery without the blank-page problem
 
-The skill asks eight focused questions with concrete answer choices, a recommended option, and the consequence of each choice. It records the audience, their top tasks, product constraints, brand character, success measures, and assumptions in `design/00-brief.md`.
+The skill asks focused questions with concrete answer choices, a recommended option, and the consequence of each choice. Every question changes a design decision: who uses it and how often, what they must do, what the business needs, what happens if it goes wrong, what content exists, where the brand sits. It records a one-line context profile, a marketing-or-product label for every surface, users, tasks, and assumptions in `design/00-brief.md`.
 
 ### 2. Three directions that are actually different
 
-Before writing tokens or components, the skill proposes three directions that differ in layout logic, typography, palette, density, surface treatment, and signature idea. The user chooses one. This prevents “three shades of the same template.”
+Before writing tokens or components, the skill proposes three directions that differ in **strategy**: what the user sees and does first, how the page persuades or how the app is navigated, how dense it is, and how it handles proof or state. For a site that might be proof-first, product-demo-first, and problem-first; for an app, overview-first, exceptions-first, and task-first. Visual language follows from the chosen strategy. The user chooses one. This prevents “three shades of the same template.”
 
 ### 3. A Design Storybook
 
@@ -139,7 +134,7 @@ The selected direction becomes a written, buildable system:
 ```text
 design/
 ├── 00-brief.md
-├── 01-art-direction.md
+├── 01-direction.md
 ├── 02-information-architecture.md
 ├── 03-design-tokens.md
 ├── 04-typography-and-color.md
@@ -173,14 +168,14 @@ The audit returns a prioritized fix list for accessibility, performance, and res
 
 | Command | Use it when… | Main result |
 |---|---|---|
-| `/ux-discover` | Starting a new site, app, or full redesign | Audience brief and explicit assumptions |
-| `/ux-direction` | The brief is ready and a visual direction must be chosen | Three distinct directions and one recorded choice |
-| `/ux-spec [scope]` | Creating the full system or a focused part of it | Tokens, type, color, IA, components, or pages |
+| `/ux-discover` | Starting a new site, app, or full redesign | Context profile, surface labels, users, tasks, assumptions |
+| `/ux-direction` | The brief is ready and a strategy must be chosen | Three strategically different directions and one recorded choice |
+| `/ux-spec [scope]` | Creating the full system or a focused part of it | Tokens, type, color, theme, IA, components, or pages — every decision traced |
 | `/ux-copy [page]` | Page or interface copy is missing or generic | Draft copy in the product’s voice |
-| `/ux-motion [mode]` | Planning or implementing motion, scroll, or justified 3D | Motion spec with fallbacks and performance limits |
+| `/ux-motion [mode]` | Planning or implementing motion, scroll, or justified 3D | Motion spec by job, with fallbacks and performance limits |
 | `/ux-build [target]` | Implementing the approved Design Storybook | Token-first build plus fidelity verification |
-| `/ux-audit [scope]` | Checking accessibility, performance, or responsiveness | One prioritized, evidence-based fix list |
-| `/ux-critique [target]` | An existing interface feels weak, cheap, or machine-made | Specific diagnosis and corrective direction |
+| `/ux-audit [scope]` | Checking accessibility, performance, or responsiveness | One prioritized, evidence-based fix list against WCAG 2.2 AA |
+| `/ux-critique [target]` | An existing interface feels weak, generic, or machine-made | Slop Detector 2.0, Specificity Score, and a prioritized fix list |
 
 <details>
 <summary><strong>Command modes and focused scopes</strong></summary>
@@ -188,7 +183,7 @@ The audit returns a prioritized fix list for accessibility, performance, and res
 - `/ux-spec tokens` — design tokens and token files
 - `/ux-spec type` — typography system
 - `/ux-spec color` — palette and contrast pairings
-- `/ux-spec theme` — light and dark themes
+- `/ux-spec theme` — a second theme, or a recorded decision not to ship one
 - `/ux-spec ia` — information architecture
 - `/ux-spec components` — component anatomy, variants, and states
 - `/ux-spec pages` — page blueprints and section rhythm
@@ -340,37 +335,43 @@ A behavioral smoke test is even better:
 1. Start a new agent session.
 2. Ask it to design a new product.
 3. Confirm it begins with drafted discovery options.
-4. Confirm `/ux-direction` presents three structurally different directions before `/ux-spec`.
+4. Confirm `/ux-direction` presents three strategically different directions before `/ux-spec`.
+5. Ask it for a dashboard and confirm it does not propose a hero, section rhythm, or scroll reveals.
 
 ## Design and implementation guarantees
 
 The skill treats these as gates:
 
-- every visual decision has a product, audience, trust, or accessibility reason;
+- no hue, typeface, radius, type ratio, or layout style is chosen before users, tasks, content, business goal, trust, and information architecture are written;
+- every major decision carries a trace to `[USER]`, `[TASK]`, `[CONTENT]`, `[BUSINESS]`, `[BRAND]`, `[CONTEXT]`, or `[A11Y]`;
+- marketing surfaces and product surfaces are reasoned separately, per surface;
 - example colors, fonts, radii, and durations cannot ship unchanged;
-- light and dark themes are independently designed;
-- foreground/background contrast is measured in both themes;
+- color layers (brand, semantic, state, surface, text, data) are separated and every pairing is measured in every theme;
+- a second theme exists only when warranted, and is designed rather than inverted;
 - components specify default, hover, focus-visible, active, disabled, loading, error, and empty states;
-- page blueprints contain real draft copy—not lorem ipsum or invented proof;
-- every animation has a named trigger and reduced-motion fallback;
-- testimonials, customers, logos, and statistics are never fabricated;
-- the final build is checked against the chosen art direction and signature element.
+- every section or region has a reflow decision, not just “stacks”;
+- blueprints contain real draft copy—not lorem ipsum or invented proof;
+- every animation has a job and a reduced-motion fallback;
+- WCAG 2.2 AA is gated with evidence;
+- the final build is checked for fidelity to the chosen strategy, and the interchangeability question is re-answered on the built product.
 
 ## Progressive reference loading
 
-The skill does not load its full design library into every task. It routes to focused references:
+The skill does not load its full library into every task. It routes by pipeline stage and surface type:
 
 ```text
-Any visual output      → anti-slop rules
-Layout work            → composition
-Page blueprint         → section library + matching category blueprint
-Typography/color       → typography, color, and theming
-Motion                 → motion system + relevant implementation recipe
-Build                  → implementation handoff
-Audit                  → craft and accessibility
+Any design decision     → design reasoning (pipeline, context model, principles)
+Discovery               → discovery question bank
+Marketing surface       → marketing UX (content-first structure, section anatomy)
+Product surface         → product UX (navigation, interaction model, screens, states)
+Visual language, tokens → visual system
+Any spec, any audit     → responsive behavior and accessibility (WCAG 2.2 AA)
+Motion                  → motion by job + relevant implementation recipe
+Build                   → implementation handoff
+Direction, gate, critique → validation (Slop Detector 2.0, Specificity Score)
 ```
 
-This keeps the active context relevant and reduces fallback to generic model defaults.
+A dashboard never loads the marketing file. A landing page never loads the product file. Nothing loads a style catalogue unless it reaches the optional-techniques appendix by a stated reason.
 
 ## Customize the skill
 
@@ -393,10 +394,12 @@ Useful customization points:
 
 | File | What to change |
 |---|---|
-| `SKILL.md` | Workflow rules, defaults, and quality gates |
-| `references/00-anti-slop.md` | Visual defaults to reject or allow |
-| `references/04-visual-styles.md` | House styles and direction vocabulary |
-| `references/16-copy-voice.md` | Voice and copy constraints |
+| `SKILL.md` | Operating rules, the pipeline, gates |
+| `references/00-design-reasoning.md` | Context model, principles-as-decisions, vague-prompt table, defaults that need a reason |
+| `references/02-marketing-ux.md` | Category notes and section anatomy for marketing surfaces |
+| `references/03-product-ux.md` | Navigation models, interaction model, screen anatomy, category notes for apps |
+| `references/04-visual-system.md` | Type, color, composition rules; the optional-techniques appendix |
+| `references/10-copy-voice.md` | Voice and copy constraints |
 | `assets/tokens.template.css` | Token structure for generated systems |
 
 ## Repository structure
@@ -410,14 +413,16 @@ src/
 ├── assets/
 ├── commands/              # 8 workflow commands
 ├── docs/
-└── references/
-    └── blueprints/        # category-specific page inventories
-test/cli.test.js
+└── references/            # 14 files, loaded by pipeline stage and surface type
+test/
+├── cli.test.js            # installer integrity
+└── skill-structure.test.js # link integrity, pipeline presence, prescriptive-rule lint
 ```
 
 - [File manifest](src/docs/FILE-MANIFEST.md) — purpose and load rule for every bundled file
 - [Workflow guide](src/docs/WORKFLOW.md) — expected end-to-end behavior
-- [Anti-slop rationale](src/docs/ANTI-SLOP-RATIONALE.md) — why the divergence and quality defenses exist
+- [Design rationale](src/docs/DESIGN-RATIONALE.md) — why each guard exists and what it replaced
+- [Sameness test](src/docs/SAMENESS-TEST.md) — the twelve-brief cross-project test
 - [Publishing guide](PUBLISHING.md) — release process for maintainers
 
 ## Development

package/bin/cli.js

@@ -230,7 +230,7 @@ function ask(q) {
 function banner() {
   log();
   log(`  ${c.b("UI/UX Storybook Architect")} ${c.dim("v" + VERSION)}`);
-  log(`  ${c.dim("Distinctive UI/UX direction + 8 workflow commands for every agentic IDE")}`);
+  log(`  ${c.dim("Context-driven UI/UX direction + 8 workflow commands for every agentic IDE")}`);
   log();
 }
 
@@ -324,7 +324,7 @@ async function cmdInit(args) {
   log();
   log(`    ${c.cy("/ux-discover")} a landing page for a fintech app aimed at 55+ users`);
   log();
-  log(`  ${c.dim("It must ask you 8 numbered questions before designing anything.")}`);
+  log(`  ${c.dim("It must ask you numbered questions with drafted options before designing anything.")}`);
   log(`  ${c.dim("If it starts designing immediately, the skill did not load — run:")} ${c.cy("npx " + NAME + " doctor")}`);
   log();
   log(`  ${c.b("Verify per IDE")}`);
@@ -438,7 +438,7 @@ function cmdEject(args) {
   log(`  Edit it, then install your version from that folder:`);
   log(`    ${c.cy(`npx ${NAME} init --src ${path.relative(process.cwd(), dest) || "."}`)}`);
   log();
-  log(`  ${c.dim("Best first edits: SKILL.md defaults table, references/04-visual-styles.md (your house style), assets/tokens.template.css")}`);
+  log(`  ${c.dim("Best first edits: references/00-design-reasoning.md (pipeline, context model), references/02-marketing-ux.md and 03-product-ux.md (category notes), assets/tokens.template.css")}`);
   log();
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uiux-storybook-architect",
-  "version": "2.0.2",
+  "version": "3.0.0",
   "description": "Interview-driven UI/UX design skill with 8 workflow commands for Claude Code, Codex, Antigravity, Cursor, Windsurf and VS Code Copilot. Turns vague briefs into distinctive, buildable Design Storybooks with art direction, tokens, copy, motion and accessibility.",
   "type": "module",
   "bin": {

package/src/AGENTS.md

@@ -3,36 +3,45 @@
 **Path:** `src/AGENTS.md`
 
 Any request to design, redesign, critique, or build a website, app, landing page, dashboard,
-color palette, type system, dark mode, or animation is UI/UX work. For all of it:
+color palette, type system, theme, or animation is UI/UX work. For all of it:
 
 1. Read `.agents/skills/uiux-storybook-architect/SKILL.md` before doing anything else.
-2. **Read `references/00-anti-slop.md` before producing any visual output.** Unconstrained, an
-   agent reproduces the training-data average: centered hero, indigo accent, Inter, three icon
-   cards, uniform padding, "transform your workflow". That file contains the ban list and the
-   self-check every visual deliverable is measured against.
-3. **Interview only when starting new work.** New site, app, or full redesign with no
-   `design/00-brief.md` → run the discovery interview: one batch of 8 numbered questions, then a
-   second batch on build constraints. **Every question carries 3–4 drafted options with a
-   recommendation and a one-line consequence**, so the user replies `1b, 2 rec, 3 skip`. Never
-   send a bare open question. If the brief exists, read it and never ask again. For a small change
-   to an existing codebase, or a single decision, do not interview: infer, state the assumption in
-   one line specific to this product, and proceed.
-4. **Never go from brief straight to spec.** `/ux-direction` is mandatory on new design work: three
-   structurally distinct directions, presented, and a human picks one. One brief with no fork
-   collapses to the one obvious execution, and the obvious execution is the average.
-5. **Never ship a template default.** Every hex, font, radius, and duration in the skill's
-   references and asset templates is illustrative. The token templates use loud magenta/lime
-   tripwire values on purpose — if they render, the tokens were never chosen.
-6. Write the Design Storybook to `design/` before building a new site. Build order is tokens →
-   primitives → layout → sections → pages → motion → 3D, never page by page.
-7. Use only tokens from `design/tokens/tokens.css`. No raw hex, no off-scale spacing, no
-   hardcoded durations anywhere in component code.
-8. Every animation must exist in `design/07-motion-spec.md` with a `prefers-reduced-motion`
-   fallback before it is implemented.
-9. WCAG 2.2 AA is a gate, not a suggestion: 4.5:1 body contrast in both themes, visible focus
-   states, ≥44px touch targets, keyboard operability.
-10. **Never invent evidence.** No fabricated testimonials, customer names, logos, or statistics,
-    even as placeholder content. Use a clearly marked empty slot.
+2. **Read `references/00-design-reasoning.md` before any design decision.** Generic output is
+   caused by unreasoned repetition, not by familiar patterns. The test is interchangeability:
+   could this be reused for an unrelated company by changing only logo, headline, accent, and
+   images? Neither the old defaults (indigo, Inter, centered hero, three cards) nor the new ones
+   (editorial asymmetry, warm paper, one burnt accent, oversized type, bento) are banned. Both
+   need a reason traceable to the brief.
+3. **Reason before styling.** No hue, typeface, radius, type ratio, surface, or layout style is
+   chosen before context, users, jobs, tasks, content, business goal, trust, and information
+   architecture are written. The pipeline order is in `SKILL.md`.
+4. **Fork by surface.** Marketing surfaces reason about persuasion, proof, trust, and conversion
+   (`references/02-marketing-ux.md`). Product surfaces reason about workflows, navigation, data,
+   states, forms, keyboard, and permissions (`references/03-product-ux.md`). Never apply
+   landing-page logic to a dashboard, or app density to a story. Decide per surface.
+5. **Interview only when starting new work.** No `design/00-brief.md` on a new site, app, or
+   full redesign → run discovery: up to 8 numbered questions, each with 3–4 drafted options,
+   a recommendation, and a one-line consequence, so the user replies `1b, 2 rec, 3 skip`. Then a
+   second round by surface type. If the brief exists, read it and never ask again. For a small
+   change or a single decision, infer, state the assumption in one line specific to this product,
+   and proceed.
+6. **Three strategic directions before any spec.** `/ux-direction` is mandatory on new design
+   work. Directions differ in information priority, strategy, hierarchy, interaction, and density;
+   visual differences follow. A human picks.
+7. **Every decision traces** to `[USER]` `[TASK]` `[CONTENT]` `[BUSINESS]` `[BRAND]` `[CONTEXT]`
+   or `[A11Y]` with one line. "Looks clean" is not a trace.
+8. **Never ship a template default.** Every value in the references and asset templates is
+   illustrative. The token templates carry magenta and lime tripwires on purpose.
+9. Write the Design Storybook to `design/` before building. Build order: tokens → primitives →
+   layout → sections or screens → pages → motion → 3D. Use only tokens from
+   `design/tokens/tokens.css`; no raw hex, off-scale spacing, or hardcoded durations in components.
+10. **Motion has a job** (feedback, causality, orientation, continuity, state, storytelling) and
+    exists in `design/07-motion-spec.md` with a `prefers-reduced-motion` fallback before it is built.
+11. **WCAG 2.2 AA** is designed in at every stage and gated with evidence at the end: contrast in
+    every theme, keyboard operability, visible and unobscured focus, ≥24px targets (≥44px touch),
+    reduced motion, no redundant entry, accessible authentication.
+12. **Never invent evidence.** No fabricated testimonials, customer names, logos, or statistics,
+    even as placeholders. Use a clearly marked empty slot.
 
 Eight slash commands, in workflow order: