@flowstack-ui/brick 0.1.9 → 0.1.12

package/dist/agents/em.json

@@ -0,0 +1,57 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "em",
+  "name": "Em",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Apply native stress emphasis while preserving the surrounding Brick typography and foreground.",
+  "useWhen": [
+    "Words in a sentence need semantic stress emphasis that changes the meaning or cadence when spoken."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Text only needs an italic visual treatment without stress emphasis.",
+      "useInstead": "a deliberate application-owned visual recipe"
+    },
+    {
+      "condition": "Text needs importance rather than stress emphasis.",
+      "useInstead": "native strong inside the surrounding text owner"
+    }
+  ],
+  "composition": [
+    "Keep Em inside the Text, heading, link, or component content owner whose sentence it completes."
+  ],
+  "rules": [
+    {
+      "id": "em-native-semantics",
+      "level": "must",
+      "statement": "Use Em only for native stress emphasis and preserve its one em host; do not select it merely for italic paint."
+    },
+    {
+      "id": "em-inheritance",
+      "level": "must",
+      "statement": "Let Em inherit the surrounding typography and foreground rather than introducing a separate size, tone, or weight recipe."
+    },
+    {
+      "id": "em-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus em.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Em as a decorative italic label or replacing a sentence-level text owner with Em.",
+      "correction": "Keep Em inside meaningful surrounding copy and use it only when stress emphasis is semantically intended."
+    }
+  ],
+  "validation": [
+    "Confirm one native em element, inherited metrics and foreground, readable forced colors, normal selection and copy, and no tab stop or role.",
+    "Check nested sentence flow, localization, zoom, RTL, and CSS delivery."
+  ],
+  "related": [
+    "text",
+    "link",
+    "interface-composition"
+  ]
+}

package/dist/agents/em.md

@@ -0,0 +1,39 @@
+# Em agent guide
+
+## Purpose
+
+Apply native stress emphasis while preserving the surrounding Brick typography and foreground.
+
+## Use when
+
+- Words in a sentence need semantic stress emphasis that changes the meaning or cadence when spoken.
+
+## Choose something else when
+
+- Text only needs an italic visual treatment without stress emphasis. Use a deliberate application-owned visual recipe.
+- Text needs importance rather than stress emphasis. Use native strong inside the surrounding text owner.
+
+## Required composition
+
+- Keep Em inside the Text, heading, link, or component content owner whose sentence it completes.
+
+## Rules
+
+- **MUST:** Use Em only for native stress emphasis and preserve its one em host; do not select it merely for italic paint.
+- **MUST:** Let Em inherit the surrounding typography and foreground rather than introducing a separate size, tone, or weight recipe.
+- **MUST:** Load styles.css or core.css plus em.css.
+
+## Common mistakes
+
+- **Avoid:** Using Em as a decorative italic label or replacing a sentence-level text owner with Em. **Instead:** Keep Em inside meaningful surrounding copy and use it only when stress emphasis is semantically intended.
+
+## Validation checklist
+
+- Confirm one native em element, inherited metrics and foreground, readable forced colors, normal selection and copy, and no tab stop or role.
+- Check nested sentence flow, localization, zoom, RTL, and CSS delivery.
+
+## Related guidance
+
+- `text`
+- `link`
+- `interface-composition`

package/dist/agents/feed.json

