{"id":50523236,"url":"https://github.com/ds1/design-token-context-model","last_synced_at":"2026-06-03T06:04:11.049Z","repository":{"id":332035706,"uuid":"1132525918","full_name":"ds1/design-token-context-model","owner":"ds1","description":"Comprehensive context ontology for multi-dimensional design token resolution. 93 dimensions, 12 categories, inheritance rules, and conflict resolution. Includes spec and W3C DTCG token implementation.","archived":false,"fork":false,"pushed_at":"2026-01-21T23:26:28.000Z","size":217,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-22T12:45:18.282Z","etag":null,"topics":["accessibility","css","design-systems","design-tokens","figma","style-dictionary","theming","w3c"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ds1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-12T04:47:46.000Z","updated_at":"2026-01-21T23:26:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ds1/design-token-context-model","commit_stats":null,"previous_names":["ds1/context-ontology","ds1/design-token-context-ontology","ds1/design-token-context-model"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ds1/design-token-context-model","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ds1%2Fdesign-token-context-model","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ds1%2Fdesign-token-context-model/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ds1%2Fdesign-token-context-model/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ds1%2Fdesign-token-context-model/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ds1","download_url":"https://codeload.github.com/ds1/design-token-context-model/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ds1%2Fdesign-token-context-model/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33850652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","css","design-systems","design-tokens","figma","style-dictionary","theming","w3c"],"created_at":"2026-06-03T06:04:09.469Z","updated_at":"2026-06-03T06:04:11.043Z","avatar_url":"https://github.com/ds1.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Design Token Context Model\n### Draft 0.1 January 20, 2026\n\nExploration of a robust specification for multi-dimensional design token resolution with full Figma Variables support.\n\n## The Problem\n\nDesign 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**.\n\nCurrent 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:\n\n- Color scheme preference (light, dark, high-contrast)\n- Density mode (compact, comfortable, spacious)\n- Interaction state (rest, hover, active, disabled)\n- Accessibility requirements (forced colors, reduced motion)\n- Platform capabilities (color gamut, touch input)\n- Locale considerations (RTL, text expansion)\n- Container context (available space, scroll position)\n- And dozens more dimensions...\n\n**This project provides the missing specification.**\n\n## What's Included\n\n### [Whitepaper](https://github.com/ds1/design-token-context-model/wiki/design-token-context-ontology-whitepaper)\n\nThe complete specification defining:\n\n| Aspect | Description |\n|--------|-------------|\n| **12 Context Categories** | Appearance, Density, Viewport, Container, Interaction States, Combinable States, Accessibility, Locale, Platform, Elevation, Semantic, Structural |\n| **93 Dimensions** | Complete enumeration with values, volatility class, and detection mechanism |\n| **5 Volatility Classes** | Immutable → Stable → Semi-stable → Volatile → Inherited |\n| **78 Cross-Category Dependencies** | Documented relationships requiring coordination |\n| **52 Conflict Scenarios** | Resolution rules for dimension intersections |\n| **Named Context Types** | Governed shortcuts for common patterns (mobile-dark, kiosk, print) |\n| **Resolution Algorithm** | Explicit precedence ordering for token resolution |\n\n### [Token Collections](tokens/)\n\nW3C Design Tokens format implementation with 10 collections (~2,750 tokens):\n\n```\ntokens/\n├── collections/\n│   ├── primitives.json  # Raw color palette (blue-500, gray-200, etc.)\n│   ├── theme.json       # Light / Dark / Dim color schemes\n│   ├── density.json     # Compact / Comfortable / Spacious spacing\n│   ├── viewport.json    # Mobile / Tablet / Desktop layouts\n│   ├── contrast.json    # Standard / High / Forced accessibility\n│   ├── motion.json      # Full / Reduced / None animations\n│   ├── elevation.json   # Base / Raised / Elevated surfaces\n│   ├── typography.json  # Default / Editorial / Technical styles\n│   ├── state.json       # Rest / Hover / Active / Disabled states\n│   └── brand.json       # Primary / Secondary / Partner identities\n└── manifest.json        # Collection metadata \u0026 GitFig mappings\n```\n\n### Additional Documentation\n\nTheoretical explorations and supporting material:\n\n- [Context as Coordinate System Thesis](https://github.com/ds1/design-token-context-model/wiki/context-as-coordinate-system-thesis) — Foundational argument that tokens are policies mapping context coordinates to values\n- [Context Coordinate Model Exploration](https://github.com/ds1/design-token-context-model/wiki/context-coordinate-model-exploration) — Application of embodied AI principles to design tokens\n- [Coordinate Model and Token Tiers](https://github.com/ds1/design-token-context-model/wiki/coordinate-model-and-token-tiers) — How the coordinate model fits within the standard 3-tier token taxonomy\n- [Design Tokens for Embodied AI](https://github.com/ds1/design-token-context-model/wiki/design_tokens_for_embodied_ai) — Theoretical bridge between UI design tokens and AI/robotics representations\n- [Design Systems: Single Source of Truth](https://github.com/ds1/design-token-context-model/wiki/Design-Systems_-Single-Source-of-Truth) — Analysis of SSOT architecture and data normalization principles\n\n## Collections Overview\n\n| Collection | Modes | Purpose |\n|------------|-------|---------|\n| **Primitives** | — | Raw color palette: 22 scales (gray→rose) × 11 steps (50-950) |\n| **Theme** | light, dark, dim | Color schemes with surfaces, foregrounds, borders, status colors |\n| **Density** | compact, comfortable, spacious | Spacing, sizing, touch targets, component dimensions |\n| **Viewport** | mobile, tablet, desktop | Responsive layouts, grids, breakpoints, navigation patterns |\n| **Contrast** | standard, high, forced | Accessibility colors, focus rings, border widths |\n| **Motion** | full, reduced, none | Durations, easings, animations, scroll behaviors |\n| **Elevation** | base, raised, elevated | Shadows, z-indices, glass effects, surface treatments |\n| **Typography** | default, editorial, technical | Font families, text styles, line heights, spacing |\n| **State** | rest, hover, active, disabled | Interaction states for buttons, inputs, links, cards |\n| **Brand** | primary, secondary, partner | Brand colors, gradients, radii, typography per brand |\n\n## Architecture\n\nEach collection represents an **independent context dimension** with its own modes:\n\n```\n┌──────────────────────────────────────────────────────────────────────────┐\n│  Collection: Theme                                                       │\n│  Modes: [light, dark, dim]                                               │\n│  Detection: prefers-color-scheme, user preference                        │\n├──────────────────────────────────────────────────────────────────────────┤\n│  Collection: Density                                                     │\n│  Modes: [compact, comfortable, spacious]                                 │\n│  Detection: pointer type, user preference                                │\n├──────────────────────────────────────────────────────────────────────────┤\n│  Collection: Viewport                                                    │\n│  Modes: [mobile, tablet, desktop]                                        │\n│  Detection: viewport width, container queries                            │\n├──────────────────────────────────────────────────────────────────────────┤\n│  ...additional collections...                                            │\n└──────────────────────────────────────────────────────────────────────────┘\n\nEach token has explicit values for ALL modes in its collection:\n\n{\n  \"surface.default\": {\n    \"$type\": \"color\",\n    \"$value\": \"#ffffff\",\n    \"$extensions\": {\n      \"mode\": {\n        \"light\": \"#ffffff\",\n        \"dark\": \"#0a0a0a\",\n        \"dim\": \"#1a1a1a\"\n      }\n    }\n  }\n}\n```\n\n## Quick Start\n\n### Import to Figma with GitFig\n\n1. Install [GitFig](https://github.com/nicholasareed/gitfig) plugin in Figma\n2. Connect your repository\n3. Import each collection file → each becomes a Figma Variable Collection with modes\n\n### Use with Style Dictionary\n\n```json\n{\n  \"source\": [\"tokens/collections/*.json\"],\n  \"platforms\": {\n    \"css\": {\n      \"transformGroup\": \"css\",\n      \"buildPath\": \"dist/\",\n      \"files\": [{ \"destination\": \"tokens.css\", \"format\": \"css/variables\" }]\n    }\n  }\n}\n```\n\n### Use Directly\n\n```javascript\nimport primitives from './tokens/collections/primitives.json';\nimport theme from './tokens/collections/theme.json';\nimport density from './tokens/collections/density.json';\n\n// Access raw color primitives\nconst blue500 = primitives.blue['500'].$value; // #3b82f6\nconst gray200 = primitives.gray['200'].$value; // #e5e5e5\n\n// Get light mode surface color\nconst surfaceLight = theme.surface.default.$extensions.mode.light; // #ffffff\n\n// Get dark mode surface color\nconst surfaceDark = theme.surface.default.$extensions.mode.dark; // #0a0a0a\n\n// Get spacing for comfortable density\nconst spacing4 = density.spacing['4'].$extensions.mode.comfortable; // 16px\n\n// Get spacing for compact density\nconst spacing4Compact = density.spacing['4'].$extensions.mode.compact; // 12px\n```\n\n## Design Philosophy\n\nThis ontology supports a **Single Source of Truth (SSOT) architecture** with controlled contextual variation:\n\n1. **Explicit chains** — Every resolved token value traces back through a documented path\n2. **Governed types** — Context types are finite and governed, not arbitrary\n3. **Learnable friction** — Exceptions are logged and promoted to tokens when patterns emerge\n4. **Predictable blast radius** — Changes at any tier have bounded, knowable effects\n5. **Full mode coverage** — Every token has explicit values for all modes (no fallbacks needed)\n\n## Resolution Precedence\n\nWhen dimensions conflict, resolution follows this order (highest to lowest):\n\n1. **Accessibility overrides** — `forced-colors`, `prefers-contrast`, minimum targets\n2. **Explicit declarations** — Dimensions set directly on element\n3. **Context type** — Dimensions from applied named context type\n4. **Inherited context** — Dimensions from ancestor chain\n5. **Platform defaults** — Platform-specific default values\n6. **System defaults** — Ontology-defined defaults\n\n## Named Context Types\n\nPre-defined combinations for common scenarios:\n\n| Context Type | Dimensions |\n|--------------|------------|\n| `mobile-dark` | viewport: mobile, theme: dark, density: comfortable |\n| `desktop-light` | viewport: desktop, theme: light, density: comfortable |\n| `kiosk` | viewport: desktop, theme: dark, density: spacious, contrast: high |\n| `print` | theme: light, contrast: high, motion: none, elevation: base |\n| `high-contrast` | contrast: high, elevation: base |\n| `reduced-motion` | motion: reduced |\n| `compact-ui` | density: compact, typography: technical |\n| `editorial-reading` | density: spacious, typography: editorial |\n\n## License\n\nMIT\n\n## Contributing\n\nIssues and pull requests welcome. See the [whitepaper](https://github.com/ds1/design-token-context-model/wiki/design-token-context-ontology-whitepaper) for the complete specification that implementations should follow.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fds1%2Fdesign-token-context-model","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fds1%2Fdesign-token-context-model","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fds1%2Fdesign-token-context-model/lists"}