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

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

@@ -0,0 +1,176 @@
+# Dialog
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: dialog
+
+# Dialog agent guide
+
+## Purpose
+
+Present a finished modal task, form, settings flow, or focused information surface while Atom owns focus, dismissal, portal, background-isolation, and scroll-lock behavior.
+
+## Use when
+
+- A user must focus on a temporary blocking task, form, settings flow, or detailed information surface before returning to the underlying application.
+
+## Choose something else when
+
+- The user must make an urgent consequential choice, the surface belongs at a screen edge, or the panel is compact and anchored to a trigger. Use AlertDialog, Drawer, or Popover.
+- The content is an in-page disclosure, a command menu, or passive transient feedback. Use Collapsible or Accordion, Menu, or Toast.
+
+## Required composition
+
+- Compose Dialog.Root with Dialog.Trigger and Dialog.Portal; inside Portal keep Dialog.Overlay and Dialog.Content as siblings. Inside Content, arrange Dialog.Header with Dialog.Title and an optional Dialog.Description, put scrollable task content in Dialog.Body, and place actions and Dialog.Close in Dialog.Footer as the workflow requires.
+- Use Dialog.Branch only for an unavoidable consumer-owned third-party portal that cannot mount inside Content. When a local Appearance scope owns the trigger, portal into that scope or apply the same Appearance to the portalled visual root.
+
+## Rules
+
+- **MUST:** Use Dialog for an ordinary blocking task or information surface; use AlertDialog for an urgent consequential decision and Popover for compact anchored work.
+- **MUST:** Render Overlay and Content as siblings inside Portal; never place Content beneath the aria-hidden Overlay.
+- **MUST:** Give Content an accessible name with one visible Title or an explicit native aria-label or aria-labelledby; add Description only when it supplies useful context.
+- **MUST:** Use Dialog-owned focus containment and restoration, background isolation, scroll locking, Escape handling, direct-target backdrop dismissal, and nested top-layer behavior instead of recreating them.
+- **MUST:** Put long or variable task content in Body so the header and footer remain available while the body owns overflow within the safe viewport bounds.
+- **MUST:** Use Footer justify for simple action distribution and Brick layout components for complex grouping; preserve a clear primary action and a visible close or cancellation path when the workflow requires one.
+- **MUST:** Mount descendant interactive portals inside Content when possible; otherwise wrap only the unavoidable same-document third-party portal owner with Branch.
+- **SHOULD:** Choose sm, md, or lg from the content measure rather than importance, and verify safe-area bounds, Body overflow, footer reflow, zoom, and narrow or short effective viewports.
+- **MUST:** When Portal leaves a local Appearance scope, reproduce that scope on the portalled visual root or target a portal container inside it.
+- **MUST:** Load styles.css or core.css plus dialog.css.
+
+## Common mistakes
+
+- **Avoid:** Nesting Content inside Overlay, hand-building focus or document listeners, or using Dialog for an anchored utility panel. **Instead:** Keep Overlay and Content siblings, rely on Dialog and Atom Modal behavior, and choose Popover for compact anchored work.
+- **Avoid:** Letting long content scroll the whole surface or assuming an unrelated third-party portal is automatically inside the modal. **Instead:** Put overflow in Body and mount the descendant portal inside Content or register its owner with Branch.
+
+## Validation checklist
+
+- Verify trigger semantics, accessible name and optional description, keyboard, pointer, touch, and programmatic initial focus, Tab containment, Close, top-layer Escape, direct-target backdrop dismissal, and focus restoration.
+- Verify controlled state, nested dialogs and every Branch, background isolation, document scroll lock, long Body scrolling, footer reflow, exit presence, zoom, reduced motion, forced colors, and narrow and short viewports.
+- Check light and dark appearance on the actual portalled Content and confirm Dialog CSS plus every composed child component stylesheet is loaded.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/dialog`
+- `@flowstack-ui/atom/agents/modal`
+- `alert-dialog`
+- `drawer`
+- `popover`
+- `button`
+- `appearance`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "dialog",
+  "name": "Dialog",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished modal task, form, settings flow, or focused information surface while Atom owns focus, dismissal, portal, background-isolation, and scroll-lock behavior.",
+  "useWhen": [
+    "A user must focus on a temporary blocking task, form, settings flow, or detailed information surface before returning to the underlying application."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The user must make an urgent consequential choice, the surface belongs at a screen edge, or the panel is compact and anchored to a trigger.",
+      "useInstead": "AlertDialog, Drawer, or Popover"
+    },
+    {
+      "condition": "The content is an in-page disclosure, a command menu, or passive transient feedback.",
+      "useInstead": "Collapsible or Accordion, Menu, or Toast"
+    }
+  ],
+  "composition": [
+    "Compose Dialog.Root with Dialog.Trigger and Dialog.Portal; inside Portal keep Dialog.Overlay and Dialog.Content as siblings. Inside Content, arrange Dialog.Header with Dialog.Title and an optional Dialog.Description, put scrollable task content in Dialog.Body, and place actions and Dialog.Close in Dialog.Footer as the workflow requires.",
+    "Use Dialog.Branch only for an unavoidable consumer-owned third-party portal that cannot mount inside Content. When a local Appearance scope owns the trigger, portal into that scope or apply the same Appearance to the portalled visual root."
+  ],
+  "rules": [
+    {
+      "id": "dialog-modal-task",
+      "level": "must",
+      "statement": "Use Dialog for an ordinary blocking task or information surface; use AlertDialog for an urgent consequential decision and Popover for compact anchored work."
+    },
+    {
+      "id": "dialog-overlay-content-siblings",
+      "level": "must",
+      "statement": "Render Overlay and Content as siblings inside Portal; never place Content beneath the aria-hidden Overlay."
+    },
+    {
+      "id": "dialog-accessible-name",
+      "level": "must",
+      "statement": "Give Content an accessible name with one visible Title or an explicit native aria-label or aria-labelledby; add Description only when it supplies useful context."
+    },
+    {
+      "id": "dialog-atom-behavior",
+      "level": "must",
+      "statement": "Use Dialog-owned focus containment and restoration, background isolation, scroll locking, Escape handling, direct-target backdrop dismissal, and nested top-layer behavior instead of recreating them."
+    },
+    {
+      "id": "dialog-body-scroll",
+      "level": "must",
+      "statement": "Put long or variable task content in Body so the header and footer remain available while the body owns overflow within the safe viewport bounds."
+    },
+    {
+      "id": "dialog-footer-actions",
+      "level": "must",
+      "statement": "Use Footer justify for simple action distribution and Brick layout components for complex grouping; preserve a clear primary action and a visible close or cancellation path when the workflow requires one."
+    },
+    {
+      "id": "dialog-branch-scope",
+      "level": "must",
+      "statement": "Mount descendant interactive portals inside Content when possible; otherwise wrap only the unavoidable same-document third-party portal owner with Branch."
+    },
+    {
+      "id": "dialog-size-responsive",
+      "level": "should",
+      "statement": "Choose sm, md, or lg from the content measure rather than importance, and verify safe-area bounds, Body overflow, footer reflow, zoom, and narrow or short effective viewports."
+    },
+    {
+      "id": "dialog-theme-scope",
+      "level": "must",
+      "statement": "When Portal leaves a local Appearance scope, reproduce that scope on the portalled visual root or target a portal container inside it."
+    },
+    {
+      "id": "dialog-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus dialog.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Nesting Content inside Overlay, hand-building focus or document listeners, or using Dialog for an anchored utility panel.",
+      "correction": "Keep Overlay and Content siblings, rely on Dialog and Atom Modal behavior, and choose Popover for compact anchored work."
+    },
+    {
+      "mistake": "Letting long content scroll the whole surface or assuming an unrelated third-party portal is automatically inside the modal.",
+      "correction": "Put overflow in Body and mount the descendant portal inside Content or register its owner with Branch."
+    }
+  ],
+  "validation": [
+    "Verify trigger semantics, accessible name and optional description, keyboard, pointer, touch, and programmatic initial focus, Tab containment, Close, top-layer Escape, direct-target backdrop dismissal, and focus restoration.",
+    "Verify controlled state, nested dialogs and every Branch, background isolation, document scroll lock, long Body scrolling, footer reflow, exit presence, zoom, reduced motion, forced colors, and narrow and short viewports.",
+    "Check light and dark appearance on the actual portalled Content and confirm Dialog CSS plus every composed child component stylesheet is loaded."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "dialog",
+      "versionPolicy": "installed-exact"
+    },
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "modal",
+      "versionPolicy": "installed-exact"
+    },
+    "alert-dialog",
+    "drawer",
+    "popover",
+    "button",
+    "appearance"
+  ]
+}
+```

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