@@ -0,0 +1,84 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "feed",
+  "name": "Feed",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a styled dynamic stream of rich focusable articles while Atom owns feed semantics, busy state, positions, and keyboard movement.",
+  "useWhen": [
+    "Activity, news, social posts, or rich notifications may change while a person reads and article-by-article keyboard movement is useful."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The sequence is static or has tabular, hierarchical, or purely visual relationships.",
+      "useInstead": "List, Table/DataGrid, Tree, or Stack/Grid according to the relationship"
+    }
+  ],
+  "composition": [
+    "Compose direct Feed.Item articles inside one named Feed.Root; give every Item a useful heading or other accessible name, accurate position metadata, and item-local actions that do not turn the article into one whole-row control.",
+    "Compose ScrollArea outside Root only when a Frame or another parent supplies a definite bounded size.",
+    "Use dividerStrength=default only when a compact utility feed needs clearer row separation; preserve the subtle default for ordinary continuous reading."
+  ],
+  "rules": [
+    {
+      "id": "feed-dynamic-owner",
+      "level": "must",
+      "statement": "Use Feed only for a dynamic rich article stream where feed semantics and article keyboard movement improve the experience."
+    },
+    {
+      "id": "feed-direct-items",
+      "level": "must",
+      "statement": "Keep Feed.Item articles as direct Root children with useful accessible names and accurate positions and totals."
+    },
+    {
+      "id": "feed-busy",
+      "level": "must",
+      "statement": "Set busy only while adding or replacing Feed DOM; do not make a passive feed a live region or treat busy paint as an announcement."
+    },
+    {
+      "id": "feed-actions",
+      "level": "must",
+      "statement": "Keep links, buttons, and menus as independently named descendants; do not make the entire Feed Item a hover or activation target."
+    },
+    {
+      "id": "feed-scroll",
+      "level": "must",
+      "statement": "When the stream is bounded, let Frame own the definite size and ScrollArea own overflow outside Feed.Root."
+    },
+    {
+      "id": "feed-virtualization",
+      "level": "must",
+      "statement": "When an application windows articles, preserve stable identities and full logical positions, keep the focused and next keyboard target articles mounted or materialize them before focus moves, and remember that geometry utilities do not own feed loading or semantics."
+    },
+    {
+      "id": "feed-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus feed.css and every composed child stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Feed for any repeated row, putting non-article children directly in Root, or adding aria-live to a passive notification tray.",
+      "correction": "Choose Feed only for a dynamic article stream, keep direct Item anatomy, and reserve live announcements for application-owned asynchronous feedback."
+    }
+  ],
+  "validation": [
+    "Check Root naming, Item headings, direct article children, positions and totals, busy state, PageUp/PageDown, Control/Command+Home/End, nested control focus, and scroll reveal.",
+    "Check divided, plain, and outline boundaries at narrow widths, zoom, RTL, forced colors, reduced motion, and light/dark appearance.",
+    "For paged or windowed feeds, verify stable keys and full logical metadata and ensure the focused and next PageUp/PageDown target articles exist before focus moves."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "feed",
+      "versionPolicy": "installed-exact"
+    },
+    "list",
+    "scroll-area",
+    "frame",
+    "button",
+    "dropdown-menu"
+  ]
+}

package/dist/agents/feed.md

