ui-foundations 0.1.2 → 0.3.0

package/docs/agentic/skills/README.md

@@ -0,0 +1,51 @@
+# Agentic Skills
+
+This directory contains repo-specific skills for AI-assisted design-system work.
+
+## Available skills
+
+### design-ops-specialist
+
+Use for tactical, proposal-first work:
+
+- minimal component drafts
+- token naming proposals
+- CSS pattern structure suggestions
+- optional React wrapper API sketches
+- docs/playground integration plans
+
+Best when the question is close to implementation and should stay incremental and non-breaking.
+
+Path:
+- `docs/agentic/skills/design-ops-specialist/SKILL.md`
+
+### design-system-architect
+
+Use for strategic, system-level work:
+
+- foundation reviews
+- token governance decisions
+- component boundary decisions
+- Figma/code reconciliation
+- architecture-level handoff and system recommendations
+
+Best when the question is about whether something belongs in the system at all, how foundations should evolve, or how to restore consistency across Figma, tokens, code, and docs.
+
+Path:
+- `docs/agentic/skills/design-system-architect/SKILL.md`
+
+## Quick selection guide
+
+Use `design-ops-specialist` when the question sounds like:
+
+- "Propose a draft for this component"
+- "How should the token names look?"
+- "What files would change?"
+- "How would the CSS and docs be structured?"
+
+Use `design-system-architect` when the question sounds like:
+
+- "Should this be a standalone component or composition?"
+- "Do we need new semantic tokens?"
+- "Are the foundations still coherent?"
+- "How do we reconcile Figma and code drift?"

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

@@ -1,46 +1,60 @@
 ---
 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."
+description: "Tactical proposal-first guidance for token-first component work in this repo and package consumers. Use when a request asks for a minimal component draft, token naming proposal, CSS pattern structure under src/ui/patterns, optional React wrapper API, docs/playground integration, or a concrete implementation plan that should stay incremental and non-breaking. Prefer design-system-architect instead when the request is about foundations, token governance, component-boundary decisions, Figma/code drift, or system-wide architecture."
 ---
 
 # Design Ops Specialist
 
 ## Intent
 
-Use this skill for proposal-first work before implementation.
+Use this skill for tactical, proposal-first work before or just ahead of implementation.
+
+This skill is narrower than `design-system-architect`.
+
+- Use `design-ops-specialist` for concrete component drafts and repo-shaped implementation proposals.
+- Use `design-system-architect` for system-wide reviews, governance, and architecture decisions.
 
 ## Workflow
 
 1. Confirm scope and constraints:
    - component name
-   - parts/variants/states
+   - parts / variants / states
    - platform or framework constraints
+   - whether the ask is proposal-only or implementation-adjacent
 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.
+3. If the request implies a new system component, call out that boundary validation is required and defer the strategic decision to `design-system-architect` when needed.
+4. Produce a concise proposal by default, with no code changes unless explicitly requested.
+5. Keep proposals minimal, incremental, and non-breaking.
 
-## Output Format
+## Output format
 
 Provide these sections:
 
-1. Token naming proposal
+1. Boundary assumption
+   - whether this is assumed to be composition or a valid standalone candidate
+   - if unclear, say so briefly
+2. Token naming proposal
    - prefix, variants, parts, states
    - alignment to foundations naming rules
-2. CSS pattern structure
-   - target files under `src/ui/patterns`
+3. CSS pattern structure
+   - target files under `src/ui/patterns` or existing family integration
    - expected class names and token hookups
-3. Optional React wrapper API
-   - only when requested or needed
+4. Optional React wrapper API
+   - only when requested or clearly needed
    - props mapped to token variants/states
-4. Docs + playground integration
+5. Docs + playground integration
    - required docs pages/sections
    - playground additions or updates
+6. Implementation surface
+   - exact repo paths likely to change
 
 ## 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.
+- Keep recommendations compatible with token-first and Figma-aligned architecture.
+- Do not broaden into foundations governance unless explicitly asked.
+- If requirements are underspecified, ask targeted clarifying questions or state minimal assumptions.
+- If the task is really about whether something belongs in the system at all, hand off conceptually to `design-system-architect`.

