From b2d40ded0132d93fef049b3a504541cb1def5cdb Mon Sep 17 00:00:00 2001
From: HerbertJulio <herbert.julio@azion.com>
Date: Wed, 24 Jun 2026 17:51:32 -0300
Subject: [PATCH 1/2] docs(webkit): codify Show code pattern + flat-import rule

storybook-write skill: document the copy-paste-ready 'Show code' transform,
now in the current repo format (stories under stories/components, title
Components/<Category>/<Name>, direct `@aziontech/webkit/<name>` imports, /i on
the SFC-detector regex). Adds .claude/rules/imports.md codifying the flat public
export name (category lives in the folder + story title, not the import).
---
 .claude/rules/imports.md                |  46 ++++++++
 .claude/skills/storybook-write/SKILL.md | 149 +++++++++++++++++-------
 2 files changed, 154 insertions(+), 41 deletions(-)
 create mode 100644 .claude/rules/imports.md

diff --git a/.claude/rules/imports.md b/.claude/rules/imports.md
new file mode 100644
index 00000000..69cfc626
--- /dev/null
+++ b/.claude/rules/imports.md
@@ -0,0 +1,46 @@
+# Rule: imports — flat public name, category in the folder only
+
+Every webkit component is published under a **flat, single-segment public name**. The category (`feedback`, `content`, `inputs`, `data`, `actions`, …) organizes the **source folder** and the **Storybook tree**, but it never appears in the public import path or the `package.json` export key.
+
+## The rule
+
+> O export é **direto**: `@aziontech/webkit/<name>`. **Nunca** com prefixo de categoria (`@aziontech/webkit/feedback/skeleton`). A categoria vive na pasta (`src/components/<category>/<name>/`) e no título da story (`Components/<Category>/<Name>`), não no nome público.
+
+| Concern | Correct | Forbidden |
+|---|---|---|
+| `package.json#exports` key | `"./skeleton"` | `"./feedback/skeleton"` |
+| `package.json#exports` value | `"./src/components/feedback/skeleton/skeleton.vue"` | — (folder keeps the category) |
+| Consumer / story / spec import | `@aziontech/webkit/skeleton` | `@aziontech/webkit/feedback/skeleton` |
+| Source folder | `src/components/feedback/skeleton/skeleton.vue` | `src/components/skeleton/skeleton.vue` |
+| Story file location | `apps/storybook/src/stories/components/feedback/skeleton/Skeleton.stories.js` | `apps/storybook/src/stories/webkit/feedback/skeleton/…` |
+| Story `title` | `Components/Feedback/Skeleton` | `Webkit/Feedback/Skeleton` |
+
+## Why
+
+- **Stable public surface.** Consumers import `@aziontech/webkit/skeleton`; moving a component between categories (e.g. `content` → `data`) is then an internal folder move, not a breaking import change.
+- **One name per component.** A flat export key can't collide with a category segment and reads the same everywhere — export key, import, Code Connect.
+- **Folder/tree still carry the category.** The source path (`src/components/<category>/<name>/`) and the Storybook title (`Components/<Category>/<Name>`) keep the taxonomy visible without leaking it into the import.
+
+## What this means in practice
+
+When adding or migrating a component named `<name>` in category `<category>`:
+
+1. **Source** lives at `packages/webkit/src/components/<category>/<name>/<name>.vue` with its local `package.json`.
+2. **Export** in `packages/webkit/package.json#exports` is the flat key:
+   ```jsonc
+   "./<name>": "./src/components/<category>/<name>/<name>.vue"
+   ```
+3. **Story** lives at `apps/storybook/src/stories/components/<category>/<name>/<PascalName>.stories.js` and sets `title: 'Components/<Category>/<PascalName>'`.
+4. **Every import** — in the story, the spec's `## Usage` block, and any consumer — is `@aziontech/webkit/<name>`.
+
+If the flat name is already taken by another component, that is a **naming** problem: rename the new component, do not fall back to a category-prefixed export. Emit `BLOCKED: export key "./<name>" already in use` and resolve the name before shipping.
+
+## Migration note
+
+Components authored before this convention (or branched from an older layout) may carry `@aziontech/webkit/<category>/<name>` imports, a `Webkit/…` story title, or a story under `stories/webkit/…`. When touching such a component, bring it to this rule: flatten the export key, retitle the story to `Components/…`, and move the story under `stories/components/…`. See [`migration.md`](./migration.md).
+
+## Enforcement
+
+- `validate-references.mjs` already rejects imports of any `@aziontech/webkit/*` path absent from `packages/webkit/package.json#exports` — a category-prefixed import therefore fails once the export key is flat.
+- The [`storybook-write`](../skills/storybook-write/SKILL.md) skill emits flat imports, `Components/<Category>/<PascalName>` titles, and `stories/components/<category>/…` locations by default.
+- Keep the export list and the story tree consistent with this rule; a prefixed export key (`"./feedback/skeleton"`) is a review-blocking deviation.
diff --git a/.claude/skills/storybook-write/SKILL.md b/.claude/skills/storybook-write/SKILL.md
index fe3f146f..ccec3b92 100644
--- a/.claude/skills/storybook-write/SKILL.md
+++ b/.claude/skills/storybook-write/SKILL.md
@@ -1,15 +1,17 @@
 ---
 name: storybook-write
