@flowstack-ui/brick 0.1.6 → 0.1.11

package/README.md

@@ -29,7 +29,8 @@ import "@flowstack-ui/brick/styles.css";
 ```
 
 New applications may opt into Brick's separate neutral reset for page sizing,
-margin removal, and browser normalization:
+body, `figure`, and `blockquote` margin removal, and browser normalization.
+Higher-level FLOWSTACK packs may require this complete two-import setup:
 
 ```ts
 import "@flowstack-ui/brick/reset.css";
@@ -139,25 +140,30 @@ Override public semantic variables with ordinary CSS:
 ```
 
 See [Appearance and tokens](docs/guides/appearance-and-tokens.md) for the full
-contract.
+customization guide. Theme tooling can discover Brick's generated
+[`flowstack.brick-theme-contract.v1`](docs/guides/theme-contract.md) artifact
+through `@flowstack-ui/brick/theme-contract.json`.
 
 ## Documentation
 
 - [Installation and stylesheet setup](docs/guides/installation.md)
 - [Appearance and semantic tokens](docs/guides/appearance-and-tokens.md)
+- [Generated theme contract](docs/guides/theme-contract.md)
+- [Shared control sizing](docs/guides/control-sizing.md)
+- [Browser support and progressive enhancement](docs/guides/browser-support.md)
 
 The complete component guides live with the source repository:
 
 | Family | Components |
 | --- | --- |
-| Actions and selection | [Button](https://github.com/flowstack-ui/brick/blob/main/docs/components/button/README.md), [Icon Button](https://github.com/flowstack-ui/brick/blob/main/docs/components/icon-button/README.md), [Toggle](https://github.com/flowstack-ui/brick/blob/main/docs/components/toggle/README.md), [Toggle Group](https://github.com/flowstack-ui/brick/blob/main/docs/components/toggle-group/README.md), [Toolbar](https://github.com/flowstack-ui/brick/blob/main/docs/components/toolbar/README.md), [Pagination](https://github.com/flowstack-ui/brick/blob/main/docs/components/pagination/README.md) |
+| Actions and selection | [Button](https://github.com/flowstack-ui/brick/blob/main/docs/components/button/README.md), [Icon Button](https://github.com/flowstack-ui/brick/blob/main/docs/components/icon-button/README.md), [Toggle](https://github.com/flowstack-ui/brick/blob/main/docs/components/toggle/README.md), [Toggle Group](https://github.com/flowstack-ui/brick/blob/main/docs/components/toggle-group/README.md), [Segment Group](https://github.com/flowstack-ui/brick/blob/main/docs/components/segment-group/README.md), [Toolbar](https://github.com/flowstack-ui/brick/blob/main/docs/components/toolbar/README.md), [Pagination](https://github.com/flowstack-ui/brick/blob/main/docs/components/pagination/README.md), [Reorderable List](https://github.com/flowstack-ui/brick/blob/main/docs/components/reorderable-list/README.md) |
 | Accessibility | [Skip Link](https://github.com/flowstack-ui/brick/blob/main/docs/components/skip-link/README.md), [Visually Hidden](https://github.com/flowstack-ui/brick/blob/main/docs/components/visually-hidden/README.md) |
-| Data display | [Aspect Ratio](https://github.com/flowstack-ui/brick/blob/main/docs/components/aspect-ratio/README.md), [Data Grid](https://github.com/flowstack-ui/brick/blob/main/docs/components/data-grid/README.md), [Tree Grid](https://github.com/flowstack-ui/brick/blob/main/docs/components/tree-grid/README.md), [Tree](https://github.com/flowstack-ui/brick/blob/main/docs/components/tree/README.md), [Feed](https://github.com/flowstack-ui/brick/blob/main/docs/components/feed/README.md), [Swipeable Item](https://github.com/flowstack-ui/brick/blob/main/docs/components/swipeable-item/README.md), [Carousel](https://github.com/flowstack-ui/brick/blob/main/docs/components/carousel/README.md) |
-| Forms and choices | [Form](https://github.com/flowstack-ui/brick/blob/main/docs/components/form/README.md), [Field](https://github.com/flowstack-ui/brick/blob/main/docs/components/field/README.md), [Fieldset](https://github.com/flowstack-ui/brick/blob/main/docs/components/fieldset/README.md), [Input](https://github.com/flowstack-ui/brick/blob/main/docs/components/input/README.md), [Number Input](https://github.com/flowstack-ui/brick/blob/main/docs/components/number-input/README.md), [OTP Field](https://github.com/flowstack-ui/brick/blob/main/docs/components/otp-field/README.md), [Password Toggle Field](https://github.com/flowstack-ui/brick/blob/main/docs/components/password-toggle-field/README.md), [Textarea](https://github.com/flowstack-ui/brick/blob/main/docs/components/textarea/README.md), [Select](https://github.com/flowstack-ui/brick/blob/main/docs/components/select/README.md), [Combobox](https://github.com/flowstack-ui/brick/blob/main/docs/components/combobox/README.md), [Multi Select](https://github.com/flowstack-ui/brick/blob/main/docs/components/multi-select/README.md), [File Upload](https://github.com/flowstack-ui/brick/blob/main/docs/components/file-upload/README.md), [Checkbox](https://github.com/flowstack-ui/brick/blob/main/docs/components/checkbox/README.md), [Checkbox Group](https://github.com/flowstack-ui/brick/blob/main/docs/components/checkbox-group/README.md), [Radio Group](https://github.com/flowstack-ui/brick/blob/main/docs/components/radio-group/README.md), [Switch](https://github.com/flowstack-ui/brick/blob/main/docs/components/switch/README.md), [Slider](https://github.com/flowstack-ui/brick/blob/main/docs/components/slider/README.md), [Rating](https://github.com/flowstack-ui/brick/blob/main/docs/components/rating/README.md) |
-| Content and status | [Text](https://github.com/flowstack-ui/brick/blob/main/docs/components/text/README.md), [Icon](https://github.com/flowstack-ui/brick/blob/main/docs/components/icon/README.md), [Image](https://github.com/flowstack-ui/brick/blob/main/docs/components/image/README.md), [Code](https://github.com/flowstack-ui/brick/blob/main/docs/components/code/README.md), [Code Block](https://github.com/flowstack-ui/brick/blob/main/docs/components/code-block/README.md), [Avatar](https://github.com/flowstack-ui/brick/blob/main/docs/components/avatar/README.md), [Badge](https://github.com/flowstack-ui/brick/blob/main/docs/components/badge/README.md), [Chip](https://github.com/flowstack-ui/brick/blob/main/docs/components/chip/README.md), [Notification Badge](https://github.com/flowstack-ui/brick/blob/main/docs/components/notification-badge/README.md), [Card](https://github.com/flowstack-ui/brick/blob/main/docs/components/card/README.md), [List](https://github.com/flowstack-ui/brick/blob/main/docs/components/list/README.md), [Table](https://github.com/flowstack-ui/brick/blob/main/docs/components/table/README.md), [Divider](https://github.com/flowstack-ui/brick/blob/main/docs/components/divider/README.md), [Collapsible](https://github.com/flowstack-ui/brick/blob/main/docs/components/collapsible/README.md), [Accordion](https://github.com/flowstack-ui/brick/blob/main/docs/components/accordion/README.md), [Skeleton](https://github.com/flowstack-ui/brick/blob/main/docs/components/skeleton/README.md), [Progress](https://github.com/flowstack-ui/brick/blob/main/docs/components/progress/README.md), [Progress Circle](https://github.com/flowstack-ui/brick/blob/main/docs/components/progress-circle/README.md), [Toast](https://github.com/flowstack-ui/brick/blob/main/docs/components/toast/README.md) |
+| Data display | [Aspect Ratio](https://github.com/flowstack-ui/brick/blob/main/docs/components/aspect-ratio/README.md), [Data List](https://github.com/flowstack-ui/brick/blob/main/docs/components/data-list/README.md), [Data Grid](https://github.com/flowstack-ui/brick/blob/main/docs/components/data-grid/README.md), [Tree Grid](https://github.com/flowstack-ui/brick/blob/main/docs/components/tree-grid/README.md), [Tree](https://github.com/flowstack-ui/brick/blob/main/docs/components/tree/README.md), [Feed](https://github.com/flowstack-ui/brick/blob/main/docs/components/feed/README.md), [Swipeable Item](https://github.com/flowstack-ui/brick/blob/main/docs/components/swipeable-item/README.md), [Carousel](https://github.com/flowstack-ui/brick/blob/main/docs/components/carousel/README.md) |
+| Forms and choices | [Color Picker](https://github.com/flowstack-ui/brick/blob/main/docs/components/color-picker/README.md), [Form](https://github.com/flowstack-ui/brick/blob/main/docs/components/form/README.md), [Field](https://github.com/flowstack-ui/brick/blob/main/docs/components/field/README.md), [Fieldset](https://github.com/flowstack-ui/brick/blob/main/docs/components/fieldset/README.md), [Input](https://github.com/flowstack-ui/brick/blob/main/docs/components/input/README.md), [Number Input](https://github.com/flowstack-ui/brick/blob/main/docs/components/number-input/README.md), [OTP Field](https://github.com/flowstack-ui/brick/blob/main/docs/components/otp-field/README.md), [Password Toggle Field](https://github.com/flowstack-ui/brick/blob/main/docs/components/password-toggle-field/README.md), [Textarea](https://github.com/flowstack-ui/brick/blob/main/docs/components/textarea/README.md), [Select](https://github.com/flowstack-ui/brick/blob/main/docs/components/select/README.md), [Combobox](https://github.com/flowstack-ui/brick/blob/main/docs/components/combobox/README.md), [Multi Select](https://github.com/flowstack-ui/brick/blob/main/docs/components/multi-select/README.md), [File Upload](https://github.com/flowstack-ui/brick/blob/main/docs/components/file-upload/README.md), [Checkbox](https://github.com/flowstack-ui/brick/blob/main/docs/components/checkbox/README.md), [Checkbox Group](https://github.com/flowstack-ui/brick/blob/main/docs/components/checkbox-group/README.md), [Radio Group](https://github.com/flowstack-ui/brick/blob/main/docs/components/radio-group/README.md), [Switch](https://github.com/flowstack-ui/brick/blob/main/docs/components/switch/README.md), [Slider](https://github.com/flowstack-ui/brick/blob/main/docs/components/slider/README.md), [Rating](https://github.com/flowstack-ui/brick/blob/main/docs/components/rating/README.md) |
+| Content and status | [Text](https://github.com/flowstack-ui/brick/blob/main/docs/components/text/README.md), [Icon](https://github.com/flowstack-ui/brick/blob/main/docs/components/icon/README.md), [Image](https://github.com/flowstack-ui/brick/blob/main/docs/components/image/README.md), [Code](https://github.com/flowstack-ui/brick/blob/main/docs/components/code/README.md), [Code Block](https://github.com/flowstack-ui/brick/blob/main/docs/components/code-block/README.md), [Avatar](https://github.com/flowstack-ui/brick/blob/main/docs/components/avatar/README.md), [Badge](https://github.com/flowstack-ui/brick/blob/main/docs/components/badge/README.md), [Chip](https://github.com/flowstack-ui/brick/blob/main/docs/components/chip/README.md), [Notification Badge](https://github.com/flowstack-ui/brick/blob/main/docs/components/notification-badge/README.md), [Status](https://github.com/flowstack-ui/brick/blob/main/docs/components/status/README.md), [Color Swatch](https://github.com/flowstack-ui/brick/blob/main/docs/components/color-swatch/README.md), [Card](https://github.com/flowstack-ui/brick/blob/main/docs/components/card/README.md), [List](https://github.com/flowstack-ui/brick/blob/main/docs/components/list/README.md), [Table](https://github.com/flowstack-ui/brick/blob/main/docs/components/table/README.md), [Divider](https://github.com/flowstack-ui/brick/blob/main/docs/components/divider/README.md), [Collapsible](https://github.com/flowstack-ui/brick/blob/main/docs/components/collapsible/README.md), [Accordion](https://github.com/flowstack-ui/brick/blob/main/docs/components/accordion/README.md), [Skeleton](https://github.com/flowstack-ui/brick/blob/main/docs/components/skeleton/README.md), [Progress](https://github.com/flowstack-ui/brick/blob/main/docs/components/progress/README.md), [Progress Circle](https://github.com/flowstack-ui/brick/blob/main/docs/components/progress-circle/README.md), [Toast](https://github.com/flowstack-ui/brick/blob/main/docs/components/toast/README.md) |
 | Contextual overlays | [Tooltip](https://github.com/flowstack-ui/brick/blob/main/docs/components/tooltip/README.md), [Hover Card](https://github.com/flowstack-ui/brick/blob/main/docs/components/hover-card/README.md), [Popover](https://github.com/flowstack-ui/brick/blob/main/docs/components/popover/README.md), [Dropdown Menu](https://github.com/flowstack-ui/brick/blob/main/docs/components/dropdown-menu/README.md), [Context Menu](https://github.com/flowstack-ui/brick/blob/main/docs/components/context-menu/README.md), [Menubar](https://github.com/flowstack-ui/brick/blob/main/docs/components/menubar/README.md) |
 | Modal surfaces | [Dialog](https://github.com/flowstack-ui/brick/blob/main/docs/components/dialog/README.md), [Alert Dialog](https://github.com/flowstack-ui/brick/blob/main/docs/components/alert-dialog/README.md), [Drawer](https://github.com/flowstack-ui/brick/blob/main/docs/components/drawer/README.md) |
-| Navigation and layout | [Appearance](https://github.com/flowstack-ui/brick/blob/main/docs/components/appearance/README.md), [Breadcrumb](https://github.com/flowstack-ui/brick/blob/main/docs/components/breadcrumb/README.md), [Tabs](https://github.com/flowstack-ui/brick/blob/main/docs/components/tabs/README.md), [Navigation Menu](https://github.com/flowstack-ui/brick/blob/main/docs/components/navigation-menu/README.md), [Bottom Navigation](https://github.com/flowstack-ui/brick/blob/main/docs/components/bottom-navigation/README.md), [Link](https://github.com/flowstack-ui/brick/blob/main/docs/components/link/README.md), [Nav List](https://github.com/flowstack-ui/brick/blob/main/docs/components/nav-list/README.md), [Sidebar](https://github.com/flowstack-ui/brick/blob/main/docs/components/sidebar/README.md), [App Bar](https://github.com/flowstack-ui/brick/blob/main/docs/components/app-bar/README.md), [Stack](https://github.com/flowstack-ui/brick/blob/main/docs/components/stack/README.md), [Grid](https://github.com/flowstack-ui/brick/blob/main/docs/components/grid/README.md), [Container](https://github.com/flowstack-ui/brick/blob/main/docs/components/container/README.md), [Section](https://github.com/flowstack-ui/brick/blob/main/docs/components/section/README.md), [Frame](https://github.com/flowstack-ui/brick/blob/main/docs/components/frame/README.md), [Show](https://github.com/flowstack-ui/brick/blob/main/docs/components/show/README.md), [Hide](https://github.com/flowstack-ui/brick/blob/main/docs/components/hide/README.md), [Surface](https://github.com/flowstack-ui/brick/blob/main/docs/components/surface/README.md), [Scroll Area](https://github.com/flowstack-ui/brick/blob/main/docs/components/scroll-area/README.md) |
+| Navigation and layout | [Appearance](https://github.com/flowstack-ui/brick/blob/main/docs/components/appearance/README.md), [Breadcrumb](https://github.com/flowstack-ui/brick/blob/main/docs/components/breadcrumb/README.md), [Tabs](https://github.com/flowstack-ui/brick/blob/main/docs/components/tabs/README.md), [Navigation Menu](https://github.com/flowstack-ui/brick/blob/main/docs/components/navigation-menu/README.md), [Bottom Navigation](https://github.com/flowstack-ui/brick/blob/main/docs/components/bottom-navigation/README.md), [Link](https://github.com/flowstack-ui/brick/blob/main/docs/components/link/README.md), [Link Box](https://github.com/flowstack-ui/brick/blob/main/docs/components/link-box/README.md), [Nav List](https://github.com/flowstack-ui/brick/blob/main/docs/components/nav-list/README.md), [Sidebar](https://github.com/flowstack-ui/brick/blob/main/docs/components/sidebar/README.md), [App Bar](https://github.com/flowstack-ui/brick/blob/main/docs/components/app-bar/README.md), [Stack](https://github.com/flowstack-ui/brick/blob/main/docs/components/stack/README.md), [Group](https://github.com/flowstack-ui/brick/blob/main/docs/components/group/README.md), [Grid](https://github.com/flowstack-ui/brick/blob/main/docs/components/grid/README.md), [Container](https://github.com/flowstack-ui/brick/blob/main/docs/components/container/README.md), [Section](https://github.com/flowstack-ui/brick/blob/main/docs/components/section/README.md), [Frame](https://github.com/flowstack-ui/brick/blob/main/docs/components/frame/README.md), [Bleed](https://github.com/flowstack-ui/brick/blob/main/docs/components/bleed/README.md), [Show](https://github.com/flowstack-ui/brick/blob/main/docs/components/show/README.md), [Hide](https://github.com/flowstack-ui/brick/blob/main/docs/components/hide/README.md), [Surface](https://github.com/flowstack-ui/brick/blob/main/docs/components/surface/README.md), [Scroll Area](https://github.com/flowstack-ui/brick/blob/main/docs/components/scroll-area/README.md) |
 | Depth layout | [ZStack](https://github.com/flowstack-ui/brick/blob/main/docs/components/z-stack/README.md) |
 
 ## Package boundary

package/dist/agents/accordion.json

@@ -26,7 +26,8 @@
   "composition": [
     "Compose Root > Item > Header > Trigger with Indicator inside Trigger, then place Content > ContentInner as Header's sibling inside the same Item.",
     "Put visible panel padding and ordinary Brick layout in ContentInner so Content remains Atom's measured motion boundary.",
-    "Choose Header levels from the host document and use Content landmark=false when many regions would make landmark navigation noisy."
+    "Choose Header levels from the host document and use Content landmark=false when many regions would make landmark navigation noisy.",
+    "Use the default decorative Indicator when the standard down-when-closed and up-when-open state cue fits; authored Indicator children may replace only the artwork."
   ],
   "rules": [
     {
@@ -53,6 +54,16 @@
       "id": "accordion-css",
       "level": "must",
       "statement": "Load styles.css or core.css plus accordion.css."
+    },
+    {
+      "id": "accordion-grouped-focus-geometry",
+      "level": "must",
+      "statement": "Keep grouped trigger corners continuous with the enclosing Root and verify that the complete focus ring remains visible at the first and last group edges."
+    },
+    {
+      "id": "accordion-indicator-direction",
+      "level": "must",
+      "statement": "Keep the default Indicator pointing down while closed and up while open in both LTR and RTL; use custom decorative artwork only for a deliberate alternate state language."
     }
   ],
   "commonMistakes": [
@@ -63,12 +74,16 @@
     {
       "mistake": "Accepting the default heading level or region landmark count without checking the host page.",
       "correction": "Set Header to the correct document level and use landmark=false when many open panels would create excessive landmarks."
+    },
+    {
+      "mistake": "Rounding every Trigger in one outlined group or clipping Root paint so the first and last Trigger focus rings are cut off.",
+      "correction": "Treat Root as the group silhouette, keep interior Trigger edges square, round only exposed group corners, and preserve visible focus outside the group boundary."
     }
   ],
   "validation": [
     "Check complete anatomy, unique values, heading order, Trigger names, linked panel relationships, landmark usefulness, and CSS delivery.",
     "Test Enter, Space, Home, End, orientation-aware arrows, RTL, disabled and locked-open state, single and multiple modes, and controlled and uncontrolled state.",
-    "Test initial open, open and close motion, dynamic panel measurement, reduced motion, focus geometry, long labels, narrow widths, zoom, and forced colors."
+    "Test initial open, open and close motion, down/up Indicator state, dynamic panel measurement, reduced motion, complete first and last Trigger focus geometry, continuous grouped corners, long labels, narrow widths, zoom, and forced colors."
   ],
   "related": [
     "collapsible",

package/dist/agents/accordion.md

@@ -19,6 +19,7 @@ Present a finished group of related disclosure sections while Atom owns expanded
 - Compose Root > Item > Header > Trigger with Indicator inside Trigger, then place Content > ContentInner as Header's sibling inside the same Item.
 - Put visible panel padding and ordinary Brick layout in ContentInner so Content remains Atom's measured motion boundary.
 - Choose Header levels from the host document and use Content landmark=false when many regions would make landmark navigation noisy.
+- Use the default decorative Indicator when the standard down-when-closed and up-when-open state cue fits; authored Indicator children may replace only the artwork.
 
 ## Rules
 
@@ -27,17 +28,20 @@ Present a finished group of related disclosure sections while Atom owns expanded
 - **MUST:** Keep visible padding and panel layout in ContentInner rather than Content so Atom can measure and animate the panel accurately.
 - **MUST:** Choose Header level from the page outline and opt out of optional Content landmarks when the resulting region count would be noisy.
 - **MUST:** Load styles.css or core.css plus accordion.css.
+- **MUST:** Keep grouped trigger corners continuous with the enclosing Root and verify that the complete focus ring remains visible at the first and last group edges.
+- **MUST:** Keep the default Indicator pointing down while closed and up while open in both LTR and RTL; use custom decorative artwork only for a deliberate alternate state language.
 
 ## Common mistakes
 
 - **Avoid:** Using Accordion for one disclosure, nesting a finished Button in Trigger, or placing padding directly on Content. **Instead:** Use Collapsible for one region, let Trigger own its visual recipe, and put panel spacing in ContentInner.
 - **Avoid:** Accepting the default heading level or region landmark count without checking the host page. **Instead:** Set Header to the correct document level and use landmark=false when many open panels would create excessive landmarks.
+- **Avoid:** Rounding every Trigger in one outlined group or clipping Root paint so the first and last Trigger focus rings are cut off. **Instead:** Treat Root as the group silhouette, keep interior Trigger edges square, round only exposed group corners, and preserve visible focus outside the group boundary.
 
 ## Validation checklist
 
 - Check complete anatomy, unique values, heading order, Trigger names, linked panel relationships, landmark usefulness, and CSS delivery.
 - Test Enter, Space, Home, End, orientation-aware arrows, RTL, disabled and locked-open state, single and multiple modes, and controlled and uncontrolled state.
-- Test initial open, open and close motion, dynamic panel measurement, reduced motion, focus geometry, long labels, narrow widths, zoom, and forced colors.
+- Test initial open, open and close motion, down/up Indicator state, dynamic panel measurement, reduced motion, complete first and last Trigger focus geometry, continuous grouped corners, long labels, narrow widths, zoom, and forced colors.
 
 ## Related guidance
 

package/dist/agents/alert-dialog.json

@@ -0,0 +1,111 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "alert-dialog",
+  "name": "AlertDialog",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished urgent or consequential decision that requires an explicit response, safe initial focus, and non-dismissible backdrop behavior.",
+  "useWhen": [
+    "A destructive, irreversible, security-sensitive, unsaved-change, or otherwise consequential action requires a safe cancellation choice and an explicit response before continuing."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The surface presents an ordinary form, information, or multi-step task rather than one urgent decision.",
+      "useInstead": "Dialog"
+    },
+    {
+      "condition": "The content is an anchored utility panel or passive feedback that does not require a response.",
+      "useInstead": "Popover or Menu, or Toast or Status"
+    }
+  ],
+  "composition": [
+    "Compose AlertDialog.Root with AlertDialog.Trigger and AlertDialog.Portal; inside Portal keep AlertDialog.Overlay and AlertDialog.Content as siblings. Inside Content, arrange Header with the required Title and Description, use a short optional Body only when needed, and place Cancel before Action in Footer.",
+    "Compose Brick Button through Cancel and Action so each response keeps its visual and behavioral role. When a local Appearance scope owns the trigger, portal into that scope or apply the same Appearance to the portalled visual root."
+  ],
+  "rules": [
+    {
+      "id": "alert-dialog-consequential-only",
+      "level": "must",
+      "statement": "Reserve AlertDialog for one urgent or consequential decision; use Dialog for ordinary tasks, forms, or complex workflows."
+    },
+    {
+      "id": "alert-dialog-required-semantics",
+      "level": "must",
+      "statement": "Keep the alertdialog semantics and provide both an accessible name with visible Title or native labeling and an accessible description with Description or native aria-describedby."
+    },
+    {
+      "id": "alert-dialog-safe-cancel",
+      "level": "must",
+      "statement": "Place a visible enabled Cancel before Action and make Cancel the safe initial focus target for consequential actions unless an explicitly safer workflow target is supplied."
+    },
+    {
+      "id": "alert-dialog-no-backdrop-dismissal",
+      "level": "must",
+      "statement": "Do not add backdrop dismissal; require Cancel, Action, or an intentionally permitted Escape path to resolve the decision."
+    },
+    {
+      "id": "alert-dialog-overlay-content-siblings",
+      "level": "must",
+      "statement": "Render Overlay and Content as siblings inside Portal and rely on AlertDialog's inherited modal focus, isolation, scroll, and top-layer ownership."
+    },
+    {
+      "id": "alert-dialog-action-tone",
+      "level": "must",
+      "statement": "Apply destructive or cautionary tone to the Action Button, not to the entire dialog surface, and keep Cancel visually safe and unambiguous."
+    },
+    {
+      "id": "alert-dialog-controlled-action",
+      "level": "must",
+      "statement": "When an Action starts asynchronous validation or work, prevent its automatic close until the application confirms success, preserves errors, and intentionally updates open state."
+    },
+    {
+      "id": "alert-dialog-application-ownership",
+      "level": "must",
+      "statement": "Keep permissions, authorization, persistence, pending state, error recovery, and the actual destructive operation in application code; AlertDialog owns presentation and interaction semantics only."
+    },
+    {
+      "id": "alert-dialog-short-content",
+      "level": "should",
+      "statement": "Keep the decision concise; use the bounded Body only for essential supporting context and move complex forms or third-party interactive portals to Dialog."
+    },
+    {
+      "id": "alert-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": "alert-dialog-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus alert-dialog.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using AlertDialog for an ordinary form, focusing the destructive Action first, omitting the description, or making the backdrop dismiss the choice.",
+      "correction": "Use Dialog for ordinary tasks; for consequential decisions provide Title, Description, safe Cancel focus, explicit Action, and no backdrop dismissal."
+    },
+    {
+      "mistake": "Closing immediately while an asynchronous destructive operation is still pending or styling the whole surface as destructive.",
+      "correction": "Prevent automatic close until application work succeeds and communicate danger through the Action Button and concise decision copy."
+    }
+  ],
+  "validation": [
+    "Verify alertdialog role, accessible name and description, visible Cancel before Action, safe Cancel initial focus for keyboard, pointer, touch, and programmatic opening, Tab containment, and that backdrop interaction cannot close the layer.",
+    "Verify Cancel and Action close reasons, prevented asynchronous Action behavior, pending and error recovery, controlled state, intentionally permitted Escape behavior, nested top-layer ownership, scroll lock, background isolation, exit presence, and focus restoration.",
+    "Verify long-label footer reflow, optional Body overflow, zoom, narrow and short viewports, reduced motion, forced colors, light and dark appearance on portalled Content, and required CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "alert-dialog",
+      "versionPolicy": "installed-exact"
+    },
+    "dialog",
+    "button",
+    "popover",
+    "toast",
+    "appearance"
+  ]
+}

package/dist/agents/alert-dialog.md

@@ -0,0 +1,53 @@
+# AlertDialog agent guide
+
+## Purpose
+
+Present a finished urgent or consequential decision that requires an explicit response, safe initial focus, and non-dismissible backdrop behavior.
+
+## Use when
+
+- A destructive, irreversible, security-sensitive, unsaved-change, or otherwise consequential action requires a safe cancellation choice and an explicit response before continuing.
+
+## Choose something else when
+
+- The surface presents an ordinary form, information, or multi-step task rather than one urgent decision. Use Dialog.
+- The content is an anchored utility panel or passive feedback that does not require a response. Use Popover or Menu, or Toast or Status.
+
+## Required composition
+
+- Compose AlertDialog.Root with AlertDialog.Trigger and AlertDialog.Portal; inside Portal keep AlertDialog.Overlay and AlertDialog.Content as siblings. Inside Content, arrange Header with the required Title and Description, use a short optional Body only when needed, and place Cancel before Action in Footer.
+- Compose Brick Button through Cancel and Action so each response keeps its visual and behavioral role. When a local Appearance scope owns the trigger, portal into that scope or apply the same Appearance to the portalled visual root.
+
+## Rules
+
+- **MUST:** Reserve AlertDialog for one urgent or consequential decision; use Dialog for ordinary tasks, forms, or complex workflows.
+- **MUST:** Keep the alertdialog semantics and provide both an accessible name with visible Title or native labeling and an accessible description with Description or native aria-describedby.
+- **MUST:** Place a visible enabled Cancel before Action and make Cancel the safe initial focus target for consequential actions unless an explicitly safer workflow target is supplied.
+- **MUST:** Do not add backdrop dismissal; require Cancel, Action, or an intentionally permitted Escape path to resolve the decision.
+- **MUST:** Render Overlay and Content as siblings inside Portal and rely on AlertDialog's inherited modal focus, isolation, scroll, and top-layer ownership.
+- **MUST:** Apply destructive or cautionary tone to the Action Button, not to the entire dialog surface, and keep Cancel visually safe and unambiguous.
+- **MUST:** When an Action starts asynchronous validation or work, prevent its automatic close until the application confirms success, preserves errors, and intentionally updates open state.
+- **MUST:** Keep permissions, authorization, persistence, pending state, error recovery, and the actual destructive operation in application code; AlertDialog owns presentation and interaction semantics only.
+- **SHOULD:** Keep the decision concise; use the bounded Body only for essential supporting context and move complex forms or third-party interactive portals to Dialog.
+- **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 alert-dialog.css.
+
+## Common mistakes
+
+- **Avoid:** Using AlertDialog for an ordinary form, focusing the destructive Action first, omitting the description, or making the backdrop dismiss the choice. **Instead:** Use Dialog for ordinary tasks; for consequential decisions provide Title, Description, safe Cancel focus, explicit Action, and no backdrop dismissal.
+- **Avoid:** Closing immediately while an asynchronous destructive operation is still pending or styling the whole surface as destructive. **Instead:** Prevent automatic close until application work succeeds and communicate danger through the Action Button and concise decision copy.
+
+## Validation checklist
+
+- Verify alertdialog role, accessible name and description, visible Cancel before Action, safe Cancel initial focus for keyboard, pointer, touch, and programmatic opening, Tab containment, and that backdrop interaction cannot close the layer.
+- Verify Cancel and Action close reasons, prevented asynchronous Action behavior, pending and error recovery, controlled state, intentionally permitted Escape behavior, nested top-layer ownership, scroll lock, background isolation, exit presence, and focus restoration.
+- Verify long-label footer reflow, optional Body overflow, zoom, narrow and short viewports, reduced motion, forced colors, light and dark appearance on portalled Content, and required CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/alert-dialog`
+- `dialog`
+- `button`
+- `popover`
+- `toast`
+- `appearance`

