Principles
Eight rules that decide every visual question in Titan, and the two-layer token architecture that enforces them.
Apple Human Interface Guidelines × trading density. Near-black surfaces, system typography, strict radii, spring-based micro-interactions, tabular numbers everywhere.
This page is rendered by the docs site itself, using a port of the interface's own token file. Every swatch, radius and curve below reads the same CSS variables the trading terminal reads — if the port drifts, these break visibly.
The eight principles
| # | Principle | Concrete consequence |
|---|---|---|
| 1 | Apple-centric | System font stack, Apple radii (5/8/11/18/22), scale(.96) on press, overshoot spring on entrances |
| 2 | Dark by default | Dark is the primary target (OLED void #0A0A0B). Light is a complete parallel "parchment" palette |
| 3 | Everything is a token | No hard-coded colour/radius/shadow in components — always var(--…) |
| 4 | Trading density | Dense, legible, aligned numbers. tabular-nums on all numbers. Three densities |
| 5 | Hierarchy via text opacity | Four ink levels instead of arbitrary greys — hierarchy from alpha, not hue |
| 6 | Stacked surfaces | Four surface layers create depth without heavy shadows |
| 7 | Tactile but restrained motion | 120–350 ms, spring cubic-bezier(.34,1.56,.64,1) for pop. Honour prefers-reduced-motion |
| 8 | Reserved semantic colour | Green/red/orange only for financial meaning. Never decorative |
Two-layer token architecture
┌─────────────────────────────────────────────┐
│ LAYER 1 — Titan tokens (source of truth) │
│ --bg, --surface, --surface-2/3, │
│ --t1..t4, --green/red/warn, --r-*, --s-* │
└──────────────────┬──────────────────────────┘
│ mapped onto ↓
┌──────────────────▼──────────────────────────┐
│ LAYER 2 — framework aliases │
│ --background, --foreground, --primary, │
│ --card, --muted, --border, --radius │
└─────────────────────────────────────────────┘Golden rule: prefer Titan tokens (var(--surface), text-[var(--t2)]) for bespoke work,
framework utilities (bg-card, text-muted-foreground) for generic primitives. Both point at the
same values.
This site is the proof that Layer 2 is genuinely swappable: Fumadocs' aliases are --color-fd-*
rather than shadcn's --card / --muted, and the entire port is a remap in
app/global.css. Zero component forks.
The surface stack
The closer to the user an element is, the higher its surface. Controls sit on --surface-3;
their active state drops back to --surface — a "pressed pearl" effect.
The ink ramp
Four levels of alpha, not four greys. Using alpha means the ramp stays correct on any surface it lands on, and inverts cleanly for the light theme.
--t1Primary text — body, values--t2Secondary — labels, decimals--t3Tertiary — table headers, captions--t4Disabled, faint strokesWhere things live
| File | Contains |
|---|---|
interface/src/index.css | @theme tokens, @layer components, toast styles |
interface/design.md | The full design source of truth |
docs/app/global.css | This site's port of the same tokens |
What "compliant" means
A surface is Titan-compliant when all of the following hold:
- No hex literal outside the token file.
- Every number is
tabular-nums. - Green/red appear only where they carry financial meaning.
- Radius comes from the Apple scale — no invented intermediates.
- In-page cards have no shadow; only floating layers do.
- State lives on
data-*, not in a conditional class string. - Motion sits under
prefers-reduced-motion: no-preference.
The full version is the checklist.