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

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

@@ -0,0 +1,132 @@
+# Frame
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: frame
+
+# Frame agent guide
+
+## Purpose
+
+Own responsive logical size constraints for one local element without taking over layout, paint, spacing, or overflow.
+
+## Use when
+
+- A rail, copy region, media canvas, or scroll boundary needs an explicit inline or block size constraint.
+
+## Choose something else when
+
+- The need is shared page measure, child arrangement, paint, aspect ratio, or scrolling. Use Container, Stack/Grid, Surface, AspectRatio, or ScrollArea.
+
+## Required composition
+
+- Use Frame inside a layout Item, or let Stack.Item/Grid.Item compose asChild around Frame when one host must own both parent participation and internal constraints.
+- For bounded long content, put ScrollArea inside a maxBlockSize Frame; Frame constrains and ScrollArea scrolls.
+
+## Rules
+
+- **MUST:** Use Frame only for inlineSize, minInlineSize, maxInlineSize, blockSize, minBlockSize, or maxBlockSize.
+- **MUST:** Prefer logical size constraints and responsive values rather than physical width/height application classes.
+- **MUST:** Keep flex/grid participation on Stack.Item or Grid.Item; Frame owns the constrained element's internal geometry.
+- **MUST:** Use nested Frames when separate ancestors need separate constraints; each Frame keeps its base and responsive values locally scoped.
+- **MUST:** Do not treat maxBlockSize as scrolling; compose ScrollArea when overflow must remain reachable.
+- **MUST:** Load styles.css or core.css plus frame.css.
+
+## Common mistakes
+
+- **Avoid:** Turning Frame into a universal Box with paint, spacing, position, overflow, and typography props. **Instead:** Keep Frame to six logical constraints and compose the existing Brick owner for every other responsibility.
+
+## Validation checklist
+
+- Check responsive carry-forward, zoom/reflow, long content, RTL, vertical writing, and focus visibility.
+- Confirm every constrained node has one clear job and that ScrollArea owns any required overflow.
+
+## Related guidance
+
+- `stack`
+- `grid`
+- `container`
+- `section`
+- `surface`
+- `aspect-ratio`
+- `scroll-area`
+- `interface-composition`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "frame",
+  "name": "Frame",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Own responsive logical size constraints for one local element without taking over layout, paint, spacing, or overflow.",
+  "useWhen": [
+    "A rail, copy region, media canvas, or scroll boundary needs an explicit inline or block size constraint."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The need is shared page measure, child arrangement, paint, aspect ratio, or scrolling.",
+      "useInstead": "Container, Stack/Grid, Surface, AspectRatio, or ScrollArea"
+    }
+  ],
+  "composition": [
+    "Use Frame inside a layout Item, or let Stack.Item/Grid.Item compose asChild around Frame when one host must own both parent participation and internal constraints.",
+    "For bounded long content, put ScrollArea inside a maxBlockSize Frame; Frame constrains and ScrollArea scrolls."
+  ],
+  "rules": [
+    {
+      "id": "frame-constraint-owner",
+      "level": "must",
+      "statement": "Use Frame only for inlineSize, minInlineSize, maxInlineSize, blockSize, minBlockSize, or maxBlockSize."
+    },
+    {
+      "id": "frame-logical",
+      "level": "must",
+      "statement": "Prefer logical size constraints and responsive values rather than physical width/height application classes."
+    },
+    {
+      "id": "frame-parent-participation",
+      "level": "must",
+      "statement": "Keep flex/grid participation on Stack.Item or Grid.Item; Frame owns the constrained element's internal geometry."
+    },
+    {
+      "id": "frame-nesting",
+      "level": "must",
+      "statement": "Use nested Frames when separate ancestors need separate constraints; each Frame keeps its base and responsive values locally scoped."
+    },
+    {
+      "id": "frame-overflow",
+      "level": "must",
+      "statement": "Do not treat maxBlockSize as scrolling; compose ScrollArea when overflow must remain reachable."
+    },
+    {
+      "id": "frame-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus frame.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Turning Frame into a universal Box with paint, spacing, position, overflow, and typography props.",
+      "correction": "Keep Frame to six logical constraints and compose the existing Brick owner for every other responsibility."
+    }
+  ],
+  "validation": [
+    "Check responsive carry-forward, zoom/reflow, long content, RTL, vertical writing, and focus visibility.",
+    "Confirm every constrained node has one clear job and that ScrollArea owns any required overflow."
+  ],
+  "related": [
+    "stack",
+    "grid",
+    "container",
+    "section",
+    "surface",
+    "aspect-ratio",
+    "scroll-area",
+    "interface-composition"
+  ]
+}
+```

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

@@ -0,0 +1,141 @@
+# Grid
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: grid
+
+# Grid agent guide
+
+## Purpose
+
+Arrange content on tokenized two-dimensional tracks with public column, row, gap, and item-placement controls.
+
+## Use when
+
+- Content needs coordinated rows and columns or responsive card tracks.
+
+## Choose something else when
+
+- The layout has one primary row or column. Use Stack.
+
+## 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.
+
+## 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
+
+- `stack`
+- `card`
+- `surface`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "grid",
+  "name": "Grid",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Arrange content on tokenized two-dimensional tracks with public column, row, gap, and item-placement controls.",
+  "useWhen": [
+    "Content needs coordinated rows and columns or responsive card tracks."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The layout has one primary row or column.",
+      "useInstead": "Stack"
+    }
+  ],
+  "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": [
+    {
+      "id": "grid-source-order",
+      "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",
+      "statement": "Use responsive columns, gaps, unanchored spans, and alignment when the same authored Grid changes at Brick breakpoints; keep explicit line starts and ends static."
+    },
+    {
+      "id": "grid-item-as-child",
+      "level": "must",
+      "statement": "Use Grid.Item asChild when an existing link, Surface, or component should itself receive placement; provide exactly one element and preserve its native semantics."
+    },
+    {
+      "id": "grid-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus grid.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "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."
+    },
+    {
+      "mistake": "Adding a Grid.Item wrapper and height CSS around an element that should itself stretch as the grid item.",
+      "correction": "Compose that one element with Grid.Item asChild."
+    }
+  ],
+  "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": [
+    "stack",
+    "card",
+    "surface"
+  ]
+}
+```

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