package/docs/agentic/skills/design-system-architect/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: design-system-architect
+description: "Strategic design-system architecture for this repo. Use when reviewing or evolving foundations, deciding token governance, evaluating component boundaries, reconciling Figma/code drift, auditing semantic coverage, or making architecture-level decisions that span beyond a single component proposal. Prefer this skill over design-ops-specialist when the request is system-wide, governance-heavy, or about whether something should enter the system at all."
+---
+
+# Design System Architect
+
+## Intent
+
+Use this skill for system-level decisions, reviews, and governance.
+
+This skill is broader than `design-ops-specialist`.
+
+- Use `design-ops-specialist` for tactical, proposal-first component drafts.
+- Use `design-system-architect` for architecture, boundaries, token governance, and Figma/code alignment decisions.
+
+## Required source alignment
+
+Before responding, align to these repo sources:
+
+- `docs/foundations/`
+- `docs/agentic/assistant-behavior-rules.md`
+- `docs/agentic/team-ai-playbook.md`
+
+At minimum, check these when relevant:
+
+- `docs/foundations/foundation-001-token-layering.md`
+- `docs/foundations/foundation-002-naming-and-grouping.md`
+- `docs/foundations/foundation-003-color-semantics-and-status.md`
+- `docs/foundations/foundation-009-component-boundaries-and-utility.md`
+- `docs/foundations/foundation-010-implementation-and-pipeline-workflow.md`
+- `docs/foundations/foundation-011-branching-and-release-governance.md`
+
+## Task types
+
+### 1. Foundation review
+
+Use when reviewing the health of the system.
+
+Check for:
+
+- layering integrity
+- semantic gaps
+- naming drift
+- duplicate concepts
+- hard-coded or leaky component decisions
+- weak state coverage
+- Figma/code mismatch
+
+### 2. Token governance
+
+Use when deciding whether to create, alias, rename, or reject token changes.
+
+Report:
+
+- correct layer
+- rationale
+- consumer scope
+- theme/mode impact
+- migration implications
+
+### 3. Boundary decision
+
+Use before proposing or implementing a new component.
+
+Decide:
+
+- composition inside an existing family, or
+- standalone system component
+
+Apply the Snowflake check from `foundation-009`.
+
+### 4. Figma/code reconciliation
+
+Use when system contracts drift between Figma and implementation.
+
+Review:
+
+- token exports in `figma/exports/`
+- Code Connect mappings in `figma/connections/`
+- implementation in `src/ui/` and `src/react/`
+- docs/playground representation in `site/components/`
+
+### 5. System handoff
+
+Use when another designer or engineer needs a structured architectural recommendation.
+
+## Output format
+
+Provide these sections when relevant:
+
+1. Task type
+2. Current system reading
+3. Decision
+4. Rationale
+5. Repo surfaces affected
+6. Risks / mismatches
+7. Recommended next step
+
+## Guardrails
+
+- Do not invent raw values inside components.
+- Keep the 4-layer architecture intact.
+- Treat token work and component boundary decisions as separate questions.
+- Prefer small, reviewable changes and feature-branch delivery.
+- Say explicitly when something should remain local instead of entering the system.

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

@@ -56,6 +56,16 @@ Run this decision gate before implementing a "new component":
    - `npm run ci:check`
 8. Iterate naming/states/a11y until stable.
 
+## Skill selection
+
+Use the repo skills intentionally:
+
+- `design-ops-specialist` for tactical, proposal-first component work
+- `design-system-architect` for strategic, system-level reviews and decisions
+
+See also:
+- `docs/agentic/skills/README.md`
+
 ## Proposal Mode: Design Ops Specialist
 
 Use this mode when the request is explicitly a proposal (no implementation yet).

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

@@ -0,0 +1,42 @@
+# Foundation-011: Branching and Release Governance
+
+## Purpose
+
+Keep delivery safe and predictable by enforcing feature-branch development and protected `main` releases.
+
+## Rules
+
+1. Development happens on feature branches only:
+   - naming: `feat/*`, `fix/*`, `chore/*`, `docs/*`
+   - no direct commits to `main`
+
+2. Merge to `main` only via pull request:
+   - at least one review required
+   - required status checks must pass (`lint`, `test:unit`, `ci:check`)
+   - no force pushes to `main`
+   - no branch deletion protection bypass
+
+3. Releases are cut from clean `main` only:
+   - run `npm run release:patch|minor|major`
+   - push commit + tag with `npm run release:push`
+   - publish with `npm run release:publish` (or `npm publish --otp=<code>`)
+
+## Recommended GitHub Branch Protection (`main`)
+
+- Require a pull request before merging
+- Require approvals: 1+
+- Dismiss stale approvals on new commits
+- Require status checks:
+  - `lint`
+  - `test:unit`
+  - `ci:check`
+- Require branches to be up to date before merging
+- Restrict who can push (optional, recommended for shared repos)
+- Disallow force pushes
+- Disallow deletions
+
+## Implications
+
+- Main stays releasable.
+- Releases become repeatable and auditable.
+- Risk of accidental or unreviewed production changes is reduced.

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

