@flowstack-ui/brick 0.1.6 → 0.1.11

package/dist/agents/progress.json

@@ -0,0 +1,91 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "progress",
+  "name": "Progress",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present finished linear read-only task progress for known, unknown, or buffered work while Atom owns progressbar semantics, normalized range state, and the presentation-only Indicator.",
+  "useWhen": [
+    "Ongoing work such as upload, download, processing, or synchronization needs a linear indication of measurable completion or indeterminate activity."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value is a stable measurement, users manipulate it, stages rather than amount matter, the finished layout is loading, compact circular presentation fits better, or only a transient result is needed.",
+      "useInstead": "the native meter element, Slider, Steps, Skeleton, ProgressCircle, or Toast"
+    }
+  ],
+  "composition": [
+    "Give Progress.Root a concise Label or native accessible name, pass a measurable value or null/omit it for indeterminate work, set a truthful range, and compose optional Value then Track with optional Buffer before Indicator.",
+    "Choose horizontal or vertical orientation, size, shape, and semantic tone. Keep application region aria-busy state and announcements outside Progress, and provide aria-valuetext or getValueLabel when the numeric range needs domain wording."
+  ],
+  "rules": [
+    {
+      "id": "progress-name",
+      "level": "must",
+      "statement": "Give Root an accessible name identifying the ongoing task through Progress.Label or native ARIA; visible Value does not name the task."
+    },
+    {
+      "id": "progress-determinate",
+      "level": "must",
+      "statement": "Use a current numeric value only for measurable work and pass null or omit value for unknown work so aria-valuenow is absent rather than pretending unknown progress is zero."
+    },
+    {
+      "id": "progress-range",
+      "level": "must",
+      "statement": "Supply truthful min and max, understand Atom clamping and invalid-range normalization, and keep optional bufferValue within the same task and range rather than treating it as a second progressbar."
+    },
+    {
+      "id": "progress-value-text",
+      "level": "should",
+      "statement": "Provide concise human-readable aria-valuetext or getValueLabel output when the numeric range alone does not communicate meaningful completion; localize visible Value formatting separately."
+    },
+    {
+      "id": "progress-indicator",
+      "level": "must",
+      "statement": "Keep Indicator and Buffer presentation-only, ordered Buffer before Indicator inside Track, and Root as the sole progressbar and announcement owner."
+    },
+    {
+      "id": "progress-readonly",
+      "level": "must",
+      "statement": "Do not make Progress interactive or keyboard adjustable and do not use it for static capacity; choose Slider for input and native meter for stable measurement."
+    },
+    {
+      "id": "progress-responsive",
+      "level": "must",
+      "statement": "Keep horizontal Progress shrinkable, vertical length explicit, label wrapping and value alignment intact, logical fill correct in RTL, and reduced-motion indeterminate state understandable as a static segment."
+    },
+    {
+      "id": "progress-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus progress.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Passing zero for unknown progress, using Progress for capacity, omitting its task name, or adding progressbar semantics to Indicator.",
+      "correction": "Use indeterminate null state, native meter for stable quantity, name Root, and keep visual parts silent."
+    },
+    {
+      "mistake": "Announcing every percent change in another live region or treating tone as the sole status meaning.",
+      "correction": "Keep one semantic progressbar, add independently justified announcements sparingly, and provide textual task or state context."
+    }
+  ],
+  "validation": [
+    "Verify naming, determinate loading/complete and indeterminate states, aria-valuenow absence, clamping, invalid-range normalization, buffer percentage, data state, explicit aria-valuetext precedence, getValueLabel, and localized visible Value formatting.",
+    "Verify Root is the only progressbar; Indicator and Buffer are silent; no keyboard interaction exists; all parts remain under Root with Buffer before Indicator; native props, refs, and composition are preserved.",
+    "Verify both orientations, five sizes, all shapes and tones, narrow width, explicit vertical length, long labels, zoom, RTL logical fill, light/dark appearance, forced colors, reduced motion, and track/indicator contrast."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "progress",
+      "versionPolicy": "installed-exact"
+    },
+    "progress-circle",
+    "slider",
+    "toast",
+    "skeleton"
+  ]
+}

