Web Stylebook Design

---
name: web-stylebook-design
description: Use BEFORE building, auditing, improving, or redesigning any frontend UI (a page, screen, component, dashboard, form, checkout, chat, or developer console). Confirms audit coverage and change depth, then calls the Web Stylebook MCP to evaluate visual design, user-facing copy and information structure, behavior, accessibility, UI states, and product-fit direction as requested. Trigger whenever the user asks to build/design/redesign/audit/review/critique/improve a UI or its copy, "make a page/screen/app", "style this", or wants a design direction, even if they don't say "Web Stylebook".
---

# Web Stylebook — design before you build

You have the **Web Stylebook MCP** server (`web-stylebook`) connected. It returns design
*contracts* (scored directions, visual-design plans, UX-principle plans, UI-state plans, tokens),
not code. You still write the code.
Calling it before writing UI produces far better, less generic results.

## When to fire

Before writing JSX/HTML/CSS for any new or redesigned UI surface. If you catch yourself about
to scaffold a page from memory, stop and run step 1 first.

## Scope gate for audits and redesigns

When the user asks to audit, review, critique, or improve an existing UI and has not already defined
the scope, ask these **two short questions before inspecting or changing it**, then stop until they
answer:

1. **Audit coverage** — visual only; visual + user-facing copy and information structure; or full
   experience including interaction, accessibility, UI states, and build/performance evidence?
2. **Change depth** — findings only; prioritized change and rewrite proposals; or implement the
   approved fixes and verify them?

Do not ask again when the request already answers both dimensions (for example, “copy only, report
only” or “review everything and fix it”). If the user says to use your judgment, state the selected
scope and proceed. Commit, push, release, and deployment remain separate authorizations even when
implementation is selected. For a new build, fold these decisions into workflow step 4 instead of
asking a duplicate gate.

Map the answer to `get_design_audit_plan.includeGroups`:

- **Visual only:** `layout`, `fidelity`, `anti-patterns`.
- **Visual + content/structure:** add `content` and `behavior` so labels, navigation, and information
  relationships are inspected with the visuals.
- **Full experience:** use every matching group, selected-principle checks, documentation, and UI-state
  coverage.

## Workflow

1. **`recommend_design_direction`** — pass the product context (productType, tone, density,
   usageFrequency, trustSensitivity, constraints, avoid). It returns **scored candidates** with
   reason codes, **rejected** styles with reasons, secondary **pairings**, assumptions, and a
   confidence. Treat `candidates` as evidence — *you* pick using product context; `candidates[0]`
   is the strongest match, not a mandate.
2. **Read the chosen styles** — `webstylebook://styles/{id}` for each pick (primary + any pairing).
   Then call **`search_design_references`** with a narrow product/category/tag query and inspect only
   a few selected entries with **`get_design_reference`**. Record their observation date,
   attribution, and rights notice. Borrow transferable structure and measured tokens; never copy or
   redistribute upstream screenshots, brand assets, copy, typefaces, or visual identity.
