From ef69c3793a4d222eaaabce7c847fd44855eb5c82 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Robson=20J=C3=BAnior?= <robson.ga.junior@gmail.com>
Date: Mon, 29 Jun 2026 14:32:07 -0300
Subject: [PATCH 1/3] feat(webkit): add accordion component

Composition accordion (content/accordion): single/multiple open modes, medium/large sizes, left/right chevron placement, v-model:value, and full keyboard + ARIA support. Adds the compound API (Accordion.Item/Trigger/Content), four flat package exports, and the Storybook story.

ENG-46311
---
 .specs/accordion.md                           | 209 ++++++++++++
 .../content/accordion/Accordion.stories.js    | 319 ++++++++++++++++++
 packages/webkit/package.json                  |   5 +
 .../accordion-content/accordion-content.vue   |  47 +++
 .../accordion-item/accordion-item.vue         |  77 +++++
 .../accordion-trigger/accordion-trigger.vue   | 109 ++++++
 .../content/accordion/accordion.vue           | 164 +++++++++
 .../src/components/content/accordion/index.ts |  18 +
 .../content/accordion/injection-key.ts        |  65 ++++
 9 files changed, 1013 insertions(+)
 create mode 100644 .specs/accordion.md
 create mode 100644 apps/storybook/src/stories/components/content/accordion/Accordion.stories.js
 create mode 100644 packages/webkit/src/components/content/accordion/accordion-content/accordion-content.vue
 create mode 100644 packages/webkit/src/components/content/accordion/accordion-item/accordion-item.vue
 create mode 100644 packages/webkit/src/components/content/accordion/accordion-trigger/accordion-trigger.vue
 create mode 100644 packages/webkit/src/components/content/accordion/accordion.vue
 create mode 100644 packages/webkit/src/components/content/accordion/index.ts
 create mode 100644 packages/webkit/src/components/content/accordion/injection-key.ts

