# Aurora Core Foundation Kit

Aurora Core v5.4.0 is packaged here as a **production-grade foundation kit** for long-lived product work.

This bundle is intentionally broader than a static design handoff. It includes:

- the authoritative HTML/CSS sampler with live component behavior
- token exports in multiple formats
- implementation examples across platforms
- Figma and zeroheight content packs
- governance, ADRs, and release guidance
- **FastMCP servers** for design-system-aware tooling and an interactive playground
- scripts and starter artifacts for scaling Aurora Core across multiple projects

## Package map

- `source/` - Authoritative HTML sampler and extracted CSS from v5.4.0.
- `tokens/` - Design token exports for custom JSON, W3C-style draft, Tokens Studio, CSS, and Tailwind.
- `docs/` - Long-form system docs, ADRs, adoption guidance, governance, and checklists.
- `figma/` - Figma library planning pack: page structure, variable import helpers, component inventory, and handoff notes.
- `zeroheight/` - Zeroheight-ready content pack: site map, article templates, and editorial structure.
- `examples/` — 25 reference implementations across web (6), mobile (6), and desktop (10) platforms, plus Storybook and Tailwind integration; see `examples/EXAMPLES_GUIDE.md`
- `mcp/` - FastMCP servers, app playground, test clients, and setup docs.
- `portal/` - Living design system showcase, deployed at [aurora-core-iota.vercel.app](https://aurora-core-iota.vercel.app/portal/index.html).
- `scripts/` - Utility scripts to export tokens, validate mappings, and build derived assets.
- `references/` - Rationale, decisions, migration history, and the final system audit trail.


## Live Site

The design system is deployed on Vercel at:

**https://aurora-core-iota.vercel.app/portal/index.html**

This is a living component showcase — every section renders Aurora Core's components natively with Dark/Light theme switching.

## Local Development

- Open `portal/index.html` directly in a browser for local use.
- Or serve locally: `python -m http.server` and visit `localhost:8000/portal/index.html`.

## Core system rules

1. **Gold emits light**. Gold is reserved for hero intent, primary actions, active navigation, focus, and premium metrics.
2. **Amber does not**. Warning is matte, darker, and never glows.
3. **Purple is analytical / secondary**. It may glow, but never outranks gold.
4. **Blue is informational / system**. It should never borrow hero gold borders or glows.
5. **Depth is optical, not shadow-based**. Use the 8 / 20 / 32 blur model.
6. **Tracks inherit semantics**. Progress and slider tracks use faint tints of their fill color rather than neutral grey.
7. **Toggles live in the secondary spectrum**. Purple -> blue indicates system/process state, not primary CTA intent.

## Recommended adoption order

1. Start with `source/aurora-core-v5.4.0.html`
2. Adopt tokens from `tokens/`
3. Read `docs/00-overview/system-overview.md`
4. Bring up the registry MCP server in `mcp/servers/aurora_registry/`
5. Stand up implementation examples from `examples/`
6. Build your Figma library using `figma/`
7. Publish docs using `zeroheight/`

## Versioning

This package reflects **Aurora Core v5.4.0** as the stable baseline. Treat `source/aurora-core-v5.4.0.html` plus the token exports as the canonical source of truth.

The canonical sampler includes the live analytics period switcher, so `7D`, `30D`, and `90D` change real chart data rather than only toggling visual state.