@@ -0,0 +1,48 @@
+# Feed agent guide
+
+## Purpose
+
+Present a styled dynamic stream of rich focusable articles while Atom owns feed semantics, busy state, positions, and keyboard movement.
+
+## Use when
+
+- Activity, news, social posts, or rich notifications may change while a person reads and article-by-article keyboard movement is useful.
+
+## Choose something else when
+
+- The sequence is static or has tabular, hierarchical, or purely visual relationships. Use List, Table/DataGrid, Tree, or Stack/Grid according to the relationship.
+
+## Required composition
+
+- Compose direct Feed.Item articles inside one named Feed.Root; give every Item a useful heading or other accessible name, accurate position metadata, and item-local actions that do not turn the article into one whole-row control.
+- Compose ScrollArea outside Root only when a Frame or another parent supplies a definite bounded size.
+- Use dividerStrength=default only when a compact utility feed needs clearer row separation; preserve the subtle default for ordinary continuous reading.
+
+## Rules
+
+- **MUST:** Use Feed only for a dynamic rich article stream where feed semantics and article keyboard movement improve the experience.
+- **MUST:** Keep Feed.Item articles as direct Root children with useful accessible names and accurate positions and totals.
+- **MUST:** Set busy only while adding or replacing Feed DOM; do not make a passive feed a live region or treat busy paint as an announcement.
+- **MUST:** Keep links, buttons, and menus as independently named descendants; do not make the entire Feed Item a hover or activation target.
+- **MUST:** When the stream is bounded, let Frame own the definite size and ScrollArea own overflow outside Feed.Root.
+- **MUST:** When an application windows articles, preserve stable identities and full logical positions, keep the focused and next keyboard target articles mounted or materialize them before focus moves, and remember that geometry utilities do not own feed loading or semantics.
+- **MUST:** Load styles.css or core.css plus feed.css and every composed child stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Using Feed for any repeated row, putting non-article children directly in Root, or adding aria-live to a passive notification tray. **Instead:** Choose Feed only for a dynamic article stream, keep direct Item anatomy, and reserve live announcements for application-owned asynchronous feedback.
+
+## Validation checklist
+
+- Check Root naming, Item headings, direct article children, positions and totals, busy state, PageUp/PageDown, Control/Command+Home/End, nested control focus, and scroll reveal.
+- Check divided, plain, and outline boundaries at narrow widths, zoom, RTL, forced colors, reduced motion, and light/dark appearance.
+- For paged or windowed feeds, verify stable keys and full logical metadata and ensure the focused and next PageUp/PageDown target articles exist before focus moves.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/feed`
+- `list`
+- `scroll-area`
+- `frame`
+- `button`
+- `dropdown-menu`

package/dist/agents/field.json

@@ -47,7 +47,12 @@
     "Check vertical and horizontal layouts at narrow widths."
   ],
   "related": [
-    "@flowstack-ui/atom/agents/field",
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "field",
+      "versionPolicy": "installed-exact"
+    },
     "form",
     "fieldset",
     "input",

package/dist/agents/fieldset.json

@@ -41,7 +41,12 @@
     "Check group messaging, state propagation, spacing, and responsive layout."
   ],
   "related": [
-    "@flowstack-ui/atom/agents/fieldset",
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "fieldset",
+      "versionPolicy": "installed-exact"
+    },
     "form",
     "field",
     "checkbox"

package/dist/agents/file-upload.json

@@ -0,0 +1,93 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "file-upload",
+  "name": "FileUpload",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished local-file picker, optional drop target, and removable selected-file list while Atom owns native picking, file state, client acceptance, Field validation, reset, and multipart form participation.",
+  "useWhen": [
+    "A form needs one or more local files selected through the native picker, optional drag and drop, review, removal, or visible client-side rejection feedback before application processing."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A native file input is sufficient, the value is a textual path or URL, the asset is already remote, or the job is transfer progress, retry, persistence, preview editing, or server policy.",
+      "useInstead": "a native input type=file, Input, Progress, Toast, Image, or an application-owned upload workflow"
+    }
+  ],
+  "composition": [
+    "Compose one Field with FileUpload.Root, exactly one HiddenInput, and an accessible Trigger. Add Dropzone only as an enhancement; use ItemGroup with one Item per accepted file and optional ItemName, ItemSize, and file-specific ItemDeleteTrigger.",
+    "State both browse and drop paths plus material constraints in visible copy. Use Root's outline or soft recipe, size, shape, and width while keeping upload transport, progress, rejection copy, and server policy outside FileUpload."
+  ],
+  "rules": [
+    {
+      "id": "file-upload-native-input",
+      "level": "must",
+      "statement": "Render exactly one HiddenInput whenever picker, Trigger, required validity, name, form, accept, or multiple semantics are needed and keep it aligned with the visible control."
+    },
+    {
+      "id": "file-upload-access-path",
+      "level": "must",
+      "statement": "Always provide a visible accessible Trigger for keyboard, touch, and pointer selection; Dropzone alone is not an equivalent picker, and Trigger already owns its button recipe rather than nesting Button."
+    },
+    {
+      "id": "file-upload-validation",
+      "level": "must",
+      "statement": "Use accept, maxFiles, maxSize, and validateFile only for immediate client feedback, show authored localized rejection reasons, and validate type, size, content, authorization, and storage policy again on the server."
+    },
+    {
+      "id": "file-upload-state",
+      "level": "must",
+      "statement": "Use files with onFilesChange or defaultFiles, choose appendFiles deliberately for multiple selection, and distinguish rejected candidates from the validity of the currently selected files."
+    },
+    {
+      "id": "file-upload-drop-form",
+      "level": "must",
+      "statement": "Preserve file-only drag state, nested drag handling, document-drop protection, disabled/read-only behavior, native FileList synchronization, required focus, Field relationships, external form, same-file reselection after deletion, and uncontrolled reset."
+    },
+    {
+      "id": "file-upload-items",
+      "level": "must",
+      "statement": "Keep ItemGroup and Item native list semantics, preserve each complete filename despite visual truncation, give every removal action a file-specific name, and do not nest Brick List or IconButton into the owning parts."
+    },
+    {
+      "id": "file-upload-responsive",
+      "level": "must",
+      "statement": "Keep drop copy and selected-file metadata contained under long filenames, localization, narrow widths, zoom, and RTL while retaining visible focus, non-color accept/reject cues, and effective action targets."
+    },
+    {
+      "id": "file-upload-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus file-upload.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Dropzone as the only picker, treating accept as security, hiding rejection reasons, wrapping Trigger in Button, or forgetting same-file reselection after removal.",
+      "correction": "Include HiddenInput and Trigger, validate again on the server, present rejection feedback, preserve the owning interactive parts, and let Atom synchronize native selection."
+    },
+    {
+      "mistake": "Turning local file selection into an upload transport with progress, retry, preview lifecycle, storage, or malware claims.",
+      "correction": "Keep FileUpload responsible for local selection and compose application-owned transfer status and durable results beside it."
+    }
+  ],
+  "validation": [
+    "Verify picker opening by pointer, touch, Enter, and Space; controlled/uncontrolled files; single replacement and multiple append/replace policy; accept rules; maximum count and size; custom rejection; visible rejection feedback; disabled/read-only state; and same-file reselection.",
+    "Verify accepted/rejected and nested drag behavior, non-file drags, document-drop protection, HiddenInput name/form/required/multiple/FileList behavior, Field labels/errors, inline/native focus, reset, ItemGroup metadata, delete labels, native props, refs, and composition.",
+    "Verify both recipes, all sizes/shapes/widths, long filenames and localized copy, narrow width, zoom, RTL, touch targets, light/dark appearance, forced colors, focus, invalid, disabled, read-only, accept, and reject paint."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "file-upload",
+      "versionPolicy": "installed-exact"
+    },
+    "input",
+    "field",
+    "form",
+    "progress",
+    "toast",
+    "image"
+  ]
+}

package/dist/agents/file-upload.md

@@ -0,0 +1,50 @@
+# FileUpload agent guide
+
+## Purpose
+
+Present a finished local-file picker, optional drop target, and removable selected-file list while Atom owns native picking, file state, client acceptance, Field validation, reset, and multipart form participation.
+
+## Use when
+
+- A form needs one or more local files selected through the native picker, optional drag and drop, review, removal, or visible client-side rejection feedback before application processing.
+
+## Choose something else when
+
+- A native file input is sufficient, the value is a textual path or URL, the asset is already remote, or the job is transfer progress, retry, persistence, preview editing, or server policy. Use a native input type=file, Input, Progress, Toast, Image, or an application-owned upload workflow.
+
+## Required composition
+
+- Compose one Field with FileUpload.Root, exactly one HiddenInput, and an accessible Trigger. Add Dropzone only as an enhancement; use ItemGroup with one Item per accepted file and optional ItemName, ItemSize, and file-specific ItemDeleteTrigger.
+- State both browse and drop paths plus material constraints in visible copy. Use Root's outline or soft recipe, size, shape, and width while keeping upload transport, progress, rejection copy, and server policy outside FileUpload.
+
+## Rules
+
+- **MUST:** Render exactly one HiddenInput whenever picker, Trigger, required validity, name, form, accept, or multiple semantics are needed and keep it aligned with the visible control.
+- **MUST:** Always provide a visible accessible Trigger for keyboard, touch, and pointer selection; Dropzone alone is not an equivalent picker, and Trigger already owns its button recipe rather than nesting Button.
+- **MUST:** Use accept, maxFiles, maxSize, and validateFile only for immediate client feedback, show authored localized rejection reasons, and validate type, size, content, authorization, and storage policy again on the server.
+- **MUST:** Use files with onFilesChange or defaultFiles, choose appendFiles deliberately for multiple selection, and distinguish rejected candidates from the validity of the currently selected files.
+- **MUST:** Preserve file-only drag state, nested drag handling, document-drop protection, disabled/read-only behavior, native FileList synchronization, required focus, Field relationships, external form, same-file reselection after deletion, and uncontrolled reset.
+- **MUST:** Keep ItemGroup and Item native list semantics, preserve each complete filename despite visual truncation, give every removal action a file-specific name, and do not nest Brick List or IconButton into the owning parts.
+- **MUST:** Keep drop copy and selected-file metadata contained under long filenames, localization, narrow widths, zoom, and RTL while retaining visible focus, non-color accept/reject cues, and effective action targets.
+- **MUST:** Load styles.css or core.css plus file-upload.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Using Dropzone as the only picker, treating accept as security, hiding rejection reasons, wrapping Trigger in Button, or forgetting same-file reselection after removal. **Instead:** Include HiddenInput and Trigger, validate again on the server, present rejection feedback, preserve the owning interactive parts, and let Atom synchronize native selection.
+- **Avoid:** Turning local file selection into an upload transport with progress, retry, preview lifecycle, storage, or malware claims. **Instead:** Keep FileUpload responsible for local selection and compose application-owned transfer status and durable results beside it.
+
+## Validation checklist
+
+- Verify picker opening by pointer, touch, Enter, and Space; controlled/uncontrolled files; single replacement and multiple append/replace policy; accept rules; maximum count and size; custom rejection; visible rejection feedback; disabled/read-only state; and same-file reselection.
+- Verify accepted/rejected and nested drag behavior, non-file drags, document-drop protection, HiddenInput name/form/required/multiple/FileList behavior, Field labels/errors, inline/native focus, reset, ItemGroup metadata, delete labels, native props, refs, and composition.
+- Verify both recipes, all sizes/shapes/widths, long filenames and localized copy, narrow width, zoom, RTL, touch targets, light/dark appearance, forced colors, focus, invalid, disabled, read-only, accept, and reject paint.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/file-upload`
+- `input`
+- `field`
+- `form`
+- `progress`
+- `toast`
+- `image`