package/dist/agents/progress.md

@@ -0,0 +1,48 @@
+# Progress agent guide
+
+## Purpose
+
+Present finished linear read-only task progress for known, unknown, or buffered work while Atom owns progressbar semantics, normalized range state, and the presentation-only Indicator.
+
+## Use when
+
+- Ongoing work such as upload, download, processing, or synchronization needs a linear indication of measurable completion or indeterminate activity.
+
+## Choose something else when
+
+- The value is a stable measurement, users manipulate it, stages rather than amount matter, the finished layout is loading, compact circular presentation fits better, or only a transient result is needed. Use the native meter element, Slider, Steps, Skeleton, ProgressCircle, or Toast.
+
+## Required composition
+
+- Give Progress.Root a concise Label or native accessible name, pass a measurable value or null/omit it for indeterminate work, set a truthful range, and compose optional Value then Track with optional Buffer before Indicator.
+- Choose horizontal or vertical orientation, size, shape, and semantic tone. Keep application region aria-busy state and announcements outside Progress, and provide aria-valuetext or getValueLabel when the numeric range needs domain wording.
+
+## Rules
+
+- **MUST:** Give Root an accessible name identifying the ongoing task through Progress.Label or native ARIA; visible Value does not name the task.
+- **MUST:** Use a current numeric value only for measurable work and pass null or omit value for unknown work so aria-valuenow is absent rather than pretending unknown progress is zero.
+- **MUST:** Supply truthful min and max, understand Atom clamping and invalid-range normalization, and keep optional bufferValue within the same task and range rather than treating it as a second progressbar.
+- **SHOULD:** Provide concise human-readable aria-valuetext or getValueLabel output when the numeric range alone does not communicate meaningful completion; localize visible Value formatting separately.
+- **MUST:** Keep Indicator and Buffer presentation-only, ordered Buffer before Indicator inside Track, and Root as the sole progressbar and announcement owner.
+- **MUST:** Do not make Progress interactive or keyboard adjustable and do not use it for static capacity; choose Slider for input and native meter for stable measurement.
+- **MUST:** Keep horizontal Progress shrinkable, vertical length explicit, label wrapping and value alignment intact, logical fill correct in RTL, and reduced-motion indeterminate state understandable as a static segment.
+- **MUST:** Load styles.css or core.css plus progress.css.
+
+## Common mistakes
+
+- **Avoid:** Passing zero for unknown progress, using Progress for capacity, omitting its task name, or adding progressbar semantics to Indicator. **Instead:** Use indeterminate null state, native meter for stable quantity, name Root, and keep visual parts silent.
+- **Avoid:** Announcing every percent change in another live region or treating tone as the sole status meaning. **Instead:** Keep one semantic progressbar, add independently justified announcements sparingly, and provide textual task or state context.
+
+## Validation checklist
+
+- Verify naming, determinate loading/complete and indeterminate states, aria-valuenow absence, clamping, invalid-range normalization, buffer percentage, data state, explicit aria-valuetext precedence, getValueLabel, and localized visible Value formatting.
+- Verify Root is the only progressbar; Indicator and Buffer are silent; no keyboard interaction exists; all parts remain under Root with Buffer before Indicator; native props, refs, and composition are preserved.
+- Verify both orientations, five sizes, all shapes and tones, narrow width, explicit vertical length, long labels, zoom, RTL logical fill, light/dark appearance, forced colors, reduced motion, and track/indicator contrast.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/progress`
+- `progress-circle`
+- `slider`
+- `toast`
+- `skeleton`

package/dist/agents/radio-group.json

@@ -0,0 +1,92 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "radio-group",
+  "name": "RadioGroup",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished short visible form choice set with exactly one selected value while Atom owns radiogroup semantics, roving focus, keyboard selection, validation, and submission.",
+  "useWhen": [
+    "A user must choose exactly one option from a short visible list whose choices are best compared together."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Several choices may be selected, a long list should stay compact, or the controls are pressed commands rather than form answers.",
+      "useInstead": "CheckboxGroup, Select, or ToggleGroup"
+    }
+  ],
+  "composition": [
+    "Give RadioGroup.Root an accessible group name and compose one uniquely valued RadioGroup.Item per visible option. Use Fieldset with Legend, Description, and Error when the set needs visible group labeling or validation context; use name and form when the selected value must submit.",
+    "Root owns sm, md, or lg size and vertical or horizontal layout. Each Item owns its complete visible option label while Brick supplies the private circular control and checked dot."
+  ],
+  "rules": [
+    {
+      "id": "radio-group-selection",
+      "level": "must",
+      "statement": "Use RadioGroup for exactly one short visible form choice; use CheckboxGroup for independent choices, Select for a compact longer list, and ToggleGroup for pressed commands."
+    },
+    {
+      "id": "radio-group-names",
+      "level": "must",
+      "statement": "Give Root an accessible group name through native ARIA or Fieldset Legend and give every Item a complete visible or native accessible option name."
+    },
+    {
+      "id": "radio-group-values",
+      "level": "must",
+      "statement": "Give every Item a stable unique value and use value with onValueChange for controlled state or defaultValue for uncontrolled state."
+    },
+    {
+      "id": "radio-group-roving",
+      "level": "must",
+      "statement": "Preserve the selected or first enabled Item as the one Tab stop, disabled-item skipping, looping policy, and orientation- and direction-aware Arrow, Home, End, and Space behavior."
+    },
+    {
+      "id": "radio-group-readonly",
+      "level": "must",
+      "statement": "Use readOnly when the selected value must remain focusable and submitted while preventing pointer, Space, and navigation-driven changes; do not substitute disabled."
+    },
+    {
+      "id": "radio-group-form",
+      "level": "must",
+      "statement": "Preserve group-level required validity, first-enabled validation focus, Fieldset state and descriptions, named hidden-radio submission, and uncontrolled form reset."
+    },
+    {
+      "id": "radio-group-responsive",
+      "level": "should",
+      "statement": "Use vertical for scan-heavy groups and horizontal only when wrapped DOM reading order remains clear under narrow widths, zoom, localization, and RTL."
+    },
+    {
+      "id": "radio-group-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus radio-group.css and Fieldset CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Omitting the group name, giving every Item a Tab stop, using RadioGroup for independent choices, or disabling a value that should remain read-only.",
+      "correction": "Use the named Atom-owned roving group, choose CheckboxGroup for independent choices, and preserve focus and submission with readOnly."
+    },
+    {
+      "mistake": "Treating the private circle or surrounding layout as the option label or applying validation to every row independently.",
+      "correction": "Label every Item with its visible content and keep shared required or invalid messaging at Root or Fieldset scope."
+    }
+  ],
+  "validation": [
+    "Verify Root and Item names, unique values, controlled and uncontrolled selection, one roving Tab stop, disabled skipping, vertical and horizontal Arrow keys, Home/End, Space, looping, explicit and inherited LTR and RTL, pointer activation, and composition semantics.",
+    "Verify read-only focus without value changes, group-level required validation with and without name, first-enabled validation focus, Fieldset descriptions and errors, hidden submission value, form association, and uncontrolled reset.",
+    "Verify three sizes, vertical and wrapping horizontal layout, long labels, narrow widths, 200% text and 400% zoom, touch targets, light and dark appearance, forced colors, RTL, and complete CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "radio-group",
+      "versionPolicy": "installed-exact"
+    },
+    "checkbox-group",
+    "select",
+    "toggle-group",
+    "fieldset",
+    "form"
+  ]
+}

package/dist/agents/radio-group.md

@@ -0,0 +1,49 @@
+# RadioGroup agent guide
+
+## Purpose
+
+Present a finished short visible form choice set with exactly one selected value while Atom owns radiogroup semantics, roving focus, keyboard selection, validation, and submission.
+
+## Use when
+
+- A user must choose exactly one option from a short visible list whose choices are best compared together.
+
+## Choose something else when
+
+- Several choices may be selected, a long list should stay compact, or the controls are pressed commands rather than form answers. Use CheckboxGroup, Select, or ToggleGroup.
+
+## Required composition
+
+- Give RadioGroup.Root an accessible group name and compose one uniquely valued RadioGroup.Item per visible option. Use Fieldset with Legend, Description, and Error when the set needs visible group labeling or validation context; use name and form when the selected value must submit.
+- Root owns sm, md, or lg size and vertical or horizontal layout. Each Item owns its complete visible option label while Brick supplies the private circular control and checked dot.
+
+## Rules
+
+- **MUST:** Use RadioGroup for exactly one short visible form choice; use CheckboxGroup for independent choices, Select for a compact longer list, and ToggleGroup for pressed commands.
+- **MUST:** Give Root an accessible group name through native ARIA or Fieldset Legend and give every Item a complete visible or native accessible option name.
+- **MUST:** Give every Item a stable unique value and use value with onValueChange for controlled state or defaultValue for uncontrolled state.
+- **MUST:** Preserve the selected or first enabled Item as the one Tab stop, disabled-item skipping, looping policy, and orientation- and direction-aware Arrow, Home, End, and Space behavior.
+- **MUST:** Use readOnly when the selected value must remain focusable and submitted while preventing pointer, Space, and navigation-driven changes; do not substitute disabled.
+- **MUST:** Preserve group-level required validity, first-enabled validation focus, Fieldset state and descriptions, named hidden-radio submission, and uncontrolled form reset.
+- **SHOULD:** Use vertical for scan-heavy groups and horizontal only when wrapped DOM reading order remains clear under narrow widths, zoom, localization, and RTL.
+- **MUST:** Load styles.css or core.css plus radio-group.css and Fieldset CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Omitting the group name, giving every Item a Tab stop, using RadioGroup for independent choices, or disabling a value that should remain read-only. **Instead:** Use the named Atom-owned roving group, choose CheckboxGroup for independent choices, and preserve focus and submission with readOnly.
+- **Avoid:** Treating the private circle or surrounding layout as the option label or applying validation to every row independently. **Instead:** Label every Item with its visible content and keep shared required or invalid messaging at Root or Fieldset scope.
+
+## Validation checklist
+
+- Verify Root and Item names, unique values, controlled and uncontrolled selection, one roving Tab stop, disabled skipping, vertical and horizontal Arrow keys, Home/End, Space, looping, explicit and inherited LTR and RTL, pointer activation, and composition semantics.
+- Verify read-only focus without value changes, group-level required validation with and without name, first-enabled validation focus, Fieldset descriptions and errors, hidden submission value, form association, and uncontrolled reset.
+- Verify three sizes, vertical and wrapping horizontal layout, long labels, narrow widths, 200% text and 400% zoom, touch targets, light and dark appearance, forced colors, RTL, and complete CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/radio-group`
+- `checkbox-group`
+- `select`
+- `toggle-group`
+- `fieldset`
+- `form`

