From 2c8f3a3f3489568a24d5d914729d984cd6d1fae8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Wed, 1 Jul 2026 11:16:42 -0300
Subject: [PATCH 01/11] [NO-ISSUE] feat: add InputGroup composition component
 with Addon sub-component

Implements Figma node 3714-10802. Composition pattern with compound API:
InputGroup root + InputGroup.Addon sub-component. States driven by
data-invalid / data-required attributes (danger border when invalid alone,
warning border when invalid + required). Provides InputGroupContextKey via
inject/provide so future input primitives can render borderless inside the
group in a follow-up PR.
---
 .specs/input-group.md                         | 190 ++++++++++++++++++
 .../inputs/input-group/InputGroup.stories.js  | 171 ++++++++++++++++
 packages/webkit/package.json                  |   3 +
 .../components/inputs/input-group/index.ts    |   4 +
 .../inputs/input-group/injection-key.ts       |   3 +
 .../input-group-addon/input-group-addon.vue   |  22 ++
 .../inputs/input-group/input-group.vue        |  43 ++++
 7 files changed, 436 insertions(+)
 create mode 100644 .specs/input-group.md
 create mode 100644 apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
 create mode 100644 packages/webkit/src/components/inputs/input-group/index.ts
 create mode 100644 packages/webkit/src/components/inputs/input-group/injection-key.ts
 create mode 100644 packages/webkit/src/components/inputs/input-group/input-group-addon/input-group-addon.vue
 create mode 100644 packages/webkit/src/components/inputs/input-group/input-group.vue

diff --git a/.specs/input-group.md b/.specs/input-group.md
new file mode 100644
index 00000000..13e56a36
--- /dev/null
+++ b/.specs/input-group.md
@@ -0,0 +1,190 @@
+---
+name: input-group
+category: inputs
+structure: composition
+status: implemented
+spec_version: 1
+figma:
+  url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3714-10802
+  node_id: 3714:10802
+checksum: e848fa74bfc0ed378b64c4e9d59672d2a9c6d2b800bafe95fb2b7ea0f74308f8
+created: 2026-07-01
+last_updated: 2026-07-01
+---
+
+# InputGroup — Component Spec
+
+## Purpose
+
+Container that flanks an input primitive with optional addons on either side (icon, static text, button), joined by vertical dividers, and reflects validation state on its border. Composed as `<InputGroup>` (root) plus `<InputGroup.Addon>` sub-components on the left, right, or both — the middle input goes in the root's default slot. Distinct from `field-*` components: `InputGroup` styles the input's *edges*; `field-*` wraps label + helper text.
+
+The root **provides** an injection key (`InputGroupContextKey`) that future revisions of `input-text` (and other input primitives) will `inject` to render borderless inside the group. Until that lands, the middle slot expects a raw `<input>` element styled with `w-full bg-transparent border-0 outline-none focus:ring-0 h-full px-[var(--spacing-md)] text-[color:var(--text-default)]` — this is the canonical middle-slot markup shown in Usage and stories.
+
+## Usage
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import InputGroup from '@aziontech/webkit/input-group'
+const value = ref('')
+</script>
+
+<template>
+  <InputGroup :invalid="false">
+    <InputGroup.Addon>https://</InputGroup.Addon>
+    <input
+      v-model="value"
+      placeholder="domain"
+      class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-[color:var(--text-default)]"
+    />
+    <InputGroup.Addon>.com</InputGroup.Addon>
+  </InputGroup>
+</template>
+```
+
+Tree-shaking alternative — standalone root + sub-component, no compound `Object.assign` pulled in:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import InputGroup from '@aziontech/webkit/input-group-root'
+import InputGroupAddon from '@aziontech/webkit/input-group-addon'
+const value = ref('')
+</script>
+
+<template>
+  <InputGroup>
+    <InputGroupAddon>https://</InputGroupAddon>
+    <input
+      v-model="value"
+      placeholder="domain"
+      class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-[color:var(--text-default)]"
+    />
+  </InputGroup>
+</template>
+```
+
+## Sub-components
+
+- `input-group-addon/input-group-addon.vue` — Left/right addon slot. Position is determined by source order relative to the middle input, not by a prop. Exposes a `default` slot (scope: none) for the addon content (icon, static text, or a `<Button>`). Renders with `bg-[var(--bg-canvas)]` surface distinct from the middle field, `px-[var(--spacing-md)]`, `text-label-sm`, `text-[color:var(--text-muted)]`. The vertical seam between an addon and its neighbour is drawn by a CSS pseudo-border on the addon itself (`[&:not(:last-child)]:border-r [&:not(:first-child)]:border-l border-[var(--border-default)]`) — no `<Divider>` element or v-node inspection needed.
+
+Resulting layout:
+
+```
+packages/webkit/src/components/inputs/input-group/
+├── input-group.vue
+├── injection-key.ts                    (exports InputGroupContextKey symbol; future primitives inject to detect nesting)
+├── index.ts                            (Object.assign(InputGroup, { Addon: InputGroupAddon }))
+└── input-group-addon/
+    └── input-group-addon.vue
+```
+
+Compound file (`index.ts`):
+
+```ts
+import InputGroup from './input-group.vue'
+import InputGroupAddon from './input-group-addon/input-group-addon.vue'
+export default Object.assign(InputGroup, { Addon: InputGroupAddon })
+```
+
+## Props
+
+Root (`InputGroup`):
+
+| Prop | Type | Default | Required | JSDoc |
+|---|---|---|---|---|
+| `invalid` | `boolean` | `false` | no | Renders the error border. When `required` is also `true`, the border uses the warning color instead of danger. Also sets `aria-invalid="true"` on the root. |
+| `required` | `boolean` | `false` | no | Semantic marker for a required field. Combined with `invalid=true`, switches the border color to warning. Sets `aria-required="true"` on the root. |
+
+Sub-component (`InputGroup.Addon`) has no props.
+
+## Events
+
+| _none_ | — | — |
+
+## Slots
+
+| Slot | Scope | Notes |
+|---|---|---|
+| `default` | — | Middle content — a raw `<input>` element in source order, optionally flanked by `<InputGroup.Addon>` siblings. `InputGroup.Addon` itself exposes a `default` slot that receives the addon content (icon, static text, or a `<Button>`); it is documented in the Sub-components section, not here. |
+
+## States
+
+- Visual states on root: `default`, `invalid`, `invalid + required`
+- `data-invalid` mirrors the `invalid` prop
+- `data-required` mirrors the `required` prop
+- `aria-invalid="true"` when `invalid`
+- `aria-required="true"` when `required`
+- Focus and hover states belong to the inner input primitive (not the group), which retains its own focus ring inside the middle slot
+
+## Motion & Animations
+
+_none_
+
+## Tokens
+
+| Region | Token (DESIGN.md) |
+|---|---|
+| root surface | `var(--bg-surface)` |
+| root border (default) | `var(--border-default)` |
+| root border (invalid, not required) | `var(--danger-border)` |
+| root border (invalid + required) | `var(--warning-border)` |
+| root border width | `border` (Tailwind utility) |
+| root shape | `var(--shape-elements)` |
+| root height | `h-8` (Tailwind utility) |
+| addon surface | `var(--bg-canvas)` |
+| addon text | `var(--text-muted)` |
+| addon padding.x | `var(--spacing-md)` |
+| addon typography | `.text-label-sm` |
+| addon seam (vertical border) | `var(--border-default)` (as `border-r`/`border-l` on the addon) |
+
+## Theme gaps
+
+| Figma variable | Temporary primitive | Follow-up |
+|---|---|---|
+| _none_ | — | — |
+
+## Accessibility (WCAG 2.1 AA)
+
+- Visible focus: not on the group root — the wrapped input primitive owns its own `focus-visible:ring-*`. The group does not steal focus, does not add `tabindex`.
+- Keyboard map: `Tab` moves through the addon interactive content (if any) and the middle input, in DOM order. No custom keybindings on the group.
+- ARIA: root uses `role="group"`; `aria-invalid` and `aria-required` reflect the props. The inner input keeps its own `aria-*` — the group does not duplicate.
+- Contrast ≥4.5:1 for addon text against `var(--bg-canvas)`; ≥3:1 for the border in every state.
+- No motion introduced by the group — `motion-reduce` is a non-concern here.
+- Touch target ≥32×32 px for interactive addon content (matches root height `var(--h-8)`).
+
+## Stories (Storybook)
+
+- Default — root with a middle `<InputText>` and no addons.
+- WithLeftAddon — one `<InputGroup.Addon>` before the input (e.g. `https://`).
+- WithRightAddon — one `<InputGroup.Addon>` after the input (e.g. `.com`).
+- BothAddons — an addon on each side.
+- Invalid — `invalid=true`, no `required` (danger border).
+- InvalidRequired — `invalid=true` and `required=true` (warning border).
+
+Justification for six stories (deviates from Default+Types+Sizes+state pattern): the component has no `kind` and no `size`, so `Types` and `Sizes` do not apply. The four composition stories (Default, WithLeftAddon, WithRightAddon, BothAddons) document the sub-component's positional flexibility, which is the primary API surface. The two state stories exercise the two visually distinct border colors that hinge on the `invalid + required` combination — a non-obvious interaction that would otherwise be hidden.
+
+## 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 points at `index.ts`, and a standalone `./<name>-root` export points at the root `.vue` (tree-shaking). 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/inputs/input-group/InputGroup.stories.js b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
new file mode 100644
index 00000000..9564a672
--- /dev/null
+++ b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
@@ -0,0 +1,171 @@
+import InputGroup from '@aziontech/webkit/input-group'
+
+import { toSfc } from '../../../_shared/story-source'
+
+const IMPORT = "import InputGroup from '@aziontech/webkit/input-group'"
+
+const MIDDLE_INPUT =
+  '<input placeholder="domain" class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-[color:var(--text-default)]" />'
+
+/** @type {import('@storybook/vue3').Meta<typeof InputGroup>} */
+const meta = {
+  title: 'Components/Inputs/InputGroup',
+  component: InputGroup,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          "Container that flanks an input primitive with optional addons on either side, joined by vertical dividers, and reflects validation state on its border. Composed as `<InputGroup>` (root) plus `<InputGroup.Addon>` sub-components on the left, right, or both — the middle input goes in the root's default slot."
+      },
+      canvas: { sourceState: 'shown' }
+    }
+  },
+  argTypes: {
+    invalid: {
+      control: 'boolean',
+      description:
+        'Renders the error border. When `required` is also `true`, the border uses the warning color instead of danger. Also sets `aria-invalid="true"` on the root.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    required: {
+      control: 'boolean',
+      description:
+        'Semantic marker for a required field. Combined with `invalid=true`, switches the border color to warning. Sets `aria-required="true"` on the root.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    }
+  },
+  args: {
+    invalid: false,
+    required: false
+  }
+}
+
+export default meta
+
+const Template = (args) => ({
+  components: { InputGroup },
+  setup() {
+    return { props: args }
+  },
+  template: `<InputGroup :invalid="props.invalid" :required="props.required">${MIDDLE_INPUT}</InputGroup>`
+})
+
+const DEFAULT_MARKUP = `<InputGroup>
+  ${MIDDLE_INPUT}
+</InputGroup>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
+export const Default = {
+  render: Template,
+  parameters: {
+    docs: {
+      description: { story: 'Root with only a raw `<input>` in the middle slot and no addons.' },
+      source: { code: toSfc(IMPORT, DEFAULT_MARKUP) }
+    }
+  }
+}
+
+const WITH_LEFT_ADDON_MARKUP = `<InputGroup>
+  <InputGroup.Addon>https://</InputGroup.Addon>
+  ${MIDDLE_INPUT}
+</InputGroup>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
+export const WithLeftAddon = {
+  render: () => ({
+    components: { InputGroup },
+    template: WITH_LEFT_ADDON_MARKUP
+  }),
+  parameters: {
+    docs: {
+      controls: { disable: true },
+      description: { story: 'A single addon placed before the middle input.' },
+      source: { code: toSfc(IMPORT, WITH_LEFT_ADDON_MARKUP) }
+    }
+  }
+}
+
+const WITH_RIGHT_ADDON_MARKUP = `<InputGroup>
+  ${MIDDLE_INPUT}
+  <InputGroup.Addon>.com</InputGroup.Addon>
+</InputGroup>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
+export const WithRightAddon = {
+  render: () => ({
+    components: { InputGroup },
+    template: WITH_RIGHT_ADDON_MARKUP
+  }),
+  parameters: {
+    docs: {
+      controls: { disable: true },
+      description: { story: 'A single addon placed after the middle input.' },
+      source: { code: toSfc(IMPORT, WITH_RIGHT_ADDON_MARKUP) }
+    }
+  }
+}
+
+const BOTH_ADDONS_MARKUP = `<InputGroup>
+  <InputGroup.Addon>https://</InputGroup.Addon>
+  ${MIDDLE_INPUT}
+  <InputGroup.Addon>.com</InputGroup.Addon>
+</InputGroup>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
+export const BothAddons = {
+  render: () => ({
+    components: { InputGroup },
+    template: BOTH_ADDONS_MARKUP
+  }),
+  parameters: {
+    docs: {
+      controls: { disable: true },
+      description: { story: 'An addon on each side of the middle input.' },
+      source: { code: toSfc(IMPORT, BOTH_ADDONS_MARKUP) }
+    }
+  }
+}
+
+const INVALID_MARKUP = `<InputGroup :invalid="true">
+  <InputGroup.Addon>https://</InputGroup.Addon>
+  ${MIDDLE_INPUT}
+  <InputGroup.Addon>.com</InputGroup.Addon>
+</InputGroup>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
+export const Invalid = {
+  render: () => ({
+    components: { InputGroup },
+    template: INVALID_MARKUP
+  }),
+  parameters: {
+    docs: {
+      controls: { disable: true },
+      description: { story: 'Invalid state — root shows the danger border.' },
+      source: { code: toSfc(IMPORT, INVALID_MARKUP) }
+    }
+  }
+}
+
+const INVALID_REQUIRED_MARKUP = `<InputGroup :invalid="true" :required="true">
+  <InputGroup.Addon>https://</InputGroup.Addon>
+  ${MIDDLE_INPUT}
+  <InputGroup.Addon>.com</InputGroup.Addon>
+</InputGroup>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
+export const InvalidRequired = {
+  render: () => ({
+    components: { InputGroup },
+    template: INVALID_REQUIRED_MARKUP
+  }),
+  parameters: {
+    docs: {
+      controls: { disable: true },
+      description: { story: 'Invalid + required — root shows the warning border instead of danger.' },
+      source: { code: toSfc(IMPORT, INVALID_REQUIRED_MARKUP) }
+    }
+  }
+}
diff --git a/packages/webkit/package.json b/packages/webkit/package.json
index c275c5a9..2b458086 100644
--- a/packages/webkit/package.json
+++ b/packages/webkit/package.json
@@ -127,6 +127,9 @@
     "./progress-bar": "./src/components/feedback/progress-bar/progress-bar.vue",
     "./calendar": "./src/components/inputs/calendar/calendar.vue",
     "./input-text": "./src/components/inputs/input-text/input-text.vue",
+    "./input-group": "./src/components/inputs/input-group/index.ts",
+    "./input-group-root": "./src/components/inputs/input-group/input-group.vue",
+    "./input-group-addon": "./src/components/inputs/input-group/input-group-addon/input-group-addon.vue",
     "./input-number": "./src/components/inputs/input-number/input-number.vue",
     "./field-text": "./src/components/inputs/field-text/field-text.vue",
     "./helper-text": "./src/components/inputs/helper-text/helper-text.vue",
