@flowstack-ui/brick 0.1.6 → 0.1.11

package/dist/agents/multi-select.json

@@ -0,0 +1,93 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "multi-select",
+  "name": "MultiSelect",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present several selected predefined values in a compact finished control while Atom owns array state, popup listbox focus, persistent toggling, positioning, validation, and native multiple-select submission.",
+  "useWhen": [
+    "A person chooses zero or more values from a predefined moderate collection that should remain collapsed until requested."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A short choice set should stay visible, only one value is allowed, or editable filtering, arbitrary tags, creation, range selection, or virtualization is required.",
+      "useInstead": "CheckboxGroup, Select, Combobox, or a documented Brick gap or higher-layer specialized control"
+    }
+  ],
+  "composition": [
+    "Compose MultiSelect.Root with a named button Trigger containing Value and optional Icon, then exactly one Content or Listbox with stable uniquely valued Items and ItemText. Add Portal, Viewport, groups and labels, separators, scroll buttons, indicators, and a direct Arrow only as required.",
+    "Use sm, md, or lg consistently with adjacent button-like controls. Keep selected values, persistence, remote data, and application effects at the application boundary."
+  ],
+  "rules": [
+    {
+      "id": "multi-select-predefined-values",
+      "level": "must",
+      "statement": "Use MultiSelect only for several predefined values; do not add editable filtering, arbitrary tags, commands, destinations, range selection, or virtualization."
+    },
+    {
+      "id": "multi-select-semantics",
+      "level": "must",
+      "statement": "Keep Trigger a separately named button rather than role=combobox and keep Content or Listbox as the focusable aria-multiselectable owner of required and read-only semantics."
+    },
+    {
+      "id": "multi-select-array-state",
+      "level": "must",
+      "statement": "Use deduplicated arrays for value and defaultValue, route controlled changes through onValueChange, and keep the popup open while Items toggle."
+    },
+    {
+      "id": "multi-select-item-text",
+      "level": "must",
+      "statement": "Give every Item a stable unique value and ItemText or label so summaries, option names, typeahead, and native options remain complete while the popup is closed."
+    },
+    {
+      "id": "multi-select-keyboard-form",
+      "level": "must",
+      "statement": "Preserve popup focus, Arrow/Home/End, typeahead, Space/Enter toggling without close, Escape focus restoration, Tab dismissal, disabled skipping, native repeated-value submission, required validity, external form, and reset."
+    },
+    {
+      "id": "multi-select-responsive",
+      "level": "must",
+      "statement": "Keep Trigger, summaries, and collision-aware popup contained under long localization, narrow widths, zoom, and RTL; do not place removal buttons inside the v1 button Trigger."
+    },
+    {
+      "id": "multi-select-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus multi-select.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Giving Trigger combobox semantics, using selected summary as its name, closing after each toggle, or deriving native options only from an open popup.",
+      "correction": "Preserve the named button/listbox model, persistent toggling, static Item registration, and complete native option contract."
+    },
+    {
+      "mistake": "Adding text entry, arbitrary tag creation, interactive descendants, or application persistence inside the component.",
+      "correction": "Keep predefined noninteractive Items and choose an approved editable higher-layer pattern or record the missing Brick capability."
+    }
+  ],
+  "validation": [
+    "Verify Trigger and listbox names, controlled and uncontrolled arrays and open state, deduplication, zero/one/many summaries and renderValue, popup focus, Arrow/Home/End, typeahead, Space/Enter without close, disabled Items, Escape, Tab, outside activation, and focus restoration.",
+    "Verify read-only on the listbox, Field relationships, hidden multiple-select options and repeated submission, required inline/native validation, external form, reset, groups, indicators, Viewport, scroll buttons, Portal, direction, collision placement, and nested modal behavior.",
+    "Verify all sizes, long summaries and option labels, narrow widths, zoom, RTL, touch targets, light and dark appearance, forced colors, and button-like control alignment."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "multi-select",
+      "versionPolicy": "installed-exact"
+    },
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "listbox",
+      "versionPolicy": "installed-exact"
+    },
+    "field",
+    "form",
+    "select",
+    "combobox",
+    "checkbox-group"
+  ]
+}

package/dist/agents/multi-select.md

@@ -0,0 +1,49 @@
+# MultiSelect agent guide
+
+## Purpose
+
+Present several selected predefined values in a compact finished control while Atom owns array state, popup listbox focus, persistent toggling, positioning, validation, and native multiple-select submission.
+
+## Use when
+
+- A person chooses zero or more values from a predefined moderate collection that should remain collapsed until requested.
+
+## Choose something else when
+
+- A short choice set should stay visible, only one value is allowed, or editable filtering, arbitrary tags, creation, range selection, or virtualization is required. Use CheckboxGroup, Select, Combobox, or a documented Brick gap or higher-layer specialized control.
+
+## Required composition
+
+- Compose MultiSelect.Root with a named button Trigger containing Value and optional Icon, then exactly one Content or Listbox with stable uniquely valued Items and ItemText. Add Portal, Viewport, groups and labels, separators, scroll buttons, indicators, and a direct Arrow only as required.
+- Use sm, md, or lg consistently with adjacent button-like controls. Keep selected values, persistence, remote data, and application effects at the application boundary.
+
+## Rules
+
+- **MUST:** Use MultiSelect only for several predefined values; do not add editable filtering, arbitrary tags, commands, destinations, range selection, or virtualization.
+- **MUST:** Keep Trigger a separately named button rather than role=combobox and keep Content or Listbox as the focusable aria-multiselectable owner of required and read-only semantics.
+- **MUST:** Use deduplicated arrays for value and defaultValue, route controlled changes through onValueChange, and keep the popup open while Items toggle.
+- **MUST:** Give every Item a stable unique value and ItemText or label so summaries, option names, typeahead, and native options remain complete while the popup is closed.
+- **MUST:** Preserve popup focus, Arrow/Home/End, typeahead, Space/Enter toggling without close, Escape focus restoration, Tab dismissal, disabled skipping, native repeated-value submission, required validity, external form, and reset.
+- **MUST:** Keep Trigger, summaries, and collision-aware popup contained under long localization, narrow widths, zoom, and RTL; do not place removal buttons inside the v1 button Trigger.
+- **MUST:** Load styles.css or core.css plus multi-select.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Giving Trigger combobox semantics, using selected summary as its name, closing after each toggle, or deriving native options only from an open popup. **Instead:** Preserve the named button/listbox model, persistent toggling, static Item registration, and complete native option contract.
+- **Avoid:** Adding text entry, arbitrary tag creation, interactive descendants, or application persistence inside the component. **Instead:** Keep predefined noninteractive Items and choose an approved editable higher-layer pattern or record the missing Brick capability.
+
+## Validation checklist
+
+- Verify Trigger and listbox names, controlled and uncontrolled arrays and open state, deduplication, zero/one/many summaries and renderValue, popup focus, Arrow/Home/End, typeahead, Space/Enter without close, disabled Items, Escape, Tab, outside activation, and focus restoration.
+- Verify read-only on the listbox, Field relationships, hidden multiple-select options and repeated submission, required inline/native validation, external form, reset, groups, indicators, Viewport, scroll buttons, Portal, direction, collision placement, and nested modal behavior.
+- Verify all sizes, long summaries and option labels, narrow widths, zoom, RTL, touch targets, light and dark appearance, forced colors, and button-like control alignment.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/multi-select`
+- `@flowstack-ui/atom/agents/listbox`
+- `field`
+- `form`
+- `select`
+- `combobox`
+- `checkbox-group`

package/dist/agents/nav-list.json

@@ -16,7 +16,7 @@
     }
   ],
   "composition": [
-    "Compose Root > List > Item > Link; use SectionLabel for static groups and add SectionTrigger plus SectionContent only for real collapsible groups. When repeated rows need Dividers, each Item owns its complete row or collapsible Section before the following boundary."
+    "Compose Root > List > Item > Link; use SectionLabel for static groups and add SectionTrigger plus SectionContent only for real collapsible groups. Pass decorative artwork directly to Link or SectionTrigger startIcon so NavList owns its size and alignment. When repeated rows need Dividers, each Item owns its complete row or collapsible Section before the following boundary."
   ],
   "rules": [
     {
@@ -29,6 +29,16 @@
       "level": "must",
       "statement": "Use NavList's section and item anatomy rather than rebuilding rows, badges, icons, and collapse behavior with arbitrary divs."
     },
+    {
+      "id": "nav-list-icons",
+      "level": "must",
+      "statement": "Pass decorative artwork directly to Link or SectionTrigger startIcon; those parts own the wrapper, size, and first-label-line alignment. Do not compensate with consumer margins or transforms."
+    },
+    {
+      "id": "nav-list-meaningful-content",
+      "level": "must",
+      "statement": "Keep decorative artwork in startIcon/endIcon; when a count or Badge is meaningful content, compose it with the label inside one Brick HStack within Link so the complete row remains one destination."
+    },
     {
       "id": "nav-list-group-boundary",
       "level": "must",
@@ -37,7 +47,7 @@
     {
       "id": "nav-list-shell-alignment",
       "level": "must",
-      "statement": "Use the logical row-padding tokens when labels and trailing artwork need independent alignment with a surrounding shell; do not shift indicators with margins or transforms."
+      "statement": "Let SectionLabel use NavList's size-aware typography and logical leading-column alignment; use the logical row-padding tokens only when navigation rows need independent alignment with a surrounding shell, and do not shift indicators with margins or transforms."
     },
     {
       "id": "nav-list-css",
@@ -47,12 +57,12 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Using buttons for routes, adding a collapsible trigger that controls no content, placing a Divider between a trigger and its controlled destinations, or moving disclosure indicators with positional CSS.",
-      "correction": "Use Link for destinations, SectionLabel alone for static groups, keep a collapsible Section intact before its boundary, and use the logical row-padding tokens for shell alignment."
+      "mistake": "Using buttons for routes, wrapping decorative artwork in a second Icon size owner, placing meaningful metadata in aria-hidden icon slots, adding a collapsible trigger that controls no content, placing a Divider between a trigger and the SectionContent that trigger controls, or moving disclosure indicators with positional CSS.",
+      "correction": "Use Link for destinations, pass raw decorative artwork to startIcon, compose meaningful row content inside Link, keep a collapsible Section intact before its boundary, and let SectionLabel own group-title alignment."
     }
   ],
   "validation": [
-    "Check current, hover, focus, collapsed, expanded, complete-group divider placement, long labels, icons, counts, zoom, narrow widths, and RTL.",
+    "Check current, hover, focus, collapsed, expanded, disclosure motion, section-label alignment, complete-group divider placement, long labels, icons, counts, zoom, narrow widths, and RTL.",
     "Confirm links and section relationships remain semantic and CSS is loaded."
   ],
   "related": [

package/dist/agents/nav-list.md

@@ -14,23 +14,25 @@ Style persistent route navigation with current state, optional section labels, a
 
 ## Required composition
 
-- Compose Root > List > Item > Link; use SectionLabel for static groups and add SectionTrigger plus SectionContent only for real collapsible groups. When repeated rows need Dividers, each Item owns its complete row or collapsible Section before the following boundary.
+- Compose Root > List > Item > Link; use SectionLabel for static groups and add SectionTrigger plus SectionContent only for real collapsible groups. Pass decorative artwork directly to Link or SectionTrigger startIcon so NavList owns its size and alignment. When repeated rows need Dividers, each Item owns its complete row or collapsible Section before the following boundary.
 
 ## Rules
 
 - **MUST:** Set current destination state from the route and keep route items as links.
 - **MUST:** Use NavList's section and item anatomy rather than rebuilding rows, badges, icons, and collapse behavior with arbitrary divs.
+- **MUST:** Pass decorative artwork directly to Link or SectionTrigger startIcon; those parts own the wrapper, size, and first-label-line alignment. Do not compensate with consumer margins or transforms.
+- **MUST:** Keep decorative artwork in startIcon/endIcon; when a count or Badge is meaningful content, compose it with the label inside one Brick HStack within Link so the complete row remains one destination.
 - **MUST:** Place a Divider after the complete navigation item or collapsible section it separates; never place it between a SectionTrigger and the SectionContent that trigger controls, and keep repeated boundaries under one consistent layout owner.
-- **MUST:** Use the logical row-padding tokens when labels and trailing artwork need independent alignment with a surrounding shell; do not shift indicators with margins or transforms.
+- **MUST:** Let SectionLabel use NavList's size-aware typography and logical leading-column alignment; use the logical row-padding tokens only when navigation rows need independent alignment with a surrounding shell, and do not shift indicators with margins or transforms.
 - **MUST:** Load styles.css or core.css plus nav-list.css.
 
 ## Common mistakes
 
-- **Avoid:** Using buttons for routes, adding a collapsible trigger that controls no content, placing a Divider between a trigger and its controlled destinations, or moving disclosure indicators with positional CSS. **Instead:** Use Link for destinations, SectionLabel alone for static groups, keep a collapsible Section intact before its boundary, and use the logical row-padding tokens for shell alignment.
+- **Avoid:** Using buttons for routes, wrapping decorative artwork in a second Icon size owner, placing meaningful metadata in aria-hidden icon slots, adding a collapsible trigger that controls no content, placing a Divider between a trigger and the SectionContent that trigger controls, or moving disclosure indicators with positional CSS. **Instead:** Use Link for destinations, pass raw decorative artwork to startIcon, compose meaningful row content inside Link, keep a collapsible Section intact before its boundary, and let SectionLabel own group-title alignment.
 
 ## Validation checklist
 
-- Check current, hover, focus, collapsed, expanded, complete-group divider placement, long labels, icons, counts, zoom, narrow widths, and RTL.
+- Check current, hover, focus, collapsed, expanded, disclosure motion, section-label alignment, complete-group divider placement, long labels, icons, counts, zoom, narrow widths, and RTL.
 - Confirm links and section relationships remain semantic and CSS is loaded.
 
 ## Related guidance

package/dist/agents/notification-badge.json

@@ -0,0 +1,88 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "notification-badge",
+  "name": "NotificationBadge",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Overlay a Brick-owned visual count or dot on exactly one element while Atom Badge supplies only the passive span host and the child or nearby content owns all accessible notification meaning.",
+  "useWhen": [
+    "One icon, Avatar, Button, or other single element needs compact visual notification metadata whose full meaning is present in the owning control name or nearby text."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content is an inline label or status, must announce automatically, performs an action itself, or the count would be the only accessible notification meaning.",
+      "useInstead": "Badge, Status, a deliberately chosen live-region pattern, Button, or visible Text"
+    }
+  ],
+  "composition": [
+    "Wrap exactly one React element in NotificationBadge and choose either count mode or dot mode, then choose tone, size, logical placement, and overlap for the child's shape. Include count or status meaning in the child control's accessible name or nearby visible status text.",
+    "Use count with a finite non-negative integer and deliberate max/showZero policy, or dot=true without count-only props. Keep child sizing, clipping, responsive placement, live announcements, and state effects outside NotificationBadge."
+  ],
+  "rules": [
+    {
+      "id": "notification-badge-one-child",
+      "level": "must",
+      "statement": "Wrap exactly one React element and keep NotificationBadge passive; the child retains its own element, interaction, focus, semantics, and accessible name."
+    },
+    {
+      "id": "notification-badge-brick-owner",
+      "level": "must",
+      "statement": "Treat the visual indicator, count normalization, maximum formatting, visibility, logical placement, overlap, and overlay geometry as Brick-owned; Atom Badge supplies only a passive span root, not notification behavior."
+    },
+    {
+      "id": "notification-badge-mode",
+      "level": "must",
+      "statement": "Choose either dot mode or count mode; use only finite non-negative integer counts, understand invalid max falls back to 99, and use showZero deliberately because zero otherwise hides."
+    },
+    {
+      "id": "notification-badge-accessible-context",
+      "level": "must",
+      "statement": "Keep the private indicator aria-hidden and include meaningful count or status in the owning control's accessible name/description or nearby visible text because an overlaid sibling is not incorporated automatically."
+    },
+    {
+      "id": "notification-badge-live-boundary",
+      "level": "must",
+      "statement": "Do not assume changing count announces or add live semantics to the private indicator; use one deliberate application-owned live path only when urgency and frequency justify it."
+    },
+    {
+      "id": "notification-badge-responsive",
+      "level": "must",
+      "statement": "Choose circular or rectangular overlap from the child geometry, preserve logical placement in RTL, and verify child clipping, focus rings, count growth, zoom, and responsive size without using physical offsets."
+    },
+    {
+      "id": "notification-badge-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus badge.css and the stylesheet for the wrapped Brick child."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using the visual count as the only name, expecting it to announce, making the wrapper interactive, or passing count and dot together.",
+      "correction": "Name the owning control or provide visible text, keep announcements application-owned, leave interaction on the child, and choose one visual mode."
+    },
+    {
+      "mistake": "Using physical placement for RTL, circular overlap on a rectangular child by habit, or allowing the child to clip the indicator or focus ring.",
+      "correction": "Choose logical placement and overlap from actual geometry and verify the complete composed boundary at responsive sizes."
+    }
+  ],
+  "validation": [
+    "Verify one child; count and dot modes; valid, zero, invalid, and above-max counts; fallback max; showZero; invisible; all tones/sizes/placements/overlaps; root ref; native span props; and absence of unsupported asChild.",
+    "Verify indicator is aria-hidden, child semantics and focus remain intact, count meaning appears exactly once in the owning name/description or visible text, updates do not announce implicitly, and any application live path is not duplicated.",
+    "Verify single-digit circles and multi-digit pills, logical RTL placement, rectangular/circular overlap, child clipping, focus visibility, narrow layout, zoom, light/dark appearance, forced colors, and wrapped Avatar/Button/Icon geometry."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "badge",
+      "versionPolicy": "installed-exact"
+    },
+    "badge",
+    "avatar",
+    "button",
+    "icon-button",
+    "status",
+    "text"
+  ]
+}

package/dist/agents/notification-badge.md

@@ -0,0 +1,49 @@
+# NotificationBadge agent guide
+
+## Purpose
+
+Overlay a Brick-owned visual count or dot on exactly one element while Atom Badge supplies only the passive span host and the child or nearby content owns all accessible notification meaning.
+
+## Use when
+
+- One icon, Avatar, Button, or other single element needs compact visual notification metadata whose full meaning is present in the owning control name or nearby text.
+
+## Choose something else when
+
+- The content is an inline label or status, must announce automatically, performs an action itself, or the count would be the only accessible notification meaning. Use Badge, Status, a deliberately chosen live-region pattern, Button, or visible Text.
+
+## Required composition
+
+- Wrap exactly one React element in NotificationBadge and choose either count mode or dot mode, then choose tone, size, logical placement, and overlap for the child's shape. Include count or status meaning in the child control's accessible name or nearby visible status text.
+- Use count with a finite non-negative integer and deliberate max/showZero policy, or dot=true without count-only props. Keep child sizing, clipping, responsive placement, live announcements, and state effects outside NotificationBadge.
+
+## Rules
+
+- **MUST:** Wrap exactly one React element and keep NotificationBadge passive; the child retains its own element, interaction, focus, semantics, and accessible name.
+- **MUST:** Treat the visual indicator, count normalization, maximum formatting, visibility, logical placement, overlap, and overlay geometry as Brick-owned; Atom Badge supplies only a passive span root, not notification behavior.
+- **MUST:** Choose either dot mode or count mode; use only finite non-negative integer counts, understand invalid max falls back to 99, and use showZero deliberately because zero otherwise hides.
+- **MUST:** Keep the private indicator aria-hidden and include meaningful count or status in the owning control's accessible name/description or nearby visible text because an overlaid sibling is not incorporated automatically.
+- **MUST:** Do not assume changing count announces or add live semantics to the private indicator; use one deliberate application-owned live path only when urgency and frequency justify it.
+- **MUST:** Choose circular or rectangular overlap from the child geometry, preserve logical placement in RTL, and verify child clipping, focus rings, count growth, zoom, and responsive size without using physical offsets.
+- **MUST:** Load styles.css or core.css plus badge.css and the stylesheet for the wrapped Brick child.
+
+## Common mistakes
+
+- **Avoid:** Using the visual count as the only name, expecting it to announce, making the wrapper interactive, or passing count and dot together. **Instead:** Name the owning control or provide visible text, keep announcements application-owned, leave interaction on the child, and choose one visual mode.
+- **Avoid:** Using physical placement for RTL, circular overlap on a rectangular child by habit, or allowing the child to clip the indicator or focus ring. **Instead:** Choose logical placement and overlap from actual geometry and verify the complete composed boundary at responsive sizes.
+
+## Validation checklist
+
+- Verify one child; count and dot modes; valid, zero, invalid, and above-max counts; fallback max; showZero; invisible; all tones/sizes/placements/overlaps; root ref; native span props; and absence of unsupported asChild.
+- Verify indicator is aria-hidden, child semantics and focus remain intact, count meaning appears exactly once in the owning name/description or visible text, updates do not announce implicitly, and any application live path is not duplicated.
+- Verify single-digit circles and multi-digit pills, logical RTL placement, rectangular/circular overlap, child clipping, focus visibility, narrow layout, zoom, light/dark appearance, forced colors, and wrapped Avatar/Button/Icon geometry.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/badge`
+- `badge`
+- `avatar`
+- `button`
+- `icon-button`
+- `status`
+- `text`

package/dist/agents/number-input.json

@@ -0,0 +1,89 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "number-input",
+  "name": "NumberInput",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present finished exact numeric entry with typing and step actions while Atom owns parsing, formatting, limits, spinbutton keyboard behavior, validation, and numeric form submission.",
+  "useWhen": [
+    "A value is genuinely numeric and a person should type an exact value or adjust it in known increments."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Digits identify something, adjustment by feel is primary, a small fixed set is valid, or the value is read-only completion.",
+      "useInstead": "Input, Slider, Select or RadioGroup, or Progress"
+    }
+  ],
+  "composition": [
+    "Compose a visibly labelled Field with NumberInput.Root containing exactly one NumberInput.Input plus optional NumberInput.Increment and NumberInput.Decrement. Name both step actions because their default artwork is decorative.",
+    "Choose outline, soft, or underline plus sm, md, or lg and an allowed shape on Root. Keep formatter and parser reversible, use number or null controlled state, and keep units and application quantity policy outside the component."
+  ],
+  "rules": [
+    {
+      "id": "number-input-numeric-domain",
+      "level": "must",
+      "statement": "Use NumberInput only for values that can be meaningfully stepped and clamped; postal codes, phone numbers, account numbers, and similar identifiers remain Input values."
+    },
+    {
+      "id": "number-input-one-input",
+      "level": "must",
+      "statement": "Render exactly one NumberInput.Input inside Root and keep Increment and Decrement inside that same Root so Atom retains numeric state, focus, limits, and aria-controls ownership."
+    },
+    {
+      "id": "number-input-state-format",
+      "level": "must",
+      "statement": "Use number or null with value and onValueChange for controlled state, preserve intermediate editing, keep formatter and parser reversible, choose positive step and suitable precision, and decide clampOnBlur deliberately."
+    },
+    {
+      "id": "number-input-accessibility",
+      "level": "must",
+      "statement": "Give Input a visible Field label or equivalent accessible name and give Increment and Decrement localized action names while preserving spinbutton ARIA, Arrow/Page/Home/End keys, native validity, and pointer focus retention."
+    },
+    {
+      "id": "number-input-form",
+      "level": "must",
+      "statement": "Keep the visible Input as validity owner and Root's named parsed value as the submission contract, including external form association, Field reporting, reset, disabled, read-only, required, and invalid state."
+    },
+    {
+      "id": "number-input-responsive",
+      "level": "must",
+      "statement": "Keep the shrinkable input and fixed logical-end action column contained at narrow widths and in RTL; preserve coarse-pointer step targets and do not use viewport width as a touch proxy."
+    },
+    {
+      "id": "number-input-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus number-input.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using NumberInput for digit-like identifiers, rendering more than one Input, formatting without a matching parser, or submitting display text as the numeric value.",
+      "correction": "Choose Input for identifiers, keep one compound Input, make parsing and formatting symmetric, and preserve Atom's parsed form contract."
+    },
+    {
+      "mistake": "Leaving decorative step buttons unnamed or adding unit selection and business limits inside the component.",
+      "correction": "Name both actions and keep units, inventory rules, calculations, and other application policy at the application boundary."
+    }
+  ],
+  "validation": [
+    "Verify controlled number and null state, uncontrolled default, intermediate typing, parsing, formatting, precision, min/max, clampOnBlur, step and largeStep, Arrow/Page/Home/End, empty state, boundary action state, and pointer/touch focus preservation.",
+    "Verify visible naming, localized step-action names, required and numeric native validity, Field reporting, named parsed submission, external form, reset, disabled/read-only behavior, refs, native props, and custom action children.",
+    "Verify outline, soft, and underline recipes; all sizes and allowed shapes; full-width and intrinsic layouts; narrow width, coarse pointer, RTL, zoom, forced colors, light and dark appearance, focus, invalid, and disabled paint."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "number-input",
+      "versionPolicy": "installed-exact"
+    },
+    "input",
+    "slider",
+    "progress",
+    "select",
+    "radio-group",
+    "field",
+    "form"
+  ]
+}

package/dist/agents/number-input.md

@@ -0,0 +1,50 @@
+# NumberInput agent guide
+
+## Purpose
+
+Present finished exact numeric entry with typing and step actions while Atom owns parsing, formatting, limits, spinbutton keyboard behavior, validation, and numeric form submission.
+
+## Use when
+
+- A value is genuinely numeric and a person should type an exact value or adjust it in known increments.
+
+## Choose something else when
+
+- Digits identify something, adjustment by feel is primary, a small fixed set is valid, or the value is read-only completion. Use Input, Slider, Select or RadioGroup, or Progress.
+
+## Required composition
+
+- Compose a visibly labelled Field with NumberInput.Root containing exactly one NumberInput.Input plus optional NumberInput.Increment and NumberInput.Decrement. Name both step actions because their default artwork is decorative.
+- Choose outline, soft, or underline plus sm, md, or lg and an allowed shape on Root. Keep formatter and parser reversible, use number or null controlled state, and keep units and application quantity policy outside the component.
+
+## Rules
+
+- **MUST:** Use NumberInput only for values that can be meaningfully stepped and clamped; postal codes, phone numbers, account numbers, and similar identifiers remain Input values.
+- **MUST:** Render exactly one NumberInput.Input inside Root and keep Increment and Decrement inside that same Root so Atom retains numeric state, focus, limits, and aria-controls ownership.
+- **MUST:** Use number or null with value and onValueChange for controlled state, preserve intermediate editing, keep formatter and parser reversible, choose positive step and suitable precision, and decide clampOnBlur deliberately.
+- **MUST:** Give Input a visible Field label or equivalent accessible name and give Increment and Decrement localized action names while preserving spinbutton ARIA, Arrow/Page/Home/End keys, native validity, and pointer focus retention.
+- **MUST:** Keep the visible Input as validity owner and Root's named parsed value as the submission contract, including external form association, Field reporting, reset, disabled, read-only, required, and invalid state.
+- **MUST:** Keep the shrinkable input and fixed logical-end action column contained at narrow widths and in RTL; preserve coarse-pointer step targets and do not use viewport width as a touch proxy.
+- **MUST:** Load styles.css or core.css plus number-input.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Using NumberInput for digit-like identifiers, rendering more than one Input, formatting without a matching parser, or submitting display text as the numeric value. **Instead:** Choose Input for identifiers, keep one compound Input, make parsing and formatting symmetric, and preserve Atom's parsed form contract.
+- **Avoid:** Leaving decorative step buttons unnamed or adding unit selection and business limits inside the component. **Instead:** Name both actions and keep units, inventory rules, calculations, and other application policy at the application boundary.
+
+## Validation checklist
+
+- Verify controlled number and null state, uncontrolled default, intermediate typing, parsing, formatting, precision, min/max, clampOnBlur, step and largeStep, Arrow/Page/Home/End, empty state, boundary action state, and pointer/touch focus preservation.
+- Verify visible naming, localized step-action names, required and numeric native validity, Field reporting, named parsed submission, external form, reset, disabled/read-only behavior, refs, native props, and custom action children.
+- Verify outline, soft, and underline recipes; all sizes and allowed shapes; full-width and intrinsic layouts; narrow width, coarse pointer, RTL, zoom, forced colors, light and dark appearance, focus, invalid, and disabled paint.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/number-input`
+- `input`
+- `slider`
+- `progress`
+- `select`
+- `radio-group`
+- `field`
+- `form`

package/dist/agents/otp-field.json

@@ -0,0 +1,87 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "otp-field",
+  "name": "OTPField",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present one short verification, recovery, or pairing code as finished segmented entry while Atom owns filtering, paste distribution, roving focus, completion, validation, reset, and combined-value submission.",
+  "useWhen": [
+    "A person enters or pastes a short one-time code supplied through another channel into visually separated cells."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value is a reusable password, permanent PIN, numeric quantity, arbitrary identifier, or ordinary variable-length text.",
+      "useInstead": "PasswordToggleField, NumberInput, or Input according to the actual entry job"
+    }
+  ],
+  "composition": [
+    "Compose one visibly labelled Field with OTPField.Root, then render exactly one OTPField.Input for each normalized length position in stable logical source order. Add aria-hidden Separator only for deliberate visual grouping; layout wrappers may group cells without creating separate values.",
+    "Give Root one accessible group name, character type, length, and submission name. Localize getInputLabel for every position and treat autoSubmit and autoFocus as explicit application workflow decisions."
+  ],
+  "rules": [
+    {
+      "id": "otp-field-one-value",
+      "level": "must",
+      "statement": "Treat all cells as one logical code, match visible Input count and order to Root length, and never create independent application state, validation, or submission names for each cell."
+    },
+    {
+      "id": "otp-field-filter",
+      "level": "must",
+      "statement": "Choose numeric, alphabetic, alphanumeric, or a safe custom pattern that accepts exactly the intended characters and preserve the same filtering for typing and paste."
+    },
+    {
+      "id": "otp-field-labels",
+      "level": "must",
+      "statement": "Name Root through Field or native ARIA, localize every generated position label, keep Separator decorative, and do not add unsupported aria-required to role=group."
+    },
+    {
+      "id": "otp-field-focus-input",
+      "level": "must",
+      "statement": "Preserve one roving Tab stop, render-order registration, replacement and advance, Arrow/Home/End, Backspace/Delete, complete-code paste, disabled/read-only state, and logical source order in RTL."
+    },
+    {
+      "id": "otp-field-completion",
+      "level": "must",
+      "statement": "Enable autoSubmit only when a complete accepted code should intentionally submit the associated form, with application-owned pending, verification, error, retry, and focus recovery behavior; choose autoFocus just as deliberately."
+    },
+    {
+      "id": "otp-field-form",
+      "level": "must",
+      "statement": "Keep required validity on the first visible cell and Root's named combined value submission-only, including Field invalid mirroring, external form association, and uncontrolled reset."
+    },
+    {
+      "id": "otp-field-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus otp-field.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Building unrelated character inputs, rendering a different cell count than length, blocking paste, reversing cells in RTL, leaving generated labels unlocalized, or auto-submitting by habit.",
+      "correction": "Use one named OTPField value, align cells to length and logical order, preserve Atom entry behavior, localize labels, and make submission an explicit application decision."
+    },
+    {
+      "mistake": "Putting code delivery, expiry, resend, attempt limits, rate limiting, or verification inside the component.",
+      "correction": "Keep security and workflow policy in the application or service and let OTPField report value and completion only."
+    }
+  ],
+  "validation": [
+    "Verify controlled and uncontrolled full value, length, render-order and explicit indices, all filters, typing replacement, accepted paste distribution, Backspace/Delete, Arrow/Home/End, one roving Tab stop, deliberate autoFocus, mask display, disabled/read-only behavior, and localized cell labels.",
+    "Verify onComplete timing, intentional autoSubmit, Root and Field naming/descriptions, required validity on the first cell, invalid state across cells, inline/native validation focus, combined named value, external form, reset, separators, native props, render composition, and refs.",
+    "Verify deliberate wrapping and grouping, 320 CSS pixels, 200% text, 400% zoom, RTL logical order, touch targets, long localized labels, focus visibility, forced colors, and every supported appearance."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "otp-field",
+      "versionPolicy": "installed-exact"
+    },
+    "password-toggle-field",
+    "number-input",
+    "input",
+    "field",
+    "form"
+  ]
+}