@flowstack-ui/brick 0.1.9 → 0.1.12

package/dist/agents/switch.json

@@ -0,0 +1,92 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "switch",
+  "name": "Switch",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished immediately applied on/off setting while Atom owns switch semantics, controlled or uncontrolled state, keyboard activation, validation, and optional form participation.",
+  "useWhen": [
+    "A setting becomes active or inactive immediately when the user operates it."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The choice is a form answer applied later, a command whose pressed state remains active, or one of several exclusive values.",
+      "useInstead": "Checkbox, Toggle, or RadioGroup"
+    }
+  ],
+  "composition": [
+    "Give Switch.Root a stable visible or native accessible setting name and add Switch.Thumb as its decorative movable part. Compose Root in Field when visible Label, Description, Error, required, or invalid context is needed; use name, value, and form when checked state must submit.",
+    "Choose Root size sm, md, or lg for the finished track, thumb, travel, and target geometry. Keep Thumb decorative and let Atom state attributes drive Brick paint."
+  ],
+  "rules": [
+    {
+      "id": "switch-immediate",
+      "level": "must",
+      "statement": "Use Switch only for an immediately applied on/off setting; use Checkbox for a deferred form answer and Toggle for a persistent pressed command."
+    },
+    {
+      "id": "switch-name",
+      "level": "must",
+      "statement": "Give Root a complete stable accessible setting name with visible Field Label, native labeling, aria-label, or aria-labelledby; Thumb remains decorative and aria-hidden."
+    },
+    {
+      "id": "switch-state",
+      "level": "must",
+      "statement": "Use checked with onCheckedChange for controlled state or defaultChecked for uncontrolled state and preserve role=switch with boolean aria-checked."
+    },
+    {
+      "id": "switch-readonly",
+      "level": "must",
+      "statement": "Use readOnly when the setting must stay focusable while Enter, Space, pointer, and custom-element activation cannot change state; do not replace it with disabled."
+    },
+    {
+      "id": "switch-form",
+      "level": "must",
+      "statement": "Preserve named checked-value submission, required validity, Field state and descriptions, validation focus, external form association, and uncontrolled reset when form behavior applies."
+    },
+    {
+      "id": "switch-state-paint",
+      "level": "must",
+      "statement": "Use Brick's canonical checked, unchecked, focus, disabled, read-only, and invalid paint; invalid changes the boundary without replacing the checked meaning, and mixed or loading state is unsupported."
+    },
+    {
+      "id": "switch-responsive",
+      "level": "should",
+      "statement": "Keep intrinsic geometry and complete target size, allow surrounding label text to reflow, and verify logical thumb travel in RTL without reversing on/off meaning."
+    },
+    {
+      "id": "switch-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus switch.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Switch for a submit-later checkbox or pressed command, relying on Thumb as the accessible control, or changing the setting label between states.",
+      "correction": "Choose by timing and semantics, name Root directly, keep Thumb decorative, and preserve one stable setting name."
+    },
+    {
+      "mistake": "Using disabled when the value should remain discoverable and read-only or inventing mixed, loading, tone, or shape props.",
+      "correction": "Use readOnly for locked focusable state and stay within the canonical binary visual recipe."
+    }
+  ],
+  "validation": [
+    "Verify accessible name, role and aria-checked, controlled and uncontrolled updates, pointer, Enter, and Space activation, disabled and read-only behavior, Thumb state inheritance, and native, asChild, and render semantics.",
+    "Verify named checked-value submission, required validity with and without name, invalid and Field descriptions, validation focus, external form association, and uncontrolled reset.",
+    "Verify three sizes, checked and unchecked contrast, focus, disabled, read-only and invalid paint, intrinsic and narrow layout, mobile targets, 200% text and 400% zoom, RTL travel, reduced motion, forced colors, and complete CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "switch",
+      "versionPolicy": "installed-exact"
+    },
+    "checkbox",
+    "toggle",
+    "radio-group",
+    "field",
+    "form"
+  ]
+}

package/dist/agents/switch.md

