@flowstack-ui/brick 0.1.6 → 0.1.11

package/dist/agents/chip.md

@@ -0,0 +1,44 @@
+# Chip agent guide
+
+## Purpose
+
+Present one compact authored or selected value with an optional, explicitly named remove action.
+
+## Use when
+
+- An applied filter, recipient, assignee, category, or other value already in application state needs compact presentation and may be removable.
+
+## Choose something else when
+
+- The content is passive metadata or status with no removal action. Use Badge.
+- The user is choosing or toggling a value rather than removing an existing one. Use Toggle, ToggleGroup, CheckboxGroup, or another matching selection control.
+
+## Required composition
+
+- Compose Root with Label and include RemoveTrigger only when the surrounding application can remove that value; give every RemoveTrigger a value-specific ariaLabel and onPress handler.
+
+## Rules
+
+- **MUST:** Keep Root noninteractive; RemoveTrigger is the only removal control, so clicking the label does not silently perform the action.
+- **MUST:** Name every RemoveTrigger with the value and action, such as ariaLabel="Remove Men filter"; never expose an unlabeled close icon.
+- **MUST:** Treat onPress as a removal request; the parent owns state mutation, URL synchronization, focus recovery, and announcements.
+- **MUST:** Keep the only removal action visible and operable at narrow widths, zoom, and increased text size.
+- **MUST:** Load styles.css or core.css plus chip.css.
+
+## Common mistakes
+
+- **Avoid:** Using one Button for the complete chip so selecting the label removes the value, or adding a decorative x with no accessible action name. **Instead:** Use passive Chip.Root and Chip.Label with a separately named Chip.RemoveTrigger.
+- **Avoid:** Using Chip as a complete editable token-entry system with automatic keyboard deletion and focus movement. **Instead:** Keep standalone Chip parent-controlled and use an Atom-backed collection owner when token-entry behavior is required.
+
+## Validation checklist
+
+- Check visible label, value-specific removal name, mouse and keyboard activation, disabled treatment, focus visibility, and parent-owned removal.
+- Check narrow widths, zoom, long labels, RTL, forced colors, touch targeting, and CSS delivery.
+
+## Related guidance
+
+- `badge`
+- `button`
+- `toggle`
+- `toggle-group`
+- `checkbox-group`

package/dist/agents/code-block.json

@@ -0,0 +1,76 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "code-block",
+  "name": "Code Block",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present preserved multi-line technical source with native scrolling, explicit metadata, optional copy behavior, and consumer-owned syntax highlighting.",
+  "useWhen": [
+    "Source examples, configuration, commands, generated markup, or other preserved multi-line technical content need a finished readable surface."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A short technical literal belongs inside prose.",
+      "useInstead": "Code"
+    },
+    {
+      "condition": "The source must be edited, executed, or behave like a terminal.",
+      "useInstead": "an application-owned editor, sandbox, or terminal"
+    }
+  ],
+  "composition": [
+    "Pass the exact plain-text source to Root value, then place Content inside Root and give focusable Content a specific accessible label.",
+    "Author Header, Title, Language, Actions, CopyTrigger, CopyStatus, and CopyIndicator only when the interface needs those optional parts.",
+    "For syntax highlighting, generate trusted React token nodes outside Brick and pass them to Content while keeping Root value identical to the plain text that must be copied.",
+    "Give the Code Block a bounded parent when vertical page or panel layout requires a fixed scrolling region; Content owns the code's horizontal overflow."
+  ],
+  "rules": [
+    {
+      "id": "code-block-copy-source",
+      "level": "must",
+      "statement": "Keep Root value authoritative and exactly aligned with rendered highlighted content so copy behavior never depends on rendered textContent."
+    },
+    {
+      "id": "code-block-highlighting-owner",
+      "level": "must",
+      "statement": "Keep tokenization, language loading, and syntax palettes in a consumer adapter; Brick accepts trusted React nodes and does not bundle a highlighter or unsafe HTML path."
+    },
+    {
+      "id": "code-block-scroll-owner",
+      "level": "must",
+      "statement": "Let Content own canonical pre, code, focus, and horizontal scrolling instead of rebuilding them with a separate ScrollArea or native pre element."
+    },
+    {
+      "id": "code-block-accessible-name",
+      "level": "must",
+      "statement": "Give every focusable Content region a specific aria-label or aria-labelledby, especially when several examples share one page."
+    },
+    {
+      "id": "code-block-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus code-block.css and its documented component dependencies."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Rendering highlighted HTML with dangerouslySetInnerHTML, copying from token text, or nesting another pre and ScrollArea inside Content.",
+      "correction": "Render trusted React token spans, preserve the original string in Root value, and let Content own the canonical code viewport."
+    },
+    {
+      "mistake": "Adding a header, language label, copy action, or status region merely because those parts exist.",
+      "correction": "Author only the optional anatomy required by the surrounding interface."
+    }
+  ],
+  "validation": [
+    "Confirm the rendered tokens and copied plain text match exactly, unsafe HTML is absent, and copy success, failure, concurrency, and status wording remain truthful when copy anatomy is present.",
+    "Check keyboard focus, uniquely named overflow landmarks, long-line scrolling or wrapping, mobile text sizing, zoom, selection, RTL/LTR, light and dark syntax contrast, and CSS delivery."
+  ],
+  "related": [
+    "code",
+    "scroll-area",
+    "button",
+    "tabs",
+    "interface-composition"
+  ]
+}

