web-stylebook-mcp

Improve existing UI with design judgment, real changes, and before/after evidence. The host agent applies researched design knowledge, edits the actual interface, verifies affected behavior, and reports the result.

English · 한국어

web-stylebook-mcp connects design knowledge to an execution and reporting workflow. For an existing interface, the agent preserves the original, chooses a context-appropriate remedy, changes the real source, verifies the result and shows the before/after difference. The server supplies researched foundations and checks the submitted evidence contract; the host agent performs the edits and observations. New builds can also use the visual directions, UX principles, UI states and tokens from the curated Web Stylebook catalog.

No API key. No model call. No network. No project filesystem access. Deterministic, read-only, fully local.

Without it / with it

Related MCP server: WordPress Design System MCP Server

Improve an existing UI — the default workflow

An improvement request now means inspect → decide → implement → verify → compare/report. The host agent edits the actual UI and uses the MCP to guide its decisions and check completion. It does not stop at a critique. Explicit review-only requests still stay read-only; a new build or new visual direction uses the existing direction tools.

get_design_improvement_plan is the entry point. It supplies 24 researched foundations, 48 illustrative applications and 30 attributed sources in English, Korean and Japanese, plus a structured host workflow. Capture the original UI first, then record the actual task and target conditions in context:

// → get_design_improvement_plan
{
  "surface": "data-table",
  "concerns": [
    "scanability",
    "hierarchy",
    "consistency"
  ],
  "limit": 6,
  "locale": "en",
  "context": {
    "userTask": "Find the incident that needs attention first.",
    "targets": [
      {
        "id": "incidents-desktop",
        "surface": "data-table",
        "route": "/incidents",
        "conditions": {
          "viewport": {
            "width": 1280,
            "height": 900
          },
          "theme": "light",
          "locale": "en-US",
          "state": "populated",
          "dataKey": "incident-fixture-v1@fixed-clock",
          "scrollAnchor": "first-row",
          "zoom": 1,
          "deviceScaleFactor": 1
        }
      }
    ]
  }
}

Each foundation connects observations, conditional remedies, counterexamples, preservation and observable checks. Apply the relevant rules and edit real source. Preserve product identity and working behavior; a new style is optional. The default is 6 entries, maximum 12, with omitted matches listed in coverage.omittedIds. Use category or explicit foundationIds to narrow retrieval. Filters combine with AND, concerns within a filter with OR. Browse webstylebook://foundations.

After implementation, call validate_design_improvement_result with the returned query, expectedPlanHash: workflow.planHash, and actual captures, changed files/diffs, observed checks, target outcomes and limitations. It returns:

• complete: submitted implementation and comparison evidence covers every planned target.

• needs-work: follow nextActions; missing before images, mismatched data/fonts/viewports, proposals without edits, skipped targets, unsupported passes and regressions cannot complete.

• no-change: fully verified unchanged UI with no implemented/proposed changes; never present it as an improvement.

• reportMarkdown: paired before/after links, changes and reasons, verification, tradeoffs and remaining unverified work. The host can present the real screenshots in a side-by-side/toggle viewer.

Each target needs visual, behavior, preservation and affected-accessibility checks. Static markup preservation alone is insufficient. The MCP validates supplied coverage and consistency, not artifact contents or design quality. The host performs edits, captures and observations; no claimed user-study results or numerical usability gains are invented. A query without context remains valid for knowledge discovery but cannot complete an improvement. Commit/push/release/deployment need separate authorization.

See the result contract and cross-UI example and research record. The machine-readable workflow is webstylebook://workflows/improve-ui, also advertised by manifest.improvementWorkflow.

Watch it decide

"High-density monitoring dashboard for SREs, watched all day on call. Calm, technical. Avoid cyberpunk."

// → recommend_design_direction  (input)
{
  "productDescription": "High-density monitoring dashboard for SREs, watched all day on call",
  "productType": "operational-saas",
  "tone": ["calm", "technical"],
  "density": "high",
  "usageFrequency": "daily",
  "avoid": ["cyberpunk"]
}

