@flowstack-ui/brick 0.1.9 → 0.1.12

package/dist/agents/progress-circle.md

@@ -0,0 +1,46 @@
+# ProgressCircle agent guide
+
+## Purpose
+
+Present compact circular read-only task progress with Brick-owned SVG ring geometry while Atom Progress owns progressbar semantics, normalized range state, and determinate or indeterminate behavior.
+
+## Use when
+
+- Ongoing measurable or indeterminate work needs compact circular feedback in a card, toolbar, dialog, or other bounded region.
+
+## Choose something else when
+
+- Linear space communicates change more clearly, the value is a stable measurement or user input, stages matter, or the finished layout is loading. Use Progress, the native meter element, Slider, Steps, or Skeleton.
+
+## Required composition
+
+- Give ProgressCircle.Root a concise Label or native accessible name, pass a measurable value or null/omit it for indeterminate work, then compose one Circle with Brick-owned Track before Indicator. Add optional Value and Label outside Circle.
+- Choose size, thickness, cap, and tone on Root. Keep SVG geometry decorative, preserve clockwise motion independent of RTL, and keep application aria-busy state and announcements outside ProgressCircle.
+
+## Rules
+
+- **MUST:** Give Root an accessible task name through Label or native ARIA; Circle, Track, Indicator, and visible Value are decorative or silent and do not replace that name.
+- **MUST:** Use a numeric value only for measurable work, pass null or omit it for indeterminate work, and preserve Atom's truthful min/max normalization, clamping, state, and aria-valuenow behavior.
+- **MUST:** Treat Circle, Track, and Indicator as Brick-owned fixed SVG presentation over Atom Progress context; keep one Circle, order Track before Indicator, and do not override viewBox, radius, circumference, dash array, or dash offset.
+- **MUST:** Keep Root as the only progressbar and announcement path, keep SVG anatomy aria-hidden and unfocusable, and do not make circular progress keyboard adjustable or use it for static measurement.
+- **SHOULD:** Localize optional visible Value and provide aria-valuetext when the numeric range needs domain wording; do not assume the decorative Value changes Root's accessible value text.
+- **MUST:** Keep the ring square, contained within its surrounding region, clockwise in LTR and RTL, label wrapping intact, track visible, and reduced-motion indeterminate state understandable as a static arc.
+- **MUST:** Load styles.css or core.css plus progress-circle.css.
+
+## Common mistakes
+
+- **Avoid:** Using an unlabeled decorative spinner, adding progressbar semantics to SVG, passing zero for unknown work, or reversing the ring in RTL. **Instead:** Name Atom-backed Root, use indeterminate null state, keep Brick SVG silent, and retain clockwise geometry.
+- **Avoid:** Overriding component-owned SVG radius or dash geometry or using ProgressCircle for capacity or input. **Instead:** Use public size/thickness/cap/tone recipes and choose native meter or Slider for other semantic jobs.
+
+## Validation checklist
+
+- Verify Root naming, determinate loading/complete and indeterminate state, aria-valuenow presence/absence, clamping, invalid-range normalization, custom value text, localized visible Value, and Atom state propagation.
+- Verify one Root progressbar, one decorative Circle, Track before Indicator, fixed component-owned geometry, silent/unfocusable SVG, no keyboard interaction, native props, refs, and supported composition.
+- Verify five sizes, three thicknesses, both caps, all tones, square containment, long labels, zoom, clockwise LTR/RTL behavior, track contrast, light/dark appearance, forced colors, and reduced motion.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/progress`
+- `progress`
+- `slider`
+- `skeleton`

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/prose.json

@@ -0,0 +1,82 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "prose",
+  "name": "Prose",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Apply finished descendant typography, rhythm, and readable measure to trusted React content.",
+  "useWhen": [
+    "An application, CMS adapter, or Markdown renderer already produced trusted React children that need coherent editorial typography."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Content is untrusted or still needs HTML or Markdown parsing.",
+      "useInstead": "an application-owned sanitizer and parser before Prose"
+    },
+    {
+      "condition": "A small explicit piece of interface copy needs one recipe.",
+      "useInstead": "Text"
+    },
+    {
+      "condition": "Content needs editing behavior.",
+      "useInstead": "a source-installed editor composition"
+    }
+  ],
+  "composition": [
+    "Pass trusted native React descendants to Prose and let the application own document structure, trust, and data loading.",
+    "Use direct Brick components when richer anatomy or behavior is needed; their classes intentionally override Prose's low-specificity descendant styles."
+  ],
+  "rules": [
+    {
+      "id": "prose-trust",
+      "level": "must",
+      "statement": "Sanitize and parse untrusted external content before it becomes Prose children; Prose never makes raw HTML safe."
+    },
+    {
+      "id": "prose-semantics",
+      "level": "must",
+      "statement": "Keep heading hierarchy, landmark choice, link destinations, table headers, language, and alternative text application-owned."
+    },
+    {
+      "id": "prose-measure",
+      "level": "must",
+      "statement": "Use the narrow, default, wide, or none reading measure intentionally rather than adding duplicate width CSS."
+    },
+    {
+      "id": "prose-components",
+      "level": "must",
+      "statement": "Use direct Link, List, Blockquote, Code Block, Table, or Image components when their richer public contract is required, including accessible preserved horizontal scrolling for source or complex tables."
+    },
+    {
+      "id": "prose-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus prose.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Passing unsanitized HTML through dangerouslySetInnerHTML inside Prose.",
+      "correction": "Keep trust and sanitization in the application, then render trusted React children."
+    },
+    {
+      "mistake": "Using Prose as a generic spacing wrapper around interface controls.",
+      "correction": "Use Stack and Text for interface composition; reserve Prose for editorial descendants."
+    }
+  ],
+  "validation": [
+    "Confirm native descendant semantics and source order remain unchanged.",
+    "Confirm size and measure, headings, lists, links, quotes, tables, code, media, dark appearance, forced colors, narrow widths, zoom, text spacing, localization, RTL, SSR, refs, and modular CSS delivery."
+  ],
+  "related": [
+    "text",
+    "link",
+    "list",
+    "blockquote",
+    "code",
+    "code-block",
+    "table",
+    "image",
+    "interface-composition"
+  ]
+}

package/dist/agents/prose.md

@@ -0,0 +1,50 @@
+# Prose agent guide
+
+## Purpose
+
+Apply finished descendant typography, rhythm, and readable measure to trusted React content.
+
+## Use when
+
+- An application, CMS adapter, or Markdown renderer already produced trusted React children that need coherent editorial typography.
+
+## Choose something else when
+
+- Content is untrusted or still needs HTML or Markdown parsing. Use an application-owned sanitizer and parser before Prose.
+- A small explicit piece of interface copy needs one recipe. Use Text.
+- Content needs editing behavior. Use a source-installed editor composition.
+
+## Required composition
+
+- Pass trusted native React descendants to Prose and let the application own document structure, trust, and data loading.
+- Use direct Brick components when richer anatomy or behavior is needed; their classes intentionally override Prose's low-specificity descendant styles.
+
+## Rules
+
+- **MUST:** Sanitize and parse untrusted external content before it becomes Prose children; Prose never makes raw HTML safe.
+- **MUST:** Keep heading hierarchy, landmark choice, link destinations, table headers, language, and alternative text application-owned.
+- **MUST:** Use the narrow, default, wide, or none reading measure intentionally rather than adding duplicate width CSS.
+- **MUST:** Use direct Link, List, Blockquote, Code Block, Table, or Image components when their richer public contract is required, including accessible preserved horizontal scrolling for source or complex tables.
+- **MUST:** Load styles.css or core.css plus prose.css.
+
+## Common mistakes
+
+- **Avoid:** Passing unsanitized HTML through dangerouslySetInnerHTML inside Prose. **Instead:** Keep trust and sanitization in the application, then render trusted React children.
+- **Avoid:** Using Prose as a generic spacing wrapper around interface controls. **Instead:** Use Stack and Text for interface composition; reserve Prose for editorial descendants.
+
+## Validation checklist
+
+- Confirm native descendant semantics and source order remain unchanged.
+- Confirm size and measure, headings, lists, links, quotes, tables, code, media, dark appearance, forced colors, narrow widths, zoom, text spacing, localization, RTL, SSR, refs, and modular CSS delivery.
+
+## Related guidance
+
+- `text`
+- `link`
+- `list`
+- `blockquote`
+- `code`
+- `code-block`
+- `table`
+- `image`
+- `interface-composition`

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`