package/dist/agents/code-block.md

@@ -0,0 +1,47 @@
+# Code Block agent guide
+
+## Purpose
+
+Present preserved multi-line technical source with native scrolling, explicit metadata, optional copy behavior, and consumer-owned syntax highlighting.
+
+## Use when
+
+- Source examples, configuration, commands, generated markup, or other preserved multi-line technical content need a finished readable surface.
+
+## Choose something else when
+
+- A short technical literal belongs inside prose. Use Code.
+- The source must be edited, executed, or behave like a terminal. Use an application-owned editor, sandbox, or terminal.
+
+## Required composition
+
+- Pass the exact plain-text source to Root value, then place Content inside Root and give focusable Content a specific accessible label.
+- Author Header, Title, Language, Actions, CopyTrigger, CopyStatus, and CopyIndicator only when the interface needs those optional parts.
+- For syntax highlighting, generate trusted React token nodes outside Brick and pass them to Content while keeping Root value identical to the plain text that must be copied.
+- Give the Code Block a bounded parent when vertical page or panel layout requires a fixed scrolling region; Content owns the code's horizontal overflow.
+
+## Rules
+
+- **MUST:** Keep Root value authoritative and exactly aligned with rendered highlighted content so copy behavior never depends on rendered textContent.
+- **MUST:** Keep tokenization, language loading, and syntax palettes in a consumer adapter; Brick accepts trusted React nodes and does not bundle a highlighter or unsafe HTML path.
+- **MUST:** Let Content own canonical pre, code, focus, and horizontal scrolling instead of rebuilding them with a separate ScrollArea or native pre element.
+- **MUST:** Give every focusable Content region a specific aria-label or aria-labelledby, especially when several examples share one page.
+- **MUST:** Load styles.css or core.css plus code-block.css and its documented component dependencies.
+
+## Common mistakes
+
+- **Avoid:** Rendering highlighted HTML with dangerouslySetInnerHTML, copying from token text, or nesting another pre and ScrollArea inside Content. **Instead:** Render trusted React token spans, preserve the original string in Root value, and let Content own the canonical code viewport.
+- **Avoid:** Adding a header, language label, copy action, or status region merely because those parts exist. **Instead:** Author only the optional anatomy required by the surrounding interface.
+
+## Validation checklist
+
+- Confirm the rendered tokens and copied plain text match exactly, unsafe HTML is absent, and copy success, failure, concurrency, and status wording remain truthful when copy anatomy is present.
+- Check keyboard focus, uniquely named overflow landmarks, long-line scrolling or wrapping, mobile text sizing, zoom, selection, RTL/LTR, light and dark syntax contrast, and CSS delivery.
+
+## Related guidance
+
+- `code`
+- `scroll-area`
+- `button`
+- `tabs`
+- `interface-composition`

