Skip to content
helixui

The two contracts

helixui only has two hard contracts. Every other convention is negotiable; these aren’t.

1. Tokens are JSON, not code

The canonical token source is W3C DTCG JSON at packages/tokens/tokens/*.json. CSS variables and TypeScript types are build outputs, not the source of truth.

If you’re adding a token:

  1. Edit the relevant DTCG JSON file (color.json, space.json, …).
  2. Run pnpm build:tokens.
  3. Commit the JSON edit only. Generated CSS/TS is rebuilt by CI.

If you find yourself editing a generated file directly, stop — you’re fighting the system. Find the upstream JSON instead.

Why JSON

DTCG JSON is parseable by any tool — Figma plugins, Style Dictionary, your own scripts. helixui’s CSS and TypeScript outputs are just one consumer. The Figma sync showcase round-trips the same JSON.

2. Every component owns a spec.md

Each component file (packages/core/src/components/<name>/<Name>.tsx) has a sibling spec.md. Its frontmatter is a machine-readable spec; its body is the human-readable doc.

---
title: Button
import: "import { Button } from '@helixui/core'"
description: "A primary action element."
props:
  - { name: variant, type: '"solid" | "soft" | "ghost" | "outline"', default: '"solid"' }
  - { name: tone,    type: '"brand" | "neutral" | "danger"', default: '"brand"' }
tokens:
  - color.bg.action.brand.default
  - radius.md
a11y:
  - inherits all <button> semantics
  - requires aria-label when icon-only
---


## Anatomy
...

If you’re adding or changing a component:

  • Update spec.md in the same commit as the code change.
  • Keep props, tokens, and a11y accurate — the docs site, the LLM manifest, and the MCP server all consume this file.

Why spec.md

Three different consumers read these files:

  • The Astro docs site (this site) renders them as content pages.
  • pnpm build:llms flattens them into llms-full.txt for AI ingestion.
  • The @helixui/mcp server exposes them as MCP resources for Claude Code, Cursor, etc.

A new component without a spec is invisible to two of those three.

Where the contracts are checked

  • pnpm typecheck — catches missing props.
  • pnpm build:llms — fails if a component is exported without a spec.
  • CI runs both on every PR.