# Lilith Design System

The visual language of Oshun V1. One product, one paper theme (cream, light),
one terracotta accent. Two registers — **manuscript** for customer surfaces and
**plate-of-record** for operator surfaces — share the same palette and fonts;
only the ornament changes.

## Why two registers, not two themes?

A theme would imply visual divergence; the registers are the same theme deployed
at different densities. Customer-facing pages keep the editorial ornament — drop
caps, hairline rules, pull-quotes, sources rails, dot navigation.
Operator-facing pages drop the ornament for a graph-paper grid, monospaced
metadata, and tabular dignity. The reader can tell at a glance which side of the
product they are in without learning a new colour or font.

## Theme variants

`L_VARIANTS` exposes three palette variants:

| Variant    | Purpose                                                                   |
| ---------- | ------------------------------------------------------------------------- |
| `cream`    | Default paper-warm light theme.                                           |
| `cream-hc` | High-contrast (≥7:1). Set via `data-lilith-theme="cream-hc"` on `<html>`. |
| `dusk`     | Evening reading register (warm low-light, not a dark theme).              |

CSS custom properties are exposed in `lilith.css` so non-React surfaces (e.g.
markdown, mailers) can read the same palette via `var(--l-bg)` etc.

## Token surface

Everything visual is a single import away:

```tsx
import {
  L, // palette object
  L_VARIANTS, // palette variants
  SERIF_L,
  SANS_L,
  MONO_L, // font families
  motion,
  type,
  space,
  radii, // scales
} from '@/design-system/lilith';
```

`L` is the canonical light palette. `cream-hc` and `dusk` are derived from it.

## Primitives

| Component                      | Purpose                                              |
| ------------------------------ | ---------------------------------------------------- |
| `LEyebrow`                     | Small uppercase eyebrow above headlines.             |
| `LRule`, `LRule2`, `LDotRule`, | Hairline horizontal rules at four weights.           |
| `LDoubleRule`, `LThickRule`    |                                                      |
| `LColumnRule`                  | Vertical newspaper column rule.                      |
| `LDisplay`                     | Display-grade serif headline.                        |
| `LDropCap`, `LOpenQuote`       | Editorial ornaments.                                 |
| `LMasthead`                    | Newspaper masthead — vol/no, date, kicker, title.    |
| `LChip`, `LCode`               | Small tags (sans-uppercase / mono).                  |
| `LSourceItem`                  | Numbered source row in an evidence rail.             |
| `LConfidence`                  | Sophia-style five-dot confidence bar.                |
| `LDomainMark`                  | Single-stroke domain glyph (six domains).            |
| `LDots`                        | Inline dot navigation for chapter/sitting progress.  |
| `LBtn`, `LCard`                | Button (four kinds) and card (with optional accent). |
| `LPullQuote`, `LField`         | Editorial pull-quote and key/value field.            |

## Pills & disclosures

Used wherever an interaction may surprise the reader (memory state, AI
assistance, severity, decision):

| Component         | Domain                                      |
| ----------------- | ------------------------------------------- |
| `LSeverityPill`   | S3 advisory · S2 degraded · S1 critical.    |
| `LStatusPill`     | ok · degraded · down · paused.              |
| `LDecisionChip`   | pending · approved · request · rejected.    |
| `LValidationPill` | ok · warn · err · info (form/state).        |
| `LAIDisclosure`   | Persistent ✻ marker on AI-touched surfaces. |
| `LSyncDot`        | live · offline · queued (with count).       |

## Shells

Page-level chrome. Customer surfaces use `LWebShell` + `LCustomerNav` (+
optional `LSubNav`). Phone surfaces use `LPhoneShell` + `LStatusBar` +
`LTabBar` + `LHomeIndicator`. Operator surfaces use `LGraphPaper` +
`LOperatorBar` + `LDataCell` + `LDataRow`.

| Component        | Register        |
| ---------------- | --------------- |
| `LWebShell`      | manuscript      |
| `LCustomerNav`   | manuscript      |
| `LSubNav`        | manuscript      |
| `LSectionHead`   | manuscript      |
| `LPhoneShell`    | mobile          |
| `LStatusBar`     | mobile          |
| `LTabBar`        | mobile          |
| `LHomeIndicator` | mobile          |
| `LGraphPaper`    | plate-of-record |
| `LOperatorBar`   | plate-of-record |
| `LDataCell`      | plate-of-record |
| `LDataRow`       | plate-of-record |