-description: Write a minimal `.stories.js` for a webkit component using the canonical Button.stories.js shape. Stories are Default + one composite story per multi-option axis (Types / Sizes / Icons / …) + one story per mutually-exclusive state (Loading / Disabled / Filled / Invalid) — never one-story-per-variant. Inject the spec's `## Usage` block into `parameters.docs.description.component` as a code snippet.
+description: Write a minimal `.stories.js` for a webkit component using the canonical Button.stories.js shape. Stories are Default + one composite story per multi-option axis (Types / Sizes / Icons / …) + one story per mutually-exclusive state (Loading / Disabled / Filled / Invalid) — never one-story-per-variant. Give `parameters.docs.description.component` a short prose lead from `## Purpose`, and add a `docs.source.transform` + `docs.canvas.sourceState: 'shown'` so the Docs "Show code" panel emits a runnable, copy-paste-ready SFC.
 status: active
-last_updated: 2026-06-15
+last_updated: 2026-06-24
 ---
 
 # Skill: storybook-write
 
 ## Purpose
 
-Generate `apps/storybook/src/stories/webkit/<category>/<name>/<PascalName>.stories.js` (or `apps/storybook/src/stories/webkit/<category>/<PascalName>.stories.js` for short-form locations) covering **only** the stories listed in the spec's "Stories (Storybook)" section. The canonical shape is the existing `Button.stories.js` — composite `Types` and `Sizes` stories plus state-specific stories (`Loading`, `Disabled`). The spec's `## Usage` block (import + minimal `<script setup>` + `<template>`) is injected verbatim into `parameters.docs.description.component`.
+Generate `apps/storybook/src/stories/components/<category>/<name>/<PascalName>.stories.js` (or `apps/storybook/src/stories/components/<category>/<PascalName>.stories.js` for short-form locations) covering **only** the stories listed in the spec's "Stories (Storybook)" section. The canonical shape is the existing `Button.stories.js` — composite `Types` and `Sizes` stories plus state-specific stories (`Loading`, `Disabled`).
+
+**"Show code" copy-paste-ready (canonical).** `parameters.docs.description.component` carries a **short prose lead** (the `## Purpose` paragraph) — NOT the spec's `## Usage` code block. Instead, the runnable usage is surfaced by the Docs **"Show code"** panel: a `parameters.docs.source.transform` wraps each story's live, args-driven source in a `<script setup>` (with the component's canonical import) + `<template>`, and `parameters.docs.canvas.sourceState: 'shown'` opens the panel by default. Arg-driven stories (Default / state) flow through that transform; **composite / multi-element stories instead set an explicit `parameters.docs.source.code`** (Storybook's dynamic source can't introspect a multi-element `render` template and would otherwise show a single component). Either way the panel shows a runnable SFC that matches the canvas. (Reference: `Skeleton.stories.js`.)
 
 ## When to invoke
 
@@ -20,51 +22,67 @@ Generate `apps/storybook/src/stories/webkit/<category>/<name>/<PascalName>.stori
 - The full text of `.specs/<name>.md`.
 - The Constraints block (verbatim).
 - [`.claude/docs/COMPONENT_REQUIREMENTS.md`](../../docs/COMPONENT_REQUIREMENTS.md), [`.claude/docs/DESIGN.md`](../../docs/DESIGN.md).
-- The reference implementation: [`apps/storybook/src/stories/webkit/actions/button/Button.stories.js`](../../../apps/storybook/src/stories/webkit/actions/button/Button.stories.js).
+- The reference implementation: [`apps/storybook/src/stories/components/actions/button/Button.stories.js`](../../../apps/storybook/src/stories/components/actions/button/Button.stories.js).
 
 ## Workflow
 
 1. **Read the spec.** Extract Props, Events, Slots, the Stories list, and the **`## Usage`** fenced code block (everything between the first ` ```vue ` and the next ` ``` ` inside the section; ignore HTML comments).
-2. **Extract the Purpose paragraph** (first paragraph under `## Purpose`). Use it as the prose lead-in for `parameters.docs.description.component`.
-3. **Build `parameters.docs.description.component`** as a single markdown string concatenating:
-   - The Purpose paragraph (one line).
-   - A blank line.
-   - The literal heading `## Usage` followed by a blank line, then the `vue` fenced code block from the spec.
+2. **Extract the Purpose paragraph** (first paragraph under `## Purpose`). Use it — and only it — as `parameters.docs.description.component` (a short prose lead). Do **not** concatenate the spec's `## Usage` block into the description; the runnable usage is surfaced by the "Show code" panel (step 3).
+3. **Build the "Show code" source transform.** Read the spec's `## Usage` fenced block only to learn the component's canonical import line (`import <PascalName> from '@aziontech/webkit/<name>'`). Add to `parameters.docs`:
+   - `source.transform` — indents the live story source and wraps it in `<script setup>` + the import + `<template>`, so the panel emits a complete, runnable SFC.
+   - `canvas.sourceState: 'shown'` — opens the code panel by default.
 
-   Example (string literal — note the embedded newlines and the four-backtick fence to escape the inner triple-backtick block):
+   Example (string-array `.join('\n')` keeps the SFC literal out of the template parser):
 
-   ````js
+   ```js
    docs: {
      description: {
-       component: [
-         'Interactive control for user actions. Supports label text, optional icon, loading state, and link rendering when `href` is set.',
-         '',
-         '## Usage',
-         '',
-         '```vue',
-         "<script setup>",
-         "import Button from '@aziontech/webkit/button'",
-         '</script>',
-         '',
-         '<template>',
-         '  <Button label="Click me" />',
-         '</template>',
-         '```'
-       ].join('\n')
-     }
+       component:
+         'Interactive control for user actions. Supports label text, optional icon, loading state, and link rendering when `href` is set.'
+     },
+     source: {
+       type: 'dynamic',
+       excludeDecorators: true,
+       transform: (code) => {
+         let src = String(code).trim()
+         // Composite stories pass a full-SFC `source.code` (see step 7) — leave it untouched.
+         if (/<script[\s>]/i.test(src)) return src
+         // Storybook sometimes already wraps arg-driven source in <template> — unwrap once
+         // so we don't emit a nested <template><template>…</template></template>.
+         const wrapped = src.match(/^<template>\s*([\s\S]*?)\s*<\/template>$/)
+         if (wrapped) src = wrapped[1].trim()
+         const body = src
+           .split('\n')
+           .map((line) => (line ? `  ${line}` : line))
+           .join('\n')
+
+         return [
+           '<script setup>',
+           "import Button from '@aziontech/webkit/button'",
+           '</script>',
+           '',
+           '<template>',
+           body,
+           '</template>'
+         ].join('\n')
+       }
+     },
+     canvas: { sourceState: 'shown' }
    }
