Foundations
Design Tokens
Primitive and semantic token layers, sizing, layering, and overrides.
Orkest UI uses two token layers.
- Primitive tokens hold raw design values such as
--ok-color-neutral-900or--ok-space-4. - Semantic tokens map those values to intent, such as
--ui-backgroundor--ui-border.
Component styles consume semantic tokens. Theme switching only remaps the semantic layer.
Source files#
packages/ui/src/styles/tokens.cssdefines primitive values.packages/ui/src/styles/themes.cssmaps semantic tokens for light and dark themes.packages/ui/src/styles/base.cssadjusts library-owned behavior such as reduced motion.
Sizing#
Control heights
| Token | Value |
|---|---|
--ok-control-height-lg | 2.75rem |
--ok-control-height-md | 2.25rem |
--ok-control-height-sm | 1.75rem |
--ok-control-height-xl | 3.25rem |
Control padding
| Token | Value |
|---|---|
--ok-control-padding-x-lg | 1.125rem |
--ok-control-padding-x-md | 0.875rem |
--ok-control-padding-x-sm | 0.625rem |
--ok-control-padding-x-xl | 1.375rem |
Icon sizes
| Token | Value |
|---|---|
--ok-icon-size-lg | 1.5rem |
--ok-icon-size-md | 1.25rem |
--ok-icon-size-sm | 1rem |
--ok-icon-size-xl | 2rem |
--ok-icon-size-xs | 0.75rem |
Focus tokens
| Token | Value |
|---|---|
--ok-focus-ring-offset | 2px |
--ok-focus-ring-width | 2px |
Layering#
Z-index tokens
| Token | Value |
|---|---|
--ok-z-dropdown | 1000 |
--ok-z-modal | 1300 |
--ok-z-overlay | 1200 |
--ok-z-popover | 1400 |
--ok-z-sticky | 1100 |
--ok-z-toast | 1500 |
--ok-z-tooltip | 1600 |
Layering tokens keep menus, overlays, dialogs, popovers, and toasts in a predictable order.
Borders and opacity#
Border tokens
| Token | Value |
|---|---|
--ok-border-width | 1px |
--ok-border-width-strong | 2px |
Opacity tokens
| Token | Value |
|---|---|
--ok-opacity-disabled | 0.45 |
Overrides#
Override semantic tokens on the document root or a themed subtree:
[data-orkest-theme='light'] {
--ui-accent: #3f545f;
--ui-focus-ring: #648292;
}Prefer semantic overrides over overriding primitive values. Primitive overrides affect every semantic token that references them and are harder to audit.