web-stylebook-design — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited web-stylebook-design (Agent Skill) and scored it 96/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 1 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 1 flagged
The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
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.
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.
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:
experience including interaction, accessibility, UI states, and build/performance evidence?
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:
layout, fidelity, anti-patterns, structure.content and behavior so labels, navigation, and informationrelationships are inspected with the visuals.
coverage.
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.
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.
previews use the right material (ask, don't assume):
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)
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.
not start implementing. First surface the decisions that change what you build, as a short, concrete checklist — ask, don't assume:
surface or several? A throwaway preview, or production code committed to the repo?
Tailwind / CSS-in-JS), TypeScript, and any existing design system or components to reuse/extend.
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.)
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.
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.
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.
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.
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).
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.
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.
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.
validate_design_audit_result with the exact planquery, 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.
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.
"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.
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.
— 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.
surface, not an internal dashboard.
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 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.
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.
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):
dominant with copy orbiting it small), never a card beside a copy column.
does the core action immediately. (Not a control parked in a side panel next to a pitch.)
"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:
it sit on a competitor, it's generic — rewrite until it's specific (a real claim, fact, or offer).
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.
The fastest "AI smell" is filler content dressed as substance. Hold the line:
"1.4-min average booking"). If it didn't come from the user/product, don't print it.
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.
representatives + "see all →"). A headline number with three cards reads as a lie.
(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.
pick a real display face.
Apply this section when the confirmed scope includes user-facing copy or the full experience:
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.
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.
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.
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.
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.
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.
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.
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_directionsWhen 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_planSelect 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_planSelect 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.
from its structure (archetype + signature moves), and clear audit_page_structure findings before calling the page done.
compare_page_revisions findings (restore, or acknowledge with a reason) before calling it done.
mustHaves (price and options on a productpage, status on a dashboard, search in docs) stay in their zone in every direction; restyle them, don't drop them for a cleaner opening.
style (fonts, grid, structure) to fit; never ship a generic "page in style X."
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.
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.
Stop before final component/system implementation until the user approves a direction.
assume the deliverable, stack, real content/data, or what to leave out; ask a short checklist first.
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.
Always read the live resources.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.