package/dist/agents/rating.json

@@ -0,0 +1,91 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "rating",
+  "name": "Rating",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Collect a short ordered score, present a repeated-star aggregate, or present a compact one-star numeric summary.",
+  "useWhen": [
+    "A person chooses a score on a short ordered scale, or an aggregate score needs recognizable repeated-star presentation."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value is a general numeric setting, a named choice, progress, or status.",
+      "useInstead": "Slider, Radio Group, Progress, or Badge"
+    }
+  ],
+  "composition": [
+    "For input, compose Root with one Item for every endpoint and use it as the sole control in Field or name the standalone Root.",
+    "For aggregate product or review data, use Display with repeated stars or Summary with one star and a visible value; give either a localized label and do not use readOnly Root as a passive summary."
+  ],
+  "rules": [
+    {
+      "id": "rating-input-vs-display",
+      "level": "must",
+      "statement": "Use Root and Item only when the person can choose a score; use Display for aggregate or read-only presentation so passive content does not create a focusable slider."
+    },
+    {
+      "id": "rating-display-label",
+      "level": "must",
+      "statement": "Give Display and Summary a localized label that states the score and maximum, such as label=\"4.5 out of 5 stars\"; use Summary valueText for localized visible formatting and keep adjacent review counts as ordinary text."
+    },
+    {
+      "id": "rating-input-name",
+      "level": "must",
+      "statement": "Provide one visible Field label for an input Rating or a complete accessible name for a standalone Root."
+    },
+    {
+      "id": "rating-scale-clear",
+      "level": "must",
+      "statement": "Use a valid ordered min and max, positive step, and Item endpoint values; keep repeated selection stable by default and enable allowClear only when clearing to the minimum is intentional."
+    },
+    {
+      "id": "rating-input-behavior",
+      "level": "must",
+      "statement": "Preserve one focusable slider Root with decorative Items, one-pointer capture, cross-item dragging, vertical page scrolling, cancellation rollback, lost-capture finalization, keyboard steps, and horizontal LTR and RTL behavior."
+    },
+    {
+      "id": "rating-form-state",
+      "level": "must",
+      "statement": "Preserve disabled, read-only, invalid, required-above-minimum validity, Field relationships, named hidden submission, validation focus, and uncontrolled form reset for input Rating."
+    },
+    {
+      "id": "rating-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus rating.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using readOnly Root to show a product's average rating, creating a focusable slider that cannot be changed.",
+      "correction": "Use Rating.Display for aggregate scores and reserve readOnly Root for rare form review states where slider semantics remain meaningful."
+    },
+    {
+      "mistake": "Making every star focusable, repeating the score through five accessible icons, or relying on star color alone.",
+      "correction": "Keep one logical Root for input or one labelled Display image for aggregate output; repeated artwork stays decorative."
+    },
+    {
+      "mistake": "Using max=1 or an ordinary star Icon to fake a compact aggregate rating.",
+      "correction": "Use Rating.Summary so one decorative star and the visible numeric value share one localized aggregate label."
+    }
+  ],
+  "validation": [
+    "For input, check pointer, touch, keyboard, fractional values, form ownership, reset, disabled, read-only, invalid, and Field relationships.",
+    "For Display and Summary, check the localized accessible name, absence from tab order, aggregate geometry, RTL, forced colors, zoom, and long adjacent review text.",
+    "Confirm CSS is loaded."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "rating",
+      "versionPolicy": "installed-exact"
+    },
+    "field",
+    "slider",
+    "radio-group",
+    "progress",
+    "badge"
+  ]
+}

