@flowstack-ui/brick 0.1.9 → 0.1.11

package/dist/agents/select.json

@@ -0,0 +1,95 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "select",
+  "name": "Select",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present one compact finished choice from a predefined list while Atom owns selection, trigger and listbox semantics, keyboard behavior, positioning, dismissal, validation, and native select form behavior.",
+  "useWhen": [
+    "A person chooses exactly one value from a predefined list whose options should stay collapsed until opened."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A short set should remain visible, several values may be selected, editable filtering or free-form entry is required, or rows are commands or destinations.",
+      "useInstead": "RadioGroup, MultiSelect, Combobox, DropdownMenu, or Link"
+    }
+  ],
+  "composition": [
+    "Compose Select.Root with a named Select.Trigger containing Select.Value and optional Select.Icon, then exactly one Select.Content or Select.Listbox. Place stable uniquely valued Items with ItemText inside optional Viewport and Group with Label; add indicators, separators, scroll buttons, Portal, and a direct popup Arrow only when required.",
+    "Use the same sm, md, or lg size as adjacent button-like controls. Keep locale loading, routing, persistence, analytics, and every other effect in onValueChange at the application boundary."
+  ],
+  "rules": [
+    {
+      "id": "select-single-value",
+      "level": "must",
+      "statement": "Use Select only for one predefined value and keep controlled value and open state aligned with their matching callbacks."
+    },
+    {
+      "id": "select-trigger-name",
+      "level": "must",
+      "statement": "Give Trigger a visible Field label or equivalent accessible name; placeholder and selected value are not the control name, and Trigger must retain combobox, expanded, controls, active-descendant, required, read-only, invalid, and disabled relationships."
+    },
+    {
+      "id": "select-item-text",
+      "level": "must",
+      "statement": "Give every Item a stable unique value and ItemText or label, keep interactive descendants out, and preserve that text for closed display, option naming, typeahead, and the hidden native select."
+    },
+    {
+      "id": "select-keyboard-form",
+      "level": "must",
+      "statement": "Preserve Trigger-owned opening, Arrow/Home/End, typeahead, Enter/Space selection, Tab, Escape, disabled skipping, focus restoration, native select options and submission, required validity, external form association, and reset."
+    },
+    {
+      "id": "select-popup-anatomy",
+      "level": "must",
+      "statement": "Render Content or Listbox once, keep Arrow directly inside it, and keep scroll buttons outside the registered Viewport so Atom owns positioning, collision, dismissal, and overflow state."
+    },
+    {
+      "id": "select-application-effect",
+      "level": "must",
+      "statement": "Keep translation loading, locale detection, persistence, navigation, analytics, and other effects in the application callback rather than inside Select."
+    },
+    {
+      "id": "select-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus select.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using placeholder or a selected code as the only name, omitting ItemText, rendering both popup owners, or rebuilding options as clickable rows.",
+      "correction": "Name Trigger separately and preserve one Atom-owned popup with registered stable Items and ItemText."
+    },
+    {
+      "mistake": "Using Select for multiple or editable choice, commands, navigation rows, or hidden application state and effects.",
+      "correction": "Choose MultiSelect, Combobox, DropdownMenu, or Link and connect legitimate value effects through onValueChange."
+    }
+  ],
+  "validation": [
+    "Verify Trigger naming and Field relationships, controlled and uncontrolled value and open state, placeholder and closed selected label, pointer/touch and keyboard opening, active descendant, Home/End, typeahead, selection, disabled Items, Tab, Escape, outside activation, and focus return.",
+    "Verify hidden native options and submission, required inline/native validity, external form, reset, groups and labels, Viewport and scroll buttons, Portal and non-Portal paths, Arrow placement, direction, collision handling, and nested modal ownership.",
+    "Verify all sizes, long localized labels, narrow widths, zoom, RTL, touch targets, light and dark appearance, forced colors, and alignment with adjacent button-like controls."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "select",
+      "versionPolicy": "installed-exact"
+    },
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "listbox",
+      "versionPolicy": "installed-exact"
+    },
+    "field",
+    "form",
+    "radio-group",
+    "combobox",
+    "multi-select",
+    "dropdown-menu",
+    "link"
+  ]
+}

package/dist/agents/select.md