package/dist/agents/code.json

@@ -0,0 +1,67 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "code",
+  "name": "Code",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a short inline technical literal with native code semantics and a finished Brick technical-text recipe.",
+  "useWhen": [
+    "A short identifier, attribute, command, filename, value, or API name belongs inside prose or a compact label."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The source is multi-line, preserves whitespace, needs language metadata, or may scroll.",
+      "useInstead": "Code Block"
+    },
+    {
+      "condition": "The content represents keyboard input, computer output, a variable, editable source, or executable source.",
+      "useInstead": "the correct native semantic element or an application-owned editor, terminal, or sandbox"
+    }
+  ],
+  "composition": [
+    "Keep Code inside the surrounding Text or component content owner when the literal completes that sentence or label.",
+    "Choose subtle for an independently visible inline token and plain with tone inherit when the surrounding component already owns paint and foreground."
+  ],
+  "rules": [
+    {
+      "id": "code-native-semantics",
+      "level": "must",
+      "statement": "Use Code only for a short computer-code fragment and preserve its one native code host; do not select it merely to obtain monospace typography."
+    },
+    {
+      "id": "code-inline-boundary",
+      "level": "must",
+      "statement": "Keep Code inline with the prose or compact label it completes and use Code Block for multi-line or overflow-owned technical source."
+    },
+    {
+      "id": "code-recipe-selection",
+      "level": "must",
+      "statement": "Choose variant, tone, and size through the closed Code recipes before overriding public variables; use tone inherit when a parent intentionally owns foreground contrast."
+    },
+    {
+      "id": "code-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus code.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using generic Text or a native span with monospace CSS for a real technical literal.",
+      "correction": "Use Code so the literal keeps native code semantics and the shared Brick technical recipe."
+    },
+    {
+      "mistake": "Putting a complete diff, command transcript, or configuration example inside Code.",
+      "correction": "Use Code Block so preserved whitespace, naming, focus, and overflow have one explicit owner."
+    }
+  ],
+  "validation": [
+    "Confirm one native code element, correct surrounding sentence flow, safe wrapping of long tokens, and no unintended block or scroll behavior.",
+    "Check inherited typography, subtle and plain recipes, light and dark appearances, forced colors, zoom, localization, RTL/bidi content, and CSS delivery."
+  ],
+  "related": [
+    "code-block",
+    "text",
+    "interface-composition"
+  ]
+}

package/dist/agents/code.md

@@ -0,0 +1,42 @@
+# Code agent guide
+
+## Purpose
+
+Present a short inline technical literal with native code semantics and a finished Brick technical-text recipe.
+
+## Use when
+
+- A short identifier, attribute, command, filename, value, or API name belongs inside prose or a compact label.
+
+## Choose something else when
+
+- The source is multi-line, preserves whitespace, needs language metadata, or may scroll. Use Code Block.
+- The content represents keyboard input, computer output, a variable, editable source, or executable source. Use the correct native semantic element or an application-owned editor, terminal, or sandbox.
+
+## Required composition
+
+- Keep Code inside the surrounding Text or component content owner when the literal completes that sentence or label.
+- Choose subtle for an independently visible inline token and plain with tone inherit when the surrounding component already owns paint and foreground.
+
+## Rules
+
+- **MUST:** Use Code only for a short computer-code fragment and preserve its one native code host; do not select it merely to obtain monospace typography.
+- **MUST:** Keep Code inline with the prose or compact label it completes and use Code Block for multi-line or overflow-owned technical source.
+- **MUST:** Choose variant, tone, and size through the closed Code recipes before overriding public variables; use tone inherit when a parent intentionally owns foreground contrast.
+- **MUST:** Load styles.css or core.css plus code.css.
+
+## Common mistakes
+
+- **Avoid:** Using generic Text or a native span with monospace CSS for a real technical literal. **Instead:** Use Code so the literal keeps native code semantics and the shared Brick technical recipe.
+- **Avoid:** Putting a complete diff, command transcript, or configuration example inside Code. **Instead:** Use Code Block so preserved whitespace, naming, focus, and overflow have one explicit owner.
+
+## Validation checklist
+
+- Confirm one native code element, correct surrounding sentence flow, safe wrapping of long tokens, and no unintended block or scroll behavior.
+- Check inherited typography, subtle and plain recipes, light and dark appearances, forced colors, zoom, localization, RTL/bidi content, and CSS delivery.
+
+## Related guidance
+
+- `code-block`
+- `text`
+- `interface-composition`