@@ -0,0 +1,136 @@
+# Group
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: group
+
+# Group agent guide
+
+## Purpose
+
+Create a compact inline visual cluster and optionally attach direct children without changing their semantics or keyboard behavior.
+
+## Use when
+
+- Direct children need shared outside corners and joined interior borders.
+- A small mixed set of controls or fields needs compact inline grouping.
+
+## Choose something else when
+
+- The relationship needs responsive direction, wrapping, distribution, or ordinary block layout. Use Stack/HStack/VStack.
+- Commands need roving focus or items own pressed selection. Use Toolbar or ToggleGroup.
+- Tags, skills, social destinations, profile facts, or responsive actions form a content collection rather than one attached control silhouette. Use List, Grid, DataList, or Stack.
+
+## Required composition
+
+- Place the intended bordered elements as direct children. Apply variants, sizes, semantics, accessible names, and events to those children.
+
+## Rules
+
+- **MUST:** Use attached only for one unwrapped row or column whose direct children form one continuous visual silhouette.
+- **MUST:** Author role=group and an accessible name only when the controls form a genuine accessibility relationship; Group adds neither by default.
+- **MUST:** Keep keyboard behavior with the composed controls; Group never substitutes for Toolbar, ToggleGroup, or a form group.
+- **MUST:** 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.
+- **MUST:** Load styles.css or core.css plus group.css and every composed child component stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Using HStack plus local negative margins, using Toolbar merely to join borders, or using Group as a generic wrapper for unrelated content. **Instead:** 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 checklist
+
+- 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 guidance
+
+- `stack`
+- `data-list`
+- `list`
+- `grid`
+- `button`
+- `icon-button`
+- `toolbar`
+- `toggle-group`
+
+## Machine record
+
+```json
+{
+  "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"
+  ]
+}
+```

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

