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:
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) andL.alertare status colours only — never decoration. - One real anchor per hero (drop cap, plate, glyph, or pull-quote — not
several).
LHeroAnchorenforces 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
LAIDisclosuresomewhere in the surface; synthetic media uses the warning-tonedLSeverityPill.
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-themeon<html>is the user's choice (creamdefault ·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.
Lis legacy-mixed (four keys arevar()refs) — preferLV(theme-aware var refs) in DOM styles, andL_VARIANTS[variant](all-literal) in canvas/SVG/OG-image code wherevar()cannot resolve.L_VARIANTSis asserted againstlilith.cssby__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:
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:
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 onrgba(var(--l-ink-rgb), .9)fill). - Hex-alpha concatenation.
`${accent}30`emits invalid CSS wheneveraccentis avar()reference; the browser drops the whole declaration silently. Usetint(). - Pinned-theme literals in themed flow. A hardcoded
#f7f1e2panel (or a cream-tuned domain hex) is invisible under dusk. Literals belong only in canvas/SVG code (viaL_VARIANTS) and in pinned-dark instrument rooms. - Ink-based modal scrims.
rgba(var(--l-ink-rgb), .55)lightens the backdrop on dusk. UseSURFACE.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) | |
/system/og |
six per-domain 1200×630 OG cards | |
/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.