package/dist/agents/collapsible.json

@@ -21,7 +21,8 @@
   ],
   "composition": [
     "Compose Root with one Trigger and one Content; put ContentInner inside Content so visible padding does not corrupt measured animation geometry.",
-    "Use Indicator inside Trigger for the canonical decorative state cue; normal Brick layout and content components belong inside ContentInner."
+    "Use Indicator inside Trigger for the canonical decorative state cue; the default points down while closed and up while open, and normal Brick layout and content components belong inside ContentInner.",
+    "Use Trigger iconOnly for a square, centered disclosure control; give it a complete accessible name and let the Root size own its target."
   ],
   "rules": [
     {
@@ -44,10 +45,30 @@
       "level": "must",
       "statement": "Use Collapsible for in-flow disclosure, not as a substitute for modal Drawer behavior or responsive Show/Hide policy."
     },
+    {
+      "id": "collapsible-presence",
+      "level": "must",
+      "statement": "Leave keepMounted false unless retained DOM or exit animation is required; when enabled, preserve Atom's closed hidden state and never expose retained descendants to interaction."
+    },
+    {
+      "id": "collapsible-live-measurement",
+      "level": "must",
+      "statement": "Consume Atom's live content width and height variables for Brick motion across responsive reflow and intrinsic content changes; never hard-code a stale measured dimension or animate a competing wrapper."
+    },
     {
       "id": "collapsible-css",
       "level": "must",
       "statement": "Load styles.css or core.css plus collapsible.css."
+    },
+    {
+      "id": "collapsible-indicator-direction",
+      "level": "must",
+      "statement": "Keep the default Indicator pointing down while closed and up while open in both LTR and RTL; use custom decorative artwork only for a deliberate alternate state language."
+    },
+    {
+      "id": "collapsible-icon-only",
+      "level": "must",
+      "statement": "Use Trigger iconOnly instead of sizing a general Trigger with layout wrappers when the disclosure control contains only artwork."
     }
   ],
   "commonMistakes": [
@@ -55,6 +76,10 @@
       "mistake": "Using Collapsible Trigger asChild around a finished Button or Icon Button.",
       "correction": "Use Trigger as the only visual control owner and author its label, icon, and optional Indicator directly."
     },
+    {
+      "mistake": "Forcing a normal Trigger into a square with Frame or local alignment CSS.",
+      "correction": "Use Trigger iconOnly so its Root size supplies square geometry and centered artwork."
+    },
     {
       "mistake": "Putting padding on Content or animating an application wrapper independently.",
       "correction": "Keep Content as the measured motion boundary and put visible spacing in ContentInner."
@@ -65,11 +90,17 @@
     }
   ],
   "validation": [
-    "Test the accessible Trigger name, aria-expanded/aria-controls relationship, Enter and Space, controlled and uncontrolled state, disabled behavior, and focus retention.",
-    "Test open/close measurement, dynamic content, reduced motion, long labels, narrow widths, RTL, and horizontal overflow.",
+    "Test the accessible Trigger name, aria-expanded/aria-controls relationship, Enter and Space, controlled and uncontrolled state, disabled behavior, focus retention, the default down/up Indicator state, and icon-only centering.",
+    "Test default unmount, keepMounted hidden descendants, initial-open state, open/close measurement, dynamic and responsive width/height changes, exit presence, reduced motion, long labels, narrow widths, RTL, and horizontal overflow without unintended page-load entrance motion.",
     "When adapting Collapsible inside another surface, report any Root geometry override instead of silently treating plain as a behavior-only recipe."
   ],
   "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "collapsible",
