feat: V4 sync release webkit/theme/icons

.claude/AGENTS.md

@@ -42,7 +42,6 @@ pnpm storybook:dev
 pnpm storybook:build
 pnpm storybook:preview
 pnpm icons:build
-pnpm webkit:build:dts
 ```
 
 ## 4) Where to change what
@@ -96,10 +95,7 @@ Run the minimum relevant validations for the scope of your change.
   - `pnpm webkit:lint`
   - `pnpm webkit:type-check`
   - `pnpm webkit:type-coverage`
-  - `pnpm webkit:build:dts`
   - `pnpm storybook:build`
-- Other webkit typings/API surface change:
-  - `pnpm webkit:build:dts`
 
 If a full validation is too expensive, run targeted checks and document what was/was not validated.
 
@@ -153,7 +149,7 @@ The legacy monolithic skill `skills/component-create.md` has been **removed**. N
 | Focused skills (one per phase) | [`.claude/skills/`](.claude/skills/) — `spec-create`, `spec-validate`, `figma-discover`, `token-map`, `reuse-audit`, `structure-decide`, `component-scaffold`, `storybook-write`, `code-connect-write`, `validate-component`, `echo-report` |
 | Isolated sub-agent prompts | [`.claude/agents/`](.claude/agents/) — one per skill, no chat history, no cross-talk |
 | Immutable rules (injected verbatim) | [`.claude/rules/`](.claude/rules/) — `no-invention`, `migration`, `dependencies` |
-| Centralized design docs (sources of truth) | [`.claude/docs/`](.claude/docs/) — `DESIGN.md` (tokens + animations + forbidden list), `COMPONENT_REQUIREMENTS.md` (component pattern + Storybook discipline), `PRIMEVUE_ABSTRACTION.md` |
+| Centralized design docs (sources of truth) | [`.claude/docs/`](.claude/docs/) — `DESIGN.md` (tokens + animations + forbidden list), `COMPONENT_REQUIREMENTS.md` (component pattern + Storybook discipline) |
 | Run logs (audit trail) | [`.claude/logs/<run-id>.jsonl`](.claude/logs/) |
 
 **How `/component-create` runs:**
@@ -166,7 +162,7 @@ The legacy monolithic skill `skills/component-create.md` has been **removed**. N
 6. **storybook-writer** — minimal stories only (Default + per kind + per size + Disabled).
 7. **code-connect-writer** — skips if `@figma/code-connect` missing.
 8. **echo-reporter** (cross-check) — independent parser; disagreement with the hook marks the run degraded.
-9. **validate-component** — `pnpm webkit:lint && type-check && type-coverage && build:dts && storybook:build`.
+9. **validate-component** — `pnpm webkit:lint && type-check && type-coverage && storybook:build`.
 10. **Finalize** — `status: approved → implemented`, refresh checksum, close log.
 
 **Why this is mandatory:** the previous workflow gave a single 749-line skill creative latitude — it sometimes added props, variants, or imports the user did not request. The new pipeline removes that latitude structurally: sub-agents see only the spec + their narrow rules; two hooks (`enforce-spec-exists`, `validate-spec-compliance`) verify the `.vue` matches the spec 1-to-1.
@@ -195,7 +191,7 @@ The trigger logic now lives in the orchestrator command [`.claude/commands/compo
 - New components use `<script setup lang="ts">` with `defineProps<...>()`, `defineEmits<...>()`, `defineSlots<...>()` and `defineModel<...>()` where applicable. JSDoc on every public prop. Zero `any`. Zero `// @ts-ignore`.
 - Variants are always exposed as `kind`. Sizes as `size` (`'small' | 'medium' | 'large'`). Boolean state props have no `is`/`has` prefix.
 - Typography is **always** applied via the generated class from DESIGN.md (`text-heading-md`, `text-body-sm`, etc.). Never `text-[length:var(--text-*)]`, `leading-*`, `tracking-*`, or `font-family` directly.
-- Colors, spacing, max-width, and shape come from semantic `var(--*)` tokens. No hex, no Tailwind palette names (`bg-gray-*`), no PrimeVue color utilities (`text-color`, `surface-*`).
+- Colors, spacing, max-width, and shape come from semantic `var(--*)` tokens. No hex, no Tailwind palette names (`bg-gray-*`), no external/legacy color utilities (`text-color`, `surface-*`).
 - `defineOptions({ name, inheritAttrs: false })` + `useAttrs()` + `rootClasses` that merges `attrs.class`. Never declare `class` in `defineProps`.
 - `data-testid` hierarchical, BEM-style: root with fallback `'<category>-<name>'`, children with `${testId}__<part>` (two underscores).
 - Composition Pattern only when the consumer needs to swap the order or omit parts (Dialog, Card composto, Tabs, Accordion, DropdownMenu, Sheet/Drawer, Form). When in doubt, stay monolithic. When applying it, ship the complete shadcn-vue anatomy (e.g. Dialog = Root + Trigger + Portal + Overlay + Content + Title + Description + Close).
