Design tokens

All canonical **runtime CSS custom properties** for Prox OS live in the workspace package **@prox-os/design-tokens**, file export:

Source of truth

All canonical runtime CSS custom properties for Prox OS live in the workspace package @prox-os/design-tokens, file export:

@prox-os/design-tokens/css/prox.css

The previous copy embedded in packages/os-ui has been reduced to a re-export of that file for backward compatibility (@prox-os/os-ui/tokens.css).

Naming

Public token names are --os-* (never unprefixed legacy names in new code). Categories include:

Color: --os-color-page, --os-color-surface, --os-color-surface-solid, --os-color-surface-muted, --os-color-glass, --os-color-ink (+ muted/faint), --os-color-border (+ strong), --os-color-accent (+ soft), semantic hues (--os-color-blue, --os-color-rose, …)
Radii: --os-radius-control, --os-radius-panel, --os-radius-window, --os-radius-dock
Shadows: --os-shadow-panel, --os-shadow-window, --os-shadow-float
Layout / density: --os-shellbar-height, --os-titlebar-height, --os-window-body-padding, --os-dock-height, desktop/folder metrics, etc.

Semantic aliases in TypeScript (e.g. tokens.color.danger → rose) are defined in @prox-os/design-tokens for inline styles; CSS remains the full truth for themes.

Variants (selectors)

prox.css adjusts tokens using data attributes, for example:

[data-os-theme="dark"] — dark palette
[data-os-density="compact"|"spacious"] — shell/app density
[data-os-background="…"] — desktop wallpaper presets (shell)

Embed hosts should set compatible attributes when the app is not in an iframe (same document as shell). For iframes, either inject aligned variables at the iframe root or accept a stable default inside the child document.

Tailwind CSS v4

Two-step setup in the app stylesheet:

@import '@prox-os/design-tokens/css/prox.css';
Optionally @import '@prox-os/design-tokens/tailwind/theme.css'; then @import 'tailwindcss';

The optional theme file adds an @theme inline bridge so utilities such as bg-os-surface, text-os-ink, rounded-os-control resolve to the same variables. Existing code may keep arbitrary values like bg-[var(--os-color-surface)]; do not mass-migrate without cause.

Rules

Prefer semantic tokens over raw hex in new UI.
Do not introduce a second parallel naming scheme for the same concepts (e.g. duplicate --app-* for shell colors) without a migration plan.
OKLCH or other color spaces: the current palette is hex / rgba for broad compatibility. A future migration can rewrite values inside prox.css while keeping --os-* names stable; document any such change here.

TypeScript API

import { cssVars, tokens } from '@prox-os/design-tokens'

Use tokens for style={{ color: tokens.color.ink }}; use cssVars when referencing property names in strings.