@@ -0,0 +1,51 @@
+# Select agent guide
+
+## Purpose
+
+Present one compact finished choice from a predefined list while Atom owns selection, trigger and listbox semantics, keyboard behavior, positioning, dismissal, validation, and native select form behavior.
+
+## Use when
+
+- A person chooses exactly one value from a predefined list whose options should stay collapsed until opened.
+
+## Choose something else when
+
+- A short set should remain visible, several values may be selected, editable filtering or free-form entry is required, or rows are commands or destinations. Use RadioGroup, MultiSelect, Combobox, DropdownMenu, or Link.
+
+## Required composition
+
+- Compose Select.Root with a named Select.Trigger containing Select.Value and optional Select.Icon, then exactly one Select.Content or Select.Listbox. Place stable uniquely valued Items with ItemText inside optional Viewport and Group with Label; add indicators, separators, scroll buttons, Portal, and a direct popup Arrow only when required.
+- Use the same sm, md, or lg size as adjacent button-like controls. Keep locale loading, routing, persistence, analytics, and every other effect in onValueChange at the application boundary.
+
+## Rules
+
+- **MUST:** Use Select only for one predefined value and keep controlled value and open state aligned with their matching callbacks.
+- **MUST:** Give Trigger a visible Field label or equivalent accessible name; placeholder and selected value are not the control name, and Trigger must retain combobox, expanded, controls, active-descendant, required, read-only, invalid, and disabled relationships.
+- **MUST:** Give every Item a stable unique value and ItemText or label, keep interactive descendants out, and preserve that text for closed display, option naming, typeahead, and the hidden native select.
+- **MUST:** Preserve Trigger-owned opening, Arrow/Home/End, typeahead, Enter/Space selection, Tab, Escape, disabled skipping, focus restoration, native select options and submission, required validity, external form association, and reset.
+- **MUST:** Render Content or Listbox once, keep Arrow directly inside it, and keep scroll buttons outside the registered Viewport so Atom owns positioning, collision, dismissal, and overflow state.
+- **MUST:** Keep translation loading, locale detection, persistence, navigation, analytics, and other effects in the application callback rather than inside Select.
+- **MUST:** Load styles.css or core.css plus select.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Using placeholder or a selected code as the only name, omitting ItemText, rendering both popup owners, or rebuilding options as clickable rows. **Instead:** Name Trigger separately and preserve one Atom-owned popup with registered stable Items and ItemText.
+- **Avoid:** Using Select for multiple or editable choice, commands, navigation rows, or hidden application state and effects. **Instead:** Choose MultiSelect, Combobox, DropdownMenu, or Link and connect legitimate value effects through onValueChange.
+
+## Validation checklist
+
+- Verify Trigger naming and Field relationships, controlled and uncontrolled value and open state, placeholder and closed selected label, pointer/touch and keyboard opening, active descendant, Home/End, typeahead, selection, disabled Items, Tab, Escape, outside activation, and focus return.
+- Verify hidden native options and submission, required inline/native validity, external form, reset, groups and labels, Viewport and scroll buttons, Portal and non-Portal paths, Arrow placement, direction, collision handling, and nested modal ownership.
+- Verify all sizes, long localized labels, narrow widths, zoom, RTL, touch targets, light and dark appearance, forced colors, and alignment with adjacent button-like controls.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/select`
+- `@flowstack-ui/atom/agents/listbox`
+- `field`
+- `form`
+- `radio-group`
+- `combobox`
+- `multi-select`
+- `dropdown-menu`
+- `link`

package/dist/agents/show.json

@@ -29,6 +29,16 @@
       "level": "must",
       "statement": "Keep IDs, landmarks, form relationships, and focus order valid in every visible alternative."
     },
+    {
+      "id": "show-transparent-layout",
+      "level": "must",
+      "statement": "Rely on Show's layout-transparent visible state inside parent layouts and put paint or geometry on a child layout component."
+    },
+    {
+      "id": "show-default-props",
+      "level": "must",
+      "statement": "Omit default-valued props such as as=div; use as only for deliberate HTML semantics or valid document structure."
+    },
     {
       "id": "show-css",
       "level": "must",
@@ -36,6 +46,10 @@
     }
   ],
   "commonMistakes": [
+    {
+      "mistake": "Adding application CSS to repair Show spacing or writing as=div even though div is the default.",
+      "correction": "Rely on Show's layout-transparent default and specify as only when semantics require another host."
+    },
     {
       "mistake": "Forgetting show.css or rendering duplicate visible navigation because Show and Hide use the wrong thresholds.",
       "correction": "Load the modular CSS and verify exact breakpoint boundaries."

package/dist/agents/show.md

@@ -20,10 +20,13 @@ Show content only at selected Brick breakpoints through CSS, avoiding JavaScript
 
 - **MUST:** Use Show's CSS breakpoint contract rather than client viewport detection for responsive first paint.
 - **MUST:** Keep IDs, landmarks, form relationships, and focus order valid in every visible alternative.
+- **MUST:** Rely on Show's layout-transparent visible state inside parent layouts and put paint or geometry on a child layout component.
+- **MUST:** Omit default-valued props such as as=div; use as only for deliberate HTML semantics or valid document structure.
 - **MUST:** Load styles.css or core.css plus show.css.
 
 ## Common mistakes
 
+- **Avoid:** Adding application CSS to repair Show spacing or writing as=div even though div is the default. **Instead:** Rely on Show's layout-transparent default and specify as only when semantics require another host.
 - **Avoid:** Forgetting show.css or rendering duplicate visible navigation because Show and Hide use the wrong thresholds. **Instead:** Load the modular CSS and verify exact breakpoint boundaries.
 
 ## Validation checklist

package/dist/agents/sidebar.json

@@ -16,7 +16,8 @@
     }
   ],
   "composition": [
-    "Compose Root with Trigger, Panel, and Main; place NavList and other Brick content inside Panel and keep one page-level main landmark."
+    "Compose Root with Trigger, Panel, and Main; place NavList and other Brick content inside Panel and keep one page-level main landmark.",
+    "When Panel content can exceed its constrained block size, place ScrollArea.Root and ScrollArea.Viewport inside Sidebar.Content; Sidebar.Content is a flexible region, not a scroll owner."
   ],
   "rules": [
     {
@@ -29,6 +30,16 @@
       "level": "must",
       "statement": "Avoid duplicate main landmarks when composing Sidebar.Main into an existing shell."
     },
+    {
+      "id": "sidebar-surface",
+      "level": "must",
+      "statement": "Choose panel paint with surface; use transparent when an ancestor Surface owns the shell background instead of overriding Sidebar background selectors."
+    },
+    {
+      "id": "sidebar-scroll-ownership",
+      "level": "must",
+      "statement": "Keep Sidebar.Content flexible and compose a bounded ScrollArea when long panel content must remain reachable; do not clip or assign ad hoc overflow to navigation children."
+    },
     {
       "id": "sidebar-css",
       "level": "must",
@@ -37,16 +48,18 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Using Sidebar as a modal drawer or letting highlighted rail items overflow into Main.",
-      "correction": "Use Drawer for modal use and validate Sidebar's expanded, rail, and offcanvas geometry."
+      "mistake": "Using Sidebar as a modal drawer, overriding panel background selectors, letting highlighted rail items overflow into Main, or assuming Sidebar.Content scrolls automatically.",
+      "correction": "Use Drawer for modal use, choose the public surface recipe, compose ScrollArea for bounded long content, and validate Sidebar's expanded, rail, and offcanvas geometry."
     }
   ],
   "validation": [
     "Check every state, both sides, current navigation item, long labels, icons, counts, trigger, focus, inert offcanvas state, zoom, narrow widths, and RTL.",
+    "When content can overflow, verify the composed ScrollArea reaches the first and last panel destinations without moving Sidebar.Main.",
     "Confirm landmark names and CSS delivery."
   ],
   "related": [
     "nav-list",
+    "scroll-area",
     "drawer",
     "app-bar",
     "container",

package/dist/agents/sidebar.md

@@ -15,25 +15,30 @@ Provide a finished application-shell side region with expanded, rail, and offcan
 ## Required composition
 
 - Compose Root with Trigger, Panel, and Main; place NavList and other Brick content inside Panel and keep one page-level main landmark.
+- When Panel content can exceed its constrained block size, place ScrollArea.Root and ScrollArea.Viewport inside Sidebar.Content; Sidebar.Content is a flexible region, not a scroll owner.
 
 ## Rules
 
 - **MUST:** Use Sidebar state and public layout hooks instead of manually translating a generic aside and overlapping its active items.
 - **MUST:** Avoid duplicate main landmarks when composing Sidebar.Main into an existing shell.
+- **MUST:** Choose panel paint with surface; use transparent when an ancestor Surface owns the shell background instead of overriding Sidebar background selectors.
+- **MUST:** Keep Sidebar.Content flexible and compose a bounded ScrollArea when long panel content must remain reachable; do not clip or assign ad hoc overflow to navigation children.
 - **MUST:** Load styles.css or core.css plus sidebar.css and every composed child stylesheet.
 
 ## Common mistakes
 
-- **Avoid:** Using Sidebar as a modal drawer or letting highlighted rail items overflow into Main. **Instead:** Use Drawer for modal use and validate Sidebar's expanded, rail, and offcanvas geometry.
+- **Avoid:** Using Sidebar as a modal drawer, overriding panel background selectors, letting highlighted rail items overflow into Main, or assuming Sidebar.Content scrolls automatically. **Instead:** Use Drawer for modal use, choose the public surface recipe, compose ScrollArea for bounded long content, and validate Sidebar's expanded, rail, and offcanvas geometry.
 
 ## Validation checklist
 
 - Check every state, both sides, current navigation item, long labels, icons, counts, trigger, focus, inert offcanvas state, zoom, narrow widths, and RTL.
+- When content can overflow, verify the composed ScrollArea reaches the first and last panel destinations without moving Sidebar.Main.
 - Confirm landmark names and CSS delivery.
 
 ## Related guidance
 
 - `nav-list`
+- `scroll-area`
 - `drawer`
 - `app-bar`
 - `container`

package/dist/agents/skeleton.json

@@ -0,0 +1,73 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "skeleton",
+  "name": "Skeleton",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Preserve expected content geometry during a short application-owned load without exposing placeholder content as meaningful UI.",
+  "useWhen": [
+    "The final geometry is known and a short loading operation would otherwise cause disruptive layout shift."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Progress duration is known, the operation failed, or the layout is not yet predictable.",
+      "useInstead": "Progress, an error recovery state, or a stable generic loading message according to the state"
+    }
+  ],
+  "composition": [
+    "Match each Skeleton shape and dimension to the expected final content, mark the owning region busy, and keep any required application status copy outside the aria-hidden placeholder."
+  ],
+  "rules": [
+    {
+      "id": "skeleton-geometry",
+      "level": "must",
+      "statement": "Use supported shape, line, width, and height inputs to preserve the expected final geometry rather than decorating an arbitrary empty region."
+    },
+    {
+      "id": "skeleton-busy-owner",
+      "level": "must",
+      "statement": "Mark the owning region aria-busy while loading; Skeleton is aria-hidden and is not a status or live region."
+    },
+    {
+      "id": "skeleton-no-fake-content",
+      "level": "must",
+      "statement": "Do not place fake names, notifications, controls, or other meaningful placeholder content in the accessibility tree."
+    },
+    {
+      "id": "skeleton-appearance",
+      "level": "must",
+      "statement": "Keep the contextual default paint or another semantic Theme role visibly distinct from the actual containing surface in light and dark appearance."
+    },
+    {
+      "id": "skeleton-motion",
+      "level": "must",
+      "statement": "Preserve reduced-motion and forced-colors behavior and avoid application animation overrides."
+    },
+    {
+      "id": "skeleton-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus skeleton.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Skeleton as generic decoration or relying on its animation as the only loading announcement.",
+      "correction": "Use Skeleton only for known geometry, mark the owning region busy, and provide application-owned status text only when an announcement is actually required."
+    },
+    {
+      "mistake": "Selecting a semantic surface token that resolves to the same paint as the containing overlay in one appearance.",
+      "correction": "Keep the contextual primary-text tint or verify any semantic override against every containing surface in both appearances."
+    }
+  ],
+  "validation": [
+    "Check stable geometry before and after load, aria-hidden placeholder output, owning-region busy state, and absence of focusable fake content.",
+    "Check placeholder visibility on base, raised, and overlay surfaces across light/dark appearance, narrow widths, zoom, increased text size, reduced motion, and forced colors."
+  ],
+  "related": [
+    "progress",
+    "frame",
+    "stack",
+    "feed"
+  ]
+}

package/dist/agents/skeleton.md

@@ -0,0 +1,43 @@
+# Skeleton agent guide
+
+## Purpose
+
+Preserve expected content geometry during a short application-owned load without exposing placeholder content as meaningful UI.
+
+## Use when
+
+- The final geometry is known and a short loading operation would otherwise cause disruptive layout shift.
+
+## Choose something else when
+
+- Progress duration is known, the operation failed, or the layout is not yet predictable. Use Progress, an error recovery state, or a stable generic loading message according to the state.
+
+## Required composition
+
+- Match each Skeleton shape and dimension to the expected final content, mark the owning region busy, and keep any required application status copy outside the aria-hidden placeholder.
+
+## Rules
+
+- **MUST:** Use supported shape, line, width, and height inputs to preserve the expected final geometry rather than decorating an arbitrary empty region.
+- **MUST:** Mark the owning region aria-busy while loading; Skeleton is aria-hidden and is not a status or live region.
+- **MUST:** Do not place fake names, notifications, controls, or other meaningful placeholder content in the accessibility tree.
+- **MUST:** Keep the contextual default paint or another semantic Theme role visibly distinct from the actual containing surface in light and dark appearance.
+- **MUST:** Preserve reduced-motion and forced-colors behavior and avoid application animation overrides.
+- **MUST:** Load styles.css or core.css plus skeleton.css.
+
+## Common mistakes
+
+- **Avoid:** Using Skeleton as generic decoration or relying on its animation as the only loading announcement. **Instead:** Use Skeleton only for known geometry, mark the owning region busy, and provide application-owned status text only when an announcement is actually required.
+- **Avoid:** Selecting a semantic surface token that resolves to the same paint as the containing overlay in one appearance. **Instead:** Keep the contextual primary-text tint or verify any semantic override against every containing surface in both appearances.
+
+## Validation checklist
+
+- Check stable geometry before and after load, aria-hidden placeholder output, owning-region busy state, and absence of focusable fake content.
+- Check placeholder visibility on base, raised, and overlay surfaces across light/dark appearance, narrow widths, zoom, increased text size, reduced motion, and forced colors.
+
+## Related guidance
+
+- `progress`
+- `frame`
+- `stack`
+- `feed`

package/dist/agents/slider.json

@@ -0,0 +1,88 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "slider",
+  "name": "Slider",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a styled approximate numeric single-value or range input while Atom owns pointer, touch, keyboard, form, and field behavior.",
+  "useWhen": [
+    "A person chooses an approximate value or bounded range and direct manipulation is more useful than exact text entry."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Exact numeric entry, a small named choice set, or read-only completion is the real job.",
+      "useInstead": "NumberInput, Select, or Progress"
+    }
+  ],
+  "composition": [
+    "Compose Root > Track > Range plus one indexed Thumb for every value; place optional Marker parts in Track and optional ValueLabel inside its Thumb.",
+    "Use Slider as the sole control in one Field when a visible label, description, error, or required state is needed; otherwise name every standalone Thumb explicitly."
+  ],
+  "rules": [
+    {
+      "id": "slider-value-anatomy",
+      "level": "must",
+      "statement": "Render one indexed Thumb for every value and keep Marker inside Track and ValueLabel inside the owning Thumb."
+    },
+    {
+      "id": "slider-approximate-choice",
+      "level": "must",
+      "statement": "Use Slider only when approximate direct manipulation is appropriate; use NumberInput or Select when exact or named choices matter."
+    },
+    {
+      "id": "slider-accessible-name",
+      "level": "must",
+      "statement": "Provide one visible Field label for the complete Slider or a complete accessible name for every standalone Thumb."
+    },
+    {
+      "id": "slider-visible-output",
+      "level": "should",
+      "statement": "Use an external application-owned output when dense ranges or long localized values would collide with a thumb ValueLabel."
+    },
+    {
+      "id": "slider-change-commit",
+      "level": "must",
+      "statement": "Use onValueChange for live updates and onValueCommit for completed interactions; true pointer cancellation restores the pointer-down value without commit while lost capture commits the latest value."
+    },
+    {
+      "id": "slider-input-direction",
+      "level": "must",
+      "statement": "Preserve one active pointer session, non-slider-axis page scrolling, orientation-aware keys, and horizontal LTR and RTL pointer and Arrow behavior."
+    },
+    {
+      "id": "slider-track-inset",
+      "level": "should",
+      "statement": "Keep the default Track inset when a parent clips overflow; set the public Track-inset token to zero only when the surrounding composition preserves complete endpoint target and focus paint."
+    },
+    {
+      "id": "slider-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus slider.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Rendering a range with one Thumb, treating decorative markers as labels, or using Slider for a discrete named choice without explaining the values.",
+      "correction": "Match Thumbs to values, label the actual control, and choose Select or RadioGroup when names carry the meaning."
+    }
+  ],
+  "validation": [
+    "Check pointer, touch, keyboard, large steps, range bounds, controlled values, reset, disabled, read-only, invalid, and form submission.",
+    "Check horizontal and vertical orientation, RTL, narrow containment, complete 44px endpoint targets, any customized Track inset, zoom, reduced motion, forced colors, and label readability."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "slider",
+      "versionPolicy": "installed-exact"
+    },
+    "field",
+    "number-input",
+    "select",
+    "progress",
+    "rating",
+    "form"
+  ]
+}

package/dist/agents/slider.md

@@ -0,0 +1,48 @@
+# Slider agent guide
+
+## Purpose
+
+Provide a styled approximate numeric single-value or range input while Atom owns pointer, touch, keyboard, form, and field behavior.
+
+## Use when
+
+- A person chooses an approximate value or bounded range and direct manipulation is more useful than exact text entry.
+
+## Choose something else when
+
+- Exact numeric entry, a small named choice set, or read-only completion is the real job. Use NumberInput, Select, or Progress.
+
+## Required composition
+
+- Compose Root > Track > Range plus one indexed Thumb for every value; place optional Marker parts in Track and optional ValueLabel inside its Thumb.
+- Use Slider as the sole control in one Field when a visible label, description, error, or required state is needed; otherwise name every standalone Thumb explicitly.
+
+## Rules
+
+- **MUST:** Render one indexed Thumb for every value and keep Marker inside Track and ValueLabel inside the owning Thumb.
+- **MUST:** Use Slider only when approximate direct manipulation is appropriate; use NumberInput or Select when exact or named choices matter.
+- **MUST:** Provide one visible Field label for the complete Slider or a complete accessible name for every standalone Thumb.
+- **SHOULD:** Use an external application-owned output when dense ranges or long localized values would collide with a thumb ValueLabel.
+- **MUST:** Use onValueChange for live updates and onValueCommit for completed interactions; true pointer cancellation restores the pointer-down value without commit while lost capture commits the latest value.
+- **MUST:** Preserve one active pointer session, non-slider-axis page scrolling, orientation-aware keys, and horizontal LTR and RTL pointer and Arrow behavior.
+- **SHOULD:** Keep the default Track inset when a parent clips overflow; set the public Track-inset token to zero only when the surrounding composition preserves complete endpoint target and focus paint.
+- **MUST:** Load styles.css or core.css plus slider.css.
+
+## Common mistakes
+
+- **Avoid:** Rendering a range with one Thumb, treating decorative markers as labels, or using Slider for a discrete named choice without explaining the values. **Instead:** Match Thumbs to values, label the actual control, and choose Select or RadioGroup when names carry the meaning.
+
+## Validation checklist
+
+- Check pointer, touch, keyboard, large steps, range bounds, controlled values, reset, disabled, read-only, invalid, and form submission.
+- Check horizontal and vertical orientation, RTL, narrow containment, complete 44px endpoint targets, any customized Track inset, zoom, reduced motion, forced colors, and label readability.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/slider`
+- `field`
+- `number-input`
+- `select`
+- `progress`
+- `rating`
+- `form`

