What is Web Stylebook MCP?
Web Stylebook MCP is a Model Context Protocol server that hands an AI coding agent scored design direction candidates, placement aware interface and UX principle plans, UI state plans, and role based design tokens, drawn from a bundled catalog of real world references and styles, entirely offline with no API key, model call or network access.
Web Stylebook MCP is a Model Context Protocol server built from a bundled, offline catalog. An agent describes a product, and the server scores styles, structure and tokens from that catalog, rather than generating code or calling a model itself.
Scored directions, not one guess
recommend_design_direction returns ranked style candidates with reason codes, a winner and runner up with a score gap, styles it rejected and why, and pairing suggestions, so the agent picks with evidence instead of committing to one look.
Tokens, structure and states
compose_design_tokens turns a chosen style into role based color, type, spacing and motion tokens with WCAG contrast warnings. Candidates also carry a layout archetype and signature moves, and get_ui_state_plan lists the states a surface needs.
Auditing a built page
audit_page_structure checks submitted HTML and CSS against banned generic patterns and the chosen style's own bans, naming each location and a replacement move. validate_design_audit_result then checks an audit's evidence and verdicts for consistency.
Who it suits
Best for
- Agents that need a defensible reason for one visual direction over another, with rejected candidates on record.
- Teams that want WCAG checked tokens and documented UI states before any code is written.
- Projects that want a page checked for the default hero plus three cards template after it is built.
Not for
- Researching real product references before locking one design direction, where Refero Design runs that research and lock step itself.
- Running blocking questions and adversarial critique before handing over component specs, where Octopus UI/UX Design enforces that question and critique workflow.
- Extracting real tokens by scraping an already live site, where Extract Design pulls those exact values instead of scoring a new direction.
- Turning one brief directly into finished brand color ramps and tokens, where Brandkit builds that foundation from scratch rather than a scored catalog.
Connect Web Stylebook MCP: Scored Design Directions for AI Agents to your AI client
claude mcp add web-stylebook -- npx -y web-stylebook-mcp@latestAdd the server
Run the command above in Claude Code, or paste the config block into Cursor, Windsurf, Claude Desktop or Codex. Node 20 or newer is required.
Describe the product
Ask for a direction for your product, tone, density and usage frequency.
recommend_design_directionreturns scored candidates and rejected styles with reasons.Compose tokens and states
Call
compose_design_tokensfor the chosen style andget_ui_state_planfor each surface, then build from the returned values.Audit after building
Pass the built page's HTML and CSS to
audit_page_structure, then feed the result intovalidate_design_audit_resultto confirm coverage.
Client configuration
{
"mcpServers": {
"web-stylebook": {
"command": "npx",
"args": ["-y", "web-stylebook-mcp@latest"]
}
}
}What you can do with it
- Reason coded recommendations
recommend_design_directionnames why the top style beat the runner up and why each rejected style was rejected. - Ties are reported as tiesWhen two candidates score alike, the result says
tied: trueinstead of inventing a winner. - Structure, not just colorEach candidate carries a layout archetype, section order and signature moves, and the catalog spans 48 layout archetypes.
- WCAG checked tokens
compose_design_tokensreports contrast warnings on role based tokens and supports CSS variables, Tailwind, JSON and TypeScript output. - UI states up front
get_ui_state_planlists required, recommended and domain states per surface, covering empty, error and loading cases. - Structure audit with evidence
audit_page_structureandvalidate_design_audit_resultturn an inspection into a contract with stable ids and hashes, not a pass or fail guess. - Offline and deterministicNo API key, no model call and no project access; the same inputs always return the same scored result.
- Localized outputEvery tool accepts a
localeof English, Korean or Japanese for reason codes, guidance and labels.
Tools it exposes
recommend_design_direction
Scores style candidates for a product brief, with a ranked winner, rejected styles and why, and each candidate's structure.
compare_design_directions
Compares two to four directions across product fit, trust, density, accessibility risk, motion and maintenance, with no single winner declared.
compose_design_tokens
Turns a chosen style into role based color, type, spacing, radius and motion tokens as CSS, Tailwind, JSON or TypeScript, with WCAG contrast checks.
get_ui_state_plan
Returns required, recommended and domain UI states for a surface such as a data table, form, checkout or chat, with triggers and accessibility notes.
get_design_principle_plan
Returns a placement, application and verification plan selected by visual concern, surface or phase.
get_ux_principle_plan
Returns an apply and verify plan for UX principles, labeled by evidence strength, with cautions and references.
audit_page_structure
Checks submitted HTML and CSS for banned generic and style specific patterns, naming each location and a replacement move.
validate_design_audit_result
Validates an audit plan query, target matrix and evidence for coverage and consistency, without judging visual quality itself.
Frequently asked questions
What is Web Stylebook MCP?
It is a Model Context Protocol server with a bundled, offline catalog of real world references, styles and principles. An agent sends a product description and gets back scored design direction candidates, UI state plans and design tokens, rather than generated code.
How do I install and connect Web Stylebook MCP?
Run claude mcp add web-stylebook -- npx -y web-stylebook-mcp@latest in Claude Code, or add the equivalent npx -y web-stylebook-mcp@latest command to Cursor, Windsurf, Claude Desktop or Codex. Node 20 or newer is required.
Does it generate the UI code itself?
No. The server returns scored evidence: direction candidates, UI state plans, tokens and audit findings. The calling agent still writes the code, now informed by that evidence rather than a default template.
What happens when two design directions tie?
recommend_design_direction reports tied: true in its ranking when the top two candidates score within a small gap, instead of forcing a single winner. The agent then chooses using product context.
Can it check a page after it is built?
Yes. audit_page_structure reads submitted HTML and CSS for banned generic sections, such as a logo strip or a stock hero, and for the chosen style's own banned patterns, naming each location, what was observed, and a replacement move drawn from that style's signature moves.
Does Web Stylebook MCP need an API key or network access?
No. It runs fully offline from a bundled catalog snapshot, makes no model calls, and does not read the project filesystem beyond the inputs an agent passes to it directly.
Which coding agents can use Web Stylebook MCP?
The project documents setup for Codex CLI, Claude Code, Claude Desktop, Cursor and Windsurf, plus a companion skill so an agent reaches for the right tool at the right step.