ui-foundations 0.3.1 → 0.4.1

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

@@ -1,3 +1,9 @@
+---
+title: Assistant rules (UI Foundations)
+status: active
+type: agent-guide
+---
+
 # Assistant rules (UI Foundations)
 
 1. Always follow foundation rules in `/docs/foundations` as the source of truth.
@@ -14,3 +20,45 @@
    - 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`.
+8. When creating a new component, always complete all integration surfaces:
+   - CSS pattern in `src/ui/patterns/<component>.css`
+   - Import in `src/ui/index.css`
+   - React wrapper in `src/react/<component>.js`
+   - Export in `src/react/index.js`
+   - Nunjucks macro in `site/_includes/macros/ui.njk` (source of truth; `dist/macros/ui.njk` is copied during build)
+   - Playground renderer in `site/assets/playground/renderers.js` — register the render function and add it to the `renderers` map
+   - Playground page in `site/components/<component>-playground.md` with `renderer: <component>` matching the key in the renderers map
+   - Docs page in `site/components/<component>.md`
+   - Code Connect file in `schemas/web-<component>.figma.ts`
+   Missing any of these (especially the playground renderer) will cause broken pages.
+9. Every new component must have its own Component-layer tokens. Never reuse tokens from another component (e.g. do not use `--input-checkbox-*` for a radio).
+   - Check `dist/tokens/css/components-ui.tokens.css` for existing tokens.
+   - If the component has no tokens in Figma yet, propose new ones following the naming pattern `--<component>-<part>-<property>-<state>` and add them to `components-ui.tokens.css`, referencing only Semantic or Core tokens.
+   - This keeps components independently themeable and avoids hidden coupling.
+10. Token alias references must point to tokens that actually exist in the system.
+    - Before adding a `$ref`, verify the target exists in `dist/tokens/css/` (Core, Modes, Semantics).
+    - Run `npm run tokens:generate` and check for "missing alias targets" warnings.
+    - Never invent Semantic/Core token names (e.g. `Color/Fill/Muted`, `Size/Spacing/50`) — use only what the system provides.
+    - If a needed Semantic token does not exist, flag it for creation in Figma first.
+11. CSS class naming must follow the project convention: bare component name (e.g. `.slider`, `.radio`, `.checkbox`).
+    - Never prefix with `.ui-` or other namespaces.
+    - CSS patterns must be wrapped in `@layer components { }`.
+12. React wrappers must follow the existing pattern:
+    - Named `export function` (not `export const`)
+    - No CSS imports inside React files
+    - Use `React.createElement`, not JSX
+    - Class array pattern: `const classes = ["component"]; if (className) classes.push(className);`
+13. Docs-only UI (code-tabs, mode toggles) must use docs-specific CSS, not component tokens.
+    - The `.code-tabs-bar` and `.docs-header` button groups are styled in `site/assets/docs.css` with hardcoded docs colors.
+    - They must not inherit brand theming from `data-brand`.
+
+## Modes
+
+The agent operates in different modes depending on the task:
+
+- **Implementation** → modify system
+- **Audit** → inspect only
+- **Pattern Discovery** → design patterns
+- **Token Proposal** → suggest tokens
+
+Mode-specific rules are defined in: `docs/agentic/modes/`

package/docs/agentic/skills/ux-writing-coach.md

@@ -0,0 +1,116 @@
+# UX Writing Coach
+
+## Purpose
+
+Provide multilingual UX writing review for digital product copy.
+
+This skill improves user-facing text for clarity, consistency, accessibility, usability, and tone-of-voice alignment.
+
+## Scope
+
+Use this skill when reviewing or rewriting:
+- UI labels
+- button text
+- links and CTAs
+- helper text
+- validation and error messages
+- empty states
+- success and feedback messages
+- transactional or task-supporting product copy
+
+Default language is English. Core supported languages are English, German, and French.
+
+## Language behaviour
+
+- Start in English by default.
+- If the user writes in German, respond in German.
+- If the user writes in French, respond in French.
+- If the user requests another language, adapt if possible.
+- Preserve the language of the source text unless translation is explicitly requested.
+
+## Working principles
+
+- Be concise, practical, and supportive.
+- Focus on the most relevant improvements first.
+- Do not over-edit.
+- Do not make text longer, more formal, or more complex unless it clearly improves usability.
+- If the text is already strong, say so and suggest only meaningful refinements.
+- Encourage the user to decide which suggestions to adopt.
+
+## Review criteria
+
+Check the text for:
+- grammar
+- spelling
+- punctuation
+- clarity
+- consistency
+- inclusivity
+- accessibility
+- formatting
+- tone of voice
+
+## UX writing principles
+
+Prefer copy that is:
+- clear
+- concise
+- consistent
+- empathetic
+- helpful
+- action-oriented
+- error-preventing
+
+## Accessibility rules
+
+- Use plain language.
+- Avoid ambiguity and unnecessary jargon.
+- Make links, buttons, and CTAs specific and understandable out of context.
+- Ensure instructions, feedback, and next steps are easy to understand.
+- Use inclusive language.
+
+## Typographic and formatting conventions
+
+- Distinguish between user-facing copy and technical or system-facing content.
+- Use ISO 8601 for technical, structured, machine-readable, or cross-market content.
+- ISO 8601 date format: YYYY-MM-DD
+- ISO 8601 date-time format: YYYY-MM-DDTHH:mm
+- Use localized date and time formats for user-facing UX copy when readability is more important.
+- Use the 24-hour time format unless context clearly requires otherwise.
+- Use leading zeros where appropriate.
+- Use an en dash (–) for ranges.
+- Never mix date systems inconsistently within the same output.
+- For German copy, use standard German weekday and month abbreviations where needed.
+
+## Tone of voice
+
+Aim for copy that is:
+- clear
+- friendly
+- confident
+- helpful
+- human
+
+Avoid copy that feels robotic, overly formal, or unnecessarily promotional.
+
+## Preferred response structure
+
+1. Brief assessment
+2. Key improvements
+3. Suggested rewrite
+4. Clean final copy
+
+## Operating instructions
+
+When given text to review:
+1. Analyse the text carefully.
+2. Identify the most important issues first.
+3. Explain the issues briefly and clearly.
+4. Suggest an improved version.
+5. Provide a clean final version ready to copy.
+
+## Prompt template
+
+Use this prompt shape when applying the skill:
+
+> Review the following text according to the rules above, accessibility standards, formatting conventions, and the tone of voice of tui.com: "[text to review]"

package/docs/foundations/README.md

@@ -0,0 +1,31 @@
+# Foundations
+
+## Purpose
+
+Foundations docs describe the canonical token, naming, theming, parity, and
+format rules that other layers build on.
+
+## Canonical files
+
+The detailed foundation ADRs are the source of truth:
+
+| File | Topic |
+|---|---|
+| `foundation-001-token-layering.md` | Core -> Color Modes -> Semantics -> Components token layering |
+| `foundation-002-naming-and-grouping.md` | Token naming, grouping, and variant-first structure |
+| `foundation-003-color-semantics-and-status.md` | Semantic color roles, status vs interaction state |
+| `foundation-004-typography-scale-and-line-height.md` | Typography scale, line height, and role composition |
+| `foundation-005-responsive-breakpoints-and-containers.md` | Breakpoints, container thresholds, and responsive separation |
+| `foundation-006-z-index-layering.md` | Z-index tokenization and overlay layering |
+| `foundation-007-typography-selectors-and-specificity.md` | Typography selectors, class API, and specificity rules |
+| `foundation-008-mode-activation-and-consumer-control.md` | Light/dark mode scoping and consumer-owned activation |
+| `foundation-009-component-boundaries-and-utility.md` | Standalone component boundary test and utility check |
+| `foundation-010-implementation-and-pipeline-workflow.md` | Token-first implementation workflow and validation commands |
+| `foundation-011-branching-and-release-governance.md` | Feature-branch, PR, and release governance |
+| `foundation-012-minimal-markup-and-composition.md` | Minimal markup, composition, and wrapper discipline |
+
+## Who should read this
+
+- Designers defining token and naming decisions
+- Engineers implementing or validating token-driven UI
+- Agents doing token, component, or parity work

package/docs/foundations/foundation-001-token-layering.md

@@ -1,3 +1,9 @@
+---
+title: Foundation-001 – Token Layering Principles
+status: active
+type: foundation-decision
+---
+
 # Foundation-001: Token Layering Principles
 
 ## Purpose

package/docs/foundations/foundation-002-naming-and-grouping.md

@@ -1,3 +1,9 @@
+---
+title: Foundation-002 – Naming and Grouping Conventions
+status: active
+type: foundation-decision
+---
+
 # Foundation-002: Naming and Grouping Conventions
 
 ## Purpose

package/docs/foundations/foundation-003-color-semantics-and-status.md

@@ -1,3 +1,9 @@
+---
+title: Foundation-003 – Color Semantics, Status vs State
+status: active
+type: foundation-decision
+---
+
 # Foundation-003: Color Semantics, Status vs State
 
 ## Purpose

package/docs/foundations/foundation-004-typography-scale-and-line-height.md

@@ -1,3 +1,9 @@
+---
+title: Foundation-004 – Typography Scale and Line Height
+status: active
+type: foundation-decision
+---
+
 # Foundation-004: Typography Scale and Line Height
 
 ## Purpose

package/docs/foundations/foundation-005-responsive-breakpoints-and-containers.md

@@ -1,3 +1,9 @@
+---
+title: Foundation-005 – Responsive Strategy (Breakpoints and Containers)
+status: active
+type: foundation-decision
+---
+
 # Foundation-005: Responsive Strategy (Breakpoints and Containers)
 
 ## Purpose

package/docs/foundations/foundation-006-z-index-layering.md

@@ -1,3 +1,9 @@
+---
+title: Foundation-006 – Z-Index and Layering Strategy
+status: active
+type: foundation-decision
+---
+
 # Foundation-006: Z-Index and Layering Strategy
 
 ## Purpose

package/docs/foundations/foundation-007-typography-selectors-and-specificity.md

@@ -1,3 +1,9 @@
+---
+title: Foundation-007 – Typography Selectors and Specificity
+status: active
+type: foundation-decision
+---
+
 # Foundation-007: Typography Selectors and Specificity
 
 ## Purpose

package/docs/foundations/foundation-008-mode-activation-and-consumer-control.md

@@ -1,3 +1,9 @@
+---
+title: Foundation-008 – Mode Activation and Consumer Control
+status: active
+type: foundation-decision
+---
+
 # Foundation-008: Mode Activation and Consumer Control
 
 ## Purpose

package/docs/foundations/foundation-009-component-boundaries-and-utility.md

@@ -1,3 +1,9 @@
+---
+title: Foundation-009 – Component Boundaries and Utility Test
+status: active
+type: foundation-decision
+---
+
 # Foundation-009: Component Boundaries and Utility Test
 
 ## Purpose

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

@@ -1,3 +1,9 @@
+---
+title: Foundation-010 – Implementation and Pipeline Workflow
+status: active
+type: foundation-decision
+---
+
 # Foundation-010: Implementation and Pipeline Workflow
 
 ## Purpose

package/docs/foundations/foundation-011-branching-and-release-governance.md

@@ -1,3 +1,9 @@
+---
+title: Foundation-011 – Branching and Release Governance
+status: active
+type: foundation-decision
+---
+
 # Foundation-011: Branching and Release Governance
 
 ## Purpose

package/docs/foundations/foundation-012-minimal-markup-and-composition.md

@@ -1,3 +1,9 @@
+---
+title: Foundation-012 – Minimal Markup and Composition
+status: active
+type: foundation-decision
+---
+
 # Foundation-012: Minimal Markup and Composition
 
 ## Purpose

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ui-foundations",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Token-first UI foundations with CSS, tokens, and React exports.",
   "license": "MIT",
   "repository": {
@@ -29,26 +29,30 @@
     "./react/input": "./dist/react/input.js",
     "./react/label": "./dist/react/label.js",
     "./assets/*": "./dist/assets/*",
-    "./tokens/core.css": "./dist/tokens/css/core-(primitives).tokens.css",
-    "./tokens/primitives.css": "./dist/tokens/css/core-(primitives).tokens.css",
-    "./tokens/brand-a.css": "./dist/tokens/css/themes-(brands).tokens.brand-a.css",
-    "./tokens/brand-b.css": "./dist/tokens/css/themes-(brands).tokens.brand-b.css",
-    "./tokens/color.css": "./dist/tokens/css/appearance-(modes).tokens.mode-light.css",
-    "./tokens/color-light.css": "./dist/tokens/css/appearance-(modes).tokens.mode-light.css",
-    "./tokens/color-dark.css": "./dist/tokens/css/appearance-(modes).tokens.mode-dark.css",
-    "./tokens/semantic.css": "./dist/tokens/css/semantics-(roles).tokens.css",
-    "./tokens/components.css": "./dist/tokens/css/components-(ui).tokens.css"
+    "./tokens/core.css": "./dist/tokens/css/core-primitives.tokens.css",
+    "./tokens/primitives.css": "./dist/tokens/css/core-primitives.tokens.css",
+    "./tokens/brand-a.css": "./dist/tokens/css/themes-brands.tokens.brand-a.css",
+    "./tokens/brand-b.css": "./dist/tokens/css/themes-brands.tokens.brand-b.css",
+    "./tokens/color.css": "./dist/tokens/css/appearance-modes.tokens.mode-light.css",
+    "./tokens/color-light.css": "./dist/tokens/css/appearance-modes.tokens.mode-light.css",
+    "./tokens/color-dark.css": "./dist/tokens/css/appearance-modes.tokens.mode-dark.css",
+    "./tokens/semantic.css": "./dist/tokens/css/semantics-roles.tokens.css",
+    "./tokens/components.css": "./dist/tokens/css/components-ui.tokens.css",
+    "./macros/ui.njk": "./dist/macros/ui.njk"
   },
   "scripts": {
     "icons:generate-list": "node scripts/generate-icon-list.mjs",
+    "plugin:meta": "node scripts/generate-plugin-meta.mjs",
     "lint:js": "node scripts/lint-js.mjs",
     "lint": "npm run lint:js",
     "test:unit": "node --test tests/*.test.mjs",
     "test": "npm run test:unit",
     "smoke:check": "node scripts/smoke-check.mjs",
     "assets:check": "node scripts/check-asset-refs.mjs",
+    "rules:validate": "node scripts/validate-rule-pipeline.mjs",
     "tokens:generate": "node scripts/extract-tokens.js",
     "tokens:validate": "node scripts/validate-tokens.mjs",
+    "dtcg:validate": "node scripts/validate-dtcg.mjs",
     "tokens:build": "npm run tokens:generate",
     "build:css": "node scripts/build-css.mjs",
     "build:all": "npm run icons:generate-list && npm run tokens:generate && npm run build:css",
@@ -62,7 +66,7 @@
     "release:publish": "npm publish",
     "docs:build": "eleventy",
     "docs:site": "npm run build:all && npm run docs:build",
-    "ci:check": "npm run lint && npm run test:unit && npm run build:all && npm run smoke:check && npm run tokens:validate && npm run assets:check && npm run docs:build",
+    "ci:check": "npm run lint && npm run test:unit && npm run build:all && npm run smoke:check && npm run tokens:validate && npm run dtcg:validate && npm run assets:check && npm run rules:validate && npm run docs:build",
     "docs:dev": "npm run build:all && eleventy --serve"
   },
   "devDependencies": {
@@ -73,7 +77,5 @@
     "jsonc-parser": "^3.3.1",
     "prismjs": "^1.30.0"
   },
-  "dependencies": {
-    "ui-foundations": "^0.1.2"
-  }
+  "dependencies": {}
 }

package/dist/tokens/css/themes-(brands).tokens.brand-a.css

@@ -1,22 +0,0 @@
-/* Auto-generated design tokens from Figma */
-/* Generated on 2026-03-31T20:27:09.734Z */
-
-:root[data-brand="a"] {
-  --brand-color-functional-success: var(--color-brand-a-green);
-  --brand-color-functional-danger: var(--color-brand-a-red);
-  --brand-color-functional-base: var(--color-brand-a-blue-700);
-  --brand-color-functional-base-dark: var(--color-brand-a-blue-800);
-  --brand-color-primary: var(--color-brand-a-purple-600);
-  --brand-color-accent: var(--color-brand-a-blue-500);
-  --brand-color-primary-dark: var(--color-brand-a-purple-800);
-  --brand-color-accent-dark: var(--color-brand-a-blue-700);
-  --brand-color-subtle: var(--color-neutral-500);
-  --brand-color-subtle-dark: var(--color-neutral-800);
-  --brand-color-subtle-light: var(--color-neutral-200);
-  --brand-font-base: var(--font-family-sans);
-  --brand-font-lead: var(--font-family-serif);
-  --brand-corner-button: var(--size-radius-700);
-  --brand-corner-card: var(--size-radius-200);
-  --brand-corner-modal: var(--size-radius-400);
-  --brand-corner-input: var(--size-radius-200);
-}

package/dist/tokens/json/appearance-(modes).tokens.mode-dark.json

@@ -1,182 +0,0 @@
-{
-  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
-  "Color": {
-    "Text": {
-      "Default": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/800"
-        }
-      },
-      "Inverse": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/000"
-        }
-      },
-      "Disabled": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/600"
-        }
-      },
-      "Brand": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Brand/Color/Primary"
-        }
-      },
-      "Subtle": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Brand/Color/Subtle"
-        }
-      },
-      "Strong": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/1000"
-        }
-      },
-      "Danger": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Brand/Color/Functional/Danger"
-        }
-      },
-      "Success": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Brand/Color/Functional/Success"
-        }
-      }
-    },
-    "Fill": {
-      "Surface": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/000"
-        }
-      },
-      "Disabled": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/300"
-        }
-      },
-      "Hover": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/Alpha/500"
-        }
-      },
-      "Brand": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Brand/Color/Primary"
-        }
-      },
-      "Subtle": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Brand/Color/Subtle Light"
-        }
-      },
-      "Active": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Brand/Color/Accent"
-        }
-      },
-      "Danger": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Brand/Color/Functional/Danger"
-        }
-      },
-      "Success": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Brand/Color/Functional/Success"
-        }
-      }
-    },
-    "Border": {
-      "Default": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/800"
-        }
-      },
-      "Subtle": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Brand/Color/Subtle"
-        }
-      },
-      "Strong": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/1000"
-        }
-      },
-      "Brand": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Brand/Color/Primary"
-        }
-      },
-      "Disabled": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/500"
-        }
-      },
-      "Danger": {
-        "$type": "color",
-        "$value": {
-          "colorSpace": "srgb",
-          "components": [
-            1,
-            0,
-            0
-          ],
-          "alpha": 1,
-          "hex": "#FF0000"
-        }
-      }
-    },
-    "Overlay": {
-      "Backdrop": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/Alpha/400"
-        }
-      },
-      "Hover": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/Alpha/200"
-        }
-      },
-      "Active": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/Alpha/400"
-        }
-      },
-      "Selected": {
-        "$type": "color",
-        "$value": {
-          "$ref": "Color/Neutral/Alpha/600"
-        }
-      }
-    },
-    "Focus": {
-      "$type": "color",
-      "$value": {
-        "$ref": "Brand/Color/Primary"
-      }
-    }
-  }
-}