Skip to Content
Slloy Docs
Architecture, Design & Testing

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 (a Dark Default, b Pure Monochrome Light):
    • Default theme is fixed dark (a); users can manually toggle to light monochrome (b). It does not follow OS prefers-color-scheme automatically (legacy c theme is migrated to b by 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.
  • 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:1 in 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 use Sparkles.

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 NameCSS VariableDark (a)Monochrome (b)Usage
page--bg#08080a#ffffffPage background (and recessed inputs inside panels)
surface--surface#111114#ffffffCards and panels
surface-2--surface2#1a1a1f#f4f4f4Secondary button background (light), input areas
surface-hover--surface-hover#232329#e8e8e8Secondary control and menu item hover; segmented track inside floating surfaces
surface-float--surface-float#1a1a1f#ffffffDropdown menus, popovers, modals (tw:bg-surface-float tw:border tw:border-edge-float)
foreground--text#f4f3ef#000000Body copy and headings
muted--muted#a3a2a8#5c5c5cSecondary copy and disabled text
muted-strong--muted-strong#83828b#75757512–14px helper text achieving WCAG AA on surface
edge--border#24242a#e6e6e6Decorative dividers and card borders
edge-control--border-control#62616a#8f8f8fInteractive control borders (>= 3:1 contrast on bg and surface)
edge-float--border-float12% white#e6e6e6Floating layer borders and internal dividers
primary--primary#f4f3ef#000000Emphasized text, featured plan border, active nav text (not buttons/selected chips)
primary-dark--primary-dark#d9d7d0#333333Callout box dark text
primary-soft--primary-soft#1f1f25#f0f0f0Callout box and menu hover soft background
on-primary--on-primary#08080a#ffffffText on primary and danger
on-brand--on-brand#ffffff#ffffffText on --brand-fill
accent--accent#8b9cff#000000Links, indicator dots, and 2px focus rings
brand-soft / brand-soft-foreground--brand-soft / --brand-soft-foreground#1e1c3a / #b4bcff#f0f0f0 / #000000Model badges and credit pills
danger--danger#ff6b6b#c0392bDestructive actions
disabled--disabled-bg#2e2e35#d4d4d4Disabled button background (pair with muted text)
toast / toast-foreground--toast-bg / --toast-fg#f4f3ef / #08080a#000000 / #ffffffToast 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-control without changing background.
    • Focus: 2px accent focus ring with 2px offset.

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 / UtilityDesktop SizeMobile (<= 620px)Usage
--fs-h140–84px32px (--fs-ef-h1)Homepage hero headline
--fs-page-h130–44px26px (--fs-h2)Inner page H1
--fs-h2 / --fs-h2-sm26–38px / 24–36px24px / 20pxSection headings
tw:text-title-lg / md / sm36px / 28px / 24px28px / 24px / 20pxLarge numerals, prices, card titles
tw:text-h4 / tw:text-title-xs20px / 18px18px / 16.5pxCard titles (includes lh: 1.35, fw: 600)
tw:text-lead / tw:text-subhead18px / 17px16.5pxLead paragraph / subhead (subhead includes lh: 1.35, fw: 600)
tw:text-body16.5px14.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-copy14.5px13.5px (ui)Secondary copy, md control font size
tw:text-ui13.5px12.5px (note)Control labels, sm control font size
tw:text-note / caption / micro12.5px / 11.5px / 10.5px11.5px / 10.5px / 10.5pxNotes, captions, and badges (micro includes fw: 700)

Layout, Radius, Elevation, Z-Index & Breakpoints

  • Shell & Layout: --shell-w: 1160px, --shell-pad: 24px (mobile 16px), --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 banner 2147483000 is the sole hardcoded exception in consent.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-*, and backdrop-blur-* are banned in feature code. Only use tokens from tokens.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" }) from ui/button.ts (36px / 42px / 50px desktop, stepping down one notch on <= 620px). Never hand-write btn btn-* classes. Preserve marker classes (ec-btn, ec-ghost, cta, sck-primary) required by Playwright tests.
  • 10 Mandatory Base UI Constraints:
    1. DirectionProvider is provided once by components/locale-shell.tsx.
    2. SEO-critical hidden content must stay in the pre-rendered DOM (keepMounted on nav dropdowns and showcase tabs; hiddenUntilFound on components/faq.tsx accordions).
    3. Portals mount under <body>—never scope popup styles under parent container classes like .nav-dd .dd-menu.
    4. Apply z-index on the Positioner (.popup-positioner), not on the Popup.
    5. Use the render prop (Base UI has no asChild), and pass nativeButton={false} when rendering a Tabs.Tab as a non-button element.
    6. Menu and Select modal/overlay defaults are customized in ui/menu.tsx and ui/select.tsx.
    7. State attributes are data-popup-open, data-panel-open, data-active, data-checked, data-selected (never Radix data-state).
    8. Ref-dependent widgets inside modals (Google OAuth button, Turnstile) must live inside an inner body component (AuthModalBody) that mounts only when the dialog opens.
    9. Expose custom select values via data-value on the trigger and data-v on options.
    10. In Playwright tests, assert closed popups with toBeHidden() rather than checking post-close class names (closed popups unmount from the DOM).

On this page