Skip to main content
Glama

Sekura Design MCP

A dockerized Model Context Protocol server that serves the complete Sekura Design System — tokens, components, layouts, UX patterns, accessibility contract and paste-ready code — to any MCP-capable tool.

Agents and developers can inspect the same tokens, native markup and interaction contracts. Application behavior still needs implementation and accessibility verification.

71 components · 16 foundations · 19 UX patterns · 9 layout recipes
120 semantic tokens · 4 themes · 3 densities · 8 target frameworks
Build-derived counts and support: sample/assets/component-manifest.json

The human-readable specification is DESIGN.md, and there is an 107-page documentation site — generated from the same data — that explains it with live demos, a full colour guide and worked examples.


Integration and migration

Sekura 3.2.2 updates the dependency tree and Node 24 runtime, including security fixes for body-parser and fast-uri. It includes the 3.2.1 changes, which remove inherited Workspace labels from examples and runtime UI, strengthen MCP guidance and add upgrade checks for existing applications. It includes the 3.2.0 changes, which address the reliability and product issues found in the 3.1 review: locale-aware input commitment, shared date validation, keyboard suggestions, predictable overlay and toast cleanup, safer HTTP boundaries, correct token exports, framework lifecycle integration and consistent release artifacts. The 3.2 review record maps each finding to its implementation and verification scope.

Navigation keeps the fixed system width with no width control in the UI. The Documents sample has its own app frame, scoped page search and mobile Document actions. Component pages lead with an interactive example and separate API maturity, native framework support, design-kit coverage and verification. The Form integration lab demonstrates draft retention and revision comparison after a conflict or uncertain save acknowledgment.

Read the migration plan for separate v2, v3.0.0 and v3.1.0 upgrade paths, HTTP configuration changes and rollback. Public-name checks cover recorded v2.1, v3.0.0 and v3.1.0 baselines. The source patch targets 3.1.0 commit 115375177e0aff5e8dbadf39bdb55d0b10948f2c; older source branches must first integrate that upstream base. New design files use the versioned handoff guide.

Existing applications also need the example-identity cleanup: remove inherited Workspace labels from markup and runtime updates while keeping routes, IDs and saved data intact. Updating the MCP does not rewrite an existing app.

The support matrix distinguishes CSS, native behavior, controllers, and application-owned actions. The workbench compares every control size and density and demonstrates pending, failure, retry, cancellation and real undo. Example data stays local; simulated remote actions are labelled.

All 71 components have stable API maturity; native implementation and verification coverage are reported separately. The completed implementations include multi-select and async search, a reusable command palette, exact/range sliders, tri-state lazy trees, cancellable upload retries, and complete workspace/timeline states. npm run test:completion checks these contracts in Chromium, Firefox and WebKit. Human screen-reader and application acceptance remain documented separately in MANUAL-VALIDATION.md.

Generated framework code is an editable reference recipe, preserving the native markup, unique IDs and controller cleanup. The dedicated native React package exports Button, TextField, Textarea, Select, Checkbox and Switch; the other generated examples remain editable recipes. Read the emitted API before passing specification props. Keep one owner for controller state and wire your own permissions, network requests, persistence and navigation.

Version 2 corrects the accordion Tab sequence and replaces the old generated wrappers. See migration notes and the second design review and the original audit. No package or site is published by a local build.

Related MCP server: ds-canon

Quickest start

./run.sh start-build

Builds everything — TypeScript, contrast audit, CSS lint, stylesheets, the documentation site and the Docker image — then serves MCP and the documentation on :8080, with the docs at /docs/.

./run.sh build          Compile, run gates, emit CSS, build the docs and the image
./run.sh start          Start the MCP server and the documentation site
./run.sh start-build    Build, then start
./run.sh restart        Stop, then start
./run.sh stop           Stop everything
./run.sh logs [target]  Follow server logs
./run.sh status         What is running, plus a live contrast-audit check
./run.sh verify         Run every gate without starting anything
./run.sh clean [--all]  Remove build output, container and image
./run.sh help

The MCP server runs in Docker when Docker is available and falls back to a local Node process when it is not, so the script behaves the same either way. The published port and the image names are overridable: SEKURA_PORT, SEKURA_IMAGE, SEKURA_CONTAINER.

./run.sh status is a real check rather than a liveness ping — /health re-runs the full contrast audit, so a server quietly using a broken palette reports it.


The documentation site

./run.sh start-build          # then open http://localhost:8080/docs/

A 107-page documentation site — explanations, a full colour guide, a type specimen, live demos, a complete component reference and ten worked examples.

It is generated from the design system's own data, so the colour guide shows genuinely audited contrast values and the component pages show the same specification the MCP server serves. Browser regression tests check that the documented interactions work.

color.html

Every ramp step with its contrast against white and black, all 120 semantic tokens in four themes, and the full 86-pairing contrast contract with measured ratios

dark-mode.html

The elevation inversion, demonstrated with the same markup under both themes side by side — plus the nine things that break silently

layout.html

Flex-first, with resizable demos that reflow on container width

tokens.html

Filterable reference for every token

component-*.html

One page per component: anatomy, states, dark-mode note, full keyboard and ARIA contract

See sample/README.md for what to try.


Quick start

docker compose up -d
curl http://localhost:8080/health

Or without compose:

docker build -t sekura-design-mcp .
docker run -d -p 8080:8080 --name sekura sekura-design-mcp

The build runs the contrast audit and the full smoke test. An image whose palette breaks a declared WCAG pairing does not get built.

Local

npm ci
npm run build
npm run build:behaviours
npm run emit:css
npm run site:build
npm start              # stdio
npm run start:http     # HTTP on 127.0.0.1:8080

Connecting a client

Claude Code / Claude Desktop — HTTP

{
  "mcpServers": {
    "sekura-design": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Claude Code — one-liner

claude mcp add --transport http sekura-design http://localhost:8080/mcp

OpenAI Codex

Codex reads MCP servers from ~/.codex/config.toml. Add a [mcp_servers.<name>] table:

# ~/.codex/config.toml

[mcp_servers.sekura-design]
command = "docker"
args = ["run", "-i", "--rm", "-e", "SEKURA_MCP_TRANSPORT=stdio", "sekura-design-mcp:3.2.2"]

# The first call builds a 5,900-line overview, so allow a little headroom.
startup_timeout_sec = 30
tool_timeout_sec = 60

Without Docker, point it at the built server directly:

[mcp_servers.sekura-design]
command = "node"
args = ["/absolute/path/to/SekuraDesignMCP/dist/index.js"]

Recent Codex versions can add it for you:

codex mcp add sekura-design -- docker run -i --rm \
  -e SEKURA_MCP_TRANSPORT=stdio sekura-design-mcp:3.2.2

codex mcp list          # confirm it registered

Then just ask for work in design-system terms — Codex will call the tools:

> Build a settings page using the Sekura design system. Check the dark mode
> foundation before you write any CSS, and validate the markup when you're done.

Note on transport. stdio is the broadly supported path and is what the examples above use. Codex's support for remote url-based MCP servers is newer and has moved between releases — check codex mcp --help for your version before relying on the HTTP endpoint. Everything the server exposes is available over stdio, so nothing is lost.

Getting good results. The server's instructions already tell a client where to start, but these help:

  • Ask it to call get_overview first on a new task.

  • For anything visual, get_foundation({ id: "dark-mode" }) before writing CSS prevents the nine most common dark-mode defects.

  • Ask it to finish with validate_markup — the linter catches missing accessible names and hard-coded colours that a model will otherwise leave behind.

stdio (client spawns the container)

{
  "mcpServers": {
    "sekura-design": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "SEKURA_MCP_TRANSPORT=stdio",
               "sekura-design-mcp:3.2.2"]
    }
  }
}

stdio (local install)

{
  "mcpServers": {
    "sekura-design": {
      "command": "node",
      "args": ["/absolute/path/to/SekuraDesignMCP/dist/index.js"]
    }
  }
}

Tools

Tool

Returns

get_overview

Start here. The map of everything, with the call needed to fetch each part.

search

Full-text search across components, foundations, patterns, layouts, tokens, behavior APIs and migration changes.

get_foundation

The reasoning: colour, dark mode, responsive layout, accessibility, typography, motion, i18n, theming…

list_components

The catalogue, filterable by category and maturity.

get_component

Full spec: anatomy, variants, sizes, states, props, tokens, dark-mode behaviour, complete accessibility contract, do/don't.

get_behavior

Runtime declarations, events, initialization, cleanup and application ownership.

get_migration_guide

Upgrade paths from v2 and v3.0, behavior changes, source-specific compatibility baselines and the optional v2 geometry bridge.

get_component_code

Paste-ready code in html, css, react, vue, svelte, angular, blazor or web-component.

get_layout

A complete page blueprint with markup and CSS.

get_pattern

A recurring UX problem, its solution, and the anti-patterns.

get_tokens

Resolved token values, showing all four themes side by side.

export_tokens

CSS, SCSS, W3C DTCG, Tailwind v3/v4, JS, TS, Swift, Android XML, Figma.

get_primitives

The raw colour ramps behind the semantic layer.

suggest_token

Describe an intent in words, get the right token with values per theme and why.

check_contrast

WCAG verdict for any pair — accepts hex or token names, resolves per theme, composites translucency.

audit_theme

Every declared pairing across every theme. The build gate.

validate_markup

Lints HTML/CSS for the failures that actually ship.

get_setup

HTML scaffold, pre-paint theme script, reset, utilities, prose, theme control.

get_stylesheet

The entire stylesheet as one file.

get_asset_urls

Published CSS, behavior and documentation artifact URLs.

validate_integration

Validate dependencies, initialization, markup references and declared action handlers.

Resources

