web-stylebook-design

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, structure.
• 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. ranking says why #1 beat #2, or reports a tie; list the most important tone first. Each candidate also carries structure: a layout archetype (hero composition, grid, section order, density, type-scale use), 2-3 signature moves with their purpose (the style resource in step 2 has their build steps), and the generic and style-specific patterns the page audit will flag. Build the page from it. The top-level mustHaves lists the elements the product type requires and the zone each must sit in (a commerce product page needs price, variant choice, add to cart, and delivery/guarantee details on the first screen; a dashboard needs the current status and what changed; docs need search and a quickstart). The style restyles them but never removes them, and they come before the archetype's opening limits: a first-screen item goes in the hero. structure.mustHaves names the candidate's moves that can present each one.
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. Its structure field points back to the chosen style's archetype and moves: the tokens set the surface, the structure sets the page.
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.

1. 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. Run audit_page_structure on each built page's rendered HTML and CSS with the chosen styleId and the same productType you passed to recommend_design_direction. Replace every finding with the signature move or archetype step it names, add every must-have listed in mustHaves.missing, move every one in mustHaves.misplaced onto the first screen, rebuild, and rerun it; then include structure in includeGroups (with the same productType) and submit its evidence and results with the rest of the audit. 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.
2. 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.