# Candlelight

> A portable design system for instruments, not dashboards. Distribution is copy-in: `npx candlelight-ds add <name>` writes component source into your repo and the code is yours — inline trap comments, G-rule citations and all. Two npm packages carry the law: @candlelight-ds/tokens (the token sheet) and @candlelight-ds/eslint-plugin (the lint guards). Everything else is registry items.

Status: v0.2 — everything below is live and public: 30 registry items, `npx candlelight-ds` (the CLI, 0.1.0), @candlelight-ds/tokens (0.2.0 — the tint ramp §2.4a and the contract-metrics module `@candlelight-ds/tokens/metrics`), and @candlelight-ds/eslint-plugin (0.2.0 — adds the tintDiscipline guard), all on npm; spec at v1.4. Remaining: copy extraction (§9), the density system (§2.6), then the v0.3 example proof app. Do not guess at APIs not listed here.

## Primitives (the foundations)

- [/tokens](/tokens): the primitives — the token sheet rendered live from @candlelight-ds/tokens: the stage and ink ladders, voice colors, fill and tint ramps, structure, motion. Raw twin: [/tokens.md](/tokens.md) — includes the full utility API (bg-stage, text-ink, bg-fill-hover, the tint ramp bg-live-chip/ring-brass-rim, ...) and the contract metrics (`import { SHEET_TAKEOVER_MAX, … } from '@candlelight-ds/tokens/metrics'`). The primitives are not registry items — they arrive via `npx candlelight-ds init` / @candlelight-ds/tokens, and they lead the rendered catalog at [/components#primitives](/components#primitives).

## Elements (the Tier-1 registry)

Install any item: `npx candlelight-ds add <name>` (also: `list`, `info <name>` for the full contract, `init` for day zero; `--json` everywhere for machines; raw payloads at /r/<name>.json for any generic installer). Every item's JSON carries machine-readable metadata under meta.candlelight: category (machine ids `primitive | instrument | shell | hook`, rendered as the catalog's four shelves: Elements, Instruments, Shells, Hooks & utilities), G-rule citations, use-when/don't-use-when, states, the keyboard contract, known traps, and acceptance tests. The registry index is at [/r/registry.json](/r/registry.json). The rendered catalog groups the same four shelves at [/components](/components).

Each component: rendered page at /components/<name>, raw markdown twin at /components/<name>.md, install payload at /r/<name>.json.

- [button](/components/button.md): every click that isn't a row or a pad; printed keys, 1px travel, one primary per region.
- [chip](/components/chip.md): status/count/tag tokens — live, armed, ready, warn, danger.
- [kbd](/components/kbd.md): the printed key (G2); ⌘ vs Ctrl by platform; honest keys only.
- [tooltip](/components/tooltip.md): one line of words, 400ms; title= is lint-banned in its favor.
- [menu](/components/menu.md): THE one floating-menu engine — dropdown + context, printed keys, danger items.
- [overlay](/components/overlay.md): the one mount above z-float; modal or bare; never stacks two deep.
- [sheet](/components/sheet.md): the one drawer — floats, never reflows; a lens on the armed object; resizable with a keyboard path.
- [ink](/components/ink.md): the editing feel — no edit mode, continuous save, real undo, [[ mentions. Read its traps before touching editor keys.
- [inline-edit](/components/inline-edit.md): the commit-once exception — create inputs and renames under navigating links.
- [slider](/components/slider.md): onChange live / onCommit once — consumers never flood.
- [segmented-control](/components/segmented-control.md): 2–4 visible exclusive options.
- [skeleton](/components/skeleton.md): a flat fill breathing; no shimmer; spinners banned outside buttons.
- [announcer](/components/announcer.md): the one quiet transient line (Undo inside) + the async-only toast viewport, max two.
- [empty-state](/components/empty-state.md): teaches the surface's verb; never "nothing here."

## Instruments (v0.2 — the equipment)

- [console](/components/console.md): THE ONE console — six zones docked at the frame's bottom edge; its six acceptance tests ship in the metadata. Read this before building any persistent strip.
- [transport-button](/components/transport-button.md): icon · micro-label · printed key · pressed tone; density-aware; held keys sit sunken.
- [commit-key](/components/commit-key.md): the GO family — armed breathes the rim; live is a status, not a button.
- [pad](/components/pad.md): one-shots — the strike blooms and decays like a drum-pad LED, restartable.
- [armed-row](/components/armed-row.md): the row that composes the grammar — arm ring, live chip, readiness, rename, menu, reorder.
- [status-dot](/components/status-dot.md): G6 — a dot until it isn't; StatusDot (system) + ReadinessDot (per-object).
- [hold-to-strike](/components/hold-to-strike.md): G4 — hold ~600ms, release cancels, completion strikes with Undo announced.
- [intensity-bands](/components/intensity-bands.md): 1–N stepped selector with printed number keys.
- [flames](/components/flames.md): activity bars — CSS grade for rows, signal grade for the console.
- [glow-panel](/components/glow-panel.md): per-card accent glow — glow is state, never decoration.

## Shells

- [stage-shell](/components/stage-shell.md): the performance anatomy — strip / stage + deck / console seat; the lens rides the Sheet.
- [room-shell](/components/room-shell.md): one strip over one panel — rooms get no bespoke anatomies.
- [split-shell](/components/split-shell.md): list + adjacent editor with the Sheet built into the detail region.

## Hooks & utilities

- [use-surface-keyboard](/components/use-surface-keyboard.md): the binding map — one listener per surface; the ? help renders FROM the map.
- [use-selection](/components/use-selection.md): the one selection model — arm/multi, focus cursor, shift-range, auto-prune.
- [use-drag-reorder](/components/use-drag-reorder.md): drag is for order — private MIME, axis-free edges, ⌥↑/↓ path.
- [utils](/components/utils.md): the class combiner every component leans on (cn: clsx + tailwind-merge); ships automatically as a registry dependency of every component.

## Law

- [The complete specification](/llms-full.txt): tokens, the interaction grammar (G1–G10), composition rules (C1–C6), the editing contract (Ink), the drawer contract (Sheet), the console contract, copy voice, accessibility laws, governance, and the paste-ready appendices (token sheet, Tailwind v4 theme, structural/motion CSS, ESLint guards). Read §1 and §3 in full before writing any code against this system.
- [The same spec as markdown](/spec.md): identical content, markdown twin.

## For agents

- Bootstrap protocol: spec §0.a. Day zero, in order: (a) tokens into your global stylesheet, (b) structural/motion CSS below them, (c) lint guards, (d) an empty living-catalog route. Governance exists before the first component does.
- The spec's values are law: fill-ramp alphas, radii/shadows/z scales, 120/150/2500ms durations and the one ease. Do not retune them.
- One of each, forever: one drawer, one menu engine, one editing feel, one console.

## Coming

- v0.3: the proof — an example app built only through `npx candlelight-ds add`, in a non-theater metaphor.