sekura://tokens/css · sekura://tokens/dtcg · sekura://foundations/principles · sekura://foundations/dark-mode · sekura://components · sekura://behaviors · sekura://migration/v2-to-v3

Prompts

build-page · review-ui · implement-dark-mode


HTTP endpoints

Beyond MCP, the container serves plain HTTP so a build step can consume tokens without speaking the protocol:

Endpoint

Purpose

POST /mcp

MCP streamable HTTP endpoint

GET /health

Health check — re-runs the contrast audit, so a container serving a broken palette reports unhealthy

GET /tokens.css

CSS custom properties, all themes and densities

GET /tokens.json

W3C Design Tokens JSON


What makes this specification unusual

Dark mode is specified, not derived. Every component documents what changes in dark mode and why. The system encodes the rules most implementations get wrong: floating surfaces get lighter as they rise while recessed surfaces get darker; saturated fills step up the ramp so their labels flip to dark; borders go darker on dark, not lighter; and elevation is two tokens because a drop shadow is nearly invisible against a dark page.

get_foundation({ id: "dark-mode" }) lists the nine failures that pass a design review and break in production — the unstyleable Chrome autofill background, SVG chevrons baked into data URIs, WebKit's search clear button, scrims that are too weak on dark, and so on.

The contrast contract is machine-verified. 86 declared pairings × 4 themes = 344 checks, run on every build and by the container's health check. Two neutral steps are pinned by contrast rather than by eye: neutral-400 is the lightest grey clearing 3:1 on white, and neutral-500 the lightest clearing 4.5:1 on the subtle surface. Moving either lighter breaks a promise, and the audit catches it.

Sekura exceeds WCAG in three places where products commonly fail: placeholder text and tertiary text are both held to full body contrast, and switch and progress tracks are treated as meaningful graphics rather than decoration.

Layout is flex-first. Composition primitives wrap rather than overflow, children declare flex explicitly, text-bearing flex children set min-inline-size: 0, and widths are flex-basis (an ideal) rather than width (a demand). Most layouts therefore respond to their container and need no media query — including the two-column sidebar-layout, which stacks purely through flex wrapping.


Example session

> get_overview
  → the full map

> get_foundation({ id: "dark-mode" })
  → the nine silent failures, the elevation inversion, theme-switching rules

> get_layout({ id: "list-page" })
  → regions, responsive strategy, a11y obligations, markup + CSS

> get_component({ id: "table" })
  → 6 variants, 6 states, full keyboard model, and why row separators
    go DARKER in dark mode

> get_component_code({ id: "table", framework: "react" })
  → typed component forwarding the required ARIA attributes

> suggest_token({ intent: "border around a card in dark mode" })
  → --sk-color-border-default, values per theme, and why

> check_contrast({ foreground: "#8590a3", background: "#ffffff", use: "ui-component" })
  → 3.22:1 — AA pass for control boundaries

> validate_markup({ markup: "<button><svg/></button>" })
  → ❌ button-accessible-name, with the fix and the WCAG criterion

> audit_theme
  → 344/344 pairings satisfied across all four themes

CI and releases

Two workflows in .github/workflows/.

ci.yml runs on every push and pull request. Each step is a gate that exits non-zero, so a change that breaks a promise cannot merge green:

Gate

Checks

check:version

No version literal has drifted from package.json

check:deps

No pre-release dependencies; every Node reference an LTS line

check:env

.env.example documents every setting, and only real ones

audit:contrast

344 checks — 86 declared pairings across four themes

lint:css

Structure, tokens only, no physical properties

smoke

Every MCP tool, component, framework and export format

test:color

Colour maths against WCAG reference values

test:urls

Path prefixes and proxy headers resolve to reachable URLs

test:reliability:server

Bounded validation, composited contrast, exact token exports, HTTP boundaries, cache refresh and artifact health

test:reliability:inputs

Locale drafts, shared date validation, keyboard suggestions, nested cleanup and focused toast queue

test:reliability:product

Storage failure, filtered contents, dedicated Workspace and component preview behavior

test:reliability:form

Conflict comparison, uncertain save outcomes and explicit recovery without draft loss

test:consumers

Packed ESM/CJS, strict declarations, real Angular SSR/hydration and Blazor Server cleanup

test:release-policy

Existing-tag resolution and verified-artifact release invariants

test:codegen

React, Angular and Web Component typechecks; Vue/Svelte compilation; Angular templates

test:blazor

All generated Razor components compile with .NET 10

test:design

Example workflows, control alignment, generated React mounts, lifecycle and mobile geometry

test:completion

Advanced components, async cleanup, RTL accents and narrow layouts in three browsers

test:behaviours

Real key presses in a browser: focus, ARIA, Escape, inert

site:publish

Static bundle is portable — nothing root-absolute

test:errors

Every failing tool call is marked, coded and actionable

test:announce

Accessible names exist and are distinct within a region

test:rtl

Nothing clipped in either direction, at four widths, including 320px, across 14 pages

