Skip to content
helixui

Why helixui is AI-friendly

Most “AI-friendly” claims for design systems mean a Claude/Cursor skill that wraps the existing system. helixui flips that: the system itself is shaped so an AI does not need a skill to use it correctly.

1. Tokens are JSON, with descriptions

packages/tokens/tokens/*.json is the source. Every token has $value, $type, and $description. The build produces:

  • dist/css/*.css — for browsers.
  • dist/index.d.ts — for TypeScript code editors.
  • dist/manifest.json — for any tool that wants to ask “what tokens exist, what do they mean, what are their values per theme”.
"color.bg.action.brand.default": {
  "value": "#3b82f6",
  "type": "color",
  "description": "Default fill for brand call-to-action.",
  "layer": "semantic",
  "cssVar": "--helixui-color-bg-action-brand-default",
  "themes": { "light": "#3b82f6", "dark": "#60a5fa" }
}

An agent can read the manifest in one fetch, decide which token fits an instruction like “make this button look like a destructive action,” and emit the right CSS variable.

2. Each component is one file you can show an LLM

Every component has a colocated spec.md:

  • The frontmatter is structured: props, slots, tokens, a11y keyboard map, related components.
  • The body is markdown: when to use, anatomy, do/don’t, code examples in fenced blocks.

There is no separate API extractor and no runtime injection of prop tables. A reader (human or AI) sees one file. To document a new component, you write that one file.

3. llms.txt ships with every build

A static /llms.txt (index) and /llms-full.txt (every page concatenated) are written into apps/docs/public/ at build time. PRs show the diff. No special server route, no dynamic generation.