ui-foundations 0.3.2 → 0.4.1

package/README.md

@@ -1,80 +1,210 @@
 # UI Foundations
 
-A token-first design system that uses Figma as the single source of truth and automatically generates CSS, JSON, and TypeScript tokens.
+Keep Figma and code in sync by default — with tokens, not guesswork.
 
-## Pipeline
+- **Token-first architecture** — every value comes from a token, no hardcoded exceptions
+- **Figma as single source of truth** — variables export directly into production code
+- **Agent-ready workflows** — structured docs that give AI agents deterministic context
+- **Reproducible pipeline** — same input, same output, validated by CI on every change
+
+[Documentation](https://ui-foundations.netlify.app/) · [Starter Template](https://github.com/tbielich/ui-foundations-starter) · [npm](https://www.npmjs.com/package/ui-foundations) · [Figma Library](https://www.figma.com/design/uqMsy8fV1fPbQdAzgwlmBA/UI-Foundations)
+
+---
+
+## Why This Exists
+
+Design systems break when design and code drift apart.
+Manual syncing is slow, error-prone, and doesn't scale.
+
+UI Foundations solves this with a pipeline that turns Figma variables into
+production tokens automatically — and structures everything so AI agents can
+work with the system reliably.
+
+---
+
+## Key Features
+
+- **Token-first architecture** — Core → Semantic → Component → Theme, strictly separated
+- **Figma ↔ code alignment** — `codeSyntax.WEB` maps Figma names directly to CSS
+- **Multi-brand and dark mode** — `data-brand` and `data-mode` switch independently
+- **Agent-ready documentation** — deterministic context for AI-assisted workflows
+- **DTCG-compliant output** — 2025.10 format with proper alias syntax and hex colors
+- **CI-enforced integrity** — full validation pipeline in one `npm run ci:check`
+
+---
+
+## How It Works
+
+### Token Flow
 
 ```
-Figma Variables → Plugin Export → figma/exports/*.tokens.json → extract-tokens.js → dist/ (CSS, JSON, TS, YAML)
+Figma Variables
+      ↓
+figma/exports/*.tokens.json
+      ↓
+extract-tokens.js
+      ↓
+dist/
 ```
 
-## Features
+The pipeline outputs:
 
-- 5 variable collections: Core Primitives, Themes (Brands), Appearance (Modes), Semantics (Roles), Components (UI)
-- Multi-brand support (Brand A/B) via `data-brand` selectors
-- Dark/light mode via `data-mode` selectors
-- Content-based scope detection (independent of filenames)
-- Figma plugin with Validate + Export tabs (see `figma/plugin/README.md`)
-- CI pipeline: lint, unit tests, build, smoke check, docs build
-- Docs site with Eleventy, auto-generated from token data
+- CSS custom properties (`dist/tokens/css/`)
+- DTCG-compliant JSON (`dist/tokens/json/`)
+- TypeScript constants (`dist/tokens/ts/`)
+- A flat YAML index (`dist/tokens/tokens.yaml`)
 
-## Tech Stack
+### Layering
+
+Tokens follow a strict hierarchy:
+
+1. **Core** — raw values (spacing, radii, colors, typography)
+2. **Semantic** — intent-based aliases (`--color-text-default`, `--color-fill-brand`)
+3. **Component** — scoped to one component (`--button-solid-container-background-hover`)
+4. **Theme** — brand and mode overrides via `data-brand` / `data-mode`
+
+Components reference only Semantic or Core. Never raw values.
+
+### Component Integration
+
+Every component ships with:
+CSS pattern, React wrapper, Nunjucks macro, playground page, docs page,
+and Code Connect mapping.
+
+All surfaces must be present for the component to work predictably across
+docs, playgrounds, and consumer apps.
+
+---
+
+## For Different Audiences
+
+### Designers
+
+- Work in Figma variables — they are the source of truth
+- Token names in Figma map directly to CSS variable names
+- Brand and mode switching is built into the variable structure
+
+### Developers
+
+- Use generated CSS custom properties — `var(--color-text-default)`
+- No hardcoded values — everything comes from tokens
+- Theming via `data-brand` and `data-mode` attributes on the root element
+
+### Agents
+
+- Start with `AGENTS.md` — it defines context loading order
+- Follow deterministic rules in `docs/agentic/assistant-behavior-rules.md`
+- Select a mode from `docs/agentic/modes/` based on the task
+
+---
 
-Vanilla CSS (Custom Properties, Layers), Node.js scripts, Eleventy, Figma Plugin API, MCP.
+## Getting Started
 
-## Install
+### Install
 
 ```bash
 npm install ui-foundations
 ```
 
-## Usage
+### Import
 
 ```js
 import "ui-foundations/core.css";
 import "ui-foundations/ui.css";
 ```
 
-Runtime scope switching:
+### Apply Theming
 
 ```js
-const root = document.documentElement;
-root.dataset.brand = "a"; // "a" | "b"
-root.dataset.mode = "light"; // "light" | "dark"
+document.documentElement.dataset.brand = "a";     // "a" | "b"
+document.documentElement.dataset.mode  = "light";  // "light" | "dark"
 ```
 
+Explore the [docs site](https://ui-foundations.netlify.app/) or the
+[vanilla starter](https://github.com/tbielich/ui-foundations-starter)
+to see it in action.
+
+---
+
+## Components
+
+Label, Button (solid / outline / ghost), ButtonGroup, Input, Icon, Checkbox,
+Radio, RadioGroup, Switch, Slider, Link
+
+Each component uses its own token layer and supports theming out of the box.
+
+---
+
+## Agent Integration
+
+This repo is structured for agent consumption:
+
+| File | Purpose |
+|---|---|
+| `AGENTS.md` | Entry point — behavior rules and context loading order |
+| `docs/playbook.md` | Documentation hierarchy and operating model |
+| `DESIGN.md` | Executive design contract |
+| `docs/working-context.md` | Current priorities |
+| `docs/context-manifest.json` | Machine-readable file index |
+| `docs/agentic/modes/` | Task-specific modes (implementation, audit, pattern discovery, token proposal) |
+
+Agents operate in modes:
+
+- **Default** → Implementation
+- **Exploratory tasks** → Pattern Discovery or Token Proposal
+- **Review tasks** → Audit
+
+---
+
+## Documentation Structure
+
+| Directory | Content |
+|---|---|
+| `docs/foundations/` | Token layering, naming, theming, parity, and 12 foundation ADRs |
+| `docs/principles/` | Perception laws, heuristics, and accessibility intent |
+| `docs/patterns/` | Pattern-level composition guidance |
+| `docs/components/` | Component entry docs |
+| `docs/agentic/` | Agent behavior rules, modes, workflows, rule pipeline |
+| `docs/validation/` | CI pipeline, token parity, rule pipeline manifest |
+| `docs/token-pipeline.md` | Token generation pipeline and format reference |
+| `site/` | Docs site source (Eleventy) |
+
+---
+
 ## Local Development
 
+### Build
+
 ```bash
 npm run build:all       # generate tokens + build CSS
 npm run docs:dev        # build + serve docs site
 ```
 
-Figma sync workflow:
+### Figma Sync
 
 ```bash
-# 1. Export tokens via Figma plugin (📦 Export tab)
+# 1. Export tokens from Figma
 # 2. Place JSON files in figma/exports/
-# 3. Build
 npm run build:all
 ```
 
-Validation:
+### Validation
 
 ```bash
-npm run lint
-npm run test:unit
-npm run ci:check
+npm run ci:check        # full pipeline
+npm run tokens:validate # token structure
+npm run dtcg:validate   # DTCG compliance
+npm run rules:validate  # rule pipeline traceability
 ```
 
+---
+
 ## MCP Integration
 
-This repo supports Figma integration via MCP (Model Context Protocol). Two servers are used:
+Figma integration via Model Context Protocol:
 
 - `figma-developer-mcp` — REST API read access (requires `FIGMA_TOKEN` in `.env`)
-- Figma Desktop MCP — local server via Figma Desktop app (enable in Dev Mode inspect panel)
-
-Configure these in your agent's MCP config. Example for the REST API server:
+- Figma Desktop MCP — local server via Figma Desktop app
 
 ```json
 {
@@ -83,13 +213,16 @@ Configure these in your agent's MCP config. Example for the REST API server:
 }
 ```
 
-## Documentation
+---
+
+## Contributing
+
+- Follow token rules — no invented tokens, no hardcoded values
+- Use semantic tokens over primitives
+- Validate before commit: `npm run ci:check`
+- Work on feature branches
 
-- Foundations: `docs/foundations/`
-- AI playbook: `docs/agentic/team-ai-playbook.md`
-- Figma plugin (Token Foundry): `figma/plugin/README.md`
-- Docs site: `site/`
-- Vanilla starter: `site/examples/vanilla-starter.md`
+---
 
 ## Release
 
@@ -98,3 +231,13 @@ npm run release:patch   # or release:minor / release:major
 npm run release:push
 npm run release:publish
 ```
+
+---
+
+## Tech Stack
+
+Vanilla CSS (Custom Properties, `@layer`) · Node.js · Eleventy · React (optional wrappers) · Nunjucks macros · Figma MCP
+
+---
+
+Designed for consistency, built for scale, ready for agents.

package/dist/assets/icons/checkmark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><polyline points="4 12 10 18 20 6"/></svg>

package/dist/core/index.css

@@ -2,11 +2,11 @@
 @import url("./base/fonts.css") layer(base);
 @import url("./base/base.css") layer(base);
 @import url("./base/typography.css") layer(base);
-@import url("../tokens/css/semantics-(roles).tokens.css") layer(tokens);
-@import url("../tokens/css/components-(ui).tokens.css") layer(tokens);
-@import url("../tokens/css/appearance-(modes).tokens.mode-dark.css") layer(tokens);
-@import url("../tokens/css/appearance-(modes).tokens.mode-light.css") layer(tokens);
-@import url("../tokens/css/core-(primitives).tokens.css") layer(tokens);
-@import url("../tokens/css/themes-(brands).tokens.brand-a.css") layer(tokens);
-@import url("../tokens/css/themes-(brands).tokens.brand-b.css") layer(tokens);
+@import url("../tokens/css/core-primitives.tokens.css") layer(tokens);
+@import url("../tokens/css/semantics-roles.tokens.css") layer(tokens);
+@import url("../tokens/css/components-ui.tokens.css") layer(tokens);
+@import url("../tokens/css/appearance-modes.tokens.mode-dark.css") layer(tokens);
+@import url("../tokens/css/appearance-modes.tokens.mode-light.css") layer(tokens);
+@import url("../tokens/css/themes-brands.tokens.brand-a.css") layer(tokens);
+@import url("../tokens/css/themes-brands.tokens.brand-b.css") layer(tokens);
 @import url("./themes/mode.css") layer(themes);

package/dist/macros/ui.njk

@@ -0,0 +1,142 @@
+{% macro toggleButton(label, dataName, dataValue, variant='outline') -%}
+{%- set classes = "button" -%}
+{%- if variant -%}{%- set classes = classes + " " + variant -%}{%- endif -%}
+<button class="{{ classes }}" type="button"{% if dataName == "mode" %} data-mode="{{ dataValue }}"{% endif %}{% if dataName == "brand" %} data-brand="{{ dataValue }}"{% endif %}{% if dataName == "lang" %} data-lang="{{ dataValue }}"{% endif %} aria-pressed="false">{{ label }}</button>
+{%- endmacro %}
+
+{% macro button(label, variant='', disabled=false, type='button') -%}
+{%- set classes = "button" -%}
+{%- if variant -%}{%- set classes = classes + " " + variant -%}{%- endif -%}
+<button type="{{ type }}" class="{{ classes }}"{% if disabled %} disabled{% endif %}>{{ label }}</button>
+{%- endmacro %}
+
+{% macro buttonGroup(attached=false, orientation='horizontal', justify='start', ariaLabel='', className='') -%}
+{%- set resolvedOrientation = "vertical" if orientation == "vertical" else "horizontal" -%}
+{%- set resolvedJustify = "stretch" if justify == "stretch" else "start" -%}
+{%- set classes = "button-group" -%}
+{%- if className -%}{%- set classes = classes + " " + className -%}{%- endif -%}
+<div class="{{ classes }}" role="group" data-orientation="{{ resolvedOrientation }}" data-attached="{{ "true" if attached else "false" }}" data-justify="{{ resolvedJustify }}"{% if ariaLabel %} aria-label="{{ ariaLabel }}"{% endif %}>{{ caller() }}</div>
+{%- endmacro %}
+
+{% macro input(type='text', placeholder='', value='', state='default', disabled=false, className='', id='', name='', dataPlaygroundControl=false, dataProp='', dataSource='', dataValueType='', dataQueryParam='') -%}
+{%- set classes = "input" -%}
+{%- if state == "hover" -%}{%- set classes = classes + " is-hover" -%}{%- endif -%}
+{%- if state == "active" -%}{%- set classes = classes + " is-active" -%}{%- endif -%}
+{%- if state == "focus" -%}{%- set classes = classes + " is-focus-visible" -%}{%- endif -%}
+{%- if state == "disabled" -%}{%- set classes = classes + " is-disabled" -%}{%- endif -%}
+{%- if className -%}{%- set classes = classes + " " + className -%}{%- endif -%}
+<input class="{{ classes }}" type="{{ type }}"{% if id %} id="{{ id }}"{% endif %}{% if name %} name="{{ name }}"{% endif %}{% if placeholder %} placeholder="{{ placeholder }}"{% endif %}{% if value %} value="{{ value }}"{% endif %}{% if dataPlaygroundControl %} data-playground-control{% endif %}{% if dataProp %} data-prop="{{ dataProp }}"{% endif %}{% if dataSource %} data-source="{{ dataSource }}"{% endif %}{% if dataValueType %} data-value-type="{{ dataValueType }}"{% endif %}{% if dataQueryParam %} data-query-param="{{ dataQueryParam }}"{% endif %}{% if disabled or state == "disabled" %} disabled{% endif %} />
+{%- endmacro %}
+
+{% macro checkbox(label='Checkbox', checked=false, disabled=false, state='default', indeterminate=false, className='', wrapperClassName='', id='', name='', value='on') -%}
+{%- set checkboxClasses = "checkbox" -%}
+{%- set fieldClasses = "checkbox-field" -%}
+{%- if checked -%}{%- set checkboxClasses = checkboxClasses + " is-checked" -%}{%- endif -%}
+{%- if indeterminate or state == "indeterminate" -%}{%- set checkboxClasses = checkboxClasses + " is-indeterminate" -%}{%- endif -%}
+{%- if state == "hover" -%}{%- set checkboxClasses = checkboxClasses + " is-hover" -%}{%- endif -%}
+{%- if state == "active" -%}{%- set checkboxClasses = checkboxClasses + " is-active" -%}{%- endif -%}
+{%- if state == "focus" -%}{%- set checkboxClasses = checkboxClasses + " is-focus-visible" -%}{%- endif -%}
+{%- if disabled or state == "disabled" -%}
+  {%- set checkboxClasses = checkboxClasses + " is-disabled" -%}
+  {%- set fieldClasses = fieldClasses + " is-disabled" -%}
+{%- endif -%}
+{%- if className -%}{%- set checkboxClasses = checkboxClasses + " " + className -%}{%- endif -%}
+{%- if wrapperClassName -%}{%- set fieldClasses = fieldClasses + " " + wrapperClassName -%}{%- endif -%}
+<label class="{{ fieldClasses }}">
+  <input class="{{ checkboxClasses }}" type="checkbox"{% if id %} id="{{ id }}"{% endif %}{% if name %} name="{{ name }}"{% endif %}{% if value %} value="{{ value }}"{% endif %}{% if checked %} checked{% endif %}{% if indeterminate or state == "indeterminate" %} aria-checked="mixed"{% endif %}{% if disabled or state == "disabled" %} disabled{% endif %} />
+  <span class="checkbox-field__text">{{ label }}</span>
+</label>
+{%- endmacro %}
+
+{% macro radio(label='Option', checked=false, disabled=false, state='default', className='', wrapperClassName='', id='', name='', value='') -%}
+{%- set radioClasses = "radio" -%}
+{%- set fieldClasses = "radio-field" -%}
+{%- if checked -%}{%- set radioClasses = radioClasses + " is-checked" -%}{%- endif -%}
+{%- if state == "hover" -%}{%- set radioClasses = radioClasses + " is-hover" -%}{%- endif -%}
+{%- if state == "active" -%}{%- set radioClasses = radioClasses + " is-active" -%}{%- endif -%}
+{%- if state == "focus" -%}{%- set radioClasses = radioClasses + " is-focus-visible" -%}{%- endif -%}
+{%- if disabled or state == "disabled" -%}
+  {%- set radioClasses = radioClasses + " is-disabled" -%}
+  {%- set fieldClasses = fieldClasses + " is-disabled" -%}
+{%- endif -%}
+{%- if className -%}{%- set radioClasses = radioClasses + " " + className -%}{%- endif -%}
+{%- if wrapperClassName -%}{%- set fieldClasses = fieldClasses + " " + wrapperClassName -%}{%- endif -%}
+<label class="{{ fieldClasses }}">
+  <input class="{{ radioClasses }}" type="radio"{% if id %} id="{{ id }}"{% endif %}{% if name %} name="{{ name }}"{% endif %}{% if value %} value="{{ value }}"{% endif %}{% if checked %} checked{% endif %}{% if disabled or state == "disabled" %} disabled{% endif %} />
+  <span class="radio-field__text">{{ label }}</span>
+</label>
+{%- endmacro %}
+
+{% macro switch(label='Notifications', checked=false, disabled=false, state='default', className='', wrapperClassName='', id='', name='', value='on') -%}
+{%- set switchClasses = "switch" -%}
+{%- set fieldClasses = "switch-field" -%}
+{%- if checked -%}{%- set switchClasses = switchClasses + " is-checked" -%}{%- endif -%}
+{%- if state == "hover" -%}{%- set switchClasses = switchClasses + " is-hover" -%}{%- endif -%}
+{%- if state == "active" -%}{%- set switchClasses = switchClasses + " is-active" -%}{%- endif -%}
+{%- if state == "focus" -%}{%- set switchClasses = switchClasses + " is-focus-visible" -%}{%- endif -%}
+{%- if disabled or state == "disabled" -%}
+  {%- set switchClasses = switchClasses + " is-disabled" -%}
+  {%- set fieldClasses = fieldClasses + " is-disabled" -%}
+{%- endif -%}
+{%- if className -%}{%- set switchClasses = switchClasses + " " + className -%}{%- endif -%}
+{%- if wrapperClassName -%}{%- set fieldClasses = fieldClasses + " " + wrapperClassName -%}{%- endif -%}
+<label class="{{ fieldClasses }}">
+  <input class="{{ switchClasses }}" type="checkbox" role="switch"{% if id %} id="{{ id }}"{% endif %}{% if name %} name="{{ name }}"{% endif %}{% if value %} value="{{ value }}"{% endif %}{% if checked %} checked{% endif %}{% if disabled or state == "disabled" %} disabled{% endif %} />
+  <span class="switch-field__text">{{ label }}</span>
+</label>
+{%- endmacro %}
+
+{% macro colorChip(token) -%}
+<div class="swatch" style="--swatch-color: var({{ token.cssVar }})">
+  <span class="swatch-name">{{ token.name }}</span>
+  <span class="swatch-meta">{{ token.value }}</span>
+</div>
+{%- endmacro %}
+
+{% macro icon(name, label='', className='') -%}
+{%- set classes = "icon" -%}
+{%- if className -%}{%- set classes = classes + " " + className -%}{%- endif -%}
+<span class="{{ classes }}" style="--icon-src: url('/assets/icons/{{ name }}.svg');"{% if label %} role="img" aria-label="{{ label }}"{% else %} aria-hidden="true"{% endif %}></span>
+{%- endmacro %}
+
+{% macro labelContent(text='', startIcon='', endIcon='', iconOnly=false) -%}
+<span class="label-content{% if iconOnly %} is-icon-only{% endif %}">
+  {%- if startIcon %}<span class="icon" data-slot="start" style="--icon-src: url('/assets/icons/{{ startIcon }}.svg');" aria-hidden="true"></span>{% endif -%}
+  {%- if not iconOnly %}<span class="label-content__text">{{ text }}</span>{% endif -%}
+  {%- if endIcon %}<span class="icon" data-slot="end" style="--icon-src: url('/assets/icons/{{ endIcon }}.svg');" aria-hidden="true"></span>{% endif -%}
+</span>
+{%- endmacro %}
+
+{% macro fieldLabel(text, htmlFor='', required=false, startIcon='') -%}
+<label class="field-label"{% if htmlFor %} for="{{ htmlFor }}"{% endif %}>
+  <span class="label-content">
+    {%- if startIcon %}<span class="icon" data-slot="start" style="--icon-src: url('/assets/icons/{{ startIcon }}.svg');" aria-hidden="true"></span>{% endif -%}
+    <span class="label-content__text">{{ text }}</span>
+  </span>
+  {%- if required %}
+  <span class="field-label__required" aria-hidden="true">*</span>
+  <span class="field-label__required-text"> (required)</span>
+  {%- endif %}
+</label>
+{%- endmacro %}
+
+{% macro link(text, href='#', startIcon='', endIcon='', state='', disabled=false) -%}
+{%- set classes = "link" -%}
+{%- if state -%}{%- set classes = classes + " is-" + state -%}{%- endif -%}
+{%- if disabled -%}{%- set classes = classes + " is-disabled" -%}{%- endif -%}
+<a class="{{ classes }}" href="{{ href }}"{% if disabled %} aria-disabled="true"{% endif %}>
+  {%- if startIcon %}<span class="icon" style="--icon-src: url('/assets/icons/{{ startIcon }}.svg');" aria-hidden="true"></span> {% endif -%}
+  {{ text }}
+  {%- if endIcon %} <span class="icon" style="--icon-src: url('/assets/icons/{{ endIcon }}.svg');" aria-hidden="true"></span>{% endif -%}
+</a>
+{%- endmacro %}
+
+{% macro badge(text, variant='', size='', startIcon='') -%}
+{%- set classes = "badge" -%}
+{%- if variant -%}{%- set classes = classes + " " + variant -%}{%- endif -%}
+{%- if size == "sm" -%}{%- set classes = classes + " sm" -%}{%- endif -%}
+<span class="{{ classes }}">
+  {%- if startIcon %}<span class="icon" style="--icon-src: url('/assets/icons/{{ startIcon }}.svg');" aria-hidden="true"></span>{% endif -%}
+  <span class="badge__text">{{ text }}</span>
+</span>
+{%- endmacro %}