# Agent Handoff

This file exists to remove ambiguity for anyone picking up work in this repo.

## Canonical source of truth

- `source/aurora-core-v5.4.0.html` is the canonical visual and interaction sampler.
- `tokens/aurora-core.tokens.json` is the canonical token dataset for exported token formats.
- Gold and amber rules are non-negotiable:
  - gold = hero, may glow
  - amber = warning, matte, no glow
  - toggles use purple -> blue, not gold

## Scope of this repository

This repo is a foundation kit, not a single runnable product app. It contains:

- the canonical sampler and extracted CSS
- token exports and validation/export scripts
- reference implementations for React, Tailwind, Android Compose, and SwiftUI
- platform libraries for Svelte, Rust, and Python in `libs/`
- docs, ADRs, governance, Figma planning, and zeroheight content
- MCP starter servers for design-system-aware tooling

For a comprehensive guide to all 25 platform examples (web, mobile, desktop), see `examples/EXAMPLES_GUIDE.md`.

## Edit order

When behavior or visuals change, update in this order unless there is a strong reason not to:

1. `source/aurora-core-v5.4.0.html`
2. mirrored root sampler `aurora-core-v5.4.0.html`
3. tokens in `tokens/` if token values changed
4. platform examples in `examples/`
5. docs and checklists in `README.md`, `docs/`, and example readmes
6. rerun verification

## Mirrors and generated files

Hand-edited:

- `source/aurora-core-v5.4.0.html`
- `source/aurora-core-v5.4.0.css`
- `aurora-core-v5.4.0.html` (mirror of the source sampler, keep in sync)
- `tokens/aurora-core.tokens.json`
- `tokens/aurora-core.tokens.studio.json`
- `tokens/aurora-core.w3c.tokens.json`
- files under `examples/`
- files under `docs/`, `figma/`, `zeroheight/`, `references/`

Generated or regenerated:

- `tokens/aurora-core.theme.css` is generated by `python scripts/export_tokens.py`
- `figma/variable-naming.generated.csv` is generated by `scripts/generate_figma_variables.py`

Intentional non-mirrors:

- `examples/web/vanilla/index.html` is intentionally minimal and is not a full mirror of the canonical sampler
- `examples/web/react/aurora.css` follows the same design language but is not a byte-for-byte mirror of `source/aurora-core-v5.4.0.css`

## Architecture map

- `source/` - canonical sampler assets
- `tokens/` - canonical token JSON plus exported token formats
- `scripts/` - validation and export utilities
- `examples/web/react/` - typed React wrappers around canonical CSS semantics
- `examples/web/vanilla/` - minimal no-framework example
- `examples/web/storybook/` - story coverage targets and interaction checks
- `examples/mobile/android-compose/` - reference Compose implementation files
- `examples/mobile/swiftui/` - reference SwiftUI implementation files
- `libs/svelte/` - Svelte 5 component library (@aurora-core/svelte)
- `libs/rust/` - Rust design token crate (aurora-core)
- `libs/python/` - Python design system package (aurora-core)
- `libs/_generator/` - token code generator and drift validator
- `docs/` - system guidance, component specs, ADRs, governance

## Toolchain expectations

Repo requirements:

- Python 3.11+
- Node.js for the React example

Observed on this machine during handoff:

- Python `3.13.6`
- Node `24.2.0`
- npm `11.3.0`
- `kotlinc` not installed
- `swiftc` not installed

Important implication:

- Android Compose and SwiftUI files in this repo are reference source files, not standalone mobile projects. They must be compiled inside a host Android/Xcode project. This repo does not currently include those host wrappers.

## Real verification commands

Repo-wide:

- `python scripts/validate_tokens.py`
- `python scripts/export_tokens.py`
- `python scripts/verify_foundation_kit.py`

Libraries:

- `python libs/_generator/generate.py --validate`
- `python scripts/validate_libs.py`
- `cd libs/rust && cargo test`

React example:

- `cd examples/web/react`
- `npm install`
- `npm run typecheck`
- `npm run build`

## Done Means

A task touching core system behavior is done when all applicable items are true:

- canonical sampler is correct in `source/aurora-core-v5.4.0.html`
- root mirror `aurora-core-v5.4.0.html` is kept in sync
- token exports and docs are updated when behavior or semantics change
- `python scripts/validate_tokens.py` passes
- `python scripts/export_tokens.py` passes
- `python scripts/verify_foundation_kit.py` passes, with any skipped checks explained
- no legacy warm-gold hex remains anywhere in the repo
- amber components do not reference glow semantics
- touched examples remain internally coherent and typed
- touched docs are updated in the same change
- no encoding regressions are introduced in HTML, CSS, or markdown

## Landmines and constraints

- The root sampler mirrors `source/aurora-core-v5.4.0.html`; forgetting one of them creates drift.
- Terminal output on Windows PowerShell can display Unicode punctuation poorly even when file bytes are correct. Prefer ASCII in docs unless there is a strong reason not to.
- `examples/web/vanilla/index.html` is intentionally sparse. Do not treat missing showcase surfaces there as a bug by default.
- `tokens/aurora-core.theme.css` is exported output. Regenerate it instead of hand-editing it.
- Gold vs amber semantics are an ADR-level rule, not a taste preference.
- If behavior changes, update docs in the same pass rather than as a follow-up.

## Visual regression anchors

If you need a quick sanity pass after edits, inspect these canonical surfaces in `source/aurora-core-v5.4.0.html`:

- Panels -> Analytics chart period switching
- Buttons -> all seven button variants
- Buttons -> Icon Actions row
- Controls & Inputs -> toggle and slider behavior
- Status surfaces where gold glow vs amber matte contrast should be obvious