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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (239) hide show
  1. package/.codex-plugin/plugin.json +37 -0
  2. package/CHANGELOG.md +21 -0
  3. package/LICENSE +21 -0
  4. package/README.md +125 -0
  5. package/docs/architecture.md +77 -0
  6. package/docs/releasing.md +26 -0
  7. package/docs/testing.md +32 -0
  8. package/package.json +63 -0
  9. package/public/index.json +2073 -0
  10. package/public/llms.txt +19 -0
  11. package/public/packages/atom/0.24.0/components/accordion.txt +131 -0
  12. package/public/packages/atom/0.24.0/components/alert-dialog.txt +112 -0
  13. package/public/packages/atom/0.24.0/components/app-bar.txt +96 -0
  14. package/public/packages/atom/0.24.0/components/aspect-ratio.txt +111 -0
  15. package/public/packages/atom/0.24.0/components/avatar.txt +119 -0
  16. package/public/packages/atom/0.24.0/components/badge.txt +123 -0
  17. package/public/packages/atom/0.24.0/components/bottom-navigation.txt +96 -0
  18. package/public/packages/atom/0.24.0/components/breadcrumb.txt +96 -0
  19. package/public/packages/atom/0.24.0/components/button.txt +98 -0
  20. package/public/packages/atom/0.24.0/components/carousel.txt +128 -0
  21. package/public/packages/atom/0.24.0/components/checkbox-group.txt +118 -0
  22. package/public/packages/atom/0.24.0/components/checkbox.txt +100 -0
  23. package/public/packages/atom/0.24.0/components/clipboard.txt +112 -0
  24. package/public/packages/atom/0.24.0/components/collapsible.txt +112 -0
  25. package/public/packages/atom/0.24.0/components/color-picker.txt +117 -0
  26. package/public/packages/atom/0.24.0/components/combobox.txt +126 -0
  27. package/public/packages/atom/0.24.0/components/context-menu.txt +114 -0
  28. package/public/packages/atom/0.24.0/components/data-grid.txt +136 -0
  29. package/public/packages/atom/0.24.0/components/dialog.txt +116 -0
  30. package/public/packages/atom/0.24.0/components/direction.txt +132 -0
  31. package/public/packages/atom/0.24.0/components/divider.txt +94 -0
  32. package/public/packages/atom/0.24.0/components/drag-drop.txt +141 -0
  33. package/public/packages/atom/0.24.0/components/drawer.txt +96 -0
  34. package/public/packages/atom/0.24.0/components/dropdown-menu.txt +112 -0
  35. package/public/packages/atom/0.24.0/components/feed.txt +132 -0
  36. package/public/packages/atom/0.24.0/components/field.txt +108 -0
  37. package/public/packages/atom/0.24.0/components/fieldset.txt +96 -0
  38. package/public/packages/atom/0.24.0/components/file-upload.txt +120 -0
  39. package/public/packages/atom/0.24.0/components/form.txt +98 -0
  40. package/public/packages/atom/0.24.0/components/hover-card.txt +114 -0
  41. package/public/packages/atom/0.24.0/components/image.txt +94 -0
  42. package/public/packages/atom/0.24.0/components/input.txt +96 -0
  43. package/public/packages/atom/0.24.0/components/label.txt +121 -0
  44. package/public/packages/atom/0.24.0/components/link.txt +100 -0
  45. package/public/packages/atom/0.24.0/components/list.txt +131 -0
  46. package/public/packages/atom/0.24.0/components/listbox.txt +120 -0
  47. package/public/packages/atom/0.24.0/components/menu.txt +126 -0
  48. package/public/packages/atom/0.24.0/components/menubar.txt +120 -0
  49. package/public/packages/atom/0.24.0/components/modal.txt +118 -0
  50. package/public/packages/atom/0.24.0/components/multi-select.txt +120 -0
  51. package/public/packages/atom/0.24.0/components/nav-list.txt +104 -0
  52. package/public/packages/atom/0.24.0/components/navigation-menu.txt +104 -0
  53. package/public/packages/atom/0.24.0/components/number-input.txt +124 -0
  54. package/public/packages/atom/0.24.0/components/otp-field.txt +122 -0
  55. package/public/packages/atom/0.24.0/components/pagination.txt +111 -0
  56. package/public/packages/atom/0.24.0/components/password-toggle-field.txt +116 -0
  57. package/public/packages/atom/0.24.0/components/popover.txt +122 -0
  58. package/public/packages/atom/0.24.0/components/pressable.txt +94 -0
  59. package/public/packages/atom/0.24.0/components/progress.txt +130 -0
  60. package/public/packages/atom/0.24.0/components/radio-group.txt +118 -0
  61. package/public/packages/atom/0.24.0/components/rating.txt +122 -0
  62. package/public/packages/atom/0.24.0/components/reorder.txt +141 -0
  63. package/public/packages/atom/0.24.0/components/scroll-area.txt +96 -0
  64. package/public/packages/atom/0.24.0/components/select.txt +126 -0
  65. package/public/packages/atom/0.24.0/components/sidebar.txt +96 -0
  66. package/public/packages/atom/0.24.0/components/skip-link.txt +96 -0
  67. package/public/packages/atom/0.24.0/components/slider.txt +124 -0
  68. package/public/packages/atom/0.24.0/components/swipeable-item.txt +118 -0
  69. package/public/packages/atom/0.24.0/components/switch.txt +116 -0
  70. package/public/packages/atom/0.24.0/components/table.txt +128 -0
  71. package/public/packages/atom/0.24.0/components/tabs.txt +96 -0
  72. package/public/packages/atom/0.24.0/components/textarea.txt +96 -0
  73. package/public/packages/atom/0.24.0/components/toast.txt +124 -0
  74. package/public/packages/atom/0.24.0/components/toggle-group.txt +118 -0
  75. package/public/packages/atom/0.24.0/components/toggle.txt +110 -0
  76. package/public/packages/atom/0.24.0/components/toolbar.txt +98 -0
  77. package/public/packages/atom/0.24.0/components/tooltip.txt +112 -0
  78. package/public/packages/atom/0.24.0/components/tree-grid.txt +138 -0
  79. package/public/packages/atom/0.24.0/components/tree.txt +138 -0
  80. package/public/packages/atom/0.24.0/components/visually-hidden.txt +119 -0
  81. package/public/packages/atom/0.24.0/docs/guides/agent-knowledge.txt +55 -0
  82. package/public/packages/atom/0.24.0/docs/guides/getting-started.txt +65 -0
  83. package/public/packages/atom/0.24.0/docs/guides/imports.txt +26 -0
  84. package/public/packages/atom/0.24.0/docs/guides/public-api.txt +100 -0
  85. package/public/packages/atom/0.24.0/guides/behavior-composition.txt +277 -0
  86. package/public/packages/atom/0.24.0/guides/layer-selection.txt +807 -0
  87. package/public/packages/atom/0.24.0/index.txt +89 -0
  88. package/public/packages/brick/0.1.11/components/accordion.txt +158 -0
  89. package/public/packages/brick/0.1.11/components/alert-dialog.txt +175 -0
  90. package/public/packages/brick/0.1.11/components/app-bar.txt +134 -0
  91. package/public/packages/brick/0.1.11/components/appearance.txt +143 -0
  92. package/public/packages/brick/0.1.11/components/aspect-ratio.txt +136 -0
  93. package/public/packages/brick/0.1.11/components/avatar.txt +152 -0
  94. package/public/packages/brick/0.1.11/components/badge.txt +139 -0
  95. package/public/packages/brick/0.1.11/components/bleed.txt +104 -0
  96. package/public/packages/brick/0.1.11/components/bottom-navigation.txt +106 -0
  97. package/public/packages/brick/0.1.11/components/breadcrumb.txt +96 -0
  98. package/public/packages/brick/0.1.11/components/button.txt +103 -0
  99. package/public/packages/brick/0.1.11/components/card.txt +132 -0
  100. package/public/packages/brick/0.1.11/components/carousel.txt +206 -0
  101. package/public/packages/brick/0.1.11/components/checkbox-group.txt +175 -0
  102. package/public/packages/brick/0.1.11/components/checkbox.txt +103 -0
  103. package/public/packages/brick/0.1.11/components/chip.txt +128 -0
  104. package/public/packages/brick/0.1.11/components/code-block.txt +134 -0
  105. package/public/packages/brick/0.1.11/components/code.txt +120 -0
  106. package/public/packages/brick/0.1.11/components/collapsible.txt +179 -0
  107. package/public/packages/brick/0.1.11/components/color-picker.txt +135 -0
  108. package/public/packages/brick/0.1.11/components/color-swatch.txt +98 -0
  109. package/public/packages/brick/0.1.11/components/combobox.txt +157 -0
  110. package/public/packages/brick/0.1.11/components/container.txt +112 -0
  111. package/public/packages/brick/0.1.11/components/context-menu.txt +174 -0
  112. package/public/packages/brick/0.1.11/components/data-grid.txt +199 -0
  113. package/public/packages/brick/0.1.11/components/data-list.txt +115 -0
  114. package/public/packages/brick/0.1.11/components/dialog.txt +176 -0
  115. package/public/packages/brick/0.1.11/components/divider.txt +104 -0
  116. package/public/packages/brick/0.1.11/components/drawer.txt +146 -0
  117. package/public/packages/brick/0.1.11/components/dropdown-menu.txt +179 -0
  118. package/public/packages/brick/0.1.11/components/feed.txt +143 -0
  119. package/public/packages/brick/0.1.11/components/field.txt +115 -0
  120. package/public/packages/brick/0.1.11/components/fieldset.txt +103 -0
  121. package/public/packages/brick/0.1.11/components/file-upload.txt +154 -0
  122. package/public/packages/brick/0.1.11/components/form.txt +108 -0
  123. package/public/packages/brick/0.1.11/components/frame.txt +132 -0
  124. package/public/packages/brick/0.1.11/components/grid.txt +141 -0
  125. package/public/packages/brick/0.1.11/components/group.txt +136 -0
  126. package/public/packages/brick/0.1.11/components/hide.txt +121 -0
  127. package/public/packages/brick/0.1.11/components/hover-card.txt +156 -0
  128. package/public/packages/brick/0.1.11/components/icon-button.txt +119 -0
  129. package/public/packages/brick/0.1.11/components/icon.txt +160 -0
  130. package/public/packages/brick/0.1.11/components/image.txt +163 -0
  131. package/public/packages/brick/0.1.11/components/input.txt +101 -0
  132. package/public/packages/brick/0.1.11/components/link-box.txt +161 -0
  133. package/public/packages/brick/0.1.11/components/link.txt +133 -0
  134. package/public/packages/brick/0.1.11/components/list.txt +139 -0
  135. package/public/packages/brick/0.1.11/components/menubar.txt +174 -0
  136. package/public/packages/brick/0.1.11/components/multi-select.txt +153 -0
  137. package/public/packages/brick/0.1.11/components/nav-list.txt +130 -0
  138. package/public/packages/brick/0.1.11/components/navigation-menu.txt +150 -0
  139. package/public/packages/brick/0.1.11/components/notification-badge.txt +148 -0
  140. package/public/packages/brick/0.1.11/components/number-input.txt +150 -0
  141. package/public/packages/brick/0.1.11/components/otp-field.txt +146 -0
  142. package/public/packages/brick/0.1.11/components/pagination.txt +124 -0
  143. package/public/packages/brick/0.1.11/components/password-toggle-field.txt +146 -0
  144. package/public/packages/brick/0.1.11/components/popover.txt +181 -0
  145. package/public/packages/brick/0.1.11/components/progress-circle.txt +142 -0
  146. package/public/packages/brick/0.1.11/components/progress.txt +150 -0
  147. package/public/packages/brick/0.1.11/components/radio-group.txt +152 -0
  148. package/public/packages/brick/0.1.11/components/rating.txt +151 -0
  149. package/public/packages/brick/0.1.11/components/reorderable-list.txt +130 -0
  150. package/public/packages/brick/0.1.11/components/scroll-area.txt +110 -0
  151. package/public/packages/brick/0.1.11/components/section.txt +118 -0
  152. package/public/packages/brick/0.1.11/components/segment-group.txt +116 -0
  153. package/public/packages/brick/0.1.11/components/select.txt +157 -0
  154. package/public/packages/brick/0.1.11/components/show.txt +121 -0
  155. package/public/packages/brick/0.1.11/components/sidebar.txt +126 -0
  156. package/public/packages/brick/0.1.11/components/skeleton.txt +127 -0
  157. package/public/packages/brick/0.1.11/components/skip-link.txt +102 -0
  158. package/public/packages/brick/0.1.11/components/slider.txt +147 -0
  159. package/public/packages/brick/0.1.11/components/stack.txt +155 -0
  160. package/public/packages/brick/0.1.11/components/status.txt +110 -0
  161. package/public/packages/brick/0.1.11/components/surface.txt +194 -0
  162. package/public/packages/brick/0.1.11/components/swipeable-item.txt +154 -0
  163. package/public/packages/brick/0.1.11/components/switch.txt +152 -0
  164. package/public/packages/brick/0.1.11/components/table.txt +183 -0
  165. package/public/packages/brick/0.1.11/components/tabs.txt +136 -0
  166. package/public/packages/brick/0.1.11/components/text.txt +148 -0
  167. package/public/packages/brick/0.1.11/components/textarea.txt +101 -0
  168. package/public/packages/brick/0.1.11/components/toast.txt +150 -0
  169. package/public/packages/brick/0.1.11/components/toggle-group.txt +149 -0
  170. package/public/packages/brick/0.1.11/components/toggle.txt +140 -0
  171. package/public/packages/brick/0.1.11/components/toolbar.txt +118 -0
  172. package/public/packages/brick/0.1.11/components/tooltip.txt +156 -0
  173. package/public/packages/brick/0.1.11/components/tree-grid.txt +160 -0
  174. package/public/packages/brick/0.1.11/components/tree.txt +156 -0
  175. package/public/packages/brick/0.1.11/components/visually-hidden.txt +123 -0
  176. package/public/packages/brick/0.1.11/components/z-stack.txt +143 -0
  177. package/public/packages/brick/0.1.11/docs/guides/agent-knowledge.txt +67 -0
  178. package/public/packages/brick/0.1.11/docs/guides/appearance-and-tokens.txt +179 -0
  179. package/public/packages/brick/0.1.11/docs/guides/browser-support.txt +25 -0
  180. package/public/packages/brick/0.1.11/docs/guides/control-sizing.txt +59 -0
  181. package/public/packages/brick/0.1.11/docs/guides/installation.txt +79 -0
  182. package/public/packages/brick/0.1.11/docs/guides/theme-contract.txt +90 -0
  183. package/public/packages/brick/0.1.11/guides/interface-composition.txt +665 -0
  184. package/public/packages/brick/0.1.11/guides/layer-selection.txt +1437 -0
  185. package/public/packages/brick/0.1.11/index.txt +110 -0
  186. package/public/packages/colors/0.1.1/docs/agent-knowledge.txt +63 -0
  187. package/public/packages/colors/0.1.1/docs/architecture.txt +74 -0
  188. package/public/packages/colors/0.1.1/docs/color-foundations.txt +128 -0
  189. package/public/packages/colors/0.1.1/docs/compatibility.txt +75 -0
  190. package/public/packages/colors/0.1.1/docs/dependency-qualification.txt +117 -0
  191. package/public/packages/colors/0.1.1/docs/installation.txt +48 -0
  192. package/public/packages/colors/0.1.1/docs/palette-generation.txt +151 -0
  193. package/public/packages/colors/0.1.1/docs/releasing.txt +34 -0
  194. package/public/packages/colors/0.1.1/docs/testing.txt +51 -0
  195. package/public/packages/colors/0.1.1/guides/colors-system.txt +282 -0
  196. package/public/packages/colors/0.1.1/index.txt +29 -0
  197. package/public/packages/colors/0.1.1/operations/color-conversion.txt +14 -0
  198. package/public/packages/colors/0.1.1/operations/color-inspection.txt +23 -0
  199. package/public/packages/colors/0.1.1/operations/color-measurement.txt +18 -0
  200. package/public/packages/colors/0.1.1/operations/color-provenance.txt +14 -0
  201. package/public/packages/colors/0.1.1/operations/named-palette-reference.txt +15 -0
  202. package/public/packages/colors/0.1.1/operations/palette-candidate.txt +37 -0
  203. package/public/packages/theme/0.1.1/docs/agent-knowledge.txt +44 -0
  204. package/public/packages/theme/0.1.1/docs/appearances-and-portals.txt +41 -0
  205. package/public/packages/theme/0.1.1/docs/architecture.txt +121 -0
  206. package/public/packages/theme/0.1.1/docs/authoring.txt +141 -0
  207. package/public/packages/theme/0.1.1/docs/colors-interchange.txt +82 -0
  208. package/public/packages/theme/0.1.1/docs/fonts.txt +40 -0
  209. package/public/packages/theme/0.1.1/docs/installation.txt +45 -0
  210. package/public/packages/theme/0.1.1/docs/migration.txt +40 -0
  211. package/public/packages/theme/0.1.1/docs/testing.txt +64 -0
  212. package/public/packages/theme/0.1.1/docs/troubleshooting.txt +53 -0
  213. package/public/packages/theme/0.1.1/guides/theme-system.txt +340 -0
  214. package/public/packages/theme/0.1.1/index.txt +31 -0
  215. package/public/packages/theme/0.1.1/operations/brick-contract-compatibility.txt +35 -0
  216. package/public/packages/theme/0.1.1/operations/colors-interchange.txt +35 -0
  217. package/public/packages/theme/0.1.1/operations/theme-artifacts.txt +19 -0
  218. package/public/packages/theme/0.1.1/operations/theme-cli.txt +10 -0
  219. package/public/packages/theme/0.1.1/operations/theme-compilation.txt +23 -0
  220. package/public/packages/theme/0.1.1/operations/theme-definition.txt +36 -0
  221. package/public/packages/theme/0.1.1/operations/theme-validation.txt +19 -0
  222. package/public/tasks/data.txt +39 -0
  223. package/public/tasks/forms.txt +65 -0
  224. package/public/tasks/layout.txt +37 -0
  225. package/public/tasks/navigation.txt +51 -0
  226. package/public/tasks/overlays.txt +39 -0
  227. package/public/tasks/theming.txt +37 -0
  228. package/skills/flowstack-ui-builder/SKILL.md +35 -0
  229. package/skills/flowstack-ui-builder/agents/openai.yaml +4 -0
  230. package/skills/flowstack-ui-builder/scripts/resolve-agent-knowledge.mjs +399 -0
  231. package/skills/flowstack-ui-compose/SKILL.md +32 -0
  232. package/skills/flowstack-ui-compose/agents/openai.yaml +4 -0
  233. package/skills/flowstack-ui-compose/scripts/resolve-agent-knowledge.mjs +399 -0
  234. package/skills/flowstack-ui-maintainer/SKILL.md +40 -0
  235. package/skills/flowstack-ui-maintainer/agents/openai.yaml +4 -0
  236. package/skills/flowstack-ui-maintainer/scripts/resolve-agent-knowledge.mjs +399 -0
  237. package/skills/flowstack-ui-review/SKILL.md +29 -0
  238. package/skills/flowstack-ui-review/agents/openai.yaml +4 -0
  239. package/skills/flowstack-ui-review/scripts/resolve-agent-knowledge.mjs +399 -0