verify:sample

Dangling references, broken links, markup lint

test:a11y

axe-core, WCAG 2.2 AA, both themes

Docker

Image builds, /health re-runs the contrast audit inside it

release.yml runs on a v* tag and publishes artifacts.

The 3.2.2 source patch already sets the release version. Commit and push the reviewed source on main first. When ready to publish that committed version, tag it without running another version bump:

sekura_release_version=$(node -p "require('./package.json').version")
git tag -a "v${sekura_release_version}" -m "Sekura ${sekura_release_version}"
git push origin "v${sekura_release_version}"

The workflow refuses to release if the tag disagrees with package.json — otherwise you ship artifacts labelled one version and containing another. It then runs the full gate chain again (a release cannot skip checks) and publishes:

Artifact

Use

sekura-<v>.css

The whole stylesheet, one file

tokens-<v>.css

Custom properties only, all themes and densities

tokens-<v>.dtcg.json

W3C Design Tokens format

sekura-behaviours-<v>.iife.min.js

Drop-in <script>, global Sekura

sekura-behaviours-<v>.esm.min.js

ES module for bundlers

sekura-css-<v>.zip

Per-component CSS, Tailwind, Swift, Android

sekura-docs-<v>.zip

The documentation site, hostable anywhere

SHA256SUMS.txt

Checksums

Stable releases also publish a multi-arch image to GHCR, tagged 1.2.3, 1.2, 1 and latest. Alpha releases use their exact version tag and do not update latest. After publishing the release:

docker run -d -p 8080:8080 ghcr.io/mictsi/sekuradesignmcp:3.2.2

Releases package the documentation as a downloadable archive and serve it in the container. The release workflow does not deploy to GitHub Pages.

For an existing release whose tagged workflow still contains the removed Pages job, start Actions → Release → Run workflow, select main, and enter the existing tag (for example v3.2.2). This uses the current workflow while resolving and verifying the original tagged source. Re-running the old tag-triggered run uses its original workflow and retains the blocked Pages job.

Versioning

package.json is the single source of truth. The server, docs site, behaviours bundle and container tag all derive from it — check:version fails the build if a literal creeps back in.

A major bump is required for anything that breaks consumers silently: renaming a semantic token or component class, changing a keyboard contract, removing an MCP tool, or changing the focus ring or spacing scale. Changing a primitive value is a minor bump, because the semantic layer absorbs it and the contrast audit proves nothing regressed. See CHANGELOG.md.


Development

npm run verify          # full checks; Node/npm, Chromium, Firefox, WebKit and .NET 10 SDK required
npm run build           # compile
npm run check:version   # no version literal has drifted
npm run check:deps      # dependency policy: stable releases, Node LTS only
npm run check:env       # .env.example matches what the code actually reads
npm run test:color      # colour maths vs WCAG reference values
npm run test:urls       # URL generation under prefixes and reverse proxies
npm run audit:contrast  # 344 contrast checks — build gate
npm run lint:css        # structural CSS lint over all 83 emitted stylesheets
npm run smoke           # checks every tool, component and export
npm run emit:css        # write dist-css/ and the dependency/event manifest
npm run site:build      # regenerate the 107-page documentation site
npm run verify:sample   # lint every page against the design system itself

lint:css exists because component CSS is a string as far as the TypeScript compiler is concerned. It checks for unbalanced braces, selectors running into at-rules, hard-coded colours, unknown tokens and physical properties — it was added after building the sample surfaced an invalid selector in the dialog stylesheet that had shipped unnoticed.

npm run emit:css produces standalone artefacts for consuming Sekura as plain files: sekura.css (everything), tokens.css, tokens.dtcg.json, tailwind.config.js, SekuraColor.swift, android-resources.xml, tokens.figma.json, per-component CSS, and component-manifest.json with dependency and behavior metadata.

Layout

src/
├── index.ts              entry, transport selection
├── server.ts             MCP server: design, runtime and migration tools, resources and prompts
├── http.ts               streamable HTTP transport, health, plain-HTTP token endpoints
├── site/                 documentation site generator
│   ├── shell.ts          page shell, navigation, reusable doc blocks
│   └── pages.ts          every page, built from the data below
├── data/
│   ├── primitives.ts     ramps, scales, type scale, elevation, motion, breakpoints
│   ├── semantic.ts       120 tokens × 4 themes + the contrast contract
│   ├── tokens.ts         resolution and audit
│   ├── base-css.ts       reset, utilities, prose, theme runtime
│   ├── foundations.ts    15 foundation documents
│   ├── layouts.ts        9 page recipes
│   ├── patterns.ts       15 UX patterns
│   └── components/       67 component specifications
└── lib/
    ├── color.ts          WCAG luminance, contrast, compositing
    ├── exporters.ts      11 output formats
    ├── codegen.ts        8 target frameworks
    ├── validate.ts       markup linting
    ├── markdown.ts       minimal renderer for the foundation documents
    ├── suggest.ts        intent → token
    └── search.ts         weighted full-text search

