Arcanea's interface system combines the portable token specification in `arcanea-ai-app/.arcanea/config/design-tokens.yaml` (backed by `/DESIGN.md` and `@arcanea/design-system` `v0.3.0`) with the brand theme wiring in `docs-platform/lib/brands.ts` and `docs-platform/app/global.css`.

## Cosmic depth and Academy color palettes (`design-tokens.yaml`) [#cosmic-depth-and-academy-color-palettes-design-tokensyaml]

Arcanea surfaces never use pure flat black (`#000000`) or saturated primary red/green/blue. Instead, interfaces layer six near-black **Cosmic** depth levels with elemental **Academy** accents:

| Token group | Token key | HSL / Hex value | Role |
|---|---|---|---|
| **Cosmic foundation** | `cosmic.void` | `240 6% 4%` (`#0b0e14`) | Deepest page background canvas |
| **Cosmic foundation** | `cosmic.deep` | `240 5% 6%` | Default application background |
| **Cosmic foundation** | `cosmic.surface` / `cosmic.raised` | `240 5% 10%` / `240 5% 14%` | Card surfaces and elevated containers |
| **Cosmic foundation** | `cosmic.border` / `cosmic.border_bright` | `240 5% 14%` / `240 5% 20%` | Structural and emphasized borders |
| **Text hierarchy** | `text.primary` / `secondary` / `muted` | `0 0% 93%` / `0 0% 64%` / `0 0% 45%` | WCAG-verified neutral text without blue tint |
| **Atlantean (Water)** | `atlantean.teal` / `atlantean.primary` | `180 70% 50%` (`#00bcd4`) / `212 70% 40%` | Primary interface accent and intelligence signal |
| **Arcanean Gold** | `gold.bright` / `gold.deep` | `48 100% 60%` (`#ffd700`) / `45 90% 50%` | Crown / Gate achievement highlight and secondary accent |
| **Draconic (Fire/Sky)** | `draconic.crimson` / `draconic.sky` | `355 80% 45%` / `200 80% 55%` | Fire and Sky Academy accents |
| **Brand & shadcn** | `aquamarine.default` / `shadcn.primary` | `160 100% 75%` / `262 83% 66%` | Aquamarine highlight and violet ring mapping (`radius: 0.5rem`) |

## Typography lock (`design-tokens.yaml` & `TASTE.md`) [#typography-lock-design-tokensyaml--tastemd]

Per the 2026-04-18 typography lock in `design-tokens.yaml`, Arcanea uses three font families and explicitly bans `Space Grotesk`, `Cinzel`, `Arial`, `Roboto`, and `Newsreader`:

| Role | Family & CSS variable | Weights / styles | Allowed usage |
|---|---|---|---|
| **Display (`typography.display`)** | `Geist` (`--font-geist-sans`) | Variable | Bold headings, hero text, and page titles |
| **Body (`typography.body`)** | `Geist` (`--font-geist-sans`) | Variable | Body copy, narrative, UI labels, and navigation |
| **Editorial serif (`typography.serif`)** | `Instrument Serif` (`--font-instrument-serif`) | `400` (`normal`, `italic`) | Chapter pull quotes, lyrical hero subtitles, and Library long-form—never UI labels or CTAs |
| **Monospace (`typography.mono`)** | `Geist Mono` (`--font-geist-mono`) | Variable | Code blocks, terminal output, and technical captions (`letter-spacing: 0.2em`) |

## Seven-tier glassmorphic surface hierarchy [#seven-tier-glassmorphic-surface-hierarchy]

`design-tokens.yaml` defines seven graduated glass tiers (`effects.glass`) paired with custom container bounds (`container_max: 1400px`, custom `2xl` breakpoint at `1400px`):

| Tier | Background | Backdrop filter | Border | Intended surface |
|---|---|---|---|---|
| **`tier1_subtle`** | `rgba(9, 9, 11, 0.4)` | `blur(8px)` | `1px solid rgba(0, 188, 212, 0.06)` | Hover overlays and secondary panels |
| **`tier2_standard`** | `rgba(9, 9, 11, 0.65)` | `blur(16px)` | `1px solid rgba(0, 188, 212, 0.12)` | Standard cards and panels |
| **`tier3_strong`** | `rgba(9, 9, 11, 0.85)` | `blur(24px)` | `1px solid rgba(0, 188, 212, 0.18)` | Navigation bars and modals |
| **`tier4_liquid`** | `135deg` white alpha gradient (`0.05` to `0.02`) | `blur(40px) saturate(1.8) brightness(1.1)` | `1px solid rgba(255, 255, 255, 0.1)` | High-refraction feature surfaces |
| **`tier5_liquid_elevated`** | `135deg` white/cosmic-blue alpha gradient | `blur(60px) saturate(2.0) brightness(1.15)` | `1px solid rgba(255, 255, 255, 0.15)` | Hero cards and featured content |
| **`tier6_iridescent`** | `135deg` peacock/teal/indigo multi-stop gradient | `blur(32px) saturate(1.6)` | `1px solid rgba(0, 137, 123, 0.18)` | Prismatic showcase cards |
| **`tier7_bubble`** | `radial-gradient` at `30% 20%` | — | `1px solid rgba(255, 255, 255, 0.10)` | Spherical orbs and Gate badges |

### Motion timing and easing (`animation`) [#motion-timing-and-easing-animation]

- **Timing scale:** `instant: 100ms`, `fast: 160ms`, `normal: 250ms`, `emphasis: 400ms`, `dramatic: 600ms` (ambient loops at `6s`, `12s`, and `20s`).
- **Easing curves:** Default `cubic-bezier(0.4, 0, 0.2, 1)` and spring `cubic-bezier(0.175, 0.885, 0.32, 1.275)`.

## How `docs-platform` renders `data-brand="arcanea"` [#how-docs-platform-renders-data-brandarcanea]

In `docs-platform/lib/brands.ts` and `app/[brand]/layout.tsx`, the Arcanea documentation tenant sets `data-brand="arcanea"`, `data-surface="dark"`, and `data-glow="on"` on the `.lz-brand` wrapper with CSS custom properties:

- `--brand-accent: #00bcd4` (Atlantean Teal, mapped to `--color-fd-primary` for active navigation rails, link underlines, and `live` capability badges).
- `--brand-accent-secondary: #ffd700` (Arcanean Gold, mapped to `planning` capability badges and gradient stops from `#0b0e14` to `#ffd700`).
- `--brand-accent-soft: oklch(0.74 0.13 210 / 0.16)` (translucent wash applied to sidebar link hovers, table row hovers, and the `3px` card focus/hover ring under `.lz-brand[data-glow='on']`).