// OPENBOX DOCS

Design system

The real CSS variables, typography, layout, and component specs for theme authoring.

OpenBoxGL's base stylesheet uses a dark, warm game-room palette: near-black surfaces, warm off-white text, brand orange (#FF7A1A) for selection and the action ramp, and teal (#5FD3C4) as the keyboard-focus signal. This page documents the actual variables shipped in the application's static/app.css (linked from index.html), not a separate token layer. Theme authors override these variables in a CSS file imported through Themes.

Base palette

All colors are dark by default. Neutral surfaces carry most of the screen; the orange family identifies selection and the launch action, while teal marks keyboard focus.

Neutral surfaces

TokenValueUse
--bg#0F0E0CPage canvas, deepest fullscreen surfaces
--topbar#151310Command rail background
--panel#1A1815Sidebar, detail pane, dialogs, lifecycle surfaces
--surface-deep#0B0A09Sticky library header and tools menu background
--surface-card#1F1C18Detail cards, emulator items, result rows, history items
--surface-field#26221DForm controls, secondary buttons
--surface-hover#322C24Hovered raised panels
--border-control#786B58Control borders
--border-card#5E5345Card and dialog borders
--line#3A342CBorders, dividers, separator rules
--text#F6F0E7Primary titles, high-priority content
--muted#B4A897Metadata, labels, helper copy, inactive navigation

Accent colors

TokenValueUse
--focus#5FD3C4Focus ring, focused controls
--brand#FF7A1ABrand identity color
--active#FF7A1AActive navigation, selected cover borders, Big Box cover borders
--action#F58A2ELaunch action (Play button), primary dialog confirmations
--action-ink#1A120ADark text inside the orange action surface
--white#fffOccasional pure white highlights
--cyan#5FD3C4Teal accent (defined in :root)
--gold#F2C14EAchievement/gold signal, decorative highlights
--rating#F2A65ARating star signal
--launch-shadow#FF7A1A44Shadow tint under the Play button
--danger#B8473FError/destructive state
--empty-action#F58A2EEmpty-state action buttons
--cover-title-start#3A2A1CCover gradient start tone
--achievement#F2B55CRetroAchievements badge, achievement points
--lifecycle-bg#3A2A18Session lifecycle overlay background
--bigbox-bg#241A10Big Box cover backdrop
--bigbox-copy#D8C7AFBig Box secondary text
--overlay-insight-cell-0#1B1916Play Insights 0-playtime cell background
--overlay-insight-cell-1#4A2E1CPlay Insights level 1 playtime cell background
--overlay-insight-cell-2#8A451APlay Insights level 2 playtime cell background
--overlay-insight-cell-3#CC5F17Play Insights level 3 playtime cell background
--overlay-insight-cell-4#FF7A1APlay Insights level 4 (peak) playtime cell background
--border-insight#4b4338Play Insights heatmap and stat card borders
--shadow-insight#0007Play Insights card shadow
--surface-insight-card#211e1aPlay Insights card surface background
--focus-ring#000000Play Insights peak (level 4) cell border

Typography

The base stack is system-ui, sans-serif (no bundled webfont in the base stylesheet). Font sizes come from --font-* variables.

TokenValueUse
--font-micro10pxTiny counters, badge numbers
--font-label12pxSection labels, field labels, nav categories
--font-meta12pxRelease year, region tags, auxiliary metadata
--font-body-small13pxInline hints, status chips
--font-body14pxDefault application copy, form content
--font-action15pxButton labels, chip text
--font-dialog16pxDialog body
--font-title-large18pxGame card titles
--font-heading24pxSection headings
--font-brand0.9375remApp title strip, breadcrumbs
--font-nav0.8125remTopbar menu items, sidebar row labels
--font-subtitle19pxDialog section headers
--font-bigbox21pxBig Box body
--font-panel-title28pxBig Box panel headers
--font-bigbox-displayclamp(38px,5vw,72px)Big Box headings
--font-screensaverclamp(44px,8vw,110px)Screensaver statements