Settings

Every setting, with what it does and when you would change it, is documented in .env.example — including the path variables this section used to omit. See Configuration for how to use the file.

A second list here would drift from that one, which is the failure npm run check:env exists to prevent.


Notes

The HTTP server is stateless — a fresh server per request, no sessions to lose. The design system is read-only at runtime, so the container runs unprivileged with a read-only filesystem and all capabilities dropped.

Supported runtimes

Node 22 (Jod) and 24 (Krypton) — the two Node LTS lines currently in support. The container builds on 24; CI runs every gate on both, so engines: >=22 is a verified claim rather than an aspiration.

Node 25 did not become LTS, and Node 26 is still Current on 2 October 2026. npm run check:deps enforces the currently supported LTS window. The window must be reviewed as Node's release policy changes with version 27.

What the build actually needs

The container build needs Docker and nothing else. The Dockerfile installs its own dependencies, compiles inside the image, and runs its own gates there, so the host toolchain is never involved:

./run.sh build --image      # or plain: docker build -t sekura-design-mcp .

The source-build path is self-contained. For 3.2.2, local checks cover the Docker/release policy and the HTTP readiness contract; an actual image build, container probe and live workflow run remain release acceptance steps.

Plain ./run.sh build does more than that: it also compiles and verifies on the host before building the image, which is why it wants TypeScript and Playwright. The script installs the revisions locked by playwright-core for behavior, RTL, cross-browser and design-kit checks. These steps are skippable:

Command

Needs

./run.sh build --image

Docker

./run.sh build --no-browser

Node and npm; Docker when available

./run.sh build

Node, npm, Docker when available, and browser downloads

--no-browser skips the browser tests and CSS capture for the Figma kit. The React package, stylesheets and documentation still build. The full build reinstalls dependencies if they differ from package-lock.json, avoiding stale local packages after Dependabot updates.

The full build installs Chromium, Firefox and WebKit through the locked Playwright CLI. To install them separately, run node node_modules/playwright-core/cli.js install chromium firefox webkit.

Configuration

Every container setting lives in one file.

cp .env.example .env      # then edit .env, which is gitignored

docker compose up, ./run.sh start and docker run --env-file .env all read it, so there is a single place to look when a deployment misbehaves. Anything already exported wins, so SEKURA_PORT=9000 ./run.sh start still works for a one-off.

npm run check:env fails the build if the code reads a setting .env.example does not document, or documents one nothing reads — a setting someone will set, restart for, and watch do nothing is worse than an undocumented one. It also rejects quoted values, because docker run --env-file keeps the quotes as part of the value while Compose strips them.

Publishing under a path

The MCP endpoint, the health check and the documentation site are served from one port under one path prefix. There is no second port and no second server:

http://host:8080/<app_path>/mcp        MCP, POST
http://host:8080/<app_path>/health     health
http://host:8080/<app_path>/docs/      documentation site

The image serves at the root by default. To publish it under a path on an existing web server — https://example.com/design-system/ — you need to know which of two things your proxy does, because they need different settings.

Variable

Answers

SEKURA_BASE_PATH

Where does this process listen?

SEKURA_EXTERNAL_URL

What does the outside world see?

They are equal in the simple case and different in the common one, which is why they are two variables rather than one.

If the proxy passes the prefix through, the app has to answer on /design-system/health:

location /design-system/ {
    proxy_pass http://app:8080/design-system/;   # prefix kept
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}
docker run -d -p 127.0.0.1:8080:8080 \
  -e SEKURA_BASE_PATH=/design-system \
  -e SEKURA_EXTERNAL_URL=https://example.com/design-system \
  sekura-design-mcp:3.2.2

If the proxy strips the prefix, the app still listens at the root but has no way to discover what was removed, so it must be told:

location /design-system/ {
    proxy_pass http://app:8080/;                 # prefix stripped
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}
docker run -d -p 8080:8080 \
  -e SEKURA_EXTERNAL_URL=https://example.com/design-system \
  sekura-design-mcp:3.2.2

With Traefik or ingress-nginx, pin SEKURA_EXTERNAL_URL when the public URL is known. Forwarded headers are honored only from peers explicitly listed in SEKURA_TRUST_PROXY; the default is false, and legacy true means loopback only. The edge must overwrite each forwarded header with a single value.

Host validation applies to the incoming Host and any trusted forwarded host. Loopback hosts and the external URL's host are included automatically; add other intended authorities to SEKURA_ALLOWED_HOSTS. Browser requests must use the resolved server origin or an explicit SEKURA_ALLOWED_ORIGINS entry. Missing Origin is allowed for non-browser clients. These checks do not add authentication or CORS. See .env.example and the HTTP upgrade section for exact values.

Check binding and built artifacts

Inspect /health for contrast and artifact status. Missing sekura.css or sekura.iife.min.js now produces a 503; build or copy matching artifacts before starting the service. Documentation availability is reported separately.

