Skip to main content

Theming

Customize colors, radii, and shadows by overriding CSS custom properties at .cider scope.

How It Works

Every colour, radius, shadow, and transition timing in Cider UI is a CSS custom property declared at :root (light mode) and overridden at .dark. Consumers re-theme by redeclaring the properties higher in the cascade — typically at .cider or at :root in your own stylesheet.

Common Overrides

Brand Colour

/* Replace Apple Blue with your brand */
.cider {
  --color-primary: oklch(0.55 0.22 25);         /* warm coral */
  --color-primary-hover: oklch(0.51 0.22 25);
  --color-primary-active: oklch(0.47 0.22 25);

  /* Text-usage variant (lighter in dark mode for readability) */
  --color-link: var(--color-primary);
}
.dark.cider {
  --color-link: oklch(0.78 0.16 25);            /* lighter in dark */
}

Rounder Corners

.cider {
  --radius-xs: 0.5rem;
  --radius-sm: 0.75rem;
  --radius:    1rem;
  --radius-lg: 1.25rem;
  --radius-xl: 1.75rem;
}

Restore Apple-Exact Palette

Cider UI's defaults darken Apple's exact palette slightly to meet WCAG AA. Users who prioritise brand fidelity can restore Apple's colours: 

.cider {
  --color-primary: oklch(0.603 0.218 257.42);        /* #007AFF */
  --color-primary-hover: oklch(0.56 0.218 257.42);
  --color-primary-active: oklch(0.518 0.218 257.42);
  --color-destructive: oklch(0.654 0.232 28.66);     /* #FF3B30 */
  --color-tertiary-foreground: oklch(0.54 0.008 286.01); /* #6E6E73 */
  --avatar-fg: oklch(0.55 0.006 286);
}
.dark.cider {
  --color-primary: oklch(0.624 0.206 255.49);        /* #0A84FF */
  --color-destructive: oklch(0.663 0.224 28.29);     /* #FF453A */
}

Caveat: some component states will fail WCAG AA 4.5:1 contrast with the Apple-exact values — matches iOS/macOS native UI, which also doesn't meet AA without system-level accessibility settings.

Full Token List

Colours

--color-primary / -hover / -active / -foreground
Brand accent (btn-filled, focus rings).
--color-link
Lighter brand-blue variant for text usage (prose anchors, btn-plain/tinted/navbar text in dark mode). Falls back to --color-primary in light mode.
--color-destructive / -hover / -active / -foreground / -text
Destructive actions. The -text variant is a lighter version for use as text on dark backgrounds.
--color-foreground / --color-background
Primary body text / page background.
--color-secondary / -hover / -foreground / -active
Secondary surfaces (btn-gray, callout, card backgrounds).
--color-tertiary-foreground
Secondary text (labels, sidebar non-active).
--color-border / --color-border-solid / --color-separator
Dividers and outlines. separator is slightly lighter than border.
--color-card / --color-card-foreground
Raised surfaces (cards, dialogs).
--color-blue / -green / -orange / -yellow / -purple / -gray
Apple System Colours for semantic accents (tags, badges, icons). Not guaranteed WCAG AA — these are system-level brand hues.

Surface Overlays

Neutral opacity layers for depth hierarchy. Auto-swap base colour in dark mode (black → white-tinted).

--surface-1
Barely visible (table headers, zebra rows).
--surface-2
Hover backgrounds.
--surface-3
Icon bg, kbd bg, toggle group (Apple quaternarySystemFill).
--surface-4
Active / pressed state (Apple tertiarySystemFill).
--surface-5
Slider track, progress bg, segmented control bg (Apple secondarySystemFill).
--surface-7
Tooltip bg (Apple systemFill).

Radii

--radius-xs (5px) / -sm (8px) / --radius (12px) / -lg (16px) / -xl (22px) / -pill (9999px)
Component corner sizes.

Shadows

--shadow-sm / --shadow / --shadow-md / --shadow-lg / --shadow-xl
Elevation steps. Darker in dark mode.
--panel-ring / --float-ring
Subtle border-like shadow outlines for cards and floating panels.

Transitions

--transition-fast (0.15s)
Hover, colour shifts.
--transition-normal (0.25s)
Opacity, transform.
--apple-ease / --apple-spring
Apple-style easing curves.
--apple-press-scale (0.98)
Scale factor for button press feedback.

Focus Ring

--focus-ring / --focus-ring-error
Shadow used for keyboard focus indicators. Already uses color-mix with --color-primary / --color-destructive so they follow your brand overrides.

Dark Mode

Cider UI enables dark mode via a .dark class on <html> (or any ancestor). The docs auto-apply it based on prefers-color-scheme: 

// Match system preference on load
if (matchMedia('(prefers-color-scheme: dark)').matches) {
  document.documentElement.classList.add('dark');
}

// Manual toggle
document.documentElement.classList.toggle('dark');

Classless Typography Scope

Cider UI scopes all classless element styling (h1, input, table, blockquote, …) inside @scope(.cider) to (.cider-reset). Add .cider to any ancestor to opt in. Drop .cider-reset on a child to opt out for that subtree (useful for third-party widgets that ship their own stylesheet).