// ← result (trimmed)
{
  "confidence": "high",
  "candidates": [
    { "styleId": "quiet-utility",  "score": 0.93 },
    { "styleId": "runtime-signal", "score": 0.89 },
    { "styleId": "notion-style",   "score": 0.83 },
    { "styleId": "console-launch", "score": 0.77 },
    { "styleId": "platform-core",  "score": 0.77 }
  ],
  "ranking": {
    "winner": "quiet-utility",
    "runnerUp": "runtime-signal",
    "gap": 0.04,
    "tied": false,
    "reasonCodes": ["USE_CASE_FIT", "LOWER_UPKEEP"],
    "explanation": "quiet-utility outranks runtime-signal by 0.04: 3 of 3 bestFor entries aim at operational-saas (runtime-signal: 2 of 3); lighter upkeep for daily use (quiet-utility: motion low, maintenance low; runtime-signal: motion low, maintenance medium)."
  },
  "rejected": [                        // 29 in total, three shown
    { "styleId": "aurora-gradient",  "reasonCodes": ["PRODUCT_NOT_IDEAL", "DAILY_USE_OVERSTIMULATION"] },
    { "styleId": "claymorphism",     "reasonCodes": ["PRODUCT_NOT_IDEAL"] },
    { "styleId": "cyberpunk-glitch", "reasonCodes": ["EXPLICITLY_AVOIDED", "DAILY_USE_OVERSTIMULATION"] }
  ],
  "pairings": [
    { "styleId": "notion-style",       "pairWith": "quiet-utility", "role": ["forms", "navigation", "repetitive surfaces"] },
    { "styleId": "macos-liquid-glass", "pairWith": "quiet-utility", "role": ["forms", "navigation", "repetitive surfaces"] }
  ],
  "guidance": "Treat candidates as scored evidence; choose using product context. candidates[0] is the strongest match, not a mandate."
}

Notice what it does: the top candidates get clearly different scores (0.93, 0.89, 0.83), and ranking says why #1 beat #2 — here every bestFor entry of quiet-utility targets operational SaaS, and its upkeep is lighter for daily use. When the top two really do score alike, ranking.tied says so instead of inventing a winner. Rejected styles come with reason codes, and pairings are suggestions rather than a mandate. The server provides evidence; the agent decides.

Then turn the chosen direction into real tokens:

// → compose_design_tokens(style: "quiet-utility", format: "css-variables", theme: "light")
// 0 WCAG contrast warnings
:root {
  --color-canvas: #ffffff;
  --color-text:   #1f2328;
  --color-accent: #526371;
  --color-border: #cecfd0;
  /* … role-based color, type, spacing, radius, motion, density */
}

One request in — and the agent chose a direction, saw what was rejected and why, and got tokens that pass WCAG, without generating a line of code.

Structure, not just tokens

Tokens only recolor a page, so every candidate also carries structure: a layout archetype (hero composition, grid rhythm, section order, density, and how the type scale is used), two or three signature moves with the job each one does, and the patterns the page must not ship. webstylebook://styles/{id} adds each move's build steps and each ban's detection criteria, and compose_design_tokens points back to it (style id, resource URI, and move ids) and prints the hero and moves in its text output. Where an archetype breaks from the style's specimen page, its basis is authored and departure says why.

After building, pass the page's HTML and CSS to audit_page_structure. This is its real output for a page an agent built from the default SaaS template (generic-saas-tailwind.html), checked against quiet-utility:

// → audit_page_structure({ html, styleId: "quiet-utility" })
// ← structure audit (trimmed)
{
  "summary": { "clean": false, "findings": 8, "major": 6, "minor": 2, "notVerified": 0, "checked": 12 },
  "findings": [
    {
      "patternId": "logo-strip",
      "name": "Logo strip",
      "severity": "major",
      "locations": ["section#customers > div.mx-auto"],
      "observed": { "logos": 5, "marquee": false, "muted": true },
      "replaceWith": {
        "instruction": "Remove it unless you have permission and a reason to name real customers; show proof a visitor can inspect instead (a real result, artifact, or named case) with this style's proof move.",
        "moves": [
          { "id": "hairline-gap-list", "name": "Gap-as-hairline state list", "purpose": "Triage: shows many resources and their current state at an even rhythm, with dividers that cannot drift out of alignment." },
          { "id": "stepped-state-badges", "name": "Three-step state badges", "purpose": "Calm status: state reads through steps of weight and fill instead of traffic-light colors, so the one urgent item stands out." }
        ]
      }
    },
    {
      "patternId": "generic-saas-skeleton",
      "observed": { "sections": "opening → proof → features → testimonials → cta", "templateSections": 5 },
      "replaceWith": {
        "archetype": {
          "sectionOrder": [
            "Top bar: breadcrumb path on the left, search and one primary action on the right",
            "The primary working list or table with its filter row",
            "A detail or form panel for the selected item",
            "Secondary panels such as activity, audit history, or settings for the same object",
            "Empty, loading, and error states drawn in the same slots as the data"
          ]
        }
      }
    }
    // 6 more: centered-stack-hero, trusted-by-band, icon-feature-grid, testimonial-carousel, closing-cta-banner, quiet-utility/corner-radius
  ]
}

Each finding names where the pattern is, what was observed, and what to put there instead: the chosen style's signature moves for the same job (proof, in the logo strip's case), its hero composition, or its section order. Rebuild, run the audit again, then add "structure" to get_design_audit_plan.includeGroups and pass the returned evidence and results to validate_design_audit_result. Audit each viewport with its own targetId: the evidence ids include it, so the runs validate together. The checks are deterministic heuristics over the submitted HTML and CSS, not a browser render, so clean means every check ran and found none of these patterns, not that the design passed. Per-style guidance (archetypes and moves) is written in English, like the catalog's own layout and typography fields; pattern names and instructions follow locale.

Must-haves a style can't remove