@@ -0,0 +1,49 @@
+# Switch agent guide
+
+## Purpose
+
+Present a finished immediately applied on/off setting while Atom owns switch semantics, controlled or uncontrolled state, keyboard activation, validation, and optional form participation.
+
+## Use when
+
+- A setting becomes active or inactive immediately when the user operates it.
+
+## Choose something else when
+
+- The choice is a form answer applied later, a command whose pressed state remains active, or one of several exclusive values. Use Checkbox, Toggle, or RadioGroup.
+
+## Required composition
+
+- Give Switch.Root a stable visible or native accessible setting name and add Switch.Thumb as its decorative movable part. Compose Root in Field when visible Label, Description, Error, required, or invalid context is needed; use name, value, and form when checked state must submit.
+- Choose Root size sm, md, or lg for the finished track, thumb, travel, and target geometry. Keep Thumb decorative and let Atom state attributes drive Brick paint.
+
+## Rules
+
+- **MUST:** Use Switch only for an immediately applied on/off setting; use Checkbox for a deferred form answer and Toggle for a persistent pressed command.
+- **MUST:** Give Root a complete stable accessible setting name with visible Field Label, native labeling, aria-label, or aria-labelledby; Thumb remains decorative and aria-hidden.
+- **MUST:** Use checked with onCheckedChange for controlled state or defaultChecked for uncontrolled state and preserve role=switch with boolean aria-checked.
+- **MUST:** Use readOnly when the setting must stay focusable while Enter, Space, pointer, and custom-element activation cannot change state; do not replace it with disabled.
+- **MUST:** Preserve named checked-value submission, required validity, Field state and descriptions, validation focus, external form association, and uncontrolled reset when form behavior applies.
+- **MUST:** Use Brick's canonical checked, unchecked, focus, disabled, read-only, and invalid paint; invalid changes the boundary without replacing the checked meaning, and mixed or loading state is unsupported.
+- **SHOULD:** Keep intrinsic geometry and complete target size, allow surrounding label text to reflow, and verify logical thumb travel in RTL without reversing on/off meaning.
+- **MUST:** Load styles.css or core.css plus switch.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Using Switch for a submit-later checkbox or pressed command, relying on Thumb as the accessible control, or changing the setting label between states. **Instead:** Choose by timing and semantics, name Root directly, keep Thumb decorative, and preserve one stable setting name.
+- **Avoid:** Using disabled when the value should remain discoverable and read-only or inventing mixed, loading, tone, or shape props. **Instead:** Use readOnly for locked focusable state and stay within the canonical binary visual recipe.
+
+## Validation checklist
+
+- Verify accessible name, role and aria-checked, controlled and uncontrolled updates, pointer, Enter, and Space activation, disabled and read-only behavior, Thumb state inheritance, and native, asChild, and render semantics.
+- Verify named checked-value submission, required validity with and without name, invalid and Field descriptions, validation focus, external form association, and uncontrolled reset.
+- Verify three sizes, checked and unchecked contrast, focus, disabled, read-only and invalid paint, intrinsic and narrow layout, mobile targets, 200% text and 400% zoom, RTL travel, reduced motion, forced colors, and complete CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/switch`
+- `checkbox`
+- `toggle`
+- `radio-group`
+- `field`
+- `form`

package/dist/agents/table.json

@@ -0,0 +1,113 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "table",
+  "name": "Table",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present finished static row-and-column relationships with native table semantics while Atom owns the semantic parts and sort metadata.",
+  "useWhen": [
+    "People need to compare values across meaningful columns in pricing, reports, invoices, inventories, audit results, or compact summaries."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The region needs arrow-key cell navigation, row selection, editing, resizing, or another interactive composite model.",
+      "useInstead": "Data Grid or an application-owned data tool"
+    },
+    {
+      "condition": "The content is a sequence without meaningful column relationships or a label/value definition structure.",
+      "useInstead": "List, Grid, Stack, or a semantic definition-list composition"
+    },
+    {
+      "condition": "The narrow layout must convert rows into unrelated cards and no longer preserves column comparison.",
+      "useInstead": "An application-owned alternate view with an explicit responsive policy"
+    }
+  ],
+  "composition": [
+    "Compose optional Container > Root > Caption, Header, Body, and optional Footer; place Row inside each section and Head or Cell inside Row according to native table content rules.",
+    "Use Head with scope=\"row\" for body row labels and keep the default column scope for header cells; use id and headers for complex associations.",
+    "Author Container explicitly when honest comparison needs horizontal overflow, and set the public minimum-inline-size token to the smallest width that preserves the column relationships.",
+    "When Table moves vertically, put the visible border and radius on the stable labelled Scroll Area viewport, use Table variant=line inside it, and keep persistent naming outside the moving viewport with aria-labelledby.",
+    "Put an independently named Button and optional decorative SortIndicator inside the active Head when the application owns sorting."
+  ],
+  "rules": [
+    {
+      "id": "table-native-relationships",
+      "level": "must",
+      "statement": "Preserve native table anatomy and meaningful row and column headers; do not rebuild tabular comparison with generic Grid, Stack, div, or ARIA role substitutes."
+    },
+    {
+      "id": "table-static-boundary",
+      "level": "must",
+      "statement": "Keep Table static and readable; do not add row focus, whole-row activation, selection, arrow-key cell navigation, data mapping, filtering, pagination, editing, or virtualization to Table."
+    },
+    {
+      "id": "table-explicit-overflow",
+      "level": "must",
+      "statement": "Author Table.Container or a separately labelled Scroll Area when wide comparison needs overflow; Root never inserts a wrapper and Table never hides columns or converts them into cards."
+    },
+    {
+      "id": "table-responsive-comparison",
+      "level": "must",
+      "statement": "At narrow widths, preserve header-to-cell relationships, complete material values, and an understandable comparison path rather than merely stacking unrelated plan or record cards."
+    },
+    {
+      "id": "table-vertical-scroll-boundary",
+      "level": "must",
+      "statement": "For bounded vertical scrolling, let the stable Scroll Area viewport own the visible border and radius; do not use a moving Table outline as the scroll-frame boundary."
+    },
+    {
+      "id": "table-sort-ownership",
+      "level": "must",
+      "statement": "Let the application sort data and pass sortDirection only to the active header; SortIndicator is decorative and never supplies the control, name, or behavior."
+    },
+    {
+      "id": "table-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus table.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using generic layout components for a pricing matrix because custom positioning feels easier.",
+      "correction": "Use Table's native Head and Cell relationships, then customize the closed recipes and public Table variables for the product-specific comparison."
+    },
+    {
+      "mistake": "Hiding material columns on mobile or visually cloning labels into card rows.",
+      "correction": "Contain honest horizontal overflow or provide a separately authored application view; do not destroy or fake the native column relationships."
+    },
+    {
+      "mistake": "Making rows hoverable or clickable without a complete interaction owner.",
+      "correction": "Keep rows structural and place independently named Brick links or buttons inside the appropriate cells."
+    },
+    {
+      "mistake": "Using Table variant=outline as the visible frame inside a vertically scrolling viewport.",
+      "correction": "Paint the stable Scroll Area viewport with Surface, use Table variant=line inside it, and connect a persistent external label with aria-labelledby."
+    },
+    {
+      "mistake": "Using a visible recommendation color as the only explanation for a preferred pricing column.",
+      "correction": "Keep the plan label and recommendation reason readable in ordinary text, then use Table paint only as supporting emphasis."
+    }
+  ],
+  "validation": [
+    "Check caption or surrounding naming, header scope, cell associations, source order, plan or record labels, and independently named controls.",
+    "Check Container overflow, the authored minimum comparison width, stable viewport corners during vertical scrolling, sticky header boundaries when used, 320 CSS pixels, zoom, long content, RTL, and no page-level horizontal overflow.",
+    "Check light and dark themes, forced colors, row and column boundaries, recommendation meaning without color, focus visibility for interactive descendants, and CSS delivery.",
+    "Check that sorting, selection, filtering, pagination, data services, and responsive alternate-view policy remain application owned."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "table",
+      "versionPolicy": "installed-exact"
+    },
+    "data-grid",
+    "tree-grid",
+    "scroll-area",
+    "button",
+    "badge",
+    "icon",
+    "text"
+  ]
+}

package/dist/agents/table.md

@@ -0,0 +1,59 @@
+# Table agent guide
+
+## Purpose
+
+Present finished static row-and-column relationships with native table semantics while Atom owns the semantic parts and sort metadata.
+
+## Use when
+
+- People need to compare values across meaningful columns in pricing, reports, invoices, inventories, audit results, or compact summaries.
+
+## Choose something else when
+
+- The region needs arrow-key cell navigation, row selection, editing, resizing, or another interactive composite model. Use Data Grid or an application-owned data tool.
+- The content is a sequence without meaningful column relationships or a label/value definition structure. Use List, Grid, Stack, or a semantic definition-list composition.
+- The narrow layout must convert rows into unrelated cards and no longer preserves column comparison. Use An application-owned alternate view with an explicit responsive policy.
+
+## Required composition
+
+- Compose optional Container > Root > Caption, Header, Body, and optional Footer; place Row inside each section and Head or Cell inside Row according to native table content rules.
+- Use Head with scope="row" for body row labels and keep the default column scope for header cells; use id and headers for complex associations.
+- Author Container explicitly when honest comparison needs horizontal overflow, and set the public minimum-inline-size token to the smallest width that preserves the column relationships.
+- When Table moves vertically, put the visible border and radius on the stable labelled Scroll Area viewport, use Table variant=line inside it, and keep persistent naming outside the moving viewport with aria-labelledby.
+- Put an independently named Button and optional decorative SortIndicator inside the active Head when the application owns sorting.
+
+## Rules
+
+- **MUST:** Preserve native table anatomy and meaningful row and column headers; do not rebuild tabular comparison with generic Grid, Stack, div, or ARIA role substitutes.
+- **MUST:** Keep Table static and readable; do not add row focus, whole-row activation, selection, arrow-key cell navigation, data mapping, filtering, pagination, editing, or virtualization to Table.
+- **MUST:** Author Table.Container or a separately labelled Scroll Area when wide comparison needs overflow; Root never inserts a wrapper and Table never hides columns or converts them into cards.
+- **MUST:** At narrow widths, preserve header-to-cell relationships, complete material values, and an understandable comparison path rather than merely stacking unrelated plan or record cards.
+- **MUST:** For bounded vertical scrolling, let the stable Scroll Area viewport own the visible border and radius; do not use a moving Table outline as the scroll-frame boundary.
+- **MUST:** Let the application sort data and pass sortDirection only to the active header; SortIndicator is decorative and never supplies the control, name, or behavior.
+- **MUST:** Load styles.css or core.css plus table.css.
+
+## Common mistakes
+
+- **Avoid:** Using generic layout components for a pricing matrix because custom positioning feels easier. **Instead:** Use Table's native Head and Cell relationships, then customize the closed recipes and public Table variables for the product-specific comparison.
+- **Avoid:** Hiding material columns on mobile or visually cloning labels into card rows. **Instead:** Contain honest horizontal overflow or provide a separately authored application view; do not destroy or fake the native column relationships.
+- **Avoid:** Making rows hoverable or clickable without a complete interaction owner. **Instead:** Keep rows structural and place independently named Brick links or buttons inside the appropriate cells.
+- **Avoid:** Using Table variant=outline as the visible frame inside a vertically scrolling viewport. **Instead:** Paint the stable Scroll Area viewport with Surface, use Table variant=line inside it, and connect a persistent external label with aria-labelledby.
+- **Avoid:** Using a visible recommendation color as the only explanation for a preferred pricing column. **Instead:** Keep the plan label and recommendation reason readable in ordinary text, then use Table paint only as supporting emphasis.
+
+## Validation checklist
+
+- Check caption or surrounding naming, header scope, cell associations, source order, plan or record labels, and independently named controls.
+- Check Container overflow, the authored minimum comparison width, stable viewport corners during vertical scrolling, sticky header boundaries when used, 320 CSS pixels, zoom, long content, RTL, and no page-level horizontal overflow.
+- Check light and dark themes, forced colors, row and column boundaries, recommendation meaning without color, focus visibility for interactive descendants, and CSS delivery.
+- Check that sorting, selection, filtering, pagination, data services, and responsive alternate-view policy remain application owned.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/table`
+- `data-grid`
+- `tree-grid`
+- `scroll-area`
+- `button`
+- `badge`
+- `icon`
+- `text`