3. **Intake, then get direction approval — before component work.** First run a short intake so the
   previews use the right material (ask, don't assume):
   - **Assets** — do they have images/brand assets to use (and which)? If not, may you pull
     **license-free** sample imagery (e.g. Unsplash, free for commercial use) for the example, or is
     no imagery needed? *(A: provided — they say which · B: none — you source license-free samples ·
     C: not needed)*
   - **Emphasis** — anything they specifically want emphasized, or any must-have / non-negotiable?
   Then, for open-ended UI requests, compose and show 2-3 distinct candidate directions or page
   previews, each with a concise critique and a clear recommendation, and ask which feeling/direction
   is right. The candidates must differ in **opening structure** (different dominant element +
   first-read element — see *The opening* below), not merely color/type tone; present **at most one**
   two-column-derived option, and make at least one carry no running-text column. **Stop here** until
   the user picks a direction or explicitly tells you to proceed. Do not build the final component
   system, reusable components, or production page before this approval gate.
4. **Confirm scope & resolve open details — before building.** Once a direction is approved, do
   **not** start implementing. First surface the decisions that change *what* you build, as a short,
   concrete checklist — ask, don't assume:
   - **Scope & deliverable** — the full reusable component library, or a single page/screen? One
     surface or several? A throwaway preview, or production code committed to the repo?
   - **Stack & integration** — framework (React / Vue / Svelte / plain), styling (CSS variables /
     Tailwind / CSS-in-JS), TypeScript, and any existing design system or components to reuse/extend.
   - **Real content & data** — brand/product name, real copy or placeholder, actual data shape and
     entities, must-have features, and explicitly what to leave out. (This is where you get the real
     numbers or omit them — never invent metrics to fill space.)
   - **Audience & environment** — primary devices/breakpoints, light/dark/both, locales, accessibility
     level, any performance budget.
   Turn the working assumptions into **confirmed facts** here. Build only after the user answers —
   or explicitly says "use your judgment," in which case record the assumption and proceed. Keep it to
   3–6 high-leverage questions; don't interrogate.
5. **Plan each screen around *the one thing*** — drop the word "hero"; it summons the SaaS template.
   Name the single most important thing the user is there for, build the screen around it, and make
   everything else earn its place or cut it. Run the furniture-check (see *The opening* below)
   on **each** screen, not just the first. Do **not** default to Hero + Features + Testimonial + CTA.
   Look up component vocabulary in `webstylebook://components`, then name the intended outcomes,
   matching surface, and current design phase for the next step.
6. **`get_design_principle_plan`** — pass the current layout concerns, matching surface, and design
   phase (or a small explicit id set). Use the returned placement guidance, application steps,
   verification checks, and cautions. Read `webstylebook://design-principles/{id}` only for selected
   entries. These are independently authored, testable craft prompts—not empirical laws or a fixed
   recipe. Accessibility and truthful behavior override visual polish.
7. **`get_ux_principle_plan`** — pass the intended outcomes, matching surface, and current design
   phase (or a small explicit id set). Use the returned design questions, apply steps, verification
   checks, cautions, and evidence confidence. Read `webstylebook://principles/{id}` only for the
   selected entries. These are contextual decision prompts, not universal laws or a substitute for
   user research; accessibility, safety, informed consent, and truthful feedback override them.
8. **`get_ui_state_plan`** — for each surface (data-table, form, checkout, chat, developer-console).
   Implement the required + recommended states, honoring `mustNot` (e.g. no silent auto-retry, don't
   lose user input, don't imply a charge that didn't happen).
9. **`compose_design_tokens`** — emit a starting token set (css-variables / tailwind / typescript).
   Heed the contrast warnings; don't ship 8–12% ghost borders.
10. **Write `design.md`** — a brief with: intent, audience/tasks, chosen direction + why, rejected
   directions, tone, color *roles* (not a raw palette), type roles, spacing/density, layout rules,
   surface hierarchy, component behavior, motion (use AND avoid), selected visual-design principles
   + placement checks, selected UX principles + cautions, returned UI-state coverage, responsive,
   accessibility, anti-patterns, confirmed
   decisions (from step 4), and verification checklist. Never leave a section empty.
11. **Implement, then call `get_design_audit_plan`** with `styleId`, `surfaces`,
   `designPrincipleIds`, `uxPrincipleIds`, matching `stateSurfaceIds`, and `locale`. This returns a localized,
   surface-aware checklist with stable ids, severity, applicability, and required evidence without
   loading the full three-language policy resources. Inspect the actual rendered UI, source,
   interactions, console, and commands for every returned check. Use `PASS` / `FIX_NOW` / `RISK` /
   `NOT_APPLICABLE` / `NOT_VERIFIED`; every `PASS` needs observed evidence, and missing evidence is
   `NOT_VERIFIED`, never an inferred pass. Include the opening's **furniture-check** when applicable:
   if the visual is generic
   furniture (a stock photo, an abstract shape, or a card you could paste onto another product)
   rather than a bespoke product demonstration, or the copy column is the full quartet, recompose.
   Do not skip the checklist's **`principles` group**: run each principle's recorded verification
   check against the built UI and write down the outcome (pass / fail / n-a + why). A principle name
   in `design.md` with no placement decision and no observed check is the `principle-as-decoration`
   anti-pattern — verify it or drop it. Keep `contextual` / `contested` labels intact; never let a
   principle override accessibility, safety, informed consent, or truthful feedback.
   When the confirmed scope includes content, do not skip the checklist's **`content` group**. Inspect
   the actual visible strings and their hierarchy, not just component names or localization keys.
   The absence of internal jargon is not a pass: ask what each material statement actually says,
   what supports it, whether it is specific to this context, and whether its certainty and prominence
   match that support and its usefulness.
12. **Validate the audit result contract** — call `validate_design_audit_result` with the exact plan
   query, `expectedPlanHash` from `get_design_audit_plan.identity.planHash`, and an explicit target for
   every inspected route/screen/state/viewport/theme/locale. Evidence needs a durable artifact
   reference, content hash, or exact route/selector/file/region; interaction evidence also identifies
   its before/input/after/recovery phase. Submit one result for every planned check/target. Resolve
   contract errors or preserve the validator's normalized `NOT_VERIFIED`; `valid: true` means the
   result contract is complete and internally consistent, not that the design passed.
   *This inline pass is your job on every build.* The server also ships three deeper audits as MCP
   **prompts** — `audit-design-direction`, `audit-design-principles`, `audit-ux-principles`. Those
   are slash commands the **user** invokes, not tools you can call, so don't wait on them: do the
   inline audit yourself, and mention the prompts when a review deeper than your own is warranted.

## Active design — compose, don't recolor

`compose_design_tokens` returns color/radius/type/spacing **scalars**. Tokens are not a design.
Swapping a token block over one fixed layout is a *reskin* — it reads as "one screen recolored"
and is **not acceptable** as a design direction. A real direction has its **own composition**:
layout, hierarchy, density, component choice, motion — built from the style's facets + component
vocabulary, not just its tokens.

- **The chosen direction is a starting tone, not a mold.** Don't pour the content into the style's
  "typical" layout — that produces a generic "page in style X." Start from what THIS brief and THIS
  content actually need: decide the sections and components from the product, then apply the style as
  *tone*, **adapting freely** — override its fonts, grid, density, and structure where the brief calls
  for it (the token `notes` literally invite this, e.g. a "mono" style that ships serif defaults). The
  result should read as "built for this product," not "applied a catalog style." When one style is too
  rigid, pair a secondary (`compare_design_directions`) or treat the style as inspiration.
- **Offer a candidate set, not one screen.** For an open-ended design request, take the top
  context-fit candidates and **fully compose each as a distinct page** (different layouts, not the
  same layout recolored). Present them with an honest per-candidate critique + a recommendation, and
  let the user choose. This is an approval gate: after presenting candidates, ask whether the feeling
  is right and wait. A single one-shot output is the weaker default.
- **Apply active judgment over the score.** Drop a high-scored candidate when the context defeats it
  — e.g. low-contrast styles (neumorphism) for elderly / medical / high-trust — even if it ranks #1.
  The score is evidence; product context decides. The MCP's own guidance says so.
- **Lead with the landing surface.** When the user just says "design X", start from the landing/opening
  surface, not an internal dashboard.
- **Land on reusable components.** The deliverable is a component library: tokens as the shared
  foundation (swap to re-skin everything), and components whose states are exactly the
  `get_ui_state_plan` contracts. Not a one-off HTML file.

## The opening — the one thing, not a hero

The word "hero" summons the SaaS template, and "reach for the default" shows worst in the first
screen. But the disease was never *two columns* — strong products (Linear, Stripe) put copy beside a
visual. The disease is **generic furniture**: a copy stack (eyebrow + headline + sub + buttons +
stats) next to a *decorative* panel — a stock photo, an abstract blob / gradient / 3D shape, generic
app chrome, or a card you could paste onto a different product by swapping the logo. Replace the
reflex with a method plus a gate that targets genericness, not column count.

1. **Derive the centerpiece** (in `design.md`): *what is the single most important object, action,
   or feeling here?* The page is built **around** that, not beside it. The opening must be
   impossible to paste verbatim onto a different product — if it could be, it's generic; redo.
2. **Enumerate three structurally-different openings, in writing, before you commit.** For each,
   name the **organizing device**, **what owns >50% of the frame**, and **where the eye lands
   first**. Two openings are the *same structure* if their dominant element and first-landing
   element are the same type — "a copy block + a side card" is **one** structure no matter what you
   relabel the card; redo until genuinely distinct. **At least one must carry no running-text
   column at all.** Starter menu (starting points, not molds — invent your own):
   - **product-as-protagonist** — the object/tool *is* the frame (full-bleed, or centered-and-
     dominant with copy orbiting it small), never a card beside a copy column.
   - **type-wall** — typography fills the opening; no visual panel; the words are the design.
   - **inline-first-action** — the opening *is* a working interface spanning the frame; the user
     does the core action immediately. (Not a control parked in a side panel next to a pitch.)
   - **ambient / broken-grid** — off-axis, asymmetric; mood through space + one focal element.
   - **full-bleed single element** — one number / word / image fills the frame; all else tucked small.
   - **horizon / architectural** — a structural line or grid organizes above/below, not copy-vs-visual.
3. **Furniture-check: does the visual earn its half?** (mandatory; gate at step 11). A two-column
   "copy + visual" opening is fine — *only* when the visual earns it. It **FAILS** if the other side
   is **generic furniture**: a stock photo, an abstract blob / gradient / 3D shape, generic app
   chrome, or a card / panel you could paste onto a *different* product by swapping the logo. It
   **passes** only if that side is a **bespoke demonstration of THIS product's core mechanic** — its
   actual input→output with realistic domain content, such that swapping the product would make the
   visual nonsensical. A decorative bridge (a "seam", a connecting thread, an overlapping chip) does
   **not** rescue a generic visual — judge the bulk, not the garnish. Still forbidden outright are the
   all-text defaults everyone reads as AI: the **centered stack** (eyebrow + headline + sub + two
   buttons, centered) and the **giant-centered-word** hero. If it fails, ship one of the
   structurally-different alternatives you enumerated.

**Prose cap.** Unless type *is* the centerpiece (type-wall), the opening carries **at most a headline
plus one short line**; the eyebrow + headline + sub-paragraph + two-buttons (+ stats) quartet must
not appear together in the opening, in any axis or order. More copy earns its place in a later
section, not the first screen.

**Kill the AI headline cadence.** The reflexive AI headline is an *evocative, abstract noun-phrase
fragment* — often two beats split by a comma, mood over substance — with **one word italicized in the
accent color**. The same cadence and the same emphasis move on every product **is the tell** — it
reads as designed-by-AI, not written for this product. Don't default to it:
- **Say something only THIS product could say.** Paste-test the headline: if swapping one noun lets
  it sit on a competitor, it's generic — rewrite until it's specific (a real claim, fact, or offer).
- **Vary the form every time** — full sentence vs. fragment, plain vs. blunt, long vs. terse — and
  **don't reflexively italicize one accent word**; choose the emphasis (or none) to fit, and don't
  repeat the same type move you used last project. There is no house voice to reach for — reach for
  what this product actually is.

This generalizes: **every** screen (dashboard, form, checkout) has a stock shape it defaults to. Run
the same furniture-check per screen — is each block doing product-specific work, or is it template
filler? — so the default can't just migrate below the fold.

## Editorial discipline — earn trust, don't fake it

The fastest "AI smell" is filler content dressed as substance. Hold the line:

- **No invented metrics.** Don't fabricate impressive-sounding numbers ("99.2% on-time rate",
  "1.4-min average booking"). If it didn't come from the user/product, don't print it.
