Design Tokens
read as.mdEvery @ggui-ai/design primitive — and by extension every gadget that ships with the OSS renderer — reads its visual state from DTCG tokens exposed as CSS custom properties. Tokens themselves need no runtime: override the variables on any ancestor and the cascade does the rest on the next paint.
Operator theming builds on these same variables: ggui.json#theme selects one of the shipped presets (or a DTCG file), and per-app overlays are validated --ggui-* maps injected after the base token block, so a partial overlay keeps token defaults. Agents can enumerate presets with ggui_list_themes and pick one per render via ggui_render({themeId}) — see Custom Theming.
/* Every primitive uses var(--ggui-…) with a hardcoded fallback */color: var(--ggui-color-primary-600, #0284c7);padding: var(--ggui-spacing-md, 16px);border-radius: var(--ggui-shape-radius-md, 8px);Colors
Section titled “Colors”Color Palettes
Section titled “Color Palettes”Primary (Sky Blue)
Gray
Success
Warning
Error
Info
Semantic Colors
Section titled “Semantic Colors”These tokens map to specific UI roles and adapt between light and dark themes.
Material Role Pairs
Section titled “Material Role Pairs”The canonical theme adds eight Material 3-inspired role pairs for surface/content layering. They sit alongside (and extend) the legacy text tokens — primitives use these to keep contrast right across nested surfaces.
| CSS variable | Role |
|---|---|
--ggui-color-surface |
Default page / sheet background |
--ggui-color-onSurface |
Primary text and icons on surface |
--ggui-color-surfaceVariant |
Subtle alternate background (cards, rails) |
--ggui-color-onSurfaceVariant |
Secondary text/icons on surfaceVariant |
--ggui-color-container |
Filled container (chips, banners, soft buttons) |
--ggui-color-onContainer |
Text/icons on container |
--ggui-color-outline |
Standard borders + dividers |
--ggui-color-outlineVariant |
Faint borders, disabled outlines |
Spacing
Section titled “Spacing”A consistent spacing scale ensures visual rhythm across all components.
xs4px--ggui-spacing-xssm8px--ggui-spacing-smmd16px--ggui-spacing-mdlg24px--ggui-spacing-lgxl32px--ggui-spacing-xl2xl48px--ggui-spacing-2xl3xl64px--ggui-spacing-3xlTypography
Section titled “Typography”Canonical theme path: font.{family,size,weight,lineHeight}.*. Emitted as --ggui-font-family-*, --ggui-font-size-*, --ggui-font-weight-*, --ggui-font-lineHeight-*.
Font Families
Font Sizes
xs12px--ggui-typography-fontSize-xssm14px--ggui-typography-fontSize-smbase16px--ggui-typography-fontSize-baselg18px--ggui-typography-fontSize-lgxl20px--ggui-typography-fontSize-xl2xl24px--ggui-typography-fontSize-2xl3xl30px--ggui-typography-fontSize-3xl4xl36px--ggui-typography-fontSize-4xlFont Weights
NormalThe quick brown fox jumps over the lazy dog400MediumThe quick brown fox jumps over the lazy dog500SemiboldThe quick brown fox jumps over the lazy dog600BoldThe quick brown fox jumps over the lazy dog700Line Heights
TightNormalRelaxedBorder Radius
Section titled “Border Radius”Canonical theme path: shape.radius.*. Emitted as --ggui-shape-radius-{none,sm,md,lg,xl,2xl,full}.
--ggui-shape-radius-none--ggui-shape-radius-sm--ggui-shape-radius-md--ggui-shape-radius-lg--ggui-shape-radius-xl--ggui-shape-radius-2xl--ggui-shape-radius-fullShadows
Section titled “Shadows”Canonical theme path: shape.shadow.*. Emitted as --ggui-shape-shadow-{none,xs,sm,md,lg,xl,2xl}.
Motion
Section titled “Motion”The canonical motion group covers durations, easings, keyframes, and ready-made transition shorthands. Durations + transitions both surface as CSS custom properties; transitions are pre-composed so primitives can drop in a single var(--ggui-motion-transition-…) without rewriting the curve.
| Variable | Typical value | When to use |
|---|---|---|
--ggui-motion-duration-instant |
0ms |
Immediate state flips (no animation) |
--ggui-motion-duration-fast |
100ms |
Hover, focus, small icon swaps |
--ggui-motion-duration-normal |
200ms |
Default for color/opacity transitions |
--ggui-motion-duration-slow |
300ms |
Layout shifts, large fades |
--ggui-motion-transition-colors |
color/background-color/border-color 200ms |
Theme-aware color changes |
--ggui-motion-transition-opacity |
opacity 200ms |
Fades, show/hide |
--ggui-motion-transition-transform |
transform 200ms |
Translate/scale interactions |
--ggui-motion-transition-all |
all 200ms |
Catch-all when several properties move |
Respect accessibility.reducedMotion — set durations to 0ms (or override the transitions to none) when it’s 'reduce'.
Accessibility
Section titled “Accessibility”Top-level accessibility tokens make a11y intent explicit instead of leaving it implicit in component styles. They emit as --ggui-accessibility-* and pair with the standard media queries.
| Variable | Type | Notes |
|---|---|---|
--ggui-accessibility-focusRing |
shadow / outline shorthand | The focus indicator used by every primitive |
--ggui-accessibility-reducedMotion |
'no-preference' | 'reduce' |
Mirror of prefers-reduced-motion; drives motion |
--ggui-accessibility-highContrast |
'standard' | 'increased' |
Mirror of prefers-contrast; thickens borders |
Override focusRing at the theme level to brand the focus indicator across every primitive at once.
Z-Index
Section titled “Z-Index”A canonical layering scale prevents floating UIs from fighting each other. Values are unitless integers and increase with elevation.
| Variable | Layer | Typical occupant |
|---|---|---|
--ggui-zIndex-hide |
-1 |
Off-screen / underlay |
--ggui-zIndex-base |
0 |
Page content |
--ggui-zIndex-docked |
10 |
Docked sidebars, sticky toolbars |
--ggui-zIndex-dropdown |
1000 |
Menus, select popovers |
--ggui-zIndex-sticky |
1100 |
Sticky table headers |
--ggui-zIndex-banner |
1200 |
Announcement / cookie banners |
--ggui-zIndex-overlay |
1300 |
Backdrop scrims |
--ggui-zIndex-modal |
1400 |
Modal dialogs |
--ggui-zIndex-popover |
1500 |
Floating popovers anchored to content |
--ggui-zIndex-skipLink |
1600 |
Keyboard skip-link (must beat modals) |
--ggui-zIndex-toast |
1700 |
Toast notifications |
--ggui-zIndex-tooltip |
1800 |
Tooltips (topmost interactive element) |
Using Tokens
Section titled “Using Tokens”In primitives
Section titled “In primitives”Nothing to wire — every primitive already consumes the tokens:
import { Button, Card, Input } from '@ggui-ai/design';
<Card> <Input placeholder="Enter your name" /> <Button variant="primary">Submit</Button></Card>;In your own components
Section titled “In your own components”Reference tokens by their CSS variable, with a hardcoded fallback for environments where the theme provider hasn’t loaded yet:
.my-component { background: var(--ggui-color-surface, #ffffff); padding: var(--ggui-spacing-md, 16px); border-radius: var(--ggui-shape-radius-lg, 12px); box-shadow: var(--ggui-shape-shadow-md, 0 8px 16px -4px rgba(15, 23, 42, 0.10)); font-family: var(--ggui-font-family-sans, system-ui, -apple-system, sans-serif); font-size: var(--ggui-font-size-sm, 14px); color: var(--ggui-color-onSurface, #111827); transition: var(--ggui-motion-transition-colors, color 200ms ease);}Theming
Section titled “Theming”Override on any element — :root for global, a wrapper for per-subtree:
:root { --ggui-color-primary-600: #7c3aed; /* Purple instead of sky blue */ --ggui-color-surface: #fefce8; /* Warm paper background */ --ggui-color-onSurface: #1f1410; /* Ink for the new surface */ --ggui-shape-radius-md: 16px; /* Pillier corners */ --ggui-motion-duration-normal: 240ms; /* Slightly more deliberate */}See Custom Theming for the full recipe — global overrides, dark-mode pairs, and scoped subtrees.