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 package-level stylesheet in packages/ui/os-ui re-exports that file as @prox-os/os-ui/tokens.css so UI primitives consume the same source.

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/ink), 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, --os-shadow-accent
Layout / density: --os-platform-navigation-height, --os-runtime-command-strip-height, --os-alma-rail-width, --os-titlebar-height, --os-window-body-padding, --os-dock-height, desktop/folder metrics, etc.
Chrome typography: --os-font-size-chrome and --os-font-size-chrome-small
Layering: shared overlay variables such as --os-z-popover and --os-z-tooltip for primitives that must escape window and iframe stacking contexts.

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. The primary product accent is configured through --os-color-accent, --os-color-accent-soft, --os-color-accent-ink, and --os-shadow-accent; update those variables first when changing the platform theme color.

Chrome Density Tokens

Token	Current value	Primary use	Notes
`--os-font-size-chrome`	`11px`	Global Platform Navigation and Runtime Command Strip labels.	Keeps platform and runtime chrome on one typographic scale.
`--os-font-size-chrome-small`	`10px`	Compact shortcuts, badges, and secondary chrome labels.	Use for metadata, not primary actions.
`--os-platform-navigation-height`	`44px`	Global Platform Navigation.	Top platform navigation should stay compact and platform-level.
`--os-runtime-command-strip-height`	`40px`	Runtime Command Strip.	Applies only inside OS Runtime or Studio runtime containers.
`--os-alma-rail-width`	`52px`	Alma Rail and runtime grid columns.	The rail remains icon-first; panels carry text-heavy work.

Variants (selectors)

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

[data-os-theme="dark"] — dark palette
[data-os-density="compact"|"spacious"] — platform and app density
[data-os-background="…"] — desktop wallpaper presets

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.