@flood-md/agent 0.2.10 → 0.2.11

package/dist/materials/component-icon-button.md

@@ -35,7 +35,9 @@ export function Example() {
 | Prop | Values | Default |
 | --- | --- | --- |
 | `variant` | `"solid" \| "subtle" \| "outline" \| "ghost"` | `"subtle"` |
+| `tone` | `"default" \| "danger"` | `—` |
 | `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
 | `loading` | `boolean` | `—` |
 | `label` | `string` | `Required` |
+| `iconSize` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `size` |
 | `Native HTML props` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-label">` | `Forwarded` |

package/dist/materials/component-menubar.md

@@ -0,0 +1,41 @@
+# Menubar
+
+Coordinated desktop application command menus with roving triggers and shared open state.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Menubar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Menubar label="Editor commands" menus={[{id:"file",label:"File",items:[{id:"new",label:"New document"},{id:"export",label:"Export"}]},{id:"edit",label:"Edit",items:[{id:"undo",label:"Undo"},{id:"redo",label:"Redo",disabled:true}]}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Arrow keys coordinate enabled menu triggers; child menus reuse Menu focus and dismissal.
+- Use native links and NavigationList for destinations, not Menubar. Controlled openValue may refuse transitions.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `menus` | `readonly MenubarMenu[]` | `Required` |
+| `openValue` | `string \| null` | `—` |
+| `defaultOpenValue` | `string \| null` | `—` |
+| `onOpenValueChange` | `(id: string \| null) => void` | `—` |
+| `onAction` | `(menuId: string, actionId: string) => void` | `—` |
+| `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `disabled` | `boolean` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "onAction">` | `Forwarded` |

package/dist/materials/component-multi-select.md

@@ -45,6 +45,16 @@ export function Example() {
 | `toggleLabel` | `string` | `"Show options"` |
 | `clearLabel` | `string` | `"Clear selection"` |
 | `invalidSelectionMessage` | `string` | `"Select at least one option."` |
+| `query` | `string` | `—` |
+| `onQueryChange` | `(query: string) => void` | `—` |
+| `filtering` | `"local" \| "manual"` | `—` |
+| `optionsQuery` | `string` | `—` |
+| `selectedOptions` | `readonly ComboboxOption[]` | `—` |
+| `loadState` | `"ready" \| "loading" \| "error"` | `—` |
+| `loadingMessage` | `string` | `—` |
+| `errorMessage` | `string` | `—` |
+| `onRetry` | `() => void` | `—` |
+| `retryLabel` | `string` | `—` |
 | `value` | `readonly string[]` | `—` |
 | `defaultValue` | `readonly string[]` | `[]` |
 | `onValueChange` | `(value: string[]) => void` | `—` |

package/dist/materials/component-navigation-group.md

@@ -0,0 +1,51 @@
+# NavigationGroup
+
+Related navigation with optional headings, section actions, separators and disclosure.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, NavigationGroup, NavigationItem } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <NavigationGroup label="Projects">
+        <NavigationItem label="Design system" href="/projects/design" />
+        <NavigationItem label="Website" href="/projects/website" />
+      </NavigationGroup>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Groups related navigation without inventing routes or application-menu semantics. Compose actual NavigationItem destinations or NavigationTree children.
+- label, hideLabel, headingAction and separator are independent optional presentation choices. Keep headings and separators only when they clarify real relationships.
+- collapsible uses Flood Collapsible and independent expanded/defaultExpanded/onExpandedChange state; an unaccepted request does not hide accepted content.
+- Compact mode keeps destinations reachable while removing redundant heading text; compare section actions and body rows on the same rail axis.
+- Original compatible addition in the unpublished 0.2.11 source candidate.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `—` |
+| `hideLabel` | `boolean` | `—` |
+| `headingAction` | `ReactNode` | `—` |
+| `separator` | `boolean` | `—` |
+| `collapsible` | `boolean` | `—` |
+| `expanded` | `boolean` | `—` |
+| `defaultExpanded` | `boolean` | `—` |
+| `onExpandedChange` | `(expanded: boolean) => void` | `—` |
+| `compact` | `boolean` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `—` |
+| `collapseDisabled` | `boolean` | `—` |
+| `children` | `ReactNode` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "title" \| "onChange">` | `Forwarded` |

package/dist/materials/component-navigation-item.md

@@ -0,0 +1,59 @@
+# NavigationItem
+
+One shared navigation row for destinations, commands and independent disclosure.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, NavigationItem } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <NavigationItem label="Projects" href="/projects" current />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Uses Flood Link or Button; navigation links remain native anchors with host handlers. Commands and destination clicks do not silently toggle a branch.
+- disclosure without a destination makes the complete row a disclosure button. href plus disclosure creates separate link and disclosure targets in one shared surface; expanded is controlled by the host.
+- compact leaf rows retain names through Tooltip. Use NavigationTree for compact branches and link-plus-branch items so the full navigation remains reachable in a Popover.
+- IconSlot owns leading artwork; IconButton keeps the disclosure target with smaller supporting artwork. trailing is noninteractive metadata, not a place to nest another button inside a link.
+- trailingAction is an independent sibling control in expanded rows. It is visible alongside any trailing metadata. Use a named IconButton and apply its own disabled state.
+- Original compatible addition in the unpublished 0.2.11 source candidate.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `description` | `string` | `—` |
+| `icon` | `ReactNode` | `—` |
+| `reserveIcon` | `boolean` | `—` |
+| `trailing` | `ReactNode` | `—` |
+| `trailingAction` | `ReactNode` | `—` |
+| `href` | `string` | `—` |
+| `linkProps` | `Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href' \| 'children' \| 'aria-current'>` | `—` |
+| `onAction` | `()=>void` | `—` |
+| `actionProps` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'>` | `—` |
+| `disclosure` | `NavigationItemDisclosure` | `—` |
+| `current` | `boolean` | `—` |
+| `currentKind` | `'page' \| 'location'` | `—` |
+| `ancestorCurrent` | `boolean` | `—` |
+| `disabled` | `boolean` | `—` |
+| `size` | `'sm' \| 'md' \| 'lg'` | `—` |
+| `compact` | `boolean` | `—` |
+| `variant` | `'quiet' \| 'standard'` | `—` |
+| `tooltip` | `boolean` | `—` |
+| `tooltipSide` | `'left' \| 'right'` | `—` |
+| `controlRef` | `Ref<HTMLElement>` | `—` |
+| `disclosureRef` | `Ref<HTMLButtonElement>` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, 'children' \| 'onChange'>` | `Forwarded` |

package/dist/materials/component-navigation-tree.md

@@ -27,6 +27,9 @@ export function Example() {
 - A branch may have both href and children: its native link navigates while a separate disclosure button expands. currentValue marks the matching destination; ancestors are expanded explicitly by the host.
 - Expansion is controlled or uncontrolled through expandedValues/defaultExpandedValues/onExpandedValuesChange. Translate disclosure names with expandLabel; content can render host-owned loading or empty branch content.
 - Item values must be globally unique and children acyclic. Disabled destinations have no active href; parent disability does not propagate to children. Introduced in 0.2.7.
+- compact creates an icon rail with real leaf links and full Popover navigation for branches. flyoutSide controls placement; current descendant styling is separate from aria-current. trailing accepts metadata in expanded rows. Compact labels remain accessible and have native title hints.
+- currentKind defaults to page. Use location when the active value identifies a broader global navigation context rather than the exact current page.
+- Enable branchGuides for dense nested lists. Item trailingAction uses the shared NavigationItem slot in expanded rows and on destinations inside branch flyouts.
 
 ## API reference
 
@@ -35,9 +38,14 @@ export function Example() {
 | `label` | `string` | `Required` |
 | `items` | `readonly NavigationTreeItem[]` | `Required` |
 | `currentValue` | `string` | `—` |
+| `currentKind` | `"page" \| "location"` | `—` |
 | `expandedValues` | `readonly string[]` | `—` |
 | `defaultExpandedValues` | `readonly string[]` | `—` |
 | `onExpandedValuesChange` | `(values: string[]) => void` | `—` |
 | `expandLabel` | `(item: NavigationTreeItem, expanded: boolean) => string` | `—` |
 | `size` | `"sm" \| "md" \| "lg"` | `—` |
+| `variant` | `"quiet" \| "standard"` | `—` |
+| `compact` | `boolean` | `—` |
+| `flyoutSide` | `"left" \| "right"` | `—` |
+| `branchGuides` | `boolean` | `—` |
 | `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "onChange">` | `Forwarded` |

package/dist/materials/component-overflow-actions.md

@@ -0,0 +1,47 @@
+# OverflowActions
+
+A priority-based action row that moves commands into a More menu when space is limited.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, OverflowActions } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <OverflowActions label="Document actions" shape="pill" items={[{id:"save",label:"Save",priority:10},{id:"duplicate",label:"Duplicate"},{id:"archive",label:"Archive"}]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Compose commands rather than links. Higher priority remains visible longer; source order is preserved.
+- Uses existing Toolbar, Button, IconSlot and Menu; hidden measurements are inert and excluded from the accessibility tree.
+- shape defaults to pill; rounded restores the field-radius Toolbar shell. Available width excludes Toolbar padding.
+- containerVariant="plain" delegates a surface-free rail to Toolbar, keeping peer control heights aligned; contained is the default. variant still styles the actions themselves.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly OverflowAction[]` | `Required` |
+| `onAction` | `(id: string) => void` | `—` |
+| `moreLabel` | `string` | `—` |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `—` |
+| `variant` | `ButtonProps["variant"]` | `—` |
+| `shape` | `ToolbarProps["shape"]` | `—` |
+| `containerVariant` | `ToolbarProps["variant"]` | `—` |
+| `disabled` | `boolean` | `—` |
+| `leading` | `ReactNode` | `—` |
+| `trailing` | `ReactNode` | `—` |
+| `maxVisibleActions` | `number` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "onAction">` | `Forwarded` |

package/dist/materials/component-page-header.md

@@ -0,0 +1,40 @@
+# PageHeader
+
+The main page heading with optional supporting text and page actions.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, PageHeader, Button } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <PageHeader title="Projects" actions={<Button>New project</Button>} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use inside main for the page's h1. An embedded preview can choose headingLevel={2}. Use Section for titled content within the page.
+- Add a description only when it supplies context the title cannot. Keep filters in the collection toolbar.
+- Actions wrap below the title when the header's own container narrows. The heading stays first in reading and keyboard order.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `description` | `ReactNode` | `—` |
+| `actions` | `ReactNode` | `—` |
+| `headingId` | `string` | `—` |
+| `headingLevel` | `1 \| 2` | `1` |
+| `headingSize` | `"page" \| "large" \| "display"` | `"large"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "title" \| "children">` | `Forwarded` |

package/dist/materials/component-popover.md

@@ -32,7 +32,7 @@ export function Example() {
 | Prop | Values | Default |
 | --- | --- | --- |
 | `title` | `string` | `Required` |
-| `chrome` | `"default" \| "minimal"` | `—` |
+| `chrome` | `"default" \| "minimal" \| "title-only"` | `—` |
 | `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
 | `children` | `ReactNode` | `—` |
 | `open` | `boolean` | `—` |
@@ -44,4 +44,5 @@ export function Example() {
 | `closeLabel` | `string` | `"Close"` |
 | `initialFocusRef` | `RefObject<HTMLElement \| null>` | `—` |
 | `positionReference` | `RefObject<HTMLElement \| null>` | `—` |
+| `focusOnOpen` | `boolean` | `—` |
 | `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "title" \| "role">` | `Forwarded` |

package/dist/materials/component-radio-card.md

@@ -17,8 +17,8 @@ export function Example() {
     <FloodRoot>
       <Fieldset legend="Plan">
         <Stack gap="2">
-          <RadioCard name="plan" value="starter" label="Starter" description="For your next idea." metadata="Free" defaultChecked />
-          <RadioCard name="plan" value="team" label="Team" description="For working together." metadata="$12 / month" />
+          <RadioCard name="plan" value="starter" label="Starter" description="1 project, up to 3 members" metadata="Free" defaultChecked />
+          <RadioCard name="plan" value="team" label="Team" description="Unlimited projects, up to 25 members" metadata="$12 / month" />
         </Stack>
       </Fieldset>
     </FloodRoot>

package/dist/materials/component-segmented-control.md

@@ -1,6 +1,6 @@
 # SegmentedControl
 
-A compact single-value choice with native radio semantics and a shared inset surface.
+A compact single-value choice or collection view switcher with native radio semantics.
 
 Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
 
@@ -15,7 +15,7 @@ import "@flood-md/react/styles.css";
 export function Example() {
   return (
     <FloodRoot>
-      <SegmentedControl label="Time range" name="period" defaultValue="day" options={[{value: "day", label: "Day"}, {value: "week", label: "Week"}, {value: "month", label: "Month"}]} />
+      <SegmentedControl label="Claims view" name="claims-view" defaultValue="pending" options={[{value: "pending", label: "Pending", count: 2}, {value: "reviewed", label: "Reviewed"}]} />
     </FloodRoot>
   );
 }
@@ -25,7 +25,9 @@ export function Example() {
 
 - Uses original RadioGroup behavior and native inputs.
 - Arrow keys move focus and select; Home/End select endpoints, skipping disabled segments. Selecting the current value does not clear it.
-- Native name/form/required, reset and controlled values are preserved. Use actual tabs for tab panels, ToggleGroup for optional pressed actions.
+- Use SegmentedControl to switch a shared collection between mutually exclusive views. Use Tabs for associated content panels and ToggleGroup for optional pressed actions.
+- An option count can communicate workload without a nested badge or a second control. Counts are read with visible labels, preserve zero, and are omitted in icon-only mode. Format localized counts before passing them.
+- Native name/form/required, reset and controlled values are preserved.
 
 ## API reference
 
@@ -44,7 +46,7 @@ export function Example() {
 | `orientation` | `"vertical" \| "horizontal"` | `"horizontal"` |
 | `required` | `boolean` | `—` |
 | `label` | `string` | `Required` |
-| `options` | `readonly ToggleOption[]` | `Required` |
+| `options` | `readonly SegmentedControlOption[]` | `Required` |
 | `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
 | `iconOnly` | `boolean` | `false` |
 | `fullWidth` | `boolean` | `false` |

package/dist/materials/component-sidebar.md

@@ -0,0 +1,64 @@
+# Sidebar
+
+A bounded workspace sidebar with grouped destinations, a compact rail and nested navigation flyouts.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Sidebar } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <div style={{height:"32rem"}}><Sidebar label="Workspace navigation" groups={[{id:"workspace",label:"Workspace",items:[{value:"overview",label:"Overview",href:"#overview"},{value:"projects",label:"Projects",children:[{value:"design",label:"Design system",href:"#design"}]}]}]} currentValue="overview" /></div>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Composes NavigationTree, ScrollArea, IconButton, Stack and Text. Host controls height; header/footer remain fixed while the navigation body scrolls with reserved scrollbar clearance.
+- collapsed/defaultCollapsed/onCollapsedChange control the full-width versus compact rail. Controlled refusals preserve accepted geometry. side supports logical start/end; width affects expanded mode only. collapsible=false omits the toggle.
+- groups need unique IDs and globally unique item values. Destinations retain real links; expansion and currentValue are independent. Disabled items cannot navigate or open a branch.
+- expandedValues/defaultExpandedValues/onExpandedValuesChange retain branch disclosure across width changes. In compact mode a top-level branch opens a Popover with full navigation; choosing a destination closes that flyout. No route is inferred or persisted.
+- header/footer accept content or a ({collapsed}) render function. Adapt meaningful content using that state, rather than hiding arbitrary descendants with CSS. The host owns workspace/account menus and their actions.
+- The inline headerLayout puts the expanded identity and toggle on one row. The stacked default keeps the toggle in its original place across states. Enable branchGuides per group for dense nesting.
+- Item icons use IconSlot; trailing content can compose Badge or other meaningful metadata in expanded mode. Compact destinations retain accessible names and native title labels; missing icons have a neutral fallback glyph.
+- No automatic mobile drawer, routing, resizing, keyboard shortcut or preference storage is added. Check the bounded host, enlarged text, RTL, final scroll item, real destinations and focus across collapse/flyout transitions.
+- groups can hide a redundant visual label with hideLabel while preserving the navigation name. currentKind="location" marks a global module; page is the default contextual destination. The workspace playground composes Sidebar profiles into GlobalRail plus ContextBar without duplicate flyouts.
+- variant defaults to quiet in the 0.2.11 candidate: muted inactive content, normal control weight and restrained rectangular selection through existing semantic roles. standard retains the stronger pill recipe. Both compose the same primitive anatomy and behavior; inspect them in the full-width navigation workspace.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `groups` | `readonly SidebarGroup[]` | `Required` |
+| `currentValue` | `string` | `—` |
+| `currentKind` | `NavigationTreeProps["currentKind"]` | `—` |
+| `collapsed` | `boolean` | `—` |
+| `defaultCollapsed` | `boolean` | `—` |
+| `onCollapsedChange` | `(collapsed:boolean)=>void` | `—` |
+| `collapsible` | `boolean` | `—` |
+| `collapseLabel` | `string` | `—` |
+| `expandLabel` | `string` | `—` |
+| `expandedValues` | `readonly string[]` | `—` |
+| `defaultExpandedValues` | `readonly string[]` | `—` |
+| `onExpandedValuesChange` | `(values:string[])=>void` | `—` |
+| `expandItemLabel` | `NavigationTreeProps["expandLabel"]` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `—` |
+| `variant` | `"quiet" \| "standard"` | `—` |
+| `side` | `"start" \| "end"` | `—` |
+| `width` | `CSSProperties["width"]` | `—` |
+| `header` | `ReactNode \| (state:SidebarSlotState)=>ReactNode` | `—` |
+| `headerLayout` | `"stacked" \| "inline"` | `—` |
+| `footer` | `ReactNode \| (state:SidebarSlotState)=>ReactNode` | `—` |
+| `footerSeparator` | `boolean` | `—` |
+| `headerSeparator` | `boolean` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "onChange">` | `Forwarded` |

package/dist/materials/component-tabs.md

@@ -23,6 +23,7 @@ export function Example() {
 
 ## Design notes
 
+- Use variant="line" for page-level sections with an active marker beside the panel. The default contained variant joins tabs and content in one surface.
 - Arrow keys navigate enabled tabs; automatic activation is default, manual needs Enter/Space. Tab leaves the tablist. Horizontal direction follows RTL.
 - Inactive panels remain mounted but hidden. Keep form validation and persistent selection under host control. Invalid, missing or disabled selected values fall back to the first available item.
 
@@ -37,6 +38,7 @@ export function Example() {
 | `onValueChange` | `(value: string) => void` | `—` |
 | `activationMode` | `"automatic" \| "manual"` | `"automatic"` |
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
+| `variant` | `"contained" \| "line"` | `—` |
 | `controlSize` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` |
 | `disabled` | `boolean` | `false` |
 | `iconOnly` | `boolean` | `false` |

package/dist/materials/component-text.md

@@ -16,8 +16,8 @@ export function Example() {
   return (
     <FloodRoot>
       <Stack gap="3">
-        <Text as="p" size="lead">A calm foundation for your next idea.</Text>
-        <Text as="p" size="compact">Use the space to make it yours.</Text>
+        <Text as="p" size="lead">Quarterly revenue</Text>
+        <Text as="p" size="compact">Revenue increased by 8% this quarter.</Text>
       </Stack>
     </FloodRoot>
   );

package/dist/materials/component-toggle.md

@@ -30,6 +30,7 @@ export function Example() {
 | Prop | Values | Default |
 | --- | --- | --- |
 | `variant` | `"solid" \| "subtle" \| "outline" \| "ghost"` | `"subtle"` |
+| `tone` | `"default" \| "danger"` | `—` |
 | `size` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` |
 | `loading` | `boolean` | `—` |
 | `pressed` | `boolean` | `—` |

package/dist/materials/component-toolbar.md

@@ -31,6 +31,8 @@ export function Example() {
 - Arrows move focus without activation; Home/End jump to the ends. Disabled and hidden actions are skipped. One Tab entry is established after hydration; before JavaScript native child tab order remains.
 - Horizontal arrows follow writing direction. Vertical arrows move between actions; open a vertical toolbar Menu with Enter/Space. Horizontal menus retain ArrowUp/Down opening.
 - loop defaults to true. Native div props/ref target the toolbar; preserve a meaningful label. Available in 0.2.4.
+- shape defaults to rounded; pill uses the action radius and a horizontal single scrollable rail.
+- variant="plain" removes the material and outer inset for grouping peer controls; contained remains the default. Keyboard ownership is unchanged.
 
 ## API reference
 
@@ -39,4 +41,6 @@ export function Example() {
 | `label` | `string` | `Required` |
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
 | `loop` | `boolean` | `true` |
+| `shape` | `"rounded" \| "pill"` | `—` |
+| `variant` | `"contained" \| "plain"` | `—` |
 | `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | `Forwarded` |

package/dist/materials/component-tooltip.md

@@ -32,7 +32,7 @@ export function Example() {
 | Prop | Values | Default |
 | --- | --- | --- |
 | `content` | `string` | `Required` |
-| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `trigger` | `(props: TooltipTriggerProps) => ReactNode` | `Required` |
 | `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` |
 | `align` | `"start" \| "center" \| "end"` | `"center"` |
 | `delay` | `number` | `300` |

package/dist/materials/guide-agent-knowledge.md

@@ -1,17 +1,17 @@
 # Agent knowledge
 
-Flood 0.2.10 adds a versioned read-only catalog and reader. Use the CLI matching
+Flood 0.2.11 includes a versioned read-only catalog and reader. Use the CLI matching
 the project's flood.json; source availability does not prove npm publication.
 The same package sources build the website, CLI results and agent instructions.
 
 ## Discover, then read
 
 ```sh
-npx @flood-md/cli@0.2.10 info --json
-npx @flood-md/cli@0.2.10 catalog --kind workflow --group foundations
-npx @flood-md/cli@0.2.10 catalog --kind component --search table
-npx @flood-md/cli@0.2.10 read recipe:table-bulk-actions
-npx @flood-md/cli@0.2.10 read component:data-table
+npx @flood-md/cli@0.2.11 info --json
+npx @flood-md/cli@0.2.11 catalog --kind workflow --group foundations
+npx @flood-md/cli@0.2.11 catalog --kind component --search table
+npx @flood-md/cli@0.2.11 read recipe:table-bulk-actions
+npx @flood-md/cli@0.2.11 read component:data-table
 ```
 
 These commands return JSON and do not install dependencies, edit files, execute
@@ -19,6 +19,13 @@ skill text or contact a Flood server. The package runner may fetch the CLI if
 it is not installed locally; keep its version deliberate. Existing project and
 agent instructions remain authoritative.
 
+For a screen that filters one table between two views, start with
+`read component:segmented-control` and follow its link to `workflow:records`.
+If the screen switches between independent panels, read `component:tabs`.
+Before delivery, open the list and a selected record together, then use
+`workflow:interface-content` and `reference:interface-content-examples` to
+decide which labels, counts and status messages the user needs in each view.
+
 info reports actual installed package versions, the configured guide version,
 framework detection, catalog identity and capability declarations. A version
 mismatch prevents catalog/read from serving an ambiguous guide train. A

package/dist/materials/guide-agents.md

@@ -14,7 +14,7 @@ sources. The website index is generated from the same bundle metadata rather
 than a second handwritten skill catalog. Source additions do not update an
 already installed package; use the guide set matching your installation.
 
-Version 0.2.10 adds [versioned knowledge discovery](agent-knowledge.md):
+Version 0.2.11 adds [versioned knowledge discovery](agent-knowledge.md):
 info reports installation context, catalog discovers compact metadata, and read
 loads a selected contract or workflow. The catalog includes typed recipes and
 semantic token records. Unknown capabilities and version mismatches are explicit;
@@ -41,6 +41,13 @@ a Badge/Progress/Dialog implementation just to make one layout fit.
 
 ## Files and responsibilities
 
+For reusable components, the composition skill also routes to
+[component families](../packages/agent/references/component-families.md): choose
+the closest existing anatomy and compare sizing, shape, nested insets and states
+in the same scene. Flood's repository instructions require that same guide for
+its own authors. Installed projects receive it through the matching manifest and
+knowledge catalog; existing customized guides are not silently overwritten.
+
 | Project file | For whom / when | Prerequisite | Source of truth | What to check |
 | --- | --- | --- | --- | --- |
 | flood.json | Developer / agent, setup or upgrade | Existing React project | Exact installed release, framework and paths | Matching CLI doctor |

package/dist/materials/guide-foundations.md

@@ -1,6 +1,6 @@
-# Foundations tokens · 0.2.5
+# Foundations tokens · 0.2.11 candidate
 
-This guide describes the **0.2.5** foundation exports. Keep Flood packages at
+This guide describes the **0.2.11 candidate** foundation exports. Keep Flood packages at
 matching exact versions. Existing 0.1.1 installs use their earlier token contract.
 
 Foundations separates fixed reference values (`ref`) from semantic roles (`sys`).
@@ -84,6 +84,49 @@ prepend `--flood-`. The generated typed lookup is the complete contract.
 | `motion` | `duration-fast`, `duration-normal`, `duration-reduced`, `easing` |
 | `layer` | `base`, `sticky`, `popover`, `modal`, `toast` |
 
+### Material and nested control context
+
+Absolute `color.surface.canvas/default/raised/overlay/floating` roles describe
+materials. A component that draws a material establishes the context for its
+children: Surface, Dialog/Drawer, anchored popups and selection menus, Toast,
+Toolbar/BulkActionBar, standalone Calendar and other shared material owners.
+Stack, Inline, Grid and other transparent layout wrappers inherit that context.
+Nesting a default Surface inside an overlay returns to the default material;
+DOM depth does not increment elevation.
+
+Neutral actions, fields, read-only/disabled fills, choices, selection, supporting
+chips/keycaps, skeletons and progress tracks consume inherited semantic roles.
+On filled materials, `color.context.filled.*` supplies translucent neutral state
+overlays: secondary actions use white 5% / 8% / 12% at rest / hover / press,
+fields use 5%, and quiet borders use 8%. This keeps a secondary action secondary
+on both a card and a floating panel. The canvas retains its established defaults.
+Primary actions, content, focus and semantic feedback colors remain independent.
+
+`color.surface.current` supplies the opaque material base for tinted feedback;
+`surface.supporting`, `surface.muted`, `surface.avatar` and `field.readonly`
+separate contextual fills from the absolute canvas color. Do not repurpose canvas
+to recolor controls: it also supplies contrasting content and document/media wells.
+
+Automatic owners require no extra Button/Input props. For an application-owned
+material boundary, `data-flood-surface="base|filled|floating"` selects the neutral
+control context. The attribute does not paint a background or implement a popup.
+Choose the actual material and override `color.surface.current` on that same
+scope if it differs from Flood's material. A transparent wrapper should not
+declare another material context.
+
+Customize contextual recipes using `--flood-sys-color-context-filled-*` and
+`--flood-sys-color-context-base-*` at the root. A direct consumer role override
+on the material owner can refine one scope; a canvas-only field override does
+not silently replace all elevated recipes. Review both contexts when opting into
+strong boundaries. The generated manifest is the complete list of roles.
+
+Floating panels use an opaque fallback, with glass enabled only where supported.
+`prefers-reduced-transparency: reduce` and `data-flood-transparency="reduced"`
+on a FloodRoot or an owning subtree request opaque panels without backdrop blur.
+Forced colors retain system backgrounds, boundaries and selection indicators.
+Translucency is a visual recipe, not an accessibility guarantee: inspect the
+composited background, content contrast and focus in the actual host.
+
 ### Inter typography
 
 Size equivalents assume a 16px root for illustration. Flood does not set the