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

package/public/packages/brick/0.1.11/guides/layer-selection.txt

@@ -0,0 +1,1437 @@
+# Brick layer selection
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: guide
+ID: layer-selection
+
+# Brick layer selection
+
+## Purpose
+
+Choose the correct FLOWSTACK layer and require Brick-first composition when building a finished interface with Brick.
+
+## Decision order
+
+1. Describe the interface job and semantic relationship before choosing markup or appearance.
+2. Search Brick's package guides and component manifest for a component that owns the job.
+3. Use Brick public components for finished interface structure, controls, navigation, content, media, responsive visibility, and visual surfaces.
+4. Let Brick consume Atom; do not import Atom directly in an ordinary Brick application.
+5. Keep purposeful sections in Blocks, page arrangements in Blueprints, theme values in a Theme, and business behavior in the application.
+
+## Selection map
+
+- **headings, paragraphs, captions, and eyebrows:** use Heading, Paragraph, Caption, or Eyebrow. Give Heading an explicit semantic level and choose its visual variant independently.
+- **other text with Brick typography:** use Text. Choose the semantic rendered element through its public API and author the intended letter case in content.
+- **extended quotation with visible attribution:** use native blockquote with Brick text content. Keep attribution outside blockquote; when the quotation and attribution form one self-contained unit, use native figure with direct blockquote and figcaption children. Cite names a referenced work, not the person quoted.
+- **one-dimensional alignment:** use Stack, HStack, or VStack. Use Grid for two-dimensional track relationships.
+- **bounded page width:** use Container. Use Surface or Card when the region also needs a visual boundary.
+- **top application or page bar:** use AppBar. Compose navigation and action components inside its sections.
+- **responsive presence:** use Show or Hide. Use CSS media visibility rather than rendering two JavaScript-controlled trees.
+- **image with resilient loading:** use Image. Use an adapter only when a framework image optimizer provides a measured capability Brick lacks.
+- **stable media or embed geometry before its content loads:** use AspectRatio. Choose Image when the asset owns resilient loading, Surface for a general visual boundary, and Skeleton for a temporary loading placeholder.
+- **preserved multi-line technical source:** use Code Block. Keep syntax tokenization in a consumer adapter and pass the exact plain source separately for copy behavior.
+- **navigation destination:** use Link or Button with href. Use Link for ordinary navigation and Button only for an emphasized destination.
+- **grouped disclosure sections:** use Accordion. Choose Collapsible for one independent disclosure and Tabs for one shared switching panel.
+- **ordinary blocking task, form, settings flow, or focused information:** use Dialog. Choose AlertDialog for one urgent consequential decision and Drawer when the temporary task belongs at a screen edge.
+- **urgent or consequential decision that requires an explicit response:** use AlertDialog. Keep a safe Cancel before Action; choose Dialog for ordinary forms and information.
+- **compact anchored interactive panel:** use Popover. Choose Tooltip or HoverCard for noninteractive context, DropdownMenu for commands, Select or Combobox for option selection, and Dialog for a larger blocking task.
+- **commands or settings opened from one visible button:** use DropdownMenu. Choose ContextMenu for contextual invocation, Menubar for persistent application command categories, Select for a form value, and NavigationMenu or NavList for navigation.
+- **target-specific commands invoked by secondary click, keyboard context action, or supported long press:** use ContextMenu. Keep a visible Button or DropdownMenu route to every important command.
+- **persistent desktop-like application command categories:** use Menubar. Choose DropdownMenu for one temporary command menu, NavigationMenu or NavList for routes, Toolbar for immediately executable controls, and Drawer only as an application-selected mobile alternative.
+- **redundant passive preview for a genuine link or focusable subject:** use HoverCard. Choose Tooltip for one short hint, Popover for interaction, Dialog for a larger task, and visible Text when the information is essential.
+- **brief supplemental description for an already named control:** use Tooltip. Choose HoverCard for a richer passive preview, Popover for interaction, and visible Text for essential information.
+- **exactly one form choice from a short visible set:** use RadioGroup. Choose CheckboxGroup for independent choices, Select for a compact longer list, and ToggleGroup for pressed commands.
+- **any number of related form choices:** use CheckboxGroup. Choose Checkbox for one independent choice, RadioGroup for exactly one choice, and ToggleGroup for pressed commands.
+- **immediately applied on or off setting:** use Switch. Choose Checkbox for a deferred form answer and Toggle for a persistent pressed command.
+- **one command with persistent pressed state:** use Toggle. Choose Button for a momentary action, Switch for an immediate setting, Checkbox for a submitted choice, and ToggleGroup for related pressed commands.
+- **related keyboard-navigable pressed commands:** use ToggleGroup. Choose Toggle for one command, RadioGroup or CheckboxGroup for form choices, Switch for immediate settings, and Tabs for switching panels.
+- **exact numeric value with typing and step actions:** use NumberInput. Choose Slider for approximate spatial adjustment, Input for numeric-looking identifiers, Select or RadioGroup for a small fixed set, and Progress for read-only completion.
+- **one predefined form value from a compact collapsed collection:** use Select. Choose RadioGroup for a short visible set, Combobox for editable filtering, MultiSelect for several values, DropdownMenu for commands, and Link for navigation.
+- **several predefined form values from a compact collapsed collection:** use MultiSelect. Choose CheckboxGroup for a short visible set, Select for one value, and Combobox only when its single-value editable model fits; record a Brick gap for unsupported tag creation or other specialized multi-value behavior.
+- **editable filtering and one committed option value:** use Combobox. Choose Input when any text is valid without options, Select for a compact noneditable list, RadioGroup for a short visible set, MultiSelect for several predefined values, and DropdownMenu for commands.
+- **persistently visible composite option collection:** use record a Brick gap before application-owned implementation. Brick has no public owner for this job. Do not import Atom directly; first reconsider RadioGroup or CheckboxGroup for visible form choices, Select or MultiSelect for collapsed choices, and Combobox for editable filtering.
+- **short one-time verification, recovery, or pairing code:** use OTPField. Choose PasswordToggleField for a reusable secret, NumberInput for a quantity, and Input for an ordinary identifier or variable-length value.
+- **password entry with an allowed reveal action:** use PasswordToggleField. Choose Input with type=password when reveal is forbidden or unwanted and OTPField for a one-time code.
+- **local file picking, optional drop, review, and removal before application processing:** use FileUpload. Choose Input for a textual path or URL, Progress for transfer progress, Toast for a transient result, and Image for a rendered asset; keep server validation and upload transport in the application.
+- **short non-blocking application outcome or process update:** use Toast. Choose Field or Form feedback for validation, Progress for numeric completion, AlertDialog for a required response, and persistent application content for essential or durable information.
+- **touch-enhanced quick actions for a list-like row with an obvious click alternative:** use SwipeableItem. Choose DropdownMenu for a larger command set, Button or IconButton for continuously visible actions, and Link when the row navigates.
+- **one independent in-flow disclosure region:** use Collapsible. Choose Accordion for coordinated peer sections, Dialog or Drawer for a modal task, Popover for an anchored layer, and Show or Hide for responsive presence.
+- **one-column hierarchical navigation and optional selection:** use Tree. Choose TreeGrid for hierarchical rows with navigable columns, Accordion or Collapsible for arbitrary disclosure content, DataGrid for flat interactive tabular data, and List for static hierarchy.
+- **hierarchical rows with several navigable columns:** use TreeGrid. Choose Tree for one primary hierarchy column, DataGrid for flat interactive rows, Table for read-oriented tabular relationships, and an application-owned data tool for editing or independent cell controls.
+- **flat tabular data with composite cell navigation or row selection:** use DataGrid. Choose Table for read-oriented comparison, TreeGrid for hierarchical rows, and an application-owned data tool for editing, column management, or an enterprise data engine.
+- **read-oriented row and column comparison:** use Table. Choose DataGrid for composite cell navigation or row selection, TreeGrid for hierarchical interactive rows, and List when meaningful column relationships are absent.
+- **changing stream of focusable articles with article-to-article keyboard movement:** use Feed. Choose List for a static sequence, Table or DataGrid for tabular relationships, Tree for hierarchy, and Stack or Grid for purely visual arrangement.
+- **linear read-only task completion or indeterminate work:** use Progress. Choose ProgressCircle when compact circular geometry is important, Slider for editable values, Toast for a transient outcome, and Skeleton for unknown content loading.
+- **compact circular read-only task completion or indeterminate work:** use ProgressCircle. Choose Progress for linear completion, Slider for editable values, and Skeleton for unknown content loading.
+- **visual count or presence dot over one owning element:** use NotificationBadge. Choose Badge for an in-flow passive label or count, Status for a named state, Button for an actionable count, and visible Text when the value must be announced or understood without the owner; NotificationBadge does not announce changes.
+- **compact identity for a named person, organization, or entity:** use Avatar. Choose Image for a larger editorial portrait and NotificationBadge only when the owning Avatar needs a separate visual count or presence indicator.
+- **short passive in-flow label, category, status, or count:** use Badge. Choose NotificationBadge for an overlaid count or dot, Status for richer named state semantics, and Button when the label is actionable.
+- **editable, selectable, or submitted opaque hexadecimal color:** use ColorPicker. Choose ColorSwatch for a passive preview; richer alpha, gradient, channel, eyedropper, and color-space editing remains an Atom-first gap.
+- **passive preview of one color or a compact color mix:** use ColorSwatch. Choose ColorPicker when the user must edit, select, or submit the value; keep interaction on a semantic owner.
+- **short assistive-only equivalent for meaning already conveyed visually:** use VisuallyHidden. Choose visible Text for essential instructions, state, errors, or announcements, and keep an IconButton or Button itself visible while placing the hidden equivalent inside it.
+- **approximate numeric value or ordered range through spatial manipulation:** use Slider. Choose NumberInput for exact entry, Progress for read-only completion, and Rating for a short ordered score.
+- **short ordered score input or recognizable passive score aggregate:** use Rating. Choose Slider for a general numeric setting and RadioGroup when choices have distinct categorical meanings.
+- **ordered or unordered content:** use List. Choose NavList, an interactive collection, Table, or DataGrid when rows navigate, select, activate, or expose data relationships.
+
+## Rules
+
+- **MUST:** Use an existing Brick component when it owns the interface job instead of recreating it with native elements and application CSS.
+- **MUST:** Do not import @flowstack-ui/atom directly in an application that has selected Brick; report a Brick gap if the finished component is missing.
+- **MUST:** Load styles.css once, or core.css once plus every rendered component's modular stylesheet; never mix the two delivery modes.
+- **MUST:** Choose components by semantic and interaction intent rather than by visual resemblance.
+- **MUST:** After selecting a Brick owner, follow interface-composition's ordered prop, semantic-token, component-token, public-part, and stable-hook customization contract.
+- **SHOULD:** Record intentional native or framework fallbacks with the searched Brick component and missing capability.
+
+## Native fallback
+
+1. Search the Brick manifest, package guide selection map, component docs, and public exports before writing native markup or replacement CSS.
+2. Use semantic native HTML only for document or application structure Brick does not own, or through a documented adapter when a framework supplies a required measured capability.
+3. Record the fallback as a Brick gap, adapter need, higher-layer composition, or intentional application-owned element before continuing.
+
+## Validation checklist
+
+- List every native layout, text, image, navigation, and interactive element and name why Brick does not own it; list every direct Brick stable-hook declaration and its completed customization gap report.
+- Confirm there are no direct @flowstack-ui/atom imports.
+- Confirm every rendered Brick component has its required modular CSS or the complete stylesheet is loaded once.
+- Classify each repeated composition as component, theme, Block, Blueprint, adapter, or application ownership.
+
+## Related guidance
+
+- `interface-composition`
+- `app-bar`
+- `container`
+- `stack`
+- `grid`
+- `text`
+- `image`
+- `aspect-ratio`
+- `code-block`
+- `show`
+- `hide`
+- `accordion`
+- `collapsible`
+- `list`
+- `feed`
+- `tree`
+- `tree-grid`
+- `table`
+- `data-grid`
+- `dialog`
+- `alert-dialog`
+- `popover`
+- `dropdown-menu`
+- `context-menu`
+- `menubar`
+- `hover-card`
+- `tooltip`
+- `radio-group`
+- `checkbox-group`
+- `switch`
+- `toggle`
+- `toggle-group`
+- `number-input`
+- `select`
+- `multi-select`
+- `combobox`
+- `otp-field`
+- `password-toggle-field`
+- `file-upload`
+- `toast`
+- `swipeable-item`
+- `progress`
+- `progress-circle`
+- `notification-badge`
+- `avatar`
+- `badge`
+- `color-picker`
+- `color-swatch`
+- `visually-hidden`
+- `slider`
+- `rating`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-guide.v1",
+  "id": "layer-selection",
+  "name": "Brick layer selection",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "guide",
+  "purpose": "Choose the correct FLOWSTACK layer and require Brick-first composition when building a finished interface with Brick.",
+  "decisionOrder": [
+    "Describe the interface job and semantic relationship before choosing markup or appearance.",
+    "Search Brick's package guides and component manifest for a component that owns the job.",
+    "Use Brick public components for finished interface structure, controls, navigation, content, media, responsive visibility, and visual surfaces.",
+    "Let Brick consume Atom; do not import Atom directly in an ordinary Brick application.",
+    "Keep purposeful sections in Blocks, page arrangements in Blueprints, theme values in a Theme, and business behavior in the application."
+  ],
+  "selection": [
+    {
+      "intent": "headings, paragraphs, captions, and eyebrows",
+      "use": "Heading, Paragraph, Caption, or Eyebrow",
+      "note": "Give Heading an explicit semantic level and choose its visual variant independently.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "text"
+        }
+      ]
+    },
+    {
+      "intent": "other text with Brick typography",
+      "use": "Text",
+      "note": "Choose the semantic rendered element through its public API and author the intended letter case in content.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "text"
+        }
+      ]
+    },
+    {
+      "intent": "extended quotation with visible attribution",
+      "use": "native blockquote with Brick text content",
+      "note": "Keep attribution outside blockquote; when the quotation and attribution form one self-contained unit, use native figure with direct blockquote and figcaption children. Cite names a referenced work, not the person quoted.",
+      "destinations": [
+        {
+          "kind": "native-application",
+          "id": "native-quotation"
+        },
+        {
+          "kind": "component",
+          "id": "text"
+        }
+      ]
+    },
+    {
+      "intent": "one-dimensional alignment",
+      "use": "Stack, HStack, or VStack",
+      "note": "Use Grid for two-dimensional track relationships.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "stack"
+        },
+        {
+          "kind": "component",
+          "id": "grid"
+        }
+      ]
+    },
+    {
+      "intent": "bounded page width",
+      "use": "Container",
+      "note": "Use Surface or Card when the region also needs a visual boundary.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "container"
+        },
+        {
+          "kind": "component",
+          "id": "surface"
+        },
+        {
+          "kind": "component",
+          "id": "card"
+        }
+      ]
+    },
+    {
+      "intent": "top application or page bar",
+      "use": "AppBar",
+      "note": "Compose navigation and action components inside its sections.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "app-bar"
+        }
+      ]
+    },
+    {
+      "intent": "responsive presence",
+      "use": "Show or Hide",
+      "note": "Use CSS media visibility rather than rendering two JavaScript-controlled trees.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "show"
+        },
+        {
+          "kind": "component",
+          "id": "hide"
+        }
+      ]
+    },
+    {
+      "intent": "image with resilient loading",
+      "use": "Image",
+      "note": "Use an adapter only when a framework image optimizer provides a measured capability Brick lacks.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "image"
+        }
+      ]
+    },
+    {
+      "intent": "stable media or embed geometry before its content loads",
+      "use": "AspectRatio",
+      "note": "Choose Image when the asset owns resilient loading, Surface for a general visual boundary, and Skeleton for a temporary loading placeholder.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "aspect-ratio"
+        },
+        {
+          "kind": "component",
+          "id": "image"
+        },
+        {
+          "kind": "component",
+          "id": "surface"
+        },
+        {
+          "kind": "component",
+          "id": "skeleton"
+        }
+      ]
+    },
+    {
+      "intent": "preserved multi-line technical source",
+      "use": "Code Block",
+      "note": "Keep syntax tokenization in a consumer adapter and pass the exact plain source separately for copy behavior.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "code-block"
+        }
+      ]
+    },
+    {
+      "intent": "navigation destination",
+      "use": "Link or Button with href",
+      "note": "Use Link for ordinary navigation and Button only for an emphasized destination.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "link"
+        },
+        {
+          "kind": "component",
+          "id": "button"
+        }
+      ]
+    },
+    {
+      "intent": "grouped disclosure sections",
+      "use": "Accordion",
+      "note": "Choose Collapsible for one independent disclosure and Tabs for one shared switching panel.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "accordion"
+        },
+        {
+          "kind": "component",
+          "id": "collapsible"
+        },
+        {
+          "kind": "component",
+          "id": "tabs"
+        }
+      ]
+    },
+    {
+      "intent": "ordinary blocking task, form, settings flow, or focused information",
+      "use": "Dialog",
+      "note": "Choose AlertDialog for one urgent consequential decision and Drawer when the temporary task belongs at a screen edge.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "dialog"
+        },
+        {
+          "kind": "component",
+          "id": "alert-dialog"
+        },
+        {
+          "kind": "component",
+          "id": "drawer"
+        }
+      ]
+    },
+    {
+      "intent": "urgent or consequential decision that requires an explicit response",
+      "use": "AlertDialog",
+      "note": "Keep a safe Cancel before Action; choose Dialog for ordinary forms and information.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "alert-dialog"
+        },
+        {
+          "kind": "component",
+          "id": "dialog"
+        }
+      ]
+    },
+    {
+      "intent": "compact anchored interactive panel",
+      "use": "Popover",
+      "note": "Choose Tooltip or HoverCard for noninteractive context, DropdownMenu for commands, Select or Combobox for option selection, and Dialog for a larger blocking task.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "popover"
+        },
+        {
+          "kind": "component",
+          "id": "tooltip"
+        },
+        {
+          "kind": "component",
+          "id": "hover-card"
+        },
+        {
+          "kind": "component",
+          "id": "dropdown-menu"
+        },
+        {
+          "kind": "component",
+          "id": "select"
+        },
+        {
+          "kind": "component",
+          "id": "combobox"
+        },
+        {
+          "kind": "component",
+          "id": "dialog"
+        }
+      ]
+    },
+    {
+      "intent": "commands or settings opened from one visible button",
+      "use": "DropdownMenu",
+      "note": "Choose ContextMenu for contextual invocation, Menubar for persistent application command categories, Select for a form value, and NavigationMenu or NavList for navigation.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "dropdown-menu"
+        },
+        {
+          "kind": "component",
+          "id": "context-menu"
+        },
+        {
+          "kind": "component",
+          "id": "menubar"
+        },
+        {
+          "kind": "component",
+          "id": "select"
+        },
+        {
+          "kind": "component",
+          "id": "navigation-menu"
+        },
+        {
+          "kind": "component",
+          "id": "nav-list"
+        }
+      ]
+    },
+    {
+      "intent": "target-specific commands invoked by secondary click, keyboard context action, or supported long press",
+      "use": "ContextMenu",
+      "note": "Keep a visible Button or DropdownMenu route to every important command.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "context-menu"
+        },
+        {
+          "kind": "component",
+          "id": "button"
+        },
+        {
+          "kind": "component",
+          "id": "dropdown-menu"
+        }
+      ]
+    },
+    {
+      "intent": "persistent desktop-like application command categories",
+      "use": "Menubar",
+      "note": "Choose DropdownMenu for one temporary command menu, NavigationMenu or NavList for routes, Toolbar for immediately executable controls, and Drawer only as an application-selected mobile alternative.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "menubar"
+        },
+        {
+          "kind": "component",
+          "id": "dropdown-menu"
+        },
+        {
+          "kind": "component",
+          "id": "navigation-menu"
+        },
+        {
+          "kind": "component",
+          "id": "nav-list"
+        },
+        {
+          "kind": "component",
+          "id": "toolbar"
+        },
+        {
+          "kind": "component",
+          "id": "drawer"
+        }
+      ]
+    },
+    {
+      "intent": "redundant passive preview for a genuine link or focusable subject",
+      "use": "HoverCard",
+      "note": "Choose Tooltip for one short hint, Popover for interaction, Dialog for a larger task, and visible Text when the information is essential.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "hover-card"
+        },
+        {
+          "kind": "component",
+          "id": "tooltip"
+        },
+        {
+          "kind": "component",
+          "id": "popover"
+        },
+        {
+          "kind": "component",
+          "id": "dialog"
+        },
+        {
+          "kind": "component",
+          "id": "text"
+        }
+      ]
+    },
+    {
+      "intent": "brief supplemental description for an already named control",
+      "use": "Tooltip",
+      "note": "Choose HoverCard for a richer passive preview, Popover for interaction, and visible Text for essential information.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "tooltip"
+        },
+        {
+          "kind": "component",
+          "id": "hover-card"
+        },
+        {
+          "kind": "component",
+          "id": "popover"
+        },
+        {
+          "kind": "component",
+          "id": "text"
+        }
+      ]
+    },
+    {
+      "intent": "exactly one form choice from a short visible set",
+      "use": "RadioGroup",
+      "note": "Choose CheckboxGroup for independent choices, Select for a compact longer list, and ToggleGroup for pressed commands.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "radio-group"
+        },
+        {
+          "kind": "component",
+          "id": "checkbox-group"
+        },
+        {
+          "kind": "component",
+          "id": "select"
+        },
+        {
+          "kind": "component",
+          "id": "toggle-group"
+        }
+      ]
+    },
+    {
+      "intent": "any number of related form choices",
+      "use": "CheckboxGroup",
+      "note": "Choose Checkbox for one independent choice, RadioGroup for exactly one choice, and ToggleGroup for pressed commands.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "checkbox-group"
+        },
+        {
+          "kind": "component",
+          "id": "checkbox"
+        },
+        {
+          "kind": "component",
+          "id": "radio-group"
+        },
+        {
+          "kind": "component",
+          "id": "toggle-group"
+        }
+      ]
+    },
+    {
+      "intent": "immediately applied on or off setting",
+      "use": "Switch",
+      "note": "Choose Checkbox for a deferred form answer and Toggle for a persistent pressed command.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "switch"
+        },
+        {
+          "kind": "component",
+          "id": "checkbox"
+        },
+        {
+          "kind": "component",
+          "id": "toggle"
+        }
+      ]
+    },
+    {
+      "intent": "one command with persistent pressed state",
+      "use": "Toggle",
+      "note": "Choose Button for a momentary action, Switch for an immediate setting, Checkbox for a submitted choice, and ToggleGroup for related pressed commands.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "toggle"
+        },
+        {
+          "kind": "component",
+          "id": "button"
+        },
+        {
+          "kind": "component",
+          "id": "switch"
+        },
+        {
+          "kind": "component",
+          "id": "checkbox"
+        },
+        {
+          "kind": "component",
+          "id": "toggle-group"
+        }
+      ]
+    },
+    {
+      "intent": "related keyboard-navigable pressed commands",
+      "use": "ToggleGroup",
+      "note": "Choose Toggle for one command, RadioGroup or CheckboxGroup for form choices, Switch for immediate settings, and Tabs for switching panels.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "toggle-group"
+        },
+        {
+          "kind": "component",
+          "id": "toggle"
+        },
+        {
+          "kind": "component",
+          "id": "radio-group"
+        },
+        {
+          "kind": "component",
+          "id": "checkbox-group"
+        },
+        {
+          "kind": "component",
+          "id": "switch"
+        },
+        {
+          "kind": "component",
+          "id": "tabs"
+        }
+      ]
+    },
+    {
+      "intent": "exact numeric value with typing and step actions",
+      "use": "NumberInput",
+      "note": "Choose Slider for approximate spatial adjustment, Input for numeric-looking identifiers, Select or RadioGroup for a small fixed set, and Progress for read-only completion.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "number-input"
+        },
+        {
+          "kind": "component",
+          "id": "slider"
+        },
+        {
+          "kind": "component",
+          "id": "input"
+        },
+        {
+          "kind": "component",
+          "id": "select"
+        },
+        {
+          "kind": "component",
+          "id": "radio-group"
+        },
+        {
+          "kind": "component",
+          "id": "progress"
+        }
+      ]
+    },
+    {
+      "intent": "one predefined form value from a compact collapsed collection",
+      "use": "Select",
+      "note": "Choose RadioGroup for a short visible set, Combobox for editable filtering, MultiSelect for several values, DropdownMenu for commands, and Link for navigation.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "select"
+        },
+        {
+          "kind": "component",
+          "id": "radio-group"
+        },
+        {
+          "kind": "component",
+          "id": "combobox"
+        },
+        {
+          "kind": "component",
+          "id": "multi-select"
+        },
+        {
+          "kind": "component",
+          "id": "dropdown-menu"
+        },
+        {
+          "kind": "component",
+          "id": "link"
+        }
+      ]
+    },
+    {
+      "intent": "several predefined form values from a compact collapsed collection",
+      "use": "MultiSelect",
+      "note": "Choose CheckboxGroup for a short visible set, Select for one value, and Combobox only when its single-value editable model fits; record a Brick gap for unsupported tag creation or other specialized multi-value behavior.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "multi-select"
+        },
+        {
+          "kind": "component",
+          "id": "checkbox-group"
+        },
+        {
+          "kind": "component",
+          "id": "select"
+        },
+        {
+          "kind": "component",
+          "id": "combobox"
+        }
+      ]
+    },
+    {
+      "intent": "editable filtering and one committed option value",
+      "use": "Combobox",
+      "note": "Choose Input when any text is valid without options, Select for a compact noneditable list, RadioGroup for a short visible set, MultiSelect for several predefined values, and DropdownMenu for commands.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "combobox"
+        },
+        {
+          "kind": "component",
+          "id": "input"
+        },
+        {
+          "kind": "component",
+          "id": "select"
+        },
+        {
+          "kind": "component",
+          "id": "radio-group"
+        },
+        {
+          "kind": "component",
+          "id": "multi-select"
+        },
+        {
+          "kind": "component",
+          "id": "dropdown-menu"
+        }
+      ]
+    },
+    {
+      "intent": "persistently visible composite option collection",
+      "use": "record a Brick gap before application-owned implementation",
+      "note": "Brick has no public owner for this job. Do not import Atom directly; first reconsider RadioGroup or CheckboxGroup for visible form choices, Select or MultiSelect for collapsed choices, and Combobox for editable filtering.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "radio-group"
+        },
+        {
+          "kind": "component",
+          "id": "checkbox-group"
+        },
+        {
+          "kind": "component",
+          "id": "select"
+        },
+        {
+          "kind": "component",
+          "id": "multi-select"
+        },
+        {
+          "kind": "component",
+          "id": "combobox"
+        }
+      ]
+    },
+    {
+      "intent": "short one-time verification, recovery, or pairing code",
+      "use": "OTPField",
+      "note": "Choose PasswordToggleField for a reusable secret, NumberInput for a quantity, and Input for an ordinary identifier or variable-length value.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "otp-field"
+        },
+        {
+          "kind": "component",
+          "id": "password-toggle-field"
+        },
+        {
+          "kind": "component",
+          "id": "number-input"
+        },
+        {
+          "kind": "component",
+          "id": "input"
+        }
+      ]
+    },
+    {
+      "intent": "password entry with an allowed reveal action",
+      "use": "PasswordToggleField",
+      "note": "Choose Input with type=password when reveal is forbidden or unwanted and OTPField for a one-time code.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "password-toggle-field"
+        },
+        {
+          "kind": "component",
+          "id": "input"
+        },
+        {
+          "kind": "component",
+          "id": "otp-field"
+        }
+      ]
+    },
+    {
+      "intent": "local file picking, optional drop, review, and removal before application processing",
+      "use": "FileUpload",
+      "note": "Choose Input for a textual path or URL, Progress for transfer progress, Toast for a transient result, and Image for a rendered asset; keep server validation and upload transport in the application.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "file-upload"
+        },
+        {
+          "kind": "component",
+          "id": "input"
+        },
+        {
+          "kind": "component",
+          "id": "progress"
+        },
+        {
+          "kind": "component",
+          "id": "toast"
+        },
+        {
+          "kind": "component",
+          "id": "image"
+        }
+      ]
+    },
+    {
+      "intent": "short non-blocking application outcome or process update",
+      "use": "Toast",
+      "note": "Choose Field or Form feedback for validation, Progress for numeric completion, AlertDialog for a required response, and persistent application content for essential or durable information.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "toast"
+        },
+        {
+          "kind": "component",
+          "id": "field"
+        },
+        {
+          "kind": "component",
+          "id": "form"
+        },
+        {
+          "kind": "component",
+          "id": "progress"
+        },
+        {
+          "kind": "component",
+          "id": "alert-dialog"
+        }
+      ]
+    },
+    {
+      "intent": "touch-enhanced quick actions for a list-like row with an obvious click alternative",
+      "use": "SwipeableItem",
+      "note": "Choose DropdownMenu for a larger command set, Button or IconButton for continuously visible actions, and Link when the row navigates.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "swipeable-item"
+        },
+        {
+          "kind": "component",
+          "id": "dropdown-menu"
+        },
+        {
+          "kind": "component",
+          "id": "button"
+        },
+        {
+          "kind": "component",
+          "id": "icon-button"
+        },
+        {
+          "kind": "component",
+          "id": "link"
+        }
+      ]
+    },
+    {
+      "intent": "one independent in-flow disclosure region",
+      "use": "Collapsible",
+      "note": "Choose Accordion for coordinated peer sections, Dialog or Drawer for a modal task, Popover for an anchored layer, and Show or Hide for responsive presence.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "collapsible"
+        },
+        {
+          "kind": "component",
+          "id": "accordion"
+        },
+        {
+          "kind": "component",
+          "id": "dialog"
+        },
+        {
+          "kind": "component",
+          "id": "drawer"
+        },
+        {
+          "kind": "component",
+          "id": "popover"
+        },
+        {
+          "kind": "component",
+          "id": "show"
+        },
+        {
+          "kind": "component",
+          "id": "hide"
+        }
+      ]
+    },
+    {
+      "intent": "one-column hierarchical navigation and optional selection",
+      "use": "Tree",
+      "note": "Choose TreeGrid for hierarchical rows with navigable columns, Accordion or Collapsible for arbitrary disclosure content, DataGrid for flat interactive tabular data, and List for static hierarchy.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "tree"
+        },
+        {
+          "kind": "component",
+          "id": "tree-grid"
+        },
+        {
+          "kind": "component",
+          "id": "accordion"
+        },
+        {
+          "kind": "component",
+          "id": "collapsible"
+        },
+        {
+          "kind": "component",
+          "id": "data-grid"
+        },
+        {
+          "kind": "component",
+          "id": "list"
+        }
+      ]
+    },
+    {
+      "intent": "hierarchical rows with several navigable columns",
+      "use": "TreeGrid",
+      "note": "Choose Tree for one primary hierarchy column, DataGrid for flat interactive rows, Table for read-oriented tabular relationships, and an application-owned data tool for editing or independent cell controls.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "tree-grid"
+        },
+        {
+          "kind": "component",
+          "id": "tree"
+        },
+        {
+          "kind": "component",
+          "id": "data-grid"
+        },
+        {
+          "kind": "component",
+          "id": "table"
+        }
+      ]
+    },
+    {
+      "intent": "flat tabular data with composite cell navigation or row selection",
+      "use": "DataGrid",
+      "note": "Choose Table for read-oriented comparison, TreeGrid for hierarchical rows, and an application-owned data tool for editing, column management, or an enterprise data engine.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "data-grid"
+        },
+        {
+          "kind": "component",
+          "id": "table"
+        },
+        {
+          "kind": "component",
+          "id": "tree-grid"
+        }
+      ]
+    },
+    {
+      "intent": "read-oriented row and column comparison",
+      "use": "Table",
+      "note": "Choose DataGrid for composite cell navigation or row selection, TreeGrid for hierarchical interactive rows, and List when meaningful column relationships are absent.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "table"
+        },
+        {
+          "kind": "component",
+          "id": "data-grid"
+        },
+        {
+          "kind": "component",
+          "id": "tree-grid"
+        },
+        {
+          "kind": "component",
+          "id": "list"
+        }
+      ]
+    },
+    {
+      "intent": "changing stream of focusable articles with article-to-article keyboard movement",
+      "use": "Feed",
+      "note": "Choose List for a static sequence, Table or DataGrid for tabular relationships, Tree for hierarchy, and Stack or Grid for purely visual arrangement.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "feed"
+        },
+        {
+          "kind": "component",
+          "id": "list"
+        },
+        {
+          "kind": "component",
+          "id": "table"
+        },
+        {
+          "kind": "component",
+          "id": "data-grid"
+        },
+        {
+          "kind": "component",
+          "id": "tree"
+        },
+        {
+          "kind": "component",
+          "id": "stack"
+        },
+        {
+          "kind": "component",
+          "id": "grid"
+        }
+      ]
+    },
+    {
+      "intent": "linear read-only task completion or indeterminate work",
+      "use": "Progress",
+      "note": "Choose ProgressCircle when compact circular geometry is important, Slider for editable values, Toast for a transient outcome, and Skeleton for unknown content loading.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "progress"
+        },
+        {
+          "kind": "component",
+          "id": "progress-circle"
+        },
+        {
+          "kind": "component",
+          "id": "slider"
+        },
+        {
+          "kind": "component",
+          "id": "toast"
+        },
+        {
+          "kind": "component",
+          "id": "skeleton"
+        }
+      ]
+    },
+    {
+      "intent": "compact circular read-only task completion or indeterminate work",
+      "use": "ProgressCircle",
+      "note": "Choose Progress for linear completion, Slider for editable values, and Skeleton for unknown content loading.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "progress-circle"
+        },
+        {
+          "kind": "component",
+          "id": "progress"
+        },
+        {
+          "kind": "component",
+          "id": "slider"
+        },
+        {
+          "kind": "component",
+          "id": "skeleton"
+        }
+      ]
+    },
+    {
+      "intent": "visual count or presence dot over one owning element",
+      "use": "NotificationBadge",
+      "note": "Choose Badge for an in-flow passive label or count, Status for a named state, Button for an actionable count, and visible Text when the value must be announced or understood without the owner; NotificationBadge does not announce changes.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "notification-badge"
+        },
+        {
+          "kind": "component",
+          "id": "badge"
+        },
+        {
+          "kind": "component",
+          "id": "status"
+        },
+        {
+          "kind": "component",
+          "id": "button"
+        },
+        {
+          "kind": "component",
+          "id": "text"
+        }
+      ]
+    },
+    {
+      "intent": "compact identity for a named person, organization, or entity",
+      "use": "Avatar",
+      "note": "Choose Image for a larger editorial portrait and NotificationBadge only when the owning Avatar needs a separate visual count or presence indicator.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "avatar"
+        },
+        {
+          "kind": "component",
+          "id": "image"
+        },
+        {
+          "kind": "component",
+          "id": "notification-badge"
+        }
+      ]
+    },
+    {
+      "intent": "short passive in-flow label, category, status, or count",
+      "use": "Badge",
+      "note": "Choose NotificationBadge for an overlaid count or dot, Status for richer named state semantics, and Button when the label is actionable.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "badge"
+        },
+        {
+          "kind": "component",
+          "id": "notification-badge"
+        },
+        {
+          "kind": "component",
+          "id": "status"
+        },
+        {
+          "kind": "component",
+          "id": "button"
+        }
+      ]
+    },
+    {
+      "intent": "editable, selectable, or submitted opaque hexadecimal color",
+      "use": "ColorPicker",
+      "note": "Choose ColorSwatch for a passive preview; richer alpha, gradient, channel, eyedropper, and color-space editing remains an Atom-first gap.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "color-picker"
+        },
+        {
+          "kind": "component",
+          "id": "color-swatch"
+        }
+      ]
+    },
+    {
+      "intent": "passive preview of one color or a compact color mix",
+      "use": "ColorSwatch",
+      "note": "Choose ColorPicker when the user must edit, select, or submit the value; keep interaction on a semantic owner.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "color-swatch"
+        },
+        {
+          "kind": "component",
+          "id": "color-picker"
+        }
+      ]
+    },
+    {
+      "intent": "short assistive-only equivalent for meaning already conveyed visually",
+      "use": "VisuallyHidden",
+      "note": "Choose visible Text for essential instructions, state, errors, or announcements, and keep an IconButton or Button itself visible while placing the hidden equivalent inside it.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "visually-hidden"
+        },
+        {
+          "kind": "component",
+          "id": "text"
+        },
+        {
+          "kind": "component",
+          "id": "icon-button"
+        },
+        {
+          "kind": "component",
+          "id": "button"
+        }
+      ]
+    },
+    {
+      "intent": "approximate numeric value or ordered range through spatial manipulation",
+      "use": "Slider",
+      "note": "Choose NumberInput for exact entry, Progress for read-only completion, and Rating for a short ordered score.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "slider"
+        },
+        {
+          "kind": "component",
+          "id": "number-input"
+        },
+        {
+          "kind": "component",
+          "id": "progress"
+        },
+        {
+          "kind": "component",
+          "id": "rating"
+        }
+      ]
+    },
+    {
+      "intent": "short ordered score input or recognizable passive score aggregate",
+      "use": "Rating",
+      "note": "Choose Slider for a general numeric setting and RadioGroup when choices have distinct categorical meanings.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "rating"
+        },
+        {
+          "kind": "component",
+          "id": "slider"
+        },
+        {
+          "kind": "component",
+          "id": "radio-group"
+        }
+      ]
+    },
+    {
+      "intent": "ordered or unordered content",
+      "use": "List",
+      "note": "Choose NavList, an interactive collection, Table, or DataGrid when rows navigate, select, activate, or expose data relationships.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "list"
+        },
+        {
+          "kind": "component",
+          "id": "nav-list"
+        },
+        {
+          "kind": "component",
+          "id": "table"
+        },
+        {
+          "kind": "component",
+          "id": "data-grid"
+        }
+      ]
+    }
+  ],
+  "rules": [
+    {
+      "id": "brick-first",
+      "level": "must",
+      "statement": "Use an existing Brick component when it owns the interface job instead of recreating it with native elements and application CSS."
+    },
+    {
+      "id": "brick-no-direct-atom",
+      "level": "must",
+      "statement": "Do not import @flowstack-ui/atom directly in an application that has selected Brick; report a Brick gap if the finished component is missing."
+    },
+    {
+      "id": "brick-css-contract",
+      "level": "must",
+      "statement": "Load styles.css once, or core.css once plus every rendered component's modular stylesheet; never mix the two delivery modes."
+    },
+    {
+      "id": "brick-semantic-choice",
+      "level": "must",
+      "statement": "Choose components by semantic and interaction intent rather than by visual resemblance."
+    },
+    {
+      "id": "brick-customization-contract",
+      "level": "must",
+      "statement": "After selecting a Brick owner, follow interface-composition's ordered prop, semantic-token, component-token, public-part, and stable-hook customization contract."
+    },
+    {
+      "id": "brick-report-fallback",
+      "level": "should",
+      "statement": "Record intentional native or framework fallbacks with the searched Brick component and missing capability."
+    }
+  ],
+  "nativeFallback": {
+    "check": "Search the Brick manifest, package guide selection map, component docs, and public exports before writing native markup or replacement CSS.",
+    "use": "Use semantic native HTML only for document or application structure Brick does not own, or through a documented adapter when a framework supplies a required measured capability.",
+    "report": "Record the fallback as a Brick gap, adapter need, higher-layer composition, or intentional application-owned element before continuing."
+  },
+  "validation": [
+    "List every native layout, text, image, navigation, and interactive element and name why Brick does not own it; list every direct Brick stable-hook declaration and its completed customization gap report.",
+    "Confirm there are no direct @flowstack-ui/atom imports.",
+    "Confirm every rendered Brick component has its required modular CSS or the complete stylesheet is loaded once.",
+    "Classify each repeated composition as component, theme, Block, Blueprint, adapter, or application ownership."
+  ],
+  "related": [
+    "interface-composition",
+    "app-bar",
+    "container",
+    "stack",
+    "grid",
+    "text",
+    "image",
+    "aspect-ratio",
+    "code-block",
+    "show",
+    "hide",
+    "accordion",
+    "collapsible",
+    "list",
+    "feed",
+    "tree",
+    "tree-grid",
+    "table",
+    "data-grid",
+    "dialog",
+    "alert-dialog",
+    "popover",
+    "dropdown-menu",
+    "context-menu",
+    "menubar",
+    "hover-card",
+    "tooltip",
+    "radio-group",
+    "checkbox-group",
+    "switch",
+    "toggle",
+    "toggle-group",
+    "number-input",
+    "select",
+    "multi-select",
+    "combobox",
+    "otp-field",
+    "password-toggle-field",
+    "file-upload",
+    "toast",
+    "swipeable-item",
+    "progress",
+    "progress-circle",
+    "notification-badge",
+    "avatar",
+    "badge",
+    "color-picker",
+    "color-swatch",
+    "visually-hidden",
+    "slider",
+    "rating"
+  ]
+}
+```