-   ````
+   ```
 
-   Storybook's Docs page renders this markdown as a fenced code block under a `Usage` heading. The same `Usage` block is the source of truth for both spec and Docs; never copy-paste it elsewhere in the story file.
+   The transform is **idempotent**: it re-wraps an arg-driven story's bare source (Default / state stories) but passes any string that already contains `<script setup>` through unchanged, and it unwraps a single stray `<template>` so the output is never double-wrapped. The spec's `## Usage` block stays the spec's source of truth — it is NOT pasted into the story file.
+
+   **Composite / multi-element stories MUST set an explicit `source.code`.** Storybook's dynamic source CANNOT introspect a custom `render` that returns a raw `template` string with several elements — it falls back to the meta `args` and emits a single component (so the "Show code" shows one item, not the row the canvas renders). Therefore every story whose canvas shows more than the single arg-driven component (`Types`, `Sizes`, `Positions`, any multi-instance composite, and any story built from a raw `render` template) MUST set `parameters.docs.source.code` to a full SFC built from the SAME template it renders. Define that template once as a `const` and reuse it for both `render`'s `template` and `source.code` so they can never drift; the idempotent transform passes the full SFC through untouched. See step 7, Shape B.
 
 4. **Write the meta** following this template (substitute spec values):
 
    ```js
-   import Component from '@aziontech/webkit/<category>/<name>'
+   import Component from '@aziontech/webkit/<name>'
 
    /** @type {import('@storybook/vue3').Meta<typeof Component>} */
    const meta = {
-     title: 'Webkit/<Category>/<PascalName>',
+     title: 'Components/<Category>/<PascalName>',
      component: Component,
      // For Composition Pattern, expose subcomponents:
      // subcomponents: { <Root>Trigger, <Root>Content, ... },
@@ -82,8 +100,14 @@ Generate `apps/storybook/src/stories/webkit/<category>/<name>/<PascalName>.stori
        },
        docs: {
          description: {
-           component: /* the multi-line string built in step 3 */
-         }
+           component: /* the short Purpose prose from step 2 — NOT the Usage block */
+         },
+         source: {
+           type: 'dynamic',
+           excludeDecorators: true,
+           transform: /* the wrapper from step 3 — emits a runnable <script setup> + <template> SFC */
+         },
+         canvas: { sourceState: 'shown' }
        }
      },
      argTypes: {
@@ -217,7 +241,28 @@ Generate `apps/storybook/src/stories/webkit/<category>/<name>/<PascalName>.stori
        `
      }),
      parameters: {
-       docs: { description: { story: 'All kind variants side by side.' } }
+       docs: {
+         controls: { disable: true },
+         description: { story: 'All kind variants side by side.' },
+         // Composite: Storybook's dynamic source can't introspect this template —
+         // supply the real SFC so "Show code" matches the canvas (all variants).
+         source: {
+           code: [
+             '<script setup>',
+             "import Component from '@aziontech/webkit/<name>'",
+             '</script>',
+             '',
+             '<template>',
+             '  <div class="flex flex-wrap items-center gap-4">',
+             '    <Component kind="primary" label="Button" />',
+             '    <Component kind="secondary" label="Button" />',
+             '    <Component kind="outlined" label="Button" />',
+             '    <Component kind="text" label="Button" />',
+             '  </div>',
+             '</template>'
+           ].join('\n')
+         }
+       }
      }
    }
 
