Skip to content

feat(linter): add parser and model resolution support for hypertokens - #169

Open
zachshallbetter wants to merge 2 commits into
google-labs-code:mainfrom
zachshallbetter:feat/hypertokens
Open

feat(linter): add parser and model resolution support for hypertokens#169
zachshallbetter wants to merge 2 commits into
google-labs-code:mainfrom
zachshallbetter:feat/hypertokens

Conversation

@zachshallbetter

@zachshallbetter zachshallbetter commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Adds support for parsing, resolving, and linting the newly proposed hypertokens category in DESIGN.md (resolves Issue #137).

Background & Motivation

This implements the "hypertokens" concept introduced by Jake Albaugh (@jake-figma) at Figma Config 2026: Design context for agentic workflows. Hypertokens act as an intermediate layer between atomic design tokens and components. Instead of forcing consumers (or AI coding agents) to guess which colors, spacing levels, and corner styles belong together on a specific UI element, hypertokens allow design authors to package those decisions into a single named visual preset.

For more details on the design rationale, see the UX Collective writeup:
What are hypertokens? The layer between tokens and components, rebuilt for agents.

We already support composite values for typography (e.g., {typography.label-md}). This PR introduces a generic hypertokens block in the frontmatter, maps the resolved properties, and allows components to reference them via a new style property.

Changes

  • Parser & Schema:
    • Register Hypertokens as a canonical section heading and add style (type Hypertoken) to component_sub_tokens in spec-config.yaml.
    • Extend ParsedDesignSystem interface and SCHEMA_KEYS in parser/spec.ts.
    • Map hypertokens from raw parsed YAML in parser/handler.ts.
  • Model Resolution:
    • Add hypertokens maps to DesignSystemState and support nested values in model/spec.ts.
    • Resolve nested references and chains within hypertokens in model/handler.ts.
    • Support resolving component properties pointing to entire hypertokens in model/handler.ts.
  • Linter Rules:
    • Extend the broken-ref rule in linter/rules/broken-ref.ts to scan state.hypertokens and verify that all internal references resolve successfully, flagging any broken links.
  • Documentation:
    • Update spec.mdx and README.md to document the hypertokens schema, component styling, and Config 2026 citations.
    • Regenerate docs/spec.md with the new schema key details.
  • Brand Example:
    • Add the brutalist-archive example showcasing an industrial design spec, generated DTCG design tokens, and a Tailwind v3 configuration.
  • Test Coverage:
    • Add parser unit tests to verify hypertokens YAML extraction in parser/handler.test.ts.
    • Add model tests to verify reference resolution and component mapping in model/handler.test.ts.
    • Add rule tests for unresolved references in linter/rules/broken-ref.test.ts.
  • Project Maintenance:
    • Add .DS_Store to .gitignore to prevent macOS system metadata from being tracked.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant