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

package/public/packages/brick/0.1.11/components/skip-link.txt

@@ -0,0 +1,102 @@
+# SkipLink
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: skip-link
+
+# SkipLink agent guide
+
+## Purpose
+
+Provide a visibly focused skip-navigation control and matching main-content target using Atom focus behavior.
+
+## Use when
+
+- A page repeats header or navigation content before main content.
+
+## Choose something else when
+
+- No repeated content precedes the primary content. Use normal document focus order.
+
+## Required composition
+
+- Place Root as the first useful focus target and one matching Target at main content; let Target own the main landmark unless custom-rendered.
+
+## Rules
+
+- **MUST:** Keep Root visible and readable when focused in every theme and viewport.
+- **MUST:** Do not create duplicate main landmarks around Target.
+- **MUST:** Load styles.css or core.css plus skip-link.css.
+
+## Common mistakes
+
+- **Avoid:** Hiding the link permanently, clipping its focus ring, or targeting a missing id. **Instead:** Use the matching Root/Target pair and test from the browser chrome.
+
+## Validation checklist
+
+- Tab to Root, activate it, and confirm Target receives visible focus and scrolls into view.
+- Check themes, zoom, sticky headers, one main landmark, and CSS delivery.
+
+## Related guidance
+
+- `app-bar`
+- `sidebar`
+- `link`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "skip-link",
+  "name": "SkipLink",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a visibly focused skip-navigation control and matching main-content target using Atom focus behavior.",
+  "useWhen": [
+    "A page repeats header or navigation content before main content."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "No repeated content precedes the primary content.",
+      "useInstead": "normal document focus order"
+    }
+  ],
+  "composition": [
+    "Place Root as the first useful focus target and one matching Target at main content; let Target own the main landmark unless custom-rendered."
+  ],
+  "rules": [
+    {
+      "id": "skip-link-visible-focus",
+      "level": "must",
+      "statement": "Keep Root visible and readable when focused in every theme and viewport."
+    },
+    {
+      "id": "skip-link-one-main",
+      "level": "must",
+      "statement": "Do not create duplicate main landmarks around Target."
+    },
+    {
+      "id": "skip-link-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus skip-link.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Hiding the link permanently, clipping its focus ring, or targeting a missing id.",
+      "correction": "Use the matching Root/Target pair and test from the browser chrome."
+    }
+  ],
+  "validation": [
+    "Tab to Root, activate it, and confirm Target receives visible focus and scrolls into view.",
+    "Check themes, zoom, sticky headers, one main landmark, and CSS delivery."
+  ],
+  "related": [
+    "app-bar",
+    "sidebar",
+    "link"
+  ]
+}
+```

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

@@ -0,0 +1,147 @@
+# Slider
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: slider
+
+# Slider agent guide
+
+## Purpose
+
+Provide a styled approximate numeric single-value or range input while Atom owns pointer, touch, keyboard, form, and field behavior.
+
+## Use when
+
+- A person chooses an approximate value or bounded range and direct manipulation is more useful than exact text entry.
+
+## Choose something else when
+
+- Exact numeric entry, a small named choice set, or read-only completion is the real job. Use NumberInput, Select, or Progress.
+
+## Required composition
+
+- Compose Root > Track > Range plus one indexed Thumb for every value; place optional Marker parts in Track and optional ValueLabel inside its Thumb.
+- Use Slider as the sole control in one Field when a visible label, description, error, or required state is needed; otherwise name every standalone Thumb explicitly.
+
+## Rules
+
+- **MUST:** Render one indexed Thumb for every value and keep Marker inside Track and ValueLabel inside the owning Thumb.
+- **MUST:** Use Slider only when approximate direct manipulation is appropriate; use NumberInput or Select when exact or named choices matter.
+- **MUST:** Provide one visible Field label for the complete Slider or a complete accessible name for every standalone Thumb.
+- **SHOULD:** Use an external application-owned output when dense ranges or long localized values would collide with a thumb ValueLabel.
+- **MUST:** Use onValueChange for live updates and onValueCommit for completed interactions; true pointer cancellation restores the pointer-down value without commit while lost capture commits the latest value.
+- **MUST:** Preserve one active pointer session, non-slider-axis page scrolling, orientation-aware keys, and horizontal LTR and RTL pointer and Arrow behavior.
+- **SHOULD:** Keep the default Track inset when a parent clips overflow; set the public Track-inset token to zero only when the surrounding composition preserves complete endpoint target and focus paint.
+- **MUST:** Load styles.css or core.css plus slider.css.
+
+## Common mistakes
+
+- **Avoid:** Rendering a range with one Thumb, treating decorative markers as labels, or using Slider for a discrete named choice without explaining the values. **Instead:** Match Thumbs to values, label the actual control, and choose Select or RadioGroup when names carry the meaning.
+
+## Validation checklist
+
+- Check pointer, touch, keyboard, large steps, range bounds, controlled values, reset, disabled, read-only, invalid, and form submission.
+- Check horizontal and vertical orientation, RTL, narrow containment, complete 44px endpoint targets, any customized Track inset, zoom, reduced motion, forced colors, and label readability.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/slider`
+- `field`
+- `number-input`
+- `select`
+- `progress`
+- `rating`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "slider",
+  "name": "Slider",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a styled approximate numeric single-value or range input while Atom owns pointer, touch, keyboard, form, and field behavior.",
+  "useWhen": [
+    "A person chooses an approximate value or bounded range and direct manipulation is more useful than exact text entry."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Exact numeric entry, a small named choice set, or read-only completion is the real job.",
+      "useInstead": "NumberInput, Select, or Progress"
+    }
+  ],
+  "composition": [
+    "Compose Root > Track > Range plus one indexed Thumb for every value; place optional Marker parts in Track and optional ValueLabel inside its Thumb.",
+    "Use Slider as the sole control in one Field when a visible label, description, error, or required state is needed; otherwise name every standalone Thumb explicitly."
+  ],
+  "rules": [
+    {
+      "id": "slider-value-anatomy",
+      "level": "must",
+      "statement": "Render one indexed Thumb for every value and keep Marker inside Track and ValueLabel inside the owning Thumb."
+    },
+    {
+      "id": "slider-approximate-choice",
+      "level": "must",
+      "statement": "Use Slider only when approximate direct manipulation is appropriate; use NumberInput or Select when exact or named choices matter."
+    },
+    {
+      "id": "slider-accessible-name",
+      "level": "must",
+      "statement": "Provide one visible Field label for the complete Slider or a complete accessible name for every standalone Thumb."
+    },
+    {
+      "id": "slider-visible-output",
+      "level": "should",
+      "statement": "Use an external application-owned output when dense ranges or long localized values would collide with a thumb ValueLabel."
+    },
+    {
+      "id": "slider-change-commit",
+      "level": "must",
+      "statement": "Use onValueChange for live updates and onValueCommit for completed interactions; true pointer cancellation restores the pointer-down value without commit while lost capture commits the latest value."
+    },
+    {
+      "id": "slider-input-direction",
+      "level": "must",
+      "statement": "Preserve one active pointer session, non-slider-axis page scrolling, orientation-aware keys, and horizontal LTR and RTL pointer and Arrow behavior."
+    },
+    {
+      "id": "slider-track-inset",
+      "level": "should",
+      "statement": "Keep the default Track inset when a parent clips overflow; set the public Track-inset token to zero only when the surrounding composition preserves complete endpoint target and focus paint."
+    },
+    {
+      "id": "slider-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus slider.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Rendering a range with one Thumb, treating decorative markers as labels, or using Slider for a discrete named choice without explaining the values.",
+      "correction": "Match Thumbs to values, label the actual control, and choose Select or RadioGroup when names carry the meaning."
+    }
+  ],
+  "validation": [
+    "Check pointer, touch, keyboard, large steps, range bounds, controlled values, reset, disabled, read-only, invalid, and form submission.",
+    "Check horizontal and vertical orientation, RTL, narrow containment, complete 44px endpoint targets, any customized Track inset, zoom, reduced motion, forced colors, and label readability."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "slider",
+      "versionPolicy": "installed-exact"
+    },
+    "field",
+    "number-input",
+    "select",
+    "progress",
+    "rating",
+    "form"
+  ]
+}
+```

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

@@ -0,0 +1,155 @@
+# Stack
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: stack
+
+# Stack agent guide
+
+## Purpose
+
+Arrange children on one primary axis with responsive direction, tokenized spacing, alignment, wrapping, and explicit child sizing.
+
+## Use when
+
+- Content needs one-dimensional vertical or horizontal layout.
+
+## Choose something else when
+
+- Both rows and columns need explicit track control. Use Grid.
+- Content overlaps in depth. Use ZStack or Surface media anatomy.
+
+## Required composition
+
+- Choose VStack when the axis is always vertical, HStack when it is always horizontal, and Stack when the same content changes axis at a breakpoint.
+- Use as="ul" or as="ol" when the one-dimensional peers form a semantic list; Stack removes native list geometry while preserving the relationship.
+- Use Stack.Item when one direct child must remain content-sized, fixed, or consume a proportional share.
+- When the parent changes axis, review each Item flex recipe too; a proportional desktop column usually becomes content-sized in a mobile column.
+- Keep the Item wrapper when equal outer tracks contain children with different padding or borders; use asChild only when the child's own box should participate in flex allocation.
+- When Stack.Item composes a control with asChild, rely on the control's own size recipe; Stack preserves its declared minimum block size while adding flex participation.
+
+## Rules
+
+- **MUST:** Use Stack for one primary layout axis and allow wrapping only when the resulting order remains clear.
+- **MUST:** Use non-negative numeric spacing factors for ordinary gap and logical edge spacing; use an explicit CSS value only for a measured exception or application spacing token, and preserve legacy string tokens when maintaining existing geometry.
+- **MUST:** Use a semantic list host when Stack children form a real set; do not add consumer CSS to cancel native ul or ol margins or markers because Stack owns that host geometry.
+- **MUST:** Use responsive Stack values for arrangement changes; use Show/Hide only when the actual interface changes.
+- **MUST:** Preserve reading and focus order; do not simulate reverse direction or visual ordering.
+- **MUST:** Load styles.css or core.css plus stack.css.
+
+## Common mistakes
+
+- **Avoid:** Duplicating the same content through Show/Hide only to switch row and column. **Instead:** Use responsive Stack direction.
+- **Avoid:** Writing grow/shrink CSS for ordinary columns. **Instead:** Use Stack.Item flex recipes.
+- **Avoid:** Adding a local class only because the desired gap is outside the legacy zero-through-six token scale. **Instead:** Use a numeric factor such as gap={8}, an explicit CSS length, or an application custom property through the supported spacing prop.
+
+## Validation checklist
+
+- Check source and visual order at narrow widths and zoom.
+- Confirm numeric, explicit, and responsive spacing values create the intended computed geometry; reject negative, non-finite, and empty values.
+- For ul and ol hosts, confirm zero native margin, no visual marker, and preserved list semantics.
+- Check every authored breakpoint, logical edge spacing, wrapping, alignment, and RTL behavior.
+
+## Related guidance
+
+- `grid`
+- `z-stack`
+- `show`
+- `hide`
+- `surface`
+- `card`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "stack",
+  "name": "Stack",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Arrange children on one primary axis with responsive direction, tokenized spacing, alignment, wrapping, and explicit child sizing.",
+  "useWhen": [
+    "Content needs one-dimensional vertical or horizontal layout."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Both rows and columns need explicit track control.",
+      "useInstead": "Grid"
+    },
+    {
+      "condition": "Content overlaps in depth.",
+      "useInstead": "ZStack or Surface media anatomy"
+    }
+  ],
+  "composition": [
+    "Choose VStack when the axis is always vertical, HStack when it is always horizontal, and Stack when the same content changes axis at a breakpoint.",
+    "Use as=\"ul\" or as=\"ol\" when the one-dimensional peers form a semantic list; Stack removes native list geometry while preserving the relationship.",
+    "Use Stack.Item when one direct child must remain content-sized, fixed, or consume a proportional share.",
+    "When the parent changes axis, review each Item flex recipe too; a proportional desktop column usually becomes content-sized in a mobile column.",
+    "Keep the Item wrapper when equal outer tracks contain children with different padding or borders; use asChild only when the child's own box should participate in flex allocation.",
+    "When Stack.Item composes a control with asChild, rely on the control's own size recipe; Stack preserves its declared minimum block size while adding flex participation."
+  ],
+  "rules": [
+    {
+      "id": "stack-one-dimension",
+      "level": "must",
+      "statement": "Use Stack for one primary layout axis and allow wrapping only when the resulting order remains clear."
+    },
+    {
+      "id": "stack-gap-scale",
+      "level": "must",
+      "statement": "Use non-negative numeric spacing factors for ordinary gap and logical edge spacing; use an explicit CSS value only for a measured exception or application spacing token, and preserve legacy string tokens when maintaining existing geometry."
+    },
+    {
+      "id": "stack-semantic-list",
+      "level": "must",
+      "statement": "Use a semantic list host when Stack children form a real set; do not add consumer CSS to cancel native ul or ol margins or markers because Stack owns that host geometry."
+    },
+    {
+      "id": "stack-responsive-arrangement",
+      "level": "must",
+      "statement": "Use responsive Stack values for arrangement changes; use Show/Hide only when the actual interface changes."
+    },
+    {
+      "id": "stack-source-order",
+      "level": "must",
+      "statement": "Preserve reading and focus order; do not simulate reverse direction or visual ordering."
+    },
+    {
+      "id": "stack-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus stack.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Duplicating the same content through Show/Hide only to switch row and column.",
+      "correction": "Use responsive Stack direction."
+    },
+    {
+      "mistake": "Writing grow/shrink CSS for ordinary columns.",
+      "correction": "Use Stack.Item flex recipes."
+    },
+    {
+      "mistake": "Adding a local class only because the desired gap is outside the legacy zero-through-six token scale.",
+      "correction": "Use a numeric factor such as gap={8}, an explicit CSS length, or an application custom property through the supported spacing prop."
+    }
+  ],
+  "validation": [
+    "Check source and visual order at narrow widths and zoom.",
+    "Confirm numeric, explicit, and responsive spacing values create the intended computed geometry; reject negative, non-finite, and empty values.",
+    "For ul and ol hosts, confirm zero native margin, no visual marker, and preserved list semantics.",
+    "Check every authored breakpoint, logical edge spacing, wrapping, alignment, and RTL behavior."
+  ],
+  "related": [
+    "grid",
+    "z-stack",
+    "show",
+    "hide",
+    "surface",
+    "card"
+  ]
+}
+```

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

@@ -0,0 +1,110 @@
+# Status
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: status
+
+# Status agent guide
+
+## Purpose
+
+Present a compact passive state with a semantic indicator and readable label, or a decorative indicator beside text that already carries the state.
+
+## Use when
+
+- A process, entity, availability, health, or review state needs a dot-plus-label presentation.
+
+## Choose something else when
+
+- The content is a category, accolade, count, progress value, consequential message, or avatar-only presence ring. Use Badge, NotificationBadge, Progress, Alert, or Avatar status.
+
+## Required composition
+
+- Compose Root with one decorative Indicator and one visible Label by default. Omit Label only when adjacent visible or visually hidden text already carries the complete state and the indicator-only Root is aria-hidden.
+
+## Rules
+
+- **MUST:** Always provide state text. Render it through Label by default; indicator-only composition is allowed only when adjacent visible or visually hidden text already carries the complete meaning and the Root is decorative.
+- **MUST:** Choose success, warning, danger, info, accent, or neutral from the state meaning, not from decorative preference.
+- **MUST:** Do not assume Status announces changes; author role=status or live-region attributes only when the application owns and validates that announcement policy.
+- **MUST:** Load styles.css or core.css plus status.css.
+
+## Common mistakes
+
+- **Avoid:** Using success for a Call button, warning for a gold accolade, or Badge merely to draw a status dot. **Instead:** Use action hierarchy for operations, accent/neutral Badge for accolades, and Status for actual dot-plus-label state.
+
+## Validation checklist
+
+- Check visible state text, semantic tone, decorative indicator, primary label color, light/dark, forced colors, zoom, RTL, and deliberate live-region ownership.
+
+## Related guidance
+
+- `badge`
+- `notification-badge`
+- `avatar`
+- `progress`
+- `toast`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "status",
+  "name": "Status",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a compact passive state with a semantic indicator and readable label, or a decorative indicator beside text that already carries the state.",
+  "useWhen": [
+    "A process, entity, availability, health, or review state needs a dot-plus-label presentation."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content is a category, accolade, count, progress value, consequential message, or avatar-only presence ring.",
+      "useInstead": "Badge, NotificationBadge, Progress, Alert, or Avatar status"
+    }
+  ],
+  "composition": [
+    "Compose Root with one decorative Indicator and one visible Label by default. Omit Label only when adjacent visible or visually hidden text already carries the complete state and the indicator-only Root is aria-hidden."
+  ],
+  "rules": [
+    {
+      "id": "status-visible-label",
+      "level": "must",
+      "statement": "Always provide state text. Render it through Label by default; indicator-only composition is allowed only when adjacent visible or visually hidden text already carries the complete meaning and the Root is decorative."
+    },
+    {
+      "id": "status-semantic-tone",
+      "level": "must",
+      "statement": "Choose success, warning, danger, info, accent, or neutral from the state meaning, not from decorative preference."
+    },
+    {
+      "id": "status-live-region",
+      "level": "must",
+      "statement": "Do not assume Status announces changes; author role=status or live-region attributes only when the application owns and validates that announcement policy."
+    },
+    {
+      "id": "status-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus status.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using success for a Call button, warning for a gold accolade, or Badge merely to draw a status dot.",
+      "correction": "Use action hierarchy for operations, accent/neutral Badge for accolades, and Status for actual dot-plus-label state."
+    }
+  ],
+  "validation": [
+    "Check visible state text, semantic tone, decorative indicator, primary label color, light/dark, forced colors, zoom, RTL, and deliberate live-region ownership."
+  ],
+  "related": [
+    "badge",
+    "notification-badge",
+    "avatar",
+    "progress",
+    "toast"
+  ]
+}
+```