Exploration of a robust specification for multi-dimensional design token resolution with full Figma Variables support.
Design tokens have become foundational infrastructure for scalable design systems. The industry has converged on a tiered abstraction model—primitives, options, decisions, components, instances—but context-awareness remains fragmented.
Current systems treat context as flat modes (light/dark, desktop/mobile) rather than as a multidimensional coordinate system with inheritance, intersection, and resolution rules. When a button needs to resolve its background color, the answer depends on:
- Color scheme preference (light, dark, high-contrast)
- Density mode (compact, comfortable, spacious)
- Interaction state (rest, hover, active, disabled)
- Accessibility requirements (forced colors, reduced motion)
- Platform capabilities (color gamut, touch input)
- Locale considerations (RTL, text expansion)
- Container context (available space, scroll position)
- And dozens more dimensions...
This project provides the missing specification.
The complete specification defining:
| Aspect | Description |
|---|---|
| 12 Context Categories | Appearance, Density, Viewport, Container, Interaction States, Combinable States, Accessibility, Locale, Platform, Elevation, Semantic, Structural |
| 93 Dimensions | Complete enumeration with values, volatility class, and detection mechanism |
| 5 Volatility Classes | Immutable → Stable → Semi-stable → Volatile → Inherited |
| 78 Cross-Category Dependencies | Documented relationships requiring coordination |
| 52 Conflict Scenarios | Resolution rules for dimension intersections |
| Named Context Types | Governed shortcuts for common patterns (mobile-dark, kiosk, print) |
| Resolution Algorithm | Explicit precedence ordering for token resolution |
W3C Design Tokens format implementation with 10 collections (~2,750 tokens):
tokens/
├── collections/
│ ├── primitives.json # Raw color palette (blue-500, gray-200, etc.)
│ ├── theme.json # Light / Dark / Dim color schemes
│ ├── density.json # Compact / Comfortable / Spacious spacing
│ ├── viewport.json # Mobile / Tablet / Desktop layouts
│ ├── contrast.json # Standard / High / Forced accessibility
│ ├── motion.json # Full / Reduced / None animations
│ ├── elevation.json # Base / Raised / Elevated surfaces
│ ├── typography.json # Default / Editorial / Technical styles
│ ├── state.json # Rest / Hover / Active / Disabled states
│ └── brand.json # Primary / Secondary / Partner identities
└── manifest.json # Collection metadata & GitFig mappings
Theoretical explorations and supporting material:
- Context as Coordinate System Thesis — Foundational argument that tokens are policies mapping context coordinates to values
- Context Coordinate Model Exploration — Application of embodied AI principles to design tokens
- Coordinate Model and Token Tiers — How the coordinate model fits within the standard 3-tier token taxonomy
- Design Tokens for Embodied AI — Theoretical bridge between UI design tokens and AI/robotics representations
- Design Systems: Single Source of Truth — Analysis of SSOT architecture and data normalization principles
| Collection | Modes | Purpose |
|---|---|---|
| Primitives | — | Raw color palette: 22 scales (gray→rose) × 11 steps (50-950) |
| Theme | light, dark, dim | Color schemes with surfaces, foregrounds, borders, status colors |
| Density | compact, comfortable, spacious | Spacing, sizing, touch targets, component dimensions |
| Viewport | mobile, tablet, desktop | Responsive layouts, grids, breakpoints, navigation patterns |
| Contrast | standard, high, forced | Accessibility colors, focus rings, border widths |
| Motion | full, reduced, none | Durations, easings, animations, scroll behaviors |
| Elevation | base, raised, elevated | Shadows, z-indices, glass effects, surface treatments |
| Typography | default, editorial, technical | Font families, text styles, line heights, spacing |
| State | rest, hover, active, disabled | Interaction states for buttons, inputs, links, cards |
| Brand | primary, secondary, partner | Brand colors, gradients, radii, typography per brand |
Each collection represents an independent context dimension with its own modes:
┌──────────────────────────────────────────────────────────────────────────┐
│ Collection: Theme │
│ Modes: [light, dark, dim] │
│ Detection: prefers-color-scheme, user preference │
├──────────────────────────────────────────────────────────────────────────┤
│ Collection: Density │
│ Modes: [compact, comfortable, spacious] │
│ Detection: pointer type, user preference │
├──────────────────────────────────────────────────────────────────────────┤
│ Collection: Viewport │
│ Modes: [mobile, tablet, desktop] │
│ Detection: viewport width, container queries │
├──────────────────────────────────────────────────────────────────────────┤
│ ...additional collections... │
└──────────────────────────────────────────────────────────────────────────┘
Each token has explicit values for ALL modes in its collection:
{
"surface.default": {
"$type": "color",
"$value": "#ffffff",
"$extensions": {
"mode": {
"light": "#ffffff",
"dark": "#0a0a0a",
"dim": "#1a1a1a"
}
}
}
}
- Install GitFig plugin in Figma
- Connect your repository
- Import each collection file → each becomes a Figma Variable Collection with modes
{
"source": ["tokens/collections/*.json"],
"platforms": {
"css": {
"transformGroup": "css",
"buildPath": "dist/",
"files": [{ "destination": "tokens.css", "format": "css/variables" }]
}
}
}import primitives from './tokens/collections/primitives.json';
import theme from './tokens/collections/theme.json';
import density from './tokens/collections/density.json';
// Access raw color primitives
const blue500 = primitives.blue['500'].$value; // #3b82f6
const gray200 = primitives.gray['200'].$value; // #e5e5e5
// Get light mode surface color
const surfaceLight = theme.surface.default.$extensions.mode.light; // #ffffff
// Get dark mode surface color
const surfaceDark = theme.surface.default.$extensions.mode.dark; // #0a0a0a
// Get spacing for comfortable density
const spacing4 = density.spacing['4'].$extensions.mode.comfortable; // 16px
// Get spacing for compact density
const spacing4Compact = density.spacing['4'].$extensions.mode.compact; // 12pxThis ontology supports a Single Source of Truth (SSOT) architecture with controlled contextual variation:
- Explicit chains — Every resolved token value traces back through a documented path
- Governed types — Context types are finite and governed, not arbitrary
- Learnable friction — Exceptions are logged and promoted to tokens when patterns emerge
- Predictable blast radius — Changes at any tier have bounded, knowable effects
- Full mode coverage — Every token has explicit values for all modes (no fallbacks needed)
When dimensions conflict, resolution follows this order (highest to lowest):
- Accessibility overrides —
forced-colors,prefers-contrast, minimum targets - Explicit declarations — Dimensions set directly on element
- Context type — Dimensions from applied named context type
- Inherited context — Dimensions from ancestor chain
- Platform defaults — Platform-specific default values
- System defaults — Ontology-defined defaults
Pre-defined combinations for common scenarios:
| Context Type | Dimensions |
|---|---|
mobile-dark |
viewport: mobile, theme: dark, density: comfortable |
desktop-light |
viewport: desktop, theme: light, density: comfortable |
kiosk |
viewport: desktop, theme: dark, density: spacious, contrast: high |
print |
theme: light, contrast: high, motion: none, elevation: base |
high-contrast |
contrast: high, elevation: base |
reduced-motion |
motion: reduced |
compact-ui |
density: compact, typography: technical |
editorial-reading |
density: spacious, typography: editorial |
MIT
Issues and pull requests welcome. See the whitepaper for the complete specification that implementations should follow.