@flowstack-ui/agent-tools 0.1.0-bootstrap.0

package/public/packages/brick/0.1.11/components/container.txt

@@ -0,0 +1,112 @@
+# Container
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: container
+
+# Container agent guide
+
+## Purpose
+
+Own consistent centered content width, logical page gutters, and size variants for sections and application shells.
+
+## Use when
+
+- Page or section content needs a shared maximum inline size and responsive logical gutters.
+
+## Choose something else when
+
+- The region needs a visual boundary or only a local one-axis relationship. Use Surface/Card or Stack.
+
+## Required composition
+
+- Place section content inside Container, then use Stack or Grid for internal relationships; let full-bleed backgrounds live outside it.
+
+## Rules
+
+- **MUST:** Use Container rather than repeating application max-width, auto-margin, and gutter CSS across sections.
+- **MUST:** Give adjacent shell regions that must share alignment lines, such as an App Bar, hero content, and attached proof rail, the same Container measure and gutter recipe.
+- **MUST:** Do not use Container as a visual card or background owner.
+- **MUST:** Load styles.css or core.css plus container.css.
+
+## Common mistakes
+
+- **Avoid:** Applying a separate max-width class to every page section, giving visually connected shell regions different measures or gutters, or nesting Containers without a width reason. **Instead:** Use one deliberate Container boundary per aligned content region and repeat the same named measure and gutter where separate regions must share a grid line.
+
+## Validation checklist
+
+- Check gutters, max width, and shared alignment lines at all adopted breakpoints, zoom levels, and RTL.
+- Confirm full-bleed and contained regions align intentionally and CSS is loaded.
+
+## Related guidance
+
+- `stack`
+- `grid`
+- `surface`
+- `card`
+- `app-bar`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "container",
+  "name": "Container",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Own consistent centered content width, logical page gutters, and size variants for sections and application shells.",
+  "useWhen": [
+    "Page or section content needs a shared maximum inline size and responsive logical gutters."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The region needs a visual boundary or only a local one-axis relationship.",
+      "useInstead": "Surface/Card or Stack"
+    }
+  ],
+  "composition": [
+    "Place section content inside Container, then use Stack or Grid for internal relationships; let full-bleed backgrounds live outside it."
+  ],
+  "rules": [
+    {
+      "id": "container-width-owner",
+      "level": "must",
+      "statement": "Use Container rather than repeating application max-width, auto-margin, and gutter CSS across sections."
+    },
+    {
+      "id": "container-shared-geometry",
+      "level": "must",
+      "statement": "Give adjacent shell regions that must share alignment lines, such as an App Bar, hero content, and attached proof rail, the same Container measure and gutter recipe."
+    },
+    {
+      "id": "container-not-surface",
+      "level": "must",
+      "statement": "Do not use Container as a visual card or background owner."
+    },
+    {
+      "id": "container-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus container.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Applying a separate max-width class to every page section, giving visually connected shell regions different measures or gutters, or nesting Containers without a width reason.",
+      "correction": "Use one deliberate Container boundary per aligned content region and repeat the same named measure and gutter where separate regions must share a grid line."
+    }
+  ],
+  "validation": [
+    "Check gutters, max width, and shared alignment lines at all adopted breakpoints, zoom levels, and RTL.",
+    "Confirm full-bleed and contained regions align intentionally and CSS is loaded."
+  ],
+  "related": [
+    "stack",
+    "grid",
+    "surface",
+    "card",
+    "app-bar"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/context-menu.txt

@@ -0,0 +1,174 @@
+# ContextMenu
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: context-menu
+
+# ContextMenu agent guide
+
+## Purpose
+
+Present finished target-specific commands at a secondary-click, keyboard context-menu invocation, or cancel-safe touch and pen long press while Atom owns invocation, menu semantics, focus, dismissal, and positioning.
+
+## Use when
+
+- Commands belong to the exact file, row, canvas object, or region invoked contextually and every important command also has a visible or keyboard-discoverable route.
+
+## Choose something else when
+
+- The actions need a visible button, are the only route to an important task, or belong to a persistent application command bar. Use DropdownMenu, visible Brick controls, or Menubar.
+- The content is site navigation or form-value selection. Use NavigationMenu or NavList, or Select.
+
+## Required composition
+
+- Compose ContextMenu.Root with ContextMenu.Trigger around the owned target and ContextMenu.Portal with ContextMenu.Content. Build Content from uniquely valued Item, CheckboxItem, RadioGroup and RadioItem, Group and Label, Separator, and paired Sub, SubTrigger, and SubContent parts; use Leading, ItemLabel, Description, Shortcut, and ItemIndicator for finished rows.
+- Keep Trigger paintless and preserve the target's native semantics through asChild or render. Give Content ariaLabel when the target cannot supply an appropriate menu label, and reproduce any local Appearance scope on the portalled visual root.
+
+## Rules
+
+- **MUST:** Provide another visible or keyboard-discoverable route to every important command; ContextMenu is an enhancement, never the only access path.
+- **MUST:** Keep Trigger as a paintless behavior wrapper and preserve the target's native role, name, action, handlers, and composition instead of inventing button semantics or target paint.
+- **MUST:** Rely on Atom for secondary-click coordinates, Shift+F10 and Context Menu key anchoring, cross-target handoff, and the fixed cancel-safe 700 ms touch and pen long press; do not add gesture timers or positioning listeners.
+- **MUST:** Give Content an explicit ariaLabel when the contextual target cannot generate an appropriate accessible menu name.
+- **MUST:** Use uniquely valued command, checkbox, and radio item roles, provide textValue when rendered content is not searchable text, and preserve disabled-item navigation, typeahead, closeOnSelect, and paired submenu behavior.
+- **MUST:** Use Leading, ItemLabel, Description, Shortcut, ItemIndicator, and tone=danger for their documented jobs instead of rebuilding row columns, selection glyphs, or destructive emphasis.
+- **SHOULD:** Keep Content collision-aware and internally scrollable at its available height; verify repeated invocation points, edge collision, zoom, narrow viewports, long labels, and LTR and RTL submenus without changing it into a mobile tray.
+- **MUST:** When Portal leaves a local Appearance scope, reproduce that scope on the portalled visual root or target a portal container inside it.
+- **MUST:** Load styles.css or core.css plus context-menu.css and every composed child component stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Making right-click the only route to an action, styling Trigger as a control, or implementing another long-press and point-positioning system. **Instead:** Keep visible alternatives, preserve target semantics, and use ContextMenu's owned invocation contract.
+- **Avoid:** Using ContextMenu for navigation or form selection, hand-building row columns, or closing the menu tree with document listeners. **Instead:** Choose the semantic owner, compose the public item anatomy, and rely on Atom's Menu focus and dismissal behavior.
+
+## Validation checklist
+
+- Verify the visible alternative, secondary click at changing coordinates, Shift+F10 and Context Menu key opening, repeated and cross-target invocation, disabled state, and touch and pen hold cancellation for movement, scroll, release, cancellation, second pointer, native contextmenu, and unmount.
+- Verify Content naming, real item focus, Home/End and typeahead, disabled navigation without activation, checkbox mixed and radio state, selection close policy, submenu keys and whole-tree dismissal, Tab, Escape, outside activation, and focus return.
+- Verify three densities, row anatomy and danger meaning, constrained scrolling, collision placement, zoom, narrow viewports, LTR and RTL, reduced motion, forced colors, light and dark portalled appearance, and complete CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/context-menu`
+- `@flowstack-ui/atom/agents/menu`
+- `dropdown-menu`
+- `menubar`
+- `navigation-menu`
+- `nav-list`
+- `select`
+- `button`
+- `appearance`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "context-menu",
+  "name": "ContextMenu",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present finished target-specific commands at a secondary-click, keyboard context-menu invocation, or cancel-safe touch and pen long press while Atom owns invocation, menu semantics, focus, dismissal, and positioning.",
+  "useWhen": [
+    "Commands belong to the exact file, row, canvas object, or region invoked contextually and every important command also has a visible or keyboard-discoverable route."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The actions need a visible button, are the only route to an important task, or belong to a persistent application command bar.",
+      "useInstead": "DropdownMenu, visible Brick controls, or Menubar"
+    },
+    {
+      "condition": "The content is site navigation or form-value selection.",
+      "useInstead": "NavigationMenu or NavList, or Select"
+    }
+  ],
+  "composition": [
+    "Compose ContextMenu.Root with ContextMenu.Trigger around the owned target and ContextMenu.Portal with ContextMenu.Content. Build Content from uniquely valued Item, CheckboxItem, RadioGroup and RadioItem, Group and Label, Separator, and paired Sub, SubTrigger, and SubContent parts; use Leading, ItemLabel, Description, Shortcut, and ItemIndicator for finished rows.",
+    "Keep Trigger paintless and preserve the target's native semantics through asChild or render. Give Content ariaLabel when the target cannot supply an appropriate menu label, and reproduce any local Appearance scope on the portalled visual root."
+  ],
+  "rules": [
+    {
+      "id": "context-menu-supplemental",
+      "level": "must",
+      "statement": "Provide another visible or keyboard-discoverable route to every important command; ContextMenu is an enhancement, never the only access path."
+    },
+    {
+      "id": "context-menu-trigger-semantics",
+      "level": "must",
+      "statement": "Keep Trigger as a paintless behavior wrapper and preserve the target's native role, name, action, handlers, and composition instead of inventing button semantics or target paint."
+    },
+    {
+      "id": "context-menu-input-contract",
+      "level": "must",
+      "statement": "Rely on Atom for secondary-click coordinates, Shift+F10 and Context Menu key anchoring, cross-target handoff, and the fixed cancel-safe 700 ms touch and pen long press; do not add gesture timers or positioning listeners."
+    },
+    {
+      "id": "context-menu-content-name",
+      "level": "must",
+      "statement": "Give Content an explicit ariaLabel when the contextual target cannot generate an appropriate accessible menu name."
+    },
+    {
+      "id": "context-menu-item-model",
+      "level": "must",
+      "statement": "Use uniquely valued command, checkbox, and radio item roles, provide textValue when rendered content is not searchable text, and preserve disabled-item navigation, typeahead, closeOnSelect, and paired submenu behavior."
+    },
+    {
+      "id": "context-menu-row-anatomy",
+      "level": "must",
+      "statement": "Use Leading, ItemLabel, Description, Shortcut, ItemIndicator, and tone=danger for their documented jobs instead of rebuilding row columns, selection glyphs, or destructive emphasis."
+    },
+    {
+      "id": "context-menu-responsive",
+      "level": "should",
+      "statement": "Keep Content collision-aware and internally scrollable at its available height; verify repeated invocation points, edge collision, zoom, narrow viewports, long labels, and LTR and RTL submenus without changing it into a mobile tray."
+    },
+    {
+      "id": "context-menu-theme-scope",
+      "level": "must",
+      "statement": "When Portal leaves a local Appearance scope, reproduce that scope on the portalled visual root or target a portal container inside it."
+    },
+    {
+      "id": "context-menu-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus context-menu.css and every composed child component stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Making right-click the only route to an action, styling Trigger as a control, or implementing another long-press and point-positioning system.",
+      "correction": "Keep visible alternatives, preserve target semantics, and use ContextMenu's owned invocation contract."
+    },
+    {
+      "mistake": "Using ContextMenu for navigation or form selection, hand-building row columns, or closing the menu tree with document listeners.",
+      "correction": "Choose the semantic owner, compose the public item anatomy, and rely on Atom's Menu focus and dismissal behavior."
+    }
+  ],
+  "validation": [
+    "Verify the visible alternative, secondary click at changing coordinates, Shift+F10 and Context Menu key opening, repeated and cross-target invocation, disabled state, and touch and pen hold cancellation for movement, scroll, release, cancellation, second pointer, native contextmenu, and unmount.",
+    "Verify Content naming, real item focus, Home/End and typeahead, disabled navigation without activation, checkbox mixed and radio state, selection close policy, submenu keys and whole-tree dismissal, Tab, Escape, outside activation, and focus return.",
+    "Verify three densities, row anatomy and danger meaning, constrained scrolling, collision placement, zoom, narrow viewports, LTR and RTL, reduced motion, forced colors, light and dark portalled appearance, and complete CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "context-menu",
+      "versionPolicy": "installed-exact"
+    },
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "menu",
+      "versionPolicy": "installed-exact"
+    },
+    "dropdown-menu",
+    "menubar",
+    "navigation-menu",
+    "nav-list",
+    "select",
+    "button",
+    "appearance"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/data-grid.txt

@@ -0,0 +1,199 @@
+# Data Grid
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: data-grid
+
+# Data Grid agent guide
+
+## Purpose
+
+Present flat interactive tabular data with Atom-owned active-cell navigation and optional row selection while applications own data, sorting, filtering, and pagination.
+
+## Use when
+
+- People must navigate tabular cells with arrow keys, select rows, or activate sortable column headers.
+
+## Choose something else when
+
+- People only need to read and compare static row-and-column data. Use Table.
+- The content is a visual card collection or ordinary two-dimensional page layout. Use Grid, List, or Card composition.
+- Cells must contain independent controls, support editing, resize or pin columns, virtualize rows, or expose a schema-driven enterprise data engine. Use An application-owned data tool or a separately qualified future component.
+
+## Required composition
+
+- Compose explicit Container when wide content needs horizontal overflow, then Root with Caption or another stable accessible name, Header, Body, optional Footer, indexed Rows, indexed ColumnHeaders, and Cells.
+- Keep all row and column indexes one-based and provide truthful logical rowCount and columnCount, including when only one page or window is rendered.
+- Place external Toolbar, filtering controls, result count, and Pagination around the grid; Data Grid never creates or executes those systems.
+- For application-controlled sorting, give the ColumnHeader onAction, update the data and sortDirection outside Data Grid, and keep SortIndicator decorative.
+
+## Rules
+
+- **MUST:** Choose Data Grid only when composite keyboard navigation, row selection, or sortable-header activation has real value; use Table for static comparison.
+- **MUST:** Provide one stable accessible name, one-based row and column indexes, and truthful logical counts for the complete represented data set.
+- **MUST:** Keep data transformation, filtering, sorting direction changes, fetching, caching, URL state, pagination, stale-request cancellation, and persistence in the application.
+- **MUST:** Compose independently named Brick controls and Pagination outside Root; do not place arbitrary interactive controls inside v1 cells or make the grid itself own surrounding workflow state.
+- **MUST:** Author DataGrid.Container explicitly when honest columns need horizontal overflow; Root never inserts containment and narrow layouts must preserve the tabular relationships.
+- **MUST:** Let the outline Root own its border, radius, and exposed cell corners; do not add a second framed or clipping wrapper to repair the outline recipe.
+- **MUST:** Use stable row IDs as selection values, keep active cell and row selection as independent states, and do not derive identity from the current visual index.
+- **MUST:** Give an actionable sortable ColumnHeader pointer and Enter parity, expose sortDirection only on the active sorted header, and treat SortIndicator as decorative.
+- **MUST:** If an application windows rows, preserve full logical one-based indexes and totals and keep the active cell mounted or move active state before it leaves the DOM; geometry utilities do not own grid semantics or focus.
+- **MUST:** Load styles.css or core.css plus data-grid.css.
+
+## Common mistakes
+
+- **Avoid:** Using Data Grid because a static table has many rows. **Instead:** Use Table until arrow-key cell navigation, row selection, or sortable-header activation is a genuine task requirement.
+- **Avoid:** Putting search, filters, pagination, fetches, and data mutation inside Data Grid. **Instead:** Compose those application-owned systems around the public Data Grid anatomy.
+- **Avoid:** Placing buttons, links, editable fields, or menus in v1 cells without an interaction mode. **Instead:** Keep cells non-editing and use an application-owned data tool when independent cell controls are required.
+- **Avoid:** Using zero-based or page-local indexes while claiming a larger logical set. **Instead:** Pass one-based logical indexes and truthful counts so active-descendant announcements remain coherent.
+- **Avoid:** Wrapping an outline Data Grid in another bordered or rounded clipping surface to hide sharp cell corners. **Instead:** Keep Container responsible only for overflow and let the outline Root own one complete rounded boundary.
+
+## Validation checklist
+
+- Inspect the accessible name, roles, one-based indexes, logical counts, active descendant, selection metadata, disabled/read-only states, and sort direction.
+- Test one Tab entry, arrows, Home and End, PageUp and PageDown, Ctrl or Meta plus Home and End, RTL mapping, disabled skipping, and pointer or Enter sortable-header parity.
+- Verify stable selection IDs and focus after application sorting, filtering, page changes, or reordered data.
+- Check explicit Container overflow, complete outline corners with and without Header or Footer, 320 CSS pixels, 200% text, 400% zoom, long content, dark appearance, forced colors, and no page-level horizontal overflow.
+- Confirm editing, arbitrary cell controls, virtualization, schemas, fetching, filtering, pagination, and persistence remain excluded.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/data-grid`
+- `table`
+- `tree-grid`
+- `toolbar`
+- `pagination`
+- `badge`
+- `scroll-area`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "data-grid",
+  "name": "Data Grid",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present flat interactive tabular data with Atom-owned active-cell navigation and optional row selection while applications own data, sorting, filtering, and pagination.",
+  "useWhen": [
+    "People must navigate tabular cells with arrow keys, select rows, or activate sortable column headers."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "People only need to read and compare static row-and-column data.",
+      "useInstead": "Table"
+    },
+    {
+      "condition": "The content is a visual card collection or ordinary two-dimensional page layout.",
+      "useInstead": "Grid, List, or Card composition"
+    },
+    {
+      "condition": "Cells must contain independent controls, support editing, resize or pin columns, virtualize rows, or expose a schema-driven enterprise data engine.",
+      "useInstead": "An application-owned data tool or a separately qualified future component"
+    }
+  ],
+  "composition": [
+    "Compose explicit Container when wide content needs horizontal overflow, then Root with Caption or another stable accessible name, Header, Body, optional Footer, indexed Rows, indexed ColumnHeaders, and Cells.",
+    "Keep all row and column indexes one-based and provide truthful logical rowCount and columnCount, including when only one page or window is rendered.",
+    "Place external Toolbar, filtering controls, result count, and Pagination around the grid; Data Grid never creates or executes those systems.",
+    "For application-controlled sorting, give the ColumnHeader onAction, update the data and sortDirection outside Data Grid, and keep SortIndicator decorative."
+  ],
+  "rules": [
+    {
+      "id": "data-grid-interactive-boundary",
+      "level": "must",
+      "statement": "Choose Data Grid only when composite keyboard navigation, row selection, or sortable-header activation has real value; use Table for static comparison."
+    },
+    {
+      "id": "data-grid-name-index-count",
+      "level": "must",
+      "statement": "Provide one stable accessible name, one-based row and column indexes, and truthful logical counts for the complete represented data set."
+    },
+    {
+      "id": "data-grid-data-ownership",
+      "level": "must",
+      "statement": "Keep data transformation, filtering, sorting direction changes, fetching, caching, URL state, pagination, stale-request cancellation, and persistence in the application."
+    },
+    {
+      "id": "data-grid-external-controls",
+      "level": "must",
+      "statement": "Compose independently named Brick controls and Pagination outside Root; do not place arbitrary interactive controls inside v1 cells or make the grid itself own surrounding workflow state."
+    },
+    {
+      "id": "data-grid-overflow",
+      "level": "must",
+      "statement": "Author DataGrid.Container explicitly when honest columns need horizontal overflow; Root never inserts containment and narrow layouts must preserve the tabular relationships."
+    },
+    {
+      "id": "data-grid-outline-owner",
+      "level": "must",
+      "statement": "Let the outline Root own its border, radius, and exposed cell corners; do not add a second framed or clipping wrapper to repair the outline recipe."
+    },
+    {
+      "id": "data-grid-selection-identity",
+      "level": "must",
+      "statement": "Use stable row IDs as selection values, keep active cell and row selection as independent states, and do not derive identity from the current visual index."
+    },
+    {
+      "id": "data-grid-sort-composition",
+      "level": "must",
+      "statement": "Give an actionable sortable ColumnHeader pointer and Enter parity, expose sortDirection only on the active sorted header, and treat SortIndicator as decorative."
+    },
+    {
+      "id": "data-grid-virtualization",
+      "level": "must",
+      "statement": "If an application windows rows, preserve full logical one-based indexes and totals and keep the active cell mounted or move active state before it leaves the DOM; geometry utilities do not own grid semantics or focus."
+    },
+    {
+      "id": "data-grid-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus data-grid.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Data Grid because a static table has many rows.",
+      "correction": "Use Table until arrow-key cell navigation, row selection, or sortable-header activation is a genuine task requirement."
+    },
+    {
+      "mistake": "Putting search, filters, pagination, fetches, and data mutation inside Data Grid.",
+      "correction": "Compose those application-owned systems around the public Data Grid anatomy."
+    },
+    {
+      "mistake": "Placing buttons, links, editable fields, or menus in v1 cells without an interaction mode.",
+      "correction": "Keep cells non-editing and use an application-owned data tool when independent cell controls are required."
+    },
+    {
+      "mistake": "Using zero-based or page-local indexes while claiming a larger logical set.",
+      "correction": "Pass one-based logical indexes and truthful counts so active-descendant announcements remain coherent."
+    },
+    {
+      "mistake": "Wrapping an outline Data Grid in another bordered or rounded clipping surface to hide sharp cell corners.",
+      "correction": "Keep Container responsible only for overflow and let the outline Root own one complete rounded boundary."
+    }
+  ],
+  "validation": [
+    "Inspect the accessible name, roles, one-based indexes, logical counts, active descendant, selection metadata, disabled/read-only states, and sort direction.",
+    "Test one Tab entry, arrows, Home and End, PageUp and PageDown, Ctrl or Meta plus Home and End, RTL mapping, disabled skipping, and pointer or Enter sortable-header parity.",
+    "Verify stable selection IDs and focus after application sorting, filtering, page changes, or reordered data.",
+    "Check explicit Container overflow, complete outline corners with and without Header or Footer, 320 CSS pixels, 200% text, 400% zoom, long content, dark appearance, forced colors, and no page-level horizontal overflow.",
+    "Confirm editing, arbitrary cell controls, virtualization, schemas, fetching, filtering, pagination, and persistence remain excluded."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "data-grid",
+      "versionPolicy": "installed-exact"
+    },
+    "table",
+    "tree-grid",
+    "toolbar",
+    "pagination",
+    "badge",
+    "scroll-area"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/data-list.txt

