Theming | Arcadia Design

Night and day

The kit's defaults are Arcadia's identity, Sodium Horizon: slate neutrals with a blue-hour cast, white ink, dove prose and one beacon.

Name	Night	Day	Use
Ink			White labels and headings by night, the night page by day.
Prose			Dove: long reading a breath softer than labels.
Page			One slate page; the sidebar is the bezel a step below.
Card			Code windows and stream cards, a step off the page.
Raised			Charcoal by night, white by day: what you touch.
Umbra			The darkest structural step of the same slate: every divider.
Beacon			The one light, for lights only.
Plan			Breeze, a quiet distance blue.

The thesis and the six rules that follow from it are on the Overview.

Switching themes

One attribute, <html data-theme="dark|light">. There is no prefers-color-scheme block in the CSS: the boot script resolves the preference before first paint.

data-theme="dark"

Chime when a turn ends

data-theme="light"

Chime when a turn ends

Any element may carry its own data-theme, and its ladders recompute from its own --ink. These two panels are subtrees of this page: open their menus and hover the gear to see overlays keep the panel's theme.

Boot and preference

TSX

import { themeBootScript } from "@arcadia/ui";

// index.html: inline it in <head>, before the stylesheet, so light users never see a dark flash.
const head = `<script>${themeBootScript({ themeKey: "myapp.theme", motionKey: "myapp.reduceMotion" })}</script>`;

TSX

import { useMotionPreference, useTheme } from "@arcadia/ui";

// At the app root: persists the preference, writes data-theme, follows the OS while "system".
const { theme, preference, setPreference } = useTheme(settings.theme, { storageKey: "myapp.theme" });
useMotionPreference(settings.reduceMotion, { storageKey: "myapp.reduceMotion" });

The boot script and the hooks read the same two storage keys, so the first paint and the running app always agree.

Four rungs, from the least reach to the most. Take the lowest one that does the job.

Brand tokens

A product that needs its own light overrides brand tokens only, in @layer brand, which comes after the kit's tokens and so wins without specificity.

CSS

/* your product's theme.css, imported right after "@arcadia/ui/styles.css" */
@layer brand {
  :root, [data-theme="dark"] { --brand-accent: #599ce7; --brand-accent-text: #7bafe9; --brand-mark: var(--text-2); }
  [data-theme="light"]       { --brand-accent: #2678c1; --brand-accent-text: #1f6cb4; --brand-mark: var(--text-2); }
}

Token	Drives
	`--hue-accent`: the caret, the needs-you and finished-unseen dots, the selection, accent washes and the live signal (`--horizon-*`).
	`--text-accent`: accent Badge and Chip text only; links stay ink. Keep it at 4.5:1 or more on every surface.
	The `ArcadiaMark` colour (`.ui-brand-mark`).

Driven by the brand lightUnreadNeeds youNewplan.mdCaretNever the brand'sselectedA link stays ink.

The light moves; the ink, the primary button, links and the focus ring stay the kit's.

Component tokens

Each component documents its tokens (--button-bg, --ib-size, --row-fill). Product code may set them from a container, in @layer features.

CSS

@layer features {
  /* a denser composer toolbar: set the component's documented token */
  .composer .ui-icon-button { --ib-size: var(--control-sm); }
}

Layout through class hooks

Every part carries a ui-* class.

CSS

@layer features {
  /* lay kit parts out (margin, grid, flex) through their ui-* class hooks */
  .settings-list { display: grid; gap: var(--space-px); }
  .settings-list .ui-row { margin-inline: calc(-1 * var(--space-2)); }
}

A new variant

When the same override comes up twice, propose a variant to the kit instead. A variant only reassigns component tokens, so every product gets it, in both themes.

TSX

// badge.tsx, in the kit: a new tone only reassigns the badge's knobs
const tones = stylex.create({
  info: { "--badge-bg": `color-mix(in srgb, ${palette["--hue-cyan"]} 10%, transparent)`, "--badge-fg": palette["--text-cyan"] },
});

Not supported

Your own font. The type ramp, tracking and weights are measured for SF Pro and Geist Mono.
Different greys. Every neutral is one ink at a rank alpha; new greys break the contrast ladder.
A different radius scale. Corners nest by the scale, and continuous corners depend on its steps.
Restyling a component's anatomy: its parts, spacing or states. Propose a variant instead.

Portals

Overlays portal to document.body.

TSX

const [el, setEl] = useState<HTMLElement | null>(null);

<div data-theme="light" ref={setEl}>
  <PortalProvider container={el}>
    <Menu>…</Menu>   {/* its popup portals into the light subtree */}
  </PortalProvider>
</div>

Mount TooltipProvider, ConfirmHost and Toaster once, near the app root.