@flood-md/agent 0.2.11 → 0.2.13

package/dist/materials/component-menu.md

@@ -31,6 +31,7 @@ export function Example() {
 - Enter/Space and ArrowDown open at the first item; ArrowUp opens at the last. Inside use arrows, Home/End and label-prefix typeahead.
 - Disabled items stay keyboard-focusable with aria-disabled but cannot activate. Separators are noninteractive; action IDs must be unique and nonempty. At least one action is required.
 - Escape closes and restores trigger focus. Tab moves to the next control after the trigger; Shift+Tab returns to the trigger. Outside interaction dismisses without stealing deliberately moved focus.
+- Use getFallbackFocus when an action can remove or disable its opener. Resolve the surviving control from the committed interface.
 - Shortcut text is a visual hint, not an implemented key binding. No href or asynchronous task manager is included. Nested items use type="submenu" and a nonempty items array. Checkbox/radio items are controlled preferences, available in 0.2.7.
 - Controlled open needs host updates; onAction requests closure before calling the host. Modern native Popover API required. Native div props/ref target the popup. Available in 0.2.4.
 - Checkbox items take checked (boolean or mixed) and onCheckedChange. Radio items take a nonempty group label, checked and onCheckedChange; the host keeps one selected item per group. Keep each radio group contiguous. Preference items stay open by default; closeOnSelect opts into dismissal. They do not call onAction or submit form values.
@@ -47,6 +48,7 @@ export function Example() {
 | `open` | `boolean` | `—` |
 | `defaultOpen` | `boolean` | `false` |
 | `onOpenChange` | `(open: boolean) => void` | `—` |
+| `getFallbackFocus` | `() => HTMLElement \| null` | `—` |
 | `disabled` | `boolean` | `false` |
 | `side` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` |
 | `align` | `"start" \| "center" \| "end"` | `"start"` |

package/dist/materials/component-range-chart.md

@@ -0,0 +1,46 @@
+# RangeChart
+
+Low and high values by category, with an optional midpoint.
+
+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, RangeChart } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <RangeChart label="Response time (ms)" lowLabel="P10" highLabel="P90" midpointLabel="Median" items={[
+        {id:"mon", label:"Mon", low:84, high:162, midpoint:119},
+        {id:"tue", label:"Tue", low:92, high:176, midpoint:125}
+      ]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Use a shared scale to compare intervals. Supply a midpoint only when it adds information, such as a measured median.
+- Use null bounds for missing observations and give the bounds meaningful labels with units. Inspect a category to read its exact values.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `items` | `readonly RangeChartItem[]` | `Required` |
+| `domain` | `readonly [number, number]` | `—` |
+| `formatValue` | `(value: number) => string` | `—` |
+| `lowLabel` | `string` | `—` |
+| `highLabel` | `string` | `—` |
+| `midpointLabel` | `string` | `—` |
+| `emptyLabel` | `string` | `—` |
+| `missingLabel` | `string` | `—` |
+| `navigationLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

package/dist/materials/component-scatter-chart.md

@@ -0,0 +1,48 @@
+# ScatterChart
+
+Paired numeric observations for inspecting how two measures vary together.
+
+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, ScatterChart } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <ScatterChart label="Response time by traffic" xLabel="Requests / sec" yLabel="Response time (ms)" points={[
+        {id:"run-1", label:"Run 1", x:12, y:110},
+        {id:"run-2", label:"Run 2", x:52, y:162},
+        {id:"run-3", label:"Run 3", x:104, y:301}
+      ]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Give each point a stable ID and finite x and y values. Label both axes with their units.
+- Use matching xDomain and yDomain to compare separate plots. Use formatX and formatY for localized values.
+- Inspect the nearest point with the pointer or traverse observations in supplied order with the keyboard.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `xLabel` | `string` | `Required` |
+| `yLabel` | `string` | `Required` |
+| `points` | `readonly ScatterChartPoint[]` | `Required` |
+| `xDomain` | `readonly [number, number]` | `—` |
+| `yDomain` | `readonly [number, number]` | `—` |
+| `formatX` | `(value: number) => string` | `—` |
+| `formatY` | `(value: number) => string` | `—` |
+| `emptyLabel` | `string` | `—` |
+| `navigationLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

package/dist/materials/component-section.md

@@ -38,5 +38,5 @@ export function Example() {
 | `description` | `ReactNode` | `—` |
 | `actions` | `ReactNode` | `—` |
 | `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` |
-| `headingSize` | `"display" \| "large" \| "page" \| "section"` | `"section"` |
+| `headingSize` | `HeadingProps["size"]` | `"section"` |
 | `Native HTML props` | `Omit<HTMLAttributes<HTMLElement>, "title">` | `Forwarded` |

package/dist/materials/component-sheet.md

@@ -0,0 +1,50 @@
+# Sheet
+
+A bottom-aligned modal for short tasks, navigation and touch-friendly choices.
+
+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, Sheet, Button, Field, Input } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Sheet title="Project settings" trigger={props => <Button {...props}>Open settings</Button>}>
+        <Field label="Project name">{control => <Input {...control} defaultValue="Flood" />}</Field>
+      </Sheet>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Sheet shares Drawer's modal semantics, dismissal, focus restoration, scrollable body and optional footer. Its scrollbar fits in the panel padding. Placement is always bottom.
+- The panel grows with content up to its size limit. Keep actions that must remain visible in the footer and use ListBox for selectable options.
+- Use a sheet for touch navigation or short choices that benefit from a wider target. Anchored popovers and selects remain useful on desktop. Available in 0.2.12.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `string` | `Required` |
+| `description` | `string` | `—` |
+| `trigger` | `(props: OverlayTriggerProps) => ReactNode` | `Required` |
+| `children` | `ReactNode` | `—` |
+| `open` | `boolean` | `—` |
+| `defaultOpen` | `boolean` | `—` |
+| `onOpenChange` | `(open: boolean) => void` | `—` |
+| `disabled` | `boolean` | `—` |
+| `closeLabel` | `string` | `—` |
+| `closeOnOutsideClick` | `boolean` | `—` |
+| `initialFocusRef` | `RefObject<HTMLElement \| null>` | `—` |
+| `getFallbackFocus` | `() => HTMLElement \| null` | `—` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
+| `footer` | `ReactNode` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLDialogElement>, "children" \| "title" \| "role">, "side">` | `Forwarded` |

package/dist/materials/component-sparkline.md

@@ -0,0 +1,41 @@
+# Sparkline
+
+A compact line or area chart for trends in a table cell, list or metric.
+
+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, Sparkline } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Sparkline label="Revenue rose from $8,000 to $12,000" values={[8000, 8200, null, 9500, 11000, 12000]} domain={[0, 15000]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Give the graphic a label that communicates the metric and the trend. Set showLabel to make that label visible.
+- Use a shared domain for comparing magnitudes across rows. Null and nonfinite samples leave gaps in both the stroke and area.
+- The default area uses an accent stroke with a gradient below it. Choose variant line for stroke only and use semantic tones only when the data has a known interpretation.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `values` | `readonly (number \| null)[]` | `Required` |
+| `label` | `string` | `Required` |
+| `showLabel` | `boolean` | `false` |
+| `domain` | `readonly [number, number]` | `—` |
+| `size` | `"sm" \| "md"` | `"md"` |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "error"` | `"accent"` |
+| `variant` | `"line" \| "area"` | `"area"` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label" \| "aria-labelledby">` | `Forwarded` |

package/dist/materials/component-table.md

@@ -28,7 +28,7 @@ export function Example() {
 
 - Caption is required and remains the accessible table name with hideCaption. Supply table sections and correct native header/cell associations.
 - Native table props, className/style and HTMLTableElement ref target the actual table. Set style.minWidth when horizontal overflow is preferable to compressed columns.
-- Flood ScrollArea owns horizontal scrolling and keyboard access. scrollLabel can name its viewport independently; dir and hidden apply to the containing scroll area too.
+- Flood ScrollArea owns horizontal scrolling and keyboard access. Set maxViewportHeight for bounded vertical scrolling with stable clearance for the overlay rail. scrollLabel names the viewport independently.
 - Use data-numeric on headers/cells for end alignment and tabular figures; data-align=start/center/end gives logical alignment. No automatic sorting, selection, pagination or data access.
 - Striped and compact/comfortable density are opt-in presentation. Available in 0.2.4.
 
@@ -42,5 +42,7 @@ export function Example() {
 | `density` | `"compact" \| "comfortable"` | `"comfortable"` |
 | `striped` | `boolean` | `false` |
 | `scrollLabel` | `string` | `—` |
+| `maxViewportHeight` | `CSSProperties["maxBlockSize"]` | `—` |
+| `stickyHeader` | `boolean` | `false` |
 | `cellVerticalAlign` | `"top" \| "middle" \| "bottom"` | `"middle"` |
 | `Native HTML props` | `Omit<TableHTMLAttributes<HTMLTableElement>, "children">` | `Forwarded` |

package/dist/materials/component-toolbar.md

@@ -30,6 +30,7 @@ export function Example() {
 - Use Button, IconButton, Toggle, native buttons/links and Menu triggers. Keep inputs, Select, Tabs and ToggleGroup outside this action-only toolbar.
 - 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.
+- A vertical pill centers its controls on one axis. Use consistently sized icon-only actions with accessible names. Use the rounded shape for a vertical group of labeled actions.
 - 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.

package/dist/materials/component-waterfall-chart.md

@@ -0,0 +1,47 @@
+# WaterfallChart
+
+Signed changes and checkpoints along a running total.
+
+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, WaterfallChart } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <WaterfallChart label="Net revenue (USD)" steps={[
+        {id:"gross", label:"Gross", value:32000, kind:"total"},
+        {id:"refunds", label:"Refunds", value:-4500},
+        {id:"fees", label:"Fees", value:-2500},
+        {id:"net", label:"Net", value:25000, kind:"total"}
+      ]} />
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- A change adds its signed value to the running total. A total is an absolute checkpoint that replaces the running total.
+- Use the same domain for charts you want to compare. It must contain zero and every intermediate total. Use formatValue to add units.
+- Hover, tap or use the keyboard to inspect exact changes and running totals. Decreases use a dashed outline.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `label` | `string` | `Required` |
+| `steps` | `readonly WaterfallChartStep[]` | `Required` |
+| `domain` | `readonly [number, number]` | `—` |
+| `formatValue` | `(value: number) => string` | `—` |
+| `changeLabel` | `string` | `—` |
+| `totalLabel` | `string` | `—` |
+| `emptyLabel` | `string` | `—` |
+| `navigationLabel` | `string` | `—` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role" \| "aria-label">` | `Forwarded` |

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

@@ -7,11 +7,11 @@ The same package sources build the website, CLI results and agent instructions.
 ## Discover, then read
 
 ```sh
-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
+npx @flood-md/cli@0.2.13 info --json
+npx @flood-md/cli@0.2.13 catalog --kind workflow --group foundations
+npx @flood-md/cli@0.2.13 catalog --kind component --search table
+npx @flood-md/cli@0.2.13 read recipe:table-bulk-actions
+npx @flood-md/cli@0.2.13 read component:data-table
 ```
 
 These commands return JSON and do not install dependencies, edit files, execute

package/dist/materials/guide-agents.md

@@ -1,5 +1,9 @@
 # Using Flood with an agent
 
+Flood pairs a React design system with a workflow for agents building and
+reviewing interfaces. Each release connects component contracts, runnable
+recipes and focused skills through the same catalog.
+
 Start with the host's instructions, package.json, flood.json and installed
 flood/DESIGN.md. Use matching package/CLI versions and declarations. A newer
 website example does not add APIs to an older installation.
@@ -82,8 +86,37 @@ component pages. Before completion use verification. For a color-only change,
 load customization and the relevant token roles; unrelated guides stay unloaded.
 
 Clients supporting the skill-folder convention can discover it. Others can read
-it explicitly or link it from existing instructions. The installer preserves
-AGENTS.md; it does not configure clients or guarantee automatic discovery.
+it explicitly. For a client that reads project instructions such as `AGENTS.md`,
+add a short trigger to the existing instructions at the scope where Flood is used:
+
+```markdown
+For UI work in this project, read `.agents/skills/flood-ui/SKILL.md` first.
+Follow its routing for the screen or component you are changing. Check the
+installed component contract. For visible changes, use the visual review workflow
+to exercise the affected states and inspect screenshots from the running app.
+```
+
+Use the `installedEntry` path in `flood/manifest.json` if it differs. The
+installer preserves `AGENTS.md`; add this trigger yourself if it suits your client.
+
+## Review the running interface
+
+When composing a new flow, start from a nearby recipe, check the installed
+component contracts and apply the workflow for the task. For example, use the
+[record management recipe](recipes/record-management.md) to see how a collection
+preserves filters, scroll and focus around a detail Drawer and edit form.
+
+For a visual issue, exercise the actual state and inspect the captured evidence.
+If it repeats, check the smallest component or layout that can enforce the fix.
+Add a browser assertion when behavior can be measured. Use the relevant workflow
+or a runnable example for decisions that depend on the task, such as information
+hierarchy or which details should stay visible. Use clean runs to test whether
+agents discover and apply new guidance on another task.
+
+For a full-window AppShell route, use
+[`assertWorkspaceScroll`](../packages/agent/references/rendered-review.md#require-workspace-scroll-in-browser-tests)
+in the browser suite. Exercise both the populated and filtered states so
+document scrolling fails the test on either state.
 
 The rules index is data, not an executable policy engine. It cannot make an agent
 obey guidance or certify accessibility. Host checks and Flood's repository

package/dist/materials/guide-charts.md

@@ -0,0 +1,34 @@
+# Charts
+
+[Try the three latency charts](https://flood.md/docs/charts#latency-example)
+with one shared service filter, or pick a chart below and copy its React example.
+For setup in React or Next.js, see [Installation](installation.md).
+
+## Trends and comparisons
+
+- [LineChart](https://flood.md/components/line-chart) shows how a measure changes over time. Compare this week with last week on the same scale.
+- [Sparkline](https://flood.md/components/sparkline) shows a small trend beside a value in a table or summary.
+- [BarChart](https://flood.md/components/bar-chart) compares categories. Group series to compare actual and planned values, or use percent stacks to compare their shares.
+- [BarList](https://flood.md/components/bar-list) ranks named values, such as traffic sources, where the labels and counts matter as much as the bars.
+- [BulletChart](https://flood.md/components/bullet-chart) compares a single value with a target and optional reference bands.
+
+## Distributions and relationships
+
+- [Histogram](https://flood.md/components/histogram) shows how often values fall into intervals. Use it to see whether requests cluster near 100 ms or have a long tail.
+- [BoxPlot](https://flood.md/components/box-plot) compares the median, quartiles and endpoints across groups, such as latency by service.
+- [ScatterChart](https://flood.md/components/scatter-chart) shows the relationship between two measurements, such as throughput and response time.
+- [Heatmap](https://flood.md/components/heatmap) shows patterns across two dimensions, such as activity by day and hour.
+- [RangeChart](https://flood.md/components/range-chart) shows an interval for each item, such as a forecast range.
+
+## Parts of a whole and change
+
+- [DonutChart](https://flood.md/components/donut-chart) shows a few shares of one whole, such as spending by category.
+- [WaterfallChart](https://flood.md/components/waterfall-chart) explains how individual increases and decreases add up to a final value.
+- [DumbbellChart](https://flood.md/components/dumbbell-chart) compares two values for each category, such as before and after a rollout.
+
+## Inspecting values
+
+Give each chart a name that includes its measure. Keep units consistent across
+axis labels and value formatting. Hover or focus interactive plots to inspect
+values, then use the arrow keys to move through the data. Where readers need to
+scan or copy many exact values, provide the data in a table alongside the chart.

package/dist/materials/guide-foundations.md

@@ -1,6 +1,6 @@
-# Foundations tokens · 0.2.11 candidate
+# Foundations tokens · 0.2.13
 
-This guide describes the **0.2.11 candidate** foundation exports. Keep Flood packages at
+This guide describes the **0.2.13** 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`).

package/dist/materials/guide-installation.md

@@ -1,6 +1,6 @@
-# Installation · 0.2.11
+# Installation · 0.2.13
 
-The commands below target version 0.2.11. Verify registry availability before installation; for local source evaluation, see the tarball instructions at the end of this guide.
+The commands below target version 0.2.13. Verify registry availability before installation; for local source evaluation, see the tarball instructions at the end of this guide.
 
 Use Node.js 22.12 or newer and an existing npm-based React/Next.js project.
 React 18.3/19 is supported; React 19 and Next.js App Router are integration targets.
@@ -15,8 +15,8 @@ repeat installation when you start using another component.
 ## Connect with the CLI
 
 ```sh
-npx @flood-md/cli@0.2.11 init --dry-run
-npx @flood-md/cli@0.2.11 init
+npx @flood-md/cli@0.2.13 init --dry-run
+npx @flood-md/cli@0.2.13 init
 ```
 
 The installer adds exact matching tokens, React and agent packages. It creates
@@ -40,7 +40,7 @@ No Tailwind configuration or font CDN is needed. The foundations profile is dark
 only; legacy theme behavior remains available outside `FloodRoot`.
 
 ```sh
-npx @flood-md/cli@0.2.11 doctor
+npx @flood-md/cli@0.2.13 doctor
 ```
 
 Doctor checks package versions and guide presence, not stylesheet imports or
@@ -50,7 +50,7 @@ reference `flood/DESIGN.md` from its existing instructions.
 ## Manual package installation
 
 ```sh
-npm install --save-exact @flood-md/tokens@0.2.11 @flood-md/react@0.2.11 @flood-md/agent@0.2.11
+npm install --save-exact @flood-md/tokens@0.2.13 @flood-md/react@0.2.13 @flood-md/agent@0.2.13
 ```
 
 Import the stylesheet and use `FloodRoot` as above. Manual installation does not

package/dist/materials/guide-introduction.md

@@ -16,6 +16,7 @@ them without a separate content service.
 | [Project UI](project-ui.md) | Optional semantic @/ui/button imports in your application |
 | [Layout](layout.md) | Intrinsic actions, responsive forms, choice sizing, gaps and hierarchy |
 | [Components](components.md) | Available controls, props and form composition |
+| [Charts](charts.md) | Choose a chart by the question it answers and try the live latency example |
 | [Base component inventory](base-components.md) | Available primitives and controls in the base release |
 | [Customization](theming.md) | Scoped dark foundations overrides and legacy theme boundaries |
 | [Foundations](foundations.md) | Typed semantic tokens and neutral dark profile for 0.2.11 |
@@ -30,7 +31,7 @@ them without a separate content service.
 
 ## Versions
 
-This branch documents **version 0.2.11**; source availability does
+This branch documents **version 0.2.13**; source availability does
 not establish npm publication. Use matching exact versions of the Flood packages. Documentation on `main` can describe later work; the
 [release tags](https://github.com/tillwithered/flood.md/releases) preserve the
 source and docs for each release. Installed `flood/DESIGN.md` takes precedence

package/dist/materials/guide-motion.md

@@ -1,10 +1,5 @@
 # Motion
 
-`PageHeader` stays static. Its actions keep their own Flood interaction feedback,
-and container reflow does not animate the title or move focus.
-`AppShell` and `AppTopBar` do not animate layout or scroll position. Sidebar
-and Drawer own their own transitions.
-
 Flood uses short motion to show where an interface changed. Motion follows the
 component's own state and respects the operating system's reduced-motion preference.
 
@@ -43,10 +38,11 @@ behavior of their children. State updates and focus take effect immediately.
 | `FloodRoot` | Applies the motion preference to its scope. Preference changes are immediate. |
 | `Text`, `Heading`, `Kbd`, `VisuallyHidden`, `Blockquote`, `InlineCode`, `IconSlot`, `Label` | Static text and artwork. The containing control owns feedback. |
 | `Stack`, `Inline`, `Surface`, `Divider`, `Container`, `Grid`, `AspectRatio`, `Section`, `Split`, `Center`, `Fieldset` | Stable layout. Children own any appearance or interaction feedback. |
+| `PageHeader`, `AppShell`, `AppTopBar` | Titles, layout and scroll position stay stable during reflow. Actions, Sidebar and Drawer own their interaction feedback. |
 | `ScrollArea`, `ResizablePanels`, `Slider` | Direct pointer tracking. Only scrollbar hover paint eases. Resize, scroll and slider positions stay under the pointer. |
 | `Button`, `IconButton`, `Toggle`, `CopyButton` | Hover paint and short press compression. Toggle holds selected paint. Copy shows its result glyph without resizing the button. |
 | `ButtonGroup`, `ToggleGroup`, `Toolbar`, `OverflowActions`, `BulkActionBar`, `Menubar` | Actions inherit Button and Menu feedback. Joined button surfaces keep their geometry. Bulk actions fade in when available. |
-| `CommandList`, `ListBox`, `Tree`, `NavigationItem`, `NavigationList`, `NavigationTree`, `NavigationGroup`, `Sidebar` | Row paint, disclosure glyphs and optional flyouts. NavigationTree fades in branch content in place and removes it immediately on collapse. Sidebar eases between expanded and rail widths. Focus, route and tree reflow update immediately. |
+| `CommandList`, `ListBox`, `Tree`, `NavigationItem`, `NavigationList`, `NavigationTree`, `NavigationGroup`, `Sidebar` | Row paint, disclosure glyphs and optional flyouts. NavigationTree fades in branch content in place and removes it immediately on collapse. Sidebar eases between expanded and rail widths and truncates its row text to keep it on one line. Its toggle shows a filled keyboard focus state, with the system outline in forced colors. Focus, route and tree reflow update immediately. |
 | `Link`, `Breadcrumb`, `Pagination`, `SkipLink`, `Steps` | Navigation is immediate. Button-style actions and step rows can ease their paint. Skip links appear immediately on focus. |
 | `Tabs`, `SegmentedControl` | Selected paint and, for line tabs, an arriving indicator. Tabs reveal the visible panel with a short fade while selection and focus update immediately. |
 | `Field`, `Input`, `Textarea`, `InputGroup`, `SearchInput`, `PasswordInput`, `NumberInput`, `PinInput`, `DateField`, `TimeField`, `DateRangeField`, `Editable`, `CharacterCount` | Field hover paint and inherited action feedback. Typing, caret, counts, validation and edit-mode focus are immediate. |
@@ -57,13 +53,26 @@ behavior of their children. State updates and focus take effect immediately.
 | `Collapsible`, `Accordion` | Keep the header flush on press, rotate the centered disclosure mark and reveal panel content. Closing immediately hides the panel and restores focus where needed. |
 | `CodeSnippet`, `Card`, `DataList`, `DataListItem`, `FileItem`, `FileList`, `AvatarGroup` | Embedded actions and avatars own motion. Reading order and record layout remain stable. |
 | `Badge`, `DescriptionList`, `Table`, `Image`, `List`, `Figure`, `Metric`, `Timeline`, `ColorSwatch`, `FileMeta` | Static content. Changes to data, labels and supporting media render immediately. |
+| `Sparkline` | Hover briefly strengthens the latest point and area. Data changes render immediately. |
+| `LineChart` | Crosshair, markers and local line emphasis track the pointer continuously. The readout shows the nearest recorded sample and lifts clear of the marker near the trailing edge. On exit the readout and marks fade in place from their last pointer position. |
+| `BarList` | Uses Meter's value transition and the same fast highlight as chart inspection. Labels and values update immediately. |
+| `BarChart` | Uses the fast motion role to emphasize the inspected group while its neighbors dim. The readout updates with the active category and column geometry stays fixed. |
+| `DonutChart` | Uses the fast motion role for the inspected segment's outline. Category colors, fills and geometry stay fixed, and the center readout updates immediately. |
+| `Heatmap` | Moves the value tooltip immediately to the inspected cell and keeps the matrix fixed. Visual gutters share the adjacent cells' hit areas. |
+| `ScatterChart` | Highlights the inspected observation and presents its coordinates. Points keep their positions. |
+| `RangeChart` | Highlights the inspected interval while its exact bounds update immediately. |
+| `BulletChart` | Uses the Meter transition for the actual value. Target marks and exact values update immediately. |
+| `WaterfallChart` | Highlights the inspected step and shows the change and running balance. |
+| `Histogram` | Shows exact bin bounds and count as inspection moves. Bin geometry stays fixed. |
+| `BoxPlot` | Highlights the inspected distribution and anchors its summary to the median. The tooltip prefers the right side and flips when space runs out. |
+| `DumbbellChart` | Highlights the inspected comparison without moving its marks. The readout updates immediately. |
 | `Avatar` | Loaded image eases in within a fixed frame. Fallback text is immediately available. |
-| `DataTable` | Selected row paint and sort chevron rotation. Sorting, pagination and table geometry update immediately. |
-| `Tooltip`, `Popover`, `Menu`, `ContextMenu`, `HoverCard`, `CommandPalette`, `Dialog`, `AlertDialog`, `Drawer`, `ImagePreview` | Anchored entrances follow placement. Modal and edge panels have their own timing. Controls, focus, close and positioning retain their native behavior. |
+| `DataTable` | Selected row paint, chevron rotation and a short height transition for row details. Sorting, pagination and column resize update geometry immediately. |
+| `Tooltip`, `Popover`, `Menu`, `ContextMenu`, `HoverCard`, `CommandPalette`, `Dialog`, `AlertDialog`, `Drawer`, `Sheet`, `ImagePreview` | Anchored entrances follow placement. Modal and edge panels have their own timing. Sheet uses the bottom Drawer entrance. Controls, focus, close and positioning retain their native behavior. |
+| `Spinner`, `Skeleton`, `Progress`, `Meter`, `ToastRegion`, `UploadItem`, `UploadList` | Busy indicators and value fill. A floating toast enters as a card from its placement edge; an inline toast fades in place. Upload compositions inherit the progress and action recipes. Announcements and final values are immediate. |
+| `Alert`, `EmptyState`, `StatusIndicator`, `ErrorSummary` | State and message changes are immediate. Embedded actions keep Button feedback. |
 
 Menu, ContextMenu and title-only navigation flyouts fade in and out where
 discrete top-layer transitions are supported. Dismissal releases focus and
 pointer interaction immediately. When a sibling navigation flyout takes over
 the same rail position, the outgoing panel yields immediately.
-| `Spinner`, `Skeleton`, `Progress`, `Meter`, `ToastRegion`, `UploadItem`, `UploadList` | Busy indicators, value fill and floating toast arrivals. Upload compositions inherit the progress and action recipes. Announcements and final values are immediate. |
-| `Alert`, `EmptyState`, `StatusIndicator`, `ErrorSummary` | State and message changes are immediate. Embedded actions keep Button feedback. |

package/dist/materials/guide-skills.md

@@ -13,11 +13,19 @@ The hierarchy workflow covers task/group/field roles, common control tracks and
 relationship spacing. It complements editorial decisions and the spacing workflow;
 it does not prescribe one screen template.
 
+The screen composition workflow helps choose page structure and reading order
+for landing pages, workspaces, forms and documentation. Review it by running
+the user's find, compare or act task in the rendered screen.
+
 The records workflow covers list/detail information selection, stable scan
 positions and the distinction between category, lifecycle state, priority and
 time. It includes examples where those attributes should remain visible, rather
 than a universal rule to hide metadata or limit badge counts.
 
+Visual review exercises the running UI, captures the affected states and checks
+the screenshots before handoff. Use it for new UI, screenshot feedback and
+visible regressions. Keep browser evidence with the findings or the fix.
+
 Use [Agent knowledge](agent-knowledge.md) to discover these workflows by semantic
 group and read the installed version. The catalog separates prerequisites from
 optional related components; grouping is not a request to load every skill.
@@ -40,6 +48,7 @@ Layout and task recipes assembled from existing primitives.
 | --- | --- | --- |
 | flood-composition | Build or review Flood UI from existing library primitives before adding composites. Use for component, website, playground and host-interface work, especially when a layout fix risks replacing a reusable element with custom markup. | [Read skill](/agent/references/flood-composition/SKILL.md) |
 | flood-interface-content | Write or review Flood interface content with editorial decisions about copy, labels, hierarchy and states. Use for visible UI text and reference adaptation; not typography styling, campaigns or rewriting user documents. | [Read skill](/agent/references/flood-interface-content/SKILL.md) |
+| flood-screen-composition | Choose the layout, reading order and first useful action for a Flood screen. Use for new screens or when an existing page is hard to scan, compare or act on. | [Read skill](/agent/references/flood-screen-composition/SKILL.md) |
 | flood-hierarchy | Establish visual hierarchy, shared form tracks and vertical rhythm in Flood screens, forms and overlays. Use when titles, groups and labels compete or a composed interface feels flat; not a fixed page template. | [Read skill](/agent/references/flood-hierarchy/SKILL.md) |
 | flood-spacing | Diagnose Flood spacing, density, nested radii and alignment from rendered geometry. Use for large gaps, crowded rows or shifting compositions. | [Read skill](/agent/references/flood-spacing/SKILL.md) |
 | flood-records | Compose record lists and detail views with a clear metadata hierarchy. Use for crowded status/category/priority/date rows, drifting scan positions or deciding between a list and a comparison table. | [Read skill](/agent/references/flood-records/SKILL.md) |
@@ -74,6 +83,7 @@ Accessibility, evidence and regression checks.
 | flood-interface-content | Write or review Flood interface content with editorial decisions about copy, labels, hierarchy and states. Use for visible UI text and reference adaptation; not typography styling, campaigns or rewriting user documents. | [Read skill](/agent/references/flood-interface-content/SKILL.md) |
 | flood-accessibility | Review Flood interface names, keyboard flow, focus, perception and reflow in the actual host. Use for interaction or accessibility acceptance. | [Read skill](/agent/references/flood-accessibility/SKILL.md) |
 | flood-verification | Verify Flood component or composed-interface changes against applicable contracts and actual evidence. Use for stabilization, regression or completion review. | [Read skill](/agent/references/flood-verification/SKILL.md) |
+| flood-visual-review | Review rendered Flood UI with Playwright or equivalent browser tooling. Use for visual bugs, screenshot feedback, new or changed UI, and visual regressions across interaction states. | [Read skill](/agent/references/flood-visual-review/SKILL.md) |
 
 ## Motion