@@ -0,0 +1,115 @@
+# Data List
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: data-list
+
+# Data List agent guide
+
+## Purpose
+
+Present repeated term/value metadata with native description-list semantics and a finished responsive recipe.
+
+## Use when
+
+- Several related labels and values describe one record, profile, object, or specification set.
+
+## Choose something else when
+
+- Items are peers rather than terms and descriptions, or the content is a columnar dataset. Use List for peers or Table/Data Grid for columnar data.
+- The values are editable form controls. Use Field or Fieldset.
+
+## Required composition
+
+- Compose Root with Item groups; place one or more Label parts before one or more Value parts inside every Item.
+
+## Rules
+
+- **MUST:** Use Root, Item, Label, and Value so the rendered dl/div/dt/dd grammar remains valid; do not recreate the relationship with ul/li or generic Stack children.
+- **MUST:** Keep one label-then-value source order and use responsive orientation rather than duplicating mobile and desktop metadata trees.
+- **MUST:** Write visible meaningful labels; do not add empty Label parts solely to force alignment.
+- **MUST:** Load styles.css or core.css plus data-list.css.
+
+## Common mistakes
+
+- **Avoid:** Using List for phone/email/title facts or adding ARIA term/definition roles to native Data List parts. **Instead:** Use DataList native anatomy and rely on its native semantics without redundant ARIA.
+
+## Validation checklist
+
+- Check dl/div/dt/dd anatomy, complete visible labels, source order, horizontal and vertical orientation, long values, links inside Value, zoom, RTL, forced colors, and CSS loading.
+
+## Related guidance
+
+- `list`
+- `table`
+- `data-grid`
+- `field`
+- `stack`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "data-list",
+  "name": "Data List",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present repeated term/value metadata with native description-list semantics and a finished responsive recipe.",
+  "useWhen": [
+    "Several related labels and values describe one record, profile, object, or specification set."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Items are peers rather than terms and descriptions, or the content is a columnar dataset.",
+      "useInstead": "List for peers or Table/Data Grid for columnar data"
+    },
+    {
+      "condition": "The values are editable form controls.",
+      "useInstead": "Field or Fieldset"
+    }
+  ],
+  "composition": [
+    "Compose Root with Item groups; place one or more Label parts before one or more Value parts inside every Item."
+  ],
+  "rules": [
+    {
+      "id": "data-list-native-anatomy",
+      "level": "must",
+      "statement": "Use Root, Item, Label, and Value so the rendered dl/div/dt/dd grammar remains valid; do not recreate the relationship with ul/li or generic Stack children."
+    },
+    {
+      "id": "data-list-responsive-source",
+      "level": "must",
+      "statement": "Keep one label-then-value source order and use responsive orientation rather than duplicating mobile and desktop metadata trees."
+    },
+    {
+      "id": "data-list-labels",
+      "level": "must",
+      "statement": "Write visible meaningful labels; do not add empty Label parts solely to force alignment."
+    },
+    {
+      "id": "data-list-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus data-list.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using List for phone/email/title facts or adding ARIA term/definition roles to native Data List parts.",
+      "correction": "Use DataList native anatomy and rely on its native semantics without redundant ARIA."
+    }
+  ],
+  "validation": [
+    "Check dl/div/dt/dd anatomy, complete visible labels, source order, horizontal and vertical orientation, long values, links inside Value, zoom, RTL, forced colors, and CSS loading."
+  ],
+  "related": [
+    "list",
+    "table",
+    "data-grid",
+    "field",
+    "stack"
+  ]
+}
+```