diff --git a/packages/webkit/src/components/inputs/input-group/index.ts b/packages/webkit/src/components/inputs/input-group/index.ts
new file mode 100644
index 00000000..5a59485b
--- /dev/null
+++ b/packages/webkit/src/components/inputs/input-group/index.ts
@@ -0,0 +1,4 @@
+import InputGroup from './input-group.vue'
+import InputGroupAddon from './input-group-addon/input-group-addon.vue'
+
+export default Object.assign(InputGroup, { Addon: InputGroupAddon })
diff --git a/packages/webkit/src/components/inputs/input-group/injection-key.ts b/packages/webkit/src/components/inputs/input-group/injection-key.ts
new file mode 100644
index 00000000..4d836de7
--- /dev/null
+++ b/packages/webkit/src/components/inputs/input-group/injection-key.ts
@@ -0,0 +1,3 @@
+import type { InjectionKey } from 'vue'
+
+export const InputGroupContextKey: InjectionKey<true> = Symbol('InputGroupContext')
diff --git a/packages/webkit/src/components/inputs/input-group/input-group-addon/input-group-addon.vue b/packages/webkit/src/components/inputs/input-group/input-group-addon/input-group-addon.vue
new file mode 100644
index 00000000..a92fce24
--- /dev/null
+++ b/packages/webkit/src/components/inputs/input-group/input-group-addon/input-group-addon.vue
@@ -0,0 +1,22 @@
+<script setup lang="ts">
+  import { computed, useAttrs } from 'vue'
+
+  defineOptions({ name: 'InputGroupAddon', inheritAttrs: false })
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const attrs = useAttrs()
+  const testId = computed(() => (attrs['data-testid'] as string | undefined) ?? 'input-group-addon')
+</script>
+
+<template>
+  <div
+    v-bind="$attrs"
+    :data-testid="testId"
+    class="flex items-center self-stretch shrink-0 bg-[var(--bg-canvas)] px-[var(--spacing-md)] text-label-sm text-[color:var(--text-muted)] [&:not(:last-child)]:border-r [&:not(:first-child)]:border-l border-[var(--border-default)]"
+  >
+    <slot />
+  </div>
+</template>
diff --git a/packages/webkit/src/components/inputs/input-group/input-group.vue b/packages/webkit/src/components/inputs/input-group/input-group.vue
new file mode 100644
index 00000000..8ef0bf29
--- /dev/null
+++ b/packages/webkit/src/components/inputs/input-group/input-group.vue
@@ -0,0 +1,43 @@
+<script setup lang="ts">
+  import { computed, provide, useAttrs } from 'vue'
+
+  import { InputGroupContextKey } from './injection-key'
+
+  defineOptions({ name: 'InputGroup', inheritAttrs: false })
+
+  export interface Props {
+    /** Renders the error border. When `required` is also `true`, the border uses the warning color instead of danger. Also sets `aria-invalid="true"` on the root. */
+    invalid?: boolean
+    /** Semantic marker for a required field. Combined with `invalid=true`, switches the border color to warning. Sets `aria-required="true"` on the root. */
+    required?: boolean
+  }
+
+  const props = withDefaults(defineProps<Props>(), {
+    invalid: false,
+    required: false
+  })
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const attrs = useAttrs()
+  const testId = computed(() => (attrs['data-testid'] as string | undefined) ?? 'input-group')
+
+  provide(InputGroupContextKey, true)
+</script>
+
+<template>
+  <div
+    v-bind="$attrs"
+    role="group"
+    :data-testid="testId"
+    :data-invalid="props.invalid || null"
+    :data-required="props.required || null"
+    :aria-invalid="props.invalid ? 'true' : undefined"
+    :aria-required="props.required ? 'true' : undefined"
+    class="relative inline-flex items-center h-8 overflow-hidden rounded-[var(--shape-elements)] border border-[var(--border-default)] bg-[var(--bg-surface)] data-[invalid]:border-[var(--danger-border)] data-[invalid]:data-[required]:border-[var(--warning-border)]"
+  >
+    <slot />
+  </div>
+</template>

From f5485238d13fce9f71e27717a65b8defb36a9e42 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Wed, 1 Jul 2026 11:35:52 -0300
Subject: [PATCH 02/11] [NO-ISSUE] refactor: align InputGroup border/focus
 chrome with input-text pattern

Independent invalid/required semantics (invalid -> danger, required ->
warning), focus-within ring on the group root, hover border-strong, and
transition-colors with motion-reduce fallback. Spec States/Motion/Tokens/
Accessibility sections updated to match; checksum refreshed.
---
 .specs/input-group.md                         | 35 +++++++++++--------
 .../inputs/input-group/input-group.vue        |  2 +-
 2 files changed, 22 insertions(+), 15 deletions(-)

diff --git a/.specs/input-group.md b/.specs/input-group.md
index 13e56a36..0ce79f19 100644
--- a/.specs/input-group.md
+++ b/.specs/input-group.md
@@ -7,7 +7,7 @@ spec_version: 1
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3714-10802
   node_id: 3714:10802
-checksum: e848fa74bfc0ed378b64c4e9d59672d2a9c6d2b800bafe95fb2b7ea0f74308f8
+checksum: 793c77a1aead7abe65b9521b3c8eec6df432f2ffe5a3ee2fd98d57f12eb0aec8
 created: 2026-07-01
 last_updated: 2026-07-01
 ---
@@ -110,16 +110,20 @@ Sub-component (`InputGroup.Addon`) has no props.
 
 ## States
 
-- Visual states on root: `default`, `invalid`, `invalid + required`
-- `data-invalid` mirrors the `invalid` prop
-- `data-required` mirrors the `required` prop
-- `aria-invalid="true"` when `invalid`
-- `aria-required="true"` when `required`
-- Focus and hover states belong to the inner input primitive (not the group), which retains its own focus ring inside the middle slot
+- Visual states on root: `default`, `hover`, `focus-within`, `invalid`, `required`
+- `data-invalid` mirrors the `invalid` prop; sets `aria-invalid="true"`
+- `data-required` mirrors the `required` prop; sets `aria-required="true"`
+- Border semantics mirror `input-text` (independent, not compound):
+  - `data-invalid` → `var(--danger-border)`
+  - `data-required` → `var(--warning-border)`
+- Hover (only when not focus-within and neither invalid nor required): `border-[var(--border-strong)]`
+- Focus-within: 2-ring at `var(--ring-color)` with `var(--bg-canvas)` offset
 
 ## Motion & Animations
 
-_none_
+| Trigger | Animation / Transition | Token (see `.claude/docs/DESIGN.md` § Animations) | Reduced-motion fallback |
+|---|---|---|---|
+| hover / focus-within / invalid / required state change | `transition-colors duration-150 ease-out` | inline (matches catalog) | `motion-reduce:transition-none` |
 
 ## Tokens
 
@@ -127,11 +131,14 @@ _none_
 |---|---|
 | root surface | `var(--bg-surface)` |
 | root border (default) | `var(--border-default)` |
-| root border (invalid, not required) | `var(--danger-border)` |
-| root border (invalid + required) | `var(--warning-border)` |
+| root border (hover) | `var(--border-strong)` |
+| root border (invalid) | `var(--danger-border)` |
+| root border (required) | `var(--warning-border)` |
 | root border width | `border` (Tailwind utility) |
 | root shape | `var(--shape-elements)` |
 | root height | `h-8` (Tailwind utility) |
+| focus ring | `var(--ring-color)` |
+| focus ring offset | `var(--bg-canvas)` |
 | addon surface | `var(--bg-canvas)` |
 | addon text | `var(--text-muted)` |
 | addon padding.x | `var(--spacing-md)` |
@@ -146,12 +153,12 @@ _none_
 
 ## Accessibility (WCAG 2.1 AA)
 
-- Visible focus: not on the group root — the wrapped input primitive owns its own `focus-visible:ring-*`. The group does not steal focus, does not add `tabindex`.
-- Keyboard map: `Tab` moves through the addon interactive content (if any) and the middle input, in DOM order. No custom keybindings on the group.
+- Visible focus: the root shows a `focus-within` ring (`ring-2 ring-[var(--ring-color)] ring-offset-2 ring-offset-[var(--bg-canvas)]`) whenever any descendant (addon control or middle input) has focus. The middle input renders `focus:ring-0 outline-none` so the group's ring is the only visible focus indicator.
+- Keyboard map: `Tab` moves through the addon interactive content (if any) and the middle input in DOM order. No custom keybindings on the group.
 - ARIA: root uses `role="group"`; `aria-invalid` and `aria-required` reflect the props. The inner input keeps its own `aria-*` — the group does not duplicate.
 - Contrast ≥4.5:1 for addon text against `var(--bg-canvas)`; ≥3:1 for the border in every state.
-- No motion introduced by the group — `motion-reduce` is a non-concern here.
-- Touch target ≥32×32 px for interactive addon content (matches root height `var(--h-8)`).
+- Motion: color transitions on state changes are `duration-150 ease-out` and pair with `motion-reduce:transition-none`.
+- Touch target ≥32×32 px for interactive addon content (matches root height `h-8`).
 
 ## Stories (Storybook)
 
diff --git a/packages/webkit/src/components/inputs/input-group/input-group.vue b/packages/webkit/src/components/inputs/input-group/input-group.vue
index 8ef0bf29..6dd011b0 100644
--- a/packages/webkit/src/components/inputs/input-group/input-group.vue
+++ b/packages/webkit/src/components/inputs/input-group/input-group.vue
@@ -36,7 +36,7 @@
     :data-required="props.required || null"
     :aria-invalid="props.invalid ? 'true' : undefined"
     :aria-required="props.required ? 'true' : undefined"
-    class="relative inline-flex items-center h-8 overflow-hidden rounded-[var(--shape-elements)] border border-[var(--border-default)] bg-[var(--bg-surface)] data-[invalid]:border-[var(--danger-border)] data-[invalid]:data-[required]:border-[var(--warning-border)]"
+    class="relative inline-flex items-center w-full h-8 overflow-hidden rounded-[var(--shape-elements)] border border-[var(--border-default)] bg-[var(--bg-surface)] transition-colors duration-150 ease-out motion-reduce:transition-none [&:not(:focus-within):not([data-invalid]):not([data-required])]:hover:border-[var(--border-strong)] focus-within:outline-none focus-within:ring-2 focus-within:ring-[var(--ring-color)] focus-within:ring-offset-2 focus-within:ring-offset-[var(--bg-canvas)] data-[invalid]:border-[var(--danger-border)] data-[required]:border-[var(--warning-border)]"
   >
     <slot />
   </div>

From 764ab843318abc0552165a14f151aea4b5ec1070 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Wed, 1 Jul 2026 11:39:37 -0300
Subject: [PATCH 03/11] [NO-ISSUE] fix: apply text-label-sm to InputGroup
 middle input to match addons

The stock <input> in the middle slot was rendering at browser default
(~16px) while the addons use text-label-sm (12px), producing a size
mismatch. Add text-label-sm + placeholder:text-[var(--text-muted)] so the
middle input matches both the addons and input-text's inner input font.
Spec and stories updated together; checksum refreshed.
---
 .specs/input-group.md                                     | 8 ++++----
 .../components/inputs/input-group/InputGroup.stories.js   | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.specs/input-group.md b/.specs/input-group.md
index 0ce79f19..e7362051 100644
--- a/.specs/input-group.md
+++ b/.specs/input-group.md
@@ -7,7 +7,7 @@ spec_version: 1
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3714-10802
   node_id: 3714:10802
-checksum: 793c77a1aead7abe65b9521b3c8eec6df432f2ffe5a3ee2fd98d57f12eb0aec8
+checksum: ee0699730149ef04727ebf10b4c6bd8ef6d93f157a3fab533524a0c741e3d873
 created: 2026-07-01
 last_updated: 2026-07-01
 ---
@@ -18,7 +18,7 @@ last_updated: 2026-07-01
 
 Container that flanks an input primitive with optional addons on either side (icon, static text, button), joined by vertical dividers, and reflects validation state on its border. Composed as `<InputGroup>` (root) plus `<InputGroup.Addon>` sub-components on the left, right, or both — the middle input goes in the root's default slot. Distinct from `field-*` components: `InputGroup` styles the input's *edges*; `field-*` wraps label + helper text.
 
-The root **provides** an injection key (`InputGroupContextKey`) that future revisions of `input-text` (and other input primitives) will `inject` to render borderless inside the group. Until that lands, the middle slot expects a raw `<input>` element styled with `w-full bg-transparent border-0 outline-none focus:ring-0 h-full px-[var(--spacing-md)] text-[color:var(--text-default)]` — this is the canonical middle-slot markup shown in Usage and stories.
+The root **provides** an injection key (`InputGroupContextKey`) that future revisions of `input-text` (and other input primitives) will `inject` to render borderless inside the group. Until that lands, the middle slot expects a raw `<input>` element styled with `w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]` — matching `input-text`'s inner font size (12px) and placeholder color. This is the canonical middle-slot markup shown in Usage and stories.
 
 ## Usage
 
@@ -35,7 +35,7 @@ const value = ref('')
     <input
       v-model="value"
       placeholder="domain"
-      class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-[color:var(--text-default)]"
+      class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]"
     />
     <InputGroup.Addon>.com</InputGroup.Addon>
   </InputGroup>
@@ -58,7 +58,7 @@ const value = ref('')
     <input
       v-model="value"
       placeholder="domain"
-      class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-[color:var(--text-default)]"
+      class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]"
     />
   </InputGroup>
 </template>
diff --git a/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
index 9564a672..e5fa225c 100644
--- a/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
+++ b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
@@ -5,7 +5,7 @@ import { toSfc } from '../../../_shared/story-source'
 const IMPORT = "import InputGroup from '@aziontech/webkit/input-group'"
 
 const MIDDLE_INPUT =
-  '<input placeholder="domain" class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-[color:var(--text-default)]" />'
+  '<input placeholder="domain" class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]" />'
 
 /** @type {import('@storybook/vue3').Meta<typeof InputGroup>} */
 const meta = {

From dabc1f73ca722b81d2b77c5cf41a4d50dabc30ad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Wed, 1 Jul 2026 11:40:52 -0300
Subject: [PATCH 04/11] [NO-ISSUE] fix: match middle input surface and text
 color to InputGroup addons
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The <input> in the middle slot inherited the group's --bg-surface and
used --text-default, making it read visually distinct from the addons
(which use --bg-canvas and --text-muted). Align both so left addon,
middle input, and right addon share the same dark fill and muted text —
one continuous surface behind the group's outer border.
---
 .specs/input-group.md                                     | 8 ++++----
 .../components/inputs/input-group/InputGroup.stories.js   | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.specs/input-group.md b/.specs/input-group.md
index e7362051..4bfb69dd 100644
--- a/.specs/input-group.md
+++ b/.specs/input-group.md
@@ -7,7 +7,7 @@ spec_version: 1
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3714-10802
   node_id: 3714:10802
-checksum: ee0699730149ef04727ebf10b4c6bd8ef6d93f157a3fab533524a0c741e3d873
+checksum: c659dbf1908636653f07361fde5af863079c8f03e0dba0f81b707cdb26bff9bc
 created: 2026-07-01
 last_updated: 2026-07-01
 ---
@@ -18,7 +18,7 @@ last_updated: 2026-07-01
 
 Container that flanks an input primitive with optional addons on either side (icon, static text, button), joined by vertical dividers, and reflects validation state on its border. Composed as `<InputGroup>` (root) plus `<InputGroup.Addon>` sub-components on the left, right, or both — the middle input goes in the root's default slot. Distinct from `field-*` components: `InputGroup` styles the input's *edges*; `field-*` wraps label + helper text.
 
-The root **provides** an injection key (`InputGroupContextKey`) that future revisions of `input-text` (and other input primitives) will `inject` to render borderless inside the group. Until that lands, the middle slot expects a raw `<input>` element styled with `w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]` — matching `input-text`'s inner font size (12px) and placeholder color. This is the canonical middle-slot markup shown in Usage and stories.
+The root **provides** an injection key (`InputGroupContextKey`) that future revisions of `input-text` (and other input primitives) will `inject` to render borderless inside the group. Until that lands, the middle slot expects a raw `<input>` element styled to visually match the addons — `bg-[var(--bg-canvas)]`, `text-label-sm`, `text-[var(--text-muted)]`, `placeholder:text-[var(--text-muted)]` — so left addon, middle input, and right addon read as one continuous dark surface with a single border and vertical seam. This is the canonical middle-slot markup shown in Usage and stories.
 
 ## Usage
 
@@ -35,7 +35,7 @@ const value = ref('')
     <input
       v-model="value"
       placeholder="domain"
-      class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]"
+      class="w-full h-full bg-[var(--bg-canvas)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-muted)] placeholder:text-[var(--text-muted)]"
     />
     <InputGroup.Addon>.com</InputGroup.Addon>
   </InputGroup>
@@ -58,7 +58,7 @@ const value = ref('')
     <input
       v-model="value"
       placeholder="domain"
-      class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]"
+      class="w-full h-full bg-[var(--bg-canvas)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-muted)] placeholder:text-[var(--text-muted)]"
     />
   </InputGroup>
 </template>
diff --git a/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
index e5fa225c..1e98d544 100644
--- a/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
+++ b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
@@ -5,7 +5,7 @@ import { toSfc } from '../../../_shared/story-source'
 const IMPORT = "import InputGroup from '@aziontech/webkit/input-group'"
 
 const MIDDLE_INPUT =