@@ -0,0 +1,42 @@
+# Foundation-012: Minimal Markup and Composition
+
+## Purpose
+
+Keep component markup as flat and simple as possible. Complexity in HTML structure should only exist when it solves a real problem.
+
+## Rules
+
+1. Start with the flattest possible markup.
+   - A link with an icon is `<a class="link"><span class="icon">...</span> Text</a>`, not three nested wrappers.
+   - Add structure only when layout or behavior requires it.
+
+2. Use CSS on the component root for layout.
+   - `inline-flex`, `gap`, `align-items` on the component class itself.
+   - Avoid wrapper elements whose only purpose is layout.
+
+3. Composition patterns (like `label-content`) are opt-in, not default.
+   - Use them only when the component genuinely needs slot management, reordering, or icon-only modes.
+   - A simple text + icon combination does not need a composition wrapper.
+
+4. Measure complexity by counting elements.
+   - If a simple variant needs more than 2 elements (root + content), question the structure.
+   - Complex variants (e.g. button with icon-only mode, loading state) may justify more elements.
+
+5. Avoid premature abstraction.
+   - Do not add wrapper elements "in case we need them later".
+   - Add structure when a real variant or behavior demands it.
+
+## Test
+
+Before finalizing component markup, ask:
+
+- Can I remove any element without losing functionality?
+- Is every wrapper solving a real layout or behavior problem?
+- Would a developer using this component find the markup obvious?
+
+## Implications
+
+- Components stay readable and debuggable in browser DevTools.
+- CSS stays simpler with fewer selectors.
+- Consumers write less HTML.
+- Complex components can still use composition patterns when justified.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ui-foundations",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Token-first UI foundations with CSS, tokens, and React exports.",
   "license": "MIT",
   "repository": {
@@ -29,15 +29,15 @@
     "./react/input": "./dist/react/input.js",
     "./react/label": "./dist/react/label.js",
     "./assets/*": "./dist/assets/*",
-    "./tokens/core.css": "./dist/tokens/css/primitives.tokens.css",
-    "./tokens/primitives.css": "./dist/tokens/css/primitives.tokens.css",
-    "./tokens/brand-a.css": "./dist/tokens/css/brand-a.tokens.css",
-    "./tokens/brand-b.css": "./dist/tokens/css/brand-b.tokens.css",
-    "./tokens/color.css": "./dist/tokens/css/color.light.tokens.css",
-    "./tokens/color-light.css": "./dist/tokens/css/color.light.tokens.css",
-    "./tokens/color-dark.css": "./dist/tokens/css/color.dark.tokens.css",
-    "./tokens/semantic.css": "./dist/tokens/css/semantic.tokens.css",
-    "./tokens/components.css": "./dist/tokens/css/component.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"
   },
   "scripts": {
     "icons:generate-list": "node scripts/generate-icon-list.mjs",
@@ -46,6 +46,7 @@
     "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",
     "tokens:generate": "node scripts/extract-tokens.js",
     "tokens:validate": "node scripts/validate-tokens.mjs",
     "tokens:build": "npm run tokens:generate",
@@ -54,9 +55,14 @@
     "build": "npm run build:all",
     "pack:check": "npm pack --dry-run",
     "release:check": "npm run ci:check && npm run pack:check",
+    "release:patch": "npm run release:check && npm version patch",
+    "release:minor": "npm run release:check && npm version minor",
+    "release:major": "npm run release:check && npm version major",
+    "release:push": "git push origin main --follow-tags",
+    "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 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",
     "docs:dev": "npm run build:all && eleventy --serve"
   },
   "devDependencies": {
@@ -66,5 +72,8 @@
     "js-yaml": "^4.1.0",
     "jsonc-parser": "^3.3.1",
     "prismjs": "^1.30.0"
+  },
+  "dependencies": {
+    "ui-foundations": "^0.1.2"
   }
 }

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