+      "versionPolicy": "installed-exact"
+    },
     "accordion",
     "drawer",
     "app-bar",

package/dist/agents/collapsible.md

@@ -16,7 +16,8 @@ Reveal one independent in-flow region while Atom owns disclosure state, relation
 ## Required composition
 
 - Compose Root with one Trigger and one Content; put ContentInner inside Content so visible padding does not corrupt measured animation geometry.
-- Use Indicator inside Trigger for the canonical decorative state cue; normal Brick layout and content components belong inside ContentInner.
+- Use Indicator inside Trigger for the canonical decorative state cue; the default points down while closed and up while open, and normal Brick layout and content components belong inside ContentInner.
+- Use Trigger iconOnly for a square, centered disclosure control; give it a complete accessible name and let the Root size own its target.
 
 ## Rules
 
@@ -24,22 +25,28 @@ Reveal one independent in-flow region while Atom owns disclosure state, relation
 - **MUST:** Let Collapsible Trigger own its finished control recipe; do not compose Button or Icon Button into Trigger because competing visual recipes would own one element.
 - **MUST:** Keep visible padding in ContentInner rather than Content so Atom can measure and animate the region accurately.
 - **MUST:** Use Collapsible for in-flow disclosure, not as a substitute for modal Drawer behavior or responsive Show/Hide policy.
+- **MUST:** Leave keepMounted false unless retained DOM or exit animation is required; when enabled, preserve Atom's closed hidden state and never expose retained descendants to interaction.
+- **MUST:** Consume Atom's live content width and height variables for Brick motion across responsive reflow and intrinsic content changes; never hard-code a stale measured dimension or animate a competing wrapper.
 - **MUST:** Load styles.css or core.css plus collapsible.css.
+- **MUST:** Keep the default Indicator pointing down while closed and up while open in both LTR and RTL; use custom decorative artwork only for a deliberate alternate state language.
+- **MUST:** Use Trigger iconOnly instead of sizing a general Trigger with layout wrappers when the disclosure control contains only artwork.
 
 ## Common mistakes
 
 - **Avoid:** Using Collapsible Trigger asChild around a finished Button or Icon Button. **Instead:** Use Trigger as the only visual control owner and author its label, icon, and optional Indicator directly.
+- **Avoid:** Forcing a normal Trigger into a square with Frame or local alignment CSS. **Instead:** Use Trigger iconOnly so its Root size supplies square geometry and centered artwork.
 - **Avoid:** Putting padding on Content or animating an application wrapper independently. **Instead:** Keep Content as the measured motion boundary and put visible spacing in ContentInner.
 - **Avoid:** Choosing Collapsible when the page must be inert behind the open panel. **Instead:** Use Drawer or Dialog so Atom can own modal isolation, focus, dismissal, and scroll locking.
 
 ## Validation checklist
 
-- Test the accessible Trigger name, aria-expanded/aria-controls relationship, Enter and Space, controlled and uncontrolled state, disabled behavior, and focus retention.
-- Test open/close measurement, dynamic content, reduced motion, long labels, narrow widths, RTL, and horizontal overflow.
+- Test the accessible Trigger name, aria-expanded/aria-controls relationship, Enter and Space, controlled and uncontrolled state, disabled behavior, focus retention, the default down/up Indicator state, and icon-only centering.
+- Test default unmount, keepMounted hidden descendants, initial-open state, open/close measurement, dynamic and responsive width/height changes, exit presence, reduced motion, long labels, narrow widths, RTL, and horizontal overflow without unintended page-load entrance motion.
 - When adapting Collapsible inside another surface, report any Root geometry override instead of silently treating plain as a behavior-only recipe.
 
 ## Related guidance
 