@@ -216,7 +212,6 @@ Uses Storybook features fully: `argTypes` (with `control`, `description`, `table
 pnpm webkit:lint
 pnpm webkit:type-check
 pnpm webkit:type-coverage
-pnpm webkit:build:dts
 pnpm storybook:build
 ```
 
@@ -226,7 +221,7 @@ pnpm storybook:build
 - Adding hex colors, raw typography classes, or Tailwind palette names "until the theme catches up". Register a theme gap with `TODO: tokenizar` instead.
 - Applying Composition Pattern reflexively. Use the decision rule: "does the consumer need to swap order or omit parts?"
 - Removing `focus-visible`, `aria-*`, `data-testid`, `disabled` HTML, or `<a>`/`<button>` polymorphism to simplify code.
-- Editing `.claude/docs/DESIGN.md`, `COMPONENT_REQUIREMENTS.md`, or `PRIMEVUE_ABSTRACTION.md` without explicit human approval (these are sources of truth).
+- Editing `.claude/docs/DESIGN.md` or `COMPONENT_REQUIREMENTS.md` without explicit human approval (these are sources of truth).
 
 For deeper, package-specific instructions, agents should also read [`packages/webkit/AGENTS.md`](packages/webkit/AGENTS.md) when working inside `packages/webkit/`.
 

.claude/README.md

@@ -0,0 +1,70 @@
+# `.claude/` — governance system: folder map & index
+
+Everything that makes the design system's standards apply by construction and block off-
+standard code. This is the entry-point map; each area links to its own index.
+
+## Folder layout
+
+```
+.claude/
+├── rules/                 # the 23 construction standards (one .md each) — see rules/README.md
+│   └── README.md          #   ↳ index (foundational/construction · general/webkit · enforcer)
+├── hooks/                 # write-time gates — exit 2 blocks (PreToolUse, except where noted)
+│   ├── validate-authoring.mjs        # blocks off-standard component authoring
+│   ├── validate-spec-compliance.mjs  # .vue must match its spec 1:1 (PostToolUse)
+│   ├── validate-tokens.mjs           # tokens only; no hex/palette/raw typography
+│   ├── validate-references.mjs       # no phantom imports / forbidden deps
+│   ├── validate-story-source.mjs     # runnable "Show code"
+│   ├── enforce-spec-exists.mjs       # no .vue without an approved spec
+│   ├── enforce-component-create.mjs  # authoring only via the pipeline
+│   └── _lib/              # shared, single-source engines
+│       ├── standards.mjs         #   the registry: rule ↔ enforcement + scope (general/webkit)
+│       ├── authoring-checks.mjs  #   construction checks (one of FOUR shared engines: authoring, token, spec, story)
+│       ├── prop-vocabulary.mjs   #   canonical prop dictionary
+│       ├── spec.mjs              #   SFC/spec parsing
+│       └── legacy-components.json #   grandfather list
+├── skills/                # executable playbooks (spec-create, component-scaffold, …)
+├── agents/                # isolated sub-agents that run the skills — see agents/_README.md
+├── commands/              # orchestrators (/component-create, /open-pr, …)
+├── docs/                  # internal sources of truth: DESIGN.md, COMPONENT_REQUIREMENTS.md
+└── settings.json          # hook registration + permissions
+
+packages/webkit/           # the parts of the system that live in the package
+├── scripts/check-authoring.mjs      # CI ratchet — runs the four shared engines repo-wide
+├── scripts/authoring-baseline.json  #   frozen debt; a new violation fails the PR
+├── test/standards/invariant.test.mjs# the meta-check: rule ↔ enforcement can't drift
+├── src/eslint-plugin/     # consumer lints (11 rules, all error)
+├── src/mcp/               # MCP server (guides the AI to the right usage)
+├── docs/GUIDELINES.md     # consumer-facing styleguide (build & use)
+└── catalog.json           # generated manifest read by the lints + MCP
+```
+
+## Where each concern lives (index)
+
+| Concern | Path |
+|---|---|
+| The standards (human) | [`rules/`](./rules/) → [`rules/README.md`](./rules/README.md) |
+| Standard ↔ enforcement (machine) | [`hooks/_lib/standards.mjs`](./hooks/_lib/standards.mjs) |
+| The check engine (hook + ratchet) | [`hooks/_lib/authoring-checks.mjs`](./hooks/_lib/authoring-checks.mjs) |
+| Write-time gates | [`hooks/`](./hooks/) |
+| CI ratchet + baseline | `packages/webkit/scripts/check-authoring.mjs` · `authoring-baseline.json` |
+| The invariant (anti-drift) | `packages/webkit/test/standards/invariant.test.mjs` |
+| Consumer lints | `packages/webkit/src/eslint-plugin/rules/*.js` |
+| Creation pipeline | [`skills/`](./skills/) · [`agents/`](./agents/) · [`commands/`](./commands/) |
+| Tokens (source of truth) | [`docs/DESIGN.md`](./docs/DESIGN.md) |
+| Consumer styleguide | `packages/webkit/docs/GUIDELINES.md` |
+
+## The standards flow (single source, no drift)
+
+```
+rules/<id>.md ──registered in──► hooks/_lib/standards.mjs ──scope: general|webkit
+      │                                    │
+      │ mechanizable check                 │ invariant test asserts the pairing
+      ▼                                    ▼
+hooks/_lib/authoring-checks.mjs  ──used by──►  validate-authoring.mjs (write-time)
+                                 └─used by──►  scripts/check-authoring.mjs (CI ratchet)
+```
+
+One rule, one enforcement, two surfaces — the write-time hook and the CI ratchet run the
+**same** engine, and `invariant.test.mjs` fails CI if a rule loses its gate (or vice-versa).
+Nothing is advisory: every standard blocks the merge, automatically or by mandatory review.

.claude/agents/_README.md

@@ -29,35 +29,48 @@ If anything is ambiguous, emit a `BLOCKED: <reason>` line and write no files.
 
 ## Catalog
 
-| Sub-agent | Skill it executes | Reads (rules) | Writes |
-|---|---|---|---|
-| `spec-author.md` | `spec-create` | tokens, naming, dependencies, migration, storybook | `.specs/<name>.md` (draft) |
-| `spec-validator.md` | `spec-validate` | tokens, naming | spec frontmatter only (status, checksum, last_updated) |
-| `figma-extractor.md` | `figma-discover` | migration | stdout JSON only |
-| `token-mapper.md` | `token-map` | tokens | stdout Markdown only |
-| `reuse-auditor.md` | `reuse-audit` | dependencies | stdout JSON only |
-| `structure-decider.md` | `structure-decide` | naming | stdout 2 lines only |
-| `scaffolder.md` | `component-scaffold` | **no-invention, naming, bem-testid, tokens, accessibility, dependencies, migration** | `<name>.vue`, sub-components, `injection-key.ts`, local `package.json`, root `package.json#exports` |
-| `storybook-writer.md` | `storybook-write` | naming, tokens, **storybook**, no-invention | `apps/storybook/src/stories/webkit/<category>/<Name>.stories.js` |
-| `code-connect-writer.md` | `code-connect-write` | naming, migration | `<name>.figma.ts` |
-| `echo-reporter.md` | `echo-report` | naming, tokens, storybook | stdout report only |
+| Sub-agent                | Skill it executes    | Reads (rules)                                                                                                                                                                                                              | Writes                                                                        |
+| ------------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `spec-author.md`         | `spec-create`        | tokens, naming, dependencies, migration, storybook                                                                                                                                                                         | `.specs/<name>.md` (draft)                                                    |
+| `spec-validator.md`      | `spec-validate`      | tokens, naming                                                                                                                                                                                                             | spec frontmatter only (status, checksum, last_updated)                        |
+| `figma-extractor.md`     | `figma-discover`     | migration                                                                                                                                                                                                                  | stdout JSON only                                                              |
+| `token-mapper.md`        | `token-map`          | tokens                                                                                                                                                                                                                     | stdout Markdown only                                                          |
+| `reuse-auditor.md`       | `reuse-audit`        | dependencies                                                                                                                                                                                                               | stdout JSON only                                                              |
+| `structure-decider.md`   | `structure-decide`   | naming                                                                                                                                                                                                                     | stdout 2 lines only                                                           |
+| `scaffolder.md`          | `component-scaffold` | **no-invention, naming, component-structure, props, prop-vocabulary, v-model, emits, event-payloads, slots, composables, root-element, component-states, styling, tokens, accessibility, testid, dependencies, migration** | `<name>.vue`, sub-components, `injection-key.ts`, root `package.json#exports` |
+| `storybook-writer.md`    | `storybook-write`    | naming, tokens, **storybook**, no-invention                                                                                                                                                                                | `apps/storybook/src/stories/components/<category>/<PascalName>.stories.js`              |
+| `code-connect-writer.md` | `code-connect-write` | naming, migration                                                                                                                                                                                                          | `<name>.figma.ts`                                                             |
+| `echo-reporter.md`       | `echo-report`        | naming, tokens, storybook                                                                                                                                                                                                  | stdout report only                                                            |
 
 ## Rules catalog ([.claude/rules/](../rules/))
 
-| File | Purpose |
-|---|---|
-| `no-invention.md` | The hard prohibitions; the spec is the contract |
-| `dependencies.md` | **No external positioning/animation libs.** CSS + Vue primitives only |
-| `migration.md` | **Never inherit artifacts as-is.** Rewrite to our conventions |
-| `styling.md` | **Classes inline on the root.** No JS class presets, no `<style>` block, variants via `data-*` |
+| File                     | Purpose                                                                                            |
+| ------------------------ | -------------------------------------------------------------------------------------------------- |
+| `no-invention.md`        | The hard prohibitions; the spec is the contract                                                    |
+| `dependencies.md`        | **No external positioning/animation libs.** CSS + Vue primitives only                              |
+| `migration.md`           | **Never inherit artifacts as-is.** Rewrite to our conventions                                      |
+| `styling.md`             | **Classes inline on the root.** No JS class presets, no `<style>` block, variants via `data-*`     |
+| `component-structure.md` | Fixed folder layout + `<script setup>` section order                                               |
+| `props.md`               | Typed `interface Props` + `withDefaults` + JSDoc; exported variant unions                          |
+| `prop-vocabulary.md`     | One canonical name/type/default per concept (`kind`, `size`, `disabled`…)                          |
+| `v-model.md`             | Two-way values via `defineModel` — controlled + uncontrolled, one macro                            |
+| `emits.md`               | Typed `defineEmits`, kebab names, model vs. activation                                             |
+| `event-payloads.md`      | Activation events emit `(event, item)` — DOM event first                                           |
+| `slots.md`               | Typed `defineSlots`, kebab names, fallback inside the slot                                         |
+| `composables.md`         | `readonly` outward, `toValue` args, `onScopeDispose` cleanup; context composable                   |
+| `root-element.md`        | Own the root: polymorphism via `href`, `$attrs` forwarding, minimal `defineExpose`                 |
+| `component-states.md`    | Declared, rendered state surface (loading/empty/error via DS components)                           |
+| `accessibility.md`       | Role, keyboard, focus, `motion-reduce` — owned by the component                                    |
+| `testid.md`              | `data-testid` derived `<category>-<name>` / `input-<name>`, overridable                            |
+| `deprecation.md`         | Mark `@deprecated` → one major → remove                                                            |
+| `bundle-budget.md`       | Per-entry budget recorded in `.size-limit.json`; automated CI gate pending — review holds the line |
 
 ## Source-of-truth docs ([.claude/docs/](../docs/))
 
-| File | Purpose |
-|---|---|
-| `DESIGN.md` | Tokens (typography, spacing, container, shape, shadow, colors), animation catalog, forbidden list |
+| File                        | Purpose                                                                                                                            |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `DESIGN.md`                 | Tokens (typography, spacing, container, shape, shadow, colors), animation catalog, forbidden list                                  |
 | `COMPONENT_REQUIREMENTS.md` | Component pattern: TypeScript, naming, slots, BEM data-testid, ARIA, Composition Pattern, Storybook discipline, Styling discipline |
-| `PRIMEVUE_ABSTRACTION.md` | PrimeVue wrapping under `core/primevue/*` |
 
 ## Rules every agent file inherits
 

.claude/agents/code-connect-writer.md

@@ -2,6 +2,7 @@
 name: code-connect-writer
 description: Isolated sub-agent that writes the <name>.figma.ts Code Connect mapping next to the .vue. Skips itself when @figma/code-connect is not installed.
 status: active
+scope: webkit
 ---
 
 # Agent: code-connect-writer

.claude/agents/echo-reporter.md

@@ -2,6 +2,7 @@
 name: echo-reporter
 description: Isolated sub-agent that re-reads every file written this run, parses props/events/slots/animations independently, and diffs against the spec. Cross-checks against validate-spec-compliance.mjs.
 status: active
+scope: webkit
 ---
 
 # Agent: echo-reporter