package/dist/agents/tabs.json

@@ -18,6 +18,8 @@
   "composition": [
     "Compose Trigger and optional Indicator inside List with matching Content values inside Root; lay out panel content with Brick components.",
     "Keep the default panel inset for ordinary copy; use Content inset=none for edge-to-edge media or nested surfaces rather than overriding component CSS.",
+    "When a page-header control row visually continues the tab divider, keep unrelated controls outside List and let the surrounding Brick layout own the continuing decorative Divider.",
+    "Use List triggerRadius=none when line tabs need square underline geometry; the option applies to every variant and changes paint only.",
     "When vertical tab semantics stay correct but mobile needs full-width content, use responsive Root layout stacked to side; do not change semantic orientation with CSS.",
     "When the same vertical selector needs a compact mobile grid, use responsive List columns (for example, initial 2 and lg 1) rather than application selectors; keyboard orientation remains vertical.",
     "When a solid or soft List is nested inside a clipping parent that owns the outer corners, use List radius=none rather than overriding Tabs selectors; add triggerRadius=default only when individual Trigger surfaces should remain rounded.",
@@ -44,6 +46,11 @@
       "level": "must",
       "statement": "Treat List radius and Trigger radius as independent visual geometry only; neither may alter inset, selection, focus, orientation, columns, or keyboard behavior."
     },