+- `@flowstack-ui/atom/agents/collapsible`
 - `accordion`
 - `drawer`
 - `app-bar`

package/dist/agents/color-picker.json

@@ -0,0 +1,78 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "color-picker",
+  "name": "Color Picker",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Edit, choose, and submit an opaque hexadecimal color through a finished text, native chooser, preset, or optional floating composition.",
+  "useWhen": [
+    "A form needs one #rrggbb color value selected through editable text, the browser chooser, named presets, or a popover that combines them."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The interface only previews a color.",
+      "useInstead": "Color Swatch"
+    },
+    {
+      "condition": "The task requires alpha, gradients, color-space conversion, channels, an eyedropper, or contrast analysis.",
+      "useInstead": "an application-owned specialist until Atom releases that behavior"
+    }
+  ],
+  "composition": [
+    "Place Label and Control inside Root; include HiddenInput when the value participates in native form submission.",
+    "Compose Trigger with Content for a floating picker, or omit both for inline editing.",
+    "Put ColorSwatch.Root inside Trigger and SwatchTrigger for finished previews while the surrounding control carries the accessible name and selected state."
+  ],
+  "rules": [
+    {
+      "id": "color-picker-label",
+      "level": "must",
+      "statement": "Give Input and NativeInput accessible names through Label or explicit aria-label values."
+    },
+    {
+      "id": "color-picker-form",
+      "level": "must",
+      "statement": "Provide name to Root and render exactly one HiddenInput when the color must submit."
+    },
+    {
+      "id": "color-picker-hex",
+      "level": "must",
+      "statement": "Use #rgb or #rrggbb; this release intentionally supports opaque hexadecimal values only."
+    },
+    {
+      "id": "color-picker-css",
+      "level": "must",
+      "statement": "Load styles.css, or core.css plus both color-picker.css and color-swatch.css when swatches are composed."
+    },
+    {
+      "id": "color-picker-preset-name",
+      "level": "should",
+      "statement": "Give presets human-readable names; do not rely on color alone or a raw hex string when a product name exists."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Reimplementing color parsing, picker state, or Popover behavior in Brick or application code.",
+      "correction": "Use the Atom-backed ColorPicker parts and controlled props."
+    },
+    {
+      "mistake": "Naming both Input and HiddenInput for form submission.",
+      "correction": "Put name on Root and render one HiddenInput."
+    },
+    {
+      "mistake": "Assuming Chakra's area, alpha, channel, format, or eyedropper parts exist.",
+      "correction": "Stay within the released Brick anatomy and treat richer behavior as Atom-first future work."
+    }
+  ],
+  "validation": [
+    "Test text, native, preset, controlled, disabled, read-only, invalid, form submit/reset, Escape/focus restoration, light/dark, forced-colors, narrow/zoom, RTL, and non-color selection cues."
+  ],
+  "related": [
+    "color-swatch",
+    "field",
+    "form",
+    "input",
+    "popover"
+  ]
+}

package/dist/agents/color-picker.md

