Capstone: Dark/Light Theme Platform

Introduction

Capstone: dark/light theme platform builds system-aware theming with prefers-color-scheme, manual override, persistence, no flash of wrong theme (FOWT), and semantic tokens that swap under [data-theme]. Covers color-scheme property, native form controls in dark mode, image treatment, and chart color tokens — the full theme architecture Spotify and GitHub ship.

Business problem

Business pressure: Users expect theme sync with OS plus manual toggle; flash of light theme on dark preference erodes premium feel; charts and images need theme-specific treatment.

• a11y: Both themes must pass contrast — not just light mode.
• Perf: Theme swap must not reload page or leak styles.

Why this feature exists

Platform history: CSS evolved theme platform CSS to solve author needs without JavaScript layout engines or table hacks.

• Problem solved: Declarative styling separated from document structure.
• Rejected alternative: Inline styles and JS layout — unmaintainable at enterprise scale.

Browser rendering perspective

FOWT prevention: Inline script in head: read localStorage theme → set data-theme on html before body parse. Use color-scheme so scrollbars and inputs match.

• Images: picture/source or CSS filter: none in dark for photos; logos as SVG with currentColor.

Internal browser workflow

Workflow: Selector match → cascade → computed values → layout tree → paint layers → composite.

Feature deep dive

Theme architecture: color-scheme on html; semantic tokens; [data-theme=light|dark|system]; inline blocking script sets data-theme before paint from localStorage + matchMedia.

html { color-scheme: light dark; }
:root, [data-theme="light"] {
  --surface: #fff;
  --text: #111;
  --border: #e5e5e5;
}
[data-theme="dark"] {
  --surface: #0d1117;
  --text: #e6edf3;
  --border: #30363d;
}
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --surface: #0d1117;
    --text: #e6edf3;
  }
}

Real production example

Production: Netflix, Amazon, and Shopify enforce theme platform CSS patterns via design tokens, lint rules, and visual regression CI.

Enterprise use case

Enterprise: Design systems (Polaris, Carbon, Atlassian) codify theme platform CSS in token pipelines and component APIs.

Accessibility considerations

A11y: Theme toggle is button with aria-pressed; both themes tested with axe; focus ring token visible on dark surfaces.

Performance considerations

Performance: theme platform CSS can trigger reflow, expensive selectors, or layer explosion — profile with DevTools Performance panel.

SEO considerations

SEO: CSS affects LCP, CLS, and mobile usability — ranking signals tied to Core Web Vitals.

Scalability considerations

Scale: theme platform CSS choices compound across micro-frontends, white-label tenants, and dark-mode variants.

Common production issues

Production failures: Specificity wars, z-index stacks, and responsive breakpoints that work in Chrome but break Safari.

Debugging guide

Debug: Chrome DevTools → Elements (computed styles), Layout panel, Rendering layers, Coverage for unused CSS.

Best practices

• Semantic tokens — never hardcode dark colors in components.
• color-scheme property on root.
• Blocking inline script for FOWT prevention.
• Test contrast in both themes before ship.
• chart-* tokens for data visualization consistency.

Anti-patterns

• Separate duplicate stylesheets for themes — drift guaranteed.
• Theme toggle only via class on body without token swap plan.
• Ignoring prefers-color-scheme when user picks system.

Trade-offs

• Inline script vs SSR cookie: Script fixes static hosting; cookie fixes SSR — pick for your deploy target.
• Image filters vs dual assets: Filters fast; dual assets accurate for brand logos.

Hands-on exercise

Capstone deliverable — theme platform: Complete theme system with app demo.

• Phase 1 — Tokens: Full semantic token set for light and dark (surface, elevated, text, muted, border, action, danger, chart-1..5).
• Phase 2 — No flash: Inline head script + localStorage key theme-preference; support light | dark | system; document FOWT test procedure.
• Phase 3 — UI demo: Page with nav, cards, form controls, code block, chart placeholders using chart tokens — all respond to theme swap instantly.
• Phase 4 — System sync: When preference is system, listen to prefers-color-scheme change and update without reload.
• Phase 5 — Media: At least one image handled differently per theme (border, opacity, or separate asset).
• Phase 6 — QA: axe both themes; contrast report for all text/background pairs; screen recording toggling themes with no flash on hard refresh.
• Submission: Repo + THEME.md architecture doc + contrast spreadsheet + demo deploy URL.

Try it yourself

Edit the CSS panel — the preview updates live. Use DevTools Performance and Accessibility panels to validate.

Summary

Theme platform capstone delivers semantic dual-theme tokens, FOWT-free persistence, system preference sync, and chart/media treatment — complete dark/light CSS architecture.

Key takeaways

• Theme platforms are token + FOWT + system sync problems.
• Both themes must pass a11y — not an afterthought.