@flowstack-ui/brick 0.1.9 → 0.1.12

package/dist/agents/slider.json

@@ -0,0 +1,88 @@
+{
+  "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/dist/agents/slider.md

@@ -0,0 +1,48 @@
+# 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`

package/dist/agents/stack.json

@@ -21,9 +21,11 @@
   ],
   "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."
+    "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": [
     {
@@ -31,6 +33,16 @@
       "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",
@@ -55,10 +67,16 @@
     {
       "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": [

package/dist/agents/stack.md

@@ -16,13 +16,17 @@ Arrange children on one primary axis with responsive direction, tokenized spacin
 ## 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.
@@ -31,10 +35,13 @@ Arrange children on one primary axis with responsive direction, tokenized spacin
 
 - **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

package/dist/agents/status.json

@@ -0,0 +1,59 @@
+{
+  "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"
+  ]
+}

package/dist/agents/status.md

@@ -0,0 +1,40 @@
+# 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`

package/dist/agents/surface.json

@@ -5,7 +5,7 @@
   "package": "@flowstack-ui/brick",
   "layer": "brick",
   "kind": "component",
-  "purpose": "Apply semantic background layers, boundaries, elevation, radius, inset, and optional decorative media layering without implying a specific content object.",
+  "purpose": "Apply semantic background tones and layers, boundaries, elevation, radius, inset, and optional decorative media layering without implying a specific content object.",
   "useWhen": [
     "A region needs a semantic visual plane but Card, Dialog, or another purposeful component would add the wrong anatomy.",
     "Decorative image, video, canvas, or authored artwork needs to sit behind foreground content with an optional contrast scrim."
@@ -17,7 +17,7 @@
     }
   ],
   "composition": [
-    "Choose Surface level and boundary by hierarchy, then compose public layout and content components inside. Use asChild around Section when paint must cover the Section rhythm without another host. For background media, author Media, optional Scrim, and Content in that order. When layered foreground content needs four-sided breathing room, set inset on the Surface root; Content owns foreground layering, not padding."
+    "Choose Surface level and boundary by hierarchy, then compose public layout and content components inside. Use asChild around Section when paint must cover the Section rhythm without another host. For background media, author Media, optional Scrim, and Content in that order. When layered foreground content needs four-sided breathing room, set inset on the Surface root; Content owns foreground layering, not padding. Use xl and 2xl for page-sized panels or heroes, and the responsive value shape when that inset should grow with the viewport."
   ],
   "rules": [
     {
@@ -25,6 +25,11 @@
       "level": "should",
       "statement": "Choose surface level by information hierarchy, not decoration alone."
     },
+    {
+      "id": "surface-accent-tone",
+      "level": "should",
+      "statement": "Use accent tone only for a branded or conversion plane, never as a generic status surface."
+    },
     {
       "id": "surface-as-child",
       "level": "must",
@@ -40,6 +45,21 @@
       "level": "must",
       "statement": "Use the Surface inset recipe for four-sided internal spacing; Surface.Content provides z-order only, and Stack startSpacing/endSpacing remain axis-specific."
     },
+    {
+      "id": "surface-inset-scale",
+      "level": "should",
+      "statement": "Use sm through lg for local panels and reserve xl or 2xl for page-sized panels, heroes, and split layouts."
+    },
+    {
+      "id": "surface-responsive-inset",
+      "level": "must",
+      "statement": "Write responsive inset mobile first with a required initial value and only the breakpoint overrides that change; omit a scalar inset none because none is already the default."
+    },
+    {
+      "id": "surface-inset-measure",
+      "level": "must",
+      "statement": "Change a centered child's Frame or Container measure when the visible issue is line length or available width; Surface inset moves every child edge and does not replace content measure."
+    },
     {
       "id": "surface-media-decoration",
       "level": "must",
@@ -78,13 +98,22 @@
     {
       "mistake": "Expecting Surface.Content or Stack edge spacing to create padding on every foreground edge.",
       "correction": "Set inset on the Surface root, then use Stack only for child arrangement and primary-axis spacing."
+    },
+    {
+      "mistake": "Repeating page-panel padding in Block CSS.",
+      "correction": "Use a larger or responsive Surface inset; use the public padding token only for one deliberate asymmetric relationship that the closed recipe cannot express."
+    },
+    {
+      "mistake": "Increasing inset to make a narrow centered child look wider.",
+      "correction": "Adjust the child's Frame or Container measure independently."
     }
   ],
   "validation": [
     "Check foreground contrast against the selected surface in every appearance.",
     "Confirm nested surfaces communicate hierarchy without excessive borders or elevation.",
     "Confirm Media and Scrim fill the root, remain hidden from assistive technology and pointer input, and Content stays above both.",
-    "Check that layered foreground content has intentional spacing on all four logical edges at narrow and wide sizes."
+    "Check that layered foreground content has intentional spacing on all four logical edges at narrow and wide sizes.",
+    "Check that responsive inset changes at the intended shared breakpoint while media and scrim remain edge-to-edge."
   ],
   "related": [
     "card",

package/dist/agents/surface.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Apply semantic background layers, boundaries, elevation, radius, inset, and optional decorative media layering without implying a specific content object.
+Apply semantic background tones and layers, boundaries, elevation, radius, inset, and optional decorative media layering without implying a specific content object.
 
 ## Use when
 
@@ -15,14 +15,18 @@ Apply semantic background layers, boundaries, elevation, radius, inset, and opti
 
 ## Required composition
 
-- Choose Surface level and boundary by hierarchy, then compose public layout and content components inside. Use asChild around Section when paint must cover the Section rhythm without another host. For background media, author Media, optional Scrim, and Content in that order. When layered foreground content needs four-sided breathing room, set inset on the Surface root; Content owns foreground layering, not padding.
+- Choose Surface level and boundary by hierarchy, then compose public layout and content components inside. Use asChild around Section when paint must cover the Section rhythm without another host. For background media, author Media, optional Scrim, and Content in that order. When layered foreground content needs four-sided breathing room, set inset on the Surface root; Content owns foreground layering, not padding. Use xl and 2xl for page-sized panels or heroes, and the responsive value shape when that inset should grow with the viewport.
 
 ## Rules
 
 - **SHOULD:** Choose surface level by information hierarchy, not decoration alone.
+- **SHOULD:** Use accent tone only for a branded or conversion plane, never as a generic status surface.
 - **MUST:** Use asChild only with one existing non-Fragment host that already owns the required semantics or layout; preserve that child's meaning and keep Surface responsible only for paint.
 - **MUST:** Load styles.css or core.css plus surface.css.
 - **MUST:** Use the Surface inset recipe for four-sided internal spacing; Surface.Content provides z-order only, and Stack startSpacing/endSpacing remain axis-specific.
+- **SHOULD:** Use sm through lg for local panels and reserve xl or 2xl for page-sized panels, heroes, and split layouts.
+- **MUST:** Write responsive inset mobile first with a required initial value and only the breakpoint overrides that change; omit a scalar inset none because none is already the default.
+- **MUST:** Change a centered child's Frame or Container measure when the visible issue is line length or available width; Surface inset moves every child edge and does not replace content measure.
 - **MUST:** Treat Surface.Media as decorative and noninteractive; keep meaningful media and controls in Content or ordinary document flow.
 - **MUST:** Give Brick Image explicit fill inside Surface.Media so its actual Content and Fallback consume the complete media layer.
 - **MUST:** Put every foreground child inside Surface.Content when Media or Scrim is used.
@@ -34,6 +38,8 @@ Apply semantic background layers, boundaries, elevation, radius, inset, and opti
 - **Avoid:** Using arbitrary background colors to recreate a surface. **Instead:** Use Surface and theme its semantic tokens.
 - **Avoid:** Adding absolute-positioning and z-index CSS for ordinary background media. **Instead:** Use Surface.Media, Surface.Scrim, and Surface.Content.
 - **Avoid:** Expecting Surface.Content or Stack edge spacing to create padding on every foreground edge. **Instead:** Set inset on the Surface root, then use Stack only for child arrangement and primary-axis spacing.
+- **Avoid:** Repeating page-panel padding in Block CSS. **Instead:** Use a larger or responsive Surface inset; use the public padding token only for one deliberate asymmetric relationship that the closed recipe cannot express.
+- **Avoid:** Increasing inset to make a narrow centered child look wider. **Instead:** Adjust the child's Frame or Container measure independently.
 
 ## Validation checklist
 
@@ -41,6 +47,7 @@ Apply semantic background layers, boundaries, elevation, radius, inset, and opti
 - Confirm nested surfaces communicate hierarchy without excessive borders or elevation.
 - Confirm Media and Scrim fill the root, remain hidden from assistive technology and pointer input, and Content stays above both.
 - Check that layered foreground content has intentional spacing on all four logical edges at narrow and wide sizes.
+- Check that responsive inset changes at the intended shared breakpoint while media and scrim remain edge-to-edge.
 
 ## Related guidance
 

package/dist/agents/swipeable-item.json

@@ -0,0 +1,93 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "swipeable-item",
+  "name": "SwipeableItem",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Enhance a finished list-like row with logical start or end quick-action panels revealed by horizontal drag or keyboard while Atom owns state, measurement, gesture intent, scrolling preservation, and keyboard behavior.",
+  "useWhen": [
+    "A row has one or two frequent commands that benefit from touch reveal and every important command also remains available through an obvious tap or click route."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "There are many commands, discovery is critical, the row navigates or selects, or swipe would be surprising or the only pointer path.",
+      "useInstead": "DropdownMenu, visible Button or IconButton controls, Link, or the appropriate selection component"
+    }
+  ],
+  "composition": [
+    "Compose Root with one focusable Content surface and a labelled Actions group for each supported logical start or end side. Put real named Button or Link controls inside Actions and keep an obvious non-swipe route, normally a visible overflow trigger, inside Content.",
+    "Choose plain inside an existing row boundary or outline for a standalone boundary. Preserve surrounding List or Feed semantics and keep confirmation, undo, persistence, and coordination between rows in the application."
+  ],
+  "rules": [
+    {
+      "id": "swipeable-enhancement",
+      "level": "must",
+      "statement": "Treat swipe and keyboard reveal as enhancements; neither replaces the required obvious tap or click route to every important action."
+    },
+    {
+      "id": "swipeable-actions",
+      "level": "must",
+      "statement": "Give every Actions panel a localized accessible group name and every child complete native semantics; keep closed panels inert and accessibility-hidden."
+    },
+    {
+      "id": "swipeable-scroll-gesture",
+      "level": "must",
+      "statement": "Preserve pan-y vertical scrolling, horizontal intent detection, pointer capture, cancellation rollback, measured logical-side widths, threshold settlement, and one owned pointer interaction."
+    },
+    {
+      "id": "swipeable-keyboard",
+      "level": "must",
+      "statement": "Keep Content focusable and preserve direction-aware Arrow reveal, opposite-Arrow close, and Escape close only when Content owns the key; nested controls retain their own keyboard behavior."
+    },
+    {
+      "id": "swipeable-no-full-swipe",
+      "level": "must",
+      "statement": "Do not implement gesture execution around Brick SwipeableItem: Brick intentionally omits Atom's onFullSwipe and fullSwipeThreshold props so destructive or consequential commands require an explicit control."
+    },
+    {
+      "id": "swipeable-state",
+      "level": "must",
+      "statement": "Use openSide with onOpenSideChange or defaultOpenSide, preserve disabled versus focusable read-only behavior, and treat start and end as logical sides that follow LTR and RTL."
+    },
+    {
+      "id": "swipeable-responsive",
+      "level": "must",
+      "statement": "Keep authored Content wrapping, visible alternatives reachable, actions measured, and the shared clipped radius intact at narrow widths, zoom, RTL, forced colors, and reduced motion."
+    },
+    {
+      "id": "swipeable-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus swipeable-item.css and the CSS for every composed action or row component."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Making swipe the only route to Delete, blocking vertical scroll, firing a destructive threshold gesture, or letting Arrow keys from nested controls reveal actions.",
+      "correction": "Provide an obvious explicit control, preserve pan-y and gesture intent, use Brick's no-full-swipe API, and retain keyboard target isolation."
+    },
+    {
+      "mistake": "Using SwipeableItem as List, Feed, navigation, selection, confirmation, or multi-row coordination ownership.",
+      "correction": "Keep semantic row ownership and application effects outside the three-part enhancement boundary."
+    }
+  ],
+  "validation": [
+    "Verify controlled/uncontrolled start/end/null state, LTR and RTL mapping, measured widths and offsets, pointer down/move/up settlement, threshold boundaries, cancellation, capture, vertical pan, disabled/read-only state, and action closeOnClick.",
+    "Verify Content focus, Arrow reveal/close, Escape, descendant keyboard isolation, inert hidden panels, group and control names, obvious pointer fallback, absence of full-swipe execution, native props, refs, and real-browser mouse/touch scrolling.",
+    "Verify plain and outline boundaries, long content, narrow widths, zoom, RTL, shared radii, focus, light/dark appearance, forced colors, reduced motion, and surrounding List or Feed semantics."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "swipeable-item",
+      "versionPolicy": "installed-exact"
+    },
+    "dropdown-menu",
+    "button",
+    "icon-button",
+    "link",
+    "list",
+    "feed"
+  ]
+}

package/dist/agents/swipeable-item.md

@@ -0,0 +1,50 @@
+# SwipeableItem agent guide
+
+## Purpose
+
+Enhance a finished list-like row with logical start or end quick-action panels revealed by horizontal drag or keyboard while Atom owns state, measurement, gesture intent, scrolling preservation, and keyboard behavior.
+
+## Use when
+
+- A row has one or two frequent commands that benefit from touch reveal and every important command also remains available through an obvious tap or click route.
+
+## Choose something else when
+
+- There are many commands, discovery is critical, the row navigates or selects, or swipe would be surprising or the only pointer path. Use DropdownMenu, visible Button or IconButton controls, Link, or the appropriate selection component.
+
+## Required composition
+
+- Compose Root with one focusable Content surface and a labelled Actions group for each supported logical start or end side. Put real named Button or Link controls inside Actions and keep an obvious non-swipe route, normally a visible overflow trigger, inside Content.
+- Choose plain inside an existing row boundary or outline for a standalone boundary. Preserve surrounding List or Feed semantics and keep confirmation, undo, persistence, and coordination between rows in the application.
+
+## Rules
+
+- **MUST:** Treat swipe and keyboard reveal as enhancements; neither replaces the required obvious tap or click route to every important action.
+- **MUST:** Give every Actions panel a localized accessible group name and every child complete native semantics; keep closed panels inert and accessibility-hidden.
+- **MUST:** Preserve pan-y vertical scrolling, horizontal intent detection, pointer capture, cancellation rollback, measured logical-side widths, threshold settlement, and one owned pointer interaction.
+- **MUST:** Keep Content focusable and preserve direction-aware Arrow reveal, opposite-Arrow close, and Escape close only when Content owns the key; nested controls retain their own keyboard behavior.
+- **MUST:** Do not implement gesture execution around Brick SwipeableItem: Brick intentionally omits Atom's onFullSwipe and fullSwipeThreshold props so destructive or consequential commands require an explicit control.
+- **MUST:** Use openSide with onOpenSideChange or defaultOpenSide, preserve disabled versus focusable read-only behavior, and treat start and end as logical sides that follow LTR and RTL.
+- **MUST:** Keep authored Content wrapping, visible alternatives reachable, actions measured, and the shared clipped radius intact at narrow widths, zoom, RTL, forced colors, and reduced motion.
+- **MUST:** Load styles.css or core.css plus swipeable-item.css and the CSS for every composed action or row component.
+
+## Common mistakes
+
+- **Avoid:** Making swipe the only route to Delete, blocking vertical scroll, firing a destructive threshold gesture, or letting Arrow keys from nested controls reveal actions. **Instead:** Provide an obvious explicit control, preserve pan-y and gesture intent, use Brick's no-full-swipe API, and retain keyboard target isolation.
+- **Avoid:** Using SwipeableItem as List, Feed, navigation, selection, confirmation, or multi-row coordination ownership. **Instead:** Keep semantic row ownership and application effects outside the three-part enhancement boundary.
+
+## Validation checklist
+
+- Verify controlled/uncontrolled start/end/null state, LTR and RTL mapping, measured widths and offsets, pointer down/move/up settlement, threshold boundaries, cancellation, capture, vertical pan, disabled/read-only state, and action closeOnClick.
+- Verify Content focus, Arrow reveal/close, Escape, descendant keyboard isolation, inert hidden panels, group and control names, obvious pointer fallback, absence of full-swipe execution, native props, refs, and real-browser mouse/touch scrolling.
+- Verify plain and outline boundaries, long content, narrow widths, zoom, RTL, shared radii, focus, light/dark appearance, forced colors, reduced motion, and surrounding List or Feed semantics.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/swipeable-item`
+- `dropdown-menu`
+- `button`
+- `icon-button`
+- `link`
+- `list`
+- `feed`