@@ -0,0 +1,46 @@
+# Color Picker agent guide
+
+## Purpose
+
+Edit, choose, and submit an opaque hexadecimal color through a finished text, native chooser, preset, or optional floating composition.
+
+## Use when
+
+- A form needs one #rrggbb color value selected through editable text, the browser chooser, named presets, or a popover that combines them.
+
+## Choose something else when
+
+- The interface only previews a color. Use Color Swatch.
+- The task requires alpha, gradients, color-space conversion, channels, an eyedropper, or contrast analysis. Use an application-owned specialist until Atom releases that behavior.
+
+## Required composition
+
+- Place Label and Control inside Root; include HiddenInput when the value participates in native form submission.
+- Compose Trigger with Content for a floating picker, or omit both for inline editing.
+- Put ColorSwatch.Root inside Trigger and SwatchTrigger for finished previews while the surrounding control carries the accessible name and selected state.
+
+## Rules
+
+- **MUST:** Give Input and NativeInput accessible names through Label or explicit aria-label values.
+- **MUST:** Provide name to Root and render exactly one HiddenInput when the color must submit.
+- **MUST:** Use #rgb or #rrggbb; this release intentionally supports opaque hexadecimal values only.
+- **MUST:** Load styles.css, or core.css plus both color-picker.css and color-swatch.css when swatches are composed.
+- **SHOULD:** Give presets human-readable names; do not rely on color alone or a raw hex string when a product name exists.
+
+## Common mistakes
+
+- **Avoid:** Reimplementing color parsing, picker state, or Popover behavior in Brick or application code. **Instead:** Use the Atom-backed ColorPicker parts and controlled props.
+- **Avoid:** Naming both Input and HiddenInput for form submission. **Instead:** Put name on Root and render one HiddenInput.
+- **Avoid:** Assuming Chakra's area, alpha, channel, format, or eyedropper parts exist. **Instead:** Stay within the released Brick anatomy and treat richer behavior as Atom-first future work.
+
+## Validation checklist
+
+- Test text, native, preset, controlled, disabled, read-only, invalid, form submit/reset, Escape/focus restoration, light/dark, forced-colors, narrow/zoom, RTL, and non-color selection cues.
+
+## Related guidance
+
+- `color-swatch`
+- `field`
+- `form`
+- `input`
+- `popover`

package/dist/agents/color-swatch.json

@@ -0,0 +1,51 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "color-swatch",
+  "name": "Color Swatch",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Preview one color or a compact mix of colors with a finished alpha-aware visual treatment.",
+  "useWhen": [
+    "A selected, available, saved, or documented color needs a compact visual preview."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The user must choose or edit a color.",
+      "useInstead": "Color Picker"
+    }
+  ],
+  "composition": [
+    "Render Root for one color and Mix for two or more colors; place the swatch inside the owning control when it represents a selectable option."
+  ],
+  "rules": [
+    {
+      "id": "color-swatch-meaning",
+      "level": "must",
+      "statement": "Do not use the swatch as the only carrier of a color name, selection state, validation state, or action."
+    },
+    {
+      "id": "color-swatch-semantics",
+      "level": "must",
+      "statement": "Leave decorative swatches unlabeled, or provide label when the swatch itself must be exposed as an image."
+    },
+    {
+      "id": "color-swatch-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus color-swatch.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Adding click handlers directly to ColorSwatch.",
+      "correction": "Place the passive swatch inside Button, Color Picker preset behavior, or another semantic control."
+    }
+  ],
+  "validation": [
+    "Check solid, alpha, mixed, size, light/dark, forced-color, zoom, RTL, and decorative versus labeled semantics."
+  ],
+  "related": [
+    "badge",
+    "input"
+  ]
+}

package/dist/agents/color-swatch.md

@@ -0,0 +1,36 @@
+# Color Swatch agent guide
+
+## Purpose
+
+Preview one color or a compact mix of colors with a finished alpha-aware visual treatment.
+
+## Use when
+
+- A selected, available, saved, or documented color needs a compact visual preview.
+
+## Choose something else when
+
+- The user must choose or edit a color. Use Color Picker.
+
+## Required composition
+
+- Render Root for one color and Mix for two or more colors; place the swatch inside the owning control when it represents a selectable option.
+
+## Rules
+
+- **MUST:** Do not use the swatch as the only carrier of a color name, selection state, validation state, or action.
+- **MUST:** Leave decorative swatches unlabeled, or provide label when the swatch itself must be exposed as an image.
+- **MUST:** Load styles.css or core.css plus color-swatch.css.
+
+## Common mistakes
+
+- **Avoid:** Adding click handlers directly to ColorSwatch. **Instead:** Place the passive swatch inside Button, Color Picker preset behavior, or another semantic control.
+
+## Validation checklist
+
+- Check solid, alpha, mixed, size, light/dark, forced-color, zoom, RTL, and decorative versus labeled semantics.
+
+## Related guidance
+
+- `badge`
+- `input`