Repo layout

helixui is a pnpm + turbo monorepo. Source of truth lives in packages/; showcases and documentation live in apps/.

packages/
  tokens/      DTCG JSON tokens + transformer (the canonical source).
  core/        React components — each owns a sibling spec.md.
  dna/         The genome model (themes, alleles, breeding).
  icons/       265+ stroke-consistent SVG icons (outline + filled).
  slides/      PPTX exporter that shares helixui tokens.
  document/    DOCX exporter that shares helixui tokens.
  prompt/      Compact UI prompt DSL.
  mcp/         Model Context Protocol server.
apps/
  site/        Marketing + showcase site (helixui.ai).
  docs/        Astro Starlight docs site (this site).
  demo/        Sandbox app used while developing new components.
scripts/       Build pipelines (llms.txt, search index, OG images, …).

Per-package conventions

Package	Source of truth	Build output	Notes
@helixui/tokens	tokens/*.json (DTCG)	CSS vars + TS types	Run pnpm build:tokens after editing.
@helixui/core	src/components/<name>/<Name>.tsx + spec.md	Ships TS source	Each component has a spec next to it.
@helixui/dna	src/*.ts	Ships TS source	The CLI lives in bin/dna.mjs.
@helixui/icons	src/outline.tsx, src/filled.tsx	Tree-shakable named exports	Authored as SVGR-style React.
@helixui/slides	src/components/*.tsx	Ships TS source	pptxgenjs loaded lazily on export.
@helixui/document	src/components/*.tsx	Ships TS source	docx loaded lazily on export.
@helixui/prompt	src/*.js	Ships JS source	Used by the MCP server.
@helixui/mcp	src/server.js	Ships JS source	Dependency-free stdio MCP server.

What’s not in packages/

• App-level state. showcases live under apps/site/src/pages/showcase/, not in @helixui/core.
• Marketing copy / illustrations. Owned by apps/site.
• Generated artifacts. llms.txt, llms-full.txt, components.md, *-manifest.json — built by scripts, never edited by hand.

When in doubt: if removing the file would break consumers of an imported package, it belongs in packages/. Otherwise it’s app-level.