-  '<input placeholder="domain" class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]" />'
+  '<input placeholder="domain" class="w-full h-full bg-[var(--bg-canvas)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-muted)] placeholder:text-[var(--text-muted)]" />'
 
 /** @type {import('@storybook/vue3').Meta<typeof InputGroup>} */
 const meta = {

From 42dfc05856493e6c8500e3d2f96b09b931aafe5c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Wed, 1 Jul 2026 11:43:26 -0300
Subject: [PATCH 05/11] [NO-ISSUE] fix: middle input inherits --bg-surface so
 addons remain the darker islands

Previous commit incorrectly aligned the middle input's background to
--bg-canvas alongside the addons, flattening the group visually. The
Figma design has the addons as darker --bg-canvas islands on either
side of the middle input, which inherits the root's --bg-surface. Also
restores --text-default for the input's typed value while keeping the
muted placeholder. Spec and stories updated together; checksum
refreshed.
---
 .specs/input-group.md                                     | 8 ++++----
 .../components/inputs/input-group/InputGroup.stories.js   | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.specs/input-group.md b/.specs/input-group.md
index 4bfb69dd..66c03252 100644
--- a/.specs/input-group.md
+++ b/.specs/input-group.md
@@ -7,7 +7,7 @@ spec_version: 1
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3714-10802
   node_id: 3714:10802
-checksum: c659dbf1908636653f07361fde5af863079c8f03e0dba0f81b707cdb26bff9bc
+checksum: eddb1e3029c0f6c5f8e9b6adcc19476a812f4f0f392fb6dc8220e1b9c5eadc2c
 created: 2026-07-01
 last_updated: 2026-07-01
 ---
@@ -18,7 +18,7 @@ last_updated: 2026-07-01
 
 Container that flanks an input primitive with optional addons on either side (icon, static text, button), joined by vertical dividers, and reflects validation state on its border. Composed as `<InputGroup>` (root) plus `<InputGroup.Addon>` sub-components on the left, right, or both — the middle input goes in the root's default slot. Distinct from `field-*` components: `InputGroup` styles the input's *edges*; `field-*` wraps label + helper text.
 
-The root **provides** an injection key (`InputGroupContextKey`) that future revisions of `input-text` (and other input primitives) will `inject` to render borderless inside the group. Until that lands, the middle slot expects a raw `<input>` element styled to visually match the addons — `bg-[var(--bg-canvas)]`, `text-label-sm`, `text-[var(--text-muted)]`, `placeholder:text-[var(--text-muted)]` — so left addon, middle input, and right addon read as one continuous dark surface with a single border and vertical seam. This is the canonical middle-slot markup shown in Usage and stories.
+The root **provides** an injection key (`InputGroupContextKey`) that future revisions of `input-text` (and other input primitives) will `inject` to render borderless inside the group. Until that lands, the middle slot expects a raw `<input>` element styled to inherit the root's surface — `bg-[var(--bg-surface)]`, `text-label-sm`, `text-[var(--text-default)]`, `placeholder:text-[var(--text-muted)]` — so the middle blends with the group's own background while the addons stand out as darker `--bg-canvas` islands on either side (matches the Figma layout). This is the canonical middle-slot markup shown in Usage and stories.
 
 ## Usage
 
@@ -35,7 +35,7 @@ const value = ref('')
     <input
       v-model="value"
       placeholder="domain"
-      class="w-full h-full bg-[var(--bg-canvas)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-muted)] placeholder:text-[var(--text-muted)]"
+      class="w-full h-full bg-[var(--bg-surface)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]"
     />
     <InputGroup.Addon>.com</InputGroup.Addon>
   </InputGroup>
@@ -58,7 +58,7 @@ const value = ref('')
     <input
       v-model="value"
       placeholder="domain"
-      class="w-full h-full bg-[var(--bg-canvas)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-muted)] placeholder:text-[var(--text-muted)]"
+      class="w-full h-full bg-[var(--bg-surface)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]"
     />
   </InputGroup>
 </template>
diff --git a/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
index 1e98d544..97cdf61d 100644
--- a/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
+++ b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
@@ -5,7 +5,7 @@ import { toSfc } from '../../../_shared/story-source'
 const IMPORT = "import InputGroup from '@aziontech/webkit/input-group'"
 
 const MIDDLE_INPUT =
-  '<input placeholder="domain" class="w-full h-full bg-[var(--bg-canvas)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-muted)] placeholder:text-[var(--text-muted)]" />'
+  '<input placeholder="domain" class="w-full h-full bg-[var(--bg-surface)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]" />'
 
 /** @type {import('@storybook/vue3').Meta<typeof InputGroup>} */
 const meta = {

From fe6c09a2fe7947e35f656b14923a006487654c91 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Wed, 1 Jul 2026 11:45:48 -0300
Subject: [PATCH 06/11] [NO-ISSUE] fix: reliable addon seam via first:/last:
 variants and explicit border color

The previous [&:not(:last-child)]:border-r / [&:not(:first-child)]:border-l
pattern relied on Tailwind arbitrary variants that were not producing a
visible seam. Switch to Tailwind's built-in first: and last: variants
(first-child addon = left, gets border-r toward the input; last-child
addon = right, gets border-l toward the input) and force color
interpretation with border-[color:var(--border-default)] so the border
color applies unambiguously. Spec updated to match.
---
 .specs/input-group.md                                       | 6 +++---
 .../input-group/input-group-addon/input-group-addon.vue     | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.specs/input-group.md b/.specs/input-group.md
index 66c03252..e6c7ea73 100644
--- a/.specs/input-group.md
+++ b/.specs/input-group.md
@@ -7,7 +7,7 @@ spec_version: 1
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3714-10802
   node_id: 3714:10802
-checksum: eddb1e3029c0f6c5f8e9b6adcc19476a812f4f0f392fb6dc8220e1b9c5eadc2c
+checksum: 07c3bcfa12057e71fecb2b6061043fa7e26cf57e996233b2d843e8ebb97ed2f2
 created: 2026-07-01
 last_updated: 2026-07-01
 ---
@@ -66,7 +66,7 @@ const value = ref('')
 
 ## Sub-components
 
-- `input-group-addon/input-group-addon.vue` — Left/right addon slot. Position is determined by source order relative to the middle input, not by a prop. Exposes a `default` slot (scope: none) for the addon content (icon, static text, or a `<Button>`). Renders with `bg-[var(--bg-canvas)]` surface distinct from the middle field, `px-[var(--spacing-md)]`, `text-label-sm`, `text-[color:var(--text-muted)]`. The vertical seam between an addon and its neighbour is drawn by a CSS pseudo-border on the addon itself (`[&:not(:last-child)]:border-r [&:not(:first-child)]:border-l border-[var(--border-default)]`) — no `<Divider>` element or v-node inspection needed.
+- `input-group-addon/input-group-addon.vue` — Left/right addon slot. Position is determined by source order relative to the middle input, not by a prop. Exposes a `default` slot (scope: none) for the addon content (icon, static text, or a `<Button>`). Renders with `bg-[var(--bg-canvas)]` surface distinct from the middle field, `px-[var(--spacing-md)]`, `text-label-sm`, `text-[color:var(--text-muted)]`. The vertical seam between an addon and its neighbour is drawn by a CSS pseudo-border on the addon itself (`first:border-r last:border-l border-[color:var(--border-default)]`) — first-child addon (left) gets a right border toward the input; last-child addon (right) gets a left border toward the input. No `<Divider>` element or v-node inspection needed.
 
 Resulting layout:
 
@@ -143,7 +143,7 @@ Sub-component (`InputGroup.Addon`) has no props.
 | addon text | `var(--text-muted)` |
 | addon padding.x | `var(--spacing-md)` |
 | addon typography | `.text-label-sm` |
-| addon seam (vertical border) | `var(--border-default)` (as `border-r`/`border-l` on the addon) |
+| addon seam (vertical border) | `border-[color:var(--border-default)]` (as `first:border-r` / `last:border-l` on the addon) |
 
 ## Theme gaps
 
diff --git a/packages/webkit/src/components/inputs/input-group/input-group-addon/input-group-addon.vue b/packages/webkit/src/components/inputs/input-group/input-group-addon/input-group-addon.vue
index a92fce24..570140e6 100644
--- a/packages/webkit/src/components/inputs/input-group/input-group-addon/input-group-addon.vue
+++ b/packages/webkit/src/components/inputs/input-group/input-group-addon/input-group-addon.vue
@@ -15,7 +15,7 @@
   <div
     v-bind="$attrs"
     :data-testid="testId"
-    class="flex items-center self-stretch shrink-0 bg-[var(--bg-canvas)] px-[var(--spacing-md)] text-label-sm text-[color:var(--text-muted)] [&:not(:last-child)]:border-r [&:not(:first-child)]:border-l border-[var(--border-default)]"
+    class="flex items-center self-stretch shrink-0 bg-[var(--bg-canvas)] px-[var(--spacing-md)] text-label-sm text-[color:var(--text-muted)] first:border-r last:border-l border-[color:var(--border-default)]"
   >
     <slot />
   </div>

From 29ce979a5beafef3d782e04ea71f24dea10971b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Wed, 1 Jul 2026 12:07:26 -0300
Subject: [PATCH 07/11] [NO-ISSUE] refactor: replace InputGroup.Addon with
 explicit SlotLeft/SlotRight sub-components
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Instead of a single positional Addon sub-component that inferred left
or right from source order and drew its seam via first:/last: CSS
selectors, expose two explicit sub-components — InputGroupSlotLeft and
InputGroupSlotRight. Each hardcodes its own seam (SlotLeft: border-r,
SlotRight: border-l) and its own testid fallback, making position
unambiguous at the template level and eliminating any dependence on
CSS pseudo-class resolution.

Compound API becomes <InputGroup.SlotLeft>...</InputGroup.SlotLeft>
and <InputGroup.SlotRight>...</InputGroup.SlotRight>. The exports map
gains ./input-group-slot-left and ./input-group-slot-right in place
of ./input-group-addon. Spec, stories, and package.json all updated
together; checksum refreshed to aefeab87... No consumers have shipped
against the Addon API yet (pre-release, still on the open feat
branch).
---
 .specs/input-group.md                         | 60 +++++++++++--------
 .../inputs/input-group/InputGroup.stories.js  | 48 +++++++--------
 packages/webkit/package.json                  |  3 +-
 .../components/inputs/input-group/index.ts    |  8 ++-
 .../input-group-slot-left.vue}                |  8 ++-
 .../input-group-slot-right.vue                | 24 ++++++++
 6 files changed, 96 insertions(+), 55 deletions(-)
 rename packages/webkit/src/components/inputs/input-group/{input-group-addon/input-group-addon.vue => input-group-slot-left/input-group-slot-left.vue} (60%)
 create mode 100644 packages/webkit/src/components/inputs/input-group/input-group-slot-right/input-group-slot-right.vue

diff --git a/.specs/input-group.md b/.specs/input-group.md
index e6c7ea73..10382467 100644
--- a/.specs/input-group.md
+++ b/.specs/input-group.md
@@ -7,7 +7,7 @@ spec_version: 1
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3714-10802
   node_id: 3714:10802
-checksum: 07c3bcfa12057e71fecb2b6061043fa7e26cf57e996233b2d843e8ebb97ed2f2
+checksum: aefeab873440e20a00aef247dce731761b70679ac67e1dfacacaad56f04851eb
 created: 2026-07-01
 last_updated: 2026-07-01
 ---
@@ -16,7 +16,7 @@ last_updated: 2026-07-01
 
 ## Purpose
 
-Container that flanks an input primitive with optional addons on either side (icon, static text, button), joined by vertical dividers, and reflects validation state on its border. Composed as `<InputGroup>` (root) plus `<InputGroup.Addon>` sub-components on the left, right, or both — the middle input goes in the root's default slot. Distinct from `field-*` components: `InputGroup` styles the input's *edges*; `field-*` wraps label + helper text.
+Container that flanks an input primitive with optional slots on either side (icon, static text, button), joined by vertical dividers, and reflects validation state on its border. Composed as `<InputGroup>` (root) plus `<InputGroup.SlotLeft>` and `<InputGroup.SlotRight>` sub-components — the middle input goes in the root's default slot. Each side sub-component owns its own seam (`SlotLeft` renders `border-r`, `SlotRight` renders `border-l`) so there is no ambiguity in the CSS selectors and consumers cannot accidentally swap positions. Distinct from `field-*` components: `InputGroup` styles the input's *edges*; `field-*` wraps label + helper text.
 
 The root **provides** an injection key (`InputGroupContextKey`) that future revisions of `input-text` (and other input primitives) will `inject` to render borderless inside the group. Until that lands, the middle slot expects a raw `<input>` element styled to inherit the root's surface — `bg-[var(--bg-surface)]`, `text-label-sm`, `text-[var(--text-default)]`, `placeholder:text-[var(--text-muted)]` — so the middle blends with the group's own background while the addons stand out as darker `--bg-canvas` islands on either side (matches the Figma layout). This is the canonical middle-slot markup shown in Usage and stories.
 
@@ -31,42 +31,45 @@ const value = ref('')
 
 <template>
   <InputGroup :invalid="false">
-    <InputGroup.Addon>https://</InputGroup.Addon>
+    <InputGroup.SlotLeft>https://</InputGroup.SlotLeft>
     <input
       v-model="value"
       placeholder="domain"
       class="w-full h-full bg-[var(--bg-surface)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]"
     />
-    <InputGroup.Addon>.com</InputGroup.Addon>
+    <InputGroup.SlotRight>.com</InputGroup.SlotRight>
   </InputGroup>
 </template>
 ```
 
-Tree-shaking alternative — standalone root + sub-component, no compound `Object.assign` pulled in:
+Tree-shaking alternative — standalone root + sub-components, no compound `Object.assign` pulled in:
 
 ```vue
 <script setup>
 import { ref } from 'vue'
 import InputGroup from '@aziontech/webkit/input-group-root'
-import InputGroupAddon from '@aziontech/webkit/input-group-addon'
+import InputGroupSlotLeft from '@aziontech/webkit/input-group-slot-left'
+import InputGroupSlotRight from '@aziontech/webkit/input-group-slot-right'
 const value = ref('')
 </script>
 
 <template>
   <InputGroup>
-    <InputGroupAddon>https://</InputGroupAddon>
+    <InputGroupSlotLeft>https://</InputGroupSlotLeft>
     <input
       v-model="value"
       placeholder="domain"
       class="w-full h-full bg-[var(--bg-surface)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]"
     />
+    <InputGroupSlotRight>.com</InputGroupSlotRight>
   </InputGroup>
 </template>
 ```
 
 ## Sub-components
 
-- `input-group-addon/input-group-addon.vue` — Left/right addon slot. Position is determined by source order relative to the middle input, not by a prop. Exposes a `default` slot (scope: none) for the addon content (icon, static text, or a `<Button>`). Renders with `bg-[var(--bg-canvas)]` surface distinct from the middle field, `px-[var(--spacing-md)]`, `text-label-sm`, `text-[color:var(--text-muted)]`. The vertical seam between an addon and its neighbour is drawn by a CSS pseudo-border on the addon itself (`first:border-r last:border-l border-[color:var(--border-default)]`) — first-child addon (left) gets a right border toward the input; last-child addon (right) gets a left border toward the input. No `<Divider>` element or v-node inspection needed.
+- `input-group-slot-left/input-group-slot-left.vue` — Left-side slot. Exposes a `default` slot (scope: none) for the content (icon, static text, or a `<Button>`). Renders with `bg-[var(--bg-canvas)]`, `px-[var(--spacing-md)]`, `text-label-sm`, `text-[color:var(--text-muted)]`, and a hardcoded `border-r border-[color:var(--border-default)]` — the vertical seam toward the middle input.
+- `input-group-slot-right/input-group-slot-right.vue` — Right-side slot. Same styling as `SlotLeft` but with a hardcoded `border-l border-[color:var(--border-default)]` seam toward the middle input on the opposite side.
 
 Resulting layout:
 
@@ -74,17 +77,23 @@ Resulting layout:
 packages/webkit/src/components/inputs/input-group/
 ├── input-group.vue
 ├── injection-key.ts                    (exports InputGroupContextKey symbol; future primitives inject to detect nesting)
-├── index.ts                            (Object.assign(InputGroup, { Addon: InputGroupAddon }))
-└── input-group-addon/
-    └── input-group-addon.vue
+├── index.ts                            (Object.assign(InputGroup, { SlotLeft, SlotRight }))
+├── input-group-slot-left/
+│   └── input-group-slot-left.vue
+└── input-group-slot-right/
+    └── input-group-slot-right.vue
 ```
 
 Compound file (`index.ts`):
 
 ```ts
 import InputGroup from './input-group.vue'
-import InputGroupAddon from './input-group-addon/input-group-addon.vue'
-export default Object.assign(InputGroup, { Addon: InputGroupAddon })
+import InputGroupSlotLeft from './input-group-slot-left/input-group-slot-left.vue'
+import InputGroupSlotRight from './input-group-slot-right/input-group-slot-right.vue'
+export default Object.assign(InputGroup, {
+  SlotLeft: InputGroupSlotLeft,
+  SlotRight: InputGroupSlotRight
+})
 ```
 
 ## Props
@@ -96,7 +105,7 @@ Root (`InputGroup`):
 | `invalid` | `boolean` | `false` | no | Renders the error border. When `required` is also `true`, the border uses the warning color instead of danger. Also sets `aria-invalid="true"` on the root. |
 | `required` | `boolean` | `false` | no | Semantic marker for a required field. Combined with `invalid=true`, switches the border color to warning. Sets `aria-required="true"` on the root. |
 
-Sub-component (`InputGroup.Addon`) has no props.
+Sub-components (`InputGroup.SlotLeft`, `InputGroup.SlotRight`) have no props.
 
 ## Events
 
@@ -106,7 +115,7 @@ Sub-component (`InputGroup.Addon`) has no props.
 
 | Slot | Scope | Notes |
 |---|---|---|
-| `default` | — | Middle content — a raw `<input>` element in source order, optionally flanked by `<InputGroup.Addon>` siblings. `InputGroup.Addon` itself exposes a `default` slot that receives the addon content (icon, static text, or a `<Button>`); it is documented in the Sub-components section, not here. |
+| `default` | — | Middle content — a raw `<input>` element in source order, optionally preceded by `<InputGroup.SlotLeft>` and/or followed by `<InputGroup.SlotRight>`. Each side sub-component exposes its own `default` slot for the addon content (icon, static text, or a `<Button>`); those are documented in the Sub-components section, not here. |
 
 ## States
 
@@ -139,11 +148,12 @@ Sub-component (`InputGroup.Addon`) has no props.
 | root height | `h-8` (Tailwind utility) |
 | focus ring | `var(--ring-color)` |
 | focus ring offset | `var(--bg-canvas)` |
-| addon surface | `var(--bg-canvas)` |
-| addon text | `var(--text-muted)` |
-| addon padding.x | `var(--spacing-md)` |
-| addon typography | `.text-label-sm` |
-| addon seam (vertical border) | `border-[color:var(--border-default)]` (as `first:border-r` / `last:border-l` on the addon) |
+| SlotLeft / SlotRight surface | `var(--bg-canvas)` |
+| SlotLeft / SlotRight text | `var(--text-muted)` |
+| SlotLeft / SlotRight padding.x | `var(--spacing-md)` |
+| SlotLeft / SlotRight typography | `.text-label-sm` |
+| SlotLeft seam (vertical border) | `border-r border-[color:var(--border-default)]` |
+| SlotRight seam (vertical border) | `border-l border-[color:var(--border-default)]` |
 
 ## Theme gaps
 
@@ -162,14 +172,14 @@ Sub-component (`InputGroup.Addon`) has no props.
 
 ## Stories (Storybook)
 
-- Default — root with a middle `<InputText>` and no addons.
-- WithLeftAddon — one `<InputGroup.Addon>` before the input (e.g. `https://`).
-- WithRightAddon — one `<InputGroup.Addon>` after the input (e.g. `.com`).
-- BothAddons — an addon on each side.
+- Default — root with a middle input and no side slots.
+- WithSlotLeft — one `<InputGroup.SlotLeft>` before the input (e.g. `https://`).
+- WithSlotRight — one `<InputGroup.SlotRight>` after the input (e.g. `.com`).
+- BothSlots — a `SlotLeft` before and a `SlotRight` after the input.
 - Invalid — `invalid=true`, no `required` (danger border).
 - InvalidRequired — `invalid=true` and `required=true` (warning border).
 
-Justification for six stories (deviates from Default+Types+Sizes+state pattern): the component has no `kind` and no `size`, so `Types` and `Sizes` do not apply. The four composition stories (Default, WithLeftAddon, WithRightAddon, BothAddons) document the sub-component's positional flexibility, which is the primary API surface. The two state stories exercise the two visually distinct border colors that hinge on the `invalid + required` combination — a non-obvious interaction that would otherwise be hidden.
+Justification for six stories (deviates from Default+Types+Sizes+state pattern): the component has no `kind` and no `size`, so `Types` and `Sizes` do not apply. The four composition stories (Default, WithSlotLeft, WithSlotRight, BothSlots) document each side sub-component individually and combined — the primary API surface. The two state stories exercise the invalid and invalid+required border colors, which are the only non-obvious visual signals.
 
 ## Constraints — DO NOT
 
diff --git a/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
index 97cdf61d..2684997e 100644
--- a/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
+++ b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
@@ -17,7 +17,7 @@ const meta = {
     docs: {
       description: {
         component:
-          "Container that flanks an input primitive with optional addons on either side, joined by vertical dividers, and reflects validation state on its border. Composed as `<InputGroup>` (root) plus `<InputGroup.Addon>` sub-components on the left, right, or both — the middle input goes in the root's default slot."
+          "Container that flanks an input primitive with optional slots on either side, joined by vertical borders, and reflects validation state on its border. Composed as `<InputGroup>` (root) plus `<InputGroup.SlotLeft>` and `<InputGroup.SlotRight>` sub-components — the middle input goes in the root's default slot."
       },
       canvas: { sourceState: 'shown' }
     }
@@ -67,71 +67,71 @@ export const Default = {
   }
 }
 
-const WITH_LEFT_ADDON_MARKUP = `<InputGroup>
-  <InputGroup.Addon>https://</InputGroup.Addon>
+const WITH_SLOT_LEFT_MARKUP = `<InputGroup>
+  <InputGroup.SlotLeft>https://</InputGroup.SlotLeft>
   ${MIDDLE_INPUT}
 </InputGroup>`
 
 /** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
-export const WithLeftAddon = {
+export const WithSlotLeft = {
   render: () => ({
     components: { InputGroup },
-    template: WITH_LEFT_ADDON_MARKUP
+    template: WITH_SLOT_LEFT_MARKUP
   }),
   parameters: {
     docs: {
       controls: { disable: true },
-      description: { story: 'A single addon placed before the middle input.' },
-      source: { code: toSfc(IMPORT, WITH_LEFT_ADDON_MARKUP) }
+      description: { story: 'A single `<InputGroup.SlotLeft>` before the middle input.' },
+      source: { code: toSfc(IMPORT, WITH_SLOT_LEFT_MARKUP) }
     }
   }
 }
 
-const WITH_RIGHT_ADDON_MARKUP = `<InputGroup>
+const WITH_SLOT_RIGHT_MARKUP = `<InputGroup>
   ${MIDDLE_INPUT}
-  <InputGroup.Addon>.com</InputGroup.Addon>
+  <InputGroup.SlotRight>.com</InputGroup.SlotRight>
 </InputGroup>`
 
 /** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
-export const WithRightAddon = {
+export const WithSlotRight = {
   render: () => ({
     components: { InputGroup },
-    template: WITH_RIGHT_ADDON_MARKUP
+    template: WITH_SLOT_RIGHT_MARKUP
   }),
   parameters: {
     docs: {
       controls: { disable: true },
-      description: { story: 'A single addon placed after the middle input.' },
-      source: { code: toSfc(IMPORT, WITH_RIGHT_ADDON_MARKUP) }
+      description: { story: 'A single `<InputGroup.SlotRight>` after the middle input.' },
+      source: { code: toSfc(IMPORT, WITH_SLOT_RIGHT_MARKUP) }
     }
   }
 }
 
-const BOTH_ADDONS_MARKUP = `<InputGroup>
-  <InputGroup.Addon>https://</InputGroup.Addon>
+const BOTH_SLOTS_MARKUP = `<InputGroup>
+  <InputGroup.SlotLeft>https://</InputGroup.SlotLeft>
   ${MIDDLE_INPUT}
-  <InputGroup.Addon>.com</InputGroup.Addon>
+  <InputGroup.SlotRight>.com</InputGroup.SlotRight>
 </InputGroup>`
 
 /** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
-export const BothAddons = {
+export const BothSlots = {
   render: () => ({
     components: { InputGroup },
-    template: BOTH_ADDONS_MARKUP
+    template: BOTH_SLOTS_MARKUP
   }),
   parameters: {
     docs: {
       controls: { disable: true },
-      description: { story: 'An addon on each side of the middle input.' },
-      source: { code: toSfc(IMPORT, BOTH_ADDONS_MARKUP) }
+      description: { story: 'A `SlotLeft` and a `SlotRight` flanking the middle input.' },
+      source: { code: toSfc(IMPORT, BOTH_SLOTS_MARKUP) }
     }
   }
 }
 
 const INVALID_MARKUP = `<InputGroup :invalid="true">
-  <InputGroup.Addon>https://</InputGroup.Addon>
+  <InputGroup.SlotLeft>https://</InputGroup.SlotLeft>
   ${MIDDLE_INPUT}
-  <InputGroup.Addon>.com</InputGroup.Addon>
+  <InputGroup.SlotRight>.com</InputGroup.SlotRight>
 </InputGroup>`
 
 /** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
@@ -150,9 +150,9 @@ export const Invalid = {
 }
 
 const INVALID_REQUIRED_MARKUP = `<InputGroup :invalid="true" :required="true">
-  <InputGroup.Addon>https://</InputGroup.Addon>
+  <InputGroup.SlotLeft>https://</InputGroup.SlotLeft>
   ${MIDDLE_INPUT}
-  <InputGroup.Addon>.com</InputGroup.Addon>
+  <InputGroup.SlotRight>.com</InputGroup.SlotRight>
 </InputGroup>`
 
 /** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
diff --git a/packages/webkit/package.json b/packages/webkit/package.json
index 2b458086..11fdb4e5 100644
--- a/packages/webkit/package.json
+++ b/packages/webkit/package.json
@@ -129,7 +129,8 @@
     "./input-text": "./src/components/inputs/input-text/input-text.vue",
     "./input-group": "./src/components/inputs/input-group/index.ts",
     "./input-group-root": "./src/components/inputs/input-group/input-group.vue",
-    "./input-group-addon": "./src/components/inputs/input-group/input-group-addon/input-group-addon.vue",
+    "./input-group-slot-left": "./src/components/inputs/input-group/input-group-slot-left/input-group-slot-left.vue",
+    "./input-group-slot-right": "./src/components/inputs/input-group/input-group-slot-right/input-group-slot-right.vue",
     "./input-number": "./src/components/inputs/input-number/input-number.vue",
     "./field-text": "./src/components/inputs/field-text/field-text.vue",
     "./helper-text": "./src/components/inputs/helper-text/helper-text.vue",
diff --git a/packages/webkit/src/components/inputs/input-group/index.ts b/packages/webkit/src/components/inputs/input-group/index.ts
index 5a59485b..c683c752 100644
--- a/packages/webkit/src/components/inputs/input-group/index.ts
+++ b/packages/webkit/src/components/inputs/input-group/index.ts
@@ -1,4 +1,8 @@
 import InputGroup from './input-group.vue'
-import InputGroupAddon from './input-group-addon/input-group-addon.vue'
+import InputGroupSlotLeft from './input-group-slot-left/input-group-slot-left.vue'
+import InputGroupSlotRight from './input-group-slot-right/input-group-slot-right.vue'
 
-export default Object.assign(InputGroup, { Addon: InputGroupAddon })
+export default Object.assign(InputGroup, {
+  SlotLeft: InputGroupSlotLeft,
+  SlotRight: InputGroupSlotRight
+})
diff --git a/packages/webkit/src/components/inputs/input-group/input-group-addon/input-group-addon.vue b/packages/webkit/src/components/inputs/input-group/input-group-slot-left/input-group-slot-left.vue
similarity index 60%
rename from packages/webkit/src/components/inputs/input-group/input-group-addon/input-group-addon.vue
rename to packages/webkit/src/components/inputs/input-group/input-group-slot-left/input-group-slot-left.vue
index 570140e6..dd3b621a 100644
--- a/packages/webkit/src/components/inputs/input-group/input-group-addon/input-group-addon.vue
+++ b/packages/webkit/src/components/inputs/input-group/input-group-slot-left/input-group-slot-left.vue
@@ -1,21 +1,23 @@
 <script setup lang="ts">
   import { computed, useAttrs } from 'vue'
 
-  defineOptions({ name: 'InputGroupAddon', inheritAttrs: false })
+  defineOptions({ name: 'InputGroupSlotLeft', inheritAttrs: false })
 
   defineSlots<{
     default(): unknown
   }>()
 
   const attrs = useAttrs()
-  const testId = computed(() => (attrs['data-testid'] as string | undefined) ?? 'input-group-addon')
+  const testId = computed(
+    () => (attrs['data-testid'] as string | undefined) ?? 'input-group-slot-left'
+  )
 </script>
 
 <template>
   <div
     v-bind="$attrs"
     :data-testid="testId"
-    class="flex items-center self-stretch shrink-0 bg-[var(--bg-canvas)] px-[var(--spacing-md)] text-label-sm text-[color:var(--text-muted)] first:border-r last:border-l border-[color:var(--border-default)]"
+    class="flex items-center self-stretch shrink-0 bg-[var(--bg-canvas)] px-[var(--spacing-md)] text-label-sm text-[color:var(--text-muted)] border-r border-[color:var(--border-default)]"
   >
     <slot />
   </div>
diff --git a/packages/webkit/src/components/inputs/input-group/input-group-slot-right/input-group-slot-right.vue b/packages/webkit/src/components/inputs/input-group/input-group-slot-right/input-group-slot-right.vue
new file mode 100644
index 00000000..c944f510
--- /dev/null
+++ b/packages/webkit/src/components/inputs/input-group/input-group-slot-right/input-group-slot-right.vue
@@ -0,0 +1,24 @@
+<script setup lang="ts">
+  import { computed, useAttrs } from 'vue'
+
+  defineOptions({ name: 'InputGroupSlotRight', inheritAttrs: false })
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  const attrs = useAttrs()
+  const testId = computed(
+    () => (attrs['data-testid'] as string | undefined) ?? 'input-group-slot-right'
+  )
+</script>
+
+<template>
+  <div
+    v-bind="$attrs"
+    :data-testid="testId"
+    class="flex items-center self-stretch shrink-0 bg-[var(--bg-canvas)] px-[var(--spacing-md)] text-label-sm text-[color:var(--text-muted)] border-l border-[color:var(--border-default)]"
+  >
+    <slot />
+  </div>
+</template>

From 71dc87ff988c117bf16d2f34c11901a7c11afc5e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Wed, 1 Jul 2026 12:15:04 -0300
Subject: [PATCH 08/11] [NO-ISSUE] refactor: switch InputGroup to monolithic
 with named #left / #right slots
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Align InputGroup's API with input-text, input-number, and field-text —
which all use named slots on the root (iconLeft/iconRight, prefix/
suffix) instead of a compound API with sub-components. The named-slot
approach eliminates:

- The compound layer (index.ts + Object.assign).
- The injection-key.ts marker (nobody was consuming it yet).
- The two sub-component files, their per-slot exports, and the
  tree-shaking -root export.
- The JIT scan surprise on newly-created files (all classes now live
  on a single .vue that Tailwind already tracks).

The visual behavior is unchanged — left slot still bg-canvas +
border-r toward the input, right slot bg-canvas + border-l, root
still owns focus-within ring / hover strong / invalid+required
border colors.

spec_version bumped to 2 (structure changed from composition to
monolithic), body re-authored, checksum refreshed to a875eb1a...
Stories updated to use <template #left> / <template #right>.
---
 .specs/input-group.md                         | 114 +++++-------------
 .../inputs/input-group/InputGroup.stories.js  |  42 +++----
 packages/webkit/package.json                  |   5 +-
 .../components/inputs/input-group/index.ts    |   8 --
 .../inputs/input-group/injection-key.ts       |   3 -
 .../input-group-slot-left.vue                 |  24 ----
 .../input-group-slot-right.vue                |  24 ----
 .../inputs/input-group/input-group.vue        |  30 +++--
 8 files changed, 72 insertions(+), 178 deletions(-)
 delete mode 100644 packages/webkit/src/components/inputs/input-group/index.ts
 delete mode 100644 packages/webkit/src/components/inputs/input-group/injection-key.ts
 delete mode 100644 packages/webkit/src/components/inputs/input-group/input-group-slot-left/input-group-slot-left.vue
 delete mode 100644 packages/webkit/src/components/inputs/input-group/input-group-slot-right/input-group-slot-right.vue

diff --git a/.specs/input-group.md b/.specs/input-group.md
index 10382467..ff13acc5 100644
--- a/.specs/input-group.md
+++ b/.specs/input-group.md
@@ -1,13 +1,13 @@
 ---
 name: input-group
 category: inputs
-structure: composition
+structure: monolithic
 status: implemented
-spec_version: 1
+spec_version: 2
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3714-10802
   node_id: 3714:10802
-checksum: aefeab873440e20a00aef247dce731761b70679ac67e1dfacacaad56f04851eb
+checksum: a875eb1aece68c1dbf57ccaea61e9801d8b1e010ffc6b4075e12e1b9bb8055f9
 created: 2026-07-01
 last_updated: 2026-07-01
 ---
@@ -16,9 +16,7 @@ last_updated: 2026-07-01
 
 ## Purpose
 
-Container that flanks an input primitive with optional slots on either side (icon, static text, button), joined by vertical dividers, and reflects validation state on its border. Composed as `<InputGroup>` (root) plus `<InputGroup.SlotLeft>` and `<InputGroup.SlotRight>` sub-components — the middle input goes in the root's default slot. Each side sub-component owns its own seam (`SlotLeft` renders `border-r`, `SlotRight` renders `border-l`) so there is no ambiguity in the CSS selectors and consumers cannot accidentally swap positions. Distinct from `field-*` components: `InputGroup` styles the input's *edges*; `field-*` wraps label + helper text.
-
-The root **provides** an injection key (`InputGroupContextKey`) that future revisions of `input-text` (and other input primitives) will `inject` to render borderless inside the group. Until that lands, the middle slot expects a raw `<input>` element styled to inherit the root's surface — `bg-[var(--bg-surface)]`, `text-label-sm`, `text-[var(--text-default)]`, `placeholder:text-[var(--text-muted)]` — so the middle blends with the group's own background while the addons stand out as darker `--bg-canvas` islands on either side (matches the Figma layout). This is the canonical middle-slot markup shown in Usage and stories.
+Monolithic container that flanks an input primitive with optional `#left` and `#right` named slots, joined by vertical seams, and reflects validation state on its border. The middle input goes in the root's `default` slot; the two side regions are simple named slots on the root — the same shape as `input-text`'s `iconLeft` / `iconRight` and `input-number`'s `prefix` / `suffix`, so the API stays consistent with the sibling inputs. Distinct from `field-*` components: `InputGroup` styles the input's *edges*; `field-*` wraps label + helper text. The middle slot expects a raw `<input>` styled `bg-[var(--bg-surface)]`, `text-label-sm`, `text-[var(--text-default)]`, `placeholder:text-[var(--text-muted)]` — matches the group's own surface so the field blends with the root while the side slots stand out as darker `--bg-canvas` islands.
 
 ## Usage
 
@@ -31,81 +29,23 @@ const value = ref('')
 
 <template>
   <InputGroup :invalid="false">
-    <InputGroup.SlotLeft>https://</InputGroup.SlotLeft>
+    <template #left>https://</template>
     <input
       v-model="value"
       placeholder="domain"
       class="w-full h-full bg-[var(--bg-surface)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]"
     />
-    <InputGroup.SlotRight>.com</InputGroup.SlotRight>
+    <template #right>.com</template>
   </InputGroup>
 </template>
 ```
 
-Tree-shaking alternative — standalone root + sub-components, no compound `Object.assign` pulled in:
-
-```vue
-<script setup>
-import { ref } from 'vue'
-import InputGroup from '@aziontech/webkit/input-group-root'
-import InputGroupSlotLeft from '@aziontech/webkit/input-group-slot-left'
-import InputGroupSlotRight from '@aziontech/webkit/input-group-slot-right'
-const value = ref('')
-</script>
-
-<template>
-  <InputGroup>
-    <InputGroupSlotLeft>https://</InputGroupSlotLeft>
-    <input
-      v-model="value"
-      placeholder="domain"
-      class="w-full h-full bg-[var(--bg-surface)] border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)]"
-    />
-    <InputGroupSlotRight>.com</InputGroupSlotRight>
-  </InputGroup>
-</template>
-```
-
-## Sub-components
-
-- `input-group-slot-left/input-group-slot-left.vue` — Left-side slot. Exposes a `default` slot (scope: none) for the content (icon, static text, or a `<Button>`). Renders with `bg-[var(--bg-canvas)]`, `px-[var(--spacing-md)]`, `text-label-sm`, `text-[color:var(--text-muted)]`, and a hardcoded `border-r border-[color:var(--border-default)]` — the vertical seam toward the middle input.
-- `input-group-slot-right/input-group-slot-right.vue` — Right-side slot. Same styling as `SlotLeft` but with a hardcoded `border-l border-[color:var(--border-default)]` seam toward the middle input on the opposite side.
-
-Resulting layout:
-
-```
-packages/webkit/src/components/inputs/input-group/
-├── input-group.vue
-├── injection-key.ts                    (exports InputGroupContextKey symbol; future primitives inject to detect nesting)
-├── index.ts                            (Object.assign(InputGroup, { SlotLeft, SlotRight }))
-├── input-group-slot-left/
-│   └── input-group-slot-left.vue
-└── input-group-slot-right/
-    └── input-group-slot-right.vue
-```
-
-Compound file (`index.ts`):
-
-```ts
-import InputGroup from './input-group.vue'
-import InputGroupSlotLeft from './input-group-slot-left/input-group-slot-left.vue'
-import InputGroupSlotRight from './input-group-slot-right/input-group-slot-right.vue'
-export default Object.assign(InputGroup, {
-  SlotLeft: InputGroupSlotLeft,
-  SlotRight: InputGroupSlotRight
-})
-```
-
 ## Props
 
-Root (`InputGroup`):
-
 | Prop | Type | Default | Required | JSDoc |
 |---|---|---|---|---|
-| `invalid` | `boolean` | `false` | no | Renders the error border. When `required` is also `true`, the border uses the warning color instead of danger. Also sets `aria-invalid="true"` on the root. |
-| `required` | `boolean` | `false` | no | Semantic marker for a required field. Combined with `invalid=true`, switches the border color to warning. Sets `aria-required="true"` on the root. |
-
-Sub-components (`InputGroup.SlotLeft`, `InputGroup.SlotRight`) have no props.
+| `invalid` | `boolean` | `false` | no | Renders the error border and sets `aria-invalid="true"` on the root. |
+| `required` | `boolean` | `false` | no | Renders the required (warning) border and sets `aria-required="true"` on the root. |
 
 ## Events
 
@@ -115,7 +55,9 @@ Sub-components (`InputGroup.SlotLeft`, `InputGroup.SlotRight`) have no props.
 
 | Slot | Scope | Notes |
 |---|---|---|
-| `default` | — | Middle content — a raw `<input>` element in source order, optionally preceded by `<InputGroup.SlotLeft>` and/or followed by `<InputGroup.SlotRight>`. Each side sub-component exposes its own `default` slot for the addon content (icon, static text, or a `<Button>`); those are documented in the Sub-components section, not here. |
+| `left` | — | Optional left-side content (icon, static text, or a `<Button>`). When present, rendered inside a styled `<div>` (`bg-[var(--bg-canvas)]`, `px-[var(--spacing-md)]`, `text-label-sm`, `text-[color:var(--text-muted)]`, `border-r border-[color:var(--border-default)]`). |
+| `default` | — | Middle content — a raw `<input>` element (or any input primitive). |
+| `right` | — | Optional right-side content, same styling as `#left` but with `border-l` instead of `border-r`. |
 
 ## States
 
@@ -148,12 +90,12 @@ Sub-components (`InputGroup.SlotLeft`, `InputGroup.SlotRight`) have no props.
 | root height | `h-8` (Tailwind utility) |
 | focus ring | `var(--ring-color)` |
 | focus ring offset | `var(--bg-canvas)` |
-| SlotLeft / SlotRight surface | `var(--bg-canvas)` |
-| SlotLeft / SlotRight text | `var(--text-muted)` |
-| SlotLeft / SlotRight padding.x | `var(--spacing-md)` |
-| SlotLeft / SlotRight typography | `.text-label-sm` |
-| SlotLeft seam (vertical border) | `border-r border-[color:var(--border-default)]` |
-| SlotRight seam (vertical border) | `border-l border-[color:var(--border-default)]` |
+| side slot surface | `var(--bg-canvas)` |
+| side slot text | `var(--text-muted)` |
+| side slot padding.x | `var(--spacing-md)` |
+| side slot typography | `.text-label-sm` |
+| left slot seam | `border-r border-[color:var(--border-default)]` |
+| right slot seam | `border-l border-[color:var(--border-default)]` |
 
 ## Theme gaps
 
@@ -163,23 +105,23 @@ Sub-components (`InputGroup.SlotLeft`, `InputGroup.SlotRight`) have no props.
 
 ## Accessibility (WCAG 2.1 AA)
 
-- Visible focus: the root shows a `focus-within` ring (`ring-2 ring-[var(--ring-color)] ring-offset-2 ring-offset-[var(--bg-canvas)]`) whenever any descendant (addon control or middle input) has focus. The middle input renders `focus:ring-0 outline-none` so the group's ring is the only visible focus indicator.
-- Keyboard map: `Tab` moves through the addon interactive content (if any) and the middle input in DOM order. No custom keybindings on the group.
+- Visible focus: the root shows a `focus-within` ring (`ring-2 ring-[var(--ring-color)] ring-offset-2 ring-offset-[var(--bg-canvas)]`) whenever any descendant (side-slot control or middle input) has focus. The middle input renders `focus:ring-0 outline-none` so the group's ring is the only visible focus indicator.
+- Keyboard map: `Tab` moves through the side-slot interactive content (if any) and the middle input in DOM order. No custom keybindings on the group.
 - ARIA: root uses `role="group"`; `aria-invalid` and `aria-required` reflect the props. The inner input keeps its own `aria-*` — the group does not duplicate.
-- Contrast ≥4.5:1 for addon text against `var(--bg-canvas)`; ≥3:1 for the border in every state.
+- Contrast ≥4.5:1 for side-slot text against `var(--bg-canvas)`; ≥3:1 for the border in every state.
 - Motion: color transitions on state changes are `duration-150 ease-out` and pair with `motion-reduce:transition-none`.
-- Touch target ≥32×32 px for interactive addon content (matches root height `h-8`).
+- Touch target ≥32×32 px for interactive side-slot content (matches root height `h-8`).
 
 ## Stories (Storybook)
 
-- Default — root with a middle input and no side slots.
-- WithSlotLeft — one `<InputGroup.SlotLeft>` before the input (e.g. `https://`).
-- WithSlotRight — one `<InputGroup.SlotRight>` after the input (e.g. `.com`).
-- BothSlots — a `SlotLeft` before and a `SlotRight` after the input.
-- Invalid — `invalid=true`, no `required` (danger border).
-- InvalidRequired — `invalid=true` and `required=true` (warning border).
+- Default — root with a middle input, no side slots filled.
+- WithSlotLeft — `#left` slot filled (e.g. `https://`).
+- WithSlotRight — `#right` slot filled (e.g. `.com`).
+- BothSlots — both `#left` and `#right` filled.
+- Invalid — `invalid=true` (danger border).
+- Required — `required=true` (warning border).
 
-Justification for six stories (deviates from Default+Types+Sizes+state pattern): the component has no `kind` and no `size`, so `Types` and `Sizes` do not apply. The four composition stories (Default, WithSlotLeft, WithSlotRight, BothSlots) document each side sub-component individually and combined — the primary API surface. The two state stories exercise the invalid and invalid+required border colors, which are the only non-obvious visual signals.
+Justification for six stories (deviates from Default+Types+Sizes+state pattern): the component has no `kind` and no `size`, so `Types` and `Sizes` do not apply. The four slot-composition stories (Default, WithSlotLeft, WithSlotRight, BothSlots) document each named-slot position individually and combined — the primary API surface. The two state stories exercise the invalid and required border colors — the only two non-default visual signals the component can emit.
 
 ## Constraints — DO NOT
 
diff --git a/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
index 2684997e..582f64a4 100644
--- a/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
+++ b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
@@ -17,7 +17,7 @@ const meta = {
     docs: {
       description: {
         component:
-          "Container that flanks an input primitive with optional slots on either side, joined by vertical borders, and reflects validation state on its border. Composed as `<InputGroup>` (root) plus `<InputGroup.SlotLeft>` and `<InputGroup.SlotRight>` sub-components — the middle input goes in the root's default slot."
+          "Monolithic container that flanks an input primitive with optional `#left` and `#right` named slots, joined by vertical seams, and reflects validation state on its border. The middle input goes in the root's `default` slot."
       },
       canvas: { sourceState: 'shown' }
     }
@@ -25,14 +25,12 @@ const meta = {
   argTypes: {
     invalid: {
       control: 'boolean',
-      description:
-        'Renders the error border. When `required` is also `true`, the border uses the warning color instead of danger. Also sets `aria-invalid="true"` on the root.',
+      description: 'Renders the error border and sets `aria-invalid="true"` on the root.',
       table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
     },
     required: {
       control: 'boolean',
-      description:
-        'Semantic marker for a required field. Combined with `invalid=true`, switches the border color to warning. Sets `aria-required="true"` on the root.',
+      description: 'Renders the required (warning) border and sets `aria-required="true"` on the root.',
       table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
     }
   },
@@ -61,14 +59,14 @@ export const Default = {
   render: Template,
   parameters: {
     docs: {
-      description: { story: 'Root with only a raw `<input>` in the middle slot and no addons.' },
+      description: { story: 'Root with only a raw `<input>` in the middle slot and no side slots.' },
       source: { code: toSfc(IMPORT, DEFAULT_MARKUP) }
     }
   }
 }
 
 const WITH_SLOT_LEFT_MARKUP = `<InputGroup>
-  <InputGroup.SlotLeft>https://</InputGroup.SlotLeft>
+  <template #left>https://</template>
   ${MIDDLE_INPUT}
 </InputGroup>`
 
@@ -81,7 +79,7 @@ export const WithSlotLeft = {
   parameters: {
     docs: {
       controls: { disable: true },
-      description: { story: 'A single `<InputGroup.SlotLeft>` before the middle input.' },
+      description: { story: 'The `#left` named slot filled with static text before the middle input.' },
       source: { code: toSfc(IMPORT, WITH_SLOT_LEFT_MARKUP) }
     }
   }
@@ -89,7 +87,7 @@ export const WithSlotLeft = {
 
 const WITH_SLOT_RIGHT_MARKUP = `<InputGroup>
   ${MIDDLE_INPUT}
-  <InputGroup.SlotRight>.com</InputGroup.SlotRight>
+  <template #right>.com</template>
 </InputGroup>`
 
 /** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
@@ -101,16 +99,16 @@ export const WithSlotRight = {
   parameters: {
     docs: {
       controls: { disable: true },
-      description: { story: 'A single `<InputGroup.SlotRight>` after the middle input.' },
+      description: { story: 'The `#right` named slot filled with static text after the middle input.' },
       source: { code: toSfc(IMPORT, WITH_SLOT_RIGHT_MARKUP) }
     }
   }
 }
 
 const BOTH_SLOTS_MARKUP = `<InputGroup>
-  <InputGroup.SlotLeft>https://</InputGroup.SlotLeft>
+  <template #left>https://</template>
   ${MIDDLE_INPUT}
-  <InputGroup.SlotRight>.com</InputGroup.SlotRight>
+  <template #right>.com</template>
 </InputGroup>`
 
 /** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
@@ -122,16 +120,16 @@ export const BothSlots = {
   parameters: {
     docs: {
       controls: { disable: true },
-      description: { story: 'A `SlotLeft` and a `SlotRight` flanking the middle input.' },
+      description: { story: 'Both `#left` and `#right` slots filled, flanking the middle input.' },
       source: { code: toSfc(IMPORT, BOTH_SLOTS_MARKUP) }
     }
   }
 }
 
 const INVALID_MARKUP = `<InputGroup :invalid="true">
-  <InputGroup.SlotLeft>https://</InputGroup.SlotLeft>
+  <template #left>https://</template>
   ${MIDDLE_INPUT}
-  <InputGroup.SlotRight>.com</InputGroup.SlotRight>
+  <template #right>.com</template>
 </InputGroup>`
 
 /** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
@@ -149,23 +147,23 @@ export const Invalid = {
   }
 }
 
-const INVALID_REQUIRED_MARKUP = `<InputGroup :invalid="true" :required="true">
-  <InputGroup.SlotLeft>https://</InputGroup.SlotLeft>
+const REQUIRED_MARKUP = `<InputGroup :required="true">
+  <template #left>https://</template>
   ${MIDDLE_INPUT}
-  <InputGroup.SlotRight>.com</InputGroup.SlotRight>
+  <template #right>.com</template>
 </InputGroup>`
 
 /** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
-export const InvalidRequired = {
+export const Required = {
   render: () => ({
     components: { InputGroup },
-    template: INVALID_REQUIRED_MARKUP
+    template: REQUIRED_MARKUP
   }),
   parameters: {
     docs: {
       controls: { disable: true },
-      description: { story: 'Invalid + required — root shows the warning border instead of danger.' },
-      source: { code: toSfc(IMPORT, INVALID_REQUIRED_MARKUP) }
+      description: { story: 'Required state — root shows the warning border.' },
+      source: { code: toSfc(IMPORT, REQUIRED_MARKUP) }
     }
   }
 }
diff --git a/packages/webkit/package.json b/packages/webkit/package.json
index 11fdb4e5..5e55f146 100644
--- a/packages/webkit/package.json
+++ b/packages/webkit/package.json
@@ -127,10 +127,7 @@
     "./progress-bar": "./src/components/feedback/progress-bar/progress-bar.vue",
     "./calendar": "./src/components/inputs/calendar/calendar.vue",
     "./input-text": "./src/components/inputs/input-text/input-text.vue",
-    "./input-group": "./src/components/inputs/input-group/index.ts",
-    "./input-group-root": "./src/components/inputs/input-group/input-group.vue",
-    "./input-group-slot-left": "./src/components/inputs/input-group/input-group-slot-left/input-group-slot-left.vue",
-    "./input-group-slot-right": "./src/components/inputs/input-group/input-group-slot-right/input-group-slot-right.vue",
+    "./input-group": "./src/components/inputs/input-group/input-group.vue",
     "./input-number": "./src/components/inputs/input-number/input-number.vue",
     "./field-text": "./src/components/inputs/field-text/field-text.vue",
     "./helper-text": "./src/components/inputs/helper-text/helper-text.vue",
diff --git a/packages/webkit/src/components/inputs/input-group/index.ts b/packages/webkit/src/components/inputs/input-group/index.ts
deleted file mode 100644
index c683c752..00000000
--- a/packages/webkit/src/components/inputs/input-group/index.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import InputGroup from './input-group.vue'
-import InputGroupSlotLeft from './input-group-slot-left/input-group-slot-left.vue'
-import InputGroupSlotRight from './input-group-slot-right/input-group-slot-right.vue'
-
-export default Object.assign(InputGroup, {
-  SlotLeft: InputGroupSlotLeft,
-  SlotRight: InputGroupSlotRight
-})
diff --git a/packages/webkit/src/components/inputs/input-group/injection-key.ts b/packages/webkit/src/components/inputs/input-group/injection-key.ts
deleted file mode 100644
index 4d836de7..00000000
--- a/packages/webkit/src/components/inputs/input-group/injection-key.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-import type { InjectionKey } from 'vue'
-
-export const InputGroupContextKey: InjectionKey<true> = Symbol('InputGroupContext')
diff --git a/packages/webkit/src/components/inputs/input-group/input-group-slot-left/input-group-slot-left.vue b/packages/webkit/src/components/inputs/input-group/input-group-slot-left/input-group-slot-left.vue
deleted file mode 100644
index dd3b621a..00000000
--- a/packages/webkit/src/components/inputs/input-group/input-group-slot-left/input-group-slot-left.vue
+++ /dev/null
@@ -1,24 +0,0 @@
-<script setup lang="ts">
-  import { computed, useAttrs } from 'vue'
-
-  defineOptions({ name: 'InputGroupSlotLeft', inheritAttrs: false })
-
-  defineSlots<{
-    default(): unknown
-  }>()
-
-  const attrs = useAttrs()
-  const testId = computed(
-    () => (attrs['data-testid'] as string | undefined) ?? 'input-group-slot-left'
-  )
-</script>
-
-<template>
-  <div
-    v-bind="$attrs"
-    :data-testid="testId"
-    class="flex items-center self-stretch shrink-0 bg-[var(--bg-canvas)] px-[var(--spacing-md)] text-label-sm text-[color:var(--text-muted)] border-r border-[color:var(--border-default)]"
-  >
-    <slot />
-  </div>
-</template>
diff --git a/packages/webkit/src/components/inputs/input-group/input-group-slot-right/input-group-slot-right.vue b/packages/webkit/src/components/inputs/input-group/input-group-slot-right/input-group-slot-right.vue
deleted file mode 100644
index c944f510..00000000
--- a/packages/webkit/src/components/inputs/input-group/input-group-slot-right/input-group-slot-right.vue
+++ /dev/null
@@ -1,24 +0,0 @@
-<script setup lang="ts">
-  import { computed, useAttrs } from 'vue'
-
-  defineOptions({ name: 'InputGroupSlotRight', inheritAttrs: false })
-
-  defineSlots<{
-    default(): unknown
-  }>()
-
-  const attrs = useAttrs()
-  const testId = computed(
-    () => (attrs['data-testid'] as string | undefined) ?? 'input-group-slot-right'
-  )
-</script>
-
-<template>
-  <div
-    v-bind="$attrs"
-    :data-testid="testId"
-    class="flex items-center self-stretch shrink-0 bg-[var(--bg-canvas)] px-[var(--spacing-md)] text-label-sm text-[color:var(--text-muted)] border-l border-[color:var(--border-default)]"
-  >
-    <slot />
-  </div>
-</template>
diff --git a/packages/webkit/src/components/inputs/input-group/input-group.vue b/packages/webkit/src/components/inputs/input-group/input-group.vue
index 6dd011b0..a51e4de9 100644
--- a/packages/webkit/src/components/inputs/input-group/input-group.vue
+++ b/packages/webkit/src/components/inputs/input-group/input-group.vue
@@ -1,14 +1,12 @@
 <script setup lang="ts">
-  import { computed, provide, useAttrs } from 'vue'
-
-  import { InputGroupContextKey } from './injection-key'
+  import { computed, useAttrs, useSlots } from 'vue'
 
   defineOptions({ name: 'InputGroup', inheritAttrs: false })
 
   export interface Props {
-    /** Renders the error border. When `required` is also `true`, the border uses the warning color instead of danger. Also sets `aria-invalid="true"` on the root. */
+    /** Renders the error border and sets aria-invalid on the root. */
     invalid?: boolean
-    /** Semantic marker for a required field. Combined with `invalid=true`, switches the border color to warning. Sets `aria-required="true"` on the root. */
+    /** Renders the required (warning) border and sets aria-required on the root. */
     required?: boolean
   }
 
