Sekura Design MCP
This MCP server provides read-only access to the Sekura Design System for discovery, implementation, token export, validation, and upgrade guidance.
Discover design-system content with overview, search, foundations, components, layouts, UX patterns, tokens and primitive ramps.
Retrieve complete component specs and runtime behavior contracts, including lifecycle, events, cleanup and application responsibilities.
Generate paste-ready implementation assets: component code in HTML/CSS/React/Vue/Svelte/Angular/Blazor/Web Components, layout recipes, setup scaffold/theme script/reset/utilities, and the full stylesheet.
Work with design tokens: inspect values across four themes, suggest tokens from intent, and export to CSS, SCSS, DTCG, Tailwind v3/v4, JS, TS, Swift, Android, Figma or JSON.
Validate work with WCAG contrast checks, full theme contrast audits, markup linting, and integration validation for markup, stylesheets, IDs, controllers and declared events.
Plan upgrades with migration guides from v2/v3.0/v3.1, behavior changes, compatibility baselines and rollback/rollout details.
Discover absolute artifact URLs for the stylesheet, token files, behaviors bundle and docs via the server.
Exports design tokens as Android XML resources for use in Android applications.
Generates Angular component code from the design system's specifications, including accessibility contract and tokens.
Generates Blazor component code from the design system's specifications, including accessibility contract and tokens.
Provides the complete design system stylesheet and design token values as CSS custom properties.
Exports design tokens to Figma for use in design workflows.
Generates React component code from the design system's specifications, including accessibility contract and tokens.
Generates Svelte component code from the design system's specifications, including accessibility contract and tokens.
Exports design tokens to Swift for use in Apple platform applications.
Exports design tokens as TypeScript definitions for use in TypeScript projects.
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., "@Sekura Design MCP What are the semantic color tokens for dark mode?"
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.
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.jsonThe 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-buildBuilds 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 helpThe 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.
| 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 |
| The elevation inversion, demonstrated with the same markup under both themes side by side — plus the nine things that break silently |
| Flex-first, with resizable demos that reflow on container width |
| Filterable reference for every token |
| 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 (recommended)
docker compose up -d
curl http://localhost:8080/healthOr without compose:
docker build -t sekura-design-mcp .
docker run -d -p 8080:8080 --name sekura sekura-design-mcpThe 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:8080Connecting 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/mcpOpenAI 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 = 60Without 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 registeredThen 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_overviewfirst 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 |
| Start here. The map of everything, with the call needed to fetch each part. |
| Full-text search across components, foundations, patterns, layouts, tokens, behavior APIs and migration changes. |
| The reasoning: colour, dark mode, responsive layout, accessibility, typography, motion, i18n, theming… |
| The catalogue, filterable by category and maturity. |
| Full spec: anatomy, variants, sizes, states, props, tokens, dark-mode behaviour, complete accessibility contract, do/don't. |
| Runtime declarations, events, initialization, cleanup and application ownership. |
| Upgrade paths from v2 and v3.0, behavior changes, source-specific compatibility baselines and the optional v2 geometry bridge. |
| Paste-ready code in |
| A complete page blueprint with markup and CSS. |
| A recurring UX problem, its solution, and the anti-patterns. |
| Resolved token values, showing all four themes side by side. |
| CSS, SCSS, W3C DTCG, Tailwind v3/v4, JS, TS, Swift, Android XML, Figma. |
| The raw colour ramps behind the semantic layer. |
| Describe an intent in words, get the right token with values per theme and why. |
| WCAG verdict for any pair — accepts hex or token names, resolves per theme, composites translucency. |
| Every declared pairing across every theme. The build gate. |
| Lints HTML/CSS for the failures that actually ship. |
| HTML scaffold, pre-paint theme script, reset, utilities, prose, theme control. |
| The entire stylesheet as one file. |
| Published CSS, behavior and documentation artifact URLs. |
| 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 |
| MCP streamable HTTP endpoint |
| Health check — re-runs the contrast audit, so a container serving a broken palette reports unhealthy |
| CSS custom properties, all themes and densities |
| 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 themesCI 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 |
| No version literal has drifted from |
| No pre-release dependencies; every Node reference an LTS line |
|
|
| 344 checks — 86 declared pairings across four themes |
| Structure, tokens only, no physical properties |
| Every MCP tool, component, framework and export format |
| Colour maths against WCAG reference values |
| Path prefixes and proxy headers resolve to reachable URLs |
| Bounded validation, composited contrast, exact token exports, HTTP boundaries, cache refresh and artifact health |
| Locale drafts, shared date validation, keyboard suggestions, nested cleanup and focused toast queue |
| Storage failure, filtered contents, dedicated Workspace and component preview behavior |
| Conflict comparison, uncertain save outcomes and explicit recovery without draft loss |
| Packed ESM/CJS, strict declarations, real Angular SSR/hydration and Blazor Server cleanup |
| Existing-tag resolution and verified-artifact release invariants |
| React, Angular and Web Component typechecks; Vue/Svelte compilation; Angular templates |
| All generated Razor components compile with .NET 10 |
| Example workflows, control alignment, generated React mounts, lifecycle and mobile geometry |
| Advanced components, async cleanup, RTL accents and narrow layouts in three browsers |
| Real key presses in a browser: focus, ARIA, Escape, inert |
| Static bundle is portable — nothing root-absolute |
| Every failing tool call is marked, coded and actionable |
| Accessible names exist and are distinct within a region |
| Nothing clipped in either direction, at four widths, including 320px, across 14 pages |
| Dangling references, broken links, markup lint |
| axe-core, WCAG 2.2 AA, both themes |
Docker | Image builds, |
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 |
| The whole stylesheet, one file |
| Custom properties only, all themes and densities |
| W3C Design Tokens format |
| Drop-in |
| ES module for bundlers |
| Per-component CSS, Tailwind, Swift, Android |
| The documentation site, hostable anywhere |
| 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.2Releases 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 itselflint: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 searchSettings
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 |
| Docker |
| Node and npm; Docker when available |
| 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 gitignoreddocker 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 siteThe 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 |
| Where does this process listen? |
| 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.2If 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.2With 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:
| Published port — what the outside world connects to |
| 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 endpoint (POST). Rename with |
| Required artifact availability and the declared contrast audit; 503 if degraded |
| Every URL above and below, as JSON |
| Custom properties, all themes and densities |
| W3C DTCG format |
| The complete stylesheet; |
| Behaviours, drop-in |
| 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 |
|
|
| One of |
Closest matches | Ranked by edit distance, never the whole namespace |
| So a model does not retry something that cannot succeed |
| 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/reactpackage 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 athttp://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_coderetains readable text and adds an output schema andstructuredContent. Recipes include stylesheet dependencies, initialization instructions, native React export availability and public event payloads.validate_integrationchecks 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://componentscontains 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. Omitidfor the complete API catalogue;sekura://behaviorsexposes the same catalogue as a resource.get_migration_guide({ componentId, fromVersion })returns the complete canonical plan and source-specific steps.fromVersionaccepts2.x,3.0.0,3.0.x,3.1.0or3.1.x; omitting it preserves the complete legacy response. Public-name baselines cover v2.1, v3.0.0 and v3.1.0. The legacysekura://migration/v2-to-v3resource remains available alongsidesekura://migration/v3.2,sekura://migration/v3.1-to-v3.2andsekura://migration/v3.0-to-v3.2. Older v3.1 URIs remain aliases.searchsupportsbehaviorandmigrationkinds 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 toolsaudit_themeAudit every declared contrast pairingARead-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 WCAGARead-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 formatBRead-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 contractsARead-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 specificationARead-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 codeARead-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 liveARead-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 documentARead-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 recipeARead-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 changesARead-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 systemARead-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 patternBRead-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 rampsARead-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 setupARead-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 stylesheetARead-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 valuesARead-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 componentsBRead-only
The component catalogue, optionally filtered by category or status.
Inputs: status, category.
searchSearch the design systemARead-only
Full-text search across components, foundations, patterns, layouts, tokens, runtime APIs and migration changes. Use when you know what you need but not where it lives.
Inputs: query (required), kinds, limit.
suggest_tokenFind the right token for an intentARead-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 integrationBRead-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 specificationARead-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
Scored across 21 tools
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.
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.
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.
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
Related MCP Connectors
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Serves your design system and coding standards to coding agents, so they stop guessing.
Accessible React components, tokens, usage guidance, and install commands for product interfaces.
Design system for agents: find components by need, check code against the real API, build themes.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA read-only MCP server that provides AI coding agents with a queryable contract for design system tokens, components, patterns, and anti-patterns.24 npm1Apache 2.0
- AlicenseAqualityCmaintenanceRead-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.83 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseAqualityCmaintenanceA 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.48568MIT