package/dist/agents/rating.md

@@ -0,0 +1,49 @@
+# Rating agent guide
+
+## Purpose
+
+Collect a short ordered score, present a repeated-star aggregate, or present a compact one-star numeric summary.
+
+## Use when
+
+- A person chooses a score on a short ordered scale, or an aggregate score needs recognizable repeated-star presentation.
+
+## Choose something else when
+
+- The value is a general numeric setting, a named choice, progress, or status. Use Slider, Radio Group, Progress, or Badge.
+
+## Required composition
+
+- For input, compose Root with one Item for every endpoint and use it as the sole control in Field or name the standalone Root.
+- For aggregate product or review data, use Display with repeated stars or Summary with one star and a visible value; give either a localized label and do not use readOnly Root as a passive summary.
+
+## Rules
+
+- **MUST:** Use Root and Item only when the person can choose a score; use Display for aggregate or read-only presentation so passive content does not create a focusable slider.
+- **MUST:** Give Display and Summary a localized label that states the score and maximum, such as label="4.5 out of 5 stars"; use Summary valueText for localized visible formatting and keep adjacent review counts as ordinary text.
+- **MUST:** Provide one visible Field label for an input Rating or a complete accessible name for a standalone Root.
+- **MUST:** Use a valid ordered min and max, positive step, and Item endpoint values; keep repeated selection stable by default and enable allowClear only when clearing to the minimum is intentional.
+- **MUST:** Preserve one focusable slider Root with decorative Items, one-pointer capture, cross-item dragging, vertical page scrolling, cancellation rollback, lost-capture finalization, keyboard steps, and horizontal LTR and RTL behavior.
+- **MUST:** Preserve disabled, read-only, invalid, required-above-minimum validity, Field relationships, named hidden submission, validation focus, and uncontrolled form reset for input Rating.
+- **MUST:** Load styles.css or core.css plus rating.css.
+
+## Common mistakes
+
+- **Avoid:** Using readOnly Root to show a product's average rating, creating a focusable slider that cannot be changed. **Instead:** Use Rating.Display for aggregate scores and reserve readOnly Root for rare form review states where slider semantics remain meaningful.
+- **Avoid:** Making every star focusable, repeating the score through five accessible icons, or relying on star color alone. **Instead:** Keep one logical Root for input or one labelled Display image for aggregate output; repeated artwork stays decorative.
+- **Avoid:** Using max=1 or an ordinary star Icon to fake a compact aggregate rating. **Instead:** Use Rating.Summary so one decorative star and the visible numeric value share one localized aggregate label.
+
+## Validation checklist
+
+- For input, check pointer, touch, keyboard, fractional values, form ownership, reset, disabled, read-only, invalid, and Field relationships.
+- For Display and Summary, check the localized accessible name, absence from tab order, aggregate geometry, RTL, forced colors, zoom, and long adjacent review text.
+- Confirm CSS is loaded.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/rating`
+- `field`
+- `slider`
+- `radio-group`
+- `progress`
+- `badge`

package/dist/agents/reorderable-list.json

@@ -0,0 +1,74 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "reorderable-list",
+  "name": "Reorderable List",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a finished list for deliberate manual ordering while Atom owns drag, touch, keyboard, focus, announcements, cancellation, and reorder state behavior.",
+  "useWhen": [
+    "A person needs to arrange a small linear collection into a meaningful saved order."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The application is sorting data automatically or changing a table sort key.",
+      "useInstead": "DataGrid or an application-owned sort control"
+    },
+    {
+      "condition": "Items move between columns, tree parents, freeform coordinates, or external applications.",
+      "useInstead": "A dedicated Kanban, tree, spatial, or file-transfer composition over Atom DragDrop"
+    },
+    {
+      "condition": "The content is static and has no manual ordering job.",
+      "useInstead": "List"
+    }
+  ],
+  "composition": [
+    "Compose Root > Item > Handle + Content + optional Actions containing direct Move controls + DropIndicator.",
+    "Keep application data keyed by each Item value and update that data from Root onItemsChange; persistence, Undo, conflicts, and validation remain application-owned.",
+    "Let Brick move direct Actions below Content when a vertical list's own container is narrow; do not add viewport logic or duplicate the item tree for this relationship."
+  ],
+  "rules": [
+    {
+      "id": "reorderable-list-stable-identity",
+      "level": "must",
+      "statement": "Use stable unique values for Root items and matching Item values; never use visual indexes as identity."
+    },
+    {
+      "id": "reorderable-list-labels",
+      "level": "must",
+      "statement": "Provide getItemLabel plus localized aria-label values for every Handle and direct Move control."
+    },
+    {
+      "id": "reorderable-list-alternative",
+      "level": "must",
+      "statement": "Provide direct movement controls when drag precision, switch access, voice access, or discoverability requires a visible non-drag path."
+    },
+    {
+      "id": "reorderable-list-ownership",
+      "level": "must",
+      "statement": "Keep persistence, Undo, optimistic updates, server conflicts, validation, and automatic sorting outside ReorderableList."
+    },
+    {
+      "id": "reorderable-list-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus reorderable-list.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using ReorderableList as a sortable table, persisting inside the component, omitting accessible movement names, or making drag the only usable path.",
+      "correction": "Choose the component by user job, keep workflow state in the application, label every control, and expose direct movement where needed."
+    }
+  ],
+  "validation": [
+    "Check direct movement, keyboard lift/move/drop/cancel, mouse and touch movement, focus preservation, disabled and read-only states, and announcement copy.",
+    "Check that narrow vertical lists preserve a useful content measure by moving direct Actions below Content, then check horizontal overflow, RTL, zoom, reduced motion, forced colors, light and dark appearance, focus-ring containment, and insertion feedback."
+  ],
+  "related": [
+    "list",
+    "data-grid",
+    "tree",
+    "swipeable-item"
+  ]
+}

package/dist/agents/reorderable-list.md

@@ -0,0 +1,45 @@
+# Reorderable List agent guide
+
+## Purpose
+
+Provide a finished list for deliberate manual ordering while Atom owns drag, touch, keyboard, focus, announcements, cancellation, and reorder state behavior.
+
+## Use when
+
+- A person needs to arrange a small linear collection into a meaningful saved order.
+
+## Choose something else when
+
+- The application is sorting data automatically or changing a table sort key. Use DataGrid or an application-owned sort control.
+- Items move between columns, tree parents, freeform coordinates, or external applications. Use A dedicated Kanban, tree, spatial, or file-transfer composition over Atom DragDrop.
+- The content is static and has no manual ordering job. Use List.
+
+## Required composition
+
+- Compose Root > Item > Handle + Content + optional Actions containing direct Move controls + DropIndicator.
+- Keep application data keyed by each Item value and update that data from Root onItemsChange; persistence, Undo, conflicts, and validation remain application-owned.
+- Let Brick move direct Actions below Content when a vertical list's own container is narrow; do not add viewport logic or duplicate the item tree for this relationship.
+
+## Rules
+
+- **MUST:** Use stable unique values for Root items and matching Item values; never use visual indexes as identity.
+- **MUST:** Provide getItemLabel plus localized aria-label values for every Handle and direct Move control.
+- **MUST:** Provide direct movement controls when drag precision, switch access, voice access, or discoverability requires a visible non-drag path.
+- **MUST:** Keep persistence, Undo, optimistic updates, server conflicts, validation, and automatic sorting outside ReorderableList.
+- **MUST:** Load styles.css or core.css plus reorderable-list.css.
+
+## Common mistakes
+
+- **Avoid:** Using ReorderableList as a sortable table, persisting inside the component, omitting accessible movement names, or making drag the only usable path. **Instead:** Choose the component by user job, keep workflow state in the application, label every control, and expose direct movement where needed.
+
+## Validation checklist
+
+- Check direct movement, keyboard lift/move/drop/cancel, mouse and touch movement, focus preservation, disabled and read-only states, and announcement copy.
+- Check that narrow vertical lists preserve a useful content measure by moving direct Actions below Content, then check horizontal overflow, RTL, zoom, reduced motion, forced colors, light and dark appearance, focus-ring containment, and insertion feedback.
+
+## Related guidance
+
+- `list`
+- `data-grid`
+- `tree`
+- `swipeable-item`

package/dist/agents/segment-group.json

@@ -0,0 +1,62 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "segment-group",
+  "name": "SegmentGroup",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present one mutually exclusive immediate mode in a compact segmented surface with radio semantics and a moving visual indicator.",
+  "useWhen": [
+    "A small visible set such as list/grid, density, or appearance must keep exactly one immediate mode selected."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Commands may be independently pressed, the choices select paired panels, or an ordinary form choice is needed.",
+      "useInstead": "ToggleGroup, Tabs, or RadioGroup according to the interaction"
+    }
+  ],
+  "composition": [
+    "Compose Root with one Indicator and directly owned Items; give Root a complete accessible name and every icon-only Item its own complete name.",
+    "Choose one shared size on Root so adjacent Button, Select, and other named-size controls align through Brick's control contract."
+  ],
+  "rules": [
+    {
+      "id": "segment-group-single-choice",
+      "level": "must",
+      "statement": "Use SegmentGroup only for one mutually exclusive value and preserve Atom Radio Group semantics and keyboard behavior."
+    },
+    {
+      "id": "segment-group-indicator",
+      "level": "must",
+      "statement": "Render one decorative Indicator for the canonical moving-selection recipe; selection and naming must remain on Items."
+    },
+    {
+      "id": "segment-group-not-tabs",
+      "level": "must",
+      "statement": "Do not use SegmentGroup for paired content panels or route navigation; use Tabs or navigation destinations."
+    },
+    {
+      "id": "segment-group-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus segment-group.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using ToggleGroup single mode for a required one-of-many mode or using SegmentGroup as visual tabs.",
+      "correction": "Choose SegmentGroup for one compact radio-semantic mode and Tabs only when panels are paired."
+    }
+  ],
+  "validation": [
+    "Check click, Space, arrows, Home/End, looping, controlled state, disabled/read-only state, and complete accessible naming.",
+    "Check indicator movement after selection and resize, exact shared outer sizes, inset Root boundary, shallow selected elevation, focus containment, light/dark themes, reduced motion, forced colors, zoom, and RTL."
+  ],
+  "related": [
+    "radio-group",
+    "toggle-group",
+    "tabs",
+    "button",
+    "select",
+    "toolbar"
+  ]
+}

package/dist/agents/segment-group.md

@@ -0,0 +1,43 @@
+# SegmentGroup agent guide
+
+## Purpose
+
+Present one mutually exclusive immediate mode in a compact segmented surface with radio semantics and a moving visual indicator.
+
+## Use when
+
+- A small visible set such as list/grid, density, or appearance must keep exactly one immediate mode selected.
+
+## Choose something else when
+
+- Commands may be independently pressed, the choices select paired panels, or an ordinary form choice is needed. Use ToggleGroup, Tabs, or RadioGroup according to the interaction.
+
+## Required composition
+
+- Compose Root with one Indicator and directly owned Items; give Root a complete accessible name and every icon-only Item its own complete name.
+- Choose one shared size on Root so adjacent Button, Select, and other named-size controls align through Brick's control contract.
+
+## Rules
+
+- **MUST:** Use SegmentGroup only for one mutually exclusive value and preserve Atom Radio Group semantics and keyboard behavior.
+- **MUST:** Render one decorative Indicator for the canonical moving-selection recipe; selection and naming must remain on Items.
+- **MUST:** Do not use SegmentGroup for paired content panels or route navigation; use Tabs or navigation destinations.
+- **MUST:** Load styles.css or core.css plus segment-group.css.
+
+## Common mistakes
+
+- **Avoid:** Using ToggleGroup single mode for a required one-of-many mode or using SegmentGroup as visual tabs. **Instead:** Choose SegmentGroup for one compact radio-semantic mode and Tabs only when panels are paired.
+
+## Validation checklist
+
+- Check click, Space, arrows, Home/End, looping, controlled state, disabled/read-only state, and complete accessible naming.
+- Check indicator movement after selection and resize, exact shared outer sizes, inset Root boundary, shallow selected elevation, focus containment, light/dark themes, reduced motion, forced colors, zoom, and RTL.
+
+## Related guidance
+
+- `radio-group`
+- `toggle-group`
+- `tabs`
+- `button`
+- `select`
+- `toolbar`