+    {
+      "id": "tabs-line-selection-paint",
+      "level": "must",
+      "statement": "For line Tabs, keep active label and icon paint on primary text and reserve accent paint for the selected edge or authored metadata such as Badge."
+    },
     {
       "id": "tabs-css",
       "level": "must",
@@ -52,8 +59,8 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Using Tabs for routes, clipping focus/indicator edges, or mismatching Trigger and Content values.",
-      "correction": "Use navigation links for routes and keep complete paired tab anatomy."
+      "mistake": "Using Tabs for routes, putting sorting or actions inside List to extend its divider, clipping focus/indicator edges, or mismatching Trigger and Content values.",
+      "correction": "Use navigation links for routes, keep unrelated controls outside the tablist, continue shared decorative edges with the surrounding Brick layout, and keep complete paired tab anatomy."
     }
   ],
   "validation": [

package/dist/agents/tabs.md

@@ -16,6 +16,8 @@ Style related in-page panel switching while Atom owns tab semantics, selection,
 
 - Compose Trigger and optional Indicator inside List with matching Content values inside Root; lay out panel content with Brick components.
 - Keep the default panel inset for ordinary copy; use Content inset=none for edge-to-edge media or nested surfaces rather than overriding component CSS.
+- When a page-header control row visually continues the tab divider, keep unrelated controls outside List and let the surrounding Brick layout own the continuing decorative Divider.
+- Use List triggerRadius=none when line tabs need square underline geometry; the option applies to every variant and changes paint only.
 - When vertical tab semantics stay correct but mobile needs full-width content, use responsive Root layout stacked to side; do not change semantic orientation with CSS.
 - When the same vertical selector needs a compact mobile grid, use responsive List columns (for example, initial 2 and lg 1) rather than application selectors; keyboard orientation remains vertical.
 - When a solid or soft List is nested inside a clipping parent that owns the outer corners, use List radius=none rather than overriding Tabs selectors; add triggerRadius=default only when individual Trigger surfaces should remain rounded.
@@ -27,11 +29,12 @@ Style related in-page panel switching while Atom owns tab semantics, selection,
 - **MUST:** Define a deliberate narrow-width overflow or wrapping policy without clipping triggers or indicator focus.
 - **MUST:** Treat List columns as visual placement only; keep DOM order and the semantic orientation that matches the intended arrow keys.
 - **MUST:** Treat List radius and Trigger radius as independent visual geometry only; neither may alter inset, selection, focus, orientation, columns, or keyboard behavior.
+- **MUST:** For line Tabs, keep active label and icon paint on primary text and reserve accent paint for the selected edge or authored metadata such as Badge.
 - **MUST:** Load styles.css or core.css plus tabs.css.
 
 ## Common mistakes
 
-- **Avoid:** Using Tabs for routes, clipping focus/indicator edges, or mismatching Trigger and Content values. **Instead:** Use navigation links for routes and keep complete paired tab anatomy.
+- **Avoid:** Using Tabs for routes, putting sorting or actions inside List to extend its divider, clipping focus/indicator edges, or mismatching Trigger and Content values. **Instead:** Use navigation links for routes, keep unrelated controls outside the tablist, continue shared decorative edges with the surrounding Brick layout, and keep complete paired tab anatomy.
 
 ## Validation checklist
 

package/dist/agents/text.json

@@ -5,9 +5,9 @@
   "package": "@flowstack-ui/brick",
   "layer": "brick",
   "kind": "component",
-  "purpose": "Apply Brick typography roles, sizes, tones, weight, alignment, and wrapping while preserving the chosen semantic text element.",
+  "purpose": "Apply Brick typography roles, tones, weight, alignment, wrapping, and deliberate transforms through flexible Text or named semantic text exports.",
   "useWhen": [
-    "Interface copy needs Brick typography, including headings, paragraphs, short editorial eyebrows, captions, metadata, or inline text."
+    "Interface copy needs Brick typography, including headings, paragraphs, short editorial eyebrows, captions, metadata, or inline text. Prefer Heading, Paragraph, Caption, and Eyebrow for their common roles; use Text for a different deliberate semantic/visual pairing."
   ],
   "avoidWhen": [
     {
@@ -16,13 +16,23 @@
     }
   ],
   "composition": [
-    "Choose the semantic element first, then select the closest Brick text role, size, and tone; use Stack for text layout rather than wrapper spans."
+    "Choose the named semantic export when it fits. Heading requires an explicit level and keeps that level independent from its visual variant. Otherwise choose Text's semantic element first, then its closest visual variant and tone. Keep inline components that complete the same sentence inside that text owner, and use Stack only for separately meaningful text peers."
   ],
   "rules": [
     {
       "id": "text-semantics",
       "level": "must",
-      "statement": "Do not choose heading or paragraph semantics solely from the desired font size."
+      "statement": "Do not choose heading or paragraph semantics solely from the desired font size. Use the display scale, responsive visual variant, or responsive logical alignment without changing the correct semantic level."
+    },
+    {
+      "id": "text-authored-case",
+      "level": "must",
+      "statement": "Author real names and titles with their correct casing. Use transform only for deliberate visual presentation; CSS capitalize is not language-aware title case and must not repair registry or product content."
+    },
+    {
+      "id": "text-named-roles",
+      "level": "must",
+      "statement": "Prefer Heading, Paragraph, Caption, or Eyebrow for ordinary roles; use Text when their fixed semantic host or restricted visual family does not fit."
     },
     {
       "id": "text-brick-first",
@@ -44,6 +54,11 @@
       "level": "must",
       "statement": "Use tone=inherit when Text is intentionally composed inside a parent such as Badge that owns the foreground and contrast relationship."
     },
+    {
+      "id": "text-inline-sentence",
+      "level": "must",
+      "statement": "Keep a Link or other inline component that completes one sentence inside the semantic Text paragraph and let it inherit the surrounding typography and natural wrapping."
+    },
     {
       "id": "text-inline-peers",
       "level": "should",
@@ -57,13 +72,13 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Using five spans to build brand text, selecting all-caps eyebrow styling for paragraph descriptions, allowing nested Text to override a parent's foreground, or aligning peer labels with literal whitespace.",
-      "correction": "Use Text with semantic elements, reserve display treatments for their intended roles, inherit the owning foreground, and use HStack gap for layout between separate nodes."
+      "mistake": "Using five spans to build brand text, repeatedly spelling ordinary headings and paragraphs as Text plus as, using capitalize to repair authored titles, selecting all-caps eyebrow styling for paragraph descriptions, allowing nested Text to override a parent's foreground, splitting one sentence into layout siblings, or aligning independent peer labels with literal whitespace.",
+      "correction": "Use the named semantic exports where they fit, author correct casing, reserve transforms and display treatments for their intended roles, inherit the owning foreground, keep one sentence in one text flow, and use HStack gap only between separate peers."
     }
   ],
   "validation": [
-    "Check heading order, semantics, line length, wrapping, truncation, user font scaling, zoom, contrast, themes, and RTL.",
-    "Confirm parent component text parts and foreground ownership are not bypassed, peer labels align without positional CSS, and CSS is loaded."
+    "Check heading order, semantics, responsive visual-recipe changes at Brick breakpoints, line length, wrapping, truncation, user font scaling, zoom, contrast, themes, and RTL.",
+    "Confirm named exports render one correct native host, Heading level follows document structure, transformed text preserves authored content in the DOM, inline sentence content remains inside its semantic owner, independent peer labels align without positional CSS, parent foreground ownership is not bypassed, and CSS is loaded."
   ],
   "related": [
     "stack",

package/dist/agents/text.md

@@ -2,11 +2,11 @@
 
 ## Purpose
 
-Apply Brick typography roles, sizes, tones, weight, alignment, and wrapping while preserving the chosen semantic text element.
+Apply Brick typography roles, tones, weight, alignment, wrapping, and deliberate transforms through flexible Text or named semantic text exports.
 
 ## Use when
 
-- Interface copy needs Brick typography, including headings, paragraphs, short editorial eyebrows, captions, metadata, or inline text.
+- Interface copy needs Brick typography, including headings, paragraphs, short editorial eyebrows, captions, metadata, or inline text. Prefer Heading, Paragraph, Caption, and Eyebrow for their common roles; use Text for a different deliberate semantic/visual pairing.
 
 ## Choose something else when
 
@@ -14,26 +14,29 @@ Apply Brick typography roles, sizes, tones, weight, alignment, and wrapping whil
 
 ## Required composition
 
-- Choose the semantic element first, then select the closest Brick text role, size, and tone; use Stack for text layout rather than wrapper spans.
+- Choose the named semantic export when it fits. Heading requires an explicit level and keeps that level independent from its visual variant. Otherwise choose Text's semantic element first, then its closest visual variant and tone. Keep inline components that complete the same sentence inside that text owner, and use Stack only for separately meaningful text peers.
 
 ## Rules
 
-- **MUST:** Do not choose heading or paragraph semantics solely from the desired font size.
+- **MUST:** Do not choose heading or paragraph semantics solely from the desired font size. Use the display scale, responsive visual variant, or responsive logical alignment without changing the correct semantic level.
+- **MUST:** Author real names and titles with their correct casing. Use transform only for deliberate visual presentation; CSS capitalize is not language-aware title case and must not repair registry or product content.
+- **MUST:** Prefer Heading, Paragraph, Caption, or Eyebrow for ordinary roles; use Text when their fixed semantic host or restricted visual family does not fit.
 - **MUST:** Use Text for standalone styled interface copy instead of native spans plus duplicate typography CSS.
 - **MUST:** Preserve readable body sizing, line height, measure, contrast, and user font scaling.
 - **MUST:** Reserve variant=eyebrow for short labels that introduce a nearby heading; do not select it merely to make unrelated copy smaller. Use body text for explanatory sentences and Badge for passive status or category content.
 - **MUST:** Use tone=inherit when Text is intentionally composed inside a parent such as Badge that owns the foreground and contrast relationship.
+- **MUST:** Keep a Link or other inline component that completes one sentence inside the semantic Text paragraph and let it inherit the surrounding typography and natural wrapping.
 - **SHOULD:** Give separately meaningful inline peer labels compatible typography metrics and arrange them with HStack gap rather than literal spaces or manual positional offsets.
 - **MUST:** Load styles.css or core.css plus text.css.
 
 ## Common mistakes
 
-- **Avoid:** Using five spans to build brand text, selecting all-caps eyebrow styling for paragraph descriptions, allowing nested Text to override a parent's foreground, or aligning peer labels with literal whitespace. **Instead:** Use Text with semantic elements, reserve display treatments for their intended roles, inherit the owning foreground, and use HStack gap for layout between separate nodes.
+- **Avoid:** Using five spans to build brand text, repeatedly spelling ordinary headings and paragraphs as Text plus as, using capitalize to repair authored titles, selecting all-caps eyebrow styling for paragraph descriptions, allowing nested Text to override a parent's foreground, splitting one sentence into layout siblings, or aligning independent peer labels with literal whitespace. **Instead:** Use the named semantic exports where they fit, author correct casing, reserve transforms and display treatments for their intended roles, inherit the owning foreground, keep one sentence in one text flow, and use HStack gap only between separate peers.
 
 ## Validation checklist
 
-- Check heading order, semantics, line length, wrapping, truncation, user font scaling, zoom, contrast, themes, and RTL.
-- Confirm parent component text parts and foreground ownership are not bypassed, peer labels align without positional CSS, and CSS is loaded.
+- Check heading order, semantics, responsive visual-recipe changes at Brick breakpoints, line length, wrapping, truncation, user font scaling, zoom, contrast, themes, and RTL.
+- Confirm named exports render one correct native host, Heading level follows document structure, transformed text preserves authored content in the DOM, inline sentence content remains inside its semantic owner, independent peer labels align without positional CSS, parent foreground ownership is not bypassed, and CSS is loaded.
 
 ## Related guidance
 

package/dist/agents/textarea.json

@@ -41,7 +41,12 @@
     "Test multi-line entry, resize policy, narrow widths, invalid/disabled states, and contrast."
   ],
   "related": [
-    "@flowstack-ui/atom/agents/textarea",
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "textarea",
+      "versionPolicy": "installed-exact"
+    },
     "field",
     "input"
   ]