@@ -18,13 +16,17 @@
   })
 
   defineSlots<{
+    left(): unknown
     default(): unknown
+    right(): unknown
   }>()
 
   const attrs = useAttrs()
-  const testId = computed(() => (attrs['data-testid'] as string | undefined) ?? 'input-group')
+  const slots = useSlots()
 
-  provide(InputGroupContextKey, true)
+  const testId = computed(() => (attrs['data-testid'] as string | undefined) ?? 'input-group')
+  const hasLeft = computed(() => Boolean(slots['left']))
+  const hasRight = computed(() => Boolean(slots['right']))
 </script>
 
 <template>
@@ -38,6 +40,20 @@
     :aria-required="props.required ? 'true' : undefined"
     class="relative inline-flex items-center w-full h-8 overflow-hidden rounded-[var(--shape-elements)] border border-[var(--border-default)] bg-[var(--bg-surface)] transition-colors duration-150 ease-out motion-reduce:transition-none [&:not(:focus-within):not([data-invalid]):not([data-required])]:hover:border-[var(--border-strong)] focus-within:outline-none focus-within:ring-2 focus-within:ring-[var(--ring-color)] focus-within:ring-offset-2 focus-within:ring-offset-[var(--bg-canvas)] data-[invalid]:border-[var(--danger-border)] data-[required]:border-[var(--warning-border)]"
   >
