Design Tokens

Every @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);

Tip

The values below mirror the OSS default light theme (packages/design/src/themes/defaults/light.ts), emitted by the DTCG parser as --ggui-color-…, --ggui-spacing-…, --ggui-shape-radius-…, --ggui-shape-shadow-… (path = group chain, hyphenated). The canonical DtcgTheme nests radius and shadow under shape.* and transitions under motion.* — primitives reference --ggui-shape-radius-md, --ggui-shape-shadow-md, --ggui-motion-duration-normal, etc.

Caution

The swatch/scale tables below are rendered from a hand-maintained snapshot at apps/docs/src/data/tokens.ts (Astro can’t import the React design package directly). If a value here disagrees with packages/design/src/themes/defaults/light.ts, the design package is authoritative.

---

Colors

Color Palettes

Primary (Sky Blue)

50

#f0f9ff--ggui-color-primary-50

100

#e0f2fe--ggui-color-primary-100

200

#bae6fd--ggui-color-primary-200

300

#7dd3fc--ggui-color-primary-300

400

#38bdf8--ggui-color-primary-400

500

#0ea5e9--ggui-color-primary-500

600

#0284c7--ggui-color-primary-600

700

#0369a1--ggui-color-primary-700

800

#075985--ggui-color-primary-800

900

#0c4a6e--ggui-color-primary-900

Gray

50

#f9fafb--ggui-color-neutral-50

100

#f3f4f6--ggui-color-neutral-100

200

#e5e7eb--ggui-color-neutral-200

300

#d1d5db--ggui-color-neutral-300

400

#9ca3af--ggui-color-neutral-400

500

#6b7280--ggui-color-neutral-500

600

#4b5563--ggui-color-neutral-600

700

#374151--ggui-color-neutral-700

800

#1f2937--ggui-color-neutral-800

900

#111827--ggui-color-neutral-900

Success

50

#f0fdf4--ggui-color-success-50

100

#dcfce7--ggui-color-success-100

200

#bbf7d0--ggui-color-success-200

500

#22c55e--ggui-color-success-500

600

#16a34a--ggui-color-success-600

700

#15803d--ggui-color-success-700

800

#166534--ggui-color-success-800

Warning

50

#fffbeb--ggui-color-warning-50

100

#fef3c7--ggui-color-warning-100

200

#fde68a--ggui-color-warning-200

500

#f59e0b--ggui-color-warning-500

600

#d97706--ggui-color-warning-600

700

#b45309--ggui-color-warning-700

800

#92400e--ggui-color-warning-800

Error

50

#fef2f2--ggui-color-error-50

100

#fee2e2--ggui-color-error-100

200

#fecaca--ggui-color-error-200

500

#ef4444--ggui-color-error-500

600

#dc2626--ggui-color-error-600

700

#b91c1c--ggui-color-error-700

800

#991b1b--ggui-color-error-800

Info

50

#ecfeff--ggui-color-info-50

100

#cffafe--ggui-color-info-100

200

#a5f3fc--ggui-color-info-200

500

#06b6d4--ggui-color-info-500

600

#0891b2--ggui-color-info-600

700

#0e7490--ggui-color-info-700

800

#155e75--ggui-color-info-800

Semantic Colors

These tokens map to specific UI roles and adapt between light and dark themes.

Ground#ffffff--ggui-color-ground

Sunken#f3f4f6--ggui-color-sunken

On Ground#111827--ggui-color-onGround

On Sunken#6b7280--ggui-color-onSunken

Outline#9ca3af--ggui-color-outline

Outline Variant#d1d5db--ggui-color-outlineVariant

Container#f9fafb--ggui-color-container

On Container#111827--ggui-color-onContainer

Note

Status colors are scales, not singletons. success, warning, error, and info each expose the full 50/100/200/500/600/700/800 stops (see the swatch panels above). Reach for --ggui-color-success-500 for fills, -600/-700 for hover/pressed states, and -50/-100 for subtle tints — the singletons that used to live here are retired.

Material Role Pairs

The canonical theme states its layering as role pairs — a background and the ink that sits on it. A theme.json authors three of the four (ground, container, sunken, each with its on*); elevated is derived. Primitives use these to keep contrast right across nested backgrounds.

CSS variable	Role
--ggui-color-ground	The canvas — page / sheet background
--ggui-color-onGround	Primary text and icons on ground
--ggui-color-container	Cards, panels, filled containers
--ggui-color-onContainer	Text/icons on container
--ggui-color-elevated	Raised surfaces (menus, popovers) — derived, not authored
--ggui-color-onElevated	Text/icons on elevated — derived
--ggui-color-sunken	Wells, inputs at rest, code blocks — recessed inside container
--ggui-color-onSunken	Secondary text/icons on sunken
--ggui-color-outline	Standard borders + dividers
--ggui-color-outlineVariant	Faint borders, disabled outlines
--ggui-color-onPrimary	Text/icons on a primary fill (CTA labels)
--ggui-color-primaryContainer	Tinted primary container (soft CTA, highlight)
--ggui-color-onPrimaryContainer	Text/icons on primaryContainer
--ggui-color-onError	Text/icons on an error fill
--ggui-color-errorContainer	Softer error container (inline error banners)
--ggui-color-onErrorContainer	Text/icons on errorContainer
--ggui-color-tertiary	Complementary accent to primary
--ggui-color-onTertiary	Text/icons on a tertiary fill
--ggui-color-tertiaryContainer	Tinted tertiary container
--ggui-color-onTertiaryContainer	Text/icons on tertiaryContainer