A direction must not cost the page its function. In the shelved showcase run (#7), the luxury skincare page built with the MCP kept a single buy button above the fold, while the control page showed sizes, a per-night price, add to bag, and delivery and guarantee details. So recommend_design_direction also returns mustHaves: the elements the resolved product type requires and the zone each one must sit in. A style restyles them but never removes them or moves them out of their zone, and they come before the archetype's limits on the opening ("one action, one short line"): every first-screen item goes in the hero. Each candidate's structure.mustHaves names that style's signature moves that do the same job, for example the proof move that can carry delivery and guarantee details.

The first screen is everything up to the end of the opening section (the section that holds the page's h1), plus up to two following sections while each section so far is short (≤ 40 words, no image, video, table, or large SVG, and not sized to fill the viewport). The site header counts; the footer does not. A brief whose product type is neither given nor inferred resolves to other, which has no list, and the result says so instead of inventing one. Every criterion is in webstylebook://structure/must-haves.

Pass the same productType to audit_page_structure, and it reports which must-haves the built page is missing. This is its real output for the showcase failure, rebuilt as a fixture (commerce-buy-button-only.html):

// → audit_page_structure({ html, styleId: "midnight-noir", productType: "commerce" })
// ← must-have audit (trimmed)
{
  "mustHaves": {
    "productType": "commerce",
    "page": "product detail page",
    "missing": [],
    "misplaced": ["price", "variant-choice", "purchase-assurance"],
    "items": [
      { "id": "price", "checkId": "structure-must-have-price", "zone": "first-screen", "status": "misplaced", "count": 1,
        "locations": ["section#buy > div > p.price:nth-of-type(1)"] },
      { "id": "add-to-cart", "checkId": "structure-must-have-add-to-cart", "zone": "first-screen", "status": "present", "count": 1,
        "locations": ["body > main > section.masthead:nth-of-type(1) > div > a.button"] }
      // 2 more: variant-choice and purchase-assurance, both misplaced
    ]
  },
  "findings": [
    {
      "patternId": "must-have/price",
      "scope": "must-have",
      "severity": "major",
      "observed": { "status": "misplaced", "zone": "first-screen", "found": 1, "inZone": 0 },
      "replaceWith": {
        "instruction": "Move it onto the first screen; the audit found it only further down the page. Show the price with its currency next to the product name; when sizes differ in price, show the price of the selected size.",
        "moves": [],
        "archetype": { "hero": "Left-heavy and low: a 1.7fr/1fr grid with align-items: end …" }
      }
    }
    // 2 more: must-have/variant-choice, must-have/purchase-assurance
  ]
}

Each must-have is present, missing, misplaced (on the page, but not on the first screen), or not-verified (the stylesheets exceeded the selector budget, parsing stopped before the end of the page, or the page has no section to place the first screen in). Each one is also a structure-must-have-<id> check: pass productType with the structure group to get_design_audit_plan, and the audit's evidence and results validate as they are. Detection reads markup, ARIA roles, and visible text in English, Korean, and Japanese. Anything hidden (hidden, display: none, a visually hidden sr-only box, or aria-hidden="true") does not count. Native controls are found reliably: a select or radio group for variants, an input type="search" for search, a time element for dates.

What an agent builds with it

A different brief — "a marketing landing page for Throughline, a B2B SaaS that turns scattered customer feedback (support tickets, sales calls, app reviews, Slack) into one prioritized roadmap." No layout, no hero, no styling was specified. Following the companion skill, the agent composed the opening from the product's core idea instead of reaching for a stock hero: the right half is a bespoke diagram of the product's actual mechanic — feedback sources converging into an auto-ranked roadmap — not a decorative card you could paste onto any other site.

How it works

flowchart LR
    A[Existing UI + user task] --> B[Host captures before]
    B --> C[get_design_improvement_plan]
    C --> D[Host edits and verifies]
    D --> E[validate_design_improvement_result]
    E -->|needs-work| D
    E -->|complete / no-change| F[Before/after report]

The agent describes the product; the server scores its curated catalog and returns structured evidence. After building, the agent passes the page markup to the structure audit, which never reads files on its own. After inspection, the validator checks the result contract without opening the referenced artifacts or judging visual quality. No code is generated and nothing leaves your machine.

Install

Requires Node ≥ 20.

Use the Codex CLI:

codex mcp add web-stylebook -- npx -y web-stylebook-mcp@latest

Or add it to ~/.codex/config.toml. You can also use a project-scoped .codex/config.toml in a trusted repository:

[mcp_servers.web-stylebook]
command = "npx"
args = ["-y", "web-stylebook-mcp@latest"]

Restart Codex or open a new session after editing config. In the Codex TUI, run /mcp to confirm the server is active.

claude mcp add web-stylebook -- npx -y web-stylebook-mcp@latest

Add to your MCP config:

{
  "mcpServers": {
    "web-stylebook": {
      "command": "npx",
      "args": ["-y", "web-stylebook-mcp@latest"]
    }
  }
}

Add the same block to your claude_desktop_config.json, then restart:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "web-stylebook": {
      "command": "npx",
      "args": ["-y", "web-stylebook-mcp@latest"]
    }
  }
}

Tools

Catalog: 520 real-world design references · 48 styles · 25 interface design principles · 23 UX principles · 51 structured audit checks · 20 components · 5 surfaces · 57 UI-state recipes · 29 motion profiles · 14 product archetypes.

Structure: 48 layout archetypes · 144 signature moves · 9 banned generic patterns · 142 style-specific bans from 19 detectors · 21 must-haves across 14 product types.

The reference library is an adapted, high-completeness subset of OpenDesign, whose structured specifications are licensed under CC BY 4.0. Web Stylebook excludes upstream screenshots and brand assets. Original sites, brands, copy, typefaces, and visual identities remain the property of their respective owners; inspect each detail's attribution and rights notice before use.

Preserve the website's visual specification

Opt into the shared contract when the selected style or web-editor adjustments must survive token generation:

{
  "primaryStyleId": "brutalist-grid",
  "format": "css-variables",
  "contract": { "schema": "webstylebook.visual.v1" },
  "locale": "ko",
  "overrides": {
    "colors": { "text": "#111111" },
    "typography": { "body": { "lineHeight": 1.75 } }
  }
}

Read webstylebook://manifest for visualContract.contractSchema and the bundled library's visualContract.contentHash. Read webstylebook://styles/brutalist-grid for the selected native contract and its visualContract.revision. Pass those values as contract.schema, contract.contentHash, and contract.revision to pin the source; a mismatch returns INVALID_INPUT. Omitting colorMode uses the style's authored native mode. Requesting light, dark, or both succeeds only when the required modes are authored.

overrides accepts semantic colors, typography roles, spacing, density, and font metadata. Use these explicit values for selections taken from another style; secondaryStyleId remains the legacy accent overlay and is rejected in contract mode. Unknown fields and conflicting density / accentOverride aliases are rejected. Supply contract whenever using overrides or acceptedRepairs.

The result includes the selected visualContract, source identity in contract, and repairProposals. Repairs stay unapplied until their exact proposal objects are sent back in acceptedRepairs; stale proposals are rejected. Apply accepted repairs with a single light or dark request; both requests return separate mode proposals. Keep visualContract alongside exported CSS: it carries component color pairs, font loading and license metadata, usage rules, provenance, and accepted repairs. Theme output also includes roleStyles and a complete metadata companion. Font loading and rendered appearance still require checks in the consuming app.

The shared runtime includes seven portable MIT sources, including fontSources.ts metadata for Korean/Japanese heavy display fallbacks. It includes no browser font loader or font binaries. visual:sync preflights the source import closure and license declarations before writing, and visual:check verifies the source hashes and artifact bytes. When updating the website revision, regenerate and synchronize catalog.v1.json, manifest.v1.json, and the visual artifact together; update the exact source pin in .github/workflows/publish.yml as well.

Export a DESIGN.md

compose_design_tokens with format: "design-md" returns the chosen direction as a DESIGN.md file (spec version alpha), so other agents and tools can read it. The server never writes the file: save content as DESIGN.md in the project.

{
  "primaryStyleId": "brutalist-grid",
  "format": "design-md",
  "contract": { "schema": "webstylebook.visual.v1" },
  "locale": "ko",
  "designMd": { "tokenPlacement": "interleaved", "productType": "developer-tool" }
}

• designMd.tokenPlacement: front-matter (default) puts every token in one YAML block at the top. interleaved keeps only name and description there and puts each token group in a YAML block inside its section.

• includeProse, includeDoDont, and includeStructure (all true by default) control the prose, the Do's and Don'ts built from the style's bans and the banned page patterns, and the page structure in Layout. productType adds that product type's must-haves to Layout.

• Colors use DESIGN.md names: primary is the text color, surface the page background, then accent, on-accent, surface-container, outline, and so on. The Colors prose names the compose_design_tokens role behind each one. Color values are hex; translucent colors become 8-digit hex. Components reference tokens, for example {colors.action-primary}. Dimensions are px, em, or rem only, and fluid type keeps its maximum size.

• The result also has sections, omitted (sections left out, each with a reason), lossy (values DESIGN.md has no key for, such as a second color mode, status colors, motion, and shadows), specVersion, and sourceHash. The same input returns the same bytes.

• webstylebook://design-md/{id} serves the same file for one style from its pinned visual contract. Optional query parameters: locale, mode, placement.

Every style, in both placements, all three locales, and with or without a contract, passes npx @google/design.md lint (0.4.0) with no errors. Its only warnings are text/background pairs below 4.5:1, which compose_design_tokens also reports.

Localized output

Every tool takes an optional locale. Reason codes, guidance, and labels come back in the requested language:

"en" | "ko" | "ja"     // English · 한국어 · 日本語

Resources

Browse the catalog directly over MCP resources:

webstylebook://manifest
webstylebook://styles · /styles/{id}
webstylebook://motion · /motion/{id}
webstylebook://components · /components/{id}
webstylebook://principles · /principles/{id}
webstylebook://design-principles · /design-principles/{id}
webstylebook://foundations · /foundations/{id}?locale=ko · /foundations/sources
webstylebook://states/surfaces · /states/{surface} · /states/{surface}/{state}
webstylebook://products · /products/{id}
webstylebook://references · /references/{id}
webstylebook://policies/anti-patterns · /policies/verification · /policies/audit-checks
webstylebook://structure/banned-patterns · /structure/must-haves
webstylebook://design-md/{id}
webstylebook://workflows/improve-ui

Style detail accepts optional locale, mode, and expected revision query parameters, for example webstylebook://styles/brutalist-grid?locale=ko&mode=light. It returns one resolved locale and mode; unsupported values, duplicate parameters, and unknown query names return an explicit error.

Foundation detail accepts one optional locale=en|ko|ja parameter. manifest.designFoundations describes this independently versioned MCP knowledge layer; the website's canonical catalog and its content hash remain separate.

Prompts

Ready-made MCP prompts for common workflows:

improve-ui · design-product · design-screen · complete-ui-states · redesign-with-style · audit-design-direction · audit-design-principles · audit-ux-principles

improve-ui starts the implementation/comparison workflow for existing interfaces. It asks only for missing information that blocks execution, not routine reapproval. audit-design-direction is an explicit review prompt: omitted scope defaults to read-only visual/content inspection. Its auditScope and changeScope parameters still allow narrower reviews, proposals or implementation; implement-and-verify continues through the improvement workflow.

Content coverage checks more than jargon: it tests whether material claims, conclusions, and recommendations match their support and expressed certainty, whether prominent copy conveys concrete context-specific information, and whether its visual emphasis matches information value, task relevance, and support. Cards, statistics, and Sitemap links are still judged by their actual user-task value rather than banned as types.

Keep what worked through a redesign

Redesigns quietly drop links, form fields, handlers, the selectors a script queries, and must-haves. Before you redesign a page, save its rendered HTML (for example document.documentElement.outerHTML) and its CSS. When the redesign is built, pass both versions to compare_page_revisions:

{
  "before": { "html": "<!doctype html>…", "css": ["…"] },
  "after": { "html": "<!doctype html>…", "css": ["…"] },
  "scriptSelectors": ["#cart-form", ".js-variant"],
  "productType": "commerce",
  "acknowledged": [
    { "kind": "link", "key": "/pricing", "change": "dropped", "reason": "Pricing moved to the sales contact page" }
  ]
}

A heading or link whose wording changed while its place or target stayed is reported as reworded (RISK). An acknowledged entry needs the matching kind, key, and change and a reason of at least 12 characters; a shorter reason does not excuse the loss and adds a RISK finding. Links, headings, figures, landmarks, words, and must-haves count visible elements only. Fields, handlers, and both kinds of hook also count hidden elements, because a hidden CSRF field, a closed dialog, or a cart drawer behind display: none is still part of how the page works.

The result has verdict (PASS, FIX_NOW, or RISK), an inventory with kept, lost, reworded, and acknowledged items, wordCount, findings, and evidence and results for the redesign-kept-<inventory> checks. To record them, call get_design_audit_plan with revisionPreservation: true (and the same productType); that plan holds only these checks, so validate_design_audit_result accepts the evidence and results as they are. Plans without revisionPreservation keep their checks and hash.

Audit result contract

get_design_audit_plan now returns an identity with the catalog version/hash and a deterministic planHash. After inspecting the actual implementation, submit the same plan query plus:

• one target per inspected route or screen, state, viewport, theme, locale, and role;

• evidence with a durable artifact reference, content hash, or exact route/selector/file/region;

• a before/input/after/recovery phase for interaction evidence; and

• one result for every planned check/target pair.