package/dist/agents/app-bar.json

@@ -16,7 +16,7 @@
     }
   ],
   "composition": [
-    "Root renders a semantic header by default. For a contained full-bleed bar, compose Root > Container > Toolbar > Start, Center, and End; omit Container only when Toolbar should use the full available width."
+    "Root renders a semantic header by default. For a contained full-bleed bar, compose Root > Container > Toolbar inset=none > Start, Center, and End so Container alone owns the page gutter; omit Container only when Toolbar should use the full available width."
   ],
   "rules": [
     {
@@ -27,7 +27,7 @@
     {
       "id": "appbar-container-owner",
       "level": "must",
-      "statement": "Place Container between Root and Toolbar when the AppBar surface should remain full bleed while its content uses a bounded measure; do not cap Root itself or recreate Toolbar geometry."
+      "statement": "Place Container between Root and Toolbar when the AppBar surface should remain full bleed while its content uses a bounded measure, and set Toolbar inset to none so Container alone owns the gutter; do not cap Root itself or recreate Toolbar geometry."
     },
     {
       "id": "appbar-structural-toolbar",
@@ -52,13 +52,14 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Hand-building a header row with div and flex CSS, assuming Root defaults to div, capping the full AppBar surface with application width CSS, or expecting AppBar to create menus and breakpoints.",
-      "correction": "Use Root's default header for banner content, place Container around Toolbar when content needs a measure, and compose the dedicated navigation, layout, and visibility owners inside it."
+      "mistake": "Hand-building a header row with div and flex CSS, assuming Root defaults to div, capping the full AppBar surface with application width CSS, double-insetting contained Toolbar content, or expecting AppBar to create menus and breakpoints.",
+      "correction": "Use Root's default header for banner content, place Container around Toolbar with Toolbar inset set to none when Container owns the gutter, and compose the dedicated navigation, layout, and visibility owners inside it."
     }
   ],
   "validation": [
     "Check the final Root element and landmark ownership, including non-banner composed hosts.",
     "Check geometric centering with unequal side content, truncation, zoom, narrow widths, and RTL.",
+    "Confirm contained App Bars have one page-gutter owner rather than stacked Container and Toolbar insets.",
     "Confirm landmark names, actions, navigation, and modular CSS are complete."
   ],
   "related": [

package/dist/agents/app-bar.md

@@ -14,12 +14,12 @@ Provide a finished top surface and one-row start, geometrically centered, and en
 
 ## Required composition
 
-- Root renders a semantic header by default. For a contained full-bleed bar, compose Root > Container > Toolbar > Start, Center, and End; omit Container only when Toolbar should use the full available width.
+- Root renders a semantic header by default. For a contained full-bleed bar, compose Root > Container > Toolbar inset=none > Start, Center, and End so Container alone owns the page gutter; omit Container only when Toolbar should use the full available width.
 
 ## Rules
 
 - **MUST:** Keep AppBar.Root's default header when it owns page or application banner content; use asChild or render only when another semantic or neutral host is intentionally required, such as non-banner chrome inside a Drawer.
-- **MUST:** Place Container between Root and Toolbar when the AppBar surface should remain full bleed while its content uses a bounded measure; do not cap Root itself or recreate Toolbar geometry.
+- **MUST:** Place Container between Root and Toolbar when the AppBar surface should remain full bleed while its content uses a bounded measure, and set Toolbar inset to none so Container alone owns the gutter; do not cap Root itself or recreate Toolbar geometry.
 - **MUST:** Do not treat AppBar.Toolbar as an ARIA toolbar; compose Toolbar for grouped-control keyboard behavior.
 - **MUST:** Keep application-specific visibility and wrapping policy outside AppBar and implement it with Brick responsive/layout components.
 - **MUST:** When application layout references an App Bar density measurement, use the matching public comfortable or compact minimum block-size token instead of repeating Brick's value; allow the rendered bar and adjacent content to grow under zoom or enlarged content.
@@ -27,12 +27,13 @@ Provide a finished top surface and one-row start, geometrically centered, and en
 
 ## Common mistakes
 
-- **Avoid:** Hand-building a header row with div and flex CSS, assuming Root defaults to div, capping the full AppBar surface with application width CSS, or expecting AppBar to create menus and breakpoints. **Instead:** Use Root's default header for banner content, place Container around Toolbar when content needs a measure, and compose the dedicated navigation, layout, and visibility owners inside it.
+- **Avoid:** Hand-building a header row with div and flex CSS, assuming Root defaults to div, capping the full AppBar surface with application width CSS, double-insetting contained Toolbar content, or expecting AppBar to create menus and breakpoints. **Instead:** Use Root's default header for banner content, place Container around Toolbar with Toolbar inset set to none when Container owns the gutter, and compose the dedicated navigation, layout, and visibility owners inside it.
 
 ## Validation checklist
 
 - Check the final Root element and landmark ownership, including non-banner composed hosts.
 - Check geometric centering with unequal side content, truncation, zoom, narrow widths, and RTL.
+- Confirm contained App Bars have one page-gutter owner rather than stacked Container and Toolbar insets.
 - Confirm landmark names, actions, navigation, and modular CSS are complete.
 
 ## Related guidance

package/dist/agents/aspect-ratio.json

@@ -0,0 +1,80 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "aspect-ratio",
+  "name": "AspectRatio",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Reserve finished stable width-to-height geometry and optional neutral frame paint for media, embeds, or placeholders while Atom owns the authoritative ratio and children retain all semantics and interaction.",
+  "useWhen": [
+    "An image, video, iframe, preview, placeholder, or authored content region needs a predictable box before content loads or a consistent clipped frame."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Intrinsic dimensions already provide the intended layout, image loading and fallback behavior is needed, the content is a general panel, or a loading placeholder owns the job.",
+      "useInstead": "the semantic native media element, Image, Surface, or Skeleton"
+    }
+  ],
+  "composition": [
+    "Wrap one semantic content region in AspectRatio.Root, pass a finite positive width-divided-by-height ratio when 16/9 is not correct, and choose plain, subtle, or outline plus radius and overflow. Size a child explicitly when it should fill the reserved box.",
+    "Keep image alt text, iframe title, media controls and captions, focus, loading, and interaction on the child. Choose overflow=visible or an inset child focus treatment whenever clipping would hide focus."
+  ],
+  "rules": [
+    {
+      "id": "aspect-ratio-geometry-only",
+      "level": "must",
+      "statement": "Treat Root as geometry and optional frame paint only; do not assign it media roles, accessible names, loading state, focus, or interaction owned by its child."
+    },
+    {
+      "id": "aspect-ratio-value",
+      "level": "must",
+      "statement": "Express ratio as width divided by height and pass a finite positive number; understand that Atom normalizes zero, negative, NaN, and infinite values to 16/9."
+    },
+    {
+      "id": "aspect-ratio-semantics",
+      "level": "must",
+      "statement": "Give contained images appropriate alt text, iframes descriptive titles, and interactive media its native controls, keyboard behavior, captions, and visible focus."
+    },
+    {
+      "id": "aspect-ratio-authority",
+      "level": "must",
+      "statement": "Do not override style.aspectRatio because Atom's ratio prop remains authoritative; use Brick variant, radius, overflow, and public frame variables for visual customization."
+    },
+    {
+      "id": "aspect-ratio-responsive",
+      "level": "must",
+      "statement": "Keep Root contained at available inline size and author responsive ratio changes outside the scalar prop; verify clipped children, full radius, narrow widths, and focus at zoom rather than assuming Root stretches or crops them."
+    },
+    {
+      "id": "aspect-ratio-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus aspect-ratio.css and the stylesheet for every rendered child component."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Treating AspectRatio as Image or video, moving the child's name to Root, passing height divided by width, or relying on invalid ratio input.",
+      "correction": "Keep Root structural, retain semantic native children, and pass a deliberate positive width/height ratio."
+    },
+    {
+      "mistake": "Assuming Root sizes or object-fits the child or clipping a child's focus ring.",
+      "correction": "Size and fit the child explicitly and use visible overflow or inset focus when interaction reaches the frame edge."
+    }
+  ],
+  "validation": [
+    "Verify default, square, portrait, and wide ratios; invalid normalization; reserved layout before loading; all variants/radii/overflow modes; authoritative ratio with other consumer styles preserved; native props; refs; and composition.",
+    "Inspect final DOM for no Root role or ARIA and correct child image, iframe, video, keyboard, focus, captions, and loading semantics.",
+    "Verify narrow width, responsive external CSS, zoom, full-radius geometry, clipping, RTL neutrality, light/dark appearance, forced colors, and focus visibility for interactive children."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "aspect-ratio",
+      "versionPolicy": "installed-exact"
+    },
+    "image",
+    "surface",
+    "skeleton"
+  ]
+}

