> ## Documentation Index
> Fetch the complete documentation index at: https://reikon.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Design System

> UI tokens and core components, condensed from the full internal reference.

# Design System

A condensed overview of Reikon's UI conventions. The full, exhaustive reference —
every component prop, every exact Tailwind class, the complete don't-do list — lives in
`docs/design-system.md` in the repo and is the source of truth if anything here seems
to conflict with the actual code. This page exists so a contributor can get oriented
without reading all 1,000+ lines of that file first.

## Stack

React 18 functional components, Tailwind CSS v3 + CSS custom properties for theming,
Phosphor Icons (`ph ph-*` / `ph-fill ph-*` classes), `class`-strategy dark mode.

## Color tokens

Surfaces use semantic tokens, never hardcoded hex:

| Token             | Light     | Dark      | Use                            |
| ----------------- | --------- | --------- | ------------------------------ |
| `reikon-canvas`   | white     | `#161b22` | Card/panel backgrounds         |
| `reikon-elevated` | `#f1f5f9` | `#21262d` | Raised surfaces, table headers |
| `reikon-border`   | `#e2e8f0` | `#30363d` | All borders                    |
| `reikon-fg`       | `#0f172a` | `#e6edf3` | Primary text                   |

Two other special tokens:

* `--accent` — user-customizable accent color (default `#34d399`), used for active
  states, progress bars, toggles. Never hardcoded.
* `--ai-gradient` — a fixed blue→violet→pink gradient, used for **every** AI-sourced
  feature, never the user's accent color. This is a hard rule: it's how a user learns
  to visually distinguish "this number is AI-suggested" from "this number is computed
  deterministically," and that distinction matters for trust.

Semantic color roles (consistent across the whole app): emerald = healthy/active,
red/rose = error/critical, amber = caution/transient, indigo = data label only (never
state), sky = informational.

## Core components

Never hand-roll these — always use the shared primitive:

* **`<Button>`** — never a raw `<button>` with manual styling
* **`<Badge>`** — always a gradient pill, never flat/bordered; tone matches what it
  represents (e.g. `rose` for errors, `emerald` for healthy/active states)
* **`<IconButton>`** — square icon-only actions, single fixed size
* **`<Avatar>`** — contributor initials, never a hand-rolled div
* **`<Tooltip>`** — never the native `title=` attribute
* **`<SubTabs>`** — page-level sub-navigation, never reimplemented per page

## Modal anatomy

Every modal follows the same structure: overlay → panel → header (icon badge + title,
no subtitle) → body → footer, all wrapped in `<Portal>` so the overlay mounts on
`document.body` and isn't mispositioned by a transformed ancestor (the tab/dashboard
entrance animations leave such transforms). `items-start` on the header flex, never
`items-center` — it's a small detail that looks fine until the title wraps to two
lines. Full anatomy with exact classes is in `docs/design-system.md`'s Modals section.

## The full-height scroll chain

Every scrollable tab follows the same pattern — a `flex h-full min-h-0 flex-col` root,
with the scrollable content area getting `flex-1 min-h-0 overflow-y-auto`. Missing
`min-h-0` anywhere in that chain is the single most common layout bug in this codebase
— content silently overflows instead of scrolling.

## Tinted alert cards

A whole-card color wash (border + background + text all in one hue) is reserved for
cards where the *entire content* shares one semantic meaning — a risk list, a warning.
It's not the default card style; most cards stay neutral white/slate. Reserve the tint
for when color itself is the message, not decoration.

## Before you build new UI

Read `docs/design-system.md`'s relevant section first — it has exact prop signatures,
the complete color-token table, and roughly 40 specific "don't do this" entries learned
from real bugs (most logged with the bug they came from). This page is a map to that
territory, not a replacement for it.