- **No compliance/IT jargon as trust signals.** "TLS·AES-256", "ISO 27001", cipher specs — the
  end user doesn't care. Choose trust signals by what THIS audience actually weighs. For a hospital
  patient: doctors by name/specialty/experience, departments, location·transit·parking, hours
  (incl. nights/weekends), insurance, wait time, reviews, emergency capability. Compliance, if shown
  at all, goes small in the footer — not a hero trust band.
- **Back every claim with content.** "214 specialists" requires a way to browse them (or a few
  representatives + "see all →"). A headline number with three cards reads as a lie.
- **No formulaic opening.** Compose the first screen via *the one thing* + the furniture-check
  (above). Two columns are fine when the visual is a **bespoke product demonstration**; they fail when
  it's **generic furniture** (stock photo / abstract blob / a card you could paste onto another
  product) — and a decorative seam bridging the columns doesn't launder a generic visual. Avoid the
  all-text centered-stack and giant-word defaults too. Cap opening prose at a headline + one short
  line + one action.
- **Intentional typography.** Generic system-sans (especially for Korean/CJK) reads as default —
  pick a real display face.

## User-facing copy — meaning before machinery

Apply this section when the confirmed scope includes user-facing copy or the full experience:

- **Use the audience's language.** Translate, define, or demote internal taxonomies, workflow labels,
  implementation terms, unexplained abbreviations, and method names unless understanding them is the
  user's actual task. Expert terminology is fine for an expert audience when it helps them act.