The lifecycle overlay uses a hardcoded clamp(34px,6vw,78px) rather than a --font-* variable.

Stock themes override the design tokens in their own :root blocks. Do not assume a bundled webfont or a theme-specific font family; the base stylesheet's available system stack remains the typography fallback unless the running source explicitly declares another stack.

Spacing

The base :root exposes a spacing scale — --space-* (--space-3xs through --space-2xl), --gap-* (--gap-micro, --gap-tight, --gap-default, --gap-loose, --gap-spacious), --stack-* (--stack-xs/sm/md), and --leading-* (--leading-tight/normal/relaxed) — plus --inset-* and --measure-*. Rules consume these tokens (e.g. padding: var(--space-2xs) var(--space-xs)); when you add custom CSS, derive spacing from these scale tokens rather than inventing new units.

Rounded corners

Four --radius-* base tokens exist, alongside *-radius component tokens (e.g. --moments-radius, which aliases --radius-cover). Other radii are hardcoded in the rules that use them.

TokenValueApplies to
--radius-hairline2pxThin decorative lines, narrow separators
--radius-cover5pxGame cover art containers
--radius-panel12pxBig Box panels, large panels
--radius-pill-large28pxBig Box play/pill buttons

Hardcoded values in the base: inputs use 4px (some 3px), cards and detail panels use 6px to 8px, dialogs use 8px, the Play button uses 18px (pill).

Layout

The shell is a three-column workspace with responsive breakpoints:

BreakpointSidebarLibraryDetail Pane
Default190pxminmax(520px, 1fr)410px
≤ 1120px150px1fr340px
≤ 760pxStacked above libraryStackedStacked below grid

Cover grid

Auto-filled columns with a minimum cover width of 132px (105px at ≤ 1120px, 100px at ≤ 760px). Covers keep the aspect ratio of each image: portrait, square, and landscape box art all render uncropped. Games without artwork fall back to a portrait 0.72 box with the title centered. The default grid gap is 24px 16px (row then column); the sticky header keeps collection title, sort, image group, and view actions visible while the grid scrolls.

Big Box compositions

LayoutComposition
StageOne large cover + description + big Play button; controller footer hints
HybridPlatform rail on left + games + scoped search field
CoverFlowHorizontal jewel-case cover strip; active cover straightens and scales

Shadows

Depth comes from tonal layering first, tokens second. The real token values in the base stylesheet (ADR 0004):

TokenValueRole
--shadow-cover#0006Default card and box art elevation shadow
--shadow-cover-strong#0007Hovered and raised card shadow
--shadow-cover-selected#000aSelected and focused card shadow
--shadow-dialog#000cModal dialog backdrop shadow
--shadow-elevated#0009Drawer and floating menu elevation
--shadow-empty#0005Empty-state container shadow
--accent-ghost#FF7A1A55Strong translucent focus halo
--accent-ghost-soft#FF7A1A44Medium focus glow
--accent-ghost-faint#FF7A1A2ESubtle focus glow
--overlay-backdrop#050403d9Dialog and modal screen overlay
--overlay-backdrop-strong#05070bd9Darkened backdrop overlay
--overlay-backdrop-soft#05070bccSoft dimmed background overlay
--overlay-screensaver-start#05070bcfScreensaver top gradient
--overlay-screensaver-mid#05070b1fScreensaver middle gradient
--surface-sheet#171513ddTranslucent bottom sheet surface
--border-sheet#ffffff55Sheet border highlight
--hero-scrim#0d0b0815Hero banner gradient tint

Component specs

Buttons

VariantBackgroundText colorRadiusPadding
Launch (Play)var(--action) → #F58A2Evar(--action-ink) → #1A120APill (18px)10px
Primaryvar(--action) → #F58A2Evar(--action-ink)4px9px 16px
Secondaryvar(--surface-field) → #26221Dvar(--text)4px(rule-specific)

