Skip to main content
Glama

Kaava

npm CI license

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.

Ahtaaja: #4f46e5, friendly

Hinaaja: #ffd400, playful, dark

Preview of the Ahtaaja example system in light mode

Preview of the Hinaaja example system in dark mode

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-mcp

Cursor, 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:

  1. kaava_create_system writes kaava.json and reports contrast.

  2. kaava_emit writes the outputs for your stack into kaava/ (or a directory you choose).

  3. The agent reads DESIGN.md and builds UI from tokens instead of hard-coded values.

  4. Later, "make the corners rounder" or "the dark primary is too dull" becomes a kaava_update_system call, and every emitted file is regenerated.

Tools

Tool

What it does

kaava_create_system

Brief → full design system saved to kaava.json. Only brandColor is required.

kaava_update_system

Patch the brief, or override single tokens. Regenerates emitted files.

kaava_get_tokens

Look up tokens by path (color, font.size, palette.primary, …).

kaava_emit

Write css, tailwind, scss, ts, dtcg, design-md, preview outputs.

kaava_audit

Accessibility audit against WCAG 2.2 AA: every promised color pairing (with APCA values), fill boundaries, status colors under color-vision deficiencies, target sizes.

kaava_check_contrast

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

brandColor

any CSS color

required

accent

any CSS color

derived from the brand hue

style

minimal, friendly, corporate, playful, editorial, technical

default

density

compact, comfortable, spacious

from style

radius

none, sm, md, lg, full

from style

typeScale

1.067 – 1.5

from style

neutralTint

0 – 1, how much brand hue the greys carry

from style

shadows

none, soft, crisp

from style

fonts

{ sans, mono, display }

from style

darkMode

boolean

true

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:4174

It 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

css

tokens.css

Any framework. Custom properties on :root; dark mode follows the OS, or force it with data-theme="dark" / .dark.

tailwind

tailwind.css

Tailwind v4. @theme variables in Tailwind's namespaces, so you get bg-surface, text-fg-muted, rounded-control, p-inset.

scss

_tokens.scss

Sass variables plus the custom properties.

ts

tokens.ts

Typed objects of resolved values for React, Vue, Svelte, React Native, charts.

dtcg

tokens.json, tokens.dark.json

W3C Design Tokens format for Figma plugins and Style Dictionary.

design-md

DESIGN.md

Tokens as YAML front matter, usage rules and the full role table, in the DESIGN.md format. Check it with npx @google/design.md lint kaava/DESIGN.md.

preview

preview.html

A self-contained page showing the system in use, with every role, ramp and scale. Open it in a browser; add #dark or #light to force a theme.

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.json and the emitted files are generated. Change them through the tools; hand edits are overwritten on the next update.

  • kaava_create_system refuses to replace an existing system unless you pass overwrite: true.

  • kaava_emit never replaces a file it did not generate (your own tokens.css, say) unless you pass overwrite: 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 output

License

MIT © Mikko Grönlund

Available Tools

6 tools
kaava_auditAudit accessibilityA
Read-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 contrastA
Read-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 systemA
DestructiveIdempotent

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 tokensA
Idempotent

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 tokensA
Read-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 systemA
Idempotent

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

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Translates design tokens across platforms — extracts from Tailwind/CSS/Figma and generates native themes for Material 3, SwiftUI, and CSS variables with WCAG contrast validation.
      9
      106 npm
      5
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      10
      63 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      7
      MIT