@@ -1,192 +0,0 @@
-{
-  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
-  "Brand": {
-    "Color": {
-      "Primary": {
-        "$type": "color",
-        "$value": {
-          "colorSpace": "srgb",
-          "components": [
-            0.5921568870544434,
-            0.27843138575553894,
-            1
-          ],
-          "alpha": 1,
-          "hex": "#9747FF"
-        }
-      },
-      "Primary Dark": {
-        "$type": "color",
-        "$value": {
-          "colorSpace": "srgb",
-          "components": [
-            0.3333333432674408,
-            0.10196078568696976,
-            0.545098066329956
-          ],
-          "alpha": 1,
-          "hex": "#551A8B"
-        }
-      },
-      "Accent": {
-        "$type": "color",
-        "$value": {
-          "colorSpace": "srgb",
-          "components": [
-            0.43921568989753723,
-            0.7960784435272217,
-            0.95686274766922
-          ],
-          "alpha": 1,
-          "hex": "#70CBF4"
-        }
-      },
-      "Subtle": {
-        "$type": "color",
-        "$value": {
-          "colorSpace": "srgb",
-          "components": [
-            0.501960813999176,
-            0.501960813999176,
-            0.501960813999176
-          ],
-          "alpha": 1,
-          "hex": "#808080"
-        }
-      },
-      "Subtle Light": {
-        "$type": "color",
-        "$value": {
-          "colorSpace": "srgb",
-          "components": [
-            0.800000011920929,
-            0.800000011920929,
-            0.800000011920929
-          ],
-          "alpha": 1,
-          "hex": "#CCCCCC"
-        }
-      },
-      "Subtle Dark": {
-        "$type": "color",
-        "$value": {
-          "colorSpace": "srgb",
-          "components": [
-            0.20000000298023224,
-            0.20000000298023224,
-            0.20000000298023224
-          ],
-          "alpha": 1,
-          "hex": "#333333"
-        }
-      },
-      "Accent Dark": {
-        "$type": "color",
-        "$value": {
-          "colorSpace": "srgb",
-          "components": [
-            0.0470588244497776,
-            0.29411765933036804,
-            0.9529411792755127
-          ],
-          "alpha": 1,
-          "hex": "#0C4BF3"
-        }
-      },
-      "Functional": {
-        "Base": {
-          "$type": "color",
-          "$value": {
-            "colorSpace": "srgb",
-            "components": [
-              0.0470588244497776,
-              0.29411765933036804,
-              0.9529411792755127
-            ],
-            "alpha": 1,
-            "hex": "#0C4BF3"
-          }
-        },
-        "Base Dark": {
-          "$type": "color",
-          "$value": {
-            "colorSpace": "srgb",
-            "components": [
-              0.10588235408067703,
-              0.06666667014360428,
-              0.3607843220233917
-            ],
-            "alpha": 1,
-            "hex": "#1B115C"
-          }
-        },
-        "Success": {
-          "$type": "color",
-          "$value": {
-            "colorSpace": "srgb",
-            "components": [
-              0.07450980693101883,
-              0.6823529601097107,
-              0.3607843220233917
-            ],
-            "alpha": 1,
-            "hex": "#13AE5C"
-          }
-        },
-        "Danger": {
-          "$type": "color",
-          "$value": {
-            "colorSpace": "srgb",
-            "components": [
-              1,
-              0,
-              0
-            ],
-            "alpha": 1,
-            "hex": "#FF0000"
-          }
-        }
-      }
-    },
-    "Font": {
-      "Lead": {
-        "$type": "string",
-        "$value": "Rokkitt"
-      },
-      "Base": {
-        "$type": "string",
-        "$value": "Inter"
-      }
-    },
-    "Corner": {
-      "Button": {
-        "$type": "dimension",
-        "$value": {
-          "value": 10000,
-          "unit": "px"
-        }
-      },
-      "Input": {
-        "$type": "dimension",
-        "$value": {
-          "value": 4,
-          "unit": "px"
-        }
-      },
-      "Card": {
-        "$type": "dimension",
-        "$value": {
-          "value": 4,
-          "unit": "px"
-        }
-      },
-      "Modal": {
-        "$type": "dimension",
-        "$value": {
-          "value": 8,
-          "unit": "px"
-        }
-      }
-    }
-  }
-}