@@ -233,11 +278,31 @@ Generate `apps/storybook/src/stories/webkit/<category>/<name>/<PascalName>.stori
        `
      }),
      parameters: {
-       docs: { description: { story: 'All size variants side by side.' } }
+       docs: {
+         controls: { disable: true },
+         description: { story: 'All size variants side by side.' },
+         source: {
+           code: [
+             '<script setup>',
+             "import Component from '@aziontech/webkit/<name>'",
+             '</script>',
+             '',
+             '<template>',
+             '  <div class="flex flex-wrap items-center gap-4">',
+             '    <Component size="small" label="Button" />',
+             '    <Component size="medium" label="Button" />',
+             '    <Component size="large" label="Button" />',
+             '  </div>',
+             '</template>'
+           ].join('\n')
+         }
+       }
      }
    }
    ```
 
+   > Tip: define the template once as a `const` and reuse it in both `render`'s `template` and `source.code` so they can never drift. Any story built from a raw multi-element `render` template (a row of variants, a `Toaster` + several trigger buttons, …) needs this explicit `source.code`.
+
    - **Always-composite stories.** Whenever a prop or slot has more than one meaningful option, render **one composite story** that shows every option side by side — never one story per option. Canonical composites and their backing concept:
      - `Types` — the `kind` prop (visual variants).
      - `Sizes` — the `size` prop.
@@ -251,15 +316,15 @@ Generate `apps/storybook/src/stories/webkit/<category>/<name>/<PascalName>.stori
 
 ## Outputs
 