@@ -0,0 +1,807 @@
1
+ # Atom layer selection
2
+
3
+ Source: @flowstack-ui/atom@0.24.0
4
+ Kind: guide
5
+ ID: layer-selection
6
+
7
+ # Atom layer selection
8
+
9
+ ## Purpose
10
+
11
+ Decide whether reusable headless behavior belongs in Atom, an existing native element, Brick, a higher composition layer, or the application before composing a primitive.
12
+
13
+ ## Decision order
14
+
15
+ 1. Start from the semantic and interaction job, not the desired appearance.
16
+ 2. Use an existing native element when it already provides the complete reusable behavior contract.
17
+ 3. Use an Atom primitive when reusable semantics, state, focus, keyboard, pointer, touch, portal, positioning, or compound composition are required.
18
+ 4. Use Brick instead when the consumer needs a finished visual component; ordinary Brick applications should not import Atom directly.
19
+ 5. Keep product workflows, page layout, content, routing, persistence, and analytics in higher layers.
20
+
21
+ ## Selection map
22
+
23
+ - **native action:** use Button. Choose Link for ordinary navigation and Pressable only for custom interactive surfaces.
24
+ - **application header structure:** use AppBar. Compose Toolbar only when grouped controls require toolbar keyboard behavior.
25
+ - **site or application navigation:** use NavList, NavigationMenu, Breadcrumb, BottomNavigation, Tabs, or Pagination. Select by the navigation relationship, not by visual resemblance.
26
+ - **temporary commands or settings:** use DropdownMenu from a visible button, ContextMenu from a contextual gesture, Menubar for persistent application command groups, or Menu as the shared direct/custom foundation. Use Select or Listbox when choosing a form value and keep important contextual actions discoverable elsewhere.
27
+ - **supplemental floating disclosure:** use Tooltip for a brief hint or HoverCard for a richer passive preview. Choose Popover when the content is interactive and visible native content when the information is essential.
28
+ - **choice or persistent control state:** use CheckboxGroup for independent form choices, RadioGroup for one visible form answer, Switch for an immediately applied on/off setting, Toggle for one pressed command, or ToggleGroup for related pressed commands. Choose by semantics and application timing rather than visual shape.
29
+ - **spatial numeric input:** use Slider for a general scalar or range adjusted by feel, or Rating for a short ordered score. Choose NumberInput when exact typed entry matters and Progress when the value is read-only.
30
+ - **option selection presentation:** use Listbox for a visible composite list, Select for one collapsed fixed value, MultiSelect for several collapsed fixed values, or Combobox for editable filtering and optional valid free-form entry. Choose RadioGroup or CheckboxGroup when short form choices should remain separate visible controls.
31
+ - **specialized text entry:** use NumberInput for exact numeric entry with stepping, OTPField for a short one-time code split across cells, or PasswordToggleField for a revealable reusable secret. Keep ordinary text and digit-like identifiers in Input.
32
+ - **local file selection and drop:** use FileUpload. Use a native file input when custom picker, drop, validation feedback, and selected-item behavior are unnecessary; always validate uploads again on the server.
33
+ - **copy known text with status:** use Clipboard. Choose Button when asynchronous copy state and authored feedback are unnecessary.
34
+ - **short non-blocking update:** use Toast. Use inline content for contextual or durable feedback and AlertDialog when a response is required.
35
+ - **gesture-enhanced row actions:** use SwipeableItem. Keep an obvious tap or click path and choose Menu when many actions or discovery make swipe unsuitable.
36
+ - **one inline disclosure region:** use Collapsible. Choose Accordion for several coordinated sections or Dialog for a modal task.
37
+ - **row and column data:** use Table for read-oriented comparison, DataGrid for flat two-dimensional keyboard navigation or row selection, or TreeGrid for hierarchical interactive rows. Keep sorting, editing, filtering, resizing, and virtualization application-composed and preserve full logical indexes when windowing.
38
+ - **hierarchical item navigation:** use Tree for one primary item column or TreeGrid for several navigable columns. Choose Accordion when branches contain general disclosure content rather than selectable items.
39
+ - **dynamic article stream:** use Feed. Choose List for a static set and add virtualization only when scale justifies its focus and accessibility cost.
40
+ - **stable media geometry:** use AspectRatio. Use Image when loading fallback is also required and keep all media semantics on the child.
41
+ - **compact identity or contextual status:** use Avatar for a named entity or Badge for a short contextual count or status. Keep essential identity visible and use Progress for ongoing completion rather than status text.
42
+ - **form control labeling:** use Label for one standalone native control or Field.Label for coordinated control, description, error, and state wiring. Use Fieldset for a group of controls.
43
+ - **ongoing work status:** use Progress for determinate or indeterminate completion. Choose the native meter element for a stable measurement, Slider for user adjustment, or Toast for a short nonblocking update.
44
+ - **assistive-only text:** use VisuallyHidden. Prefer visible text when it benefits everyone and use aria-hidden rather than VisuallyHidden for decorative content.
45
+ - **direction-aware Atom subtree:** use Direction together with the matching native dir attribute. Provider mirrors Atom behavior but never replaces browser text-direction semantics; prefer a component's local dir prop only for an intentional nested override.
46
+ - **ordinary blocking task, form, or information surface:** use Dialog. Choose AlertDialog for an urgent consequential choice, Drawer for a side sheet, or Popover for a compact attached panel.
47
+ - **custom modal-family primitive foundation:** use Modal. Application work should prefer the purpose-built modal-family components.
48
+ - **scrollable viewport with owned scrollbar behavior:** use ScrollArea. Keep ordinary document scrolling native.
49
+ - **resilient media loading:** use Image. Use a native img when loading state and fallback composition are unnecessary.
50
+ - **grouped disclosure sections:** use Accordion. Choose Collapsible for one independent disclosure and Tabs for one shared switching panel.
51
+ - **static ordered or unordered content:** use List. Choose NavList or an interactive collection primitive when items navigate, select, or activate.
52
+
53
+ ## Rules
54
+
55
+ - **MUST:** Keep Atom guidance and compositions headless; do not add visual recipes, color, theme, product copy, or application layout policy.
56
+ - **MUST:** Preserve native semantics and behavior unless Atom explicitly owns the added reusable contract.
57
+ - **MUST:** Do not rebuild focus, keyboard, pointer, touch, portal, positioning, or controlled-state behavior already owned by an Atom primitive.
58
+ - **SHOULD:** When building with Brick, consume Brick public components and let Brick consume Atom rather than importing both layers directly.
59
+
60
+ ## Native fallback
61
+
62
+ 1. Search Atom's manifest, public exports, and related component guides for the required behavior before using a native fallback.
63
+ 2. Use the narrowest semantic native element only when no Atom primitive owns the behavior and no reusable state or interaction contract is being recreated.
64
+ 3. Record the missing primitive or intentional native choice so repeated gaps can be evaluated by Atom maintainers.
65
+
66
+ ## Validation checklist
67
+
68
+ - Name the selected semantic and interaction job and its owning layer.
69
+ - Confirm no visual or application policy entered the Atom composition.
70
+ - Confirm the rendered elements, accessible names, state, focus, keyboard, pointer, touch, and RTL behavior that apply.
71
+ - Record any native fallback and the Atom capability searched first.
72
+
73
+ ## Related guidance
74
+
75
+ - `behavior-composition`
76
+ - `button`
77
+ - `link`
78
+ - `pressable`
79
+ - `app-bar`
80
+ - `navigation-menu`
81
+ - `menu`
82
+ - `dropdown-menu`
83
+ - `context-menu`
84
+ - `menubar`
85
+ - `tooltip`
86
+ - `hover-card`
87
+ - `checkbox-group`
88
+ - `radio-group`
89
+ - `switch`
90
+ - `toggle`
91
+ - `toggle-group`
92
+ - `slider`
93
+ - `rating`
94
+ - `listbox`
95
+ - `select`
96
+ - `multi-select`
97
+ - `combobox`
98
+ - `number-input`
99
+ - `otp-field`
100
+ - `password-toggle-field`
101
+ - `file-upload`
102
+ - `clipboard`
103
+ - `toast`
104
+ - `swipeable-item`
105
+ - `collapsible`
106
+ - `table`
107
+ - `data-grid`
108
+ - `tree`
109
+ - `tree-grid`
110
+ - `feed`
111
+ - `aspect-ratio`
112
+ - `avatar`
113
+ - `badge`
114
+ - `label`
115
+ - `progress`
116
+ - `visually-hidden`
117
+ - `direction`
118
+ - `modal`
119
+ - `dialog`
120
+ - `alert-dialog`
121
+ - `drawer`
122
+ - `popover`
123
+ - `accordion`
124
+ - `list`
125
+
126
+ ## Machine record
127
+
128
+ ```json
129
+ {
130
+ "schema": "flowstack.agent-guide.v1",
131
+ "id": "layer-selection",
132
+ "name": "Atom layer selection",
133
+ "package": "@flowstack-ui/atom",
134
+ "layer": "atom",
135
+ "kind": "guide",
136
+ "purpose": "Decide whether reusable headless behavior belongs in Atom, an existing native element, Brick, a higher composition layer, or the application before composing a primitive.",
137
+ "decisionOrder": [
138
+ "Start from the semantic and interaction job, not the desired appearance.",
139
+ "Use an existing native element when it already provides the complete reusable behavior contract.",
140
+ "Use an Atom primitive when reusable semantics, state, focus, keyboard, pointer, touch, portal, positioning, or compound composition are required.",
141
+ "Use Brick instead when the consumer needs a finished visual component; ordinary Brick applications should not import Atom directly.",
142
+ "Keep product workflows, page layout, content, routing, persistence, and analytics in higher layers."
143
+ ],
144
+ "selection": [
145
+ {
146
+ "intent": "native action",
147
+ "use": "Button",
148
+ "note": "Choose Link for ordinary navigation and Pressable only for custom interactive surfaces.",
149
+ "destinations": [
150
+ {
151
+ "kind": "component",
152
+ "id": "button"
153
+ },
154
+ {
155
+ "kind": "component",
156
+ "id": "link"
157
+ },
158
+ {
159
+ "kind": "component",
160
+ "id": "pressable"
161
+ }
162
+ ]
163
+ },
164
+ {
165
+ "intent": "application header structure",
166
+ "use": "AppBar",
167
+ "note": "Compose Toolbar only when grouped controls require toolbar keyboard behavior.",
168
+ "destinations": [
169
+ {
170
+ "kind": "component",
171
+ "id": "app-bar"
172
+ },
173
+ {
174
+ "kind": "component",
175
+ "id": "toolbar"
176
+ }
177
+ ]
178
+ },
179
+ {
180
+ "intent": "site or application navigation",
181
+ "use": "NavList, NavigationMenu, Breadcrumb, BottomNavigation, Tabs, or Pagination",
182
+ "note": "Select by the navigation relationship, not by visual resemblance.",
183
+ "destinations": [
184
+ {
185
+ "kind": "component",
186
+ "id": "nav-list"
187
+ },
188
+ {
189
+ "kind": "component",
190
+ "id": "navigation-menu"
191
+ },
192
+ {
193
+ "kind": "component",
194
+ "id": "breadcrumb"
195
+ },
196
+ {
197
+ "kind": "component",
198
+ "id": "bottom-navigation"
199
+ },
200
+ {
201
+ "kind": "component",
202
+ "id": "tabs"
203
+ },
204
+ {
205
+ "kind": "component",
206
+ "id": "pagination"
207
+ }
208
+ ]
209
+ },
210
+ {
211
+ "intent": "temporary commands or settings",
212
+ "use": "DropdownMenu from a visible button, ContextMenu from a contextual gesture, Menubar for persistent application command groups, or Menu as the shared direct/custom foundation",
213
+ "note": "Use Select or Listbox when choosing a form value and keep important contextual actions discoverable elsewhere.",
214
+ "destinations": [
215
+ {
216
+ "kind": "component",
217
+ "id": "dropdown-menu"
218
+ },
219
+ {
220
+ "kind": "component",
221
+ "id": "context-menu"
222
+ },
223
+ {
224
+ "kind": "component",
225
+ "id": "menubar"
226
+ },
227
+ {
228
+ "kind": "component",
229
+ "id": "menu"
230
+ },
231
+ {
232
+ "kind": "component",
233
+ "id": "select"
234
+ },
235
+ {
236
+ "kind": "component",
237
+ "id": "listbox"
238
+ }
239
+ ]
240
+ },
241
+ {
242
+ "intent": "supplemental floating disclosure",
243
+ "use": "Tooltip for a brief hint or HoverCard for a richer passive preview",
244
+ "note": "Choose Popover when the content is interactive and visible native content when the information is essential.",
245
+ "destinations": [
246
+ {
247
+ "kind": "component",
248
+ "id": "tooltip"
249
+ },
250
+ {
251
+ "kind": "component",
252
+ "id": "hover-card"
253
+ },
254
+ {
255
+ "kind": "component",
256
+ "id": "popover"
257
+ },
258
+ {
259
+ "kind": "native-application",
260
+ "id": "native-element"
261
+ }
262
+ ]
263
+ },
264
+ {
265
+ "intent": "choice or persistent control state",
266
+ "use": "CheckboxGroup for independent form choices, RadioGroup for one visible form answer, Switch for an immediately applied on/off setting, Toggle for one pressed command, or ToggleGroup for related pressed commands",
267
+ "note": "Choose by semantics and application timing rather than visual shape.",
268
+ "destinations": [
269
+ {
270
+ "kind": "component",
271
+ "id": "checkbox-group"
272
+ },
273
+ {
274
+ "kind": "component",
275
+ "id": "radio-group"
276
+ },
277
+ {
278
+ "kind": "component",
279
+ "id": "switch"
280
+ },
281
+ {
282
+ "kind": "component",
283
+ "id": "toggle"
284
+ },
285
+ {
286
+ "kind": "component",
287
+ "id": "toggle-group"
288
+ }
289
+ ]
290
+ },
291
+ {
292
+ "intent": "spatial numeric input",
293
+ "use": "Slider for a general scalar or range adjusted by feel, or Rating for a short ordered score",
294
+ "note": "Choose NumberInput when exact typed entry matters and Progress when the value is read-only.",
295
+ "destinations": [
296
+ {
297
+ "kind": "component",
298
+ "id": "slider"
299
+ },
300
+ {
301
+ "kind": "component",
302
+ "id": "rating"
303
+ },
304
+ {
305
+ "kind": "component",
306
+ "id": "number-input"
307
+ },
308
+ {
309
+ "kind": "component",
310
+ "id": "progress"
311
+ }
312
+ ]
313
+ },
314
+ {
315
+ "intent": "option selection presentation",
316
+ "use": "Listbox for a visible composite list, Select for one collapsed fixed value, MultiSelect for several collapsed fixed values, or Combobox for editable filtering and optional valid free-form entry",
317
+ "note": "Choose RadioGroup or CheckboxGroup when short form choices should remain separate visible controls.",
318
+ "destinations": [
319
+ {
320
+ "kind": "component",
321
+ "id": "listbox"
322
+ },
323
+ {
324
+ "kind": "component",
325
+ "id": "select"
326
+ },
327
+ {
328
+ "kind": "component",
329
+ "id": "multi-select"
330
+ },
331
+ {
332
+ "kind": "component",
333
+ "id": "combobox"
334
+ },
335
+ {
336
+ "kind": "component",
337
+ "id": "radio-group"
338
+ },
339
+ {
340
+ "kind": "component",
341
+ "id": "checkbox-group"
342
+ }
343
+ ]
344
+ },
345
+ {
346
+ "intent": "specialized text entry",
347
+ "use": "NumberInput for exact numeric entry with stepping, OTPField for a short one-time code split across cells, or PasswordToggleField for a revealable reusable secret",
348
+ "note": "Keep ordinary text and digit-like identifiers in Input.",
349
+ "destinations": [
350
+ {
351
+ "kind": "component",
352
+ "id": "number-input"
353
+ },
354
+ {
355
+ "kind": "component",
356
+ "id": "otp-field"
357
+ },
358
+ {
359
+ "kind": "component",
360
+ "id": "password-toggle-field"
361
+ },
362
+ {
363
+ "kind": "component",
364
+ "id": "input"
365
+ }
366
+ ]
367
+ },
368
+ {
369
+ "intent": "local file selection and drop",
370
+ "use": "FileUpload",
371
+ "note": "Use a native file input when custom picker, drop, validation feedback, and selected-item behavior are unnecessary; always validate uploads again on the server.",
372
+ "destinations": [
373
+ {
374
+ "kind": "component",
375
+ "id": "file-upload"
376
+ },
377
+ {
378
+ "kind": "native-application",
379
+ "id": "native-element"
380
+ }
381
+ ]
382
+ },
383
+ {
384
+ "intent": "copy known text with status",
385
+ "use": "Clipboard",
386
+ "note": "Choose Button when asynchronous copy state and authored feedback are unnecessary.",
387
+ "destinations": [
388
+ {
389
+ "kind": "component",
390
+ "id": "clipboard"
391
+ },
392
+ {
393
+ "kind": "component",
394
+ "id": "button"
395
+ }
396
+ ]
397
+ },
398
+ {
399
+ "intent": "short non-blocking update",
400
+ "use": "Toast",
401
+ "note": "Use inline content for contextual or durable feedback and AlertDialog when a response is required.",
402
+ "destinations": [
403
+ {
404
+ "kind": "component",
405
+ "id": "toast"
406
+ },
407
+ {
408
+ "kind": "component",
409
+ "id": "alert-dialog"
410
+ },
411
+ {
412
+ "kind": "native-application",
413
+ "id": "native-element"
414
+ }
415
+ ]
416
+ },
417
+ {
418
+ "intent": "gesture-enhanced row actions",
419
+ "use": "SwipeableItem",
420
+ "note": "Keep an obvious tap or click path and choose Menu when many actions or discovery make swipe unsuitable.",
421
+ "destinations": [
422
+ {
423
+ "kind": "component",
424
+ "id": "swipeable-item"
425
+ },
426
+ {
427
+ "kind": "component",
428
+ "id": "menu"
429
+ }
430
+ ]
431
+ },
432
+ {
433
+ "intent": "one inline disclosure region",
434
+ "use": "Collapsible",
435
+ "note": "Choose Accordion for several coordinated sections or Dialog for a modal task.",
436
+ "destinations": [
437
+ {
438
+ "kind": "component",
439
+ "id": "collapsible"
440
+ },
441
+ {
442
+ "kind": "component",
443
+ "id": "accordion"
444
+ },
445
+ {
446
+ "kind": "component",
447
+ "id": "dialog"
448
+ }
449
+ ]
450
+ },
451
+ {
452
+ "intent": "row and column data",
453
+ "use": "Table for read-oriented comparison, DataGrid for flat two-dimensional keyboard navigation or row selection, or TreeGrid for hierarchical interactive rows",
454
+ "note": "Keep sorting, editing, filtering, resizing, and virtualization application-composed and preserve full logical indexes when windowing.",
455
+ "destinations": [
456
+ {
457
+ "kind": "component",
458
+ "id": "table"
459
+ },
460
+ {
461
+ "kind": "component",
462
+ "id": "data-grid"
463
+ },
464
+ {
465
+ "kind": "component",
466
+ "id": "tree-grid"
467
+ }
468
+ ]
469
+ },
470
+ {
471
+ "intent": "hierarchical item navigation",
472
+ "use": "Tree for one primary item column or TreeGrid for several navigable columns",
473
+ "note": "Choose Accordion when branches contain general disclosure content rather than selectable items.",
474
+ "destinations": [
475
+ {
476
+ "kind": "component",
477
+ "id": "tree"
478
+ },
479
+ {
480
+ "kind": "component",
481
+ "id": "tree-grid"
482
+ },
483
+ {
484
+ "kind": "component",
485
+ "id": "accordion"
486
+ }
487
+ ]
488
+ },
489
+ {
490
+ "intent": "dynamic article stream",
491
+ "use": "Feed",
492
+ "note": "Choose List for a static set and add virtualization only when scale justifies its focus and accessibility cost.",
493
+ "destinations": [
494
+ {
495
+ "kind": "component",
496
+ "id": "feed"
497
+ },
498
+ {
499
+ "kind": "component",
500
+ "id": "list"
501
+ }
502
+ ]
503
+ },
504
+ {
505
+ "intent": "stable media geometry",
506
+ "use": "AspectRatio",
507
+ "note": "Use Image when loading fallback is also required and keep all media semantics on the child.",
508
+ "destinations": [
509
+ {
510
+ "kind": "component",
511
+ "id": "aspect-ratio"
512
+ },
513
+ {
514
+ "kind": "component",
515
+ "id": "image"
516
+ }
517
+ ]
518
+ },
519
+ {
520
+ "intent": "compact identity or contextual status",
521
+ "use": "Avatar for a named entity or Badge for a short contextual count or status",
522
+ "note": "Keep essential identity visible and use Progress for ongoing completion rather than status text.",
523
+ "destinations": [
524
+ {
525
+ "kind": "component",
526
+ "id": "avatar"
527
+ },
528
+ {
529
+ "kind": "component",
530
+ "id": "badge"
531
+ },
532
+ {
533
+ "kind": "component",
534
+ "id": "progress"
535
+ }
536
+ ]
537
+ },
538
+ {
539
+ "intent": "form control labeling",
540
+ "use": "Label for one standalone native control or Field.Label for coordinated control, description, error, and state wiring",
541
+ "note": "Use Fieldset for a group of controls.",
542
+ "destinations": [
543
+ {
544
+ "kind": "component",
545
+ "id": "label"
546
+ },
547
+ {
548
+ "kind": "component",
549
+ "id": "field"
550
+ },
551
+ {
552
+ "kind": "component",
553
+ "id": "fieldset"
554
+ }
555
+ ]
556
+ },
557
+ {
558
+ "intent": "ongoing work status",
559
+ "use": "Progress for determinate or indeterminate completion",
560
+ "note": "Choose the native meter element for a stable measurement, Slider for user adjustment, or Toast for a short nonblocking update.",
561
+ "destinations": [
562
+ {
563
+ "kind": "component",
564
+ "id": "progress"
565
+ },
566
+ {
567
+ "kind": "native-application",
568
+ "id": "native-element"
569
+ },
570
+ {
571
+ "kind": "component",
572
+ "id": "slider"
573
+ },
574
+ {
575
+ "kind": "component",
576
+ "id": "toast"
577
+ }
578
+ ]
579
+ },
580
+ {
581
+ "intent": "assistive-only text",
582
+ "use": "VisuallyHidden",
583
+ "note": "Prefer visible text when it benefits everyone and use aria-hidden rather than VisuallyHidden for decorative content.",
584
+ "destinations": [
585
+ {
586
+ "kind": "component",
587
+ "id": "visually-hidden"
588
+ },
589
+ {
590
+ "kind": "native-application",
591
+ "id": "native-element"
592
+ }
593
+ ]
594
+ },
595
+ {
596
+ "intent": "direction-aware Atom subtree",
597
+ "use": "Direction together with the matching native dir attribute",
598
+ "note": "Provider mirrors Atom behavior but never replaces browser text-direction semantics; prefer a component's local dir prop only for an intentional nested override.",
599
+ "destinations": [
600
+ {
601
+ "kind": "component",
602
+ "id": "direction"
603
+ },
604
+ {
605
+ "kind": "native-application",
606
+ "id": "native-element"
607
+ }
608
+ ]
609
+ },
610
+ {
611
+ "intent": "ordinary blocking task, form, or information surface",
612
+ "use": "Dialog",
613
+ "note": "Choose AlertDialog for an urgent consequential choice, Drawer for a side sheet, or Popover for a compact attached panel.",
614
+ "destinations": [
615
+ {
616
+ "kind": "component",
617
+ "id": "dialog"
618
+ },
619
+ {
620
+ "kind": "component",
621
+ "id": "alert-dialog"
622
+ },
623
+ {
624
+ "kind": "component",
625
+ "id": "drawer"
626
+ },
627
+ {
628
+ "kind": "component",
629
+ "id": "popover"
630
+ }
631
+ ]
632
+ },
633
+ {
634
+ "intent": "custom modal-family primitive foundation",
635
+ "use": "Modal",
636
+ "note": "Application work should prefer the purpose-built modal-family components.",
637
+ "destinations": [
638
+ {
639
+ "kind": "component",
640
+ "id": "modal"
641
+ },
642
+ {
643
+ "kind": "component",
644
+ "id": "dialog"
645
+ },
646
+ {
647
+ "kind": "component",
648
+ "id": "alert-dialog"
649
+ },
650
+ {
651
+ "kind": "component",
652
+ "id": "drawer"
653
+ }
654
+ ]
655
+ },
656
+ {
657
+ "intent": "scrollable viewport with owned scrollbar behavior",
658
+ "use": "ScrollArea",
659
+ "note": "Keep ordinary document scrolling native.",
660
+ "destinations": [
661
+ {
662
+ "kind": "component",
663
+ "id": "scroll-area"
664
+ },
665
+ {
666
+ "kind": "native-application",
667
+ "id": "native-element"
668
+ }
669
+ ]
670
+ },
671
+ {
672
+ "intent": "resilient media loading",
673
+ "use": "Image",
674
+ "note": "Use a native img when loading state and fallback composition are unnecessary.",
675
+ "destinations": [
676
+ {
677
+ "kind": "component",
678
+ "id": "image"
679
+ },
680
+ {
681
+ "kind": "native-application",
682
+ "id": "native-element"
683
+ }
684
+ ]
685
+ },
686
+ {
687
+ "intent": "grouped disclosure sections",
688
+ "use": "Accordion",
689
+ "note": "Choose Collapsible for one independent disclosure and Tabs for one shared switching panel.",
690
+ "destinations": [
691
+ {
692
+ "kind": "component",
693
+ "id": "accordion"
694
+ },
695
+ {
696
+ "kind": "component",
697
+ "id": "collapsible"
698
+ },
699
+ {
700
+ "kind": "component",
701
+ "id": "tabs"
702
+ }
703
+ ]
704
+ },
705
+ {
706
+ "intent": "static ordered or unordered content",
707
+ "use": "List",
708
+ "note": "Choose NavList or an interactive collection primitive when items navigate, select, or activate.",
709
+ "destinations": [
710
+ {
711
+ "kind": "component",
712
+ "id": "list"
713
+ },
714
+ {
715
+ "kind": "component",
716
+ "id": "nav-list"
717
+ }
718
+ ]
719
+ }
720
+ ],
721
+ "rules": [
722
+ {
723
+ "id": "atom-behavior-only",
724
+ "level": "must",
725
+ "statement": "Keep Atom guidance and compositions headless; do not add visual recipes, color, theme, product copy, or application layout policy."
726
+ },
727
+ {
728
+ "id": "atom-native-first",
729
+ "level": "must",
730
+ "statement": "Preserve native semantics and behavior unless Atom explicitly owns the added reusable contract."
731
+ },
732
+ {
733
+ "id": "atom-no-duplicate-behavior",
734
+ "level": "must",
735
+ "statement": "Do not rebuild focus, keyboard, pointer, touch, portal, positioning, or controlled-state behavior already owned by an Atom primitive."
736
+ },
737
+ {
738
+ "id": "atom-brick-boundary",
739
+ "level": "should",
740
+ "statement": "When building with Brick, consume Brick public components and let Brick consume Atom rather than importing both layers directly."
741
+ }
742
+ ],
743
+ "nativeFallback": {
744
+ "check": "Search Atom's manifest, public exports, and related component guides for the required behavior before using a native fallback.",
745
+ "use": "Use the narrowest semantic native element only when no Atom primitive owns the behavior and no reusable state or interaction contract is being recreated.",
746
+ "report": "Record the missing primitive or intentional native choice so repeated gaps can be evaluated by Atom maintainers."
747
+ },
748
+ "validation": [
749
+ "Name the selected semantic and interaction job and its owning layer.",
750
+ "Confirm no visual or application policy entered the Atom composition.",
751
+ "Confirm the rendered elements, accessible names, state, focus, keyboard, pointer, touch, and RTL behavior that apply.",
752
+ "Record any native fallback and the Atom capability searched first."
753
+ ],
754
+ "related": [
755
+ "behavior-composition",
756
+ "button",
757
+ "link",
758
+ "pressable",
759
+ "app-bar",
760
+ "navigation-menu",
761
+ "menu",
762
+ "dropdown-menu",
763
+ "context-menu",
764
+ "menubar",
765
+ "tooltip",
766
+ "hover-card",
767
+ "checkbox-group",
768
+ "radio-group",
769
+ "switch",
770
+ "toggle",
771
+ "toggle-group",
772
+ "slider",
773
+ "rating",
774
+ "listbox",
775
+ "select",
776
+ "multi-select",
777
+ "combobox",
778
+ "number-input",
779
+ "otp-field",
780
+ "password-toggle-field",
781
+ "file-upload",
782
+ "clipboard",
783
+ "toast",
784
+ "swipeable-item",
785
+ "collapsible",
786
+ "table",
787
+ "data-grid",
788
+ "tree",
789
+ "tree-grid",
790
+ "feed",
791
+ "aspect-ratio",
792
+ "avatar",
793
+ "badge",
794
+ "label",
795
+ "progress",
796
+ "visually-hidden",
797
+ "direction",
798
+ "modal",
799
+ "dialog",
800
+ "alert-dialog",
801
+ "drawer",
802
+ "popover",
803
+ "accordion",
804
+ "list"
805
+ ]
806
+ }
807
+ ```