@flowstack-ui/brick 0.1.3 → 0.1.5

package/dist/agents/hide.json

@@ -0,0 +1,54 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "hide",
+  "name": "Hide",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Hide content through Brick's CSS breakpoint contract without JavaScript viewport state or hydration flicker.",
+  "useWhen": [
+    "One composition should be absent at selected Brick breakpoints while remaining present elsewhere."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Content should be visually hidden but remain available to assistive technology, or should not render for business reasons.",
+      "useInstead": "VisuallyHidden or application conditional rendering"
+    }
+  ],
+  "composition": [
+    "Wrap the smallest complete region whose presence changes; pair with Show only when desktop and mobile genuinely need distinct compositions."
+  ],
+  "rules": [
+    {
+      "id": "hide-css-breakpoint",
+      "level": "must",
+      "statement": "Use Hide instead of JavaScript matchMedia for first-paint responsive visibility."
+    },
+    {
+      "id": "hide-no-semantic-loss",
+      "level": "must",
+      "statement": "Do not hide the only accessible name, error, instruction, or required content at a breakpoint."
+    },
+    {
+      "id": "hide-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus hide.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Hide without its modular CSS or duplicating two interactive trees with conflicting IDs.",
+      "correction": "Load hide.css and verify alternate compositions have independent valid relationships."
+    }
+  ],
+  "validation": [
+    "Test boundary pixels, zoom, first paint, hydration, focus order, and duplicate IDs across all visibility states.",
+    "Confirm CSS is loaded."
+  ],
+  "related": [
+    "show",
+    "visually-hidden",
+    "app-bar",
+    "drawer"
+  ]
+}

package/dist/agents/hide.md

@@ -0,0 +1,39 @@
+# Hide agent guide
+
+## Purpose
+
+Hide content through Brick's CSS breakpoint contract without JavaScript viewport state or hydration flicker.
+
+## Use when
+
+- One composition should be absent at selected Brick breakpoints while remaining present elsewhere.
+
+## Choose something else when
+
+- Content should be visually hidden but remain available to assistive technology, or should not render for business reasons. Use VisuallyHidden or application conditional rendering.
+
+## Required composition
+
+- Wrap the smallest complete region whose presence changes; pair with Show only when desktop and mobile genuinely need distinct compositions.
+
+## Rules
+
+- **MUST:** Use Hide instead of JavaScript matchMedia for first-paint responsive visibility.
+- **MUST:** Do not hide the only accessible name, error, instruction, or required content at a breakpoint.
+- **MUST:** Load styles.css or core.css plus hide.css.
+
+## Common mistakes
+
+- **Avoid:** Using Hide without its modular CSS or duplicating two interactive trees with conflicting IDs. **Instead:** Load hide.css and verify alternate compositions have independent valid relationships.
+
+## Validation checklist
+
+- Test boundary pixels, zoom, first paint, hydration, focus order, and duplicate IDs across all visibility states.
+- Confirm CSS is loaded.
+
+## Related guidance
+
+- `show`
+- `visually-hidden`
+- `app-bar`
+- `drawer`

package/dist/agents/icon-button.json

@@ -0,0 +1,54 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "icon-button",
+  "name": "IconButton",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a compact finished action control for a single recognizable icon with an explicit accessible name.",
+  "useWhen": [
+    "A familiar icon represents one action and visible button text would be redundant in the available space."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The control navigates, needs visible explanatory text, or is an arbitrary clickable surface.",
+      "useInstead": "Link, Button, or another owning component"
+    }
+  ],
+  "composition": [
+    "Place one decorative Icon or SVG inside IconButton and provide an accessible label through the component's naming API."
+  ],
+  "rules": [
+    {
+      "id": "icon-button-name",
+      "level": "must",
+      "statement": "Give every IconButton a concise discernible accessible name; the icon alone is not a name."
+    },
+    {
+      "id": "icon-button-action",
+      "level": "must",
+      "statement": "Use IconButton for actions, not ordinary navigation."
+    },
+    {
+      "id": "icon-button-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus icon-button.css and icon.css when using Brick Icon."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using a random glyph, code icon for GitHub, or unlabeled SVG inside a generic button.",
+      "correction": "Use the correct icon asset in a named IconButton."
+    }
+  ],
+  "validation": [
+    "Check accessible name, icon alignment, touch target, focus ring, disabled/loading states, contrast, and forced colors.",
+    "Confirm component CSS is loaded."
+  ],
+  "related": [
+    "button",
+    "icon",
+    "toolbar",
+    "tooltip"
+  ]
+}