- **Lead with meaning.** Prominent headings and summaries state the conclusion, consequence, or next
  action first. Methodology, provenance, and internal reasoning follow as supporting evidence or
  optional detail; they do not become the headline merely because the system worked hard to produce
  them.
- **Reject pseudo-precision.** Counts, scores, agreement labels, confidence badges, and status
  language need a clear method, denominator, uncertainty, and decision value. Otherwise remove the
  number or rewrite it as a qualified statement; never use it to perform certainty or authority.
- **Make every block earn attention.** Review prominent cards, statistics, navigation links,
  sections, and disclosures against the primary user task. Keep them when useful. Remove, merge, or
  demote them only when the observed context shows they are irrelevant — no content type is banned by
  default.
- **Match claims to support.** For every material claim, conclusion, or recommendation, identify what
  in the available content, evidence, or context supports it. Calibrate wording and certainty to that
  support, and make decision-relevant sources or limits visible. Qualify or remove anything that
  cannot be supported; never invent evidence, facts, or next steps to make copy sound useful.
- **Reject abstract consultancy filler.** A string can fail even when it contains no internal jargon.
  Ask what concrete information it adds here and whether the unchanged sentence would remain equally
  plausible on an unrelated product or page. Rewrite it around the information this audience needs
  to understand, decide, or act. If it cannot become specific without inventing facts, remove it.