---

Spacing

A consistent spacing scale ensures visual rhythm across all components.

xs4px

--ggui-spacing-xs

sm8px

--ggui-spacing-sm

md16px

--ggui-spacing-md

lg24px

--ggui-spacing-lg

xl32px

--ggui-spacing-xl

2xl48px

--ggui-spacing-2xl

3xl64px

--ggui-spacing-3xl

---

Typography

Canonical theme path: font.{family,weight,ramp,letterSpacing} — a theme authors the families, the weights, one font.ramp and optional letter-spacing; the size and line-height scales are derived from the ramp. Emitted as --ggui-font-family-*, --ggui-font-weight-*, and the derived --ggui-font-size-* / --ggui-font-lineHeight-* shown below. Web fonts are declared as typography.faces (https: sources only); ggui deploy names any family the hosted path does not deliver yet. Authored font.size or font.lineHeight is refused.

Font Families

The quick brown fox jumps over the lazy dog

Sans--ggui-typography-fontFamily-sans

The quick brown fox jumps over the lazy dog

Mono--ggui-typography-fontFamily-mono

Font Sizes

xs12px

The quick brown fox--ggui-typography-fontSize-xs

sm14px

The quick brown fox--ggui-typography-fontSize-sm

base16px

The quick brown fox--ggui-typography-fontSize-base

lg18px

The quick brown fox--ggui-typography-fontSize-lg

xl20px

The quick brown fox--ggui-typography-fontSize-xl

2xl24px

The quick brown fox--ggui-typography-fontSize-2xl

3xl30px

The quick brown fox--ggui-typography-fontSize-3xl

4xl36px

The quick brown fox--ggui-typography-fontSize-4xl

Font Weights

NormalThe quick brown fox jumps over the lazy dog400

MediumThe quick brown fox jumps over the lazy dog500

SemiboldThe quick brown fox jumps over the lazy dog600

BoldThe quick brown fox jumps over the lazy dog700

Line Heights

Tight

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

1.25

Normal

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

1.5

Relaxed

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

1.75

---

Border Radius

Canonical theme path: shape.radius.*. Emitted as --ggui-shape-radius-{none,sm,md,lg,xl,2xl,full}.

none0

--ggui-shape-radius-none

sm4px

--ggui-shape-radius-sm

md8px

--ggui-shape-radius-md

lg12px

--ggui-shape-radius-lg

xl16px

--ggui-shape-radius-xl

2xl24px

--ggui-shape-radius-2xl

full9999px

--ggui-shape-radius-full

---

Shadows

Canonical theme path: shape.shadow.*. Emitted as --ggui-shape-shadow-{none,xs,sm,md,lg,xl,2xl}.

none0 0 0 0 transparent--ggui-shape-shadow-none

xs0 1px 2px 0 rgba(15, 23, 42, 0.04)--ggui-shape-shadow-xs

sm0 1px 3px 0 rgba(15, 23, 42, 0.06)--ggui-shape-shadow-sm

md0 8px 16px -4px rgba(15, 23, 42, 0.10)--ggui-shape-shadow-md

lg0 16px 32px -8px rgba(15, 23, 42, 0.14)--ggui-shape-shadow-lg

xl0 24px 48px -12px rgba(15, 23, 42, 0.18)--ggui-shape-shadow-xl

2xl0 25px 50px -12px rgba(0, 0, 0, 0.25)--ggui-shape-shadow-2xl

---

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-duration-slower	500ms	Full-surface transitions, long fades
--ggui-motion-transition-fast	100ms cubic-bezier(0.4, 0, 0.2, 1)	Duration + curve only; you name the property
--ggui-motion-transition-normal	200ms cubic-bezier(0.4, 0, 0.2, 1)	Duration + curve only; you name the property
--ggui-motion-transition-slow	300ms cubic-bezier(0.4, 0, 0.2, 1)	Duration + curve only; you name the property
--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

There is no catch-all all transition — name the properties you move, or use one of the bare fast / normal / slow shorthands. Under prefers-reduced-motion: reduce, fall back to var(--ggui-accessibility-reducedMotion-duration) (0ms) instead of the durations above.

---

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.

focusRing, reducedMotion, and highContrast are token groups, not scalars — each leaf emits its own variable, so there is no bare --ggui-accessibility-focusRing.

Variable	Type	Notes
--ggui-accessibility-focusRing-color	color	Focus-indicator color used by every primitive
--ggui-accessibility-focusRing-width	dimension	Ring thickness (2px in the canonical theme)
--ggui-accessibility-focusRing-offset	dimension	Gap between the element and the ring
--ggui-accessibility-reducedMotion-duration	duration	Duration to use under prefers-reduced-motion: reduce
--ggui-accessibility-highContrast-borderWidth	dimension	Border thickness under prefers-contrast: more
--ggui-accessibility-highContrast-textColor	color	Text color under prefers-contrast: more
--ggui-accessibility-highContrast-backgroundColor	color	Background under prefers-contrast: more
--ggui-accessibility-highContrast-linkColor	color	Link color under prefers-contrast: more

Override the focusRing group at the theme level to brand the focus indicator across every primitive at once.

---

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

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

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-ground, #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-onGround, #111827);
  transition: var(--ggui-motion-transition-colors, color 200ms ease);
}

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-ground: #fefce8;          /* Warm paper canvas */
  --ggui-color-onGround: #1f1410;        /* Ink for the new ground */
  --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.