validate_design_audit_result regenerates the plan and rejects stale plan hashes, missing or duplicate result slots, broken evidence references, cross-target evidence, invalid regions, unsupported NOT_APPLICABLE, and PASS that lacks required evidence or contradicts failed evidence. Missing result slots are materialized as NOT_VERIFIED, never hidden. With includeGroups containing structure and a styleId, the plan adds one automated check per banned pattern, and productType adds one per must-have; audit_page_structure returns evidence and results for those check ids that the validator accepts as they are. With revisionPreservation: true, the plan holds only the redesign-kept-* checks that compare_page_revisions answers. The result carries content-addressed plan, evidence-bundle, and normalized-result hashes for comparable rechecks. The tool never opens the artifact references and never turns contract validity into a design-quality score.

The repository includes a reproducible contract-quality benchmark:

npm run eval:audit-contract

Across 14 human-labeled normal and adversarial cases, legacy pass-through verdicts score 4/14 (28.57%) with 9 false PASS results. The validator scores 14/14 with 0 false PASS results and classifies every contract-valid/invalid case correctly. The corpus covers missing, narrative-only, unknown, cross-target, indeterminate, phase-less, blocker/major/minor failure, honest NOT_VERIFIED, and valid/invalid NOT_APPLICABLE cases. This demonstrates result-contract correctness; it does not claim that subjective visual judgment itself is 100% accurate.

CLI

web-stylebook-mcp                 # run the server over stdio (default)
web-stylebook-mcp --version
web-stylebook-mcp --catalog-info
web-stylebook-mcp --validate-catalog

Companion skill

A companion skill ships in skill/ so your agent reaches for these tools at the right moment — and uses the results well (compose, don't recolor; offer multiple candidates; earn trust, don't fake it; land on reusable components):

Codex

• Copy or symlink skill/web-stylebook-design/ into a Codex skill location such as .agents/skills/web-stylebook-design/ in your repo, or ~/.agents/skills/web-stylebook-design/ for your user profile.

• If you do not want to install the skill, copy skill/AGENTS.md into your project's AGENTS.md.

Claude Code and other agents

• Point your agent's skills directory at skill/web-stylebook-design/, or

• Copy skill/CLAUDE.md into your project's CLAUDE.md or equivalent rules file.

Privacy & security

The server reads from a catalog snapshot bundled in the package. Nothing is sent anywhere; the same inputs always yield the same contracts.

Catalog source sync

The canonical catalog is authored in the web-stylebook repository. After generating its local MCP handoff snapshot, verify byte-for-byte parity before releasing this package:

npm run catalog:check-canonical -- /absolute/path/to/web-stylebook/packages/mcp/generated

Without an argument, the command uses WEB_STYLEBOOK_CANONICAL_CATALOG_DIR or the local sibling path ../showcase/packages/mcp/generated. The regular test suite verifies the bundled artifact's internal hash, enums, counts, and runtime contract; this command is the explicit cross-repository source check.

Compatibility

• Node: ≥ 20

• Transport: stdio (Model Context Protocol)

• Clients: Codex CLI / IDE extension, Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client

Tool inputs are unchanged apart from new optional values, and structure is an added output field. Plans requested without includeGroups keep their checks and hash, because structure is opt-in. Calls without contract keep the same token shape and light-mode default. As of 0.11.0, those calls emit the pinned style's authored shadows instead of the generic soft shadow, and editorial or monospace-led styles emit authored font families instead of the style-family fonts. Color, type scale, line-height, spacing, radius, motion, and omitted density stay on the previous legacy path. An explicit density still takes precedence over a family's row and gutter, and CSS / theme output retains line-height tokens. Pass contract for the full authored specification. The shared contract is additive; no new tool is required.

License

MIT — covers the code and the bundled catalog snapshot (free for commercial use).

The webstylebook.com website is licensed CC BY-NC. The same owner grants an MIT license for the catalog snapshot bundled in this package.

UX-principle entries are independently written application and verification guidance. They attribute and link to Laws of UX (CC BY-NC-ND 4.0) and supporting references; Laws of UX prose, illustrations, and page layouts are not bundled.

Interface-design-principle entries form an independently authored, task-oriented review system for contemporary interfaces. They cover semantic structure, responsive reflow, localization, tokens and themes, multiple input modes, complete state models, recovery, and motion preferences.