+    <div
+      v-if="hasLeft"
+      data-testid="input-group-slot-left"
+      class="flex items-center self-stretch shrink-0 bg-[var(--bg-canvas)] px-[var(--spacing-md)] text-label-sm text-[color:var(--text-muted)] border-r border-[color:var(--border-default)]"
+    >
+      <slot name="left" />
+    </div>
     <slot />
+    <div
+      v-if="hasRight"
+      data-testid="input-group-slot-right"
+      class="flex items-center self-stretch shrink-0 bg-[var(--bg-canvas)] px-[var(--spacing-md)] text-label-sm text-[color:var(--text-muted)] border-l border-[color:var(--border-default)]"
+    >
+      <slot name="right" />
+    </div>
   </div>
 </template>

From d640cea3560d0a80734ed4c3c482a23793466c66 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Wed, 1 Jul 2026 12:31:56 -0300
Subject: [PATCH 09/11] [NO-ISSUE] feat: add InputGroup disabled +
 FieldInputGroup wrapper + WithIcon story

InputGroup gains a disabled prop (spec bump 2 to 3) with data-disabled
mirror, aria-disabled on the root, and disabled-state tokens borrowed
from input-text: bg-disabled fill, text-disabled color, not-allowed
cursor, focus-within ring suppressed, hover ignored. Story WithIcon
added showing PrimeIcons in the side slots (pi pi-globe and pi
pi-times) so consumers see how icons inhabit the slots at label-sm
size. Story Disabled added.