-- One file: `apps/storybook/src/stories/webkit/<category>/<PascalName>.stories.js` (mirror the component's actual storybook location — some components live under `webkit/<category>/<name>/`, others directly under `webkit/<category>/`).
+- One file: `apps/storybook/src/stories/components/<category>/<PascalName>.stories.js` (mirror the component's actual storybook location — some components live under `components/<category>/<name>/`, others directly under `components/<category>/`).
 - Nothing else.
 
 ## Rules
 
 - **No HEX / Tailwind palette / raw typography** in story templates (some stories embed markup for slots).
 - **No Figma references.** Do NOT add `parameters.design`, `parameters.figma`, links to Figma frames in `docs.description.component` / `docs.description.story`, or imports from `@storybook/addon-designs` / `storybook-addon-designs`. The Figma link is owned by `<name>.figma.ts` (Code Connect), not the story. Full rationale: [`.claude/docs/COMPONENT_REQUIREMENTS.md`](../../docs/COMPONENT_REQUIREMENTS.md).
-- **`docs.description.component` is built from the spec.** The leading prose comes from `## Purpose`; the trailing `## Usage` heading + fenced code block comes verbatim from `## Usage`. No marketing copy, no design history, no Figma URLs, no hand-edited usage examples.
-- **Do not duplicate the Usage snippet.** It lives in `parameters.docs.description.component` and nowhere else in the story file. Do not paste it into a story `description.story`, JSDoc, or comment.
+- **`docs.description.component` is a short prose lead from `## Purpose`** — one or two sentences. Do NOT embed the spec's `## Usage` block (or any static code snippet) in the description; the runnable usage comes from the "Show code" panel. No marketing copy, no design history, no Figma URLs.
+- **Surface usage via the "Show code" panel, not a pasted snippet.** Add `docs.source.transform` (wraps the live arg-driven source in `<script setup>` + the canonical import + `<template>`) and `docs.canvas.sourceState: 'shown'`. The transform must be **idempotent** (pass through any string already containing `<script setup>`; unwrap a single stray `<template>` so it is never double-wrapped). **Composite / multi-element stories set an explicit `docs.source.code`** (full SFC from the same template they render) because the dynamic source can't introspect them. Never paste the `## Usage` code into `description.component`, `description.story`, JSDoc, or a comment.
 - **Events keys are camelCase `on<EventName>`** in `argTypes`. Kebab-case keys silently break the Actions panel.
 - **Do NOT use** `parameters.actions.argTypesRegex` (deprecated in Storybook 8). Declare each event explicitly.
 - **Do NOT use** the legacy `Name.args = {...}` form. Always object-style CSF3.
@@ -271,7 +336,7 @@ Generate `apps/storybook/src/stories/webkit/<category>/<name>/<PascalName>.stori
 
 ## Fallbacks
 
-- Spec has no `## Usage` block (legacy spec being migrated) → emit `BLOCKED: spec missing ## Usage block` and stop. Do not invent a usage snippet.
+- Spec has no `## Usage` block (legacy spec being migrated) → derive the transform's import line from the component's export path (`@aziontech/webkit/<name>`) and proceed; note the missing block in the report. Do not invent a `<template>` example — the transform wraps the live story source, so none is needed.
 - Spec.Stories lists a story name the skill does not recognize → emit it with `args: {}` and a `// TODO: define this story` comment.
 - Spec lists `Types` but the component has only one `kind` (or `Sizes` with one `size`) → omit that story silently; record the divergence in the report.
 
@@ -279,7 +344,9 @@ Generate `apps/storybook/src/stories/webkit/<category>/<name>/<PascalName>.stori
 
 - [ ] One `.stories.js` written at the canonical path.
 - [ ] Meta has `title`, `component`, `tags: ['autodocs']`, `parameters` (`layout: 'centered'`, `backgrounds`, `a11y`, `docs`), `argTypes`, `args`.
-- [ ] `parameters.docs.description.component` contains the Purpose paragraph **and** the `## Usage` heading + the `vue` fenced code block lifted verbatim from the spec.
+- [ ] `parameters.docs.description.component` is the short `## Purpose` prose only (no embedded `## Usage` block / code snippet).
+- [ ] `parameters.docs.source.transform` wraps the live story source in `<script setup>` + the canonical import + `<template>`, is idempotent (passes through full SFCs, unwraps a stray `<template>`), and `parameters.docs.canvas.sourceState: 'shown'` is set (the "Show code" panel emits a runnable, copy-paste-ready SFC).
+- [ ] Every composite / multi-element story (`Types`, `Sizes`, `Positions`, any multi-instance row, any raw-`render`-template story) sets an explicit `parameters.docs.source.code` (a full SFC from the same template it renders), so "Show code" shows all rendered elements — not a single arg-driven component.
 - [ ] Every prop, event, and slot from the spec has an `argTypes` entry.
 - [ ] Reusable `Template` declared once at module scope, forwarding `args` reactively via `setup() { return { args } }` + `v-bind="args"` — NO destructuring, NO manual `@event` listeners for stateless components (events auto-wire through `v-bind` when declared in `argTypes` with `action`).
 - [ ] **For v-model components**, every story (Default, composites, and state stories) holds a local `ref` synced from `args.modelValue` (via `watch` on `Template`, or fresh refs per instance in composites), binds it with `:model-value="value"` + `@update:model-value="onUpdate"`, and the handler calls `args['onUpdate:modelValue']?.(next)` so the Actions panel logs every change. Composite stories that render multiple stateful instances give each instance its own ref (or one shared ref if the spec links them) — never leave instances with a frozen `modelValue` from `v-bind="args"` alone.
@@ -289,4 +356,4 @@ Generate `apps/storybook/src/stories/webkit/<category>/<name>/<PascalName>.stori
 - [ ] No one-story-per-variant (`Small`/`Medium`/`Large`, `Primary`/`Secondary`/…, `WithLeadingIcon`/`WithTrailingIcon`) — the corresponding composite (`Sizes`, `Types`, `Icons`) is the canonical replacement.
 - [ ] No `argTypesRegex`, no legacy `.args =` form.
 - [ ] No `parameters.design` / `parameters.figma`, no Figma URLs anywhere in the file, no `@storybook/addon-designs` import.
-- [ ] The `## Usage` snippet appears in exactly one place in the file (inside `docs.description.component`).
+- [ ] No static `## Usage` snippet is pasted into `description.component` — usage is emitted by the "Show code" panel (`docs.source.transform` for arg-driven stories, `docs.source.code` for composites).

From 8f470a7c2965a2fe19bfda562ee47505241c3d42 Mon Sep 17 00:00:00 2001
From: HerbertJulio <herbert.julio@azion.com>
Date: Thu, 25 Jun 2026 18:23:39 -0300
Subject: [PATCH 2/2] docs(webkit): translate imports rule blockquote to
 English

---
 .claude/rules/imports.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude/rules/imports.md b/.claude/rules/imports.md
index 69cfc626..d707c711 100644
--- a/.claude/rules/imports.md
+++ b/.claude/rules/imports.md
@@ -4,7 +4,7 @@ Every webkit component is published under a **flat, single-segment public name**
 
 ## The rule
 
-> O export é **direto**: `@aziontech/webkit/<name>`. **Nunca** com prefixo de categoria (`@aziontech/webkit/feedback/skeleton`). A categoria vive na pasta (`src/components/<category>/<name>/`) e no título da story (`Components/<Category>/<Name>`), não no nome público.
+> The export is **flat**: `@aziontech/webkit/<name>`. **Never** with a category prefix (`@aziontech/webkit/feedback/skeleton`). The category lives in the folder (`src/components/<category>/<name>/`) and in the story title (`Components/<Category>/<Name>`), not in the public name.
 
 | Concern | Correct | Forbidden |
 |---|---|---|