package/dist/agents/toast.json

@@ -0,0 +1,91 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "toast",
+  "name": "Toast",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present queued finished transient updates while Atom owns store identity, timers, announcements, focus, hotkey access, portal, dismissal, swipe, and lifecycle.",
+  "useWhen": [
+    "A short non-blocking outcome or process update is useful, can be safely ignored, and remains recoverable or visible elsewhere without interrupting the current task."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Feedback belongs beside a field, is essential or durable, represents numeric progress, or requires a response before continuing.",
+      "useInstead": "Field or Form feedback, persistent application content, Progress, or AlertDialog"
+    }
+  ],
+  "composition": [
+    "Install one Toaster near the application root. Create imperative updates with toast helpers, or use the public Toast.Root, Icon, Content, Title, Description, Actions, Action, Close, and Viewport parts for advanced rendering while preserving one Atom Provider and Viewport announcement path.",
+    "Supply concise meaningful title or description, choose type by announcement priority, localize Toaster label and closeLabel, and include an optional action only when it is safe to ignore and may dismiss immediately."
+  ],
+  "rules": [
+    {
+      "id": "toast-nonessential",
+      "level": "must",
+      "statement": "Never make Toast the sole home of essential, response-required, validation, or durable information because it is transient and does not move focus when it appears."
+    },
+    {
+      "id": "toast-single-live-path",
+      "level": "must",
+      "statement": "Keep Viewport's persistent polite and assertive announcers as the only live path; do not add role=status, role=alert, or aria-live to visible Root cards."
+    },
+    {
+      "id": "toast-priority-content",
+      "level": "must",
+      "statement": "Use warning and error assertion only for genuinely important feedback, keep Title and Description concise, include meaning beyond color and glyph, and update content only when a new announcement is intended."
+    },
+    {
+      "id": "toast-timing-focus",
+      "level": "must",
+      "statement": "Preserve normalized duration, hover/focus/page-focus pause, localized hotkey access, focused Escape dismissal, and focus restoration; never steal focus merely because a toast appeared."
+    },
+    {
+      "id": "toast-actions-dismiss",
+      "level": "must",
+      "statement": "Use Brick's single Action only for a callback that may dismiss immediately; Brick has no Cancel part, and async interaction that must stay open belongs in persistent application UI."
+    },
+    {
+      "id": "toast-dismissal",
+      "level": "must",
+      "statement": "Keep Close, Escape, timeout, or another obvious path available; directional swipe is optional and never the sole dismissal mechanism."
+    },
+    {
+      "id": "toast-responsive",
+      "level": "must",
+      "statement": "Choose logical position, responsive/compact/full width, and separated/overlap stacking deliberately; keep safe areas, fixed chrome, software keyboards, narrow screens, zoom, RTL, and viewport offsets under styled or application ownership."
+    },
+    {
+      "id": "toast-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus toast.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Toast for validation or confirmation, adding a second live region, choosing assertive type by color preference, or expecting Action to remain open during async work.",
+      "correction": "Use inline or blocking UI for those jobs, preserve one announcement path, choose priority semantically, and move persistent async interaction outside Toast."
+    },
+    {
+      "mistake": "Making swipe the only dismissal, mounting multiple Toasters casually, or allowing fixed application chrome to cover the viewport.",
+      "correction": "Provide an obvious non-swipe dismissal, keep one application-level viewport, and set documented logical offsets for measured chrome collisions."
+    }
+  ],
+  "validation": [
+    "Verify imperative create/update/dismiss and promise flows, declarative Root, stable IDs, type priority, duration and maxVisible normalization, queue and stacking, close inheritance, entry/exit lifecycle, forceMount, auto-close, pause policies, and meaningful updates announced once.",
+    "Verify localized Viewport label/hotkey, polite/assertive announcers, no visible-card live region, focus-within pause, Escape and restoration, Action and Close callbacks/dismissal, optional swipe threshold/direction/cancel, non-swipe dismissal, custom renderToast, portal container, and logical positions.",
+    "Verify six types, all width/stacking/position recipes, title-only and description-only geometry, long localized content, safe-area and application offsets, 320px, zoom, RTL, light/dark appearance, forced colors, and reduced motion."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "toast",
+      "versionPolicy": "installed-exact"
+    },
+    "alert-dialog",
+    "field",
+    "form",
+    "progress"
+  ]
+}