Hover shifts secondary toward a lighter raised surface. Focused controls gain a 2px focus border (var(--focus)) plus a one-pixel ring.

Chips and badges

Rating, status, and ESRB chips use muted text on card surfaces. Achievement signals use --achievement (#F2B55C). Badges stay subordinate to cover art and the launch action.

Cards

ElementRadiusPaddingBackground
Cover cardvar(--radius-cover) (5px)12pxGradient (#3A2A1C → #171410) or raised surface
Detail card6px to 8px12pxvar(--surface-card)
Big Box panelvar(--radius-panel) (12px)24px to 26pxvar(--bigbox-bg) / var(--panel)

Inputs / Fields

Fields use --surface-field background, --border-control border, 4px radius, and 7px 8px padding. On focus, the border shifts to --focus (#5FD3C4) and gains a one-pixel ring. Disabled actions reduce opacity and show not-allowed cursor. No separate error palette exists in the base system; errors reuse the standard flow with a textual message rather than a colored field.

Topbar items are borderless and transparent at rest, gaining a raised background on hover. Active platform rows use a darker panel tone with a small orange marker dot. Inactive navigation is muted and transparent. The rail scrolls horizontally; the workspace columns tighten at 1120px and stack below 760px.

Big Box specifics

Big Box reuses the palette and typography tokens, then scales them:

  • Titles use --font-bigbox-display (clamp 38-72px) and the screensaver uses --font-screensaver (clamp 44-110px).
  • Controller footer hints use the --font-label weight mapped to the currently pressed button.
  • Jewel-case perspective on CoverFlow uses CSS transforms, not asset files.
  • Background music (library_music setting path) plays under covers; video_bgm_mix lowers volume when video audio is present.

Light theme note

Harbor Light is the only bundled light theme. It overrides --bg, --panel, --line, --text, --muted, --cyan, --accent, and --danger with paper tones. Note --accent is part of the base contract: it defaults to var(--active) and is consumed for focus rings, skeleton shimmer, and --mood-secondary. If you author a light theme, ensure --focus, --active, --action, and --action-ink remain legible against your light surfaces and that text contrast stays at least 4.5:1.

Token contract

The :root block in static/app.css is the theme contract. Every stock theme overrides :root and (almost) nothing else:

  • themes/Cinema Marquee.css
  • themes/Harbor Light.css (the only bundled light theme)
  • themes/High Contrast.css (added in 1.15.0; dark, pure-black base)
  • themes/Midnight Circuit.css
  • themes/Nordic Mist.css
  • themes/Phosphor Terminal.css

scripts/check_tokens.py enforces the contract in CI: raw hex outside :root must stay at the ratcheted baseline of 0. A new visual value means a new :root token plus its entry in each of the six theme files. For the full per-token table, read the :root block in static/app.css in the repository you are running — this page documents the palette groups, not a frozen count of names.

Feature token families (introduced in v1.9.0)

  • Mood Match: --mood-primary, --mood-ink, --mood-secondary (aliases --accent), --mood-glow (aliases --accent-ghost), --mood-tint, --mood-transition. Driven live from the selected cover when mood_match_enabled / mood_match_bigbox are on.
  • Constellation: --constellation-edge-series, --constellation-edge-developer, --constellation-edge-publisher, --constellation-edge-genre, --constellation-edge-platform_family, --constellation-edge-co_played.
  • Mastery Map: --mastery-never, --mastery-played, --mastery-beaten, --mastery-completed, --mastery-mastered.
  • --accent: defined by the base stylesheet as var(--active) and consumed for focus rings, skeleton shimmer, and --mood-secondary — themes may override it directly.
  • Themes for the six stock CSS themes and the import workflow
  • How OpenBoxGL works for how tokens render at runtime
  • static/app.css in the application repository for the authoritative :root block