Public Site Design System & Tokens
Complete token specification, dark/monochrome themes, typography scale, Base UI constraints, Motion transitions, and design-tokens test enforcement.
This specification covers the Slloy Public Site (frontend/site/). The /admin console uses frontend/admin/'s independent shadcn/ui configuration and does not share tokens or bundles with the public site.
Single Source of Truth: frontend/site/design-system/DESIGN.md and frontend/site/styles/tokens.css (mapped to Tailwind tw: utilities in styles/site.css @theme inline and enforced automatically in CI by tests/tools/design-tokens.test.ts).
1. Visual Philosophy & Core Rules
- Restrained Gallery Aesthetic: The UI recedes so generated images and videos take center stage.
- Two Themes Only (
aDark Default,bPure Monochrome Light):- Default theme is fixed dark (
a); users can manually toggle to light monochrome (b). It does not follow OSprefers-color-schemeautomatically (legacyctheme is migrated tobby the root script). - In dark theme (
a), the brand blue-purple gradient (--brand-fill) is used only for primary buttons, active selections, and small accents—never for cards or large surface fills. - In light theme (
b), the palette is pure black and white (#000000/#ffffff) with zero color accents. - Only one primary CTA (
buttonClass({ variant: "primary" })) should appear per viewport.
- Default theme is fixed dark (
- WCAG AA Contrast & RTL Direction:
- Body text and small labels meet WCAG AA (
>= 4.5:1); control borders (--border-control) and focus rings (--accent) meet>= 3:1in both themes. - Exclusively use CSS logical properties (
margin-inline-start,tw:ps-3,tw:pe-3) so Arabic (ar) and Hebrew (he) RTL layouts work natively. Directional Lucide icons (arrows) must flip in RTL; generation triggers always useSparkles.
- Body text and small labels meet WCAG AA (
2. Semantic Color Tokens (tokens.css)
Never write literal hex/RGB values in components or feature stylesheets. Use semantic utilities (tw:bg-page, tw:text-foreground, tw:border-edge):
| Utility Name | CSS Variable | Dark (a) | Monochrome (b) | Usage |
|---|---|---|---|---|
page | --bg | #08080a | #ffffff | Page background (and recessed inputs inside panels) |
surface | --surface | #111114 | #ffffff | Cards and panels |
surface-2 | --surface2 | #1a1a1f | #f4f4f4 | Secondary button background (light), input areas |
surface-hover | --surface-hover | #232329 | #e8e8e8 | Secondary control and menu item hover; segmented track inside floating surfaces |
surface-float | --surface-float | #1a1a1f | #ffffff | Dropdown menus, popovers, modals (tw:bg-surface-float tw:border tw:border-edge-float) |
foreground | --text | #f4f3ef | #000000 | Body copy and headings |
muted | --muted | #a3a2a8 | #5c5c5c | Secondary copy and disabled text |
muted-strong | --muted-strong | #83828b | #757575 | 12–14px helper text achieving WCAG AA on surface |
edge | --border | #24242a | #e6e6e6 | Decorative dividers and card borders |
edge-control | --border-control | #62616a | #8f8f8f | Interactive control borders (>= 3:1 contrast on bg and surface) |
edge-float | --border-float | 12% white | #e6e6e6 | Floating layer borders and internal dividers |
primary | --primary | #f4f3ef | #000000 | Emphasized text, featured plan border, active nav text (not buttons/selected chips) |
primary-dark | --primary-dark | #d9d7d0 | #333333 | Callout box dark text |
primary-soft | --primary-soft | #1f1f25 | #f0f0f0 | Callout box and menu hover soft background |
on-primary | --on-primary | #08080a | #ffffff | Text on primary and danger |
on-brand | --on-brand | #ffffff | #ffffff | Text on --brand-fill |
accent | --accent | #8b9cff | #000000 | Links, indicator dots, and 2px focus rings |
brand-soft / brand-soft-foreground | --brand-soft / --brand-soft-foreground | #1e1c3a / #b4bcff | #f0f0f0 / #000000 | Model badges and credit pills |
danger | --danger | #ff6b6b | #c0392b | Destructive actions |
disabled | --disabled-bg | #2e2e35 | #d4d4d4 | Disabled button background (pair with muted text) |
toast / toast-foreground | --toast-bg / --toast-fg | #f4f3ef / #08080a | #000000 / #ffffff | Toast notifications |
- Theme-Invariant Media Overlays: Content overlaid on artwork/video uses
tw:text-on-media(--on-media),--on-media-muted,--on-media-ink,--media-bg, and--media-chip-bg. - State Hierarchy:
- Primary CTA & Active Selection:
--brand-fill+tw:text-on-brand(tw:[background:var(--brand-fill)] tw:border-transparent tw:text-on-brand). - Unselected Hover: Switches border to
edge-controlwithout changing background. - Focus:
2pxaccentfocus ring with2pxoffset.
- Primary CTA & Active Selection:
3. Typography, Spacing, Radius, Elevation & Z-Index
Typography Scale (--font-body System Stack Only, Weights 400, 600, 700)
No web fonts are loaded. tw:font-extrabold is blocked by tests. On mobile (<= 620px), the entire scale steps down one notch automatically via media queries in tokens.css:
| Token / Utility | Desktop Size | Mobile (<= 620px) | Usage |
|---|---|---|---|
--fs-h1 | 40–84px | 32px (--fs-ef-h1) | Homepage hero headline |
--fs-page-h1 | 30–44px | 26px (--fs-h2) | Inner page H1 |
--fs-h2 / --fs-h2-sm | 26–38px / 24–36px | 24px / 20px | Section headings |
tw:text-title-lg / md / sm | 36px / 28px / 24px | 28px / 24px / 20px | Large numerals, prices, card titles |
tw:text-h4 / tw:text-title-xs | 20px / 18px | 18px / 16.5px | Card titles (includes lh: 1.35, fw: 600) |
tw:text-lead / tw:text-subhead | 18px / 17px | 16.5px | Lead paragraph / subhead (subhead includes lh: 1.35, fw: 600) |
tw:text-body | 16.5px | 14.5px (copy) | Body prose (article prose uses --fs-prose-h2: 26px, --fs-prose-h3: 20px, --fs-prose-h4: 17.5px, --lh-prose: 1.62) |
tw:text-copy | 14.5px | 13.5px (ui) | Secondary copy, md control font size |
tw:text-ui | 13.5px | 12.5px (note) | Control labels, sm control font size |
tw:text-note / caption / micro | 12.5px / 11.5px / 10.5px | 11.5px / 10.5px / 10.5px | Notes, captions, and badges (micro includes fw: 700) |
Layout, Radius, Elevation, Z-Index & Breakpoints
- Shell & Layout:
--shell-w: 1160px,--shell-pad: 24px(mobile16px),--prose-w: 760px,--sp-sec-head: 52px,--sp-section-sm: 64px,--sp-section: 88px. - Border Radius:
tw:rounded-control(--ds-radius-control: 4px),tw:rounded-panel(--ds-radius-panel: 6px),tw:rounded-full(--radius-full: 999px, strictly for circular avatars/toggles). - Elevation Shadows:
tw:shadow-raised,tw:shadow-menu,tw:shadow-popover,tw:shadow-modal,tw:shadow-bar,tw:shadow-glow. - Z-Index Scale:
--z-sticky: 40,--z-drawer: 49,--z-nav: 50,--z-dropdown: 60,--z-toast: 99,--z-modal: 100,--z-lightbox: 9999(cookie banner2147483000is the sole hardcoded exception inconsent.css). - Breakpoints:
tw:max-phone-sm:(360px),tw:max-phone:(620px),tw:max-tablet:(860px),tw:max-desktop:(1040px),tw:max-nav:(1101px). - Gradients & Blurs: Literal gradients, literal
backdrop-filter,bg-linear-*, andbackdrop-blur-*are banned in feature code. Only use tokens fromtokens.css(--scrim-hero,--scrim-card,--scrim-reveal,--scrim-caption,--wb-bg-veil,--stage-ink-shadow,--cover-image,--cover-video,--mask-fade-*,--brand-fill,--blur-bar,--blur-panel).
4. Component Architecture: Base UI & Motion Rules
Interactive primitives live in frontend/site/components/ui/ and wrap Base UI (@base-ui/react/*) and Motion (import * as m from "motion/react-m" under strict MotionProvider):
- Buttons: Always use
buttonClass({ variant: "primary" | "light" | "outline" | "subtle" | "danger", size: "sm" | "md" | "lg" })fromui/button.ts(36px/42px/50pxdesktop, stepping down one notch on<= 620px). Never hand-writebtn btn-*classes. Preserve marker classes (ec-btn,ec-ghost,cta,sck-primary) required by Playwright tests. - 10 Mandatory Base UI Constraints:
DirectionProvideris provided once bycomponents/locale-shell.tsx.- SEO-critical hidden content must stay in the pre-rendered DOM (
keepMountedon nav dropdowns and showcase tabs;hiddenUntilFoundoncomponents/faq.tsxaccordions). - Portals mount under
<body>—never scope popup styles under parent container classes like.nav-dd .dd-menu. - Apply
z-indexon the Positioner (.popup-positioner), not on the Popup. - Use the
renderprop (Base UI has noasChild), and passnativeButton={false}when rendering aTabs.Tabas a non-button element. MenuandSelectmodal/overlay defaults are customized inui/menu.tsxandui/select.tsx.- State attributes are
data-popup-open,data-panel-open,data-active,data-checked,data-selected(never Radixdata-state). - Ref-dependent widgets inside modals (Google OAuth button, Turnstile) must live inside an inner body component (
AuthModalBody) that mounts only when the dialog opens. - Expose custom select values via
data-valueon the trigger anddata-von options. - In Playwright tests, assert closed popups with
toBeHidden()rather than checking post-close class names (closed popups unmount from the DOM).
Backup, Rollback & Disaster Recovery Runbook
Recovery runbooks for Cloudflare Worker code rollbacks, append-only R2 media backups (rclone copy), quarterly Neon 7-day PITR drills, and DLQ inspection.
Reference Image Preprocessing & Trust Boundary
Browser-side EXIF/sRGB/white-background normalization (image-prep.ts) paired with low-cost Worker header sniffing (imageSniff.ts).