Skip to main content
Glama

Lumen: a design system AI assistants can read

Lumen is a small, machine-readable design system. Its tokens and component rules are data, an MCP server serves them to AI assistants, and a checker scores the UI those assistants produce.

Live demo: add the Vercel link here after the first deploy

Same prompt

Adherence score

Assistant without the design system

29% (27 off-system values)

Assistant with Lumen over MCP

100% (0 off-system values)

Scores come from the included checker (npm run score). The v0.1 samples are hand-written examples of typical output; see Limits.


The problem

Design systems are mostly written for people: documentation sites, Figma libraries, component packages. More and more UI is now drafted by AI assistants, and they never read the docs site. They invent colours, pick spacing by feel and restyle native elements instead of using the components a team already maintains. Every screen built that way adds design debt that someone has to find and fix by hand.

The design system needs a second audience: machines.

Related MCP server: ds-mcp

Who it is for

User

Need

Design system owners

Know whether AI-generated UI follows the system, without reviewing every screen by hand.

Designers, PMs and engineers building with AI

Get on-brand UI from the first prompt instead of fixing it afterwards.

AI assistants

A precise, queryable source of truth: which tokens exist, what each is for, which component to use.

What it does

  1. Tokens as data. Colour, spacing, radius, border and type live in one W3C Design Tokens file (tokens/tokens.json). Style Dictionary turns it into CSS variables and a flat JSON list. Colour is split into a raw palette and semantic tokens (text, surface, action, border, feedback), and only semantic tokens are meant for components.

  2. Rules as data. rules/components.json holds global rules and, for each component, its props, the tokens it uses and its usage rules ("at most one primary button per view"). Prose guidelines become something an assistant can query.

  3. Served over MCP. mcp-server/ exposes three tools:

    • get_tokens: tokens with CSS variable, value and intended use, filterable by category.

    • get_component_rules: global rules plus one or all components.

    • check_ui: scores a piece of UI code and returns each off-system value with the token to use instead.

  4. Checked before it ships. The checker finds raw colours, framework palette classes (bg-blue-500), arbitrary values (p-[13px]), off-scale pixel values, unknown tokens and palette tokens used where a semantic token belongs. Colour suggestions depend on the CSS property, so #fff as a background suggests color.surface.default and as text suggests color.text.on-action.

How I would measure success

Metric

Why it matters

Adherence score of AI-generated UI, per product area

The core outcome: are assistants building on-system?

Share of generated screens that pass check_ui with no edits

Measures how much manual clean-up remains.

Time from prompt to an on-system screen

The value builders feel.

Tool calls per session (get_tokens, get_component_rules)

Shows whether assistants actually consult the system.

Tokens and rules with no lookups over 90 days

Finds parts of the system nobody uses.

Try it

Requires Node 20 or later.

npm install
npm test          # checker and MCP server tests
npm run dev       # demo page at http://localhost:5173
npm run check -- samples/before.jsx   # score any file

Use it from Claude Desktop (or any MCP client)

Run npm install && npm run tokens once, then add this to your MCP client config with your absolute path:

{
  "mcpServers": {
    "lumen": {
      "command": "node",
      "args": ["/absolute/path/to/design-system-mcp/mcp-server/index.mjs"]
    }
  }
}

Then ask: "Using the Lumen tools, build a sign-up card in React, run check_ui on it and fix any violations."

Repo layout

tokens/tokens.json        source of truth (W3C DTCG format)
rules/components.json     global and per-component rules
scripts/build-tokens.mjs  Style Dictionary build to build/tokens.css and build/tokens.flat.json
components/               React components that use only tokens
checker/                  adherence checker
mcp-server/               MCP server (stdio)
samples/                  same prompt, without and with the system
site/                     demo page (Vite + React), deployed on Vercel
tests/                    node:test suites

Design decisions

  • W3C Design Tokens format. It is the emerging standard, tools like Style Dictionary and Figma variables can read it, and an assistant gets one predictable shape.

  • Semantic tokens over palette tokens. color.action.primary tells an assistant what a colour is for. blue-600 only says what it looks like, which is how off-system UI starts.

  • MCP rather than a long system prompt. The assistant asks for what it needs, when it needs it, from any MCP client. The system stays one source of truth instead of being pasted into prompts that drift.

  • A simple, explainable checker. Pattern rules are easy to trust and debug, and each violation comes with a fix. A score nobody can explain will not change behaviour.

Limits

  • The v0.1 before and after samples are hand-written to show typical patterns. The next step is recorded runs: the same prompt in one assistant session without the MCP server and one with it, with transcripts stored in samples/runs/.

  • The checker uses patterns, not a full parser. It does not judge layout, hierarchy or accessibility, and it counts layout widths such as 400px as off-scale.

  • Five components and one theme, by design. It is a working prototype of the idea, not a full system.

What I would build next

  1. Recorded evaluation set. Ten prompts, several runs each, with and without the server, so the score difference is measured rather than illustrated.

  2. Figma variables sync. Read and write the same token file from Figma so designers and assistants share one source.

  3. Theming and multiple brands. Semantic tokens resolving to different palettes per product, which is where machine-readable systems pay off at scale.

  4. CI check. Run check_ui on pull requests and report the adherence score per product area.

  5. Split into small services. Separate token, rules and checking services with versioned APIs, so product teams can adopt one piece without the whole platform.


Built by Ibrahim Adil as a product exploration of design systems for AI-assisted building. MIT licensed.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that exposes your design system components and tokens to AI agents, preventing duplicate component creation and hardcoded token values.
      6 npm
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A read-only MCP server that provides AI coding agents with a queryable contract for design system tokens, components, patterns, and anti-patterns.
      13 npm
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that gives AI assistants structured access to a design system's tokens, components, guidelines, and patterns, enabling them to read, lint, and author design system data.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Read-only MCP server that exposes a design system's tokens, components, conventions, and deprecations as queryable tools, enabling agents to look up canonical values, assess change impact, and detect hardcoded value drift.
      8
      3 npm
      MIT