@flowstack-ui/brick 0.1.9 → 0.1.12

package/dist/agents/menubar.md

@@ -0,0 +1,54 @@
+# Menubar agent guide
+
+## Purpose
+
+Present a finished persistent application command strip with coordinated top-level menus while Atom owns menubar semantics, roving focus, adjacent-menu handoff, and shared Menu behavior.
+
+## Use when
+
+- A desktop-like application has several persistent command categories such as File, Edit, and View that must behave as one keyboard menubar.
+
+## Choose something else when
+
+- There is one temporary command menu, ordinary website navigation, a route list, or a toolbar of immediately executable controls. Use DropdownMenu, NavigationMenu or NavList, or Toolbar.
+- The application needs responsive mobile replacement or overflow orchestration. Use An application-owned composition using DropdownMenu, Drawer, or another appropriate command surface.
+
+## Required composition
+
+- Give Menubar.Root an accessible name and compose one or more uniquely valued Menubar.Menu scopes, each containing Menubar.Trigger and portalled Menubar.Content. Build Content from the shared command, selection, grouping, separator, static row, and paired submenu anatomy.
+- Root owns sm, md, or lg density and horizontal or vertical orientation; Content and SubContent inherit that density. Reproduce any local Appearance scope on each portalled visual root.
+
+## Rules
+
+- **MUST:** Use Menubar only for persistent application command categories, not website navigation, page tabs, route-current state, or a responsive application shell.
+- **MUST:** Give the role=menubar Root an accessible name and keep every top-level Trigger as its role=menuitem child with one Atom-owned roving tab stop.
+- **MUST:** Give every top-level Menu a unique value and keep its Trigger and Content within that Menu scope so controlled value and adjacent-menu handoff remain deterministic.
+- **MUST:** Match orientation to the visible Root arrangement and preserve direction-aware Arrow movement, Home/End, first and last item opening, adjacent handoff, and nested submenu keys in LTR and RTL.
+- **MUST:** Preserve uniquely valued item roles, real focus, typeahead, disabled navigation, checkbox and radio state, closeOnSelect, paired submenus, whole-root Tab exit, Escape restoration, and parent-modal ownership.
+- **MUST:** Use Leading, ItemLabel, Description, Shortcut, ItemIndicator, and tone=danger for their documented jobs; shortcuts are visual hints and Menubar does not register global commands.
+- **MUST:** Do not automatically wrap, collapse, or change Menubar semantics at a breakpoint; applications own an explicit scrolling region or a separately selected mobile command surface.
+- **MUST:** When Content leaves a local Appearance scope through Portal, reproduce that scope on the portalled visual root or target a container inside it.
+- **MUST:** Load styles.css or core.css plus menubar.css and every composed child component stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Using Menubar as styled website navigation, omitting Root's name, duplicating top-level values, or implementing each heading as an independent dropdown. **Instead:** Use Menubar only for application commands and preserve its named, uniquely valued, orientation-aware top-level ownership.
+- **Avoid:** Hiding or collapsing the command strip at a Brick breakpoint or treating Shortcut text as registered keyboard behavior. **Instead:** Let the application select a responsive alternative and keep shortcut execution in application code.
+
+## Validation checklist
+
+- Verify Root naming and orientation, unique Menu values, one top-level tab stop, Home/End, horizontal and vertical Arrow movement, LTR and RTL, pointer and touch opening, keyboard first and last opening, hover switching, controlled active value, disabled triggers, and adjacent-menu focus ownership.
+- Verify shared item focus and typeahead, checkbox mixed and radio state, submenus, selection close policy, whole-root Tab exit, top-layer Escape, focus return, portals, parent-modal ownership, and asChild or render composition.
+- Verify three densities, persistent Root and open-trigger paint, constrained popup scrolling, danger meaning, narrow overflow policy, zoom, long localization, reduced motion, forced colors, portalled appearance, and complete CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/menubar`
+- `@flowstack-ui/atom/agents/menu`
+- `dropdown-menu`
+- `context-menu`
+- `navigation-menu`
+- `nav-list`
+- `toolbar`
+- `drawer`
+- `appearance`

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`