ui-foundations 0.1.1 → 0.1.2

package/README.md

@@ -1,259 +1,66 @@
 # UI Foundations
 
-This repository contains the **foundation layer** of our UI platform:
+Token-first UI foundations aligned with Figma variables.
 
-- Design tokens (core primitives, color modes, semantic roles)
-- Component token APIs (variants, parts, properties, states)
-- Foundational architecture rules for long-term consistency
-- Docs/playground generated with Eleventy
+This package provides:
 
-## What this is
+- foundation and semantic design tokens
+- UI pattern CSS
+- optional React wrappers
+- docs/playground via Eleventy
 
-- A **token-first** foundation that aligns **Figma Variables** with **CSS custom properties**
-- A **multi-brand** and **multi-mode** ready architecture
-- A place to document foundational rules that must remain stable over time
+## Install
 
-## What this is not (yet)
-
-- A full “product design system” with all patterns, usage guidelines, and governance
-- Product-specific application rules (these live downstream in product repositories)
-
-## Architecture (4 layers)
-
-1. **Core (Primitives)**  
-   Raw physical values: spacing, radii, borders, typography primitives, layout constants.
-
-2. **Color Modes (Light/Dark)**  
-   Theme palettes: brand colors, neutrals, overlays. No semantic meaning.
-
-3. **Semantics (Roles)**  
-   Meaning-based roles: `Color.Text.*`, `Color.Fill.*`, `Color.Border.*`, `Typography.*`, `Corner.*`.  
-   Supports brand modes (e.g. TUI, ROBINSON, LTUR).
-
-4. **Components (APIs)**  
-   Component-level API rules: variants, parts, properties, states.  
-   Components reference semantic roles—**never raw values**.
-
-## Naming conventions
-
-Component tokens use a **variant-first** grouping:
-
-`Component.variant.part.property.state`
-
-Example:
-
-- `Button.solid.container.background.default`
-- `Button.outline.container.border-color.hover`
-
-Rules:
-
-- **Typography never includes color** (color lives in `Color.Text.*`)
-- **Components never introduce new colors** (they reference semantic roles)
-- Layout primitives (breakpoints, container sizes, z-index) live in **Core**
-
-## Repository structure
-
-- `figma/exports/` — token source exports from Figma
-- `dist/tokens/` — generated token artifacts (CSS/JSON/TS)
-- `src/` — package source layers (Core/UI/React)
-- `site/` — Eleventy preview/docs site (templates + docs-specific CSS)
-- `docs/foundations/` — foundational architecture and token rules (source of truth)
-- `docs/agentic/` — assistant behavior rules and AI collaboration playbooks
-- `figma/` — Figma exports, mappings, Code Connect notes
-- `AGENTS.md` — entrypoint for AI coding agents
-
-Docs structure (`site/`):
-- `_includes/layouts/` — shared Nunjucks layouts
-- `tokens/*.md` — token docs pages (Eleventy collection)
-- `components/*.md` — component docs pages (Eleventy collection)
-- `assets/docs.css` — docs-only styling
-
-AI collaboration:
-- `AGENTS.md` — quick entrypoint and baseline checks for agents
-- `docs/agentic/assistant-behavior-rules.md` — assistant-specific guardrails
-- `docs/agentic/team-ai-playbook.md` — standard AI-assisted workflows for component incubation and token roundtrips
-
-## Flow: Add a new component
-
-```text
-Figma
-├─ 0) Run boundary + utility check
-│  ├─ Is this a standalone component or composition of an existing one?
-│  └─ Snowflake check: one-off local case vs shared cross-context utility
-├─ 1) Create/update component tokens
-│  └─ figma/exports/Component.tokens.json
-├─ 2) (Optional) Add/update Code Connect mapping
-│  └─ figma/connections/web-<component>.figma.ts
-└─ 3) Regenerate generated artifacts
-   └─ npm run build:all
-      ├─ dist/tokens/*
-      ├─ dist/ui/*
-      ├─ dist/react/*
-      └─ dist/main.css
-
-Repository implementation
-├─ 4) Add CSS pattern
-│  └─ src/ui/patterns/<component>.css
-├─ 5) Export pattern in UI bundle
-│  └─ src/ui/index.css
-├─ 6) Add React wrapper (if needed)
-│  ├─ src/react/<component>.js
-│  └─ src/react/index.js
-└─ 7) Add assets (if needed)
-   └─ src/assets/*
-
-Documentation + Playground
-├─ 8) Add component docs page
-│  └─ site/components/<component>.md
-├─ 9) Add playground page
-│  └─ site/components/<component>-playground.md
-├─ 10) Extend macros (if needed)
-│   └─ site/_includes/macros/{ui.njk,playground.njk}
-└─ 11) Extend playground runtime (only for new behavior)
-   └─ site/assets/playground/{renderers.js,state.js,code.js,shared.js}
-
-Validation
-├─ npm run test:unit
-├─ npm run build:all
-├─ npm run docs:site
-└─ npm run ci:check
+```bash
+npm install ui-foundations
 ```
 
-## Flow: AI-assisted component incubation
+## Package Usage
 
-This project is designed for a collaborative build loop between design and implementation, not only for one-way token export.
-
-```text
-Collaborative loop (real-world workflow)
-├─ 0) Run boundary + utility check
-│  ├─ standalone component or composition inside an existing component family
-│  └─ Snowflake check: solves one local case or reusable across contexts
-├─ 1) Ask the assistant for a proposed component setup
-│  ├─ component structure (HTML/CSS/React)
-│  ├─ token naming proposal
-│  └─ docs/playground example
-├─ 2) Review and adapt the proposal
-│  └─ align names and states with your design language
-├─ 3) Create/import the proposed tokens in Figma
-│  └─ refine values and variants in design
-├─ 4) Export from Figma back into this repository
-│  └─ figma/exports/*.tokens.json
-├─ 5) Let the assistant integrate and align implementation
-│  ├─ src/ui/patterns/<component>.css
-│  ├─ src/react/<component>.js
-│  ├─ site/components/<component>.md
-│  ├─ site/components/<component>-playground.md
-│  └─ figma/connections/web-<component>.figma.ts (if needed)
-└─ 6) Validate and iterate
-   ├─ npm run ci:check
-   └─ repeat loop for naming, states, a11y, and behavior refinements
+```js
+import "ui-foundations/core.css";
+import "ui-foundations/ui.css";
 ```
 
-Why this matters:
-- It closes the gap between design intent and production implementation.
-- It keeps token naming and component APIs consistent across Figma and code.
-- It makes component incubation faster while staying auditable in Git.
-
-## Script locations
-
-- `scripts/` — build, token extraction, validation, lint and smoke-check automation for local/CI usage
-- `site/assets/playground/` — browser runtime modules for docs playground (shared helpers, state, code formatting, renderers)
-- `tests/` — unit tests for extraction helpers and edge-case behavior
-
-## CSS variable naming
-
-CSS custom property names are derived from `com.figma.codeSyntax.WEB`.
-If a token is missing `codeSyntax.WEB`, a warning is logged and the build
-falls back to an auto-derived token name.
-
-Scopes are derived from export filenames:
-
-- `Brand X.tokens.json` -> `:root[data-brand="x"]`
-- `Mode Light.tokens.json` -> `:root`
-- `Mode Dark.tokens.json` -> `:root[data-mode="dark"]`
-
-## Specification compliance
-
-Generated JSON tokens follow the official Design Tokens Community Group format where applicable:
-
-- W3C DTCG format: `https://www.designtokens.org/tr/drafts/format/`
-- Export normalization maps Figma values to spec-friendly types (for example `dimension`, `fontFamily`, `fontWeight`)
-- `fontWeight` values are emitted numerically in generated JSON, even if authored as strings in Figma
-- Distributed JSON in `dist/tokens/json/*.json` strips `com.figma.*` metadata for cleaner consumer output
-- Optional: include Figma metadata sidecars with `npm run tokens:generate -- --include-figma-metadata` (writes `*.figma.json`)
-
-## Quick start (local)
+Optional token imports:
 
-1. Read the foundation rules in `docs/foundations/`
-2. Inspect source tokens in `figma/exports/` and generated tokens in `dist/tokens/`
-3. Run `npm run docs:dev`
-
-## Prompt to UI Component
-
-Use this copy/paste prompt with AI when you want a new component scaffolded and implemented in this repo:
-
-```text
-Scaffold and implement a new UI component named <component-name> in this repository.
-
-Follow these sources strictly:
-- docs/agentic/team-ai-playbook.md
-- docs/agentic/assistant-behavior-rules.md
-- docs/foundations/*
-
-Execution requirements:
-1) Run the Component Boundary Check first and state the decision (composition vs standalone).
-2) Keep scope small, incremental, and reviewable in Git.
-3) Implement token-first and reuse existing patterns:
-   - src/ui/patterns/<component>.css
-   - src/react/<component>.js and src/react/index.js (if needed)
-   - site/components/<component>.md
-   - site/components/<component>-playground.md
-   - figma/connections/web-<component>.figma.ts (only if a publishable top-level Figma component/component-set exists)
-4) Validate before handoff:
-   - npm run lint
-   - npm run test:unit
-   - npm run ci:check
-
-Mandatory progress tracker for this task type:
-- Start with: Tasks completion: 0/4
-- Update after each phase: 1/4, 2/4, 3/4, 4/4
-
-Handoff format:
-- boundary decision result
-- files changed
-- validation results
-- open follow-ups (if any)
+```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";
 ```
 
-## Build (local)
+Runtime scope example:
 
-1. Optional syntax lint for JS files: `npm run lint`
-2. Optional unit tests for extractor helpers: `npm run test:unit`
-3. Generate token outputs (after Figma export updates): `npm run tokens:generate`
-4. Build CSS bundles from already generated tokens: `npm run build:css`
-5. Full refresh in one command (tokens + CSS): `npm run build:all`
-6. Run smoke checks for generated artifacts: `npm run smoke:check`
-7. Build docs: `npm run docs:site`
-8. Run CI-equivalent checks locally: `npm run ci:check`
+```js
+const root = document.documentElement;
+root.dataset.brand = "a"; // "a" | "b"
+root.dataset.mode = "light"; // "light" | "dark"
+```
 
-`npm run build:css` fails if `dist/tokens/css/*.tokens.css` does not exist yet.
+## Documentation
 
-## Token Pipeline Internals
+- 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`
 
-`scripts/extract-tokens.js` is the orchestration entry point.
+## Local Development
 
-Main helper modules:
-- `scripts/extract-tokens.utils.js` — parsing + normalization helpers (`readJsonLike`, `parseWebSyntax`, length/path utilities)
-- `scripts/extract-tokens.lookup.js` — alias lookup + cycle/missing-target handling
-- `scripts/extract-tokens.value.js` — token grouping + output value formatting
-- `scripts/extract-tokens.scope.js` — scope parsing and selector/output-base normalization
+```bash
+npm run docs:dev
+```
 
-Data flow:
-1. Read `figma/exports/*.tokens.json` (JSON/JSONC supported)
-2. Flatten tokens + resolve aliases across the combined lookup
-3. Assign CSS variable names from `com.figma.codeSyntax.WEB`
-4. Emit `dist/tokens/{css,json,ts}` and `dist/tokens/tokens.yaml`
+Validation baseline:
 
-Fallback behavior:
-- Missing or invalid `com.figma.codeSyntax.WEB` values fall back to auto-derived CSS variable names and are reported in the extract summary.
-- Missing alias targets and alias cycles fall back to literal values and are reported.
+```bash
+npm run lint
+npm run test:unit
+npm run ci:check
+```

package/dist/main.css

@@ -181,7 +181,7 @@
   }
 }
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.474Z */
+/* Generated on 2026-03-04T21:56:02.562Z */
 
 :root {
   --color-transparent: rgba(0 0 0 / 0);
@@ -308,7 +308,7 @@
   --zindex-tooltip: 1070;
 }
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.456Z */
+/* Generated on 2026-03-04T21:56:02.552Z */
 
 :root[data-brand="a"] {
   --brand-color-primary: var(--color-brand-a-purple-600);
@@ -330,7 +330,7 @@
   --brand-corner-modal: var(--size-radius-400);
 }
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.458Z */
+/* Generated on 2026-03-04T21:56:02.554Z */
 
 :root[data-brand="b"] {
   --brand-color-primary: var(--color-brand-b-blue-500);
@@ -352,7 +352,7 @@
   --brand-corner-modal: var(--size-radius-200);
 }
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.476Z */
+/* Generated on 2026-03-04T21:56:02.563Z */
 
 :root {
   --typography-code: var(--font-family-mono);
@@ -387,7 +387,7 @@
   --corner-modal-radius: var(--brand-corner-modal);
 }
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.464Z */
+/* Generated on 2026-03-04T21:56:02.558Z */
 
 :root {
   --button-font-family: var(--brand-font-lead);
@@ -490,7 +490,7 @@
   --form-field-helper-text-color-invalid: var(--color-text-danger);
 }
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.470Z */
+/* Generated on 2026-03-04T21:56:02.560Z */
 
 :root {
   --color-focus: var(--brand-color-primary);
@@ -522,7 +522,7 @@
   --color-overlay-selected: var(--color-neutral-alpha-600);
 }
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.468Z */
+/* Generated on 2026-03-04T21:56:02.559Z */
 
 :root[data-mode="dark"] {
   --color-focus: var(--brand-color-primary-dark);

package/dist/tokens/css/brand-a.tokens.css

@@ -1,5 +1,5 @@
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.456Z */
+/* Generated on 2026-03-04T21:56:02.552Z */
 
 :root[data-brand="a"] {
   --brand-color-primary: var(--color-brand-a-purple-600);

package/dist/tokens/css/brand-b.tokens.css

@@ -1,5 +1,5 @@
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.458Z */
+/* Generated on 2026-03-04T21:56:02.554Z */
 
 :root[data-brand="b"] {
   --brand-color-primary: var(--color-brand-b-blue-500);

package/dist/tokens/css/color.dark.tokens.css

@@ -1,5 +1,5 @@
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.468Z */
+/* Generated on 2026-03-04T21:56:02.559Z */
 
 :root[data-mode="dark"] {
   --color-focus: var(--brand-color-primary-dark);

package/dist/tokens/css/color.light.tokens.css

@@ -1,5 +1,5 @@
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.470Z */
+/* Generated on 2026-03-04T21:56:02.560Z */
 
 :root {
   --color-focus: var(--brand-color-primary);

package/dist/tokens/css/component.tokens.css

@@ -1,5 +1,5 @@
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.464Z */
+/* Generated on 2026-03-04T21:56:02.558Z */
 
 :root {
   --button-font-family: var(--brand-font-lead);

package/dist/tokens/css/primitives.tokens.css

@@ -1,5 +1,5 @@
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.474Z */
+/* Generated on 2026-03-04T21:56:02.562Z */
 
 :root {
   --color-transparent: rgba(0 0 0 / 0);

package/dist/tokens/css/semantic.tokens.css

@@ -1,5 +1,5 @@
 /* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-04T21:31:32.476Z */
+/* Generated on 2026-03-04T21:56:02.563Z */
 
 :root {
   --typography-code: var(--font-family-mono);

package/dist/tokens/tokens.yaml

@@ -1,5 +1,5 @@
 # Auto-generated design tokens from Figma
-# Generated on 2026-03-04T21:31:32.490Z
+# Generated on 2026-03-04T21:56:02.574Z
 
 summary:
   total: 338

package/dist/tokens/ts/brand-a.tokens.ts

@@ -1,5 +1,5 @@
 // Auto-generated design tokens from Figma
-// Generated on 2026-03-04T21:31:32.457Z
+// Generated on 2026-03-04T21:56:02.553Z
 
 export const tokens = {
   "colors": {

package/dist/tokens/ts/brand-b.tokens.ts

@@ -1,5 +1,5 @@
 // Auto-generated design tokens from Figma
-// Generated on 2026-03-04T21:31:32.458Z
+// Generated on 2026-03-04T21:56:02.554Z
 
 export const tokens = {
   "colors": {

package/dist/tokens/ts/color.dark.tokens.ts

@@ -1,5 +1,5 @@
 // Auto-generated design tokens from Figma
-// Generated on 2026-03-04T21:31:32.468Z
+// Generated on 2026-03-04T21:56:02.559Z
 
 export const tokens = {
   "colors": {

package/dist/tokens/ts/color.light.tokens.ts

@@ -1,5 +1,5 @@
 // Auto-generated design tokens from Figma
-// Generated on 2026-03-04T21:31:32.470Z
+// Generated on 2026-03-04T21:56:02.560Z
 
 export const tokens = {
   "colors": {

package/dist/tokens/ts/component.tokens.ts

@@ -1,5 +1,5 @@
 // Auto-generated design tokens from Figma
-// Generated on 2026-03-04T21:31:32.464Z
+// Generated on 2026-03-04T21:56:02.558Z
 
 export const tokens = {
   "components": {

package/dist/tokens/ts/primitives.tokens.ts

@@ -1,5 +1,5 @@
 // Auto-generated design tokens from Figma
-// Generated on 2026-03-04T21:31:32.474Z
+// Generated on 2026-03-04T21:56:02.562Z
 
 export const tokens = {
   "colors": {

package/dist/tokens/ts/semantic.tokens.ts

@@ -1,5 +1,5 @@
 // Auto-generated design tokens from Figma
-// Generated on 2026-03-04T21:31:32.476Z
+// Generated on 2026-03-04T21:56:02.563Z
 
 export const tokens = {
   "typography": {

package/docs/agentic/assistant-behavior-rules.md

@@ -0,0 +1,16 @@
+# Assistant rules (UI Foundations)
+
+1. Always follow foundation rules in `/docs/foundations` as the source of truth.
+2. Keep the 4-layer architecture: Core → Color Modes → Semantics → Components.
+3. Components may only reference Semantics/Core tokens; no raw values in components.
+4. Typography tokens never include color; text color lives in `Color.Text.*`.
+5. Responsive thresholds:
+   - Viewport breakpoints in `Core.Breakpoint.*`
+   - Container query thresholds in `Core.Container.*`
+6. Use variant-first naming: `Component.variant.part.property.state`.
+7. Before creating a new component, run a boundary check:
+   - Prefer composition inside an existing component family when behavior is mainly layout/wrapping/grouping.
+   - Create a standalone component only if it introduces distinct semantics, API surface, or lifecycle.
+   - This decision is independent from token work: new tokens alone are not sufficient reason for a standalone component.
+   - Apply the Snowflake check: local one-off solutions stay local; shared utility can enter the system.
+   - Source of truth: `docs/foundations/foundation-009-component-boundaries-and-utility.md`.

package/docs/agentic/skills/design-ops-specialist/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: design-ops-specialist
+description: "Design Ops Specialist guidance for token-first component proposals in this repo and package consumers. Use when a request asks for token naming (variants/parts/states), CSS pattern structure under src/ui/patterns, optional React wrapper API, and docs/playground integration while keeping scope minimal and non-breaking."
+---
+
+# Design Ops Specialist
+
+## Intent
+
+Use this skill for proposal-first work before implementation.
+
+## Workflow
+
+1. Confirm scope and constraints:
+   - component name
+   - parts/variants/states
+   - platform or framework constraints
+2. Align with source rules:
+   - `docs/foundations/`
+   - `docs/agentic/assistant-behavior-rules.md`
+   - `docs/agentic/team-ai-playbook.md`
+3. Produce a concise proposal (no code changes unless explicitly requested).
+4. Keep proposals minimal, incremental, and non-breaking by default.
+
+## Output Format
+
+Provide these sections:
+
+1. Token naming proposal
+   - prefix, variants, parts, states
+   - alignment to foundations naming rules
+2. CSS pattern structure
+   - target files under `src/ui/patterns`
+   - expected class names and token hookups
+3. Optional React wrapper API
+   - only when requested or needed
+   - props mapped to token variants/states
+4. Docs + playground integration
+   - required docs pages/sections
+   - playground additions or updates
+
+## Guardrails
+
+- Prefer extending existing patterns over introducing new frameworks.
+- If requirements are underspecified, ask targeted clarifying questions.
+- Preserve compatibility with token-first and Figma-aligned architecture.

package/docs/agentic/team-ai-playbook.md

@@ -0,0 +1,216 @@
+# AI Playbook
+
+This playbook defines how to use AI as an engineering copilot in this repository.
+
+## Goal
+
+Use AI to speed up component incubation and implementation while keeping output:
+
+- token-first
+- reviewable in Git
+- consistent with existing architecture
+
+## Principles
+
+1. Keep changes small and incremental.
+2. Prefer existing patterns over introducing new abstractions.
+3. Keep Figma and code aligned through explicit token roundtrips.
+4. Always validate with local checks before pushing.
+
+## Component Boundary Check (Mandatory)
+
+Run this decision gate before implementing a "new component":
+
+1. Start with composition-first:
+   - If the new idea is primarily grouping, layout, or orchestration of existing components, implement it as composition within the existing component family and document it there.
+2. Promote to standalone only when needed:
+   - The candidate introduces distinct semantics (own role/responsibility), a stable API surface, or independent lifecycle/behavior that is not just a wrapper.
+3. Apply a utility test ("Snowflake check"):
+   - One-off/local case -> keep it local or document as composition.
+   - Reusable across contexts/products -> valid candidate for system-level component.
+4. Keep token work independent:
+   - New tokens may be needed in both paths.
+   - Token creation does not automatically justify a new standalone component.
+5. Source of truth:
+   - `docs/foundations/foundation-009-component-boundaries-and-utility.md`
+
+## Standard Workflow: New Component
+
+1. Run the Component Boundary Check and decide:
+   - standalone component, or
+   - composition inside existing component docs/API.
+2. Ask AI for a first proposal:
+   - structure: HTML/CSS/React
+   - token names and states
+   - docs + playground example
+3. Review and adjust naming before implementation.
+4. Add/import proposed tokens in Figma.
+5. Export tokens from Figma to `figma/exports/`.
+6. Let AI integrate implementation:
+   - `src/ui/patterns/<component>.css`
+   - `src/react/<component>.js` and `src/react/index.js` (if needed)
+   - `site/components/<component>.md`
+   - `site/components/<component>-playground.md`
+   - `figma/connections/web-<component>.figma.ts` (if needed)
+7. Run validation:
+   - `npm run ci:check`
+8. Iterate naming/states/a11y until stable.
+
+## Proposal Mode: Design Ops Specialist
+
+Use this mode when the request is explicitly a proposal (no implementation yet).
+
+1. Confirm scope and constraints first:
+   - component name
+   - variants/sizes/states/parts
+   - platform constraints
+2. Review source rules before proposing:
+   - `docs/foundations/`
+   - `docs/agentic/assistant-behavior-rules.md`
+   - this playbook
+3. Deliver a concise proposal with these sections:
+   - token naming proposal (variants/parts/states)
+   - CSS pattern structure under `src/ui/patterns`
+   - optional React wrapper API (only if requested/needed)
+   - docs + playground integration plan
+4. Keep recommendations minimal and non-breaking by default.
+
+## Standard Workflow: Token Roundtrip
+
+1. Create or update tokens in Figma.
+2. Export into `figma/exports/*.tokens.json`.
+3. Run:
+   - `npm run build:all`
+   - `npm run tokens:validate`
+4. Check output consistency:
+   - `dist/tokens/css/*.tokens.css`
+   - `dist/tokens/json/*.json`
+   - `dist/tokens/tokens.yaml`
+5. If warnings appear (missing/invalid WEB syntax, alias issues), fix in Figma first.
+
+## Standard Workflow: Figma Drift Reconciliation
+
+Use this when the component was scaffolded in code first and component variables/variants are created or changed in Figma afterwards.
+
+1. Define the contract first:
+   - component API (props/states/semantics)
+   - token names and expected usage
+2. Update Figma variables/variants and export tokens:
+   - `figma/exports/*.tokens.json`
+3. Rebuild token artifacts:
+   - `npm run build:all`
+   - `npm run tokens:validate`
+4. Reconcile Code Connect mappings:
+   - update `figma/connections/web-<component>.figma.ts`
+   - align node-id targets and property names with actual Figma top-level component/component set
+   - run `figma connect parse`
+   - run `figma connect publish --dry-run`
+5. Reconcile implementation only where needed:
+   - adjust CSS/React/docs/playground to match agreed contract
+   - avoid broad rewrites; keep changes minimal
+6. Validate and stabilize:
+   - `npm run lint`
+   - `npm run test:unit`
+   - `npm run ci:check`
+7. Commit with explicit scope, for example:
+   - `chore(figma): reconcile <component> code-connect mapping`
+   - `feat(<component>): align states and tokens with figma`
+
+## Standard Workflow: Refactor and Quality
+
+1. Ask AI to identify one small refactor target.
+2. Implement only one focused change set.
+3. Add or update tests when behavior is touched.
+4. Run:
+   - `npm run lint`
+   - `npm run test:unit`
+   - `npm run ci:check`
+5. Commit with clear scope in message.
+
+## Prompt Templates
+
+### 1) New component incubation
+
+```text
+You are my Design OPS Manager. Propose a token-first setup for a new <component>.
+Include:
+- token naming proposal (variants/parts/states)
+- CSS pattern structure under src/ui/patterns
+- optional React wrapper API
+- docs + playground integration
+Keep changes minimal and aligned with existing repository conventions.
+```
+
+### 2) Token integration after Figma export
+
+```text
+I updated figma/exports. Please run the token/build pipeline, review warnings,
+and apply minimal fixes so docs and bundles are green.
+```
+
+### 3) Safe refactor
+
+```text
+Refactor <target file/module> for maintainability in small steps only.
+No behavior changes. Add tests if needed. Keep ci:check green.
+```
+
+### 4) Prompt to UI component (scaffold + implement)
+
+```text
+Scaffold and implement a new UI component named <component-name> in this repository.
+
+Follow these sources strictly:
+- docs/agentic/team-ai-playbook.md
+- docs/agentic/assistant-behavior-rules.md
+- docs/foundations/*
+
+Execution requirements:
+1) Run the Component Boundary Check first and state the decision (composition vs standalone).
+2) Keep scope small, incremental, and reviewable in Git.
+3) Implement token-first and reuse existing patterns:
+   - src/ui/patterns/<component>.css
+   - src/react/<component>.js and src/react/index.js (if needed)
+   - site/components/<component>.md
+   - site/components/<component>-playground.md
+   - figma/connections/web-<component>.figma.ts (only if a publishable top-level Figma component/component-set exists)
+4) Validate before handoff:
+   - npm run lint
+   - npm run test:unit
+   - npm run ci:check
+
+Mandatory progress tracker for this task type:
+- Start with: Tasks completion: 0/4
+- Update after each phase: 1/4, 2/4, 3/4, 4/4
+
+Handoff format:
+- boundary decision result
+- files changed
+- validation results
+- open follow-ups (if any)
+```
+
+## Definition of Done (AI Task)
+
+- Scope is clear and minimal.
+- Affected files are easy to review.
+- No broken exports or docs.
+- `npm run ci:check` passes.
+- README/docs updated when behavior or workflow changes.
+
+## Worked example: Button Group
+
+This repository now includes a concrete walkthrough based on a `Button Group`:
+
+1. AI proposal:
+   - layout model (`orientation`, `attached`, `justify`)
+   - token proposal (`--button-group-gap`, `--button-group-border-radius`)
+2. Implementation in code:
+   - integrated button family CSS: `src/ui/patterns/button.css`
+   - React wrapper API in `src/react/button.js` (`ButtonGroup`)
+3. Documentation:
+   - integrated in `site/components/button.md` under grouped usage
+4. Validation:
+   - `npm run ci:check`
+
+Use this pattern as the reference baseline for future AI-assisted component incubation where wrappers extend an existing component family.

package/docs/foundations/foundation-010-implementation-and-pipeline-workflow.md

@@ -0,0 +1,82 @@
+# Foundation-010: Implementation and Pipeline Workflow
+
+## Purpose
+
+Define the stable implementation workflow for adding or updating UI foundations artifacts, including token generation, component integration, docs updates, and validation.
+
+## Rules
+
+1. Follow this sequence for new components:
+   - Run boundary + utility check first (see Foundation-009).
+   - Add/update Figma token exports in `figma/exports/`.
+   - Regenerate artifacts via `npm run build:all`.
+   - Add or update CSS pattern in `src/ui/patterns/`.
+   - Export pattern in `src/ui/index.css`.
+   - Add React wrapper only when needed.
+   - Add docs + playground pages in `site/components/`.
+
+2. Keep changes token-first:
+   - Components consume semantic/foundation tokens.
+   - Do not introduce component-local hard-coded colors.
+
+3. Treat generated output as build artifacts:
+   - `dist/tokens/` and `dist/` are generated outputs.
+   - Build scripts in `scripts/` are the source for generation behavior.
+
+4. Keep package runtime mode policy consumer-owned:
+   - Token outputs define scopes/selectors.
+   - Consumers decide when/how `data-mode` and `data-brand` are applied.
+
+## Build and Validation
+
+Use these commands as the baseline:
+
+- `npm run lint`
+- `npm run test:unit`
+- `npm run ci:check`
+
+Additional useful commands:
+
+- `npm run tokens:generate`
+- `npm run build:css`
+- `npm run build:all`
+- `npm run docs:site`
+
+## Token Pipeline Notes
+
+`scripts/extract-tokens.js` orchestrates generation.
+
+Key helpers:
+
+- `scripts/extract-tokens.utils.js`
+- `scripts/extract-tokens.lookup.js`
+- `scripts/extract-tokens.value.js`
+- `scripts/extract-tokens.scope.js`
+
+Scope behavior from export filenames:
+
+- `Brand X.tokens.json` -> `:root[data-brand="x"]`
+- `Mode Light.tokens.json` -> `:root`
+- `Mode Dark.tokens.json` -> `:root[data-mode="dark"]`
+
+Fallback behavior:
+
+- Missing or invalid `com.figma.codeSyntax.WEB` falls back to auto-derived CSS variable names and is reported.
+- Missing alias targets and alias cycles fall back to literal values and are reported.
+
+## AI-Assisted Workflow
+
+When using assistants for component incubation:
+
+1. Define boundary (composition vs standalone).
+2. Propose token naming + component structure.
+3. Align/update Figma tokens.
+4. Regenerate and integrate in code.
+5. Update docs/playground.
+6. Run validation commands before handoff.
+
+## Implications
+
+- The repository remains predictable for humans and assistants.
+- Detailed operational guidance stays in foundations docs, not top-level onboarding.
+- The README can remain minimal while implementation rigor stays explicit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ui-foundations",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Token-first UI foundations with CSS, tokens, and React exports.",
   "license": "MIT",
   "repository": {
@@ -15,7 +15,10 @@
   "files": [
     "dist/**",
     "README.md",
-    "docs/foundations/**"
+    "docs/foundations/**",
+    "docs/agentic/assistant-behavior-rules.md",
+    "docs/agentic/team-ai-playbook.md",
+    "docs/agentic/skills/**"
   ],
   "exports": {
     "./core.css": "./dist/core/index.css",