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

package/public/packages/atom/0.24.0/components/scroll-area.txt

@@ -0,0 +1,96 @@
+# ScrollArea
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: scroll-area
+
+# ScrollArea agent guide
+
+## Purpose
+
+Provide an owned scroll viewport and synchronized scrollbar anatomy without replacing native document scrolling.
+
+## Use when
+
+- A bounded region needs explicit scroll viewport and scrollbar behavior or stable compound scrollbar anatomy.
+
+## Choose something else when
+
+- The page or ordinary content region can use native overflow and browser scrollbars. Use native document or overflow scrolling.
+
+## Required composition
+
+- Compose Viewport and the required Scrollbar/Thumb parts inside Root, adding Corner when both axes are present.
+
+## Rules
+
+- **MUST:** Preserve wheel, touch, keyboard, and assistive-technology scrolling without hijacking page input.
+- **SHOULD:** Make the viewport focusable and named only when keyboard access to an otherwise unreachable scrolling region requires it.
+
+## Common mistakes
+
+- **Avoid:** Wrapping every overflow region in ScrollArea or removing visible focus to hide a focusable viewport. **Instead:** Use native overflow by default and add ScrollArea only for its owned behavior.
+
+## Validation checklist
+
+- Test mouse, trackpad, touch, keyboard, zoom, nested scrolling, both axes, and RTL.
+- Confirm focusability and accessible naming are intentional.
+
+## Related guidance
+
+- `table`
+- `data-grid`
+- `sidebar`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "scroll-area",
+  "name": "ScrollArea",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide an owned scroll viewport and synchronized scrollbar anatomy without replacing native document scrolling.",
+  "useWhen": [
+    "A bounded region needs explicit scroll viewport and scrollbar behavior or stable compound scrollbar anatomy."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The page or ordinary content region can use native overflow and browser scrollbars.",
+      "useInstead": "native document or overflow scrolling"
+    }
+  ],
+  "composition": [
+    "Compose Viewport and the required Scrollbar/Thumb parts inside Root, adding Corner when both axes are present."
+  ],
+  "rules": [
+    {
+      "id": "scroll-area-native-input",
+      "level": "must",
+      "statement": "Preserve wheel, touch, keyboard, and assistive-technology scrolling without hijacking page input."
+    },
+    {
+      "id": "scroll-area-focus",
+      "level": "should",
+      "statement": "Make the viewport focusable and named only when keyboard access to an otherwise unreachable scrolling region requires it."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Wrapping every overflow region in ScrollArea or removing visible focus to hide a focusable viewport.",
+      "correction": "Use native overflow by default and add ScrollArea only for its owned behavior."
+    }
+  ],
+  "validation": [
+    "Test mouse, trackpad, touch, keyboard, zoom, nested scrolling, both axes, and RTL.",
+    "Confirm focusability and accessible naming are intentional."
+  ],
+  "related": [
+    "table",
+    "data-grid",
+    "sidebar"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/select.txt

@@ -0,0 +1,126 @@
+# Select
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: select
+
+# Select agent guide
+
+## Purpose
+
+Choose one value from a compact trigger-owned popup listbox with typeahead, active-descendant focus, positioning, dismissal, Field integration, and native select form behavior.
+
+## Use when
+
+- A user chooses one value from a predefined list whose options should stay collapsed until the control opens.
+
+## Choose something else when
+
+- A short list should remain visible, several values may be chosen, or users need editable filtering or free-form entry. Use RadioGroup or Listbox, MultiSelect, or Combobox.
+
+## Required composition
+
+- Compose Root with an accessible Trigger containing optional Value and Icon, then one Content or Listbox popup. Add Portal only when needed; place Items with stable values and ItemText inside optional Viewport, Group with Label, separators, scroll buttons, indicators, and a direct popup Arrow as required.
+
+## Rules
+
+- **MUST:** Give Trigger an accessible name through native ARIA or Field labeling and preserve its combobox, expanded, controls, active-descendant, required, read-only, invalid, and disabled relationships.
+- **MUST:** Use Select only for one predefined value and route controlled value and open state through their matching callbacks.
+- **MUST:** Give every Item a stable unique value and ItemText or label so Trigger Value display, option naming, typeahead, and the hidden native select work even before the popup mounts.
+- **MUST:** Preserve Trigger-owned Arrow, Home/End, printable typeahead, Enter/Space selection, Tab, Escape stack, disabled skipping, highlight, focus restoration, and completed outside-interaction behavior.
+- **MUST:** Preserve the hidden native select's name, form, options, selected value, disabled state, required validity, reset, and validation-focus redirection to Trigger.
+- **MUST:** Use either Content or Listbox once, keep Arrow inside it, and keep scroll buttons outside the registered Viewport so Atom can own positioning and overflow state.
+
+## Common mistakes
+
+- **Avoid:** Using Select for multiple or editable choice, omitting ItemText from complex options, rendering both Content and Listbox, or rebuilding keyboard and form behavior around a styled button. **Instead:** Choose the correct selection model and preserve Select's single popup, registered option text, Trigger ownership, and native form mirror.
+
+## Validation checklist
+
+- Verify Trigger naming and Field relationships, controlled/uncontrolled value and open state, placeholder and closed selected label, pointer/touch opening, Arrow and printable-key opening, active descendant, Home/End, typeahead, selection, disabled items, Tab, Escape, outside activation, and focus return.
+- Verify native select options and submission, required inline/native validity, external form association, disabled/read-only/invalid state, reset, groups and labels, Viewport and scroll buttons, portal and non-portal paths, Arrow placement, direction, collision handling, and nested-modal ownership.
+
+## Related guidance
+
+- `listbox`
+- `multi-select`
+- `combobox`
+- `radio-group`
+- `field`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "select",
+  "name": "Select",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Choose one value from a compact trigger-owned popup listbox with typeahead, active-descendant focus, positioning, dismissal, Field integration, and native select form behavior.",
+  "useWhen": [
+    "A user chooses one value from a predefined list whose options should stay collapsed until the control opens."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A short list should remain visible, several values may be chosen, or users need editable filtering or free-form entry.",
+      "useInstead": "RadioGroup or Listbox, MultiSelect, or Combobox"
+    }
+  ],
+  "composition": [
+    "Compose Root with an accessible Trigger containing optional Value and Icon, then one Content or Listbox popup. Add Portal only when needed; place Items with stable values and ItemText inside optional Viewport, Group with Label, separators, scroll buttons, indicators, and a direct popup Arrow as required."
+  ],
+  "rules": [
+    {
+      "id": "select-trigger-name",
+      "level": "must",
+      "statement": "Give Trigger an accessible name through native ARIA or Field labeling and preserve its combobox, expanded, controls, active-descendant, required, read-only, invalid, and disabled relationships."
+    },
+    {
+      "id": "select-single-value",
+      "level": "must",
+      "statement": "Use Select only for one predefined value and route controlled value and open state through their matching callbacks."
+    },
+    {
+      "id": "select-item-text",
+      "level": "must",
+      "statement": "Give every Item a stable unique value and ItemText or label so Trigger Value display, option naming, typeahead, and the hidden native select work even before the popup mounts."
+    },
+    {
+      "id": "select-owned-keyboard",
+      "level": "must",
+      "statement": "Preserve Trigger-owned Arrow, Home/End, printable typeahead, Enter/Space selection, Tab, Escape stack, disabled skipping, highlight, focus restoration, and completed outside-interaction behavior."
+    },
+    {
+      "id": "select-form",
+      "level": "must",
+      "statement": "Preserve the hidden native select's name, form, options, selected value, disabled state, required validity, reset, and validation-focus redirection to Trigger."
+    },
+    {
+      "id": "select-popup-anatomy",
+      "level": "must",
+      "statement": "Use either Content or Listbox once, keep Arrow inside it, and keep scroll buttons outside the registered Viewport so Atom can own positioning and overflow state."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Select for multiple or editable choice, omitting ItemText from complex options, rendering both Content and Listbox, or rebuilding keyboard and form behavior around a styled button.",
+      "correction": "Choose the correct selection model and preserve Select's single popup, registered option text, Trigger ownership, and native form mirror."
+    }
+  ],
+  "validation": [
+    "Verify Trigger naming and Field relationships, controlled/uncontrolled value and open state, placeholder and closed selected label, pointer/touch opening, Arrow and printable-key opening, active descendant, Home/End, typeahead, selection, disabled items, Tab, Escape, outside activation, and focus return.",
+    "Verify native select options and submission, required inline/native validity, external form association, disabled/read-only/invalid state, reset, groups and labels, Viewport and scroll buttons, portal and non-portal paths, Arrow placement, direction, collision handling, and nested-modal ownership."
+  ],
+  "related": [
+    "listbox",
+    "multi-select",
+    "combobox",
+    "radio-group",
+    "field",
+    "form"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/sidebar.txt

@@ -0,0 +1,96 @@
+# Sidebar
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: sidebar
+
+# Sidebar agent guide
+
+## Purpose
+
+Coordinate expanded, rail, and offcanvas sidebar state across a trigger, complementary panel, and associated main region.
+
+## Use when
+
+- An application shell has a persistent side region that can collapse to a rail or leave the layout offcanvas.
+
+## Choose something else when
+
+- The side panel is a temporary modal overlay or ordinary static aside. Use Drawer or a native aside.
+
+## Required composition
+
+- Compose Trigger, Panel, and Main inside Root; place persistent navigation such as NavList inside Panel.
+
+## Rules
+
+- **MUST:** Use Sidebar.Main only when it is the page's single main landmark, or custom-render it without creating duplicate main landmarks.
+- **MUST:** Keep offcanvas Panel content inert and outside the accessibility tree through the primitive contract.
+
+## Common mistakes
+
+- **Avoid:** Using Sidebar as a modal drawer or placing another main landmark inside Sidebar.Main. **Instead:** Use Drawer for modal panels and preserve one main landmark.
+
+## Validation checklist
+
+- Test controlled and uncontrolled expanded, rail, and offcanvas states and trigger announcements.
+- Confirm offcanvas controls cannot receive focus and landmark names are unique.
+
+## Related guidance
+
+- `nav-list`
+- `drawer`
+- `app-bar`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "sidebar",
+  "name": "Sidebar",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Coordinate expanded, rail, and offcanvas sidebar state across a trigger, complementary panel, and associated main region.",
+  "useWhen": [
+    "An application shell has a persistent side region that can collapse to a rail or leave the layout offcanvas."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The side panel is a temporary modal overlay or ordinary static aside.",
+      "useInstead": "Drawer or a native aside"
+    }
+  ],
+  "composition": [
+    "Compose Trigger, Panel, and Main inside Root; place persistent navigation such as NavList inside Panel."
+  ],
+  "rules": [
+    {
+      "id": "sidebar-one-main",
+      "level": "must",
+      "statement": "Use Sidebar.Main only when it is the page's single main landmark, or custom-render it without creating duplicate main landmarks."
+    },
+    {
+      "id": "sidebar-offcanvas-inert",
+      "level": "must",
+      "statement": "Keep offcanvas Panel content inert and outside the accessibility tree through the primitive contract."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Sidebar as a modal drawer or placing another main landmark inside Sidebar.Main.",
+      "correction": "Use Drawer for modal panels and preserve one main landmark."
+    }
+  ],
+  "validation": [
+    "Test controlled and uncontrolled expanded, rail, and offcanvas states and trigger announcements.",
+    "Confirm offcanvas controls cannot receive focus and landmark names are unique."
+  ],
+  "related": [
+    "nav-list",
+    "drawer",
+    "app-bar"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/skip-link.txt

@@ -0,0 +1,96 @@
+# SkipLink
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: skip-link
+
+# SkipLink agent guide
+
+## Purpose
+
+Let keyboard and assistive-technology users bypass repeated page navigation and move focus to main content.
+
+## Use when
+
+- A page repeats navigation or controls before its main content.
+
+## Choose something else when
+
+- There is no repeated content before the primary content target. Use the normal document focus order.
+
+## Required composition
+
+- Place Root near the beginning of the page and provide one matching Target id at main content.
+
+## Rules
+
+- **MUST:** Keep Root href and Target id identical and unique.
+- **MUST:** Make Root the first useful focus target when it bypasses repeated navigation.
+
+## Common mistakes
+
+- **Avoid:** Linking to a missing id or adding a second main landmark around Target. **Instead:** Use one matching Target as the page's main landmark.
+
+## Validation checklist
+
+- Tab from the browser chrome, activate Root, and confirm Target receives visible focus and scrolls into view.
+- Confirm the document contains one main landmark.
+
+## Related guidance
+
+- `app-bar`
+- `sidebar`
+- `link`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "skip-link",
+  "name": "SkipLink",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Let keyboard and assistive-technology users bypass repeated page navigation and move focus to main content.",
+  "useWhen": [
+    "A page repeats navigation or controls before its main content."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "There is no repeated content before the primary content target.",
+      "useInstead": "the normal document focus order"
+    }
+  ],
+  "composition": [
+    "Place Root near the beginning of the page and provide one matching Target id at main content."
+  ],
+  "rules": [
+    {
+      "id": "skip-link-match",
+      "level": "must",
+      "statement": "Keep Root href and Target id identical and unique."
+    },
+    {
+      "id": "skip-link-first",
+      "level": "must",
+      "statement": "Make Root the first useful focus target when it bypasses repeated navigation."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Linking to a missing id or adding a second main landmark around Target.",
+      "correction": "Use one matching Target as the page's main landmark."
+    }
+  ],
+  "validation": [
+    "Tab from the browser chrome, activate Root, and confirm Target receives visible focus and scrolls into view.",
+    "Confirm the document contains one main landmark."
+  ],
+  "related": [
+    "app-bar",
+    "sidebar",
+    "link"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/slider.txt

@@ -0,0 +1,124 @@
+# Slider
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: slider
+
+# Slider agent guide
+
+## Purpose
+
+Adjust one numeric value or an ordered numeric range by pointer, touch, or keyboard with slider semantics, snapping, commit events, and optional form submission.
+
+## Use when
+
+- A user adjusts a number or range by feel and continuous spatial manipulation is more useful than exact text entry.
+
+## Choose something else when
+
+- An exact typed number matters, the value is read-only progress, or the ordered scale is specifically a small rating. Use NumberInput, Progress, or Rating.
+
+## Required composition
+
+- Give Root an accessible name and compose Track with one Thumb for a scalar value or one indexed Thumb per range value; add Range only when the styled layer needs decorative selected geometry. Use ariaValueText for values whose meaning is not obvious from the number.
+
+## Rules
+
+- **MUST:** Match Thumb count and indices to Root's scalar or array values; every Thumb is a focusable slider and Range remains decorative.
+- **MUST:** Give every Thumb an accessible name through Root native ARIA or Field labeling and provide ariaValueText when numeric values need human meaning.
+- **MUST:** Choose valid min, max, positive step, largeStep, and minStepsBetweenThumbs values and preserve each range Thumb's effective adjacent bounds.
+- **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.
+- **MUST:** Preserve disabled, read-only, invalid, required, Field, form submission, and uncontrolled reset behavior across every Thumb.
+
+## Common mistakes
+
+- **Avoid:** Using Slider when exact entry is required, rendering fewer Thumbs than range values, labeling only the decorative Track, or treating every live drag update as a committed value. **Instead:** Use NumberInput for exact entry, align values and Thumbs, label the slider controls through Root, and separate change from commit effects.
+
+## Validation checklist
+
+- Verify scalar and range controlled/uncontrolled values, Thumb indices and names, min/max/step snapping, effective dependent bounds, minimum gaps, Arrow, PageUp/PageDown, Home/End, orientation, disabled/read-only state, and LTR/RTL.
+- Verify track click, mouse, touch and pen dragging, nearest Thumb, one-pointer ownership, preserved cross-axis scrolling, true cancellation rollback without commit, lost-capture commit, onValueChange/onValueCommit timing, form values, Field relationships, and reset.
+
+## Related guidance
+
+- `number-input`
+- `progress`
+- `rating`
+- `field`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "slider",
+  "name": "Slider",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Adjust one numeric value or an ordered numeric range by pointer, touch, or keyboard with slider semantics, snapping, commit events, and optional form submission.",
+  "useWhen": [
+    "A user adjusts a number or range by feel and continuous spatial manipulation is more useful than exact text entry."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "An exact typed number matters, the value is read-only progress, or the ordered scale is specifically a small rating.",
+      "useInstead": "NumberInput, Progress, or Rating"
+    }
+  ],
+  "composition": [
+    "Give Root an accessible name and compose Track with one Thumb for a scalar value or one indexed Thumb per range value; add Range only when the styled layer needs decorative selected geometry. Use ariaValueText for values whose meaning is not obvious from the number."
+  ],
+  "rules": [
+    {
+      "id": "slider-thumb-count",
+      "level": "must",
+      "statement": "Match Thumb count and indices to Root's scalar or array values; every Thumb is a focusable slider and Range remains decorative."
+    },
+    {
+      "id": "slider-name",
+      "level": "must",
+      "statement": "Give every Thumb an accessible name through Root native ARIA or Field labeling and provide ariaValueText when numeric values need human meaning."
+    },
+    {
+      "id": "slider-range",
+      "level": "must",
+      "statement": "Choose valid min, max, positive step, largeStep, and minStepsBetweenThumbs values and preserve each range Thumb's effective adjacent bounds."
+    },
+    {
+      "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-state-form",
+      "level": "must",
+      "statement": "Preserve disabled, read-only, invalid, required, Field, form submission, and uncontrolled reset behavior across every Thumb."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Slider when exact entry is required, rendering fewer Thumbs than range values, labeling only the decorative Track, or treating every live drag update as a committed value.",
+      "correction": "Use NumberInput for exact entry, align values and Thumbs, label the slider controls through Root, and separate change from commit effects."
+    }
+  ],
+  "validation": [
+    "Verify scalar and range controlled/uncontrolled values, Thumb indices and names, min/max/step snapping, effective dependent bounds, minimum gaps, Arrow, PageUp/PageDown, Home/End, orientation, disabled/read-only state, and LTR/RTL.",
+    "Verify track click, mouse, touch and pen dragging, nearest Thumb, one-pointer ownership, preserved cross-axis scrolling, true cancellation rollback without commit, lost-capture commit, onValueChange/onValueCommit timing, form values, Field relationships, and reset."
+  ],
+  "related": [
+    "number-input",
+    "progress",
+    "rating",
+    "field",
+    "form"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/swipeable-item.txt

@@ -0,0 +1,118 @@
+# SwipeableItem
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: swipeable-item
+
+# SwipeableItem agent guide
+
+## Purpose
+
+Enhance a list-like row with direction-aware start or end action panels revealed by horizontal drag or equivalent keyboard commands while preserving vertical scrolling.
+
+## Use when
+
+- A row has a few quick actions that benefit from touch swipe reveal and the same actions remain available through an obvious tap or click route and keyboard reveal.
+
+## Choose something else when
+
+- There are many actions, discovery is critical, or swipe would be surprising or the only single-pointer path. Use Menu, visible actions, or another explicit application control.
+
+## Required composition
+
+- Compose Root with one focusable Content surface and an Actions group for each supported logical start or end side. Put real accessible buttons or links inside Actions and provide an obvious non-swipe route to every important command.
+
+## Rules
+
+- **MUST:** Treat swipe as enhancement only; keyboard reveal does not replace the required obvious tap or click alternative for important actions.
+- **MUST:** Give every Actions panel an accessible group name and its child controls complete semantics; keep closed panels inert and accessibility-hidden.
+- **MUST:** Preserve vertical pan, horizontal intent detection, pointer capture, cancellation rollback, measured side sizes, threshold settlement, and one owned pointer interaction rather than blocking page scrolling.
+- **MUST:** Keep Content focusable and preserve direction-aware Arrow reveal, opposite-Arrow close, same-Arrow full swipe, and Escape close only when Content itself owns the key; descendant controls retain their keys.
+- **MUST:** Enable onFullSwipe only for an action safe to invoke from a threshold gesture and retain an explicit equivalent control; choose thresholds deliberately.
+- **MUST:** Use openSide with onOpenSideChange for controlled state or defaultOpenSide for uncontrolled state and preserve disabled versus focusable read-only behavior and logical LTR/RTL sides.
+
+## Common mistakes
+
+- **Avoid:** Making swipe the only route to Delete, preventing vertical page scroll, firing a destructive full swipe too easily, or letting Arrow keys from nested controls reveal actions. **Instead:** Provide an explicit action route, retain pan-y behavior and intent thresholds, reserve full swipe for deliberate safe policy, and preserve keyboard target isolation.
+
+## Validation checklist
+
+- Verify controlled/uncontrolled start/end/null state, LTR and RTL logical side mapping, measured widths and offsets, pointer down/move/up settlement, threshold boundaries, cancellation rollback, capture, vertical pan, disabled/read-only state, and action closeOnClick.
+- Verify Content focus, Arrow reveal and close, same-Arrow full swipe, Escape, descendant keyboard isolation, hidden/inert closed panels, accessible action group and controls, obvious pointer fallback, full-swipe equivalent action, asChild/render composition, and real-browser mouse/touch scrolling behavior.
+
+## Related guidance
+
+- `menu`
+- `list`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "swipeable-item",
+  "name": "SwipeableItem",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Enhance a list-like row with direction-aware start or end action panels revealed by horizontal drag or equivalent keyboard commands while preserving vertical scrolling.",
+  "useWhen": [
+    "A row has a few quick actions that benefit from touch swipe reveal and the same actions remain available through an obvious tap or click route and keyboard reveal."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "There are many actions, discovery is critical, or swipe would be surprising or the only single-pointer path.",
+      "useInstead": "Menu, visible actions, or another explicit application control"
+    }
+  ],
+  "composition": [
+    "Compose Root with one focusable Content surface and an Actions group for each supported logical start or end side. Put real accessible buttons or links inside Actions and provide an obvious non-swipe route to every important command."
+  ],
+  "rules": [
+    {
+      "id": "swipeable-enhancement",
+      "level": "must",
+      "statement": "Treat swipe as enhancement only; keyboard reveal does not replace the required obvious tap or click alternative for important actions."
+    },
+    {
+      "id": "swipeable-actions",
+      "level": "must",
+      "statement": "Give every Actions panel an accessible group name and its child controls complete semantics; keep closed panels inert and accessibility-hidden."
+    },
+    {
+      "id": "swipeable-scroll-gesture",
+      "level": "must",
+      "statement": "Preserve vertical pan, horizontal intent detection, pointer capture, cancellation rollback, measured side sizes, threshold settlement, and one owned pointer interaction rather than blocking page scrolling."
+    },
+    {
+      "id": "swipeable-keyboard",
+      "level": "must",
+      "statement": "Keep Content focusable and preserve direction-aware Arrow reveal, opposite-Arrow close, same-Arrow full swipe, and Escape close only when Content itself owns the key; descendant controls retain their keys."
+    },
+    {
+      "id": "swipeable-full-swipe",
+      "level": "must",
+      "statement": "Enable onFullSwipe only for an action safe to invoke from a threshold gesture and retain an explicit equivalent control; choose thresholds deliberately."
+    },
+    {
+      "id": "swipeable-state",
+      "level": "must",
+      "statement": "Use openSide with onOpenSideChange for controlled state or defaultOpenSide for uncontrolled state and preserve disabled versus focusable read-only behavior and logical LTR/RTL sides."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Making swipe the only route to Delete, preventing vertical page scroll, firing a destructive full swipe too easily, or letting Arrow keys from nested controls reveal actions.",
+      "correction": "Provide an explicit action route, retain pan-y behavior and intent thresholds, reserve full swipe for deliberate safe policy, and preserve keyboard target isolation."
+    }
+  ],
+  "validation": [
+    "Verify controlled/uncontrolled start/end/null state, LTR and RTL logical side mapping, measured widths and offsets, pointer down/move/up settlement, threshold boundaries, cancellation rollback, capture, vertical pan, disabled/read-only state, and action closeOnClick.",
+    "Verify Content focus, Arrow reveal and close, same-Arrow full swipe, Escape, descendant keyboard isolation, hidden/inert closed panels, accessible action group and controls, obvious pointer fallback, full-swipe equivalent action, asChild/render composition, and real-browser mouse/touch scrolling behavior."
+  ],
+  "related": [
+    "menu",
+    "list"
+  ]
+}
+```