New FieldInputGroup component mirrors FieldText verbatim, adapted to
the InputGroup primitive: renders its own middle <input>, exposes only
left and right slots forwarded to InputGroup, computes helperKind via
disabled greater invalid greater required greater helper precedence,
auto-ids via useId, wires aria-describedby to HelperText. Six stories
Default, WithSlots, Required (reactive validation flow), Invalid,
Disabled, Icons.

Package export ./field-input-group added; lint, type-check, type-
coverage 99.96%, storybook:build all green.
---
 .specs/field-input-group.md                   | 146 ++++++++
 .specs/input-group.md                         |  21 +-
 .../FieldInputGroup.stories.js                | 348 ++++++++++++++++++
 .../inputs/input-group/InputGroup.stories.js  |  59 ++-
 packages/webkit/package.json                  |   1 +
 .../field-input-group/field-input-group.vue   | 146 ++++++++
 .../inputs/input-group/input-group.vue        |   9 +-
 7 files changed, 719 insertions(+), 11 deletions(-)
 create mode 100644 .specs/field-input-group.md
 create mode 100644 apps/storybook/src/stories/components/inputs/field-input-group/FieldInputGroup.stories.js
 create mode 100644 packages/webkit/src/components/inputs/field-input-group/field-input-group.vue

diff --git a/.specs/field-input-group.md b/.specs/field-input-group.md
new file mode 100644
index 00000000..401442d5
--- /dev/null
+++ b/.specs/field-input-group.md
@@ -0,0 +1,146 @@
+---
+name: field-input-group
+category: inputs
+structure: monolithic
+status: implemented
+spec_version: 1
+figma:
+  url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3714-10802
+  node_id: 3714:10802
+checksum: 6e03ff3fb8fdf3f005031bc583ef44c78b670d4f95304248730cae0846a69c76
+created: 2026-07-01
+last_updated: 2026-07-01
+---
+
+# FieldInputGroup — Component Spec
+
+## Purpose
+
+Form field wrapper around `InputGroup` that composes `Label`, `InputGroup` (with its own middle `<input>` rendered internally), and `HelperText` into a single vertical stack with consistent spacing. Mirrors `FieldText`'s API and template shape verbatim, except the underlying primitive is `InputGroup` (fixed height, no `size` prop, side slots for icons/text) instead of `InputText`. Use it whenever a text input surrounded by prefix/suffix content needs a visible label or helper/error message.
+
+## Usage
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import FieldInputGroup from '@aziontech/webkit/field-input-group'
+
+const domain = ref('')
+</script>
+
+<template>
+  <FieldInputGroup
+    v-model="domain"
+    label="Website"
+    placeholder="mysite"
+    helper-text="Enter the domain without the scheme."
+    required
+  >
+    <template #left>https://</template>
+    <template #right>.com</template>
+  </FieldInputGroup>
+</template>
+```
+
+## Props
+
+| Prop | Type | Default | Required | JSDoc |
+|---|---|---|---|---|
+| `modelValue` | `string` | `''` | no | Two-way bound value of the internal `<input>`. |
+| `label` | `string` | `''` | no | Text rendered inside the `Label`. When empty, the label row is omitted. |
+| `placeholder` | `string` | `''` | no | Placeholder forwarded to the internal `<input>`. |
+| `helperText` | `string` | `''` | no | Auxiliary text rendered inside `HelperText`. When empty, the helper row is omitted **except** when `disabled` is true — in that case the component falls back to a default disabled message so the lock icon always has matching copy. |
+| `disabled` | `boolean` | `false` | no | Disables the input and the `InputGroup` chrome, and switches the helper to `kind="disabled"` (lock icon). |
+| `readonly` | `boolean` | `false` | no | Marks the internal input read-only; value is visible but not editable. Native pass-through. |
+| `required` | `boolean` | `false` | no | Adds the Required tag to the `Label`, sets `required` on `InputGroup`, and sets native `required` + `aria-required` on the internal `<input>`. |
+| `invalid` | `boolean` | `false` | no | Sets `invalid` on `InputGroup` (danger border) and switches the helper to `kind="invalid"`. Also sets `aria-invalid` on the internal `<input>`. |
+| `inputId` | `string` | `''` | no | `id` for the internal `<input>`; consumed by `Label` via `for` and by `aria-describedby` wiring. Auto-generated via Vue's `useId()` when empty. |
+| `name` | `string` | `''` | no | HTML `name` for the internal `<input>` (form + vee-validate integration). |
+
+## Events
+
+| Event | Payload | Notes |
+|---|---|---|
+| `update:modelValue` | `[value: string]` | Re-emitted from the internal `<input>` on native `input` event. Enables `v-model`. |
+
+## Slots
+
+| Slot | Scope | Notes |
+|---|---|---|
+| `left` | — | Forwarded verbatim to `InputGroup`'s `#left`. Optional prefix content (icon, static text, or a small control). |
+| `right` | — | Forwarded verbatim to `InputGroup`'s `#right`. Optional suffix content. |
+
+## States
+
+- Visual states delegated to `InputGroup`: `default`, `hover`, `focus-within`, `invalid`, `required`, `disabled`.
+- On the field wrapper root: `data-disabled`, `data-invalid`, `data-required` mirror the props (for test/query targeting).
+- `HelperText.kind` computed by precedence: `disabled > invalid > required > 'helper'`.
+- When `disabled` is set and `helperText` is empty, the helper defaults to `'This field is locked.'` (parity with `FieldText`).
+
+## Motion & Animations
+
+_none_
+
+## Tokens
+
+| Region | Token (DESIGN.md) |
+|---|---|
+| stack gap (vertical) | `var(--spacing-xs)` |
+| internal input surface | `var(--bg-surface)` |
+| internal input text | `var(--text-default)` |
+| internal input placeholder | `var(--text-muted)` |
+| internal input padding.x | `var(--spacing-md)` |
+| internal input typography | `.text-label-sm` |
+
+Border / focus / hover / invalid / required / disabled tokens are owned by the nested `InputGroup`.
+
+## Theme gaps
+
+| Figma variable | Temporary primitive | Follow-up |
+|---|---|---|
+| _none_ | — | — |
+
+## Accessibility (WCAG 2.1 AA)
+
+- Visible focus: delegated to `InputGroup` (focus-within ring on the group root). The internal `<input>` renders `focus:ring-0 outline-none` so only the group ring shows.
+- Keyboard map: `Tab` moves through any interactive side-slot content and then the internal `<input>`, in DOM order.
+- ARIA: internal `<input>` receives `aria-invalid`, `aria-required`, and `aria-describedby` pointing at the `HelperText` id when helper text is present or `disabled` forces the fallback. `Label` is linked via `for=<inputId>`.
+- Contrast ≥4.5:1 for label / input text / helper text against their surfaces.
+- Motion: state color transitions come from `InputGroup` (`duration-150 ease-out`, `motion-reduce:transition-none`).
+- Touch target ≥32×32 px (matches the fixed `h-8` `InputGroup` root).
+
+## Stories (Storybook)
+
+- Default — value + label + placeholder + helperText, no side slots filled.
+- WithSlots — `#left` (`https://`) and `#right` (`.com`) filled.
+- Required — `required=true`, reactive validation flow (label shows Required tag, invalid switches on empty submission).
+- Invalid — `invalid=true` with a message in `helperText`.
+- Disabled — `disabled=true`, helper falls back to the disabled copy.
+- Icons — PrimeIcons in both side slots (`pi pi-globe` left, `pi pi-times` right).
+
+Justification for six stories (deviates from Default+Types+Sizes+state pattern): the component has no `kind` and no `size`, so `Types` and `Sizes` do not apply. `Default`, `WithSlots`, and `Icons` document the composition API (label + helper + side slots). `Required`, `Invalid`, `Disabled` exercise the three state signals the wrapper propagates.
+
+## 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 points at `index.ts`, and a standalone `./<name>-root` export points at the root `.vue` (tree-shaking). 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/.specs/input-group.md b/.specs/input-group.md
index ff13acc5..50215ef9 100644
--- a/.specs/input-group.md
+++ b/.specs/input-group.md
@@ -3,11 +3,11 @@ name: input-group
 category: inputs
 structure: monolithic
 status: implemented
-spec_version: 2
+spec_version: 3
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=3714-10802
   node_id: 3714:10802
-checksum: a875eb1aece68c1dbf57ccaea61e9801d8b1e010ffc6b4075e12e1b9bb8055f9
+checksum: 0ede3c42dbd778be429c8e91192d35cbc9b09f42154ae6a9ae6f064a2b6a74d7
 created: 2026-07-01
 last_updated: 2026-07-01
 ---
@@ -46,6 +46,7 @@ const value = ref('')
 |---|---|---|---|---|
 | `invalid` | `boolean` | `false` | no | Renders the error border and sets `aria-invalid="true"` on the root. |
 | `required` | `boolean` | `false` | no | Renders the required (warning) border and sets `aria-required="true"` on the root. |
+| `disabled` | `boolean` | `false` | no | Renders the disabled visual (muted fill, not-allowed cursor, no focus-within ring) and sets `aria-disabled="true"` on the root. Does not propagate to the middle `<input>` — the consumer is responsible for the inner input's own `disabled` attribute (mirrors how `FieldText` disables `InputText`). |
 
 ## Events
 
@@ -61,14 +62,16 @@ const value = ref('')
 
 ## States
 
-- Visual states on root: `default`, `hover`, `focus-within`, `invalid`, `required`
+- Visual states on root: `default`, `hover`, `focus-within`, `invalid`, `required`, `disabled`
 - `data-invalid` mirrors the `invalid` prop; sets `aria-invalid="true"`
 - `data-required` mirrors the `required` prop; sets `aria-required="true"`
+- `data-disabled` mirrors the `disabled` prop; sets `aria-disabled="true"`
 - Border semantics mirror `input-text` (independent, not compound):
   - `data-invalid` → `var(--danger-border)`
   - `data-required` → `var(--warning-border)`
-- Hover (only when not focus-within and neither invalid nor required): `border-[var(--border-strong)]`
-- Focus-within: 2-ring at `var(--ring-color)` with `var(--bg-canvas)` offset
+- Hover (only when not focus-within, not invalid, not required, not disabled): `border-[var(--border-strong)]`
+- Focus-within: 2-ring at `var(--ring-color)` with `var(--bg-canvas)` offset (suppressed when `data-disabled`)
+- Disabled: `bg-[var(--bg-disabled)]`, `text-[var(--text-disabled)]`, `cursor-not-allowed`, hover ignored, focus-within ring suppressed
 
 ## Motion & Animations
 
@@ -85,6 +88,8 @@ const value = ref('')
 | root border (hover) | `var(--border-strong)` |
 | root border (invalid) | `var(--danger-border)` |
 | root border (required) | `var(--warning-border)` |
+| root surface (disabled) | `var(--bg-disabled)` |
+| root text (disabled) | `var(--text-disabled)` |
 | root border width | `border` (Tailwind utility) |
 | root shape | `var(--shape-elements)` |
 | root height | `h-8` (Tailwind utility) |
@@ -105,7 +110,7 @@ const value = ref('')
 
 ## Accessibility (WCAG 2.1 AA)
 