If the container is healthy but unreachable, inspect HOST. A published port forwards to the container's external interface; HOST=127.0.0.1 binds the container's own loopback instead, so nothing on the host can connect — while the container's health check, probing from inside, passes and Docker reports it healthy.

./run.sh start now names this when it happens, and the server warns at startup. To restrict access, leave HOST=0.0.0.0 and narrow the mapping instead: -p 127.0.0.1:8080:8080.

Ports

Two, and only two:

SEKURA_PORT

Published port — what the outside world connects to

PORT

Internal port — what the server listens on in the container

They meet at the port mapping (-p ${SEKURA_PORT}:8080). Change the published one; leave the internal one alone, or the healthcheck, the EXPOSE and the mapping have to be kept in step by hand.

What gets published

Every path below is relative to the mount point. There is no route outside it — not even a redirect from /. A deployment reachable at two addresses is one where a link, a bookmark or a proxy rule eventually points at the wrong one.

Path

What

/mcp

MCP endpoint (POST). Rename with SEKURA_MCP_PATH

/health

Required artifact availability and the declared contrast audit; 503 if degraded

/manifest.json

Every URL above and below, as JSON

/tokens.css

Custom properties, all themes and densities

/tokens.json

W3C DTCG format

/css/sekura.css

The complete stylesheet; /css/ also has per-component files

/js/sekura.iife.min.js

Behaviours, drop-in <script>; .esm.min.js alongside

/docs/

The 107-page documentation site

Do not assemble those paths by hand from a base you assume. Fetch /manifest.json, or call the get_endpoints MCP tool — only the server knows what prefix it is actually reachable on, and both report the real URLs including anything a proxy rewrote.

curl -s https://example.com/design-system/manifest.json | jq .artefacts.stylesheet.url
# "https://example.com/design-system/css/sekura.css"

The documentation site uses relative links throughout, so it is portable to any prefix with no rebuild.

Errors, for a model rather than a developer

The caller of an MCP server is a language model. That changes what a good error is: a model that receives "Unknown component" in a success envelope has no signal anything went wrong, and will carry on and invent the component.

Every failure from this server is marked isError, and carries:

Field

Why

code

UNKNOWN_COMPONENT — branchable without parsing English

hint

One of RETRY_LATER, CHECK_INPUT, TRY_ALTERNATIVE, REPORT_TO_USER

Closest matches

Ranked by edit distance, never the whole namespace

retryable

So a model does not retry something that cannot succeed

traceId

So a bug report can name one specific response

ERROR UNKNOWN_COMPONENT

No component with that id.

Received: "datepicker"

Closest matches:
  - date-picker
  - date-range-picker

Next:
  - Call `list_components` for the full list.

Recovery hint: TRY_ALTERNATIVE
Retryable: no — the same call will fail again. Change the arguments first.
This is an error, not content. Do not include it in generated output.

An empty result is not an error, and says so explicitly with count: 0. A model cannot otherwise tell "there genuinely are none" from "something broke and returned a default", and the second is a false claim of safety.

npm run test:errors enforces all of this — 94 checks.

Publishing the documentation as a static site

npm run site:publish        # -> dist-site/

dist-site/ is self-contained: 107 pages, the assets, and a 404 page. Upload it anywhere. Every reference in it is relative, so the same bundle serves from a domain root or any subdirectory with no rebuild:

dist-site/  ->  https://example.com/
            ->  https://example.com/design-system/

The command is a gate, not just a copy. It refuses to produce a bundle containing a root-absolute href or src, because that is the failure that works locally, works at a domain root, and 404s under a subdirectory — which is where most bundles end up.

The running container serves the same site at <app_path>/docs/, so publishing statically is an alternative to it rather than a prerequisite.

Licence

MIT — see LICENSE.

Contributing: CONTRIBUTING.md · Security: SECURITY.md · Changes: CHANGELOG.md

Review follow-ups

  • npm run build:react: builds the versioned local @sekura/react package with Button, TextField, Textarea, Select, Checkbox and Switch. See the API contract.

  • npm run build:design-kit: derives six Figma component sets (216 theme/density/state variants) from emitted CSS. See import instructions and coverage. It is a starter library requiring visual review in Figma before publication.

  • npm run demo:server: serves the form-composition lab at http://127.0.0.1:4173/form-lab.html, with same-origin HTTP validation, save and version-conflict endpoints. Data lives in memory. These endpoints are not mounted by the MCP server.

  • npm run test:browsers: exercises native React controls, HTTP workflows, cancellation, permission changes, keyboard overlays, RTL and enlarged text in Chromium, Firefox and WebKit.

  • get_component_code retains readable text and adds an output schema and structuredContent. Recipes include stylesheet dependencies, initialization instructions, native React export availability and public event payloads.

  • validate_integration checks selected components, markup, loaded CSS, SVG symbols, target IDs, initialization and declared application handlers together. Warnings about undeclared handlers do not execute or prove callback behavior.