package/dist/agents/icon-button.md

@@ -0,0 +1,39 @@
+# IconButton agent guide
+
+## Purpose
+
+Provide a compact finished action control for a single recognizable icon with an explicit accessible name.
+
+## Use when
+
+- A familiar icon represents one action and visible button text would be redundant in the available space.
+
+## Choose something else when
+
+- The control navigates, needs visible explanatory text, or is an arbitrary clickable surface. Use Link, Button, or another owning component.
+
+## Required composition
+
+- Place one decorative Icon or SVG inside IconButton and provide an accessible label through the component's naming API.
+
+## Rules
+
+- **MUST:** Give every IconButton a concise discernible accessible name; the icon alone is not a name.
+- **MUST:** Use IconButton for actions, not ordinary navigation.
+- **MUST:** Load styles.css or core.css plus icon-button.css and icon.css when using Brick Icon.
+
+## Common mistakes
+
+- **Avoid:** Using a random glyph, code icon for GitHub, or unlabeled SVG inside a generic button. **Instead:** Use the correct icon asset in a named IconButton.
+
+## Validation checklist
+
+- Check accessible name, icon alignment, touch target, focus ring, disabled/loading states, contrast, and forced colors.
+- Confirm component CSS is loaded.
+
+## Related guidance
+
+- `button`
+- `icon`
+- `toolbar`
+- `tooltip`

package/dist/agents/image.json

@@ -0,0 +1,59 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "image",
+  "name": "Image",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide styled resilient media with Atom loading/fallback behavior, sizing recipes, and accessible image semantics.",
+  "useWhen": [
+    "A product image, brand asset, illustration, or content image needs Brick sizing, fit, radius, loading, or fallback presentation."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A framework optimizer provides a required measured optimization Brick does not expose.",
+      "useInstead": "a documented Image adapter that preserves semantics and reports the capability gap"
+    }
+  ],
+  "composition": [
+    "Compose Image.Content and optional Image.Fallback inside Image.Root; use Brick Stack or layout components around it rather than wrapper spans for alignment."
+  ],
+  "rules": [
+    {
+      "id": "image-brick-first",
+      "level": "must",
+      "statement": "Use Brick Image for ordinary interface media; document any native or framework image fallback and the missing capability."
+    },
+    {
+      "id": "image-alt",
+      "level": "must",
+      "statement": "Provide meaningful alt text, or alt=\"\" for a decorative image."
+    },
+    {
+      "id": "image-layout",
+      "level": "should",
+      "statement": "Reserve dimensions or aspect ratio to prevent layout shift."
+    },
+    {
+      "id": "image-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus image.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using next/image automatically, wrapping Image in spans for ordinary alignment, or duplicating the caption in alt text.",
+      "correction": "Start with Brick Image, use Brick layout components, and adapt only for a measured missing optimizer capability."
+    }
+  ],
+  "validation": [
+    "Check loaded, loading, error, cached, responsive size, crop, layout shift, alt text, contrast of fallback content, and RTL where relevant.",
+    "Confirm CSS and any adapter report are complete."
+  ],
+  "related": [
+    "aspect-ratio",
+    "stack",
+    "avatar",
+    "surface"
+  ]
+}

package/dist/agents/image.md

@@ -0,0 +1,40 @@
+# Image agent guide
+
+## Purpose
+
+Provide styled resilient media with Atom loading/fallback behavior, sizing recipes, and accessible image semantics.
+
+## Use when
+
+- A product image, brand asset, illustration, or content image needs Brick sizing, fit, radius, loading, or fallback presentation.
+
+## Choose something else when
+
+- A framework optimizer provides a required measured optimization Brick does not expose. Use a documented Image adapter that preserves semantics and reports the capability gap.
+
+## Required composition
+
+- Compose Image.Content and optional Image.Fallback inside Image.Root; use Brick Stack or layout components around it rather than wrapper spans for alignment.
+
+## Rules
+
+- **MUST:** Use Brick Image for ordinary interface media; document any native or framework image fallback and the missing capability.
+- **MUST:** Provide meaningful alt text, or alt="" for a decorative image.
+- **SHOULD:** Reserve dimensions or aspect ratio to prevent layout shift.
+- **MUST:** Load styles.css or core.css plus image.css.
+
+## Common mistakes
+
+- **Avoid:** Using next/image automatically, wrapping Image in spans for ordinary alignment, or duplicating the caption in alt text. **Instead:** Start with Brick Image, use Brick layout components, and adapt only for a measured missing optimizer capability.
+
+## Validation checklist
+
+- Check loaded, loading, error, cached, responsive size, crop, layout shift, alt text, contrast of fallback content, and RTL where relevant.
+- Confirm CSS and any adapter report are complete.
+
+## Related guidance
+
+- `aspect-ratio`
+- `stack`
+- `avatar`
+- `surface`

