@uix-design/tokens

Shared design tokens for UIX.

Exports

import {
  tokens,
  lightTheme,
  darkTheme,
  highContrastTheme,
  createTheme,
  mergeTheme,
  resolveToken,
  themeToCssVariables
} from "@uix-design/tokens";

CSS

import "@uix-design/tokens/css";

The CSS output includes :root, [data-uix-theme="dark"], [data-uix-theme="high-contrast"] and density selectors.

SCSS

@use "@uix-design/tokens/scss";

License

MIT. Copyright (c) 2026 José L. Alvarado Santamaría.

Concentric rounded surfaces

Choose a restrained exterior radius from the component's shape tokens first. For adjacent, parallel nested edges, derive inner radius = outer radius - inset. When the inset is CSS padding, also subtract the outer border width. The result clamps at zero so generous padding never forces large outer corners.

@use "pkg:@uix-design/tokens/scss" as geometry;

.container {
  --outer-radius: var(--uix-radius-lg);
  --content-inset: var(--uix-space-1);

  padding: var(--content-inset);
  border: 1px solid;
  border-radius: var(--outer-radius);
}

.container > .surface {
  border-radius: geometry.radius-inner("var(--outer-radius)", "var(--content-inset)", 1px);
}

radius-outer(inner, inset, border) provides the equivalent forward operation when the inner geometry is deliberately fixed. Both functions retain CSS variables. These are geometry helpers, not global sizing defaults: density may change insets and derived inner corners without inflating card or panel radii. Apply the relation only to contours sharing an inset; circles, pills, independent controls and diagram notation retain their own geometry. Asymmetric insets require per-corner values.

Density tokens

Workspace headings use the existing 18 px title token and --uix-workspace-subtitle-size (13 px) for secondary descriptions. Their hierarchy stays stable across densities, with theme-aware primary and secondary text colors.

Framed control surfaces use --uix-surface-control-inset (12 px) for symmetric headers, footers, toolbars and edge actions. Visible gaps between corner actions match that inset. Dense toolbars use 8 px gaps; inner tool groups can use 4 px. Content panels keep density padding, and data rows and fields keep their dedicated geometry. Nested radii must adapt to these insets without reducing them to fit a corner control.

tokens.radius.surface, the Sass surface radius and --uix-radius-surface define the 24px radius for primary content surfaces. Smaller control and feedback radii remain independent; the surface radius is stable across density modes.

tokens.density and the SCSS $uix-density map expose compact, comfortable and spacious. Desktop control heights are 2 / 2.5 / 3rem, gaps 0.5 / 0.75 / 1rem and panel padding 0.75 / 1.25 / 1.75rem. The CSS selectors [data-uix-density] and compactTheme, comfortableTheme, spaciousTheme use the same values. Density changes spacing; it does not scale typography or surface radii.

Semantic elevation

The shared shadow scale is neutral and uses the current theme's shadow color:

| CSS token | Use | | --------------------------------- | ------------------------------------------------------ | | --uix-elevation-control-rest | Resting controls and subtle interactive card elevation | | --uix-elevation-control-hover | Hovered controls | | --uix-elevation-control-pressed | Pressed controls, including the inner contact shadow | | --uix-elevation-panel | Menus, filter panels, popovers and floating toasts | | --uix-elevation-modal | Dialogs, overlay drawers and command palettes | | --uix-elevation-drag | Cards lifted during dragging |

The elevation-tokens Sass mixin is exported from @uix-design/tokens/scss. React includes it at each theme root so nested themes resolve their own colors. Control shadows preserve the reduced intensity used by CloseButton. Elevation never replaces keyboard focus, selection indicators or solid-button highlights.

Workspace chrome

@uix-design/tokens/scss exports framework-independent workspace-heading, workspace-controls, workspace-title, workspace-description, workspace-mark, workspace-toolbar, workspace-footer and workspace-window-action mixins. React UI, Advanced, Charts and Flow consume this visual foundation without adding cross-package component dependencies. These mixins emit styles only when included.

Headings and work areas use the panel surface. Toolbars and footers use the muted panel surface, adapting to light/dark themes. Headings share 18px semibold titles, 13px descriptions, 12px edge insets, and 32px desktop / 44px touch controls. Window actions use the diagonal Maximize2/Minimize2 glyphs; the host owns labels, pressed state, focus restoration and window behavior. Canvas zoom/fit actions remain separate from window expansion.

Shared acrylic material

The glass Sass mixin uses one backdrop layer with 24px blur and 125% saturation, keeping background colors quieter while preserving depth. React floating surfaces, image captions and Advanced image galleries consume this material; opacity remains a separate control. Shells and glass icon buttons share its glass-filter mixin.

Override --uix-glass-blur and --uix-glass-saturation on a containing surface to tune it. The previous floating-surface treatment was 18px and 180%; these two overrides restore that optical treatment without duplicating component CSS. Opaque fallbacks remain in the glass mixin for reduced transparency, forced colors and browsers without backdrop filters. The filter-only mixin leaves background and accessibility fallbacks to its consumer.

Success colors

Positive states share an emerald family. Use --uix-success-indicator (#34d399) for filled status marks, presence dots and success surfaces, paired with --uix-on-success-indicator (#073c30) for text or icons inside them. Use --uix-success (#047857) for success text on light surfaces and subtle semantic styles. Do not use white text on the mint fill. Keep a label or icon alongside color so approval and completion remain understandable without color perception.