package/dist/agents/form.json

@@ -16,7 +16,7 @@
     }
   ],
   "composition": [
-    "Compose Form -> Fieldset for related groups -> Field for each control -> a named submit Button."
+    "Compose Form -> Field for each independently labelled control -> a named submit Button; add Fieldset only when multiple controls answer one meaningful group question."
   ],
   "rules": [
     {
@@ -34,6 +34,10 @@
     {
       "mistake": "Treating Form as a complete login or contact workflow.",
       "correction": "Keep business workflow in the application or a future Block; Form owns the generic visual boundary."
+    },
+    {
+      "mistake": "Wrapping the entire form in Fieldset only to obtain spacing, then repeating the page heading as its legend.",
+      "correction": "Let Form own ordinary field rhythm and reserve Fieldset for a real labelled subgroup."
     }
   ],
   "validation": [
@@ -41,7 +45,12 @@
     "Inspect submitted values, invalid relationships, spacing, and narrow-layout behavior."
   ],
   "related": [
-    "@flowstack-ui/atom/agents/form",
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "form",
+      "versionPolicy": "installed-exact"
+    },
     "field",
     "fieldset",
     "button"

package/dist/agents/form.md

@@ -14,7 +14,7 @@ Provide a finished native submission boundary and consistent form rhythm while A
 
 ## Required composition
 
-- Compose Form -> Fieldset for related groups -> Field for each control -> a named submit Button.
+- Compose Form -> Field for each independently labelled control -> a named submit Button; add Fieldset only when multiple controls answer one meaningful group question.
 
 ## Rules
 
@@ -24,6 +24,7 @@ Provide a finished native submission boundary and consistent form rhythm while A
 ## Common mistakes
 
 - **Avoid:** Treating Form as a complete login or contact workflow. **Instead:** Keep business workflow in the application or a future Block; Form owns the generic visual boundary.
+- **Avoid:** Wrapping the entire form in Fieldset only to obtain spacing, then repeating the page heading as its legend. **Instead:** Let Form own ordinary field rhythm and reserve Fieldset for a real labelled subgroup.
 
 ## Validation checklist
 

package/dist/agents/grid.json

@@ -16,7 +16,8 @@
     }
   ],
   "composition": [
-    "Choose Grid tracks from the minimum readable child size; use Grid.Item placement only when source order remains meaningful."
+    "Choose Grid tracks from the minimum readable child size; use Grid.Item placement only when source order remains meaningful.",
+    "Use as=\"ul\" or as=\"ol\" when the peers form a semantic list; Grid removes native list geometry while preserving the list relationship."
   ],
   "rules": [
     {
@@ -24,6 +25,16 @@
       "level": "must",
       "statement": "Keep DOM order meaningful; visual placement must not create a confusing keyboard or reading sequence."
     },
+    {
+      "id": "grid-spacing-values",
+      "level": "must",
+      "statement": "Use non-negative numeric factors for ordinary uniform and axis gaps; reserve explicit CSS values for measured exceptions or application spacing tokens, including inside responsive objects."
+    },
+    {
+      "id": "grid-semantic-list",
+      "level": "must",
+      "statement": "Use a semantic list host when the Grid children form a real set; do not add Block CSS to cancel native ul or ol margins, padding, or markers because Grid owns that host geometry."
+    },
     {
       "id": "grid-responsive-relationships",
       "level": "must",
@@ -45,6 +56,10 @@
       "mistake": "Keeping too many columns until cards become unreadably narrow.",
       "correction": "Reduce columns at the content's real minimum width, not at a device-name breakpoint."
     },
+    {
+      "mistake": "Adding local CSS only because a gap is outside the legacy zero-through-six token scale.",
+      "correction": "Use the supported numeric factor or explicit spacing value on gap, rowGap, or columnGap."
+    },
     {
       "mistake": "Combining a responsive Item span with explicit line placement.",
       "correction": "Let the responsive item auto-place, or keep one deliberate static line placement."
@@ -56,6 +71,8 @@
   ],
   "validation": [
     "Test intrinsic sizing, overflow, zoom, narrow widths, source order, and RTL.",
+    "Confirm numeric, explicit, axis-specific, and responsive gaps create the intended computed geometry.",
+    "For ul and ol hosts, confirm zero native margin and padding, no visual marker, and preserved list semantics.",
     "Confirm each child remains readable before and after track changes."
   ],
   "related": [

package/dist/agents/grid.md

@@ -15,10 +15,13 @@ Arrange content on tokenized two-dimensional tracks with public column, row, gap
 ## Required composition
 
 - Choose Grid tracks from the minimum readable child size; use Grid.Item placement only when source order remains meaningful.
+- Use as="ul" or as="ol" when the peers form a semantic list; Grid removes native list geometry while preserving the list relationship.
 
 ## Rules
 
 - **MUST:** Keep DOM order meaningful; visual placement must not create a confusing keyboard or reading sequence.
+- **MUST:** Use non-negative numeric factors for ordinary uniform and axis gaps; reserve explicit CSS values for measured exceptions or application spacing tokens, including inside responsive objects.
+- **MUST:** Use a semantic list host when the Grid children form a real set; do not add Block CSS to cancel native ul or ol margins, padding, or markers because Grid owns that host geometry.
 - **MUST:** Use responsive columns, gaps, unanchored spans, and alignment when the same authored Grid changes at Brick breakpoints; keep explicit line starts and ends static.
 - **MUST:** Use Grid.Item asChild when an existing link, Surface, or component should itself receive placement; provide exactly one element and preserve its native semantics.
 - **MUST:** Load styles.css or core.css plus grid.css.
@@ -26,12 +29,15 @@ Arrange content on tokenized two-dimensional tracks with public column, row, gap
 ## Common mistakes
 
 - **Avoid:** Keeping too many columns until cards become unreadably narrow. **Instead:** Reduce columns at the content's real minimum width, not at a device-name breakpoint.
+- **Avoid:** Adding local CSS only because a gap is outside the legacy zero-through-six token scale. **Instead:** Use the supported numeric factor or explicit spacing value on gap, rowGap, or columnGap.
 - **Avoid:** Combining a responsive Item span with explicit line placement. **Instead:** Let the responsive item auto-place, or keep one deliberate static line placement.
 - **Avoid:** Adding a Grid.Item wrapper and height CSS around an element that should itself stretch as the grid item. **Instead:** Compose that one element with Grid.Item asChild.
 
 ## Validation checklist
 
 - Test intrinsic sizing, overflow, zoom, narrow widths, source order, and RTL.
+- Confirm numeric, explicit, axis-specific, and responsive gaps create the intended computed geometry.
+- For ul and ol hosts, confirm zero native margin and padding, no visual marker, and preserved list semantics.
 - Confirm each child remains readable before and after track changes.
 
 ## Related guidance

package/dist/agents/group.json

@@ -0,0 +1,77 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "group",
+  "name": "Group",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Create a compact inline visual cluster and optionally attach direct children without changing their semantics or keyboard behavior.",
+  "useWhen": [
+    "Direct children need shared outside corners and joined interior borders.",
+    "A small mixed set of controls or fields needs compact inline grouping."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The relationship needs responsive direction, wrapping, distribution, or ordinary block layout.",
+      "useInstead": "Stack/HStack/VStack"
+    },
+    {
+      "condition": "Commands need roving focus or items own pressed selection.",
+      "useInstead": "Toolbar or ToggleGroup"
+    },
+    {
+      "condition": "Tags, skills, social destinations, profile facts, or responsive actions form a content collection rather than one attached control silhouette.",
+      "useInstead": "List, Grid, DataList, or Stack"
+    }
+  ],
+  "composition": [
+    "Place the intended bordered elements as direct children. Apply variants, sizes, semantics, accessible names, and events to those children."
+  ],
+  "rules": [
+    {
+      "id": "group-attached-chain",
+      "level": "must",
+      "statement": "Use attached only for one unwrapped row or column whose direct children form one continuous visual silhouette."
+    },
+    {
+      "id": "group-semantics",
+      "level": "must",
+      "statement": "Author role=group and an accessible name only when the controls form a genuine accessibility relationship; Group adds neither by default."
+    },
+    {
+      "id": "group-no-behavior",
+      "level": "must",
+      "statement": "Keep keyboard behavior with the composed controls; Group never substitutes for Toolbar, ToggleGroup, or a form group."
+    },
+    {
+      "id": "group-not-content-collection",
+      "level": "must",
+      "statement": "Do not use Group for tags, skills, social destinations, profile facts, or responsive action rows; use List, Grid, DataList, or Stack unless direct children need one compact attached control silhouette."
+    },
+    {
+      "id": "group-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus group.css and every composed child component stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using HStack plus local negative margins, using Toolbar merely to join borders, or using Group as a generic wrapper for unrelated content.",
+      "correction": "Use Group only for the compact or attached direct-child relationship and select List, DataList, Grid, Stack, Toolbar, or ToggleGroup for the actual content or behavior."
+    }
+  ],
+  "validation": [
+    "Check direct-child structure, shared borders, outside logical corners, hover/focus stacking, visible focus rings, RTL, vertical orientation, zoom, forced colors, and narrow containment.",
+    "Confirm Group adds no role, name, selection, or keyboard behavior."
+  ],
+  "related": [
+    "stack",
+    "data-list",
+    "list",
+    "grid",
+    "button",
+    "icon-button",
+    "toolbar",
+    "toggle-group"
+  ]
+}