Example MCP integration validation:

{
  "componentIds": ["button"],
  "markup": "<button type=\"button\" class=\"sk-button\">Save</button>",
  "stylesheets": ["sekura.css"],
  "initialization": "auto",
  "handledEvents": ["button:click"]
}

Run npm run test:integration for structured MCP contracts and npm run test:request for HTTP error/abort/timeout handling. Actual screen-reader, OS contrast, physical touch and Figma acceptance procedures are recorded in MANUAL-VALIDATION.md; they have not been performed by a human tester.

Runtime and migration discovery through MCP

  • get_component({ id }) returns the complete specification as text and structured data. sekura://components contains all 71 stable components.

  • get_component_code({ id, framework }) includes CSS dependencies, primary controller, all runtime factories, automatic selectors, manual-only APIs, events and application responsibilities.

  • get_behavior({ id }) accepts a component ID or any public behavior export name. It returns generated TypeScript declarations with supporting types, initialization and cleanup instructions. Omit id for the complete API catalogue; sekura://behaviors exposes the same catalogue as a resource.

  • get_migration_guide({ componentId, fromVersion }) returns the complete canonical plan and source-specific steps. fromVersion accepts 2.x, 3.0.0, 3.0.x, 3.1.0 or 3.1.x; omitting it preserves the complete legacy response. Public-name baselines cover v2.1, v3.0.0 and v3.1.0. The legacy sekura://migration/v2-to-v3 resource remains available alongside sekura://migration/v3.2, sekura://migration/v3.1-to-v3.2 and sekura://migration/v3.0-to-v3.2. Older v3.1 URIs remain aliases.

  • search supports behavior and migration kinds as well as the existing design records.

The build embeds declarations and migration content in dist/data/mcp-reference.json, so stdio and HTTP installations work without source files or the original working directory. Rebuild after changing behavior APIs or migration documentation. npm run test:mcp checks all component specifications, every recipe format, public APIs and resources through an MCP client.

Dependency policy: maintain the reviewed Node 24 LTS runtime and Angular 21 LTS on their latest patches; use the latest supported stable releases for other packages. See the release dependency record for verified versions and source links. Angular packages validate templates, wrapper code and an actual server-render/hydration fixture; a consuming Angular application must use its own supported Angular/TypeScript toolchain. These checks are not a complete ngc application build. The package version is 3.2.2; component maturity does not mean the manual acceptance record is complete.

Available Tools

21 tools
audit_themeAudit every declared contrast pairingA
Read-only

Runs every contrast promise the design system makes against one theme or all four. This is the build gate — run it after any palette change. A pairing that is not declared here is not promised and must not be used to carry meaning.

Inputs: theme, failuresOnly.

check_contrastCheck a colour pair against WCAGA
Read-only

WCAG 2.2 contrast for the rendered foreground/background pair. Supports hex, transparent, modern rgb() and token names. Composites background over an explicit opaque backdrop, or the disclosed theme base when omitted, then foreground over that background.

Inputs: background (required), foreground (required), use, theme, +1 more.

export_tokensExport tokens in a build formatB
Read-only

Emit tokens in a consumable format. Each format documents its supported scopes, projections and consumer verification obligations; CSS is the complete runtime token artifact.

Inputs: format (required), theme.

get_behaviorGet runtime behavior and lifecycle contractsA
Read-only

Complete public behavior API, including exact TypeScript declarations and supporting types. Filter by component id or exported API name; omit id for the full catalogue. Includes automatic selectors, manual initialization, cleanup, events and application responsibilities.

Inputs: id. Returns: id, api, events, runtime, +5 more

get_componentGet a component specificationA
Read-only

The complete spec for one component: anatomy, variants, sizes, states, props, tokens consumed, dark-mode behaviour, full accessibility contract (role, keyboard model, ARIA obligations, WCAG criteria, target size), content rules, and do/don't guidance.

Inputs: id (required). Returns: version, component, schemaVersion

get_component_codeGet paste-ready component codeA
Read-only

Production code for a component in the requested framework. HTML returns reference markup with the required ARIA wiring; CSS returns the production stylesheet written against semantic tokens; framework options return editable reference recipes with native markup and lifecycle wiring. Inspect implementation metadata for dependencies and application responsibilities.

Inputs: id (required), framework (required). Returns: code, version, framework, componentId, +4 more

get_endpointsWhere the published artefacts liveA
Read-only

Absolute URLs for the stylesheet, token files, behaviours bundle and documentation site served by this instance. Use this instead of assuming paths: the server may be mounted under a path prefix, and only it knows what that prefix is.

Inputs: no named parameters.

get_foundationGet a foundation documentA
Read-only

The reasoning behind the system: principles, colour, dark mode, responsive layout, typography, spacing, elevation, motion, accessibility, content and voice, iconography, density, internationalisation, data visualisation, theming. Read the relevant foundation before implementing in that area.