diff --git a/.specs/accordion.md b/.specs/accordion.md
new file mode 100644
index 000000000..bcb2431c0
--- /dev/null
+++ b/.specs/accordion.md
@@ -0,0 +1,209 @@
+---
+name: accordion
+category: content
+structure: composition
+status: implemented
+spec_version: 1
+figma:
+  url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=480-876
+  node_id: "480:876"
+checksum: 9622e5553d34740b37547c94095a517c81bec07e36ed29a7e03766753336a2f4
+created: 2026-06-26
+last_updated: 2026-06-26
+---
+
+# Accordion — Component Spec
+
+## Purpose
+
+A vertically stacked set of disclosure items: each item has a clickable header that expands or collapses its content panel. Use it to condense long content into scannable sections. Unlike `tab-view` (mutually-exclusive panels shown in place), an accordion can keep one item open at a time (`type="single"`) or several at once (`type="multiple"`), and its content expands inline below each header.
+
+## Usage
+
+```vue
+<script setup>
+import Accordion from '@aziontech/webkit/accordion'
+</script>
+
+<template>
+  <Accordion
+    type="single"
+    collapsible
+    default-value="overview"
+    size="medium"
+    arrow-position="right"
+  >
+    <Accordion.Item value="overview">
+      <Accordion.Trigger>What is Azion?</Accordion.Trigger>
+      <Accordion.Content>Azion runs your code at the edge, close to users.</Accordion.Content>
+    </Accordion.Item>
+    <Accordion.Item value="pricing">
+      <Accordion.Trigger>How does pricing work?</Accordion.Trigger>
+      <Accordion.Content>Pay only for what you use, with no upfront cost.</Accordion.Content>
+    </Accordion.Item>
+    <Accordion.Item value="support" disabled>
+      <Accordion.Trigger>Enterprise support</Accordion.Trigger>
+      <Accordion.Content>Available on Business and Enterprise plans.</Accordion.Content>
+    </Accordion.Item>
+  </Accordion>
+</template>
+```
+
+Tree-shaking alternative — the same sub-components as standalone imports:
+
+```vue
+<script setup>
+import Accordion from '@aziontech/webkit/accordion'
+import AccordionItem from '@aziontech/webkit/accordion-item'
+import AccordionTrigger from '@aziontech/webkit/accordion-trigger'
+import AccordionContent from '@aziontech/webkit/accordion-content'
+</script>
+```
+
+## Sub-components
+
+The root ships a **compound API**: an `index.ts` (beside `accordion.vue`) attaches every sub-component to the root so `<Accordion.Item>` / `<Accordion.Trigger>` / `<Accordion.Content>` resolve from one import; the standalone imports above remain the tree-shaking path. The root is a disclosure component with `data-state="open|closed"`, so `Trigger` / `Content` are the correct anatomy names. Shared open-state flows through `provide`/`inject` (`injection-key.ts`), so the consumer wires nothing.
+
+- `accordion-item/accordion-item.vue` — One disclosure row. Registers itself with the root by `value`, derives its own open/closed state from the injected context, and groups a `Trigger` + a `Content`.
+  - Props: `value: string` (**required** — unique identifier used by the open-state model), `disabled?: boolean` (default `false` — prevents this item from toggling; from the Figma component description).
+  - Slot: `default` — the item's `Accordion.Trigger` and `Accordion.Content`.
+- `accordion-trigger/accordion-trigger.vue` — The clickable header row (Figma "Header"): renders the title plus the `pi pi-chevron-down` glyph, toggles the item through the injected context, and exposes `aria-expanded` / `aria-controls`. To satisfy the ARIA accordion pattern, the `<button>` is wrapped in a heading element.
+  - Props: `level?: 2 | 3 | 4 | 5 | 6` (default `3` — heading level of the wrapping `<h{level}>` for correct document outline).
+  - Slot: `default` — header title content.
+- `accordion-content/accordion-content.vue` — The collapsible panel. Mounts only when its item is open, reads the content/trigger ids from context, and exposes `role="region"` + `aria-labelledby`.
+  - Slot: `default` — panel body content.
+
+Resulting layout (no per-component `package.json` — dropped repo-wide; the root `packages/webkit/package.json#exports` resolves every path; `.d.ts` is generated at publish time, never committed):
+
+```
+packages/webkit/src/components/content/accordion/
+├── accordion.vue                 (root; owns type/value/size/arrowPosition, provides context)
+├── index.ts                      (compound: attaches Item / Trigger / Content to the root)
+├── injection-key.ts              (shared AccordionContext)
+├── accordion-item/
+│   └── accordion-item.vue
+├── accordion-trigger/
+│   └── accordion-trigger.vue
+└── accordion-content/
+    └── accordion-content.vue
+```
+
+Exports to add to `packages/webkit/package.json#exports` (flat public names; category lives in the folder only):
+
+```jsonc
+"./accordion": "./src/components/content/accordion/index.ts",
+"./accordion-item": "./src/components/content/accordion/accordion-item/accordion-item.vue",
+"./accordion-trigger": "./src/components/content/accordion/accordion-trigger/accordion-trigger.vue",
+"./accordion-content": "./src/components/content/accordion/accordion-content/accordion-content.vue"
+```
+
+## Props
+
+Props below belong to the root `Accordion`. Sub-component props are documented in the **Sub-components** section above.
+
+| Prop | Type | Default | Required | JSDoc |
+|---|---|---|---|---|
+| `type` | `'single' \| 'multiple'` | `'single'` | no | Whether one or multiple items can be open at the same time. |
+| `value` | `string \| string[] \| null` | `undefined` | no | Controlled open item(s): a single `value` string in single mode, an array of values in multiple mode. Use with `v-model:value`. |
+| `defaultValue` | `string \| string[] \| null` | `null` | no | Initial open item(s) when uncontrolled. |
+| `collapsible` | `boolean` | `true` | no | In single mode, lets the open item collapse so that no item is open. |
+| `size` | `'medium' \| 'large'` | `'medium'` | no | Size token; affects header height, padding, and typography. Provided to every item via context. |
+| `arrowPosition` | `'left' \| 'right'` | `'right'` | no | Side of the header the chevron sits on. Provided to every item via context. |
+
+## Events
+
+Events below are emitted by the root `Accordion`.
+
+| Event | Payload | Notes |
+|---|---|---|
+| `update:value` | `string \| string[] \| null` | `v-model:value`. Fires when the open item(s) change. |
+| `value-change` | `string \| string[] \| null` | Convenience event mirroring `update:value`. |
+
+## Slots
+
+| Slot | Scope | Notes |
+|---|---|---|
+| `default` | — | The `Accordion.Item` children. Each sub-component's own `default` slot is documented in the Sub-components section. |
+
+## States
+
+- Visual states: `default`, `hover`, `focus-visible`, `active`, `disabled`
+- `data-state` values: `open` | `closed` — on the item, the trigger, and the content
+- `data-disabled` mirrors the per-item `disabled` prop
+- `data-orientation`: `vertical`
+
+## Motion & Animations
+
+| Trigger | Animation / Transition | Token (see `.claude/docs/DESIGN.md` § Animations) | Reduced-motion fallback |
+|---|---|---|---|
+| chevron rotate on open | `transition-transform duration-150 ease-out` + `data-[state=open]:rotate-180` | inline (matches catalog) | `motion-reduce:transition-none` |
+| content reveal on open (on `Accordion.Content` only) | fade-in semantic utility from `animations.js` | semantic (matches catalog) | reduced-motion fallback via the matching `motion-reduce` utility |
+| header hover state change | `transition-colors duration-150 ease-out` | inline (matches catalog) | `motion-reduce:transition-none` |
+
+> Figma declares no motion spec for this component (the open/closed/hover states are static variants). The transitions above are taken from our existing catalog — the chevron pattern mirrors `select-trigger.vue` (`data-[state=open]:rotate-180`), and the content reveal reuses the fade-in semantic utility (as `tab-view` does). No component-local `@keyframes`.
+
+## Tokens
+
+| Region | Token (DESIGN.md) |
+|---|---|
+| header title typography (large / medium) | `.text-body-md` / `.text-body-sm` |
+| content body typography (large / medium) | `.text-body-sm` / `.text-body-xs` |
+| header title text | `var(--text-default)` |
+| content body text | `var(--text-muted)` |
+| disabled text | `var(--text-disabled)` |
+| header divider (bottom border) | `var(--border-default)` |
+| item divider when closed | `var(--border-muted)` |
+| header padding-x | `var(--spacing-md)` |
+| header gap (arrow right / left) | `var(--spacing-sm)` / `var(--spacing-xs)` |
+| content padding (large / medium) | `var(--spacing-xl)` / `var(--spacing-md)` |
+| focus ring / ring offset | `var(--ring-color)` / `var(--bg-canvas)` |
+
+## Theme gaps
+
+| Figma variable | Temporary primitive | Follow-up |
+|---|---|---|
+| `Heading/xss` · `Heading/xs` (Sora Regular, line-height 1.4) used for the header title | `.text-body-sm` · `.text-body-md` (line-height 1.5, same 14px / 16px sizes, same Regular weight) | `TODO: decide whether to surface text-heading-xs/xxs in DESIGN.md, or keep the body family for the title` |
+| `Hover=True` variant (delta not resolvable via the Figma MCP bound-variable API) | `hover:bg-[var(--bg-hover)]` on the trigger | `TODO: confirm the header hover treatment with design` |
+| `--border-width-default` (0.8px header / item divider) | `border-b` (1px) | `TODO: tokenize the sub-pixel border width if it must match exactly` |
+
+## Accessibility (WCAG 2.1 AA)
+
+- Visible focus (Figma has no focus variant; we own it): `focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)]` on each `Accordion.Trigger`.
+- Keyboard map: `Tab` / `Shift+Tab` move between triggers and into open content; `Enter` / `Space` toggle the focused item; `Arrow Down` / `Arrow Up` move focus to the next / previous trigger; `Home` / `End` move focus to the first / last trigger.
+- ARIA: each trigger is a `<button>` with `aria-expanded` reflecting open state and `aria-controls` referencing its content; the trigger button is wrapped in a heading element (`<h{level}>`, default `h3`); the content panel has `role="region"` and `aria-labelledby` referencing its trigger. A `disabled` item sets `disabled` + `aria-disabled` on its trigger.
+- Contrast ≥4.5:1 for text (title `--text-default`, body `--text-muted` on the surface) / ≥3:1 for the chevron glyph, including the disabled state (`--text-disabled`).
+- `motion-reduce:transition-none motion-reduce:animate-none` on the chevron rotation and content reveal.
+- Touch target: the `large` header is 40px tall and the full-width header row is the hit area (≥40×40). The `medium` header is 32px tall — a justified deviation matching the Figma `medium` size token, mitigated by the full-width clickable row.
+
+## Stories (Storybook)
+
+- **Default** — a single-mode accordion with a few items, one open via `default-value`.
+- **Sizes** — composite story rendering `medium` and `large` side by side.
+- **ArrowPosition** — composite story rendering `right` and `left` chevron placement side by side. _Justification:_ `arrowPosition` is a visual variant axis taken straight from the Figma variant matrix, exactly like `size`; the canonical one-composite-story-per-axis pattern applies.
+- **Disabled** — an accordion whose middle item carries the per-item `disabled` prop, demonstrating the non-toggling state.
+- **Multiple** — an accordion with `type="multiple"` and two items open at once. _Justification:_ single-vs-multiple is the component's core behavioral contract (called out in the Figma component description) and is the one mode the single-mode Default story cannot show.
+
+## Constraints — DO NOT
+
+<!-- This block is injected VERBATIM into every sub-agent prompt.
+     spec-validator rejects the spec if this block is missing or shorter than the template. -->
+
+- Do not add props beyond the Props table above. If you need a prop that is not listed, emit `BLOCKED: missing prop <name>` and stop — do not invent.
+- Do not add events beyond the Events table above. Same rule for slots and sub-components.
+- Do not invent imports. Every `@aziontech/webkit/*` path must exist in `packages/webkit/package.json#exports`. Every relative import must resolve to a real file. Every npm package must be installed.
+- Do not use HEX/RGB/HSL colors, Tailwind palette names (e.g. `bg-blue-500`), raw typography classes (e.g. `text-sm`), `any`, `@ts-ignore`, or `class` inside `defineProps`.
+- Do not install or import positioning/animation libraries (`@floating-ui/*`, `popper.js`, `tippy.js`, `gsap`, `framer-motion`, `motion`, `@vueuse/motion`, `@formkit/auto-animate`, drag-drop runtimes, scroll virtualization libs). Use CSS + Vue primitives (`<Teleport>`, `<Transition>`). See `.claude/rules/dependencies.md`.
+- Do not improvise animations. Every `animate-*` / `transition-*` class must come from `packages/theme/src/tokens/semantic/animations.js`; every motion-bearing class pairs with `motion-reduce:*` on the same class string; no component-local `@keyframes`.
+- Do not create class presets in JavaScript (`const kindClasses = {...}`, `const sharedClasses = [...]`, `const sizeClasses = {...}`, `const rootClasses = computed(...)`). Variants live on `data-*` attributes consumed by Tailwind `data-[attr=value]:`. All utilities live inline on the root element's `class` attribute. No `<style>` block, no component-local `.css`/`.scss`. See `.claude/rules/styling.md`.
+- Do not inherit artifacts as-is from another design system, Figma file, library, or pre-existing `CONTRACT.md` / `README.md`. Rewrite to our conventions. See `.claude/rules/migration.md`.
+- Do not add Figma references to Storybook stories. No `parameters.design`, no `parameters.figma`, no Figma URLs in `docs.description.*`, no `@storybook/addon-designs` import. The Figma link is owned by `<name>.figma.ts` (Code Connect). See `.claude/docs/COMPONENT_REQUIREMENTS.md`.
+- Do not use `parameters.actions.argTypesRegex` (deprecated in Storybook 8 and silently misroutes Vue 3 emits) or `parameters.actions.handles` (DOM-only). Declare every event explicitly in `argTypes` with a camelCase `on<Event>` key and `{ action: '<emitted-name>' }`. Do not use the legacy CSF2 `Name.args = {...}` form — always object-style CSF3.
+- Do not add bespoke Storybook stories beyond Default + Types + Sizes + state stories (`Loading`, `Disabled`) for the props the component actually declares, unless the spec's "Stories (Storybook)" section explicitly justifies the addition. Do not split Types/Sizes into one-story-per-variant — the composite stories are the canonical pattern.
+- Do not duplicate the `## Usage` block from the spec inside the Storybook story body. The block is injected once into `parameters.docs.description.component` by the storybook-write skill; copy it nowhere else.
+- Do not edit `.claude/docs/DESIGN.md`, `.claude/docs/COMPONENT_REQUIREMENTS.md`, or `.claude/docs/PRIMEVUE_ABSTRACTION.md`.
+- Do not edit the root `package.json` or `.github/workflows/*`.
+- Do not export composition sub-components without attaching them to the root compound (`index.ts` via `Object.assign`; vue-tsc generates `index.d.ts` — never hand-write it); the root export and the root `package.json` main/module point at `index.ts`, `types` at `index.d.ts`. Do not invent overlay part names (`Trigger` / `Content`) on a component with no `data-state=open|closed`, and do not collapse a slot-shaped concern into a config-array prop. See `.claude/rules/compound-api.md`.
+- Do not change `structure` after `status: approved`. To change structure, bump `spec_version` and re-author the spec.
+- Do not create files outside the paths declared by your task (the orchestrator tells you exactly which files to write).
+- Do not run `git` commands, `pnpm install`, or any command that changes the lockfile.
+- If anything in the spec is ambiguous or contradicts the rules, emit `BLOCKED: <one-sentence reason>` and write nothing.
diff --git a/apps/storybook/src/stories/components/content/accordion/Accordion.stories.js b/apps/storybook/src/stories/components/content/accordion/Accordion.stories.js
new file mode 100644
index 000000000..5897cd6a9
--- /dev/null
+++ b/apps/storybook/src/stories/components/content/accordion/Accordion.stories.js
@@ -0,0 +1,319 @@
+import Accordion from '@aziontech/webkit/accordion'
+
+const components = {
+  Accordion,
+  AccordionItem: Accordion.Item,
+  AccordionTrigger: Accordion.Trigger,
+  AccordionContent: Accordion.Content
+}
+
+const ITEMS = [
+  {
+    value: 'overview',
+    title: 'What is Azion?',
+    body: 'Azion runs your code at the edge, close to users.'
+  },
+  {
+    value: 'pricing',
+    title: 'How does pricing work?',
+    body: 'Pay only for what you use, with no upfront cost.'
+  },
+  {
+    value: 'support',
+    title: 'Enterprise support',
+    body: 'Available on Business and Enterprise plans.'
+  }
+]
+
+/** @type {import('@storybook/vue3').Meta<typeof Accordion>} */
+const meta = {
+  title: 'Components/Content/Accordion',
+  component: Accordion,
+  subcomponents: {
+    'Accordion.Item': Accordion.Item,
+    'Accordion.Trigger': Accordion.Trigger,
+    'Accordion.Content': Accordion.Content
+  },
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    backgrounds: { default: 'dark' },
+    a11y: {
+      config: {
+        rules: [
+          { id: 'color-contrast', enabled: true },
+          { id: 'aria-required-attr', enabled: true }
+        ]
+      }
+    },
+    docs: {
+      description: {
+        component: [
+          'A vertically stacked set of disclosure items: each item has a clickable header that expands or collapses its content panel. Use it to condense long content into scannable sections. Unlike `tab-view` (mutually-exclusive panels shown in place), an accordion can keep one item open at a time (`type="single"`) or several at once (`type="multiple"`), and its content expands inline below each header.',
+          '',
+          '## Usage',
+          '',
+          '```vue',
+          '<script setup>',
+          "import Accordion from '@aziontech/webkit/accordion'",
+          '</script>',
+          '',
+          '<template>',
+          '  <Accordion',
+          '    type="single"',
+          '    collapsible',
+          '    default-value="overview"',
+          '    size="medium"',
+          '    arrow-position="right"',
+          '  >',
+          '    <Accordion.Item value="overview">',
+          '      <Accordion.Trigger>What is Azion?</Accordion.Trigger>',
+          '      <Accordion.Content>Azion runs your code at the edge, close to users.</Accordion.Content>',
+          '    </Accordion.Item>',
+          '    <Accordion.Item value="pricing">',
+          '      <Accordion.Trigger>How does pricing work?</Accordion.Trigger>',
+          '      <Accordion.Content>Pay only for what you use, with no upfront cost.</Accordion.Content>',
+          '    </Accordion.Item>',
+          '    <Accordion.Item value="support" disabled>',
+          '      <Accordion.Trigger>Enterprise support</Accordion.Trigger>',
+          '      <Accordion.Content>Available on Business and Enterprise plans.</Accordion.Content>',
+          '    </Accordion.Item>',
+          '  </Accordion>',
+          '</template>',
+          '```'
+        ].join('\n')
+      },
+      source: {
+        type: 'dynamic',
+        excludeDecorators: true
+      },
+      canvas: {
+        sourceState: 'shown'
+      }
+    }
+  },
+  argTypes: {
+    type: {
+      control: 'select',
+      options: ['single', 'multiple'],
+      description: 'Whether one or multiple items can be open at the same time.',
+      table: {
+        category: 'props',
+        type: { summary: "'single' | 'multiple'" },
+        defaultValue: { summary: "'single'" }
+      }
+    },
+    value: {
+      control: 'text',
+      description:
+        'Controlled open item(s): a single `value` string in single mode, an array of values in multiple mode. Use with `v-model:value`.',
+      table: { category: 'props', type: { summary: 'string | string[] | null' } }
+    },
+    defaultValue: {
+      control: 'text',
+      description: 'Initial open item(s) when uncontrolled.',
+      table: {
+        category: 'props',
+        type: { summary: 'string | string[] | null' },
+        defaultValue: { summary: 'null' }
+      }
+    },
+    collapsible: {
+      control: 'boolean',
+      description: 'In single mode, lets the open item collapse so that no item is open.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'true' } }
+    },
+    size: {
+      control: 'select',
+      options: ['medium', 'large'],
+      description: 'Size token; affects header height, padding, and typography.',
+      table: {
+        category: 'props',
+        type: { summary: "'medium' | 'large'" },
+        defaultValue: { summary: "'medium'" }
+      }
+    },
+    arrowPosition: {
+      control: 'select',
+      options: ['left', 'right'],
+      description: 'Side of the header the chevron sits on.',
+      table: {
+        category: 'props',
+        type: { summary: "'left' | 'right'" },
+        defaultValue: { summary: "'right'" }
+      }
+    },
+    onUpdateValue: {
+      action: 'update:value',
+      description: '`v-model:value`. Fires when the open item(s) change.',
+      table: { category: 'events' }
+    },
+    onValueChange: {
+      action: 'value-change',
+      description: 'Convenience event mirroring `update:value`.',
+      table: { category: 'events' }
+    },
+    default: {
+      control: false,
+      description: 'The `Accordion.Item` children.',
+      table: { type: { summary: 'VNode' }, category: 'slots' }
+    }
+  },
+  args: {
+    type: 'single',
+    collapsible: true,
+    size: 'medium',
+    arrowPosition: 'right'
+  }
+}
+
+export default meta
+
+const Template = (args) => ({
+  components,
+  setup() {
+    const { onUpdateValue, onValueChange, ...props } = args
+    return { props, items: ITEMS, onUpdateValue, onValueChange }
+  },
+  template: `
+    <Accordion
+      v-bind="props"
+      class="w-full max-w-[40rem]"
+      @update:value="onUpdateValue"
+      @value-change="onValueChange"
+    >
+      <AccordionItem v-for="item in items" :key="item.value" :value="item.value">
+        <AccordionTrigger>{{ item.title }}</AccordionTrigger>
+        <AccordionContent>{{ item.body }}</AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  `
+})
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Accordion>} */
+export const Default = {
+  args: { defaultValue: 'overview' },
+  render: Template,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Single-mode accordion with one item open via `default-value`.'
+      }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Accordion>} */
+export const Sizes = {
+  render: () => ({
+    components,
+    setup() {
+      return { items: ITEMS }
+    },
+    template: `
+      <div class="flex flex-col gap-8 w-full max-w-[40rem]">
+        <Accordion type="single" collapsible default-value="overview" size="medium">
+          <AccordionItem v-for="item in items" :key="item.value" :value="item.value">
+            <AccordionTrigger>{{ item.title }}</AccordionTrigger>
+            <AccordionContent>{{ item.body }}</AccordionContent>
+          </AccordionItem>
+        </Accordion>
+        <Accordion type="single" collapsible default-value="overview" size="large">
+          <AccordionItem v-for="item in items" :key="item.value" :value="item.value">
+            <AccordionTrigger>{{ item.title }}</AccordionTrigger>
+            <AccordionContent>{{ item.body }}</AccordionContent>
+          </AccordionItem>
+        </Accordion>
+      </div>
+    `
+  }),
+  parameters: {
+    docs: {
+      description: { story: '`medium` and `large` sizes side by side.' }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Accordion>} */
+export const ArrowPosition = {
+  render: () => ({
+    components,
+    setup() {
+      return { items: ITEMS }
+    },
+    template: `
+      <div class="flex flex-col gap-8 w-full max-w-[40rem]">
+        <Accordion type="single" collapsible default-value="overview" arrow-position="right">
+          <AccordionItem v-for="item in items" :key="item.value" :value="item.value">
+            <AccordionTrigger>{{ item.title }}</AccordionTrigger>
+            <AccordionContent>{{ item.body }}</AccordionContent>
+          </AccordionItem>
+        </Accordion>
+        <Accordion type="single" collapsible default-value="overview" arrow-position="left">
+          <AccordionItem v-for="item in items" :key="item.value" :value="item.value">
+            <AccordionTrigger>{{ item.title }}</AccordionTrigger>
+            <AccordionContent>{{ item.body }}</AccordionContent>
+          </AccordionItem>
+        </Accordion>
+      </div>
+    `
+  }),
+  parameters: {
+    docs: {
+      description: { story: '`right` and `left` chevron placement side by side.' }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Accordion>} */
+export const Disabled = {
+  render: () => ({
+    components,
+    setup() {
+      return { items: ITEMS }
+    },
+    template: `
+      <Accordion type="single" collapsible default-value="overview" class="w-full max-w-[40rem]">
+        <AccordionItem
+          v-for="item in items"
+          :key="item.value"
+          :value="item.value"
+          :disabled="item.value === 'pricing'"
+        >
+          <AccordionTrigger>{{ item.title }}</AccordionTrigger>
+          <AccordionContent>{{ item.body }}</AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    `
+  }),
+  parameters: {
+    docs: {
+      description: { story: 'The middle item carries the per-item `disabled` prop and cannot toggle.' }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Accordion>} */
+export const Multiple = {
+  render: () => ({
+    components,
+    setup() {
+      return { items: ITEMS, openValues: ['overview', 'pricing'] }
+    },
+    template: `
+      <Accordion type="multiple" :default-value="openValues" class="w-full max-w-[40rem]">
+        <AccordionItem v-for="item in items" :key="item.value" :value="item.value">
+          <AccordionTrigger>{{ item.title }}</AccordionTrigger>
+          <AccordionContent>{{ item.body }}</AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    `
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: '`type="multiple"` with two items open at once via an array `default-value`.'
+      }
+    }
+  }
+}
diff --git a/packages/webkit/package.json b/packages/webkit/package.json
index 8518717e0..b39c4f5a3 100644
--- a/packages/webkit/package.json
+++ b/packages/webkit/package.json
@@ -67,6 +67,11 @@
     "./tag": "./src/components/tag/tag.vue",
     "./avatar": "./src/components/avatar/avatar.vue",
     "./badge": "./src/components/content/badge/badge.vue",
+    "./accordion": "./src/components/content/accordion/index.ts",
+    "./accordion-root": "./src/components/content/accordion/accordion.vue",
+    "./accordion-item": "./src/components/content/accordion/accordion-item/accordion-item.vue",
+    "./accordion-trigger": "./src/components/content/accordion/accordion-trigger/accordion-trigger.vue",
+    "./accordion-content": "./src/components/content/accordion/accordion-content/accordion-content.vue",
     "./card-box": "./src/components/content/card-box/card-box.vue",
     "./card-pricing": "./src/components/content/card-pricing/card-pricing.vue",
     "./item": "./src/components/content/item/index.js",
diff --git a/packages/webkit/src/components/content/accordion/accordion-content/accordion-content.vue b/packages/webkit/src/components/content/accordion/accordion-content/accordion-content.vue
new file mode 100644
index 000000000..37d14a60e
--- /dev/null
+++ b/packages/webkit/src/components/content/accordion/accordion-content/accordion-content.vue
@@ -0,0 +1,47 @@
+<script setup lang="ts">
+  import { computed, inject, useAttrs } from 'vue'
+
+  import { AccordionInjectionKey, AccordionItemInjectionKey } from '../injection-key'
+
+  defineOptions({
+    name: 'AccordionContent',
+    inheritAttrs: false
+  })
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const ctx = inject(AccordionInjectionKey)
+  if (!ctx) {
+    throw new Error('AccordionContent must be used inside <Accordion>.')
+  }
+
+  const itemCtx = inject(AccordionItemInjectionKey)
+  if (!itemCtx) {
+    throw new Error('AccordionContent must be used inside <Accordion.Item>.')
+  }
+
+  const attrs = useAttrs()
+
+  const testId = computed(
+    () => (attrs['data-testid'] as string | undefined) ?? 'content-accordion-content'
+  )
+</script>
+
+<template>
+  <div
+    v-if="itemCtx.open.value"
+    v-bind="$attrs"
+    role="region"
+    :id="itemCtx.contentId.value"
+    :aria-labelledby="itemCtx.triggerId.value"
+    :data-testid="testId"
+    :data-state="itemCtx.open.value ? 'open' : 'closed'"
+    :data-size="ctx.size.value"
+    :class="attrs.class"
+    class="animate-fade-in text-[var(--text-muted)] motion-reduce:animate-none data-[size=medium]:p-[var(--spacing-md)] data-[size=medium]:text-body-xs data-[size=large]:p-[var(--spacing-xl)] data-[size=large]:text-body-sm"
+  >
+    <slot />
+  </div>
+</template>
diff --git a/packages/webkit/src/components/content/accordion/accordion-item/accordion-item.vue b/packages/webkit/src/components/content/accordion/accordion-item/accordion-item.vue
new file mode 100644
index 000000000..c7a61ea37
--- /dev/null
+++ b/packages/webkit/src/components/content/accordion/accordion-item/accordion-item.vue
@@ -0,0 +1,77 @@
+<script setup lang="ts">
+  import { computed, inject, onBeforeUnmount, onMounted, provide, ref, useAttrs } from 'vue'
+
+  import { cn } from '../../../../utils/cn'
+  import { AccordionInjectionKey, AccordionItemInjectionKey } from '../injection-key'
+
+  defineOptions({
+    name: 'AccordionItem',
+    inheritAttrs: false
+  })
+
+  interface Props {
+    /** Unique identifier used by the open-state model. */
+    value: string
+    /** Prevents this item from toggling. */
+    disabled?: boolean
+  }
+
+  const props = withDefaults(defineProps<Props>(), {
+    disabled: false
+  })
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const ctx = inject(AccordionInjectionKey)
+  if (!ctx) {
+    throw new Error('AccordionItem must be used inside <Accordion>.')
+  }
+
+  const attrs = useAttrs()
+  const root = ref<globalThis.HTMLElement | null>(null)
+
+  const testId = computed(
+    () => (attrs['data-testid'] as string | undefined) ?? 'content-accordion-item'
+  )
+
+  const open = computed(() => ctx.isOpen(props.value))
+  const disabled = computed(() => props.disabled)
+  const triggerId = computed(() => ctx.triggerId(props.value))
+  const contentId = computed(() => ctx.contentId(props.value))
+
+  provide(AccordionItemInjectionKey, {
+    value: props.value,
+    disabled,
+    open,
+    triggerId,
+    contentId
+  })
+
+  onMounted(() => {
+    ctx.register({ value: props.value, disabled: props.disabled, el: root })
+  })
+
+  onBeforeUnmount(() => {
+    ctx.unregister(props.value)
+  })
+</script>
+
+<template>
+  <div
+    ref="root"
+    v-bind="$attrs"
+    :data-testid="testId"
+    :data-state="open ? 'open' : 'closed'"
+    :data-disabled="disabled || null"
+    :class="
+      cn(
+        'flex flex-col border-b border-[var(--border-muted)] data-[state=open]:border-b-0',
+        attrs.class as string | undefined
+      )
+    "
+  >
+    <slot />
+  </div>
+</template>
diff --git a/packages/webkit/src/components/content/accordion/accordion-trigger/accordion-trigger.vue b/packages/webkit/src/components/content/accordion/accordion-trigger/accordion-trigger.vue
new file mode 100644
index 000000000..8a803cee4
--- /dev/null
+++ b/packages/webkit/src/components/content/accordion/accordion-trigger/accordion-trigger.vue
@@ -0,0 +1,109 @@
+<script setup lang="ts">
+  import { computed, inject, useAttrs } from 'vue'
+
+  import { AccordionInjectionKey, AccordionItemInjectionKey } from '../injection-key'
+
+  defineOptions({
+    name: 'AccordionTrigger',
+    inheritAttrs: false
+  })
+
+  interface Props {
+    /** Heading level of the wrapping heading element for correct document outline. */
+    level?: 2 | 3 | 4 | 5 | 6
+  }
+
+  const props = withDefaults(defineProps<Props>(), {
+    level: 3
+  })
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const ctx = inject(AccordionInjectionKey)
+  if (!ctx) {
+    throw new Error('AccordionTrigger must be used inside <Accordion>.')
+  }
+
+  const itemCtx = inject(AccordionItemInjectionKey)
+  if (!itemCtx) {
+    throw new Error('AccordionTrigger must be used inside <Accordion.Item>.')
+  }
+
+  const attrs = useAttrs()
+
+  const testId = computed(
+    () => (attrs['data-testid'] as string | undefined) ?? 'content-accordion-trigger'
+  )
+
+  const headingTag = computed(() => `h${props.level}` as const)
+
+  const onClick = () => {
+    if (itemCtx.disabled.value) return
+    ctx.toggle(itemCtx.value)
+  }
+
+  const onKeydown = (event: globalThis.KeyboardEvent) => {
+    switch (event.key) {
+      case 'Enter':
+      case ' ':
+        if (itemCtx.disabled.value) return
+        event.preventDefault()
+        ctx.toggle(itemCtx.value)
+        break
+      case 'ArrowDown':
+        event.preventDefault()
+        ctx.focusSibling(itemCtx.value, 1)
+        break
+      case 'ArrowUp':
+        event.preventDefault()
+        ctx.focusSibling(itemCtx.value, -1)
+        break
+      case 'Home':
+        event.preventDefault()
+        ctx.focusEdge('first')
+        break
+      case 'End':
+        event.preventDefault()
+        ctx.focusEdge('last')
+        break
+      default:
+    }
+  }
+</script>
+
+<template>
+  <component
+    :is="headingTag"
+    class="flex"
+  >
+    <button
+      v-bind="$attrs"
+      type="button"
+      :id="itemCtx.triggerId.value"
+      :aria-expanded="itemCtx.open.value"
+      :aria-controls="itemCtx.contentId.value"
+      :aria-disabled="itemCtx.disabled.value || undefined"
+      :disabled="itemCtx.disabled.value"
+      :data-testid="testId"
+      :data-state="itemCtx.open.value ? 'open' : 'closed'"
+      :data-size="ctx.size.value"
+      :data-arrow="ctx.arrowPosition.value"
+      :data-disabled="itemCtx.disabled.value || null"
+      :class="attrs.class"
+      class="group flex w-full items-center justify-between border-b border-[var(--border-default)] bg-transparent px-[var(--spacing-md)] text-left text-[var(--text-default)] outline-none transition-colors duration-150 ease-out motion-reduce:transition-none hover:bg-[var(--bg-hover)] focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)] data-[size=medium]:min-h-8 data-[size=medium]:gap-[var(--spacing-sm)] data-[size=medium]:text-body-sm data-[size=large]:min-h-10 data-[size=large]:gap-[var(--spacing-sm)] data-[size=large]:text-body-md data-[arrow=left]:flex-row-reverse data-[arrow=left]:justify-end data-[arrow=left]:gap-[var(--spacing-xs)] data-[disabled]:cursor-not-allowed data-[disabled]:text-[var(--text-disabled)]"
+      @click="onClick"
+      @keydown="onKeydown"
+    >
+      <span class="flex-1 data-[arrow=left]:flex-none group-data-[arrow=left]:flex-none">
+        <slot />
+      </span>
+      <i
+        class="pi pi-chevron-down shrink-0 text-[var(--text-muted)] transition-transform duration-150 ease-out motion-reduce:transition-none group-data-[state=open]:rotate-180 group-data-[disabled]:text-[var(--text-disabled)]"
+        aria-hidden="true"
+        :data-testid="`${testId}__chevron`"
+      />
+    </button>
+  </component>
+</template>
diff --git a/packages/webkit/src/components/content/accordion/accordion.vue b/packages/webkit/src/components/content/accordion/accordion.vue
new file mode 100644
index 000000000..4c53a15fe
--- /dev/null
+++ b/packages/webkit/src/components/content/accordion/accordion.vue
@@ -0,0 +1,164 @@
+<script setup lang="ts">
+  import { computed, onBeforeUnmount, provide, shallowRef, useAttrs, useId } from 'vue'
+
+  import { useControllable } from '../../../composables/use-controllable'
+  import { cn } from '../../../utils/cn'
+  import {
+    type AccordionArrowPosition,
+    AccordionInjectionKey,
+    type AccordionItemRegistration,
+    type AccordionSize,
+    type AccordionType,
+    type AccordionValue
+  } from './injection-key'
+
+  defineOptions({
+    name: 'Accordion',
+    inheritAttrs: false
+  })
+
+  interface Props {
+    /** Whether one or multiple items can be open at the same time. */
+    type?: AccordionType
+    /** Controlled open item(s): a single value string in single mode, an array of values in multiple mode. Use with `v-model:value`. */
+    value?: AccordionValue
+    /** Initial open item(s) when uncontrolled. */
+    defaultValue?: AccordionValue
+    /** In single mode, lets the open item collapse so that no item is open. */
+    collapsible?: boolean
+    /** Size token; affects header height, padding, and typography. Provided to every item via context. */
+    size?: AccordionSize
+    /** Side of the header the chevron sits on. Provided to every item via context. */
+    arrowPosition?: AccordionArrowPosition
+  }
+
+  const props = withDefaults(defineProps<Props>(), {
+    type: 'single',
+    value: undefined,
+    defaultValue: null,
+    collapsible: true,
+    size: 'medium',
+    arrowPosition: 'right'
+  })
+
+  const emit = defineEmits<{
+    'update:value': [value: AccordionValue]
+    'value-change': [value: AccordionValue]
+  }>()
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const valueModel = defineModel<AccordionValue>('value', { default: undefined })
+
+  const attrs = useAttrs()
+  const baseId = useId()
+
+  const testId = computed(() => (attrs['data-testid'] as string | undefined) ?? 'content-accordion')
+
+  const valueProp = computed(() => valueModel.value ?? props.value)
+
+  const openValue = useControllable<AccordionValue>({
+    prop: valueProp,
+    defaultProp: props.defaultValue,
+    onChange: (next) => {
+      valueModel.value = next
+      emit('update:value', next)
+      emit('value-change', next)
+    }
+  })
+
+  const isOpen = (value: string): boolean => {
+    const current = openValue.value
+    if (Array.isArray(current)) return current.includes(value)
+    return current === value
+  }
+
+  const toggle = (value: string) => {
+    if (props.type === 'multiple') {
+      const current = Array.isArray(openValue.value) ? [...openValue.value] : []
+      const index = current.indexOf(value)
+      if (index === -1) current.push(value)
+      else current.splice(index, 1)
+      openValue.set(current)
+      return
+    }
+
+    if (openValue.value === value) {
+      if (props.collapsible) openValue.set(null)
+      return
+    }
+    openValue.set(value)
+  }
+
+  const items = shallowRef<AccordionItemRegistration[]>([])
+
+  const register = (registration: AccordionItemRegistration) => {
+    const existing = items.value.filter((item) => item.value !== registration.value)
+    items.value = [...existing, registration]
+  }
+
+  const unregister = (value: string) => {
+    items.value = items.value.filter((item) => item.value !== value)
+  }
+
+  const getEnabled = () => items.value.filter((item) => !item.disabled)
+
+  const focusTrigger = (item: AccordionItemRegistration | undefined) => {
+    const trigger = item?.el.value?.querySelector<globalThis.HTMLButtonElement>('button')
+    trigger?.focus()
+  }
+
+  const focusSibling = (value: string, direction: 1 | -1) => {
+    const enabled = getEnabled()
+    if (!enabled.length) return
+    const currentIndex = enabled.findIndex((item) => item.value === value)
+    const startIndex = currentIndex === -1 ? 0 : currentIndex
+    const nextIndex = (startIndex + direction + enabled.length) % enabled.length
+    focusTrigger(enabled[nextIndex])
+  }
+
+  const focusEdge = (edge: 'first' | 'last') => {
+    const enabled = getEnabled()
+    if (!enabled.length) return
+    focusTrigger(edge === 'first' ? enabled[0] : enabled[enabled.length - 1])
+  }
+
+  const triggerId = (value: string) => `${baseId}-trigger-${value}`
+  const contentId = (value: string) => `${baseId}-content-${value}`
+
+  provide(AccordionInjectionKey, {
+    value: computed(() => openValue.value),
+    toggle,
+    isOpen,
+    type: computed(() => props.type),
+    collapsible: computed(() => props.collapsible),
+    size: computed(() => props.size),
+    arrowPosition: computed(() => props.arrowPosition),
+    register,
+    unregister,
+    focusSibling,
+    focusEdge,
+    triggerId,
+    contentId
+  })
+
+  onBeforeUnmount(() => {
+    items.value = []
+  })
+</script>
+
+<template>
+  <div
+    v-bind="$attrs"
+    :data-testid="testId"
+    data-orientation="vertical"
+    :data-type="type"
+    :data-size="size"
+    :data-arrow="arrowPosition"
+    :class="cn('flex w-full flex-col', attrs.class as string | undefined)"
+  >
+    <slot />
+  </div>
+</template>
diff --git a/packages/webkit/src/components/content/accordion/index.ts b/packages/webkit/src/components/content/accordion/index.ts
new file mode 100644
index 000000000..aa04a69a4
--- /dev/null
+++ b/packages/webkit/src/components/content/accordion/index.ts
@@ -0,0 +1,18 @@
+import AccordionRoot from './accordion.vue'
+import AccordionContent from './accordion-content/accordion-content.vue'
+import AccordionItem from './accordion-item/accordion-item.vue'
+import AccordionTrigger from './accordion-trigger/accordion-trigger.vue'
+
+interface AccordionStatic {
+  Item: typeof AccordionItem
+  Trigger: typeof AccordionTrigger
+  Content: typeof AccordionContent
+}
+
+const Accordion = AccordionRoot as typeof AccordionRoot & AccordionStatic
+Accordion.Item = AccordionItem
+Accordion.Trigger = AccordionTrigger
+Accordion.Content = AccordionContent
+
+export default Accordion
+export { AccordionContent, AccordionItem, AccordionTrigger }
diff --git a/packages/webkit/src/components/content/accordion/injection-key.ts b/packages/webkit/src/components/content/accordion/injection-key.ts
new file mode 100644
index 000000000..3acb33a49
--- /dev/null
+++ b/packages/webkit/src/components/content/accordion/injection-key.ts
@@ -0,0 +1,65 @@
+import type { ComputedRef, InjectionKey, Ref } from 'vue'
+
+export type AccordionType = 'single' | 'multiple'
+
+export type AccordionSize = 'medium' | 'large'
+
+export type AccordionArrowPosition = 'left' | 'right'
+
+export type AccordionValue = string | string[] | null
+
+export interface AccordionItemRegistration {
+  /** Unique identifier of the item. */
+  value: string
+  /** Whether the item is non-interactive. */
+  disabled: boolean
+  /** Item root element ref, used by roving focus to locate triggers. */
+  el: Ref<globalThis.HTMLElement | null>
+}
+
+export interface AccordionContext {
+  /** Resolved open item(s): a string (or null) in single mode, an array in multiple mode. */
+  value: ComputedRef<AccordionValue>
+  /** Toggles the item identified by `value`, honoring type/collapsible rules. */
+  toggle: (value: string) => void
+  /** Whether the item identified by `value` is currently open. */
+  isOpen: (value: string) => boolean
+  /** Selection mode. */
+  type: ComputedRef<AccordionType>
+  /** In single mode, whether the open item may collapse to none. */
+  collapsible: ComputedRef<boolean>
+  /** Size token, mirrored onto every item. */
+  size: ComputedRef<AccordionSize>
+  /** Side the chevron sits on, mirrored onto every item. */
+  arrowPosition: ComputedRef<AccordionArrowPosition>
+  /** Registers an item so roving focus can find its trigger. */
+  register: (registration: AccordionItemRegistration) => void
+  /** Removes a previously registered item. */
+  unregister: (value: string) => void
+  /** Moves focus to the next/previous enabled trigger (wraps). */
+  focusSibling: (value: string, direction: 1 | -1) => void
+  /** Moves focus to the first/last enabled trigger. */
+  focusEdge: (edge: 'first' | 'last') => void
+  /** Stable id for an item's trigger button. */
+  triggerId: (value: string) => string
+  /** Stable id for an item's content panel. */
+  contentId: (value: string) => string
+}
+
+export const AccordionInjectionKey: InjectionKey<AccordionContext> = Symbol('AccordionContext')
+
+export interface AccordionItemContext {
+  /** This item's unique identifier. */
+  value: string
+  /** Whether this item is non-interactive. */
+  disabled: ComputedRef<boolean>
+  /** Whether this item is currently open. */
+  open: ComputedRef<boolean>
+  /** Stable id of this item's trigger button. */
+  triggerId: ComputedRef<string>
+  /** Stable id of this item's content panel. */
+  contentId: ComputedRef<string>
+}
+
+export const AccordionItemInjectionKey: InjectionKey<AccordionItemContext> =
+  Symbol('AccordionItemContext')

From 84ffd9bc12449b12d765db314a211ecfc05548a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Thu, 2 Jul 2026 11:34:15 -0300
Subject: [PATCH 2/3] feat!: remove default padding from Accordion.Content

BREAKING CHANGE: Accordion.Content no longer applies internal padding. Consumers that relied on the built-in spacing must wrap their slot content with their own padding.
---
 .specs/accordion.md                                      | 9 ++++-----
 .../accordion/accordion-content/accordion-content.vue    | 2 +-
 2 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/.specs/accordion.md b/.specs/accordion.md
index bcb2431c0..c348551c9 100644
--- a/.specs/accordion.md
+++ b/.specs/accordion.md
@@ -3,13 +3,13 @@ name: accordion
 category: content
 structure: composition
 status: implemented
-spec_version: 1
+spec_version: 2
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=480-876
   node_id: "480:876"
-checksum: 9622e5553d34740b37547c94095a517c81bec07e36ed29a7e03766753336a2f4
+checksum: 228238eb66de5c316dc42923e807a87ac550d3b351134e5ae64deb356827f793
 created: 2026-06-26
-last_updated: 2026-06-26
+last_updated: 2026-07-02
 ---
 
 # Accordion — Component Spec
@@ -70,7 +70,7 @@ The root ships a **compound API**: an `index.ts` (beside `accordion.vue`) attach
 - `accordion-trigger/accordion-trigger.vue` — The clickable header row (Figma "Header"): renders the title plus the `pi pi-chevron-down` glyph, toggles the item through the injected context, and exposes `aria-expanded` / `aria-controls`. To satisfy the ARIA accordion pattern, the `<button>` is wrapped in a heading element.
   - Props: `level?: 2 | 3 | 4 | 5 | 6` (default `3` — heading level of the wrapping `<h{level}>` for correct document outline).
   - Slot: `default` — header title content.
-- `accordion-content/accordion-content.vue` — The collapsible panel. Mounts only when its item is open, reads the content/trigger ids from context, and exposes `role="region"` + `aria-labelledby`.
+- `accordion-content/accordion-content.vue` — The collapsible panel. Mounts only when its item is open, reads the content/trigger ids from context, and exposes `role="region"` + `aria-labelledby`. The container applies no padding — the slotted content owns its own spacing.
   - Slot: `default` — panel body content.
 
 Resulting layout (no per-component `package.json` — dropped repo-wide; the root `packages/webkit/package.json#exports` resolves every path; `.d.ts` is generated at publish time, never committed):
@@ -155,7 +155,6 @@ Events below are emitted by the root `Accordion`.
 | item divider when closed | `var(--border-muted)` |
 | header padding-x | `var(--spacing-md)` |
 | header gap (arrow right / left) | `var(--spacing-sm)` / `var(--spacing-xs)` |
-| content padding (large / medium) | `var(--spacing-xl)` / `var(--spacing-md)` |
 | focus ring / ring offset | `var(--ring-color)` / `var(--bg-canvas)` |
 
 ## Theme gaps
diff --git a/packages/webkit/src/components/content/accordion/accordion-content/accordion-content.vue b/packages/webkit/src/components/content/accordion/accordion-content/accordion-content.vue
index 37d14a60e..529a337d5 100644
--- a/packages/webkit/src/components/content/accordion/accordion-content/accordion-content.vue
+++ b/packages/webkit/src/components/content/accordion/accordion-content/accordion-content.vue
@@ -40,7 +40,7 @@
     :data-state="itemCtx.open.value ? 'open' : 'closed'"
     :data-size="ctx.size.value"
     :class="attrs.class"
-    class="animate-fade-in text-[var(--text-muted)] motion-reduce:animate-none data-[size=medium]:p-[var(--spacing-md)] data-[size=medium]:text-body-xs data-[size=large]:p-[var(--spacing-xl)] data-[size=large]:text-body-sm"
+    class="animate-fade-in text-[var(--text-muted)] motion-reduce:animate-none data-[size=medium]:text-body-xs data-[size=large]:text-body-sm"
   >
     <slot />
   </div>

From 5ed2ca47080d2618fb7bbe8af5b6f0e4da232234 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Thu, 2 Jul 2026 14:08:56 -0300
Subject: [PATCH 3/3] docs: show runnable SFC in Accordion Storybook Show Code

Replace Storybook's unreliable dynamic Vue source with explicit
parameters.docs.source.code built via toSfc, per storybook-source rule.
Each story now shows a full <script setup> + <template> snippet using
the Accordion.Item / Accordion.Trigger / Accordion.Content dot-notation
that consumers can paste and run as-is.
---
 .../content/accordion/Accordion.stories.js    | 280 +++++++++++-------
 1 file changed, 178 insertions(+), 102 deletions(-)

diff --git a/apps/storybook/src/stories/components/content/accordion/Accordion.stories.js b/apps/storybook/src/stories/components/content/accordion/Accordion.stories.js
index 5897cd6a9..f7cb64d8d 100644
--- a/apps/storybook/src/stories/components/content/accordion/Accordion.stories.js
+++ b/apps/storybook/src/stories/components/content/accordion/Accordion.stories.js
@@ -1,5 +1,9 @@
 import Accordion from '@aziontech/webkit/accordion'
 
+import { toSfc } from '../../../_shared/story-source'
+
+const IMPORT = "import Accordion from '@aziontech/webkit/accordion'"
+
 const components = {
   Accordion,
   AccordionItem: Accordion.Item,
@@ -7,24 +11,6 @@ const components = {
   AccordionContent: Accordion.Content
 }
 
-const ITEMS = [
-  {
-    value: 'overview',
-    title: 'What is Azion?',
-    body: 'Azion runs your code at the edge, close to users.'
-  },
-  {
-    value: 'pricing',
-    title: 'How does pricing work?',
-    body: 'Pay only for what you use, with no upfront cost.'
-  },
-  {
-    value: 'support',
-    title: 'Enterprise support',
-    body: 'Available on Business and Enterprise plans.'
-  }
-]
-
 /** @type {import('@storybook/vue3').Meta<typeof Accordion>} */
 const meta = {
   title: 'Components/Content/Accordion',
@@ -48,48 +34,10 @@ const meta = {
     },
     docs: {
       description: {
-        component: [
-          'A vertically stacked set of disclosure items: each item has a clickable header that expands or collapses its content panel. Use it to condense long content into scannable sections. Unlike `tab-view` (mutually-exclusive panels shown in place), an accordion can keep one item open at a time (`type="single"`) or several at once (`type="multiple"`), and its content expands inline below each header.',
-          '',
-          '## Usage',
-          '',
-          '```vue',
-          '<script setup>',
-          "import Accordion from '@aziontech/webkit/accordion'",
-          '</script>',
-          '',
-          '<template>',
-          '  <Accordion',
-          '    type="single"',
-          '    collapsible',
-          '    default-value="overview"',
-          '    size="medium"',
-          '    arrow-position="right"',
-          '  >',
-          '    <Accordion.Item value="overview">',
-          '      <Accordion.Trigger>What is Azion?</Accordion.Trigger>',
-          '      <Accordion.Content>Azion runs your code at the edge, close to users.</Accordion.Content>',
-          '    </Accordion.Item>',
-          '    <Accordion.Item value="pricing">',
-          '      <Accordion.Trigger>How does pricing work?</Accordion.Trigger>',
-          '      <Accordion.Content>Pay only for what you use, with no upfront cost.</Accordion.Content>',
-          '    </Accordion.Item>',
-          '    <Accordion.Item value="support" disabled>',
-          '      <Accordion.Trigger>Enterprise support</Accordion.Trigger>',
-          '      <Accordion.Content>Available on Business and Enterprise plans.</Accordion.Content>',
-          '    </Accordion.Item>',
-          '  </Accordion>',
-          '</template>',
-          '```'
-        ].join('\n')
-      },
-      source: {
-        type: 'dynamic',
-        excludeDecorators: true
+        component:
+          'A vertically stacked set of disclosure items: each item has a clickable header that expands or collapses its content panel. Use it to condense long content into scannable sections. Unlike `tab-view` (mutually-exclusive panels shown in place), an accordion can keep one item open at a time (`type="single"`) or several at once (`type="multiple"`), and its content expands inline below each header.'
       },
-      canvas: {
-        sourceState: 'shown'
-      }
+      canvas: { sourceState: 'shown' }
     }
   },
   argTypes: {
@@ -126,7 +74,7 @@ const meta = {
     size: {
       control: 'select',
       options: ['medium', 'large'],
-      description: 'Size token; affects header height, padding, and typography.',
+      description: 'Size token; affects header height and typography.',
       table: {
         category: 'props',
         type: { summary: "'medium' | 'large'" },
@@ -169,11 +117,26 @@ const meta = {
 
 export default meta
 
+const DEFAULT_MARKUP = `<Accordion type="single" collapsible default-value="overview" size="medium" arrow-position="right" class="w-full max-w-[40rem]">
+  <Accordion.Item value="overview">
+    <Accordion.Trigger>What is Azion?</Accordion.Trigger>
+    <Accordion.Content>Azion runs your code at the edge, close to users.</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="pricing">
+    <Accordion.Trigger>How does pricing work?</Accordion.Trigger>
+    <Accordion.Content>Pay only for what you use, with no upfront cost.</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="support">
+    <Accordion.Trigger>Enterprise support</Accordion.Trigger>
+    <Accordion.Content>Available on Business and Enterprise plans.</Accordion.Content>
+  </Accordion.Item>
+</Accordion>`
+
 const Template = (args) => ({
   components,
   setup() {
     const { onUpdateValue, onValueChange, ...props } = args
-    return { props, items: ITEMS, onUpdateValue, onValueChange }
+    return { props, onUpdateValue, onValueChange }
   },
   template: `
     <Accordion
@@ -182,9 +145,17 @@ const Template = (args) => ({
       @update:value="onUpdateValue"
       @value-change="onValueChange"
     >
-      <AccordionItem v-for="item in items" :key="item.value" :value="item.value">
-        <AccordionTrigger>{{ item.title }}</AccordionTrigger>
-        <AccordionContent>{{ item.body }}</AccordionContent>
+      <AccordionItem value="overview">
+        <AccordionTrigger>What is Azion?</AccordionTrigger>
+        <AccordionContent>Azion runs your code at the edge, close to users.</AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="pricing">
+        <AccordionTrigger>How does pricing work?</AccordionTrigger>
+        <AccordionContent>Pay only for what you use, with no upfront cost.</AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="support">
+        <AccordionTrigger>Enterprise support</AccordionTrigger>
+        <AccordionContent>Available on Business and Enterprise plans.</AccordionContent>
       </AccordionItem>
     </Accordion>
   `
@@ -198,30 +169,59 @@ export const Default = {
     docs: {
       description: {
         story: 'Single-mode accordion with one item open via `default-value`.'
-      }
+      },
+      source: { code: toSfc(IMPORT, DEFAULT_MARKUP) }
     }
   }
 }
 
+const SIZES_MARKUP = `<div class="flex flex-col gap-8 w-full max-w-[40rem]">
+  <Accordion type="single" collapsible default-value="overview" size="medium">
+    <Accordion.Item value="overview">
+      <Accordion.Trigger>What is Azion?</Accordion.Trigger>
+      <Accordion.Content>Azion runs your code at the edge, close to users.</Accordion.Content>
+    </Accordion.Item>
+    <Accordion.Item value="pricing">
+      <Accordion.Trigger>How does pricing work?</Accordion.Trigger>
+      <Accordion.Content>Pay only for what you use, with no upfront cost.</Accordion.Content>
+    </Accordion.Item>
+  </Accordion>
+  <Accordion type="single" collapsible default-value="overview" size="large">
+    <Accordion.Item value="overview">
+      <Accordion.Trigger>What is Azion?</Accordion.Trigger>
+      <Accordion.Content>Azion runs your code at the edge, close to users.</Accordion.Content>
+    </Accordion.Item>
+    <Accordion.Item value="pricing">
+      <Accordion.Trigger>How does pricing work?</Accordion.Trigger>
+      <Accordion.Content>Pay only for what you use, with no upfront cost.</Accordion.Content>
+    </Accordion.Item>
+  </Accordion>
+</div>`
+
 /** @type {import('@storybook/vue3').StoryObj<typeof Accordion>} */
 export const Sizes = {
   render: () => ({
     components,
-    setup() {
-      return { items: ITEMS }
-    },
     template: `
       <div class="flex flex-col gap-8 w-full max-w-[40rem]">
         <Accordion type="single" collapsible default-value="overview" size="medium">
-          <AccordionItem v-for="item in items" :key="item.value" :value="item.value">
-            <AccordionTrigger>{{ item.title }}</AccordionTrigger>
-            <AccordionContent>{{ item.body }}</AccordionContent>
+          <AccordionItem value="overview">
+            <AccordionTrigger>What is Azion?</AccordionTrigger>
+            <AccordionContent>Azion runs your code at the edge, close to users.</AccordionContent>
+          </AccordionItem>
+          <AccordionItem value="pricing">
+            <AccordionTrigger>How does pricing work?</AccordionTrigger>
+            <AccordionContent>Pay only for what you use, with no upfront cost.</AccordionContent>
           </AccordionItem>
         </Accordion>
         <Accordion type="single" collapsible default-value="overview" size="large">
-          <AccordionItem v-for="item in items" :key="item.value" :value="item.value">
-            <AccordionTrigger>{{ item.title }}</AccordionTrigger>
-            <AccordionContent>{{ item.body }}</AccordionContent>
+          <AccordionItem value="overview">
+            <AccordionTrigger>What is Azion?</AccordionTrigger>
+            <AccordionContent>Azion runs your code at the edge, close to users.</AccordionContent>
+          </AccordionItem>
+          <AccordionItem value="pricing">
+            <AccordionTrigger>How does pricing work?</AccordionTrigger>
+            <AccordionContent>Pay only for what you use, with no upfront cost.</AccordionContent>
           </AccordionItem>
         </Accordion>
       </div>
@@ -229,30 +229,60 @@ export const Sizes = {
   }),
   parameters: {
     docs: {
-      description: { story: '`medium` and `large` sizes side by side.' }
+      description: { story: '`medium` and `large` sizes side by side.' },
+      controls: { disable: true },
+      source: { code: toSfc(IMPORT, SIZES_MARKUP) }
     }
   }
 }
 
+const ARROW_MARKUP = `<div class="flex flex-col gap-8 w-full max-w-[40rem]">
+  <Accordion type="single" collapsible default-value="overview" arrow-position="right">
+    <Accordion.Item value="overview">
+      <Accordion.Trigger>What is Azion?</Accordion.Trigger>
+      <Accordion.Content>Azion runs your code at the edge, close to users.</Accordion.Content>
+    </Accordion.Item>
+    <Accordion.Item value="pricing">
+      <Accordion.Trigger>How does pricing work?</Accordion.Trigger>
+      <Accordion.Content>Pay only for what you use, with no upfront cost.</Accordion.Content>
+    </Accordion.Item>
+  </Accordion>
+  <Accordion type="single" collapsible default-value="overview" arrow-position="left">
+    <Accordion.Item value="overview">
+      <Accordion.Trigger>What is Azion?</Accordion.Trigger>
+      <Accordion.Content>Azion runs your code at the edge, close to users.</Accordion.Content>
+    </Accordion.Item>
+    <Accordion.Item value="pricing">
+      <Accordion.Trigger>How does pricing work?</Accordion.Trigger>
+      <Accordion.Content>Pay only for what you use, with no upfront cost.</Accordion.Content>
+    </Accordion.Item>
+  </Accordion>
+</div>`
+
 /** @type {import('@storybook/vue3').StoryObj<typeof Accordion>} */
 export const ArrowPosition = {
   render: () => ({
     components,
-    setup() {
-      return { items: ITEMS }
-    },
     template: `
       <div class="flex flex-col gap-8 w-full max-w-[40rem]">
         <Accordion type="single" collapsible default-value="overview" arrow-position="right">
-          <AccordionItem v-for="item in items" :key="item.value" :value="item.value">
-            <AccordionTrigger>{{ item.title }}</AccordionTrigger>
-            <AccordionContent>{{ item.body }}</AccordionContent>
+          <AccordionItem value="overview">
+            <AccordionTrigger>What is Azion?</AccordionTrigger>
+            <AccordionContent>Azion runs your code at the edge, close to users.</AccordionContent>
+          </AccordionItem>
+          <AccordionItem value="pricing">
+            <AccordionTrigger>How does pricing work?</AccordionTrigger>
+            <AccordionContent>Pay only for what you use, with no upfront cost.</AccordionContent>
           </AccordionItem>
         </Accordion>
         <Accordion type="single" collapsible default-value="overview" arrow-position="left">
-          <AccordionItem v-for="item in items" :key="item.value" :value="item.value">
-            <AccordionTrigger>{{ item.title }}</AccordionTrigger>
-            <AccordionContent>{{ item.body }}</AccordionContent>
+          <AccordionItem value="overview">
+            <AccordionTrigger>What is Azion?</AccordionTrigger>
+            <AccordionContent>Azion runs your code at the edge, close to users.</AccordionContent>
+          </AccordionItem>
+          <AccordionItem value="pricing">
+            <AccordionTrigger>How does pricing work?</AccordionTrigger>
+            <AccordionContent>Pay only for what you use, with no upfront cost.</AccordionContent>
           </AccordionItem>
         </Accordion>
       </div>
@@ -260,51 +290,95 @@ export const ArrowPosition = {
   }),
   parameters: {
     docs: {
-      description: { story: '`right` and `left` chevron placement side by side.' }
+      description: { story: '`right` and `left` chevron placement side by side.' },
+      controls: { disable: true },
+      source: { code: toSfc(IMPORT, ARROW_MARKUP) }
     }
   }
 }
 
+const DISABLED_MARKUP = `<Accordion type="single" collapsible default-value="overview" class="w-full max-w-[40rem]">
+  <Accordion.Item value="overview">
+    <Accordion.Trigger>What is Azion?</Accordion.Trigger>
+    <Accordion.Content>Azion runs your code at the edge, close to users.</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="pricing" disabled>
+    <Accordion.Trigger>How does pricing work?</Accordion.Trigger>
+    <Accordion.Content>Pay only for what you use, with no upfront cost.</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="support">
+    <Accordion.Trigger>Enterprise support</Accordion.Trigger>
+    <Accordion.Content>Available on Business and Enterprise plans.</Accordion.Content>
+  </Accordion.Item>
+</Accordion>`
+
 /** @type {import('@storybook/vue3').StoryObj<typeof Accordion>} */
 export const Disabled = {
   render: () => ({
     components,
-    setup() {
-      return { items: ITEMS }
-    },
     template: `
       <Accordion type="single" collapsible default-value="overview" class="w-full max-w-[40rem]">
-        <AccordionItem
-          v-for="item in items"
-          :key="item.value"
-          :value="item.value"
-          :disabled="item.value === 'pricing'"
-        >
-          <AccordionTrigger>{{ item.title }}</AccordionTrigger>
-          <AccordionContent>{{ item.body }}</AccordionContent>
+        <AccordionItem value="overview">
+          <AccordionTrigger>What is Azion?</AccordionTrigger>
+          <AccordionContent>Azion runs your code at the edge, close to users.</AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="pricing" disabled>
+          <AccordionTrigger>How does pricing work?</AccordionTrigger>
+          <AccordionContent>Pay only for what you use, with no upfront cost.</AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="support">
+          <AccordionTrigger>Enterprise support</AccordionTrigger>
+          <AccordionContent>Available on Business and Enterprise plans.</AccordionContent>
         </AccordionItem>
       </Accordion>
     `
   }),
   parameters: {
     docs: {
-      description: { story: 'The middle item carries the per-item `disabled` prop and cannot toggle.' }
+      description: {
+        story: 'The middle item carries the per-item `disabled` prop and cannot toggle.'
+      },
+      controls: { disable: true },
+      source: { code: toSfc(IMPORT, DISABLED_MARKUP) }
     }
   }
 }
 
+const MULTIPLE_MARKUP = `<Accordion type="multiple" :default-value="['overview', 'pricing']" class="w-full max-w-[40rem]">
+  <Accordion.Item value="overview">
+    <Accordion.Trigger>What is Azion?</Accordion.Trigger>
+    <Accordion.Content>Azion runs your code at the edge, close to users.</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="pricing">
+    <Accordion.Trigger>How does pricing work?</Accordion.Trigger>
+    <Accordion.Content>Pay only for what you use, with no upfront cost.</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="support">
+    <Accordion.Trigger>Enterprise support</Accordion.Trigger>
+    <Accordion.Content>Available on Business and Enterprise plans.</Accordion.Content>
+  </Accordion.Item>
+</Accordion>`
+
 /** @type {import('@storybook/vue3').StoryObj<typeof Accordion>} */
 export const Multiple = {
   render: () => ({
     components,
     setup() {
-      return { items: ITEMS, openValues: ['overview', 'pricing'] }
+      return { openValues: ['overview', 'pricing'] }
     },
     template: `
       <Accordion type="multiple" :default-value="openValues" class="w-full max-w-[40rem]">
-        <AccordionItem v-for="item in items" :key="item.value" :value="item.value">
-          <AccordionTrigger>{{ item.title }}</AccordionTrigger>
-          <AccordionContent>{{ item.body }}</AccordionContent>
+        <AccordionItem value="overview">
+          <AccordionTrigger>What is Azion?</AccordionTrigger>
+          <AccordionContent>Azion runs your code at the edge, close to users.</AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="pricing">
+          <AccordionTrigger>How does pricing work?</AccordionTrigger>
+          <AccordionContent>Pay only for what you use, with no upfront cost.</AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="support">
+          <AccordionTrigger>Enterprise support</AccordionTrigger>
+          <AccordionContent>Available on Business and Enterprise plans.</AccordionContent>
         </AccordionItem>
       </Accordion>
     `
@@ -313,7 +387,9 @@ export const Multiple = {
     docs: {
       description: {
         story: '`type="multiple"` with two items open at once via an array `default-value`.'
-      }
+      },
+      controls: { disable: true },
+      source: { code: toSfc(IMPORT, MULTIPLE_MARKUP) }
     }
   }
 }