-- Visible focus: the root shows a `focus-within` ring (`ring-2 ring-[var(--ring-color)] ring-offset-2 ring-offset-[var(--bg-canvas)]`) whenever any descendant (side-slot control or middle input) has focus. The middle input renders `focus:ring-0 outline-none` so the group's ring is the only visible focus indicator.
+- Visible focus: the root shows a `focus-within` ring (`ring-2 ring-[var(--ring-color)] ring-offset-2 ring-offset-[var(--bg-canvas)]`) whenever any descendant (side-slot control or middle input) has focus. The middle input renders `focus:ring-0 outline-none` so the group's ring is the only visible focus indicator. Suppressed when `data-disabled` is present.
 - Keyboard map: `Tab` moves through the side-slot interactive content (if any) and the middle input in DOM order. No custom keybindings on the group.
 - ARIA: root uses `role="group"`; `aria-invalid` and `aria-required` reflect the props. The inner input keeps its own `aria-*` — the group does not duplicate.
 - Contrast ≥4.5:1 for side-slot text against `var(--bg-canvas)`; ≥3:1 for the border in every state.
@@ -118,10 +123,12 @@ const value = ref('')
 - WithSlotLeft — `#left` slot filled (e.g. `https://`).
 - WithSlotRight — `#right` slot filled (e.g. `.com`).
 - BothSlots — both `#left` and `#right` filled.
+- WithIcon — `#left` filled with `<i class="pi pi-globe" aria-hidden="true" />`, showing how PrimeIcons inhabit the side slots at the same size as text content.
 - Invalid — `invalid=true` (danger border).
 - Required — `required=true` (warning border).
+- Disabled — `disabled=true` (muted fill, not-allowed cursor, no focus ring).
 
-Justification for six stories (deviates from Default+Types+Sizes+state pattern): the component has no `kind` and no `size`, so `Types` and `Sizes` do not apply. The four slot-composition stories (Default, WithSlotLeft, WithSlotRight, BothSlots) document each named-slot position individually and combined — the primary API surface. The two state stories exercise the invalid and required border colors — the only two non-default visual signals the component can emit.
+Justification for eight stories (deviates from Default+Types+Sizes+state pattern): the component has no `kind` and no `size`, so `Types` and `Sizes` do not apply. Four slot-composition stories (Default, WithSlotLeft, WithSlotRight, BothSlots) document each named-slot position individually and combined. `WithIcon` demonstrates that side slots accept `<i>` icons at the same size/color as text content (parallel to `FieldText`'s Icons story). Three state stories exercise `Invalid`, `Required`, and `Disabled` — the visual signals the component can emit.
 
 ## Constraints — DO NOT
 
diff --git a/apps/storybook/src/stories/components/inputs/field-input-group/FieldInputGroup.stories.js b/apps/storybook/src/stories/components/inputs/field-input-group/FieldInputGroup.stories.js
new file mode 100644
index 00000000..535192d3
--- /dev/null
+++ b/apps/storybook/src/stories/components/inputs/field-input-group/FieldInputGroup.stories.js
@@ -0,0 +1,348 @@
+import Button from '@aziontech/webkit/button'
+import FieldInputGroup from '@aziontech/webkit/field-input-group'
+import { ref } from 'vue'
+
+import { toSfc } from '../../../_shared/story-source'
+
+const IMPORT = "import FieldInputGroup from '@aziontech/webkit/field-input-group'"
+
+/** @type {import('@storybook/vue3').Meta<typeof FieldInputGroup>} */
+const meta = {
+  title: 'Components/Inputs/FieldInputGroup',
+  component: FieldInputGroup,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          "Form field wrapper around `InputGroup` that composes `Label`, `InputGroup` (with its own middle `<input>` rendered internally), and `HelperText` into a single vertical stack. Mirrors `FieldText`'s API — same `label` / `helperText` / `disabled` / `invalid` / `required` behavior — with the added `#left` and `#right` slots forwarded to `InputGroup`."
+      },
+      canvas: { sourceState: 'shown' }
+    }
+  },
+  argTypes: {
+    modelValue: {
+      control: 'text',
+      description: 'Two-way bound value of the internal `<input>`.',
+      table: { category: 'props', type: { summary: 'string' } }
+    },
+    label: {
+      control: 'text',
+      description: 'Text rendered inside the `Label`. When empty, the label row is omitted.',
+      table: { category: 'props', type: { summary: 'string' } }
+    },
+    placeholder: {
+      control: 'text',
+      description: 'Placeholder forwarded to the internal `<input>`.',
+      table: { category: 'props', type: { summary: 'string' } }
+    },
+    helperText: {
+      control: 'text',
+      description:
+        'Auxiliary text rendered inside `HelperText`. When empty, the helper row is omitted (except when `disabled` — fallback copy is shown).',
+      table: { category: 'props', type: { summary: 'string' } }
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disables the input and the `InputGroup` chrome; switches helper to `kind="disabled"`.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    readonly: {
+      control: 'boolean',
+      description: 'Marks the internal input read-only; value is visible but not editable.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    required: {
+      control: 'boolean',
+      description:
+        'Adds the Required tag to Label, propagates `required` to InputGroup and native input.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    invalid: {
+      control: 'boolean',
+      description:
+        'Sets `invalid` on InputGroup and switches helper to `kind="invalid"`. Also sets `aria-invalid` on the internal input.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    inputId: {
+      control: 'text',
+      description: 'id for the internal input; auto-generated via `useId()` when empty.',
+      table: { category: 'props', type: { summary: 'string' } }
+    },
+    name: {
+      control: 'text',
+      description: 'HTML name for the internal input (form + vee-validate integration).',
+      table: { category: 'props', type: { summary: 'string' } }
+    },
+    left: { control: false, table: { category: 'slots', type: { summary: 'slot' } } },
+    right: { control: false, table: { category: 'slots', type: { summary: 'slot' } } },
+    'onUpdate:modelValue': {
+      action: 'update:modelValue',
+      description: 'Re-emitted from the internal `<input>` on every input event.',
+      table: { category: 'events', type: { summary: 'string' } }
+    }
+  },
+  args: {
+    modelValue: '',
+    label: 'Website',
+    placeholder: 'mysite',
+    helperText: 'Enter the domain without the scheme.',
+    disabled: false,
+    readonly: false,
+    required: false,
+    invalid: false
+  }
+}
+
+export default meta
+
+const Template = (args) => ({
+  components: { FieldInputGroup },
+  setup() {
+    return { args }
+  },
+  template: '<div class="w-[360px]"><FieldInputGroup v-bind="args" /></div>'
+})
+
+const DEFAULT_MARKUP = `<FieldInputGroup
+  v-model="value"
+  label="Website"
+  placeholder="mysite"
+  helper-text="Enter the domain without the scheme."
+/>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof FieldInputGroup>} */
+export const Default = {
+  render: Template,
+  parameters: {
+    docs: {
+      description: { story: 'Label + internal input + helper text, no side slots filled.' },
+      source: { code: toSfc(IMPORT, DEFAULT_MARKUP) }
+    }
+  }
+}
+
+const WITH_SLOTS_MARKUP = `<FieldInputGroup
+  v-model="value"
+  label="Website"
+  placeholder="mysite"
+  helper-text="Enter the domain without the scheme."
+>
+  <template #left>https://</template>
+  <template #right>.com</template>
+</FieldInputGroup>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof FieldInputGroup>} */
+export const WithSlots = {
+  render: () => ({
+    components: { FieldInputGroup },
+    setup() {
+      const value = ref('')
+      return { value }
+    },
+    template: `
+      <div class="w-[360px]">
+        <FieldInputGroup
+          v-model="value"
+          label="Website"
+          placeholder="mysite"
+          helper-text="Enter the domain without the scheme."
+        >
+          <template #left>https://</template>
+          <template #right>.com</template>
+        </FieldInputGroup>
+      </div>
+    `
+  }),
+  parameters: {
+    docs: {
+      controls: { disable: true },
+      description: { story: '`#left` and `#right` slots forwarded to the underlying `InputGroup`.' },
+      source: { code: toSfc(IMPORT, WITH_SLOTS_MARKUP) }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof FieldInputGroup>} */
+export const Required = {
+  render: () => ({
+    components: { FieldInputGroup, Button },
+    setup() {
+      const value = ref('')
+      const missing = ref(false)
+      const loading = ref(false)
+
+      const onSubmit = () => {
+        if (loading.value) return
+        missing.value = false
+        loading.value = true
+        setTimeout(() => {
+          loading.value = false
+          missing.value = !value.value
+        }, 1200)
+      }
+
+      const onUpdate = (next) => {
+        value.value = next
+        if (next) missing.value = false
+      }
+
+      return { value, missing, loading, onSubmit, onUpdate }
+    },
+    template: `
+      <div class="flex flex-col gap-4 w-[360px]">
+        <FieldInputGroup
+          label="Website"
+          placeholder="mysite"
+          :model-value="value"
+          @update:model-value="onUpdate"
+          :required="missing"
+          :disabled="loading"
+          :helper-text="missing ? 'This field is required.' : 'Enter the domain without the scheme.'"
+        >
+          <template #left>https://</template>
+          <template #right>.com</template>
+        </FieldInputGroup>
+        <Button label="Submit" size="medium" :loading="loading" @click="onSubmit" />
+      </div>
+    `
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Click **Submit** with the field empty: the button shows the loading spinner for ~1.2s and the field locks. When loading finishes, the required check fires — the `Label` gets the Required tag, the InputGroup border turns warning, and the helper switches to the warning "This field is required." copy. Typing any value clears the error.'
+      }
+    }
+  }
+}
+
+const INVALID_MARKUP = `<FieldInputGroup
+  v-model="value"
+  label="Website"
+  model-value="not a domain"
+  helper-text="Enter a valid domain (letters, digits, hyphens)."
+  invalid
+>
+  <template #left>https://</template>
+  <template #right>.com</template>
+</FieldInputGroup>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof FieldInputGroup>} */
+export const Invalid = {
+  args: {
+    invalid: true,
+    modelValue: 'not a domain',
+    helperText: 'Enter a valid domain (letters, digits, hyphens).'
+  },
+  render: (args) => ({
+    components: { FieldInputGroup },
+    setup() {
+      return { args }
+    },
+    template: `
+      <div class="w-[360px]">
+        <FieldInputGroup v-bind="args">
+          <template #left>https://</template>
+          <template #right>.com</template>
+        </FieldInputGroup>
+      </div>
+    `
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Invalid state — helper switches to `kind="invalid"` (danger tokens) and the InputGroup border turns danger.'
+      },
+      source: { code: toSfc(IMPORT, INVALID_MARKUP) }
+    }
+  }
+}
+
+const DISABLED_MARKUP = `<FieldInputGroup
+  v-model="value"
+  label="Website"
+  model-value="mysite"
+  disabled
+>
+  <template #left>https://</template>
+  <template #right>.com</template>
+</FieldInputGroup>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof FieldInputGroup>} */
+export const Disabled = {
+  args: {
+    disabled: true,
+    modelValue: 'mysite',
+    helperText: ''
+  },
+  render: (args) => ({
+    components: { FieldInputGroup },
+    setup() {
+      return { args }
+    },
+    template: `
+      <div class="w-[360px]">
+        <FieldInputGroup v-bind="args">
+          <template #left>https://</template>
+          <template #right>.com</template>
+        </FieldInputGroup>
+      </div>
+    `
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Disabled state — helper falls back to "This field is locked." with the lock icon (`kind="disabled"`), the InputGroup surface goes muted, and cursor becomes `not-allowed`.'
+      },
+      source: { code: toSfc(IMPORT, DISABLED_MARKUP) }
+    }
+  }
+}
+
+const ICONS_MARKUP = `<FieldInputGroup
+  v-model="value"
+  label="Website"
+  placeholder="mysite"
+  helper-text="Icons in the side slots parallel FieldText's icon story vocabulary."
+>
+  <template #left><i class="pi pi-globe" aria-hidden="true" /></template>
+  <template #right><i class="pi pi-times" aria-hidden="true" /></template>
+</FieldInputGroup>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof FieldInputGroup>} */
+export const Icons = {
+  render: () => ({
+    components: { FieldInputGroup },
+    setup() {
+      const value = ref('')
+      return { value }
+    },
+    template: `
+      <div class="w-[360px]">
+        <FieldInputGroup
+          v-model="value"
+          label="Website"
+          placeholder="mysite"
+          helper-text="Icons in the side slots parallel FieldText's icon story vocabulary."
+        >
+          <template #left><i class="pi pi-globe" aria-hidden="true" /></template>
+          <template #right><i class="pi pi-times" aria-hidden="true" /></template>
+        </FieldInputGroup>
+      </div>
+    `
+  }),
+  parameters: {
+    docs: {
+      controls: { disable: true },
+      description: {
+        story:
+          'PrimeIcons flanking the internal input inside `InputGroup`\'s side slots. Same vocabulary as `FieldText`\'s Icons story.'
+      },
+      source: { code: toSfc(IMPORT, ICONS_MARKUP) }
+    }
+  }
+}
diff --git a/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
index 582f64a4..2d141442 100644
--- a/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
+++ b/apps/storybook/src/stories/components/inputs/input-group/InputGroup.stories.js
@@ -32,11 +32,18 @@ const meta = {
       control: 'boolean',
       description: 'Renders the required (warning) border and sets `aria-required="true"` on the root.',
       table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    disabled: {
+      control: 'boolean',
+      description:
+        'Renders the disabled visual (muted fill, not-allowed cursor, no focus ring) and sets `aria-disabled="true"` on the root.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
     }
   },
   args: {
     invalid: false,
-    required: false
+    required: false,
+    disabled: false
   }
 }
 
@@ -47,7 +54,7 @@ const Template = (args) => ({
   setup() {
     return { props: args }
   },
-  template: `<InputGroup :invalid="props.invalid" :required="props.required">${MIDDLE_INPUT}</InputGroup>`
+  template: `<InputGroup :invalid="props.invalid" :required="props.required" :disabled="props.disabled">${MIDDLE_INPUT}</InputGroup>`
 })
 
 const DEFAULT_MARKUP = `<InputGroup>
@@ -126,6 +133,30 @@ export const BothSlots = {
   }
 }
 
+const WITH_ICON_MARKUP = `<InputGroup>
+  <template #left><i class="pi pi-globe" aria-hidden="true" /></template>
+  ${MIDDLE_INPUT}
+  <template #right><i class="pi pi-times" aria-hidden="true" /></template>
+</InputGroup>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
+export const WithIcon = {
+  render: () => ({
+    components: { InputGroup },
+    template: WITH_ICON_MARKUP
+  }),
+  parameters: {
+    docs: {
+      controls: { disable: true },
+      description: {
+        story:
+          'PrimeIcons in the side slots. Icons inherit the slot text tokens (12px, muted color) — same visual treatment as text content.'
+      },
+      source: { code: toSfc(IMPORT, WITH_ICON_MARKUP) }
+    }
+  }
+}
+
 const INVALID_MARKUP = `<InputGroup :invalid="true">
   <template #left>https://</template>
   ${MIDDLE_INPUT}
@@ -167,3 +198,27 @@ export const Required = {
     }
   }
 }
+
+const DISABLED_MARKUP = `<InputGroup :disabled="true">
+  <template #left>https://</template>
+  ${MIDDLE_INPUT}
+  <template #right>.com</template>
+</InputGroup>`
+
+/** @type {import('@storybook/vue3').StoryObj<typeof InputGroup>} */
+export const Disabled = {
+  render: () => ({
+    components: { InputGroup },
+    template: DISABLED_MARKUP
+  }),
+  parameters: {
+    docs: {
+      controls: { disable: true },
+      description: {
+        story:
+          'Disabled state — muted fill, not-allowed cursor, focus-within ring suppressed. Note: the consumer must also set `disabled` on their middle `<input>`; InputGroup does not propagate it.'
+      },
+      source: { code: toSfc(IMPORT, DISABLED_MARKUP) }
+    }
+  }
+}
diff --git a/packages/webkit/package.json b/packages/webkit/package.json
index 5e55f146..38ec03e4 100644
--- a/packages/webkit/package.json
+++ b/packages/webkit/package.json
@@ -130,6 +130,7 @@
     "./input-group": "./src/components/inputs/input-group/input-group.vue",
     "./input-number": "./src/components/inputs/input-number/input-number.vue",
     "./field-text": "./src/components/inputs/field-text/field-text.vue",
+    "./field-input-group": "./src/components/inputs/field-input-group/field-input-group.vue",
     "./helper-text": "./src/components/inputs/helper-text/helper-text.vue",
     "./label": "./src/components/inputs/label/label.vue",
     "./input-password": "./src/components/inputs/input-password/input-password.vue",