## Edge states

The calm-under-stress register — every component is editorial, never alarming:

| Component         | Behaviour                                                               |
| ----------------- | ----------------------------------------------------------------------- |
| `LSkeleton`       | Dotted hairline, no shimmer.                                            |
| `LEmpty`          | A sentence and a single action.                                         |
| `LError`          | Stamped notice with code + logged-at — never alarming, always specific. |
| `LOffline`        | Full-bleed banner + cached-since timestamp.                             |
| `LPartialFailure` | Keeps what loaded, names what didn't, offers retry.                     |
| `LPwaUpdate`      | "A new edition" ribbon.                                                 |

## Specimen sheet

Open `/system` (the verification surface) to view live specimens of the type
ramp, palette, primitive grid, edge states, severity grammar, and the two
registers side-by-side.

## Authoring rules

- One terracotta accent for emphasis. Olive (`L.ok`) and `L.alert` are status
  colours only — never decoration.
- One real anchor per hero (drop cap, plate, glyph, or pull-quote — not
  several). `LHeroAnchor` enforces this at runtime if you adopt it.
- Inline-style components are intentional — values come from `tokens.ts`, which
  remains a single source of truth.
- Operator surfaces never use display-size serif — they use the same fonts at
  reduced size with monospaced metadata.
- AI-assisted output always renders with a visible `LAIDisclosure` somewhere in
  the surface; synthetic media uses the warning-toned `LSeverityPill`.

## Theming architecture

Two CSS custom-property layers ship in V1, both theme-scoped by the same
attributes:

| Layer       | Prefix      | Source of truth                   | Use for                                                        |
| ----------- | ----------- | --------------------------------- | -------------------------------------------------------------- |
| Lilith      | `--l-*`     | `lilith.css`                      | Everything new. Palette, rules, surfaces, domain text accents. |
| v2 semantic | `--oshun-*` | `globals-v2.css` + `../tokens.ts` | Behavior contracts (disclosure, trust, admin states), legacy.  |

Rules that keep the two layers coherent:

- **Theme attributes.** `data-lilith-theme` on `<html>` is the _user's_ choice
  (`cream` default · `cream-hc` · `dusk`). `data-lilith-register="night"` on a
  _container_ pins that subtree to the warm-night palette in every theme — for
  rooms that are night by design (planetarium, solar monitor, NEO tracker,
  telescope tools). Both attributes drive the **same** rule blocks in both
  layers; the contract test fails if either layer's selector list loses one.
- **TS mirrors.** `L` is legacy-mixed (four keys are `var()` refs) — prefer `LV`
  (theme-aware var refs) in DOM styles, and `L_VARIANTS[variant]` (all-literal)
  in canvas/SVG/OG-image code where `var()` cannot resolve. `L_VARIANTS` is
  asserted against `lilith.css` by `__tests__/lilith-css-contract.test.ts`; edit
  the CSS first, then the mirror, and the test will hold you to it.

### Surfaces

Panels compose from four semantic washes plus one scrim — all tracking the paper
family in every theme:

```tsx
import { SURFACE } from '@/design-system/lilith';

SURFACE.veil; // rgba(paper, .40) — hover/section wash
SURFACE.wash; // rgba(paper, .66) — quiet nested panel
SURFACE.card; // rgba(paper, .86) — standard raised card
SURFACE.solid; // rgba(paper, .97) — menus, docks, sticky chrome
SURFACE.scrim; // pinned-ink modal backdrop — dims in every theme
```

### Alpha and tints

`color-mix` is the only sanctioned alpha idiom — it composes with `var()`
references:

```tsx
import { tint, blend } from '@/design-system/lilith';

border: `1px solid ${tint(accent, 22)}`; // translucent tint
background: blend(accent, 8); // opaque wash over paper
background: blend(accent, 8, 'var(--l-bg)'); // …or over another base
```

### Anti-patterns (each of these shipped as a real bug)

- **The ink plate.** `background: rgba(var(--l-ink-rgb), 0.8+)` under ink-family
  text renders dark-on-dark in cream and cream-on-cream in dusk. An ink-filled
  control is legitimate only when its content uses the paper family
  (`var(--l-bg)` text on `rgba(var(--l-ink-rgb), .9)` fill).
- **Hex-alpha concatenation.** `` `${accent}30` `` emits invalid CSS whenever
  `accent` is a `var()` reference; the browser drops the whole declaration
  silently. Use `tint()`.
- **Pinned-theme literals in themed flow.** A hardcoded `#f7f1e2` panel (or a
  cream-tuned domain hex) is invisible under dusk. Literals belong only in
  canvas/SVG code (via `L_VARIANTS`) and in pinned-dark instrument rooms.
- **Ink-based modal scrims.** `rgba(var(--l-ink-rgb), .55)` _lightens_ the
  backdrop on dusk. Use `SURFACE.scrim`.

The banned pre-Lilith palette (navy `#0f172a…`, indigo `#818cf8/#6366f1`, slate
`#e2e8f0/#f1f5f9`, amber `#ffb347`, …) is enforced against every stylesheet by
the contract test.

## File map

```
src/design-system/lilith/
├── README.md          ← this file
├── index.ts           ← re-exports everything
├── tokens.ts          ← palette, fonts, motion, scales
├── primitives.tsx     ← editorial primitives (rules, eyebrow, drop cap, …)
├── pills.tsx          ← severity/status/decision/validation/AI/sync pills
├── shells.tsx         ← web/phone/operator shells & nav
├── edge-states.tsx    ← skeleton/empty/error/offline/partial/pwa
└── lilith.css         ← global stylesheet, CSS custom properties, theme variants
```

## Surfaces shipped on Lilith

