[NO-ISSUE] feat(webkit)!: adoption toolkit (in-package) + prop-vocabulary guardrails + canonical prop renames

.claude/AGENTS.md

@@ -149,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:**
@@ -191,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).
@@ -221,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

@@ -37,7 +37,7 @@ If anything is ambiguous, emit a `BLOCKED: <reason>` line and write no files.
 | `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`, root `package.json#exports` |
+| `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/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 |
@@ -50,14 +50,27 @@ If anything is ambiguous, emit a `BLOCKED: <reason>` line and write no files.
 | `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 `size-limit`; tree-shaking stays intact |
 
 ## Source-of-truth docs ([.claude/docs/](../docs/))
 
 | 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/scaffolder.md

@@ -24,6 +24,8 @@ You are the `scaffolder` sub-agent. You execute the `component-scaffold` skill v
 - Do not default an optional text-bearing string prop to `undefined`. Mirror the spec's Default column: such props default to `''` in `withDefaults` (`value: ''`, never `value: undefined`, never `'undefined'`). `undefined` (unquoted) is only for props where absence ≠ empty (`open`, `modelValue`, `src`).
 - Do not invent imports. Every `@aziontech/webkit/*` path must exist in `packages/webkit/package.json#exports`. Every relative import must resolve.
 - Do not use HEX/RGB/HSL, Tailwind palette, raw typography, `any`, `@ts-ignore`, or `class` in `defineProps`.
+- Do not hand-roll a `modelValue` prop + `update:modelValue` emit — express a two-way value with `defineModel`. See `.claude/rules/v-model.md`.
+- Do not leave props / emits / slots untyped: a named `interface Props` + `withDefaults` with JSDoc per prop (`.claude/rules/props.md`); typed `defineEmits<{…}>()` (`.claude/rules/emits.md`, `event-payloads.md`); typed `defineSlots<{…}>()` (`.claude/rules/slots.md`). Follow the fixed `<script setup>` section order and folder layout in `.claude/rules/component-structure.md`, the root-element contract in `.claude/rules/root-element.md`, the composable contract in `.claude/rules/composables.md`, the state surface in `.claude/rules/component-states.md`, and the `data-testid` derivation in `.claude/rules/testid.md`.
 - Do not declare component-local `@keyframes` or `<style>` blocks.
 - Do not omit `motion-reduce:*` on motion-bearing classes.
 - Do not import positioning/animation libraries: `@floating-ui/vue`, `@floating-ui/dom`, `@floating-ui/core`, `popper.js`, `@popperjs/core`, `tippy.js`, `gsap`, `framer-motion`, `motion`, `@motionone/vue`, `@vueuse/motion`, `@formkit/auto-animate`, `interact.js`, drag-drop runtimes, scroll virtualization libs. Use CSS + Vue primitives (`<Teleport>`, `<Transition>`). See `.claude/rules/dependencies.md`.

.claude/commands/add-animation.md

@@ -0,0 +1,22 @@
+# /add-animation <name> [component]
+
+Scaffold a **new** webkit animation in the one correct place — the semantic animation
+catalog — so components never ship a component-local `@keyframes` or an off-catalog
+`animate-[…]`. Triggered by hand, or pointed at by `validate-spec-compliance` when a
+component uses an `animate-*` that is not yet in the catalog.
+
+Run the **add-animation** skill (`.claude/skills/add-animation/SKILL.md`). It:
+
+1. Adds a `.animate-<name>` utility + its `@keyframes` to
+   `packages/theme/src/tokens/semantic/animations.js`, using the `duration` / `curve`
+   tokens from `primitives/animations/animate.js` (never a raw ms / cubic-bezier literal).
+2. Records a **Theme gaps** row in the component's `.specs/<component>.md` (when a
+   component is given) so the addition is tracked.
+3. Regenerates the catalog (`pnpm --filter @aziontech/webkit.dev catalog:build`) so
+   `tokens.animations` includes `<name>` and the compliance cross-check passes.
+4. Reminds you to pair the class with `motion-reduce:*` in the component.
+
+Do **not** edit `.claude/docs/DESIGN.md` — the catalog + `semantic/animations.js` are the
+source of truth; DESIGN.md is a human mirror updated separately.
+
+`<name>` is kebab-case (e.g. `slide-left`). The keyframe name is its camelCase form.

.claude/commands/component-create.md