package/dist/agents/stack.json

@@ -21,9 +21,11 @@
   ],
   "composition": [
     "Choose VStack when the axis is always vertical, HStack when it is always horizontal, and Stack when the same content changes axis at a breakpoint.",
+    "Use as=\"ul\" or as=\"ol\" when the one-dimensional peers form a semantic list; Stack removes native list geometry while preserving the relationship.",
     "Use Stack.Item when one direct child must remain content-sized, fixed, or consume a proportional share.",
     "When the parent changes axis, review each Item flex recipe too; a proportional desktop column usually becomes content-sized in a mobile column.",
-    "Keep the Item wrapper when equal outer tracks contain children with different padding or borders; use asChild only when the child's own box should participate in flex allocation."
+    "Keep the Item wrapper when equal outer tracks contain children with different padding or borders; use asChild only when the child's own box should participate in flex allocation.",
+    "When Stack.Item composes a control with asChild, rely on the control's own size recipe; Stack preserves its declared minimum block size while adding flex participation."
   ],
   "rules": [
     {
@@ -31,6 +33,16 @@
       "level": "must",
       "statement": "Use Stack for one primary layout axis and allow wrapping only when the resulting order remains clear."
     },
+    {
+      "id": "stack-gap-scale",
+      "level": "must",
+      "statement": "Use non-negative numeric spacing factors for ordinary gap and logical edge spacing; use an explicit CSS value only for a measured exception or application spacing token, and preserve legacy string tokens when maintaining existing geometry."
+    },
+    {
+      "id": "stack-semantic-list",
+      "level": "must",
+      "statement": "Use a semantic list host when Stack children form a real set; do not add consumer CSS to cancel native ul or ol margins or markers because Stack owns that host geometry."
+    },
     {
       "id": "stack-responsive-arrangement",
       "level": "must",
@@ -55,10 +67,16 @@
     {
       "mistake": "Writing grow/shrink CSS for ordinary columns.",
       "correction": "Use Stack.Item flex recipes."
+    },
+    {
+      "mistake": "Adding a local class only because the desired gap is outside the legacy zero-through-six token scale.",
+      "correction": "Use a numeric factor such as gap={8}, an explicit CSS length, or an application custom property through the supported spacing prop."
     }
   ],
   "validation": [
     "Check source and visual order at narrow widths and zoom.",
+    "Confirm numeric, explicit, and responsive spacing values create the intended computed geometry; reject negative, non-finite, and empty values.",
+    "For ul and ol hosts, confirm zero native margin, no visual marker, and preserved list semantics.",
     "Check every authored breakpoint, logical edge spacing, wrapping, alignment, and RTL behavior."
   ],
   "related": [

package/dist/agents/stack.md

@@ -16,13 +16,17 @@ Arrange children on one primary axis with responsive direction, tokenized spacin
 ## Required composition
 
 - Choose VStack when the axis is always vertical, HStack when it is always horizontal, and Stack when the same content changes axis at a breakpoint.
+- Use as="ul" or as="ol" when the one-dimensional peers form a semantic list; Stack removes native list geometry while preserving the relationship.
 - Use Stack.Item when one direct child must remain content-sized, fixed, or consume a proportional share.
 - When the parent changes axis, review each Item flex recipe too; a proportional desktop column usually becomes content-sized in a mobile column.
 - Keep the Item wrapper when equal outer tracks contain children with different padding or borders; use asChild only when the child's own box should participate in flex allocation.
+- When Stack.Item composes a control with asChild, rely on the control's own size recipe; Stack preserves its declared minimum block size while adding flex participation.
 
 ## Rules
 
 - **MUST:** Use Stack for one primary layout axis and allow wrapping only when the resulting order remains clear.
+- **MUST:** Use non-negative numeric spacing factors for ordinary gap and logical edge spacing; use an explicit CSS value only for a measured exception or application spacing token, and preserve legacy string tokens when maintaining existing geometry.
+- **MUST:** Use a semantic list host when Stack children form a real set; do not add consumer CSS to cancel native ul or ol margins or markers because Stack owns that host geometry.
 - **MUST:** Use responsive Stack values for arrangement changes; use Show/Hide only when the actual interface changes.
 - **MUST:** Preserve reading and focus order; do not simulate reverse direction or visual ordering.
 - **MUST:** Load styles.css or core.css plus stack.css.
@@ -31,10 +35,13 @@ Arrange children on one primary axis with responsive direction, tokenized spacin
 
 - **Avoid:** Duplicating the same content through Show/Hide only to switch row and column. **Instead:** Use responsive Stack direction.
 - **Avoid:** Writing grow/shrink CSS for ordinary columns. **Instead:** Use Stack.Item flex recipes.
+- **Avoid:** Adding a local class only because the desired gap is outside the legacy zero-through-six token scale. **Instead:** Use a numeric factor such as gap={8}, an explicit CSS length, or an application custom property through the supported spacing prop.
 
 ## Validation checklist
 
 - Check source and visual order at narrow widths and zoom.
+- Confirm numeric, explicit, and responsive spacing values create the intended computed geometry; reject negative, non-finite, and empty values.
+- For ul and ol hosts, confirm zero native margin, no visual marker, and preserved list semantics.
 - Check every authored breakpoint, logical edge spacing, wrapping, alignment, and RTL behavior.
 
 ## Related guidance