Skip to content
BranchesTags

Repository files navigation

╭─────────────────╖
│ 16              ║
│            ⬤   ║
│   ██   ██       ║
│   ██   ██  ██   ║
│   ██   ██  ██   ║
│   ░▒███▒░  ██   ║
├─────────────────╢
│   Foundations   ║
╘═════════════════╝

UI Foundations

Keep Figma and code in sync by default — with tokens, not guesswork.

  • 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 · Starter Template · npm · Figma Library

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 → Appearance → Semantics (Brands) → Patterns/Components, 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          │
 └───────────────┬─────────────────┘
                 ▼
 ┌─────────────────────────────────┐
 │  figma/exports/*.tokens.json    │
 └───────────────┬─────────────────┘
                 ▼
 ┌─────────────────────────────────┐
 │       extract-tokens.js         │
 └───────────────┬─────────────────┘
     ┌───────────┼───────────┐
     ▼           ▼           ▼
 ┌───────┐  ┌───────┐  ┌───────┐
 │  CSS  │  │ JSON  │  │ TS/YML│
 └───────┘  └───────┘  └───────┘

 dist/
 ├── tokens/
 │   ├── css/   ← Custom Properties
 │   ├── json/  ← DTCG-compliant
 │   ├── ts/    ← TypeScript constants
 │   └── tokens.yaml ← Flat index
 ├── core/      ← Reset + Base + Tokens
 ├── ui/        ← Component patterns
 ├── elements/  ← Light-DOM Web Components
 └── main.css   ← Bundled (all layers)

Layering

Token layers from foundation to surface:

   ╱─ PATTERN/COMPONENT   Scoped usage tokens
  ╱── SEMANTICS (BRANDS)  Brand-scoped semantic roles
 ╱─── APPEARANCE          Mode-dependent decisions
╱──── CORE                Primitive/reference values

Patterns consume semantic roles or Core tokens. Never raw values.

Component Integration

Every pattern ships with:

 ┌────────────┬────────────┬────────────┐
 │ CSS pattern│ Nunjucks   │ Playground │
 ├────────────┼────────────┼────────────┤
 │ Docs page  │ Web Comp.  │ Code Conn. │
 └────────────┴────────────┴────────────┘

All surfaces must be present for the pattern 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
  • Brand and appearance context 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

Getting Started

Install

npm install ui-foundations

Import

@import "ui-foundations/core.css";
@import "ui-foundations/ui.css";

Use Patterns (plain HTML)

<button class="uif-button solid">Label</button>
<button class="uif-button outline">Outline</button>
<input class="uif-input" type="text" />

Optional: Web Components

import "ui-foundations/elements/ui-button";
<uif-button variant="outline">Label</uif-button>

The light-DOM Custom Elements are the canonical convenience layer. They render the same semantic HTML used by the CSS patterns and work across frameworks. Consumers upgrading to v1 should follow the React removal migration guide. For the v1 macro alias and Custom Element tag changes, see the public API namespace migration guide. For the Runtime-facing canonical API summary, see Public API Surface (v1).

Documentation quickstart

If you are new to this repository, start with:

  1. Documentation map
  2. Runtime architecture overview
  3. Public API Surface (v1)
  4. Foundations overview
  5. Patterns and components entry
  6. Validation checks

Terminology and source-traceability references:

Apply Theming

document.documentElement.dataset.brand = "a";     // "a" | "b" | "c"
document.documentElement.dataset.mode  = "light";  // "light" | "dark"

Explore the docs site or the vanilla starter to see it in action.

Patterns

CSS-only, stateless UI building blocks. No JavaScript required.

 ┌──────────┬──────────┬──────────┬──────────┐
 │ Button   │ Input    │ Checkbox │ Radio    │
 ├──────────┼──────────┼──────────┼──────────┤
 │ Switch   │ Tabs     │ Accordion│ Tooltip  │
 ├──────────┼──────────┼──────────┼──────────┤
 │ Badge    │ Avatar   │ Divider  │ Link     │
 ├──────────┼──────────┼──────────┼──────────┤
 │ Label    │ TextArea │ Icon     │ Select   │
 ├──────────┼──────────┼──────────┼──────────┤
 │ Form     │ FormGroup│          │          │
 └──────────┴──────────┴──────────┴──────────┘

Each pattern uses semantic tokens and supports theming out of the box. See docs/patterns/README.md for hierarchy and status.

Components

Runtime currently exposes component-facing behavior through light-DOM Custom Elements in src/elements/ (for example: ui-button, ui-input, ui-tabs, ui-tooltip, ui-select).

Standalone product-component documentation is tracked through docs/components/README.md, including explicit placeholder topics and status.

Agent Integration

 ┌─────────────────────────────────────────┐
 │ AGENTS.md                               │
 │ ├── DESIGN.md                           │
 │ ├── docs/playbook.md                    │
 │ ├── docs/working-context.md             │
 │ ├── docs/ui-foundations-rules.md        │
 │ ├── docs/agentic/modes/                 │
 │ │   ├── implementation                  │
 │ │   ├── audit                           │
 │ │   ├── pattern-discovery               │
 │ │   └── token-proposal                  │
 │ └── docs/context-manifest.json          │
 └─────────────────────────────────────────┘

Agents operate in modes:

  • Default → Implementation
  • Exploratory tasks → Pattern Discovery or Token Proposal
  • Review tasks → Audit

Documentation Structure

 docs/
 ├── foundations/    ← Token layering, naming, foundation records
 ├── patterns/       ← Pattern hierarchy and composition guidance
 ├── components/     ← Component-facing status and entry points
 ├── agentic/        ← Agent rules, modes, workflows
 ├── validation/     ← CI pipeline, parity checks
 └── token-pipeline.md
 site/
 ├── patterns/      ← Pattern docs + playgrounds
 ├── foundations/   ← Token and principle pages
 └── examples/     ← Usage examples

Local Development

Build

npm run build:all       # generate tokens + build CSS
npm run docs:dev        # build + serve docs site

Build Output

╭──────────────────────────────────────╮
│ ╻╻· │ FOUNDATIONS                    │
│ ┗┛╹ │ BUILD 0.8.1                    │
╰──────────────────────────────────────╯
█ ICONS                             [OK]
├ Entries                           0289
└ Output                   icon-names.ts
────────────────────────────────────────
█ TOKENS
├ CSS                              READY
├ JSON                             READY
├ TypeScript                       READY
└ YAML                             READY
────────────────────────────────────────
█ INTEGRITY                         [OK]
├ Missing WEB                       0000
├ Unparseable WEB                   0000
└ Duplicate vars                    0000
────────────────────────────────────────
█ DIST                              [OK]
├ Token CSS                         0008
├ Macros                           READY
└ Bundles                          READY
────────────────────────────────────────
BUILD OK · READY · 503ms

Figma Sync

# Option A: Manual export from Figma plugin → place files → build
npm run build:all

# Option B: Agent-assisted sync via MCP (recommended)
npm run tokens:sync

Validation

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

Figma integration uses the Model Context Protocol. Token exports live in figma/exports/ and are processed by npm run tokens:generate.

 ┌────────────────────┐     ┌───────────────────┐
 │   Figma Desktop    │────▶│  Local MCP Server │
 └────────────────────┘     └────────┬──────────┘
                                     │
                                     ▼
                            ┌───────────────────┐
                            │  figma/exports/   │
                            └───────────────────┘
  • Figma Desktop MCP — local server via the Figma Desktop app (primary path)
  • figma-developer-mcp — REST API read access (requires FIGMA_TOKEN in .env)
{
  "command": "npx",
  "args": ["-y", "figma-developer-mcp", "--figma-api-key=YOUR_TOKEN", "--stdio"]
}

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

Adding a New Pattern

Load the #pattern-creation steering file for the full 10-phase workflow. Key steps: semantic HTML first, then Figma tokens (bind variables, never hardcode), CSS pattern, Nunjucks macro, Web Component, docs page, playground, Code Connect.

Release

npm run release:patch   # or release:minor / release:major
npm run release:push
npm run release:publish

Tech Stack

 ┌────────────────┬───────────────────────────┐
 │ Tokens         │ CSS Custom Properties     │
 ├────────────────┼───────────────────────────┤
 │ Build          │ Node.js                   │
 ├────────────────┼───────────────────────────┤
 │ Docs           │ Eleventy + Nunjucks       │
 ├────────────────┼───────────────────────────┤
 │ Design         │ Figma + MCP               │
 ├────────────────┼───────────────────────────┤
 │ Patterns       │ Vanilla CSS (@layer)      │
 ├────────────────┼───────────────────────────┤
 │ Convenience    │ Light-DOM Web Components  │
 └────────────────┴───────────────────────────┘

Roadmap

  • Calendar Component — first functional component with state, date logic, and keyboard navigation. Built on top of existing patterns.
  • Navigation Key Tips — experimental Alt-triggered keyboard shortcuts for fast docs navigation (available now).
  • UIF public namespace — migrate Custom Element tags from the legacy ui-* namespace to the approved uif-* namespace for v1.0.

PolyForm Noncommercial License 1.0.0

About

Runtime assets for the UI Foundations ecosystem.

ui-foundations.com/

Topics

design-systemdesign-tokensui-foundation

Resources

Readme
License
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages