The design system an AI agent can use without guessing.
Explicit per-component contracts, script-verified tokens, and a canonical prop vocabulary — built so humans and agents generate the same consistent UI on the first try.
Everything in this screenshot is Helix: AppShell, SideNav, StatCard, Table, Badge, Switch — zero hand-written layout <div>s.
Helix is a design system built directly on native HTML elements — no primitive kit underneath — plus Tailwind CSS v4 and Tabler Icons. Why, in ADR-001. Every component ships with:
- A contract (
contracts/components/{Name}.json) that defines props, variants, and rules before a single line of implementation exists. - Tokens in DTCG format (
--helix-*), automatically checked against WCAG AA contrast and semantic naming. - Evals: real code-generation prompts run against an LLM, to verify the system itself is interpretable by an agent — not just by a person reading Storybook.
Requires React 19 and Tailwind CSS v4 in your app.
npm install @helixds/react @helixds/tokens @tabler/icons-react/* the CSS file Tailwind processes — replaces @import "tailwindcss"; */
@import "@helixds/react/globals.css";import { Button } from '@helixds/react';
<Button variant="primary" onClick={save}>Save</Button>Dark mode follows the operating system, or set data-theme="dark" / "light" on <html>. The full guide —
setup, dark mode, lint — is docs/getting-started.md; every component is in the
Storybook.
Copy node_modules/@helixds/react/AGENTS.md to your project root, and connect the Helix MCP server so the
agent reads contracts and validates its code instead of guessing props:
{ "mcpServers": { "helix": { "command": "npx", "args": ["-y", "@helixds/mcp"] } } }For the full guardrails (hooks that make the agent read a contract before writing, lint after writing and ask
before patching Helix), run pnpm setup:ai <path-to-your-app> from a clone of this repo. Claude Code, Cursor,
Codex and Gemini CLI are supported — details in AGENTS.md.
git clone https://github.com/MartaCondeDesign/helixds.git
cd helixds
pnpm install
pnpm sb # Storybook → http://localhost:6006Then read CONTRIBUTING.md.
| 🧩 33 components | 29 content components (Button, Input, Select, Badge, Checkbox, Chip, RadioGroup, Switch, Textarea, Card, Avatar, IconButton, Table...) + 4 layout components (AppShell, PageHeader, SideNav, TopBar) |
| 🎨 DTCG tokens | tokens.json → CSS variables + TS constants, with documented, audited exceptions (pnpm docs:token-exceptions) |
📐 No-<div> layout |
Every page composition goes through a layout component — never hand-written display:flex |
| 📄 Contract before code | Every new component starts as a .json in contracts/; Figma is reference only, the contract wins |
| ♿ Verified contrast | Every text/icon-on-fill color pair is checked against WCAG 2.2 AA, in both light and dark |
| 🤖 AI-ready by default | AGENTS.md, llms.txt, contracts, and .ai/maps/ — an agent can generate correct UI without exploring the codebase first |
| ✅ Script-verified, not eyeballed | verify:contract, verify:props, verify:tokens, verify:icons run locally before anything is considered done |
This table is Storybook's Status page (pnpm sb), rendered straight from contracts/manifest.json. Every ✓ is a real check — contract exists, exported, documented, typed, has a story, a11y complete, modeled in Figma — not someone's opinion of "done."
pnpm install
pnpm sb # Storybook → http://localhost:6006
pnpm contract <Name> # scaffold a new component contract
pnpm verify:contract # validate contracts vs implementation
pnpm verify:props # prop names vs .ai/maps/prop-map.md
pnpm verify:tokens # token naming
pnpm verify:icons # every Tabler icon goes through the Icon component
pnpm token:add # add a new token
pnpm docs:manifest # regenerate contracts/manifest.json
pnpm docs:changelog # regenerate the changelog shown in Storybook
pnpm eval:run # LLM code-generation evalspackages/tokens— DTCG tokens compiled to CSS and TS. ADR-002packages/core— the 33 React components.packages/storybook-addon-tokens— Storybook addon for inspecting tokens.apps/storybook— stories per component and per pattern.contracts/— one.jsonper component;manifest.jsonis the generated index of all of them..ai/— prop vocabulary, design patterns, and skills for agents (Figma, tokens, icons).docs/ADR/— architecture decisions.evals/— prompts and outputs from automated evaluation.llms.txt— index for an LLM to load system context quickly.
- Never
<div>for layout — use the components inpackages/core/src/layout/. - Never render a Tabler icon directly — always go through the
Iconcomponent. - Color and border-radius: always a
--helix-*token, no exceptions. - New UI with no native HTML equivalent → needs an ADR before implementation.
- Canonical prop vocabulary lives in
.ai/maps/prop-map.md; synonyms aren't allowed. - New component → contract first, at
contracts/components/{Name}.json, then the code.
Full detail in CLAUDE.md.
Issues and pull requests are welcome — start with CONTRIBUTING.md (proposals for tokens and components go through an issue first). Agents working on Helix itself read contributor-ai/CONTRIBUTOR.md. Everyone follows the Code of Conduct.
Found a vulnerability? Please don't open a public issue — see SECURITY.md for how to report it privately.
If Helix is useful to you, a ⭐ on the repo helps other people find it. Questions and ideas are welcome in Discussions; bugs go in Issues.
MIT — see LICENSE for details.
Built by Marta Conde — LinkedIn · YouTube · martaconde.com