@@ -0,0 +1,121 @@
+# Hide
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: hide
+
+# Hide agent guide
+
+## Purpose
+
+Hide content through Brick's CSS breakpoint contract without JavaScript viewport state or hydration flicker.
+
+## Use when
+
+- One composition should be absent at selected Brick breakpoints while remaining present elsewhere.
+
+## Choose something else when
+
+- Content should be visually hidden but remain available to assistive technology, or should not render for business reasons. Use VisuallyHidden or application conditional rendering.
+
+## Required composition
+
+- Wrap the smallest complete region whose presence changes; pair with Show only when desktop and mobile genuinely need distinct compositions.
+
+## Rules
+
+- **MUST:** Use Hide instead of JavaScript matchMedia for first-paint responsive visibility.
+- **MUST:** Do not hide the only accessible name, error, instruction, or required content at a breakpoint.
+- **MUST:** Rely on Hide's layout-transparent visible state inside parent layouts and put paint or geometry on a child layout component.
+- **MUST:** Omit default-valued props such as as=div; use as only for deliberate HTML semantics or valid document structure.
+- **MUST:** Load styles.css or core.css plus hide.css.
+
+## Common mistakes
+
+- **Avoid:** Adding application CSS to repair Hide spacing or writing as=div even though div is the default. **Instead:** Rely on Hide's layout-transparent default and specify as only when semantics require another host.
+- **Avoid:** Using Hide without its modular CSS or duplicating two interactive trees with conflicting IDs. **Instead:** Load hide.css and verify alternate compositions have independent valid relationships.
+
+## Validation checklist
+
+- Test boundary pixels, zoom, first paint, hydration, focus order, and duplicate IDs across all visibility states.
+- Confirm CSS is loaded.
+
+## Related guidance
+
+- `show`
+- `visually-hidden`
+- `app-bar`
+- `drawer`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "hide",
+  "name": "Hide",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Hide content through Brick's CSS breakpoint contract without JavaScript viewport state or hydration flicker.",
+  "useWhen": [
+    "One composition should be absent at selected Brick breakpoints while remaining present elsewhere."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Content should be visually hidden but remain available to assistive technology, or should not render for business reasons.",
+      "useInstead": "VisuallyHidden or application conditional rendering"
+    }
+  ],
+  "composition": [
+    "Wrap the smallest complete region whose presence changes; pair with Show only when desktop and mobile genuinely need distinct compositions."
+  ],
+  "rules": [
+    {
+      "id": "hide-css-breakpoint",
+      "level": "must",
+      "statement": "Use Hide instead of JavaScript matchMedia for first-paint responsive visibility."
+    },
+    {
+      "id": "hide-no-semantic-loss",
+      "level": "must",
+      "statement": "Do not hide the only accessible name, error, instruction, or required content at a breakpoint."
+    },
+    {
+      "id": "hide-transparent-layout",
+      "level": "must",
+      "statement": "Rely on Hide's layout-transparent visible state inside parent layouts and put paint or geometry on a child layout component."
+    },
+    {
+      "id": "hide-default-props",
+      "level": "must",
+      "statement": "Omit default-valued props such as as=div; use as only for deliberate HTML semantics or valid document structure."
+    },
+    {
+      "id": "hide-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus hide.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Adding application CSS to repair Hide spacing or writing as=div even though div is the default.",
+      "correction": "Rely on Hide's layout-transparent default and specify as only when semantics require another host."
+    },
+    {
+      "mistake": "Using Hide without its modular CSS or duplicating two interactive trees with conflicting IDs.",
+      "correction": "Load hide.css and verify alternate compositions have independent valid relationships."
+    }
+  ],
+  "validation": [
+    "Test boundary pixels, zoom, first paint, hydration, focus order, and duplicate IDs across all visibility states.",
+    "Confirm CSS is loaded."
+  ],
+  "related": [
+    "show",
+    "visually-hidden",
+    "app-bar",
+    "drawer"
+  ]
+}
+```