# Aurora Core Examples Guide

## What This Repo Is

Aurora Core v5.4.0 is a production-grade design system foundation kit, not a single runnable app. The `examples/` directory contains reference implementations across 25 framework targets showing how to implement Aurora's components and design tokens on each platform. This guide is the primary entry point for AI agents (Claude, Codex) and humans navigating these examples.

## Quick-Find Matrix

| Language | Framework | Category | Directory Path | Status |
|----------|-----------|----------|----------------|--------|
| TypeScript | React 19 | web | `examples/web/react/` | Buildable |
| HTML/CSS/JS | Vanilla HTML | web | `examples/web/vanilla/` | Source-only |
| TypeScript | Vue 3 | web | `examples/web/vue/` | Source-only |
| TypeScript | Svelte 5 | web | `examples/web/svelte/` | Source-only |
| TypeScript | Angular | web | `examples/web/angular/` | Source-only |
| JavaScript | Web Components | web | `examples/web/web-components/` | Source-only |
| Kotlin | Jetpack Compose | mobile | `examples/mobile/android-compose/` | Source-only |
| Swift | SwiftUI | mobile | `examples/mobile/swiftui/` | Source-only |
| Kotlin/XML | Android XML | mobile | `examples/mobile/android-xml/` | Source-only |
| Dart | Flutter | mobile | `examples/mobile/flutter/` | Source-only |
| TypeScript | React Native | mobile | `examples/mobile/react-native/` | Source-only |
| Kotlin | Compose Multiplatform | mobile | `examples/mobile/compose-multiplatform/` | Source-only |
| Java | Java Swing | desktop | `examples/desktop/java-swing/` | Source-only |
| Java | JavaFX | desktop | `examples/desktop/java-fx/` | Source-only |
| Python | PySide6 | desktop | `examples/desktop/python-pyside6/` | Runnable |
| Python | Tkinter | desktop | `examples/desktop/python-tkinter/` | Source-only |
| C#/XAML | WPF | desktop | `examples/desktop/csharp-wpf/` | Source-only |
| C#/XAML | .NET MAUI | desktop | `examples/desktop/csharp-maui/` | Source-only |
| Rust | egui | desktop | `examples/desktop/rust-egui/` | Source-only |
| Rust | Iced | desktop | `examples/desktop/rust-iced/` | Source-only |
| C++ | Qt | desktop | `examples/desktop/cpp-qt/` | Source-only |
| Go | Fyne | desktop | `examples/desktop/go-fyne/` | Source-only |
| TypeScript | Storybook | web | `examples/web/storybook/` | Supporting |
| CSS | Tailwind | web | `examples/web/tailwind/` | Supporting |

## Canonical Sources of Truth

- **Tokens:** `tokens/aurora-core.tokens.json`
- **CSS variables:** `source/aurora-core-v5.4.0.css`
- **Visual reference:** `source/aurora-core-v5.4.0.html`
- **Design rules:** `docs/adr/` (ADRs 0001-0004)
- **Component docs:** `docs/02-components/`

## Component Inventory

| # | Component | Behavioral Summary |
|---|-----------|-------------------|
| 1 | **Button** | 7 variants; gold primary glows, amber warning is matte |
| 2 | **Toggle** | Purple-to-blue gradient, never gold; 280ms morph animation |
| 3 | **Slider** | Tone system (gold/blue/purple); tinted tracks, never neutral grey |
| 4 | **Badge** | 7 tones with optional dot; amber dots do not glow |
| 5 | **ProgressBar** | Tinted tracks; value clamped 0-100; accessible |
| 6 | **Card** | Glass surface with 3 depth tiers (8/20/32px blur); optical depth only |
| 7 | **TextInput** | Glass surface; gold focus ring; red error state |
| 8 | **Alert** | Gold hero (glow), green success (no glow), amber warning (no glow), red error, blue info |
| 9 | **Tabs** | Gold active indicator (glow); glass track; keyboard navigable |

## Design Rules Summary

These are non-negotiable, ADR-level decisions:

1. **Gold emits light** -- always glow on hero elements
2. **Amber does NOT glow** -- matte warning only
3. **Depth is optical** -- blur tiers (8/20/32px), never box-shadow for elevation
4. **Toggles use purple-to-blue** -- never gold
5. **Tinted tracks** -- progress bars and sliders inherit faint fill tint
6. **No hardcoded colors** -- always reference token constants
7. **No legacy warm-gold (#D4A560)** -- use canonical values only

## How to Use an Example

- **React** is buildable:
  ```bash
  cd examples/web/react && npm install && npm run dev
  ```
- **PySide6** is runnable:
  ```bash
  cd examples/desktop/python-pyside6 && pip install PySide6 && python showcase.py
  ```
- All other examples are **source-only reference files**. Copy files into your project and adapt.
- Each example has a README with platform-specific setup instructions.

## Version Stamp

All examples target Aurora Core v5.4.0. Last reviewed: 2026-03-22.

## Freshness Policy

All examples are best-effort-without-building kept in sync with the canonical source. When tokens, CSS variables, design rules, or component behaviors change, all examples must be reviewed and updated in the same PR or an immediate follow-up task. Use `examples/COMPONENT_CHECKLIST.md` to verify compliance.