customization.md

Customization

browserux.css is customized through CSS custom properties. Load BrowserUX first, then override tokens in your own stylesheet.

---

Override semantic tokens

Prefer semantic tokens over raw palette tokens:

:root {
  --bux-color-accent: #7c3aed;
  --bux-color-accent-2: #06b6d4;
  --bux-font-size: 1.8rem;
}

Tokens such as --bux-color-accent-soft, --bux-focus-color, and --bux-selection-bg are derived from semantic tokens in browsers that support color-mix().

---

Override light and dark values

BrowserUX uses light-dark() where supported. You can use the same pattern:

@supports (color: light-dark(white, black)) {
  :root {
    --bux-color-bg: light-dark(#f7f7f7, #101010);
    --bux-color-text: light-dark(#111111, #f2f2f2);
    --bux-color-accent: light-dark(#7c3aed, #a78bfa);
  }
}

For browsers without light-dark(), keep regular fallback values outside the @supports block:

:root {
  --bux-color-bg: #f7f7f7;
  --bux-color-text: #111111;
}

---

Manual theme switch

If your application controls the active theme with an attribute, override the semantic tokens for that state:

[data-theme="dark"] {
  color-scheme: dark;
  --bux-color-bg: #101010;
  --bux-color-text: #f2f2f2;
  --bux-color-muted: #c8c8c8;
  --bux-color-border: #555555;
}

---

Motion

Use BrowserUX motion tokens in your own components if you want them to respect the same reduced-motion strategy:

.panel {
  transition:
    opacity var(--bux-duration-base) var(--bux-easing),
    transform var(--bux-duration-base) var(--bux-easing);
}

When prefers-reduced-motion: reduce is active, BrowserUX sets the duration tokens to 1ms.

---

Cascade layers

BrowserUX declares this internal layer order:

@layer bux.tokens, bux.browser-default, bux.preferences, bux.native-ui;

Unlayered application styles naturally override all BrowserUX layers. If your project uses layers, declare your application layers after BrowserUX or keep component overrides unlayered.

---

Migration from v4

The main v4 token names were renamed in v5. Common replacements:

- --bux-color-primary
+ --bux-color-accent

- --bux-page-bg
+ --bux-color-bg

- --bux-typo-font-size
+ --bux-font-size

See the CSS Variables reference for the full mapping.