ui-foundations 0.1.2 → 0.3.0

package/README.md

@@ -1,13 +1,26 @@
 # UI Foundations
 
-Token-first UI foundations aligned with Figma variables.
+A token-first design system that uses Figma as the single source of truth and automatically generates CSS, JSON, and TypeScript tokens.
 
-This package provides:
+## Pipeline
 
-- foundation and semantic design tokens
-- UI pattern CSS
-- optional React wrappers
-- docs/playground via Eleventy
+```
+Figma Variables → Plugin Export → figma/exports/*.tokens.json → extract-tokens.js → dist/ (CSS, JSON, TS, YAML)
+```
+
+## Features
+
+- 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
+
+## Tech Stack
+
+Vanilla CSS (Custom Properties, Layers), Node.js scripts, Eleventy, Figma Plugin API, MCP.
 
 ## Install
 
@@ -15,26 +28,14 @@ This package provides:
 npm install ui-foundations
 ```
 
-## Package Usage
+## Usage
 
 ```js
 import "ui-foundations/core.css";
 import "ui-foundations/ui.css";
 ```
 
-Optional token imports:
-
-```js
-import "ui-foundations/tokens/primitives.css";
-import "ui-foundations/tokens/brand-a.css";
-import "ui-foundations/tokens/brand-b.css";
-import "ui-foundations/tokens/color-light.css";
-import "ui-foundations/tokens/color-dark.css";
-import "ui-foundations/tokens/semantic.css";
-import "ui-foundations/tokens/components.css";
-```
-
-Runtime scope example:
+Runtime scope switching:
 
 ```js
 const root = document.documentElement;
@@ -42,25 +43,58 @@ root.dataset.brand = "a"; // "a" | "b"
 root.dataset.mode = "light"; // "light" | "dark"
 ```
 
-## Documentation
+## Local Development
 
-- Foundations (source of truth): `docs/foundations/`
-- Workflow + pipeline details: `docs/foundations/foundation-010-implementation-and-pipeline-workflow.md`
-- AI playbook: `docs/agentic/team-ai-playbook.md`
-- Shareable skill: `docs/agentic/skills/design-ops-specialist/SKILL.md`
-- Docs site content: `site/`
-- Vanilla starter guide: `site/examples/vanilla-starter.md`
+```bash
+npm run build:all       # generate tokens + build CSS
+npm run docs:dev        # build + serve docs site
+```
 
-## Local Development
+Figma sync workflow:
 
 ```bash
-npm run docs:dev
+# 1. Export tokens via Figma plugin (📦 Export tab)
+# 2. Place JSON files in figma/exports/
+# 3. Build
+npm run build:all
 ```
 
-Validation baseline:
+Validation:
 
 ```bash
 npm run lint
 npm run test:unit
 npm run ci:check
 ```
+
+## MCP Integration
+
+This repo supports Figma integration via MCP (Model Context Protocol). Two servers are used:
+
+- `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:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "figma-developer-mcp", "--figma-api-key=YOUR_TOKEN", "--stdio"]
+}
+```
+
+## Documentation
+
+- 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
+
+```bash
+npm run release:patch   # or release:minor / release:major
+npm run release:push
+npm run release:publish
+```

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/primitives.tokens.css") layer(tokens);
-@import url("../tokens/css/brand-a.tokens.css") layer(tokens);
-@import url("../tokens/css/brand-b.tokens.css") layer(tokens);
-@import url("../tokens/css/semantic.tokens.css") layer(tokens);
-@import url("../tokens/css/component.tokens.css") layer(tokens);
-@import url("../tokens/css/color.light.tokens.css") layer(tokens);
-@import url("../tokens/css/color.dark.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/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("./themes/mode.css") layer(themes);