Inputs: id (required).

get_layoutGet a page layout recipeA
Read-only

A complete page blueprint: regions, responsive strategy, accessibility obligations, dark-mode notes, and paste-ready markup plus CSS. All recipes are flex-first and most contain no media query.

Inputs: id (required).

get_migration_guideGet migration plan and behavior changesA
Read-only

Upgrade to the current release from v2 or v3.0: full canonical plan, source-specific steps, rollout/rollback guidance, behavior changes, compatibility baseline and optional legacy geometry CSS. componentId filters behavior changes; fromVersion selects the upgrade source while preserving the complete guide.

Inputs: componentId, fromVersion. Returns: changes, version, markdown, componentId, +4 more

get_overviewOverview of the design systemA
Read-only

Start here. Returns the map of everything available: foundations, component catalogue, layout recipes, UX patterns, token groups and export formats, with the tool call needed to retrieve each.

Inputs: no named parameters.

get_patternGet a UX patternB
Read-only

A recurring UX problem and the Sekura answer: the problem, the solution, the rules, the accessibility obligations, and the anti-patterns to avoid.

Inputs: id (required).

get_primitivesGet primitive colour rampsA
Read-only

The raw colour ramps behind the semantic layer. Use these to build new semantic tokens or to re-brand. Never reference a primitive from product code — it does not change between themes, so it will not adapt to dark mode.

Inputs: ramp.

get_setupGet the project setupA
Read-only

Everything needed to start: the HTML scaffold, the pre-paint theme script (which must be inline and synchronous, or you get a flash of the wrong theme), the reset, the utility layer, the prose styles, and the theme control markup.

Inputs: part.

get_stylesheetGet the complete stylesheetA
Read-only

The entire Sekura stylesheet as one file: tokens for all four themes and three densities, reset, prose, utilities, and every component. This is the single artefact needed to render any Sekura interface.

Inputs: include.

get_tokensGet token valuesA
Read-only

Resolved token values. Filter by group, by name fragment, or return everything. Shows the value in every theme so dark-mode differences are visible side by side.

Inputs: group, theme, filter, includeScales.

list_componentsList componentsB
Read-only

The component catalogue, optionally filtered by category or status.

Inputs: status, category.

suggest_tokenFind the right token for an intentA
Read-only

Describe what you are styling in plain words and get the semantic tokens that apply, with resolved values per theme and a note on why that token rather than a neighbour. Use this instead of guessing a token name or reaching for a hex value.

Inputs: intent (required), limit.

validate_integrationValidate component integrationB
Read-only

Check component markup, stylesheet dependencies, SVG symbols, ID references, initialization and declared application events. Returns structured findings and fixes; does not execute callbacks.

Inputs: markup (required), stylesheets (required), componentIds (required), initialization (required), +4 more. Returns: valid, version, findings, limitation, +3 more

validate_markupLint markup against the specificationA
Read-only

Checks HTML or CSS for the accessibility and design-system failures that actually ship: missing accessible names, unlabelled inputs, hard-coded colours that break in dark mode, flex containers that will overflow, positive tabindex, removed focus outlines, and misused live regions. Advisory — a clean result is not a certificate of accessibility.

Inputs: markup (required), componentId.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 21 tools

    Disambiguation4/5

    Most tools have clearly distinct targets (catalogue vs single component vs code vs behaviour vs migration). A few clusters need the descriptions to disambiguate: get_tokens/export_tokens/get_primitives/suggest_token all touch tokens, and validate_markup vs validate_integration overlap on validation. The descriptions do a good job of explaining when to use each, so misselection is unlikely but possible.

    Naming Consistency5/5

    Names uniformly follow a snake_case verb_noun pattern (get_component, list_components, validate_markup, export_tokens, audit_theme, suggest_token, check_contrast). The only mild outlier is the bare 'search', which is idiomatic and unambiguous. No mixing of casing or style conventions.

    Tool Count4/5

    21 tools is on the heavy side but maps to a genuinely broad domain: discovery, components, foundations, tokens, code, patterns, layouts, validation, migration and setup. Each tool earns a distinguishable place, though a few token-related ones could conceivably be consolidated.

    Completeness4/5

    Coverage is strong for a read-only design-system surface: overview/discovery, component catalogue and specs, foundations, tokens, code and layout generation, contrast/theme/markup/integration validation, migration and endpoint discovery. Minor gaps like a changelog or version-history tool exist, but core agent workflows have no dead ends.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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.
      24 npm
      1
      Apache 2.0
    • 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to access a governed, versioned design style specification through MCP, including deterministic checks, proposal review workflows, and generated CSS, JSON, and TypeScript artifacts.
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      A design harness for AI coding agents. Better Design gives an agent design systems, UI and UX principles, icons and UI review: it finds or creates a design system that fits the product and installs its components, explains how sign-up, forms and onboarding should work, and reviews finished screens for readability, accessibility and unclear copy.
      48
      568
      MIT