diff --git a/packages/webkit/src/components/inputs/field-input-group/field-input-group.vue b/packages/webkit/src/components/inputs/field-input-group/field-input-group.vue
new file mode 100644
index 00000000..22ba6ddb
--- /dev/null
+++ b/packages/webkit/src/components/inputs/field-input-group/field-input-group.vue
@@ -0,0 +1,146 @@
+<script setup lang="ts">
+  import { computed, useAttrs, useId } from 'vue'
+
+  import HelperText, { type HelperTextKind } from '../helper-text/helper-text.vue'
+  import InputGroup from '../input-group/input-group.vue'
+  import Label from '../label/label.vue'
+
+  defineOptions({
+    name: 'FieldInputGroup',
+    inheritAttrs: false
+  })
+
+  interface Props {
+    /** Two-way bound value of the internal input. */
+    modelValue?: string
+    /** Text rendered inside the Label. When empty, the label row is omitted. */
+    label?: string
+    /** Placeholder forwarded to the internal input. */
+    placeholder?: string
+    /** Auxiliary text rendered inside HelperText. When empty, the helper row is omitted. */
+    helperText?: string
+    /** Disables the input and the InputGroup chrome; switches helper to kind=disabled. */
+    disabled?: boolean
+    /** Marks the internal input read-only; value is visible but not editable. */
+    readonly?: boolean
+    /** Adds the Required tag to Label and propagates required to InputGroup and input. */
+    required?: boolean
+    /** Applies invalid border on InputGroup and switches helper to kind=invalid. */
+    invalid?: boolean
+    /** id for the internal input; consumed by Label via for and by aria-describedby wiring. */
+    inputId?: string
+    /** HTML name for the internal input (form + vee-validate integration). */
+    name?: string
+  }
+
+  const props = withDefaults(defineProps<Props>(), {
+    modelValue: '',
+    label: '',
+    placeholder: '',
+    helperText: '',
+    disabled: false,
+    readonly: false,
+    required: false,
+    invalid: false,
+    inputId: '',
+    name: ''
+  })
+
+  const emit = defineEmits<{
+    'update:modelValue': [value: string]
+  }>()
+
+  defineSlots<{
+    left(): unknown
+    right(): unknown
+  }>()
+
+  const attrs = useAttrs()
+  const generatedId = useId()
+
+  const testId = computed(
+    () => (attrs['data-testid'] as string | undefined) ?? 'input-field-input-group'
+  )
+
+  const resolvedInputId = computed(() => props.inputId || generatedId)
+  const helperId = computed(() => `${resolvedInputId.value}-helper`)
+
+  const helperKind = computed<HelperTextKind>(() => {
+    if (props.disabled) return 'disabled'
+    if (props.invalid) return 'invalid'
+    if (props.required) return 'required'
+    return 'helper'
+  })
+
+  const effectiveHelperText = computed(() => {
+    if (props.helperText) return props.helperText
+    if (props.disabled) return 'This field is locked.'
+    return ''
+  })
+
+  const describedBy = computed(() => (effectiveHelperText.value ? helperId.value : undefined))
+
+  const onInput = (event: Event) => {
+    const target = event.target as HTMLInputElement
+    emit('update:modelValue', target.value)
+  }
+</script>
+
+<template>
+  <div
+    v-bind="$attrs"
+    :data-testid="testId"
+    :data-disabled="disabled || null"
+    :data-invalid="invalid || null"
+    :data-required="required || null"
+    class="flex flex-col gap-[var(--spacing-xs)] w-full"
+  >
+    <Label
+      v-if="label"
+      :value="label"
+      :required="required"
+      :for="resolvedInputId"
+      :data-testid="`${testId}__label`"
+    />
+    <InputGroup
+      :invalid="invalid"
+      :required="required"
+      :disabled="disabled"
+      :data-testid="`${testId}__group`"
+    >
+      <template
+        v-if="$slots['left']"
+        #left
+      >
+        <slot name="left" />
+      </template>
+      <input
+        :id="resolvedInputId"
+        :name="name"
+        :value="modelValue"
+        :placeholder="placeholder"
+        :disabled="disabled"
+        :readonly="readonly"
+        :required="required"
+        :aria-invalid="invalid || undefined"
+        :aria-required="required || undefined"
+        :aria-describedby="describedBy"
+        class="w-full h-full bg-transparent border-0 outline-none focus:ring-0 px-[var(--spacing-md)] text-label-sm text-[var(--text-default)] placeholder:text-[var(--text-muted)] disabled:cursor-not-allowed disabled:text-[var(--text-disabled)]"
+        @input="onInput"
+      />
+      <template
+        v-if="$slots['right']"
+        #right
+      >
+        <slot name="right" />
+      </template>
+    </InputGroup>
+    <HelperText
+      v-if="effectiveHelperText"
+      :id="helperId"
+      :value="effectiveHelperText"
+      :kind="helperKind"
+      :data-testid="`${testId}__helper`"
+    />
+  </div>
+</template>
diff --git a/packages/webkit/src/components/inputs/input-group/input-group.vue b/packages/webkit/src/components/inputs/input-group/input-group.vue
index a51e4de9..b9e9c6ba 100644
--- a/packages/webkit/src/components/inputs/input-group/input-group.vue
+++ b/packages/webkit/src/components/inputs/input-group/input-group.vue
@@ -8,11 +8,14 @@
     invalid?: boolean
     /** Renders the required (warning) border and sets aria-required on the root. */
     required?: boolean
+    /** Renders the disabled visual (muted fill, not-allowed cursor, no focus ring) and sets aria-disabled on the root. Does not propagate to the middle input — the consumer must set the input disabled attribute themselves. */
+    disabled?: boolean
   }
 
   const props = withDefaults(defineProps<Props>(), {
     invalid: false,
-    required: false
+    required: false,
+    disabled: false
   })
 
   defineSlots<{
@@ -36,9 +39,11 @@
     :data-testid="testId"
     :data-invalid="props.invalid || null"
     :data-required="props.required || null"
+    :data-disabled="props.disabled || null"
     :aria-invalid="props.invalid ? 'true' : undefined"
     :aria-required="props.required ? 'true' : undefined"
-    class="relative inline-flex items-center w-full h-8 overflow-hidden rounded-[var(--shape-elements)] border border-[var(--border-default)] bg-[var(--bg-surface)] transition-colors duration-150 ease-out motion-reduce:transition-none [&:not(:focus-within):not([data-invalid]):not([data-required])]:hover:border-[var(--border-strong)] focus-within:outline-none focus-within:ring-2 focus-within:ring-[var(--ring-color)] focus-within:ring-offset-2 focus-within:ring-offset-[var(--bg-canvas)] data-[invalid]:border-[var(--danger-border)] data-[required]:border-[var(--warning-border)]"
+    :aria-disabled="props.disabled ? 'true' : undefined"
+    class="relative inline-flex items-center w-full h-8 overflow-hidden rounded-[var(--shape-elements)] border border-[var(--border-default)] bg-[var(--bg-surface)] transition-colors duration-150 ease-out motion-reduce:transition-none [&:not(:focus-within):not([data-invalid]):not([data-required]):not([data-disabled])]:hover:border-[var(--border-strong)] focus-within:outline-none focus-within:ring-2 focus-within:ring-[var(--ring-color)] focus-within:ring-offset-2 focus-within:ring-offset-[var(--bg-canvas)] data-[invalid]:border-[var(--danger-border)] data-[required]:border-[var(--warning-border)] data-[disabled]:bg-[var(--bg-disabled)] data-[disabled]:text-[var(--text-disabled)] data-[disabled]:cursor-not-allowed data-[disabled]:focus-within:ring-0 data-[disabled]:focus-within:ring-offset-0"
   >
     <div
       v-if="hasLeft"

From 0408de6f52fc1ea07161da5c7acfd945f678be1e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Wed, 1 Jul 2026 12:56:53 -0300
Subject: [PATCH 10/11] [NO-ISSUE] refactor: replace Label Required tag with
 inline *Required indicator

The Required tag (severity=warning size=small) is replaced by inline
text 'asterisk + Required', where the asterisk uses var(--primary)
(orange F3652B) and the word Required uses var(--text-muted). The
asterisk is decorative (aria-hidden=true) so screen readers announce
only 'Required' alongside the label text.

Applies uniformly across every consumer of Label with required=true:
field-text, field-password, field-input-group, field-checkbox,
field-radio, field-switch, field-textarea. Tag component is no longer
imported by label.vue.

Spec body updated (Purpose, Props JSDoc, Tokens, Accessibility);
checksum refreshed to e261b72f (also fixes a pre-existing checksum
drift on label.md that the enforce-spec-exists hook flagged when this
change tried to write).
---
 .specs/label.md                                | 10 ++++++----
 .../src/components/inputs/label/label.vue      | 18 ++++++++++--------
 2 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/.specs/label.md b/.specs/label.md
index ffdd0820..2bf11e46 100644
--- a/.specs/label.md
+++ b/.specs/label.md
@@ -7,7 +7,7 @@ spec_version: 1
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=562-6660
   node_id: 562:6660
-checksum: ece9d2e9709b3d49abc00122991f5409b5e98e3dfe85fc8c1bfcbb0f1add5dfd
+checksum: e261b72fa4b697ec15057be72d4a470106dba9efcf1e3daef9da429ff8d6010e
 created: 2026-06-15
 last_updated: 2026-06-15
 ---
@@ -16,7 +16,7 @@ last_updated: 2026-06-15
 
 ## Purpose
 
-Form-field label that pairs descriptive text with an optional `Required` badge. Renders a native `<label>` element so consumers can associate it with any input via the standard `for` attribute. Use it above (or beside) any input control in the `inputs` category to communicate the field name and whether it must be filled.
+Form-field label that pairs descriptive text with an optional required indicator. Renders a native `<label>` element so consumers can associate it with any input via the standard `for` attribute. Use it above (or beside) any input control in the `inputs` category to communicate the field name and whether it must be filled. The required indicator is rendered inline as `*Required` — the `*` in the primary orange, the word "Required" in muted text — replacing the older `Tag` badge for a lighter typographic signal.
 
 ## Usage
 
@@ -37,7 +37,7 @@ import InputText from '@aziontech/webkit/input-text'
 | Prop | Type | Default | Required | JSDoc |
 |---|---|---|---|---|
 | `value` | `string` | `''` | no | Fallback text when the default slot is empty. |
-| `required` | `boolean` | `false` | no | Appends a `Required` tag next to the label text. |
+| `required` | `boolean` | `false` | no | Appends an inline required indicator (`<span aria-hidden>*</span>Required`) next to the label text. The `*` uses `var(--primary)`; "Required" inherits `var(--text-muted)`. |
 
 ## Events
 
@@ -64,6 +64,8 @@ _none_
 |---|---|
 | typography | `.text-label-sm` |
 | color (text) | `var(--text-default)` |
+| color (required indicator "Required") | `var(--text-muted)` |
+| color (required indicator "*") | `var(--primary)` |
 | gap (required variant) | `var(--spacing-xxs)` |
 
 ## Theme gaps
@@ -76,7 +78,7 @@ _none_
 
 - Root is a native `<label>` element; consumers pass `for="<input-id>"` via attrs to associate it with the corresponding control.
 - Keyboard map: not focusable (decorative wrapper for native `<label>` semantics); clicking the label focuses the associated input via native browser behavior.
-- ARIA: the `Required` indicator is the existing `Tag` component (`severity="warning"`, `size="small"`, content `"Required"`) and is visible text — no extra ARIA needed; consumers that wire the input with `aria-required="true"` keep the programmatic state in sync.
+- ARIA: the required indicator is inline text (`*Required`). The `*` character is decorative and marked `aria-hidden="true"` so screen readers announce only "Required" together with the label text. Consumers that wire the input with `aria-required="true"` keep the programmatic state in sync.
 - Contrast ≥4.5:1 between `var(--text-default)` and `var(--bg-canvas)`; the warning tag inherits its own contrast guarantees.
 - `motion-reduce:transition-none motion-reduce:transform-none` not applicable (no motion).
 - Touch target: label itself is non-interactive; the associated input owns the ≥40×40 px target.
diff --git a/packages/webkit/src/components/inputs/label/label.vue b/packages/webkit/src/components/inputs/label/label.vue
index 3f620fb5..57c6b68f 100644
--- a/packages/webkit/src/components/inputs/label/label.vue
+++ b/packages/webkit/src/components/inputs/label/label.vue
@@ -1,8 +1,6 @@
 <script setup lang="ts">
   import { computed, useAttrs } from 'vue'
 
-  import Tag from '../../tag/tag.vue'
-
   defineOptions({
     name: 'Label',
     inheritAttrs: false
@@ -11,7 +9,7 @@
   interface Props {
     /** Fallback text when the default slot is empty. */
     value?: string
-    /** Appends a `Required` tag next to the label text. */
+    /** Appends a required indicator (an orange asterisk followed by the word "Required") next to the label text. */
     required?: boolean
   }
 
@@ -41,12 +39,16 @@
       <slot v-if="$slots['default']" />
       <template v-else-if="value">{{ value }}</template>
     </span>
-    <Tag
+    <span
       v-if="required"
-      value="Required"
-      severity="warning"
-      size="small"
       :data-testid="`${testId}__required`"
-    />
+      class="text-label-sm text-[var(--text-muted)]"
+    >
+      <span
+        aria-hidden="true"
+        class="text-[var(--primary)]"
+        >*</span
+      >Required
+    </span>
   </label>
 </template>

From 90d5b4c7105236812f40f4e00a83f83e76dc1e43 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Wed, 1 Jul 2026 13:03:28 -0300
Subject: [PATCH 11/11] [NO-ISSUE] fix: format Label required indicator as *
 (Required) with parentheses

Wrap the required word in parentheses and add a space between the
asterisk and the parenthesized text, producing '* (Required)' instead
of the previous '*Required'. The asterisk stays orange (var(--primary))
and (Required) stays muted (var(--text-muted)); the * remains
aria-hidden so screen readers still announce only '(Required)'.

Spec Purpose, Props JSDoc, Tokens, and Accessibility sections updated
to match; checksum refreshed.
---
 .specs/label.md                                       | 10 +++++-----
 packages/webkit/src/components/inputs/label/label.vue |  3 ++-
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/.specs/label.md b/.specs/label.md
index 2bf11e46..e5163f66 100644
--- a/.specs/label.md
+++ b/.specs/label.md
@@ -7,7 +7,7 @@ spec_version: 1
 figma:
   url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=562-6660
   node_id: 562:6660
-checksum: e261b72fa4b697ec15057be72d4a470106dba9efcf1e3daef9da429ff8d6010e
+checksum: 744bbcf186cef0f22e6259417644544988325d4d720b62a0ab2acd7ea2e6b6b7
 created: 2026-06-15
 last_updated: 2026-06-15
 ---
@@ -16,7 +16,7 @@ last_updated: 2026-06-15
 
 ## Purpose
 
-Form-field label that pairs descriptive text with an optional required indicator. Renders a native `<label>` element so consumers can associate it with any input via the standard `for` attribute. Use it above (or beside) any input control in the `inputs` category to communicate the field name and whether it must be filled. The required indicator is rendered inline as `*Required` — the `*` in the primary orange, the word "Required" in muted text — replacing the older `Tag` badge for a lighter typographic signal.
+Form-field label that pairs descriptive text with an optional required indicator. Renders a native `<label>` element so consumers can associate it with any input via the standard `for` attribute. Use it above (or beside) any input control in the `inputs` category to communicate the field name and whether it must be filled. The required indicator is rendered inline as `* (Required)` — the `*` in the primary orange followed by the parenthesized word "(Required)" in muted text — replacing the older `Tag` badge for a lighter typographic signal.
 
 ## Usage
 
@@ -37,7 +37,7 @@ import InputText from '@aziontech/webkit/input-text'
 | Prop | Type | Default | Required | JSDoc |
 |---|---|---|---|---|
 | `value` | `string` | `''` | no | Fallback text when the default slot is empty. |
-| `required` | `boolean` | `false` | no | Appends an inline required indicator (`<span aria-hidden>*</span>Required`) next to the label text. The `*` uses `var(--primary)`; "Required" inherits `var(--text-muted)`. |
+| `required` | `boolean` | `false` | no | Appends an inline required indicator (`<span aria-hidden>*</span> (Required)`) next to the label text. The `*` uses `var(--primary)`; "(Required)" inherits `var(--text-muted)`. |
 
 ## Events
 
@@ -64,7 +64,7 @@ _none_
 |---|---|
 | typography | `.text-label-sm` |
 | color (text) | `var(--text-default)` |
-| color (required indicator "Required") | `var(--text-muted)` |
+| color (required indicator "(Required)") | `var(--text-muted)` |
 | color (required indicator "*") | `var(--primary)` |
 | gap (required variant) | `var(--spacing-xxs)` |
 
@@ -78,7 +78,7 @@ _none_
 
 - Root is a native `<label>` element; consumers pass `for="<input-id>"` via attrs to associate it with the corresponding control.
 - Keyboard map: not focusable (decorative wrapper for native `<label>` semantics); clicking the label focuses the associated input via native browser behavior.
-- ARIA: the required indicator is inline text (`*Required`). The `*` character is decorative and marked `aria-hidden="true"` so screen readers announce only "Required" together with the label text. Consumers that wire the input with `aria-required="true"` keep the programmatic state in sync.
+- ARIA: the required indicator is inline text (`* (Required)`). The `*` character is decorative and marked `aria-hidden="true"` so screen readers announce only "(Required)" together with the label text. Consumers that wire the input with `aria-required="true"` keep the programmatic state in sync.
 - Contrast ≥4.5:1 between `var(--text-default)` and `var(--bg-canvas)`; the warning tag inherits its own contrast guarantees.
 - `motion-reduce:transition-none motion-reduce:transform-none` not applicable (no motion).
 - Touch target: label itself is non-interactive; the associated input owns the ≥40×40 px target.
diff --git a/packages/webkit/src/components/inputs/label/label.vue b/packages/webkit/src/components/inputs/label/label.vue
index 57c6b68f..77e3e97c 100644
--- a/packages/webkit/src/components/inputs/label/label.vue
+++ b/packages/webkit/src/components/inputs/label/label.vue
@@ -48,7 +48,8 @@
         aria-hidden="true"
         class="text-[var(--primary)]"
         >*</span
-      >Required
+      >
+      (Required)
     </span>
   </label>
 </template>