@@ -35,7 +35,7 @@ Spawn the `spec-validator` sub-agent with the universal envelope (see `.claude/a
 If `--dry-run`, print the planned writes here and exit 0.
 
 ### Step 4 — Scaffold (writes)
-Spawn the `scaffolder` sub-agent. Envelope includes: spec verbatim + Constraints + rules (`no-invention`, `naming`, `bem-testid`, `tokens`, `accessibility`) + `component-scaffold` skill + canonical paths to inspect (button.vue, card-pricing.vue). Task tells it exactly which files to write.
+Spawn the `scaffolder` sub-agent. Envelope includes: spec verbatim + Constraints + the construction rules — `no-invention`, `naming`, `component-structure`, `props`, `prop-vocabulary`, `v-model`, `emits`, `event-payloads`, `slots`, `composables`, `root-element`, `component-states`, `styling`, `tokens`, `accessibility`, `testid` — + `component-scaffold` skill + canonical paths to inspect (button.vue, card-pricing.vue). Task tells it exactly which files to write.
 
 Hooks that fire on every Write:
 - PreToolUse: `enforce-spec-exists`, `validate-tokens`, `validate-references`, `enforce-component-create`.

.claude/docs/COMPONENT_REQUIREMENTS.md

@@ -476,7 +476,7 @@ If your component needs Vue Router:
 
 ### 3. Styling
 
-- ✅ **DO:** Use PrimeVue styling conventions
+- ✅ **DO:** Use the webkit token + `data-*` styling conventions
 - ✅ **DO:** Support custom classes via `attrs.class` (`useAttrs()` with `inheritAttrs: false`; do not declare `class` as a prop)
 - ✅ **DO:** Use Tailwind CSS utility classes
 - ❌ **DON'T:** Hardcode colors or spacing
@@ -560,7 +560,7 @@ When creating a new component, ensure you've completed all requirements:
 <script setup>
   import { computed, ref, toRef, useAttrs } from 'vue'
   import { useField } from 'vee-validate'
-  import InputText from 'primevue/inputtext'
+  import InputText from '@aziontech/webkit/input-text'
   import Label from '../label/label.vue'
 
   const emit = defineEmits(['blur', 'input'])
@@ -645,7 +645,7 @@ When creating a new component, ensure you've completed all requirements:
 ```vue
 <script setup>
   import { ref, onMounted } from 'vue'
-  import Button from 'primevue/button'
+  import Button from '@aziontech/webkit/button'
 
   const props = defineProps({
     apiUrl: {
@@ -708,7 +708,7 @@ When creating a new component, ensure you've completed all requirements:
 ```vue
 <script setup>
   import { useRouter } from 'vue-router'
-  import Button from 'primevue/button'
+  import Button from '@aziontech/webkit/button'
 
   const props = defineProps({
     to: {
@@ -786,7 +786,6 @@ When creating a new component, ensure you've completed all requirements:
 
 - [Vue 3 Composition API](https://vuejs.org/api/composition-api-setup.html)
 - [VeeValidate Documentation](https://vee-validate.logaretm.com/v4/)
-- [PrimeVue Components](https://primevue.org/)
 - [Vue Router Documentation](https://router.vuejs.org/)
 
 ---
@@ -806,7 +805,7 @@ All visual rules (typography classes, spacing, max-width, shape, semantic colors
 - **Shape:** `var(--shape-button)`, `var(--shape-elements)`, `var(--shape-card)`, `var(--shape-flat)`. For pseudo-element inheritance use `rounded-[inherit]`.
 - **Spacing:** `var(--spacing-1)..(--spacing-N)` applied via `px-[...]` / `py-[...]` / `gap-[...]` / `m-[...]`. For section-level responsive spacing use the semantic utilities (`gap-spacing-elements-md`, `p-spacing-elements-lg`).
 - **Max width:** `var(--container-max-width)` for layout containers, `var(--container-3xs..--container-7xl)` for fixed content (cards, modals). Utility helper: `.max-container-width`.
-- **Forbidden:** hex/rgb/hsl hardcoded; Tailwind palette names (`bg-gray-*`, `text-violet-*`); PrimeVue color utilities (`text-color`, `surface-*`); raw typography (`text-xs`/`text-sm`/`text-base`/`text-lg`).
+- **Forbidden:** hex/rgb/hsl hardcoded; Tailwind palette names (`bg-gray-*`, `text-violet-*`); external/legacy color utilities (`text-color`, `surface-*`); raw typography (`text-xs`/`text-sm`/`text-base`/`text-lg`).
 
 ### 2. TypeScript tipado obrigatório