- **Match emphasis to substance.** Match typographic and structural emphasis to information value,
  task relevance, and support. Do not turn vague, generic, redundant, or weakly supported content into
  an oversized headline, isolated card, badge, or statistic. Replace it with content that earns the
  attention, or demote it and reduce its scale.
- **Rewrite without inventing.** Preserve factual meaning, material caveats, and domain nuance. For
  findings/proposal scope, show the smallest useful before → after rewrite and why. For implementation
  scope, edit the real strings, re-check wrapping and hierarchy at target locales/viewports, and
  collect fresh evidence.

## `compare_design_directions`

When the user is torn between looks, pass 2–4 directions. It returns each one's favorable
conditions and likely failure mode — there is deliberately no single winner; choose by product fit.
Each direction may carry an optional `secondaryStyleId` to model a primary+secondary pairing; the
comparison reflects the merged pairing in its axes (e.g. a louder secondary raises distinctiveness).

## `get_design_principle_plan`

Select by what must be visually resolved (`concerns`), where (`surface`), and when in the design
process (`phase`). Keep the set small. For each selected principle, answer its design question,
place the elements as directed, apply only the relevant craft move, and keep its observable
verification check in `design.md`. Use this catalog for composition and visual review; use
`get_ux_principle_plan` separately for behavioral and cognitive evidence.

## `get_ux_principle_plan`

Select by what the user must accomplish (`outcomes`), where (`surface`), and when in the design
process (`phase`). Keep the returned set small. Apply the checks, not the label: for each selected
principle, answer its design question, implement only the relevant steps, and define how its
verification will be observed. Preserve `contextual` and `contested` confidence labels in audits;
do not turn a mnemonic or systems maxim into a scientific claim.

## Rules

- **Never present a token-swap recolor as a design direction** — compose each direction's own layout.
- **Direction = starting tone, not a mold** — compose the components THIS brief needs and adapt the
  style (fonts, grid, structure) to fit; never ship a generic "page in style X."
- **The opening's visual is a product demonstration, not furniture** — a stock photo, abstract blob,
  or a card you could paste onto another product fails (a decorative seam bridging it doesn't change
  that); two columns are fine when the visual earns its half. Keep the copy column off the full
  eyebrow + headline + sub + buttons quartet. Enumerate three structurally-distinct openings and
  derive the pick from the product's *one thing*.
- **No AI headline cadence** — don't default to the evocative noun-phrase fragment with one
  italic-accent word (same move on every product = the tell). The headline must pass the paste-test
  (couldn't sit on a competitor by swapping a noun), and its form + emphasis must vary per project,
  not repeat last time's move.
- **Default to a multi-candidate set + an honest recommendation**, not one screen; the user picks.
  Stop before final component/system implementation until the user approves a direction.
- **After the direction is picked, confirm scope + open details before building** — don't silently
  assume the deliverable, stack, real content/data, or what to leave out; ask a short checklist first.
- **Component states are owned by the component.** Interaction states (hover/focus/active/disabled)
  live on the primitive's own classes — never let an ancestor/context selector (`nav a:hover`,
  `.card a`) bleed in and override them. Scope context rules with `:not(.btn)` etc. A primitive must
  look and behave the same wherever it's placed.
- The MCP is the single source of design knowledge — **don't** paraphrase or cache its catalog here.
  Always read the live resources.
- Everything it returns is deterministic and model-free: same input → same output.
- It never sees your repo. Give it a short product summary as input; it gives you a contract back.