| Route                    | Component                                                                      | Register        |
| ------------------------ | ------------------------------------------------------------------------------ | --------------- |
| `/`                      | `CustomerToday`                                                                | manuscript      |
| `/landing`               | `MarketingLanding`                                                             | manuscript      |
| `/explore`               | `LilithExplore` — featured · curated collections · recently read               | manuscript      |
| `/library`               | `LilithLibrary` — six kinds · recently kept                                    | manuscript      |
| `/activity`              | `LilithActivity` — cross-domain timeline · sittings bar · achievements         | manuscript      |
| `/profile`               | `LilithProfile` — account · connected rooms · AI · privacy summary             | manuscript      |
| `/search`                | `LilithSearch` — cross-room results, grouped by room                           | manuscript      |
| `/tara`                  | `TaraRoom`                                                                     | manuscript      |
| `/arete`                 | `AreteRoom`                                                                    | manuscript      |
| `/arete/streak`          | `AreteStreak` in phone frame — humane streak, "47 days, gently"                | mobile          |
| `/arete/recovery`        | `AreteRecovery` in phone frame — soft return after three quiet days            | mobile          |
| `/arete/plan`            | `AretePlan` — week workspace: goals · routine · friction                       | manuscript      |
| `/arete/goal`            | `AreteGoal` — one true page with measurable criteria + 90-day arc              | manuscript      |
| `/arete/review`          | `AreteReview` — Celebrate · Notice · Choose · Invite                           | manuscript      |
| `/arete/coaching`        | `AreteCoaching` — Lilith's letter + named patterns + adjustments               | manuscript      |
| `/arete/patterns`        | `AretePatterns` — heatmap + correlation table + mood-by-hour                   | manuscript      |
| `/arete/offering`        | `AreteOffering` — Living Offering: scene + score + cue-privacy                 | manuscript      |
| `/veritas`               | `VeritasRoom`                                                                  | manuscript      |
| `/veritas/claim`         | `VeritasClaim` — claim mode, banded underlines + evidence rail                 | manuscript      |
| `/veritas/source`        | `VeritasSource` — source profile (band, track record, conflicts)               | manuscript      |
| `/veritas/story`         | `VeritasTimeline` — story over time, struck retractions                        | manuscript      |
| `/veritas/counterclaims` | `VeritasCounter` — two sources side-by-side + verdict                          | manuscript      |
| `/veritas/topic`         | `VeritasTopic` — settled · open · what you've read · gaps                      | manuscript      |
| `/veritas/provenance`    | `VeritasProvenance` — receipt + declared limits + C2PA                         | manuscript      |
| `/veritas/retraction`    | `VeritasRetraction` — private soft-correction letter                           | manuscript      |
| `/veritas/mobile`        | `VeritasMobile` in phone frame — tap-to-peek claim card                        | mobile          |
| `/nyx`                   | `NyxRoom`                                                                      | manuscript      |
| `/nisaba`                | `NisabaRoom`                                                                   | manuscript      |
| `/nisaba/scholar`        | `NisabaScholar` — full apparatus criticus, witnesses, marginalia               | manuscript      |
| `/nisaba/compare`        | `NisabaCompare` — three editions side by side with diff                        | manuscript      |
| `/nisaba/manuscript`     | `NisabaManuscript` — Vatic. gr. 1950, vellum scan + provenance                 | manuscript      |
| `/nisaba/lexicon`        | `NisabaLexicon` — declension · etymology · attestations · field                | manuscript      |
| `/nisaba/graph`          | `NisabaGraph` — concept graph, 17 nodes around ἡγεμονικόν                      | manuscript      |
| `/nisaba/notebook`       | `NisabaNotebook` — long-form study with footnotes + suggestions                | manuscript      |
| `/nisaba/plan`           | `NisabaPlan` — seven-week arc with prerequisite chain                          | manuscript      |
| `/nisaba/daily`          | `NisabaDaily` in phone frame — the small morning page                          | mobile          |
| `/metis`                 | `MetisSchoolroom`                                                              | manuscript      |
| `/metis/lesson`          | `MetisLesson` (course reader)                                                  | manuscript      |
| `/metis/assessment`      | `MetisAssessment` (short-answer + Themis integrity)                            | manuscript      |
| `/metis/tutor`           | `MetisTutor` (chat + cited sources, ✻)                                         | manuscript      |
| `/metis/byom`            | `MetisBYOM` (bring your own materials)                                         | manuscript      |
| `/operator`              | four-card index                                                                | plate-of-record |
| `/operator/studio`       | `StudioReview`                                                                 | plate-of-record |
| `/operator/tenant`       | `TenantConsole`                                                                | plate-of-record |
| `/operator/admin`        | `AdminInbox`                                                                   | plate-of-record |
| `/operator/metis`        | `MetisOperator` (institutional Metis dashboard)                                | plate-of-record |
| `/mobile`                | phone-shell gallery (home + Tara pre/play/post + Arete + Nyx)                  | mobile          |
| `/tablet`                | tablet gallery — 768 home, 1366 Veritas, 1024 Nisaba (native)                  | tablet          |
| `/system/edge-states`    | full-page edge-state gallery (skeleton, empty, error, partial, …)              | manuscript      |
| `/system/verify`         | six measurement specimens — contrast, type, spacing, states, print, responsive | verification    |
| `/system/emails`         | four email templates (welcome, digest, veritas, incident)                      | print           |
| `/system/og`             | six per-domain 1200×630 OG cards                                               | print           |
| `/status`                | public status page — components, 90-day history, incidents                     | manuscript      |
| `/legal/lilith`          | `LegalPage(kind="terms")` — terms of use                                       | manuscript      |
| `/legal/lilith/privacy`  | `LegalPage(kind="privacy")` — privacy policy                                   | manuscript      |
| `/switcher`              | desktop ⌘D domain-switch overlay                                               | manuscript      |
| `/atelier`               | five-room workshop index (X–XIV) + house rules                                 | manuscript      |
| `/atelier/image`         | `AtelierImage` — Camera Obscura · X                                            | manuscript      |
| `/atelier/audio`         | `AtelierAudio` — Foundry of Voices · XI                                        | manuscript      |
| `/atelier/video`         | `AtelierVideo` — Cinematheque · XII                                            | manuscript      |
| `/atelier/forms`         | `AtelierForms` — Forms · XIII                                                  | manuscript      |
| `/atelier/motion`        | `AtelierMotion` — Stage of Motion · XIV                                        | manuscript      |
| `/lilith`                | top-level index — every shipped surface in one broadsheet grid                 | manuscript      |
| `/system`                | specimen sheet (palette, type, primitives, edge states)                        | manuscript      |

The legacy `/welcome` flow (auth-coupled) is unchanged. The previous dark/aqua
design system continues to compile so that the 300+ components still importing
`@/design-system/*` keep working; routes listed above render in the new Lilith
language.