@@ -0,0 +1,104 @@
+# Divider
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: divider
+
+# Divider agent guide
+
+## Purpose
+
+Render a finished decorative or semantic content boundary with horizontal or vertical visual recipes.
+
+## Use when
+
+- Adjacent content groups need a visible boundary and Atom Divider semantics.
+
+## Choose something else when
+
+- Spacing alone expresses the relationship or the boundary is interactive. Use Stack gap or a dedicated splitter.
+
+## Required composition
+
+- Use Divider inside the layout owner shared by the adjacent complete groups and choose decorative=false only when the separation has meaning.
+
+## Rules
+
+- **MUST:** Choose semantic versus decorative behavior independently from color, thickness, and orientation.
+- **MUST:** Place Divider between complete semantic or interactive groups under one consistent layout owner; do not split a trigger from the content it controls.
+- **MUST:** Load styles.css or core.css plus divider.css.
+
+## Common mistakes
+
+- **Avoid:** Using a bordered div or text glyph for every separator, or placing a Divider inside only part of a repeated group's anatomy. **Instead:** Use Divider when there is a boundary, Stack gap when there is only spacing, and keep repeated boundaries after complete groups under the same owner.
+
+## Validation checklist
+
+- Check orientation, adjacent-group ownership, contrast, forced colors, zoom, and semantics.
+- Confirm it is not focusable and CSS is loaded.
+
+## Related guidance
+
+- `stack`
+- `toolbar`
+- `surface`
+- `nav-list`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "divider",
+  "name": "Divider",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Render a finished decorative or semantic content boundary with horizontal or vertical visual recipes.",
+  "useWhen": [
+    "Adjacent content groups need a visible boundary and Atom Divider semantics."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Spacing alone expresses the relationship or the boundary is interactive.",
+      "useInstead": "Stack gap or a dedicated splitter"
+    }
+  ],
+  "composition": [
+    "Use Divider inside the layout owner shared by the adjacent complete groups and choose decorative=false only when the separation has meaning."
+  ],
+  "rules": [
+    {
+      "id": "divider-meaning",
+      "level": "must",
+      "statement": "Choose semantic versus decorative behavior independently from color, thickness, and orientation."
+    },
+    {
+      "id": "divider-group-owner",
+      "level": "must",
+      "statement": "Place Divider between complete semantic or interactive groups under one consistent layout owner; do not split a trigger from the content it controls."
+    },
+    {
+      "id": "divider-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus divider.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using a bordered div or text glyph for every separator, or placing a Divider inside only part of a repeated group's anatomy.",
+      "correction": "Use Divider when there is a boundary, Stack gap when there is only spacing, and keep repeated boundaries after complete groups under the same owner."
+    }
+  ],
+  "validation": [
+    "Check orientation, adjacent-group ownership, contrast, forced colors, zoom, and semantics.",
+    "Confirm it is not focusable and CSS is loaded."
+  ],
+  "related": [
+    "stack",
+    "toolbar",
+    "surface",
+    "nav-list"
+  ]
+}
+```

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

@@ -0,0 +1,146 @@
+# Drawer
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: drawer
+
+# Drawer agent guide
+
+## Purpose
+
+Present a finished modal side sheet while Atom owns focus, dismissal, portal, scroll-lock, and labeling behavior.
+
+## Use when
+
+- A temporary modal task or navigation panel should enter from a screen edge.
+
+## Choose something else when
+
+- The side region is persistent layout or the overlay has no edge meaning. Use Sidebar or Dialog.
+
+## Required composition
+
+- Compose Trigger and Portal with Overlay and Content; put a header containing Title, Description when useful, and Close inside Content, then use Stack/NavList for its body.
+- Title is a native heading rather than a polymorphic layout host. Use its as prop to choose the heading level; do not pass a multi-element brand or layout through asChild. When the surface intentionally has no visible heading, give Content an explicit accessible name such as aria-label="Mobile navigation".
+
+## Rules
+
+- **MUST:** Use Drawer parts rather than hand-building overlay, focus trap, Escape, outside interaction, or portal behavior.
+- **MUST:** Give Content an accessible name with a concise Title or, when no visible heading is appropriate, an explicit aria-label or aria-labelledby on Content.
+- **MUST:** Choose size and placement from content needs: use xl when content may need the viewport but should shrink when short, and full only when the surface must always fill it.
+- **MUST:** Let top and bottom Drawers grow naturally to their selected size cap; keep long overflow in Drawer.Body instead of forcing a fixed application height.
+- **MUST:** Use Footer justify for simple action distribution, a Brick layout component inside Footer for complex grouping, and Button fullWidth only when the action itself should fill the row.
+- **MUST:** In React Server Components, import the component subpath as import * as Drawer from @flowstack-ui/brick/drawer; use the legacy root-package runtime object only inside a client-owned module.
+- **MUST:** Load styles.css or core.css plus drawer.css.
+
+## Common mistakes
+
+- **Avoid:** Building a mobile menu as an absolutely positioned div or placing Close outside the labeled content hierarchy. **Instead:** Use Drawer anatomy and compose the menu content with Brick navigation and layout components.
+- **Avoid:** Adding use client to an entire Next page only to dereference the legacy Drawer runtime object. **Instead:** Use the RSC-safe module-namespace subpath so only Drawer remains client-owned.
+- **Avoid:** Using asChild on Title or treating a brand lockup as a heading. **Instead:** Keep branding in the visual header and name Content explicitly when there is no concise visible title.
+
+## Validation checklist
+
+- Test labeling, initial focus, focus containment/return, Escape, overlay, Close, scroll lock, content growth and capped Body overflow, touch, reduced motion, narrow screens, and nested portals.
+- Confirm CSS and every composed child component stylesheet are loaded.
+- In a React Server Component consumer, confirm the module-namespace form passes a production prerender without promoting the page to use client.
+
+## Related guidance
+
+- `sidebar`
+- `dialog`
+- `nav-list`
+- `stack`
+- `show`
+- `hide`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "drawer",
+  "name": "Drawer",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished modal side sheet while Atom owns focus, dismissal, portal, scroll-lock, and labeling behavior.",
+  "useWhen": [
+    "A temporary modal task or navigation panel should enter from a screen edge."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The side region is persistent layout or the overlay has no edge meaning.",
+      "useInstead": "Sidebar or Dialog"
+    }
+  ],
+  "composition": [
+    "Compose Trigger and Portal with Overlay and Content; put a header containing Title, Description when useful, and Close inside Content, then use Stack/NavList for its body.",
+    "Title is a native heading rather than a polymorphic layout host. Use its as prop to choose the heading level; do not pass a multi-element brand or layout through asChild. When the surface intentionally has no visible heading, give Content an explicit accessible name such as aria-label=\"Mobile navigation\"."
+  ],
+  "rules": [
+    {
+      "id": "drawer-anatomy",
+      "level": "must",
+      "statement": "Use Drawer parts rather than hand-building overlay, focus trap, Escape, outside interaction, or portal behavior."
+    },
+    {
+      "id": "drawer-accessible-name",
+      "level": "must",
+      "statement": "Give Content an accessible name with a concise Title or, when no visible heading is appropriate, an explicit aria-label or aria-labelledby on Content."
+    },
+    {
+      "id": "drawer-responsive",
+      "level": "must",
+      "statement": "Choose size and placement from content needs: use xl when content may need the viewport but should shrink when short, and full only when the surface must always fill it."
+    },
+    {
+      "id": "drawer-content-growth",
+      "level": "must",
+      "statement": "Let top and bottom Drawers grow naturally to their selected size cap; keep long overflow in Drawer.Body instead of forcing a fixed application height."
+    },
+    {
+      "id": "drawer-footer-layout",
+      "level": "must",
+      "statement": "Use Footer justify for simple action distribution, a Brick layout component inside Footer for complex grouping, and Button fullWidth only when the action itself should fill the row."
+    },
+    {
+      "id": "drawer-rsc-import",
+      "level": "must",
+      "statement": "In React Server Components, import the component subpath as import * as Drawer from @flowstack-ui/brick/drawer; use the legacy root-package runtime object only inside a client-owned module."
+    },
+    {
+      "id": "drawer-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus drawer.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Building a mobile menu as an absolutely positioned div or placing Close outside the labeled content hierarchy.",
+      "correction": "Use Drawer anatomy and compose the menu content with Brick navigation and layout components."
+    },
+    {
+      "mistake": "Adding use client to an entire Next page only to dereference the legacy Drawer runtime object.",
+      "correction": "Use the RSC-safe module-namespace subpath so only Drawer remains client-owned."
+    },
+    {
+      "mistake": "Using asChild on Title or treating a brand lockup as a heading.",
+      "correction": "Keep branding in the visual header and name Content explicitly when there is no concise visible title."
+    }
+  ],
+  "validation": [
+    "Test labeling, initial focus, focus containment/return, Escape, overlay, Close, scroll lock, content growth and capped Body overflow, touch, reduced motion, narrow screens, and nested portals.",
+    "Confirm CSS and every composed child component stylesheet are loaded.",
+    "In a React Server Component consumer, confirm the module-namespace form passes a production prerender without promoting the page to use client."
+  ],
+  "related": [
+    "sidebar",
+    "dialog",
+    "nav-list",
+    "stack",
+    "show",
+    "hide"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/dropdown-menu.txt

@@ -0,0 +1,179 @@
+# DropdownMenu
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: dropdown-menu
+
+# DropdownMenu agent guide
+
+## Purpose
+
+Present a finished compact command or settings menu from a visible button while Atom owns menu semantics, real item focus, keyboard navigation, selection, dismissal, portals, and collision-aware placement.
+
+## Use when
+
+- A visible named button should reveal a short list of commands, independent settings, exclusive settings, secondary destinations, or nested commands.
+
+## Choose something else when
+
+- Commands belong to a contextual gesture, several persistent application command categories, a form value, or ordinary site navigation. Use ContextMenu, Menubar, Select, or NavigationMenu or NavList.
+
+## Required composition
+
+- Compose DropdownMenu.Root with DropdownMenu.Trigger asChild around a finished named Button or IconButton, plus DropdownMenu.Portal and DropdownMenu.Content. Build Content from uniquely valued Item, CheckboxItem, RadioGroup and RadioItem, Group and Label, Separator, and paired Sub, SubTrigger, and SubContent parts; use Leading, ItemLabel, Description, Shortcut, and ItemIndicator for finished rows.
+- For a genuine secondary destination, compose Item asChild around one Brick Link and preserve its href; command rows use onSelect. Reproduce any local Appearance scope on portalled Content and SubContent.
+
+## Rules
+
+- **MUST:** Use DropdownMenu for commands or settings opened by a visible button; use Select for a form value, ContextMenu for contextual invocation, Menubar for persistent command categories, and navigation owners for route lists.
+- **MUST:** Compose Trigger around a visible finished Button or IconButton with a complete accessible name and preserve Atom's button, popup, expanded, controls, disabled, and input-aware opening semantics.
+- **MUST:** Use uniquely valued Item, CheckboxItem, and RadioItem for their matching roles, provide textValue when rendered children are not searchable text, and preserve real focus, typeahead, and disabled-item navigation without activation.
+- **MUST:** Choose closeOnSelect by job: commands normally close while checkbox and radio settings normally remain open; do not close the tree with competing handlers or document listeners.
+- **MUST:** Keep SubTrigger and SubContent inside one Sub and preserve direction-aware cascade keys, hover intent, whole-tree dismissal, and collision-resolved placement instead of inventing responsive drill-in behavior.
+- **MUST:** Compose a genuine destination Item around one Brick Link so href and menuitem semantics share the same interactive owner; do not attach routing to a command-only div.
+- **MUST:** Use Leading, ItemLabel, Description, Shortcut, ItemIndicator, and tone=danger for their documented jobs instead of rebuilding columns, selection glyphs, icon sizing, or destructive emphasis.
+- **SHOULD:** Let Content use its collision-aware available height and native internal scrolling; verify three densities, long labels, zoom, narrow viewports, LTR and RTL, and reachable nested commands without semantic transformation.
+- **MUST:** When Portal leaves a local Appearance scope, reproduce that scope on Content and SubContent or target a portal container inside it.
+- **MUST:** Load styles.css or core.css plus dropdown-menu.css and every composed child component stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Using an unlabeled icon trigger, Popover for menu commands, DropdownMenu for form selection or primary navigation, or custom key and document dismissal handlers. **Instead:** Use a named Button or IconButton, choose the semantic owner, and rely on DropdownMenu and shared Menu behavior.
+- **Avoid:** Nesting a Button inside Item, rebuilding row columns, or treating Shortcut text as registered keyboard behavior. **Instead:** Keep one interactive owner, compose the public row anatomy, and register application shortcuts outside DropdownMenu.
+
+## Validation checklist
+
+- Verify Trigger name and semantics, click, tap, Enter, Space, ArrowDown, and ArrowUp opening, initial real item focus, Home/End, typeahead, controlled and disabled state, Tab exit, Escape, outside dismissal, and focus return.
+- Verify command, destination-link, checkbox mixed, radio, group, indicator, separator, and submenu behavior; unique values and textValue; close policies; modal and parent-modal ownership; and LTR and RTL cascade keys.
+- Verify three densities, Leading geometry, danger meaning, constrained scrolling, collision placement, zoom, narrow viewports, reduced motion, forced colors, light and dark portalled appearance, and complete CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/dropdown-menu`
+- `@flowstack-ui/atom/agents/menu`
+- `context-menu`
+- `menubar`
+- `select`
+- `navigation-menu`
+- `nav-list`
+- `button`
+- `icon-button`
+- `link`
+- `appearance`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "dropdown-menu",
+  "name": "DropdownMenu",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished compact command or settings menu from a visible button while Atom owns menu semantics, real item focus, keyboard navigation, selection, dismissal, portals, and collision-aware placement.",
+  "useWhen": [
+    "A visible named button should reveal a short list of commands, independent settings, exclusive settings, secondary destinations, or nested commands."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Commands belong to a contextual gesture, several persistent application command categories, a form value, or ordinary site navigation.",
+      "useInstead": "ContextMenu, Menubar, Select, or NavigationMenu or NavList"
+    }
+  ],
+  "composition": [
+    "Compose DropdownMenu.Root with DropdownMenu.Trigger asChild around a finished named Button or IconButton, plus DropdownMenu.Portal and DropdownMenu.Content. Build Content from uniquely valued Item, CheckboxItem, RadioGroup and RadioItem, Group and Label, Separator, and paired Sub, SubTrigger, and SubContent parts; use Leading, ItemLabel, Description, Shortcut, and ItemIndicator for finished rows.",
+    "For a genuine secondary destination, compose Item asChild around one Brick Link and preserve its href; command rows use onSelect. Reproduce any local Appearance scope on portalled Content and SubContent."
+  ],
+  "rules": [
+    {
+      "id": "dropdown-menu-selection",
+      "level": "must",
+      "statement": "Use DropdownMenu for commands or settings opened by a visible button; use Select for a form value, ContextMenu for contextual invocation, Menubar for persistent command categories, and navigation owners for route lists."
+    },
+    {
+      "id": "dropdown-menu-trigger",
+      "level": "must",
+      "statement": "Compose Trigger around a visible finished Button or IconButton with a complete accessible name and preserve Atom's button, popup, expanded, controls, disabled, and input-aware opening semantics."
+    },
+    {
+      "id": "dropdown-menu-item-model",
+      "level": "must",
+      "statement": "Use uniquely valued Item, CheckboxItem, and RadioItem for their matching roles, provide textValue when rendered children are not searchable text, and preserve real focus, typeahead, and disabled-item navigation without activation."
+    },
+    {
+      "id": "dropdown-menu-selection-close",
+      "level": "must",
+      "statement": "Choose closeOnSelect by job: commands normally close while checkbox and radio settings normally remain open; do not close the tree with competing handlers or document listeners."
+    },
+    {
+      "id": "dropdown-menu-submenu",
+      "level": "must",
+      "statement": "Keep SubTrigger and SubContent inside one Sub and preserve direction-aware cascade keys, hover intent, whole-tree dismissal, and collision-resolved placement instead of inventing responsive drill-in behavior."
+    },
+    {
+      "id": "dropdown-menu-destination",
+      "level": "must",
+      "statement": "Compose a genuine destination Item around one Brick Link so href and menuitem semantics share the same interactive owner; do not attach routing to a command-only div."
+    },
+    {
+      "id": "dropdown-menu-row-anatomy",
+      "level": "must",
+      "statement": "Use Leading, ItemLabel, Description, Shortcut, ItemIndicator, and tone=danger for their documented jobs instead of rebuilding columns, selection glyphs, icon sizing, or destructive emphasis."
+    },
+    {
+      "id": "dropdown-menu-responsive",
+      "level": "should",
+      "statement": "Let Content use its collision-aware available height and native internal scrolling; verify three densities, long labels, zoom, narrow viewports, LTR and RTL, and reachable nested commands without semantic transformation."
+    },
+    {
+      "id": "dropdown-menu-theme-scope",
+      "level": "must",
+      "statement": "When Portal leaves a local Appearance scope, reproduce that scope on Content and SubContent or target a portal container inside it."
+    },
+    {
+      "id": "dropdown-menu-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus dropdown-menu.css and every composed child component stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using an unlabeled icon trigger, Popover for menu commands, DropdownMenu for form selection or primary navigation, or custom key and document dismissal handlers.",
+      "correction": "Use a named Button or IconButton, choose the semantic owner, and rely on DropdownMenu and shared Menu behavior."
+    },
+    {
+      "mistake": "Nesting a Button inside Item, rebuilding row columns, or treating Shortcut text as registered keyboard behavior.",
+      "correction": "Keep one interactive owner, compose the public row anatomy, and register application shortcuts outside DropdownMenu."
+    }
+  ],
+  "validation": [
+    "Verify Trigger name and semantics, click, tap, Enter, Space, ArrowDown, and ArrowUp opening, initial real item focus, Home/End, typeahead, controlled and disabled state, Tab exit, Escape, outside dismissal, and focus return.",
+    "Verify command, destination-link, checkbox mixed, radio, group, indicator, separator, and submenu behavior; unique values and textValue; close policies; modal and parent-modal ownership; and LTR and RTL cascade keys.",
+    "Verify three densities, Leading geometry, danger meaning, constrained scrolling, collision placement, zoom, narrow viewports, reduced motion, forced colors, light and dark portalled appearance, and complete CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "dropdown-menu",
+      "versionPolicy": "installed-exact"
+    },
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "menu",
+      "versionPolicy": "installed-exact"
+    },
+    "context-menu",
+    "menubar",
+    "select",
+    "navigation-menu",
+    "nav-list",
+    "button",
+    "icon-button",
+    "link",
+    "appearance"
+  ]
+}
+```