package/dist/agents/aspect-ratio.md

@@ -0,0 +1,45 @@
+# AspectRatio agent guide
+
+## Purpose
+
+Reserve finished stable width-to-height geometry and optional neutral frame paint for media, embeds, or placeholders while Atom owns the authoritative ratio and children retain all semantics and interaction.
+
+## Use when
+
+- An image, video, iframe, preview, placeholder, or authored content region needs a predictable box before content loads or a consistent clipped frame.
+
+## Choose something else when
+
+- Intrinsic dimensions already provide the intended layout, image loading and fallback behavior is needed, the content is a general panel, or a loading placeholder owns the job. Use the semantic native media element, Image, Surface, or Skeleton.
+
+## Required composition
+
+- Wrap one semantic content region in AspectRatio.Root, pass a finite positive width-divided-by-height ratio when 16/9 is not correct, and choose plain, subtle, or outline plus radius and overflow. Size a child explicitly when it should fill the reserved box.
+- Keep image alt text, iframe title, media controls and captions, focus, loading, and interaction on the child. Choose overflow=visible or an inset child focus treatment whenever clipping would hide focus.
+
+## Rules
+
+- **MUST:** Treat Root as geometry and optional frame paint only; do not assign it media roles, accessible names, loading state, focus, or interaction owned by its child.
+- **MUST:** Express ratio as width divided by height and pass a finite positive number; understand that Atom normalizes zero, negative, NaN, and infinite values to 16/9.
+- **MUST:** Give contained images appropriate alt text, iframes descriptive titles, and interactive media its native controls, keyboard behavior, captions, and visible focus.
+- **MUST:** Do not override style.aspectRatio because Atom's ratio prop remains authoritative; use Brick variant, radius, overflow, and public frame variables for visual customization.
+- **MUST:** Keep Root contained at available inline size and author responsive ratio changes outside the scalar prop; verify clipped children, full radius, narrow widths, and focus at zoom rather than assuming Root stretches or crops them.
+- **MUST:** Load styles.css or core.css plus aspect-ratio.css and the stylesheet for every rendered child component.
+
+## Common mistakes
+
+- **Avoid:** Treating AspectRatio as Image or video, moving the child's name to Root, passing height divided by width, or relying on invalid ratio input. **Instead:** Keep Root structural, retain semantic native children, and pass a deliberate positive width/height ratio.
+- **Avoid:** Assuming Root sizes or object-fits the child or clipping a child's focus ring. **Instead:** Size and fit the child explicitly and use visible overflow or inset focus when interaction reaches the frame edge.
+
+## Validation checklist
+
+- Verify default, square, portrait, and wide ratios; invalid normalization; reserved layout before loading; all variants/radii/overflow modes; authoritative ratio with other consumer styles preserved; native props; refs; and composition.
+- Inspect final DOM for no Root role or ARIA and correct child image, iframe, video, keyboard, focus, captions, and loading semantics.
+- Verify narrow width, responsive external CSS, zoom, full-radius geometry, clipping, RTL neutrality, light/dark appearance, forced colors, and focus visibility for interactive children.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/aspect-ratio`
+- `image`
+- `surface`
+- `skeleton`

package/dist/agents/avatar.json

@@ -0,0 +1,92 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "avatar",
+  "name": "Avatar",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present one compact person or entity identity with a finished fixed-square image/fallback recipe and optional visual status ring.",
+  "useWhen": [
+    "A person, organization, workspace, or other named entity needs a compact fixed-square identity token with explicit fallback content."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A larger editorial or profile portrait needs an authored aspect ratio, crop, focal position, or responsive measure.",
+      "useInstead": "Image"
+    },
+    {
+      "condition": "A count or dot must attach to an identity.",
+      "useInstead": "NotificationBadge composed around Avatar"
+    }
+  ],
+  "composition": [
+    "Provide explicit alt and fallback; keep Avatar passive and let an owning Button or Link provide interaction, focus, and the functional accessible name.",
+    "Keep visible identity or status text nearby when the image or status ring alone would be ambiguous or consequential."
+  ],
+  "rules": [
+    {
+      "id": "avatar-compact-identity",
+      "level": "must",
+      "statement": "Use Avatar for compact fixed-square identity presentation, not generic media or larger editorial portraits."
+    },
+    {
+      "id": "avatar-alt-context",
+      "level": "must",
+      "statement": "Decide alt from context: preserve meaningful identity when Avatar adds it, and use alt=\"\" only when adjacent text or the owning control already supplies the same identity."
+    },
+    {
+      "id": "avatar-source-state",
+      "level": "must",
+      "statement": "Pass the same source to the Atom-backed Root and Image path, preserve idle/loading/loaded/error state, and keep explicit fallback content durable through missing, changed, delayed, and failed images."
+    },
+    {
+      "id": "avatar-explicit-fallback",
+      "level": "must",
+      "statement": "Supply explicit localized fallback content; do not generate initials or infer identity from a filename."
+    },
+    {
+      "id": "avatar-passive",
+      "level": "must",
+      "statement": "Keep Avatar passive; wrap it with the public Button or Link that owns any action or destination."
+    },
+    {
+      "id": "avatar-status-text",
+      "level": "must",
+      "statement": "Provide separate accessible status text when a status ring communicates meaningful availability."
+    },
+    {
+      "id": "avatar-named-size",
+      "level": "must",
+      "statement": "Choose the nearest named Avatar size, including 2xl through 5xl for larger square profile identities, instead of overriding --brick-avatar-size inline; use Image for authored non-square portrait media."
+    },
+    {
+      "id": "avatar-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus avatar.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Forcing a large 4:5 profile portrait into Avatar, using alt=\"\" merely because a name appears somewhere nearby, generating fallback initials inside Brick, or treating the status ring as an announcement.",
+      "correction": "Use Image for authored portrait media, make the alt decision from the specific context, provide explicit fallback content, and keep meaningful status in text."
+    }
+  ],
+  "validation": [
+    "Check missing, idle, loading, loaded, changed-source, and error paths; delayed fallback timing; fixed square size; crop; informative and decorative naming; passive semantics; nearby identity/status text; light/dark/forced colors; zoom; and RTL.",
+    "Confirm a named Avatar size is used, CSS is loaded, and any owning Button, Link, or NotificationBadge preserves its own public contract."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "avatar",
+      "versionPolicy": "installed-exact"
+    },
+    "image",
+    "button",
+    "link",
+    "notification-badge",
+    "badge",
+    "status"
+  ]
+}