Kaava
Generates a tokens.css stylesheet exposing the design system as CSS custom properties, with light/dark theme support via OS preference or data-theme/.dark.
Emits W3C Design Tokens (tokens.json/tokens.dark.json) intended for consumption by Figma plugins and Style Dictionary.
Provides Google Fonts family autocomplete and preview in the workbench, and adds the selected font's stylesheet to the generated style.
Generates _tokens.scss with Sass variables plus the corresponding CSS custom properties for use in Sass projects.
Generates typed tokens.ts objects of resolved design-token values for use in TypeScript-based apps, components, charts, and native targets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Kaava Set up a design system for this app with brand color #4f46e5 and a friendly feel."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Kaava
An MCP server that gives your coding agent a real design system.
Agents are good at taste and bad at color math. Left alone they invent a new shade of blue in every file, pick greys that fail contrast, and drift between turns. Kaava (Finnish for formula) splits the work:
The agent supplies the brief: a brand color and a style.
A style supplies the character: ramp shape, typography, spacing rhythm, corners, elevation and motion, authored by a person and stored as a file.
Kaava supplies the formula: OKLCH color ramps, light and dark semantic roles that are contrast-checked, a modular type scale, spacing, radii, shadows and motion. Deterministic: the same brief always produces the same system.
The result is one kaava.json in your repo, emitted as CSS variables, a Tailwind v4 theme, SCSS, TypeScript, W3C design tokens, and a DESIGN.md that tells the next agent session how to use it.
No API keys, no network calls, no LLM inside the server.
Both pages are preview.html as emitted by Kaava from a two-field brief: a brand color and a style. Open the live examples, or browse every generated file in examples/. The example names are Finnish too: ahtaaja is a stevedore, hinaaja a tugboat.
Install
Claude Code:
claude mcp add kaava -- npx -y kaava-mcpCursor, VS Code, Claude Desktop and other MCP clients:
{
"mcpServers": {
"kaava": { "command": "npx", "args": ["-y", "kaava-mcp"] }
}
}Requires Node 20 or newer.
Related MCP server: Ensemble MCP
Use
Ask your agent:
Set up a design system for this app with Kaava. Brand color is #4f46e5, friendly feel.
or run the built-in new-design-system prompt, which has the agent inspect the project, ask what it cannot infer, generate the system and wire it in.
What happens:
kaava_create_systemwriteskaava.jsonand reports contrast.kaava_emitwrites the outputs for your stack intokaava/(or a directory you choose).The agent reads
DESIGN.mdand builds UI from tokens instead of hard-coded values.Later, "make the corners rounder" or "the dark primary is too dull" becomes a
kaava_update_systemcall, and every emitted file is regenerated.
Tools
Tool | What it does |
| Brief → full design system saved to |
| Patch the brief, or override single tokens. Regenerates emitted files. |
| Look up tokens by path ( |
| Write |
| Accessibility audit against WCAG 2.2 AA: every promised color pairing (with APCA values), fill boundaries, status colors under color-vision deficiencies, target sizes. |
| Check any two colors or tokens against WCAG 2.2; when the pair fails, get the nearest passing color and the system text colors that do pass. |
Resources: kaava://system (the current kaava.json) and kaava://styles (every style, its author and each decision it makes).
The brief
Field | Values | Default |
| any CSS color | required |
| any CSS color | derived from the brand hue |
|
|
|
|
| from style |
|
| from style |
| 1.067 – 1.5 | from style |
| 0 – 1, how much brand hue the greys carry | from style |
|
| from style |
|
| from style |
| boolean |
|
Explicit fields win over the style: each one swaps a single aspect of it for a generic version, so leave them out to keep the style as designed.
Styles
A style is one JSON file in styles/ holding every decision that gives a system its character, independent of brand color: the lightness and chroma curve of the color ramps, which steps are page and surface, status hues, type families and web fonts, each type size with its line height and letter-spacing, control heights and spacing rhythm per density, the radius scale, border width, shadow layers, durations and easings. Each file names its author.
Styles are designed in the workbench, a local page with a control for every value and a live preview rendered by the real engine:
npm run workbench # http://127.0.0.1:4174It shows the style against several brand colors at once, with a contrast verdict for each, because a style has to hold for any color a brief brings. The family fields autocomplete every Google Fonts family, and a searchable list shows each one in its own typeface; choosing one adds its stylesheet to the style. Saving writes styles/<id>.json; the test suite then checks the new style against WCAG 2.2 AA across 102 brand colors.
The built-in styles are generic starting points. Duplicate one and make it yours.
Overrides
When a derived value is not what you want, override the token rather than editing files:
{
"overrides": {
"radius.control": "{radius.full}",
"font.size.base": "1.0625rem",
"dark:color.primary": "#8b9cff"
}
}Keys are token paths; prefix semantic colors with light: or dark: to target one theme. Values are CSS values or {references} to other tokens. Overrides survive brief changes, and kaava_audit tells you if one broke contrast.
What you get
Color. Seven 11-step ramps (neutral, primary, accent, success, warning, danger, info) with identical lightness per step, plus semantic roles for light and dark: bg, surface, surface-muted, fg, fg-muted, border, border-strong, ring, and for each of primary / accent / status: the fill, its hover, on-* text, a *-subtle tint, on-*-subtle text and *-text for colored text on surfaces. Your exact brand color is the primary fill. Text roles are chosen by searching the ramp for the first step that reaches 4.5:1 on every surface it is promised for, so the pairings hold for any brand color.
Type. Nine sizes on a modular scale with matched line heights, four weights, sans / mono / display families.
Space and shape. A 4px spacing scale, semantic spacing (gap, inset, section, control), control heights, a radius scale with control and surface aliases, three shadow levels, durations and easings.
Accessibility. Every promised text and UI pairing meets WCAG 2.2 AA for any brand color, and the test suite sweeps 102 brand colors across all styles to keep it that way. kaava_audit also reports what tokens alone cannot guarantee: fills too faint to mark a button's edge, status colors that look alike with protanopia, deuteranopia or tritanopia, and controls under 24px. kaava_check_contrast covers any pairing you add yourself. The emitted stylesheets honor prefers-reduced-motion. Kaava audits the tokens, not rendered pages: run a tool such as axe on the built UI for markup, labels and focus order.
Output formats
Target | File | For |
|
| Any framework. Custom properties on |
|
| Tailwind v4. |
|
| Sass variables plus the custom properties. |
|
| Typed objects of resolved values for React, Vue, Svelte, React Native, charts. |
|
| W3C Design Tokens format for Figma plugins and Style Dictionary. |
|
| Tokens as YAML front matter, usage rules and the full role table, in the DESIGN.md format. Check it with |
|
| A self-contained page showing the system in use, with every role, ramp and scale. Open it in a browser; add |
Notes
Kaava writes only inside the project root: the workspace root your MCP client exposes, or the directory the server starts in. Every writing tool accepts
dryRun.kaava.jsonand the emitted files are generated. Change them through the tools; hand edits are overwritten on the next update.kaava_create_systemrefuses to replace an existing system unless you passoverwrite: true.kaava_emitnever replaces a file it did not generate (your owntokens.css, say) unless you passoverwrite: true, and it does not follow symlinks out of the project.
Roadmap
0.2 Components: framework-neutral specs and shared styles with thin React, Vue, Svelte and HTML wrappers; scanning code for hard-coded values.
0.3 Import an existing system from CSS variables, Tailwind config or DTCG files.
0.4 Import from Figma and Storybook.
Programmatic use
import { buildSystem, renderTargets } from 'kaava-mcp';
const system = buildSystem({ brandColor: '#4f46e5', style: 'friendly' });
const files = renderTargets(system, ['css', 'design-md']);Development
npm install
npm test # engine, emitters, and an in-memory MCP client end to end
npm run build
npm run inspect # open the MCP Inspector against the built server
npm run workbench # design styles with a live preview
npm run examples # regenerate examples/ after a change to generated outputLicense
MIT © Mikko Grönlund
Available Tools
6 toolskaava_auditAudit accessibilityARead-only
Accessibility audit of the current design system against WCAG 2.2 AA, in light and dark. Checks every promised foreground/background pairing (4.5:1 text, 3:1 UI, with APCA Lc for reference), whether solid fills have a visible boundary, whether status colors stay distinguishable with color-vision deficiencies (protanopia, deuteranopia, tritanopia), control target sizes and minimum text size. Run after overriding colors or sizes. It audits the tokens, not rendered pages.
Inputs: projectRoot, failuresOnly.
kaava_check_contrastCheck contrastARead-only
Check one foreground/background pair against WCAG 2.2 and report the APCA Lc value. Each color is a CSS color ("#767676", "rgb(0 0 0 / 0.6)") or a token of the current design system ("color.fg-muted", "--color-primary", "palette.neutral.400"). When the pair fails, returns the nearest passing color of the same hue and the system text colors that do pass on that background. Use it before introducing a pairing the system does not already promise. Works without a kaava.json when both colors are CSS colors.
Inputs: background (required), foreground (required), use, mode, +2 more.
kaava_create_systemCreate design systemADestructiveIdempotent
Generate a complete design system from a short brief and save it as kaava.json in the project root. Only brandColor is required; style picks a hand-authored character for the rest (read kaava://styles for what each one is). Returns a summary and a contrast report. Follow with kaava_emit to write tokens for the project stack.
Inputs: brandColor (required), name, fonts, style, +11 more.
kaava_emitEmit tokensAIdempotent
Write the design system out for the project stack. Targets: "css" (custom properties, works with any framework), "tailwind" (Tailwind v4 @theme), "scss", "ts" (typed token object for React/Vue/Svelte/React Native), "dtcg" (W3C design tokens JSON for Figma/Style Dictionary), "design-md" (DESIGN.md in the open DESIGN.md format: tokens as YAML front matter plus usage rules, for agents and people), "preview" (self-contained preview.html showing the system in use, for the user to open in a browser). The choice is remembered, so later kaava_update_system calls regenerate the same files.
Inputs: targets (required), dryRun, outDir, overwrite, +1 more.
kaava_get_tokensGet tokensARead-only
Look up tokens from the current design system. Without a path, returns the list of token groups. With a path prefix ("color", "color.primary", "palette.neutral", "font.size", "space", "radius", "shadow"), returns each token with its CSS variable and value. Semantic colors live under "color"; raw ramps under "palette".
Inputs: mode, path, projectRoot.
kaava_update_systemUpdate design systemAIdempotent
Change the existing design system: patch brief fields (everything is re-derived) and/or override individual tokens. Files written earlier by kaava_emit are regenerated. Overrides are keyed by token path, e.g. {"radius.control": "{radius.full}", "dark:color.primary": "#8b9cff", "font.size.base": "1.0625rem"}; prefix semantic colors with "light:" or "dark:" to target one theme.
Inputs: brief, dryRun, overrides, projectRoot, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool maps to a distinct action: create, update, read tokens, full a11y audit, emit for stack, and single-pair contrast check. The audit vs check_contrast boundary is clearly explained (whole-system audit vs one-off pair check), so an agent can pick correctly.
All tools share the kaava_ prefix and snake_case with verb-first naming (create_system, update_system, get_tokens, check_contrast). Two tools (kaava_audit, kaava_emit) drop the noun object, a minor deviation from the otherwise consistent verb_noun pattern.
Six tools is well-scoped for a design-system generator: create/update lifecycle, token introspection, auditing, contrast check, and multi-target emission. No tool feels redundant or padding.
The surface covers create → update → inspect → audit → emit plus ad-hoc contrast checks, a solid lifecycle. The only notable gap is no delete/reset operation to remove kaava.json or clear overrides, which agents might occasionally need.
Related MCP Connectors
Generate design systems: OKLCH colors, fluid type scales, spacing, shape, icon and motion tokens.
Give your agent a real design system: tokens, measured WCAG contrast, and rules to follow.
Build and manage your design system with AI: tokens, themes, components, icons, Figma and code.
BrandPilot brands and design systems for coding agents: tokens, design context, repo rules.
Related MCP Servers
- AlicenseAqualityDmaintenanceTranslates design tokens across platforms — extracts from Tailwind/CSS/Figma and generates native themes for Material 3, SwiftUI, and CSS variables with WCAG contrast validation.9106 npm5MIT
- AlicenseAqualityCmaintenanceEnables AI agents to generate complete, deterministic design systems from a single brand color — harmonious palettes, font pairings, type and spacing scales, elevation shadows, responsive grids, motion presets, dark-mode themes, and WCAG contrast audits — and export them as CSS, JSON, Tailwind, or SCSS through natural conversation.1063 npmMIT
- AlicenseAqualityCmaintenanceEnables LLM agents to search, resolve and audit DTCG design tokens — finding the token behind an intent or a hard-coded color/size, checking naming grammar, auditing CSS for hard-coded or unknown tokens, arbitrating semver, and previewing token additions as JSON Patch diffs. Writes are gated behind explicit confirmation plus an opt-in flag, so every change arrives as a reviewable proposal rather than an edit.7MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to generate harmonized presentation design themes from a primary brand color, including WCAG AA/AAA contrast checks, typography pairings, and semantic styling tokens.7MIT

