Recommended model
Preference: Auto, Light, Dark.
Resolved appearance: Light or Dark.
Theme values: semantic roles mapped to each appearance.
Production explainer · Version 3.0
Theme the system.
Theme the system.
Not the screenshot.
A durable color-mode system separates user preference, resolved appearance, semantic meaning, and rendered values. Light and dark are complete palettes. Auto is the resolver that selects one.
Preference
Store Auto, Light, or Dark.
Resolution
Render only Light or Dark.
Tokens
Map semantic roles, never raw inversion.
Validation
Test every state and preference.
Decision
Adopt a two-palette, three-preference model.
Use semantic tokens as the contract. Auto is a live preference resolver, not a third palette.
Override precedence
- Explicit user choice.
- System preference when Auto is selected.
- Product fallback when neither is available.
Primary anti-pattern
Do not invert raw values. Reassign role-specific values for canvas, surfaces, text, borders, controls, focus, status, charts, and media.
Decision consequence
Components remain unaware of appearance mechanics. They consume stable semantic contracts while the theme layer supplies appropriate values.
Architecture
Separate stored intent from rendered state.
The distinction prevents Auto from becoming stale and lets analytics, debugging, browser chrome, and native controls remain synchronized.
Stored preferenceAuto
System inputLight
Resolved appearanceLight
Persist the preference
Store auto, light, or dark. Do not persist Auto’s current resolution as the source of truth.
For server rendering, mirror the preference in a cookie when first-paint consistency justifies the added state.
Synchronize four surfaces
- Authored CSS values.
- Browser-provided controls and scrollbars.
- Browser chrome through
theme-color. - Embedded media, charts, and assets.
Browser-chrome gap
Media-qualified theme-color follows the system preference. When the product offers an explicit in-page override, update the matching metadata so the browser UI follows the product selection rather than the operating system.
Semantic tokens
Name colors by responsibility.
Keep the knowledge model separate from component presentation through foundation, semantic, and component token layers.
Foundation
Raw ramps and color-space values.
--blue-600 · --neutral-950Semantic
Stable intent shared across products.
--color-action · --color-text-secondaryComponent
Local bindings and state decisions.
--button-primary-bg · --input-focus-ringMinimum semantic inventory
- Canvas and surfaces.
- Primary and secondary text.
- Subtle and control borders.
- Actions and selected states.
- Focus and interaction states.
- Success, warning, danger, info.
- Data visualization roles.
- Code and media surfaces.
Names that survive change
×
--white, --black, --light-grayThey describe appearance and become misleading across modes.
✓
--surface-raised, --text-muted, --border-controlThey preserve intent while values change.
Palette engineering
Create hierarchy without glare or collapse.
Both modes need readable text, distinguishable surfaces, explicit controls, coherent elevation, and tuned brand colors.
Use a tinted canvas and restrained extremes.
Surface 1
Primary cards and controls.
Surface 2
Nested or grouped regions.
Surface 3
Selected, code-adjacent, or inset regions.
Near-black text often reads more comfortably than absolute black. Separate decorative dividers from boundaries required to identify controls.
Reserve tonal room above the canvas.
Near-black canvas
Not every product needs OLED black.
Raised surface
Use tonal change before heavy shadow.
Nested surface
Maintain visible structure at low luminance.
Bright saturated accents can bloom against dark fields. Tune lightness and chroma independently rather than reusing the light-mode value.
Elevation
Use surface tone and border contrast first. Shadows are supplementary, especially in dark mode.
Transparency
Keep an opaque baseline. Contrast over uncontrolled translucent content is nondeterministic.
True black
Reserve it for media, cinematic surfaces, or an explicit OLED profile rather than making it the universal dark canvas.
Contrast and states
Validate rendered pairs, not isolated swatches.
WCAG 2.2 remains the production conformance gate. Emerging algorithms can supplement design analysis but do not replace current compliance.
| Content | WCAG 2.2 AA | Preferred product target | Operational note |
|---|---|---|---|
| Normal text | 4.5:1 | 7:1 when practical | Includes meaningful secondary and helper text. |
| Large text | 3:1 | 4.5:1 | Approximately 24px regular or 18.66px bold. |
| Essential UI boundaries and graphics | 3:1 | 3.5–4.5:1 | Decorative separators are evaluated differently. |
| Focus indication | Visible and unobscured | Two-color, multi-surface ring | Focus Appearance adds stronger AAA guidance. |
Interactive check
Contrast laboratory
WCAG 2.x sRGB ratio for opaque hex colors.
Readable interface text
Secondary information still carries meaning.
17.13:1
AA normal
AAA normal
AA large
Muted is not exempt
Dates, metadata, help text, breadcrumbs, and status explanations remain meaningful text.
Disabled is a state
Inactive controls may be exempt from specific contrast criteria, but should remain identifiable and understandable.
Color is redundant
Pair hue with text, icons, shape, pattern, position, or accessible status announcements.
contrast-color() requires guardrailsIt is newly available in Baseline 2026, but currently resolves only to black or white. Mid-tone backgrounds can still produce inadequate small-text results. Restrict input ranges, provide fallbacks, and validate the final pair.
WCAG 3 and supplemental contrast analysis
WCAG 3.0 remains a Working Draft and does not replace WCAG 2.2. Use alternative perceptual contrast methods as design-analysis signals only. Keep WCAG 2.2 AA as the formal production gate until applicable standards and policy change.
Color profiles and spaces
Author perceptually. Ship interoperably.
sRGB is the required baseline. OKLCH improves palette construction. Display P3 and HDR are progressive enhancements, not correctness dependencies.
Three complementary roles
sRGB: compatibility, remote desktops, screenshots, mixed displays, and default UI assets.
OKLCH: perceptual lightness, coherent ramps, interpolation, and independent chroma control.
Display P3: additional gamut for supported devices after the sRGB path already works.
Illustrative OKLCH ramp
Perceptual lightness makes systematic ramps easier to reason about than HSL. Equal lightness does not guarantee equal WCAG contrast.
→
Dual validation
Validate the sRGB fallback and wide-gamut override independently. Gamut mapping can change the final rendered result.
color-gamut
Indicates approximate device and user-agent gamut support. It does not prove display calibration or exact appearance.
ICC handling
Embed appropriate profiles in raster assets. Verify optimization, screenshot, PDF, and export paths do not strip or reinterpret them.
HDR
Keep core UI in SDR. Reserve HDR for media and specialized visualization where hardware variability and glare are explicitly managed.
Browser and native UI
Theme the interface you do not fully control.
color-scheme affects native controls, scrollbars, spellcheck indicators, the canvas, and other browser-rendered UI.
Current appearance
accent-color is useful progressive enhancement, but current compatibility is not universal. Native controls must remain usable when it is ignored.
Browser-chrome contract
1
Declare supported schemes early
Use the color-scheme metadata before CSS to reduce mismatched initial canvas flashes.
2
Declare CSS support
Use :root { color-scheme: light dark; } so browser-provided controls can adapt.
3
Update explicit overrides
Synchronize theme-color and any theme-aware favicon or manifest behavior.
Images, logos, charts, and embedded documents
Prefer adaptable assets
- Use
currentColorfor monochrome SVG icons. - Define chart roles rather than hard-coded series colors.
- Provide light and dark logo treatments when the brand mark requires them.
- Test transparent PNG edges on both canvases.
Choose robust switching
- Use CSS or
<picture media>for essential art direction. - Treat newer
light-dark()image support as progressive until your browser matrix is verified. - Check cross-origin SVG and iframe color-scheme behavior explicitly.
Typography rendering
Let the platform rasterize text.
Font smoothing hacks are non-standard and can thin glyphs, especially bright text on dark backgrounds. Optimize font selection and metrics instead.
Recommended
✓
Platform-default antialiasing
Omit global font-smoothing overrides.
✓
font-optical-sizing: autoUse the font’s optical-size axis when available.
✓
Real faces and tested fallbacks
Provide intended weights and scripts; avoid accidental synthetic styling.
Avoid
×
Global WebKit smoothing rules
-webkit-font-smoothing is non-standard and platform-specific.
×
Global
optimizeLegibilityUse rendering hints only after controlled cross-browser tests.
×
Disabling text adjustment
Preserve mobile and user-level text scaling behavior.
→
Dark-mode review
Test small text at ordinary pixel density and 100%, 125%, 150%, and 200% scaling. Avoid compensating for weak contrast with thinner type.
Scrolling and viewport
Preserve native physics and visibility.
Native scrolling protects keyboard behavior, touch momentum, history restoration, find-in-page, and assistive-technology expectations.
Smooth anchors
Use smooth behavior for navigation, not for direct wheel or touch control. Disable it under reduced motion.
Sticky offsets
Use scroll-padding and scroll-margin so focused and linked content is not obscured.
Stable gutters
scrollbar-gutter: stable reduces width shifts where classic scrollbars consume layout space.
Local containment
Apply overscroll containment to nested panes only when scroll chaining is undesirable.
×
Avoid scroll-jacking
Do not replace native scrolling with transform-driven canvases, wheel interception, or mandatory full-page snapping for ordinary content.
Evidence S21
User preference matrix
Dark mode is not high-contrast mode.
Color scheme, contrast, forced colors, motion, transparency, data use, gamut, and dynamic range represent distinct adaptation dimensions.
Preference signals
System color scheme
Contrast preference
Forced colors
Reduced motion
Reduced transparency
Color gamut
Dynamic range
Adaptation priority
1Forced colors: allow user-agent colors and use system color keywords for remaining authored properties.
2More contrast: strengthen boundaries, secondary text, and focus rather than only changing the canvas.
3Reduced motion: remove non-essential animation and smooth scrolling.
4Reduced transparency: replace blur and translucent materials with opaque surfaces.
!
Compatibility distinction
forced-colors and prefers-contrast are broadly available. prefers-reduced-transparency remains experimental and limited, so the opaque design must be the dependable baseline.
Implementation
Use modern CSS with explicit fallbacks.
The production pattern below uses native scheme negotiation, semantic tokens, one compact theme control, persisted preference, and synchronized browser chrome.
Feature support in this browser
light-dark()Checkingcontrast-color()Checkingoklch()Checkingcolor(display-p3)Checkingscrollbar-gutterCheckingCompatibility posture
- Core: semantic tokens, sRGB fallbacks, WCAG 2.2, native scrolling.
- Modern baseline:
light-dark(), OKLCH, P3 detection. - Guarded:
contrast-color()for constrained backgrounds. - Progressive: reduced transparency, HDR, advanced image switching.
Production CSS baseline
:root {
color-scheme: light dark;
/* sRGB fallbacks first */
--canvas: #f7f8fb;
--surface: #ffffff;
--text-primary: #171b23;
/* Modern adaptive values */
--canvas: light-dark(#f7f8fb, #0d1016);
--surface: light-dark(#ffffff, #171c25);
--text-primary: light-dark(#171b23, #f2f5f9);
--text-secondary: light-dark(#4d5766, #bac3cf);
--border-control: light-dark(#909aa9, #697687);
--action: light-dark(#155eef, #8eb8ff);
--focus: light-dark(#005fcc, #9fc5ff);
}
:root[data-theme="light"] { color-scheme: only light; }
:root[data-theme="dark"] { color-scheme: only dark; }
html {
text-size-adjust: 100%;
-webkit-text-size-adjust: 100%;
scrollbar-gutter: stable;
scroll-padding-block-start: var(--sticky-offset, 4.75rem);
scroll-behavior: smooth;
}
body {
background: var(--canvas);
color: var(--text-primary);
font-optical-sizing: auto;
text-rendering: auto;
}
@media (prefers-reduced-motion: reduce) {
html { scroll-behavior: auto; }
}
@media (prefers-contrast: more) {
:root { --text-secondary: var(--text-primary); }
}
@media (forced-colors: active) {
:focus-visible { outline-color: Highlight; }
}Preference resolution and browser-chrome synchronization
type ThemePreference = "auto" | "light" | "dark";
type ResolvedTheme = "light" | "dark";
const systemDark = matchMedia("(prefers-color-scheme: dark)");
function resolveTheme(preference: ThemePreference): ResolvedTheme {
if (preference === "auto") {
return systemDark.matches ? "dark" : "light";
}
return preference;
}
function applyTheme(preference: ThemePreference): void {
const resolved = resolveTheme(preference);
document.documentElement.dataset.theme = preference;
document.documentElement.dataset.resolvedTheme = resolved;
// Synchronize browser chrome with explicit overrides.
lightThemeMeta.media = preference === "dark" ? "not all" :
preference === "light" ? "all" : "(prefers-color-scheme: light)";
darkThemeMeta.media = preference === "light" ? "not all" :
preference === "dark" ? "all" : "(prefers-color-scheme: dark)";
}
Validation and governance
Test a state matrix, not a screenshot.
Theme quality depends on transitions, preference combinations, rendering environments, content stress, and first-paint behavior.
Appearance
✓Auto, Light, Dark.
✓System change while Auto is active.
✓First paint and hydration.
✓Browser chrome and native UI.
Accessibility
✓WCAG 2.2 contrast.
✓Forced colors and more contrast.
✓Reduced motion and transparency.
✓Keyboard focus and zoom.
Rendering
✓sRGB and P3 devices.
✓Ordinary and high-density screens.
✓Windows, macOS, iOS, Android.
✓Safari, Chrome, Edge, Firefox.
Content stress
- Long and localized text.
- Empty, loading, error, success, disabled, selected.
- Transparent images and brand marks.
- Charts, syntax highlighting, and data density.
- Print, screenshot, PDF, remote desktop.
Release gates
- No unpaired semantic foreground/background tokens.
- No control state relies on color alone.
- No explicit theme causes browser-chrome mismatch.
- No essential information depends on wide gamut, HDR, blur, or animation.
- Provenance and compatibility assumptions are current.
Provenance
Evidence is part of the artifact.
The document includes visible citations, section-level source mappings, structured metadata, a machine-readable provenance manifest, and explicit evidence classes.
Standards and WCAG requirements.
Browser behavior and compatibility.
Design-system and operating-system guidance.
Draft or limited-availability features.
Document record
- Created
- 18 July 2026
- Rebuilt
- 21 July 2026
- Version
- 3.0
- Generator
- OpenAI
Method and limitations
Normative standards are treated as the source of truth. MDN is used for implementation and Baseline status. Platform guidance is advisory. Browser support and draft specifications can change after the research date.
This explainer does not constitute an automated accessibility conformance report. Real-device, assistive-technology, and product-context validation remain required.