package/dist/agents/input.json

@@ -0,0 +1,48 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "input",
+  "name": "Input",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Render finished native single-line text entry with Brick sizing, states, and Atom field integration.",
+  "useWhen": [
+    "The user enters a single-line text, email, search, URL, telephone, or supported native input value."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The value needs multiple lines.",
+      "useInstead": "Textarea"
+    }
+  ],
+  "composition": [
+    "Place Input inside one Field.Root after Field.Label; provide name, type, and autocomplete appropriate to the data."
+  ],
+  "rules": [
+    {
+      "id": "input-label",
+      "level": "must",
+      "statement": "Use a persistent accessible label; placeholder is not a replacement."
+    },
+    {
+      "id": "input-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus input.css and field.css when composed with Field."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using placeholder as the only visible label.",
+      "correction": "Compose Input with Field.Label and use placeholder only as optional example text."
+    }
+  ],
+  "validation": [
+    "Inspect label, name, type, autocomplete, and messaging relationships.",
+    "Test focus, entry, autofill, invalid/disabled states, zoom, and both appearances."
+  ],
+  "related": [
+    "@flowstack-ui/atom/agents/input",
+    "field",
+    "textarea"
+  ]
+}

package/dist/agents/input.md

@@ -0,0 +1,37 @@
+# Input agent guide
+
+## Purpose
+
+Render finished native single-line text entry with Brick sizing, states, and Atom field integration.
+
+## Use when
+
+- The user enters a single-line text, email, search, URL, telephone, or supported native input value.
+
+## Choose something else when
+
+- The value needs multiple lines. Use Textarea.
+
+## Required composition
+
+- Place Input inside one Field.Root after Field.Label; provide name, type, and autocomplete appropriate to the data.
+
+## Rules
+
+- **MUST:** Use a persistent accessible label; placeholder is not a replacement.
+- **MUST:** Load styles.css or core.css plus input.css and field.css when composed with Field.
+
+## Common mistakes
+
+- **Avoid:** Using placeholder as the only visible label. **Instead:** Compose Input with Field.Label and use placeholder only as optional example text.
+
+## Validation checklist
+
+- Inspect label, name, type, autocomplete, and messaging relationships.
+- Test focus, entry, autofill, invalid/disabled states, zoom, and both appearances.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/input`
+- `field`
+- `textarea`

package/dist/agents/interface-composition.json

@@ -0,0 +1,184 @@
+{
+  "schema": "flowstack.agent-guide.v1",
+  "id": "interface-composition",
+  "name": "Brick interface composition",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "guide",
+  "purpose": "Build complete interfaces from Brick's structural, content, navigation, action, responsive, and surface components before adding narrow application styling.",
+  "decisionOrder": [
+    "Map the page into landmarks, bounded regions, layout relationships, content, navigation, actions, media, and responsive changes.",
+    "Choose the Brick owner for each relationship and read every selected component guide before implementation.",
+    "Compose from the outside inward: AppBar or page landmark, Container, Grid or Stack, Surface or Card, then content and controls.",
+    "Follow the customization order completely: component owner, supported props, semantic theme tokens, component tokens, public parts, and only then a narrow stable-hook escape hatch.",
+    "Audit responsive behavior, accessibility, CSS delivery, and native fallbacks before treating the composition as complete."
+  ],
+  "selection": [
+    {
+      "intent": "page width and gutters",
+      "use": "Container",
+      "note": "Do not reproduce max-width and inline padding on every section."
+    },
+    {
+      "intent": "row or column relationship",
+      "use": "HStack or VStack",
+      "note": "Use Stack when direction is selected dynamically."
+    },
+    {
+      "intent": "track-based responsive layout",
+      "use": "Grid",
+      "note": "Use Stack when only one axis matters."
+    },
+    {
+      "intent": "visual region",
+      "use": "Surface or Card",
+      "note": "Use Card for titled or actionable contained content and Surface for a general visual boundary."
+    },
+    {
+      "intent": "brand or content image",
+      "use": "Image",
+      "note": "Keep alt text and fallback behavior intentional."
+    },
+    {
+      "intent": "site navigation",
+      "use": "NavigationMenu or NavList",
+      "note": "Use NavigationMenu for disclosure navigation and NavList for persistent route lists."
+    },
+    {
+      "intent": "responsive desktop and mobile alternatives",
+      "use": "Show and Hide",
+      "note": "Keep one CSS-controlled breakpoint contract and avoid hydration-dependent visibility; distinct navigation patterns should consume one application-owned destination model."
+    },
+    {
+      "intent": "grouped application actions",
+      "use": "Toolbar",
+      "note": "Do not use AppBar.Toolbar as an ARIA toolbar."
+    }
+  ],
+  "rules": [
+    {
+      "id": "interface-outside-in",
+      "level": "must",
+      "statement": "Assign page structure to Brick components before writing element-level CSS."
+    },
+    {
+      "id": "interface-correct-owner",
+      "level": "must",
+      "statement": "Do not use Stack, Surface, Button, or another convenient component when a more specific Brick navigation, media, content, or interaction component owns the job."
+    },
+    {
+      "id": "interface-native-semantics",
+      "level": "must",
+      "statement": "Preserve document landmarks and semantic elements when Brick does not provide an owner; Brick-first is not permission to erase HTML meaning."
+    },
+    {
+      "id": "interface-responsive-navigation-data",
+      "level": "must",
+      "statement": "When desktop and mobile require distinct navigation components, share application-owned destination labels, hrefs, values, and ordering while preserving each pattern's correct Brick anatomy; do not duplicate navigation content or force one interaction tree across breakpoints."
+    },
+    {
+      "id": "interface-responsive-overlay-state",
+      "level": "must",
+      "statement": "Use Show and Hide for first-paint visibility; when a controlled interactive overlay may remain open across a breakpoint, synchronize its application state at that boundary so a hidden modal cannot retain focus, scroll lock, or isolation."
+    },
+    {
+      "id": "interface-theme-first",
+      "level": "should",
+      "statement": "Express reusable brand values through semantic Brick tokens and a theme rather than repeating literal application values."
+    },
+    {
+      "id": "interface-document-foundation",
+      "level": "must",
+      "statement": "When styles.css or styles/core.css is loaded, change the document canvas, foreground, and body typography through semantic Brick tokens instead of repeating the body bindings that Brick's foundation already owns."
+    },
+    {
+      "id": "interface-customization-order",
+      "level": "must",
+      "statement": "Do not write a direct declaration against a Brick part until the correct component, supported props, semantic tokens, component tokens, and public compound parts have been checked in order."
+    },
+    {
+      "id": "interface-public-hooks-only",
+      "level": "must",
+      "statement": "Target only documented Brick tokens, public compound parts, stable brick-* base classes, documented slots, and documented state attributes; inspected internal wrappers or implementation selectors are not APIs."
+    },
+    {
+      "id": "interface-report-token-gap",
+      "level": "must",
+      "statement": "When a direct stable-hook override remains because no public prop or token expresses the requirement, emit the required customization gap report and classify its owner before treating the interface as complete."
+    },
+    {
+      "id": "interface-extract-evidence",
+      "level": "should",
+      "statement": "Classify repeated purposeful sections as Block candidates and repeated page arrangements as Blueprint candidates only after real reuse evidence."
+    }
+  ],
+  "customization": {
+    "order": [
+      {
+        "owner": "Correct Brick component",
+        "instruction": "Select the component whose semantic, behavioral, layout, content, navigation, or surface contract owns the job; styling a convenient substitute is not equivalent."
+      },
+      {
+        "owner": "Supported props and recipes",
+        "instruction": "Use the component's documented variant, tone, size, density, orientation, placement, and other closed recipes when they express the result."
+      },
+      {
+        "owner": "Semantic theme tokens",
+        "instruction": "Assign reusable brand color, typography, spacing, radius, surface, focus, and motion roles through a theme scope, preserving required foreground/background and interaction-state pairs."
+      },
+      {
+        "owner": "Documented component tokens",
+        "instruction": "Use stable --brick-<component>-* variables for supported anatomy-specific adjustments instead of overriding the declaration that consumes them."
+      },
+      {
+        "owner": "Public compound parts",
+        "instruction": "Place product-specific composition classes on the public part that owns the region; do not create slot maps or select private wrappers."
+      },
+      {
+        "owner": "Narrow stable-hook escape hatch",
+        "instruction": "Use className or style only for application-owned composition or a value Brick does not expose, and target a documented public hook when direct CSS is unavoidable."
+      }
+    ],
+    "classNamePolicy": "className scopes a product composition or supplies consumer-defined token values. It must not replace a supported prop, repeat a reusable theme value, or depend on undocumented anatomy.",
+    "directCssPolicy": "Direct declarations on a stable Brick class are a last resort. Keep them narrow, preserve component state and accessibility, verify the affected responsive and appearance states, and report the missing public capability.",
+    "gapReport": {
+      "requiredWhen": "Emit this record for every native/framework fallback or direct stable-hook declaration that remains after the ordered search.",
+      "fields": [
+        "interfaceJob",
+        "brickOwnerSearched",
+        "supportedPropsChecked",
+        "semanticTokensChecked",
+        "componentTokensChecked",
+        "publicPartsChecked",
+        "fallbackOrOverride",
+        "missingCapability",
+        "proposedOwner",
+        "verification"
+      ]
+    }
+  },
+  "nativeFallback": {
+    "check": "Review the interface map against the manifest and selected component guides, including layout, text, image, visibility, and navigation owners.",
+    "use": "Keep native landmarks and product-specific semantic structures where no Brick component adds a useful contract; add only narrow composition classes.",
+    "report": "Record what Brick lacked, whether an adapter or new component is warranted, and whether the pattern belongs to Theme, Block, Blueprint, or the application."
+  },
+  "validation": [
+    "Inspect the rendered DOM, accessible names, heading order, landmarks, focus order, keyboard operation, touch targets, contrast, zoom, and RTL behavior.",
+    "Test every adopted breakpoint without JavaScript-dependent first-paint flicker.",
+    "Confirm layout primitives own ordinary gap, alignment, wrapping, width, and visibility before accepting custom CSS.",
+    "Confirm repeated CSS values are theme tokens, component-specific values use documented component tokens, and every remaining direct stable-hook declaration has a complete customization gap report.",
+    "Run the package's CSS-delivery check and the application's accessibility, browser, and performance checks."
+  ],
+  "related": [
+    "layer-selection",
+    "app-bar",
+    "container",
+    "stack",
+    "grid",
+    "surface",
+    "card",
+    "navigation-menu",
+    "show",
+    "hide"
+  ]
+}

package/dist/agents/interface-composition.md

@@ -0,0 +1,93 @@
+# Brick interface composition
+
+## Purpose
+
+Build complete interfaces from Brick's structural, content, navigation, action, responsive, and surface components before adding narrow application styling.
+
+## Decision order
+
+1. Map the page into landmarks, bounded regions, layout relationships, content, navigation, actions, media, and responsive changes.
+2. Choose the Brick owner for each relationship and read every selected component guide before implementation.
+3. Compose from the outside inward: AppBar or page landmark, Container, Grid or Stack, Surface or Card, then content and controls.
+4. Follow the customization order completely: component owner, supported props, semantic theme tokens, component tokens, public parts, and only then a narrow stable-hook escape hatch.
+5. Audit responsive behavior, accessibility, CSS delivery, and native fallbacks before treating the composition as complete.
+
+## Selection map
+
+- **page width and gutters:** use Container. Do not reproduce max-width and inline padding on every section.
+- **row or column relationship:** use HStack or VStack. Use Stack when direction is selected dynamically.
+- **track-based responsive layout:** use Grid. Use Stack when only one axis matters.
+- **visual region:** use Surface or Card. Use Card for titled or actionable contained content and Surface for a general visual boundary.
+- **brand or content image:** use Image. Keep alt text and fallback behavior intentional.
+- **site navigation:** use NavigationMenu or NavList. Use NavigationMenu for disclosure navigation and NavList for persistent route lists.
+- **responsive desktop and mobile alternatives:** use Show and Hide. Keep one CSS-controlled breakpoint contract and avoid hydration-dependent visibility; distinct navigation patterns should consume one application-owned destination model.
+- **grouped application actions:** use Toolbar. Do not use AppBar.Toolbar as an ARIA toolbar.
+
+## Rules
+
+- **MUST:** Assign page structure to Brick components before writing element-level CSS.
+- **MUST:** Do not use Stack, Surface, Button, or another convenient component when a more specific Brick navigation, media, content, or interaction component owns the job.
+- **MUST:** Preserve document landmarks and semantic elements when Brick does not provide an owner; Brick-first is not permission to erase HTML meaning.
+- **MUST:** When desktop and mobile require distinct navigation components, share application-owned destination labels, hrefs, values, and ordering while preserving each pattern's correct Brick anatomy; do not duplicate navigation content or force one interaction tree across breakpoints.
+- **MUST:** Use Show and Hide for first-paint visibility; when a controlled interactive overlay may remain open across a breakpoint, synchronize its application state at that boundary so a hidden modal cannot retain focus, scroll lock, or isolation.
+- **SHOULD:** Express reusable brand values through semantic Brick tokens and a theme rather than repeating literal application values.
+- **MUST:** When styles.css or styles/core.css is loaded, change the document canvas, foreground, and body typography through semantic Brick tokens instead of repeating the body bindings that Brick's foundation already owns.
+- **MUST:** Do not write a direct declaration against a Brick part until the correct component, supported props, semantic tokens, component tokens, and public compound parts have been checked in order.
+- **MUST:** Target only documented Brick tokens, public compound parts, stable brick-* base classes, documented slots, and documented state attributes; inspected internal wrappers or implementation selectors are not APIs.
+- **MUST:** When a direct stable-hook override remains because no public prop or token expresses the requirement, emit the required customization gap report and classify its owner before treating the interface as complete.
+- **SHOULD:** Classify repeated purposeful sections as Block candidates and repeated page arrangements as Blueprint candidates only after real reuse evidence.
+
+## Customization order
+
+1. **Correct Brick component:** Select the component whose semantic, behavioral, layout, content, navigation, or surface contract owns the job; styling a convenient substitute is not equivalent.
+2. **Supported props and recipes:** Use the component's documented variant, tone, size, density, orientation, placement, and other closed recipes when they express the result.
+3. **Semantic theme tokens:** Assign reusable brand color, typography, spacing, radius, surface, focus, and motion roles through a theme scope, preserving required foreground/background and interaction-state pairs.
+4. **Documented component tokens:** Use stable --brick-<component>-* variables for supported anatomy-specific adjustments instead of overriding the declaration that consumes them.
+5. **Public compound parts:** Place product-specific composition classes on the public part that owns the region; do not create slot maps or select private wrappers.
+6. **Narrow stable-hook escape hatch:** Use className or style only for application-owned composition or a value Brick does not expose, and target a documented public hook when direct CSS is unavoidable.
+
+**Class name policy:** className scopes a product composition or supplies consumer-defined token values. It must not replace a supported prop, repeat a reusable theme value, or depend on undocumented anatomy.
+
+**Direct CSS policy:** Direct declarations on a stable Brick class are a last resort. Keep them narrow, preserve component state and accessibility, verify the affected responsive and appearance states, and report the missing public capability.
+
+### Required gap report
+
+Emit this record for every native/framework fallback or direct stable-hook declaration that remains after the ordered search.
+
+- `interfaceJob`
+- `brickOwnerSearched`
+- `supportedPropsChecked`
+- `semanticTokensChecked`
+- `componentTokensChecked`
+- `publicPartsChecked`
+- `fallbackOrOverride`
+- `missingCapability`
+- `proposedOwner`
+- `verification`
+
+## Native fallback
+
+1. Review the interface map against the manifest and selected component guides, including layout, text, image, visibility, and navigation owners.
+2. Keep native landmarks and product-specific semantic structures where no Brick component adds a useful contract; add only narrow composition classes.
+3. Record what Brick lacked, whether an adapter or new component is warranted, and whether the pattern belongs to Theme, Block, Blueprint, or the application.
+
+## Validation checklist
+
+- Inspect the rendered DOM, accessible names, heading order, landmarks, focus order, keyboard operation, touch targets, contrast, zoom, and RTL behavior.
+- Test every adopted breakpoint without JavaScript-dependent first-paint flicker.
+- Confirm layout primitives own ordinary gap, alignment, wrapping, width, and visibility before accepting custom CSS.
+- Confirm repeated CSS values are theme tokens, component-specific values use documented component tokens, and every remaining direct stable-hook declaration has a complete customization gap report.
+- Run the package's CSS-delivery check and the application's accessibility, browser, and performance checks.
+
+## Related guidance
+
+- `layer-selection`
+- `app-bar`
+- `container`
+- `stack`
+- `grid`
+- `surface`
+- `card`
+- `navigation-menu`
+- `show`
+- `hide`