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.

Redesigning an existing page: before changing it, save the original's rendered HTML (document.documentElement.outerHTML) and its CSS, and note the selectors its scripts query. After the redesign is built, call compare_page_revisions with both versions, those scriptSelectors, and the product's productType. Restore every lost link, field, handler, hook, heading, figure, landmark, and must-have, or put an intended removal in acknowledged with a reason of at least 12 characters, and rerun it until nothing is left unexplained. Record it with a separate get_design_audit_plan query of revisionPreservation: true (same productType) and submit its evidence and results to validate_design_audit_result.

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. When the project should carry a standard file that other agents and tools read, call it again with format: "design-md" and the same productType in designMd, and save content as DESIGN.md (the server never writes files). Tell the user what lossy lists, such as a second color mode.
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. 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.
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 from its structure (archetype + signature moves), and clear audit_page_structure findings before calling the page done.
• A redesign keeps what worked — keep the original HTML and CSS before redesigning and clear compare_page_revisions findings (restore, or acknowledge with a reason) before calling it done.
• Style never removes a must-have — the product type's mustHaves (price and options on a product page, status on a dashboard, search in docs) stay in their zone in every direction; restyle them, don't drop them for a cleaner opening.
• 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.