@flood-md/agent 0.2.11 → 0.2.13

package/lib/inspect.mjs

@@ -13,6 +13,7 @@ export function inspectSourceUI(source,options={}) {
   };
   if(format==='jsx'){
     for(const match of source.matchAll(/\b(?:window|globalThis)\.(confirm|alert|prompt)\s*\(/g))record(match,'composition.native-dialog',match[1]==='confirm'?'AlertDialog':match[1]==='prompt'?'Dialog':'Alert','Native browser dialog candidate. Review the actual call and use the installed Flood owner unless native UI is explicitly required.');
+    for(const match of source.matchAll(/<AppShell\b[^<>]*?\s+scroll\s*=\s*(?:(["'])page\1|\{\s*(["'])page\2\s*\})/g))record(match,'composition.page-scroll','AppShell / ScrollArea','AppShell page mode uses document scrolling. For a full-window application, use content mode and verify the Flood viewport owns vertical overflow. Document layouts may deliberately use page mode.');
     for(const match of source.matchAll(/<(select|button)\b|<input\b[^>]*\btype\s*=\s*["'](date|time|checkbox|radio|range)["']/g)){
       const role=match[1]||match[2],owner={select:'Select',button:'Button',date:'DatePicker',time:'TimeField',checkbox:'Checkbox',radio:'Radio',range:'Slider'}[role];
       record(match,'composition.native-control',owner,'Raw control candidate. Review whether an existing Flood component owns this role; native form/table structure and deliberate documented adapters are separate cases.');
@@ -29,6 +30,50 @@ export function inspectSourceUI(source,options={}) {
   return {schemaVersion:1,issues,truncated,notChecked:['Text matching is not parsing: comments, strings and examples can match; aliases, dynamic types and indirect calls can be missed. Review source context.','This function reads only the supplied text. It does not execute it, open files or inspect imports, component capability, rendered layout or editorial necessity.']};
 }
 
+/** Assert the scroll contract of a full-window AppShell in a settled browser state. */
+export function assertWorkspaceScroll({rootSelector = '.flood-app-shell', expectOverflow} = {}) {
+  const prefix = 'Flood workspace scroll';
+  if (typeof document === 'undefined') throw new Error(`${prefix}: run this check in the rendered browser document`);
+  const roots = document.querySelectorAll(rootSelector);
+  if (roots.length !== 1 || !roots[0].matches('.flood-app-shell[data-scroll="content"]')) {
+    throw new Error(`${prefix}: select one workspace rendered with AppShell scroll="content" (${rootSelector})`);
+  }
+  const root = roots[0];
+  const viewport = root.querySelector(':scope > .flood-app-shell__workspace > .flood-app-shell__main > .flood-scroll-area > .flood-app-shell__scroll');
+  const viewportStyle = viewport && getComputedStyle(viewport);
+  if (!viewport || viewport.clientHeight === 0 || !['auto', 'scroll'].includes(viewportStyle.overflowY) || viewport.dataset.scrollbars !== 'overlay') {
+    throw new Error(`${prefix}: the AppShell content must have a visible, enhanced vertical Flood ScrollArea`);
+  }
+
+  const documentGutter = innerWidth - document.documentElement.clientWidth;
+  const scrollOwner = document.scrollingElement ?? document.documentElement;
+  const documentOverflow = scrollOwner.scrollHeight - scrollOwner.clientHeight;
+  if (documentGutter > 1 || documentOverflow > 1) {
+    throw new Error(`${prefix}: the document has ${documentOverflow}px vertical overflow and a ${documentGutter}px gutter. Contain overflow in the workspace.`);
+  }
+
+  const workspaceOverflow = viewport.scrollHeight - viewport.clientHeight;
+  const hasOverflow = workspaceOverflow > 1;
+  if (expectOverflow === true && !hasOverflow) {
+    throw new Error(`${prefix}: the populated fixture must overflow the workspace viewport`);
+  }
+  if (expectOverflow === false && hasOverflow) {
+    throw new Error(`${prefix}: expected the workspace content to fit, but it overflows by ${workspaceOverflow}px`);
+  }
+  // Flood intentionally exposes native scrollbars inside the viewport in forced colors.
+  if (!matchMedia('(forced-colors: active)').matches) {
+    const viewportGutter = viewport.offsetWidth - viewport.clientWidth
+      - parseFloat(viewportStyle.borderLeftWidth) - parseFloat(viewportStyle.borderRightWidth);
+    if (viewportGutter > 1) {
+      throw new Error(`${prefix}: a native scrollbar reserves ${viewportGutter}px inside the Flood viewport`);
+    }
+    if (hasOverflow && !viewport.parentElement.querySelector(':scope > .flood-scroll-area__track--vertical')) {
+      throw new Error(`${prefix}: the overflowing workspace has no vertical Flood scrollbar`);
+    }
+  }
+  return {documentGutter, documentOverflow, workspaceOverflow};
+}
+
 /** Read-only DOM observations. Pass this self-contained function to page.evaluate. */
 export function inspectRenderedUI(options = {}) {
   if (typeof document === 'undefined') throw new Error('inspectRenderedUI must run in the rendered browser document');
@@ -51,6 +96,26 @@ export function inspectRenderedUI(options = {}) {
     return matches.slice(0, limit);
   };
   if(root===document&&document.documentElement.scrollWidth>innerWidth+1)addIssue({id:'layout.page-overflow',target:{tag:'html',id:document.documentElement.id||null,className:document.documentElement.getAttribute('class')||'',label:'Document'},offset:document.documentElement.scrollWidth-innerWidth,message:'The document extends beyond the viewport. Review the actual overflow owner at this text size; dense content can scroll locally. Hiding page overflow does not repair the layout.'});
+  const documentGutter = innerWidth - document.documentElement.clientWidth;
+  const scrollOwner = document.scrollingElement;
+  const recordTables = select('.flood-data-table');
+  const table = recordTables.find(element => {
+    const main = element.closest('main.flood-app-shell__main');
+    const shell = main?.closest('.flood-app-shell[data-scroll="page"]');
+    if (!shell || shell.parentElement?.closest('.flood-app-shell')) return false;
+    const {top, width} = shell.getBoundingClientRect();
+    return top + scrollY <= 1 && width >= document.documentElement.clientWidth - 1;
+  });
+  const reservedGutter = documentGutter > 1 && scrollOwner && scrollOwner.scrollHeight > scrollOwner.clientHeight + 1;
+  const recordView = table || (reservedGutter && recordTables[0]);
+  if (recordView) addIssue({
+    id: 'layout.record-scroll-owner',
+    target: target(recordView),
+    offset: documentGutter,
+    message: table
+      ? 'A full-window record workspace uses AppShell page mode. Use content mode so Flood owns vertical scrolling even when the OS currently hides its scrollbar.'
+      : 'A document scrollbar consumes width on this record view. Compare full and filtered views with classic scrollbars and check whether a Flood ScrollArea should own vertical overflow.',
+  });
   for (const button of select('button.flood-button, button.flood-icon-button')) {
     // Text is inspected outside real icon slots, SVGs and visually hidden names.
     const walker = document.createTreeWalker(button, NodeFilter.SHOW_TEXT);

package/manifest.json

@@ -117,6 +117,11 @@
       "target": ".agents/skills/flood-ui/references/flood-verification/SKILL.md",
       "kind": "skill"
     },
+    {
+      "source": "references/flood-visual-review/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-visual-review/SKILL.md",
+      "kind": "skill"
+    },
     {
       "source": "references/knowledge.md",
       "target": ".agents/skills/flood-ui/references/knowledge.md",
@@ -142,6 +147,11 @@
       "target": ".agents/skills/flood-ui/references/flood-hierarchy/SKILL.md",
       "kind": "skill"
     },
+    {
+      "source": "references/flood-screen-composition/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-screen-composition/SKILL.md",
+      "kind": "skill"
+    },
     {
       "source": "references/flood-records/SKILL.md",
       "target": ".agents/skills/flood-ui/references/flood-records/SKILL.md",
@@ -158,7 +168,7 @@
       "kind": "reference"
     }
   ],
-  "version": "0.2.11",
+  "version": "0.2.13",
   "installedEntry": ".agents/skills/flood-ui/SKILL.md",
   "pathBase": "source is package-relative; target is relative to the host project root"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flood-md/agent",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "type": "module",
   "description": "Versioned Flood design instructions for coding agents.",
   "license": "MIT",

package/references/component-families.md

@@ -18,6 +18,7 @@ chosen siblings and intentional differences in development notes, outside the UI
 | Command collection | Toolbar/Menu owners, action sizes and keyboard ownership |
 | Floating surface | Existing overlay material, layer placement, inset and focus restoration |
 | Named content or record | Typography, hierarchy and metadata owners, not a new title scale |
+| Data visualization | LineChart data-mark stroke weight, quiet plot grid, exact-value inspection and stable geometry |
 
 Reuse these owners inside the new component. Extend the smallest missing owner
 before adding a composite override. For example, the Toolbar that draws an
@@ -89,6 +90,10 @@ override leaves fields and composed controls inconsistent. Keep absolute
 material colors separate from contextual control roles and verify the nearest
 nested owner resets those roles. Preserve accent focus and destructive meaning.
 
+Vertical pill Toolbar keeps one column on a shared center axis. Use named
+icon-only actions and a consistent control size for a compact rail. Use a
+rounded vertical Toolbar with consistently labeled controls when text is needed.
+
 BulkActionBar is a one-row capsule for a small set of selection commands. Keep
 one to three visible commands, prefer two, and disclose the remainder through
 its overflow owner. Do not wrap this floating rail into a second row or use it
@@ -128,6 +133,15 @@ focus bounds and overflow thresholds. Exercise resize while an action or popup
 has focus. After a shared-owner correction, inspect another consumer. A green
 build or token reuse alone does not establish visual kinship.
 
+Check the same component in a real host composition. Record the geometry that
+should remain stable as state changes. For example, a table cell editor may
+open over its cell, but entering edit mode should keep the row height and
+column widths stable. Then exercise commit and cancel with a long value. If
+the failure repeats, fix the first owner that can enforce the relationship: a
+semantic token for a shared role, the primitive for its own states, or the
+composite for how siblings fit. Add guidance when callers can already choose
+the right behavior through the public API.
+
 ## Keep the contract discoverable
 
 In Flood source, update declarations, component examples, applicable guidance

package/references/composition.md

@@ -43,6 +43,18 @@ adapter such as @/ui/button may re-export Flood, but does not change React APIs.
 Before handing off, inspect a real composed screen at narrow and wide widths,
 not only isolated controls. See [verification](verification.md).
 
+Choose the scroll owner when laying out a screen. In an application workspace
+with fixed chrome or floating collection actions, use AppShell with
+`scroll="content"`. For a padded workspace, set `scrollContentInset="none"`
+when that prop is available and the existing edge padding clears the rails.
+Use the document as scroll owner for pages designed to flow as one document.
+Apply the workspace recipe to filterable or pageable record queues with floating
+actions even when they have no persistent top bar. Keep viewport-fixed actions
+outside the scrolling content. Table's horizontal ScrollArea handles wide
+columns independently.
+When testing a floating selection bar, select the first row and check that the
+viewport and the table keep the same inline size as the overlay rail appears.
+
 For constrained overflow, use installed ScrollArea when available. Set height or
 maxHeight on its viewport, choose the needed axis, and provide a useful accessible
 name. Rails overlay content with insets; keep essential content out of the rail

package/references/flood-composition/SKILL.md

@@ -52,6 +52,13 @@ If discovery finds no suitable component, state the missing capability; do not
 claim that the library has no owner without checking. Keep this decision record
 in development notes, never as extra explanatory text in the product.
 
+For an unfamiliar composition, find the closest runnable recipe and reuse the
+relationship it demonstrates. For example, use `recipe:record-management` to see
+how a DataTable row opens a Drawer while the list preserves scroll and filters.
+Use `recipe:table-bulk-actions` when a selection needs shared commands and
+confirmation. Check the recipe against the installed contracts and adapt it to
+the host's actual task and data.
+
 - Reuse the matching component with its supported props and tokens.
 - If spacing or alignment is wrong, inspect both the primitive and the parent
   composition. Fix the owner of the relationship. Keep the primitive intact.

package/references/flood-data-display/SKILL.md

@@ -60,6 +60,42 @@ the interface-content workflow for contextual placement.
   Keep identifiers, such as postal codes and account numbers, aligned as text
   even when they contain only digits. Preserve formatted units and use raw sort
   values when localized text or rich cells would sort differently.
+- For a collection that users repeatedly filter, preserve the important column
+  tracks at the same viewport as results change. Compare the populated, filtered
+  and no-results states. A table can keep its outer width while its headers move
+  because the body is empty. Where stable scan positions matter, use the
+  supported column sizing to keep the tracks instead of sizing from the rows.
+  Bounded Table and DataTable already keep clearance for their own overlay rail.
+  Reuse that clearance and compare column edges across the overflow threshold.
+- Offer column visibility when users need different subsets of fields for real
+  tasks in the same table. Leave it off for compact tables with a fixed task.
+  Use one layout control per table. If the screen already has View options or
+  Display settings, put column visibility there and pass `hiddenColumnIds`.
+  Otherwise enable `showColumnVisibility`. If the table already has search and
+  filters, use the `toolbar` render function and put its Columns control in
+  `CollectionToolbar.actions` to share the existing tool row. Keep the record
+  identity visible with `hideable: false` and save preferences by column ID in
+  the host. Keep layout preferences independent of the data query. Verify that
+  visibility changes preserve page, selection and sort.
+- Enable resizing for columns with variable-length content when readers need
+  control over width. Use logical start pinning for record identity and logical
+  end for recurring actions when horizontal scrolling would hide them. Persist
+  widths by column ID with visibility, and verify keyboard resize, reset, RTL
+  and access to the unpinned middle at the smallest intended width.
+- Choose short one-line column labels and use DataTable's `unit` badge for
+  a shared short unit. Preserve the complete label when a narrow column
+  truncates it. Compare the label, sort icon and resize grip on the same row.
+- Use DataTable's row disclosure for short details the reader needs while
+  scanning parent records. Compose a named nested Table for related line items.
+  Keep the disclosure and any record-opening action independent. Use a Drawer
+  or separate page for longer detail or editing tasks.
+- Use Sparkline when the shape of a series helps a comparison. Supply a label
+  that describes the trend, use a shared scale for comparing magnitudes, and
+  show decision-critical numbers as text. If a rich trend cell is sortable,
+  define the metric it sorts by and supply its raw value.
+  Keep the same tone across rows of one metric. A soft area fill supports the
+  stroke and follows the same gaps. Reserve semantic tones for meaning and
+  keep numbers and labels readable independently of color.
 - DescriptionList expresses named values; DataList/DataListItem express records.
   Card/Section/Surface organize groups without inventing a second typography or
   spacing system. A heading's semantic level does not prescribe its visual size.
@@ -71,6 +107,79 @@ the interface-content workflow for contextual placement.
 - Preserve native image alt/fallback semantics and aspect constraints. Decorative
   artwork should not duplicate an adjacent accessible identity.
 
+## Choose a chart by the question
+
+Use Metric for a current value, Sparkline for a compact trend in a row,
+LineChart for comparing observations over ordered, equally spaced categories,
+BarChart for comparing discrete groups such as actual and planned values per
+team, and BarList for ranking a few comparable nonnegative values. Sort BarList
+items in the host and retain their exact labels, values and units. Use the same
+domain or max across panels that readers must compare. Keep zero distinct
+from a missing observation and identify comparison series by line pattern
+as well as color. In a LineChart review, traverse dates by keyboard and check
+that the value readout exposes missing data without inventing a value.
+Keep the value readout compact and close to the active marker, within the plot's
+bounds. Keep the marker clear where the readout approaches the edge. Show the
+active category on the axis, where it stays tied to the guide. Exercise a dense
+series as well as a short one and keep only the axis labels that fit.
+Enable LineChart's numeric axis when the reader needs to estimate levels
+or compare them at a glance.
+Use DonutChart for mutually exclusive parts of one total. Group small categories
+only when a combined bucket is meaningful, and prefer BarList for precise
+comparisons between similar values. Check zero and empty separately. Keep the
+center readout as the single source for an inspected category's name and share.
+Keep pointer inspection continuous through the visual gaps between segments.
+Check that the center readout moves directly to the next share at each boundary.
+Give segments the same visual emphasis when the readout shows the total. Keep
+category colors stable and emphasize only the inspected segment's outline.
+Use a quiet categorical palette and the same accent and translucent fill as
+the other charts. Reserve feedback colors for data that actually carries
+success, warning or error meaning.
+Keep the LineChart and BarChart legends off by default. The inspection readout
+already names the series. Enable showLegend when a reader needs to identify
+series before interacting or when the chart is presented as a static image.
+Use Heatmap to find dense and quiet intersections across two labelled axes.
+Compare matrices on the same max and keep missing observations distinct from
+zero. Check exact values by keyboard and pointer with both axis labels present.
+Keep hit areas contiguous across visual gutters so inspection stays continuous.
+Show exact values in a compact tooltip anchored to the inspected cell. Check
+that it stays inside the chart at the edges and leaves the matrix in place.
+Anchor every BarChart to a shared zero baseline. Use stacked bars for additive
+parts and grouped bars for alternatives such as actual versus plan. Keep the
+series order consistent across stacks. Check positive and negative directions,
+missing values, and exact values with pointer and keyboard at the narrowest width.
+Use BarChart's percent layout to compare how the composition changes across
+categories with different totals. Keep the raw values in the readout and leave
+the column empty when its total is zero.
+Use smooth interpolation only when it preserves the observed extrema and
+breaks at missing values. Keep rank labels and values aligned independently
+of the fill widths.
+Use the same accent, translucent fills, tabular values and fast highlight
+motion across chart families. Use the LineChart stroke weight for data marks
+and keep guides, grids and tooltip borders quieter.
+Use ScatterChart for paired numeric observations, RangeChart for observed
+intervals, and BulletChart for actual values against targets. Give every axis
+or bound its unit and keep shared domains consistent across panels.
+Use WaterfallChart to explain a sequence of changes and checkpoints. Use
+Histogram to show frequencies across numeric intervals and BoxPlot to compare
+summaries across groups. Label the units and keep bin edges or scales consistent
+when comparing distributions. Name the meaning of the whiskers in the chart
+context when it affects interpretation.
+Keep Histogram bins contiguous for inspection. A small visual inset separates
+the marks while preserving the numeric interval and its full hit area.
+When a filter applies to several views of one dataset, derive every view from
+the same filtered observations. Keep comparable scales and bin edges stable
+across filter changes so a change in height reflects the data.
+For Histogram and BoxPlot cards in one row, set a shared
+`--flood-chart-plot-height` to align their tick rows. State shared units once
+in the surrounding title and keep them in exact values or axis names.
+Use DumbbellChart for two measurements of the same group. Preserve endpoint
+identity with hollow and filled marks even when the values cross or coincide.
+Keep a pointer guide continuous across the plot
+while the readout shows exact recorded samples. A visual marker may follow
+the curve between samples where data is continuous. Preserve gaps in the
+series and keep keyboard inspection tied to discrete samples.
+
 ## Choose the information, not all available slots
 
 For record lists/details, apply the [records skill](../flood-records/SKILL.md)
@@ -140,6 +249,11 @@ property text. A summary outside the panel needs its property named again.
 Use CollectionToolbar for the search/filter query row, with accepted summaries
 and a staged editor in filterContent. Keep saved views outside it. The fieldset
 uses normal Tab navigation; do not place its editable search in a roving Toolbar.
+When a view or status selector occupies the start of a shared row, set
+`align="end"` on CollectionToolbar to place search and filters as a group at
+the trailing edge. Compare the last visible control to the row's content edge,
+including when there is only a quick filter and no Filters button. Let the groups
+wrap in order at a narrower size.
 Reuse FilterGroup for finite-choice drafts. The host owns validation, Apply,
 Cancel, request execution and reset scope; canClear must include quickFilters
 state when that slot is used. Preserve any-match meaning in summaryPrefix.

package/references/flood-feedback/SKILL.md

@@ -35,6 +35,14 @@ visible even when reducing decorative emphasis.
 
 ## Scope feedback to its operation
 
+Use a floating ToastRegion for the result of a discrete action in a collection
+that is still usable. Keep a failed action's toast available while its retry
+is offered, and preserve the operation's captured targets. Start at bottom-end
+and keep the toast clear of selection actions. Use an inline Alert when the message belongs to
+the affected section, for example when a read failure blocks the table itself.
+Keep its action on the same visual axis as the message in a short titleless
+row. Use Flood Button variants so hover and press inherit the Alert tone.
+
 Associate a message with the operation and record that produced it. Preserve
 entered data after refusal and keep a useful error while that operation remains
 unresolved. A successful retry clears/replaces its failure. Explicitly discarding
@@ -48,6 +56,10 @@ that distinction; the feedback primitive only presents the supplied state.
 
 ## Evidence
 
+After a collection action, check that its result is visible at the current
+scroll position and that success, refusal, retry and dismissal leave the
+table header and scroll height in place.
+
 Trigger the operation and observe each applicable transition, including failure
 and retry. Also follow failure → explicit discard → list → reopen a saved record;
 the abandoned draft's failure must be gone and the saved data unchanged. Distinguish

package/references/flood-forms/SKILL.md

@@ -36,6 +36,11 @@ brief did not enumerate every affordance of choosing a date.
 - Error is invalid; warning/success/info are advisory, not validation algorithms.
   Host validation decides the error and useful message. Keep native constraints,
   invalid focus and the accessible message association coherent.
+- For a validation message users need while correcting a value, render it with
+  the associated Field. An application-specific error should remain visible
+  during correction. Preserve the native form constraint and focus on the first
+  invalid field, then check the message and nearby controls after the failed
+  submission. Native validity by itself does not verify the error presentation.
 
 For visual roles and rhythm, read the [hierarchy skill](../flood-hierarchy/SKILL.md).
 Fieldset legendSize="section" is for an independent section; a short form may

package/references/flood-hierarchy/SKILL.md

@@ -21,6 +21,10 @@ this workflow makes that meaning visible.
 
 - Dialog owns its task heading and the body inset. Its dark title uses the
   dialog-title role (1.25rem / 600); it is distinct from compact popup captions.
+- For independent blocks inside a record Drawer, use Section with
+  `headingSize="group"` when installed. Keep the Drawer title one level stronger
+  visually. Set the semantic heading level separately. Start with a tighter gap
+  from each heading to its content and space-8 between independent sections.
 - Field owns the label-to-control relationship: space-1 (.25rem) in the dark
   profile. DateField/TimeField already use that relationship. Leave room between
   independent fields instead of increasing the gap inside every label/control pair.

package/references/flood-interface-content/SKILL.md

@@ -38,6 +38,13 @@ Do not hide essential instructions or risks behind a tooltip merely
 to make a screen quieter. Preserve accessible names and associations when reducing
 visible copy; use the component's documented hideLabel API where appropriate.
 
+For a bulk confirmation, put the action and its scope first. Use the title for
+the count when it reads naturally there. If the count belongs in the body, give
+it the first sentence. Put a meaningful consequence on a separate line or in a
+separate paragraph. Let each thought wrap naturally on narrow screens. Preserve
+the dialog's accessible description and check singular and plural copy.
+AlertDialog preserves a newline in its string description.
+
 ## Separate prototype provenance from product state
 
 An explicitly requested local prototype or fixture-backed test app does not need

package/references/flood-motion/SKILL.md

@@ -22,6 +22,9 @@ opacity and transform on bounded visual parts. Keep an anchored overlay's
 positioning root stable while a child moves. Animate color only where the old and
 new colors keep required information legible. Keep focus outlines and error
 messages immediate. Apply hover treatment only to devices that can hover.
+For ToastRegion, animate each arriving card as a unit from its placement edge.
+Keep the region anchored and its announcement available as soon as it appears.
+Inline toasts can fade without moving surrounding content.
 Keep compression off disabled controls, text editors and joined control
 surfaces. Verify release and cancellation without a layout shift.
 Treat disclosure headers as part of their enclosing surface. Keep their

package/references/flood-overlays/SKILL.md

@@ -31,6 +31,11 @@ Modal and nonmodal focus are different: do not add a trap to every floating
 surface or remove a modal's background inertness. Escape dismisses the active
 layer; a nested menu/select must not also close its parent dialog. Restore opener
 focus unless the host intentionally moved it elsewhere.
+When a Menu or Dialog-family action can remove or disable its opener, pass
+`getFallbackFocus` to resolve a reachable target after the close commits.
+Choose the next surviving record by its identity or return to the search
+field when the action leaves an empty result. Test focus with the opener
+still present, after its removal and after a deliberate focus change.
 
 Task Dialog titles and body insets use their own recipe; do not reuse compact
 popup caption typography for the modal task. The
@@ -56,6 +61,12 @@ DescriptionList or Fieldset as appropriate. Put the next action in the footer
 when it must stay reachable during scrolling. Avoid repeating the heading
 as a section name or showing two equivalent dismiss actions in a clean state.
 
+Use Sheet when a short touch task, navigation list or option list needs the
+width of the phone. Keep the current choice visible on its trigger and compose
+single-choice options with ListBox. Commit on selection, keep the previous value
+on dismissal, and return focus to the trigger. Use one scrolling body and keep
+long content, the close action and safe-area padding reachable.
+
 Overlay material establishes the nested neutral control context automatically.
 Compare its fields, secondary actions, selection and supporting chips with their
 canvas counterparts. Avoid opaque dark action islands or hiding the entire

package/references/flood-records/SKILL.md

@@ -69,6 +69,32 @@ button provides the keyboard entry. Keep checkbox, links and menus independent.
 For a real destination, preserve a Link. Use the table toolbar and matching
 edge inset when the heading, filters, cells and footer share one surface.
 
+For transient selection commands, look up `recipe:collection-views` in the
+installed catalog. For a full-window record workspace with a changing row count,
+use `AppShell scroll="content" scrollOrientation="vertical"` as the vertical
+scroll owner, including when the page has no app chrome. If workspace padding
+already clears the overlay rail, set `scrollContentInset="none"` to keep the
+content width stable when the rail appears. Keep fixed actions outside that
+ScrollArea and wide table scrolling inside the table. Test populated and empty
+views with space-reserving system scrollbars enabled. Check which element
+scrolls, that the document reserves zero scrollbar width, and that table edges
+stay put when the app scrollbar appears or disappears.
+
+Place BulkActionBar in a fixed host centered near the bottom
+of the viewport. Keep the host outside the table toolbar. Budget any needed
+bottom clearance in the base layout so selecting rows preserves both the table
+position and the scroll height. Use `showSelection={false}` when BulkActionBar displays the count.
+The table still announces selection and can show its result range and pagination.
+When a bordered Surface wraps a flush table, apply `overflow: clip` to that
+frame. Keep horizontal scrolling on the table's own ScrollArea. Verify the
+outline at both lower corners with a visible footer and check keyboard focus at
+the frame's edges.
+
+If a detail table's total summarizes its rows, put it in Table's `tfoot`. Use a
+row header for the label and align the amount with the corresponding numeric
+column. The existing footer border separates it from the last item. Use an
+external summary when its scope includes data beyond the table.
+
 Give a queue's summaries only the prominence they earn in the task. If a
 count changes which work to pick up, make the relevant scope clear. If the
 table already exposes the decision, compare a quiet inline count with a
@@ -117,6 +143,12 @@ reapply the current filter to the updated data. If the source row disappears,
 return focus to a surviving list control such as search. In a long list, verify
 the scroll position and focus separately after both Save and Cancel.
 
+For a table-to-Drawer flow, give DataTable's primary action the record title
+and open the same Drawer from the row surface and keyboard action. Group facts
+in DescriptionList and related rows in a captioned Table. Keep the Drawer body
+as the vertical scroll owner and keep the edit or save action in its footer.
+Use floating feedback for the save result so the table stays in place.
+
 Keep search and a frequently used filter visible when there is room. Put
 occasional or grouped criteria behind a named Filters action. Show applied
 criteria at the list edge so users can tell why a record is missing.

package/references/flood-screen-composition/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: flood-screen-composition
+description: 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.
+---
+
+# Compose for the user's task
+
+Identify the information the user needs to find, the decision they need to
+make, and what they can do next. Arrange the first viewport so that it reveals
+the page's purpose and the next useful content or control. Keep local actions
+with the item or region they affect. A passive view may need no primary button.
+
+Choose a screen structure before choosing surfaces, cards or emphasis.
+
+| User task | Useful starting structure | Inspect in the rendered screen |
+| --- | --- | --- |
+| Understand an offer on a landing page | Lead with the offer and a relevant next action. Put product evidence near the claim it supports. Use a split hero when the visual helps explain the product. | Read the opening with the image absent and at narrow width. The offer, evidence and action still follow a meaningful order. |
+| Find or compare records | Put search and filters next to their results. Use a list for recognition and a table when readers compare the same attributes across rows. | Find an item by title, then compare one value across several rows without losing the column or confusing it with status. |
+| Monitor or decide | Start with the decision or the signal that changes it. Put a summary near the chart, queue or record that explains it. Use separate surfaces for genuinely independent scopes. | Identify what needs attention and follow the visible path to its detail or action. Remove repeated summaries and metrics with no decision to support. |
+| Complete a form or edit | Keep related fields in reading order. Show a review step when correcting a consequential submission warrants one. Preserve entered answers when going back. | Follow labels, input, error and next action with the keyboard. Exercise Back or Cancel and verify which data and focus survive. |
+| Find an answer in documentation | Use informative section headings and place examples next to the explanation they demonstrate. Add an outline when the document has enough sections to make it useful. | Find an answer by scanning headings, then locate its example without reading unrelated sections. |
+
+Use [composition](../flood-composition/SKILL.md) to choose the installed
+component owners. Use [hierarchy](../flood-hierarchy/SKILL.md) when related
+titles, groups and controls need visual separation.
+
+## Treat scanning patterns as observations
+
+F-shaped scanning can appear in undifferentiated prose. Give readers useful
+section headings and put distinguishing words early. A diagonal or Z-shaped
+path can be a hypothesis for a sparse, image-led composition. Judge it using
+that screen's content and task. For repeated comparisons, keep equivalent
+labels or values on predictable tracks. Check the semantic and keyboard order
+as columns stack or writing direction changes. A screenshot alone cannot
+establish where users look.
+
+## Review the assembled screen
+
+Inspect one real populated screen at the intended width and the narrowest
+supported width or enlarged text size. Walk the task without relying on
+explanatory copy. Check whether a heading, surface, badge or metric earns its
+place by identifying scope, grouping related content or supporting a decision.
+Follow an empty or failure state when relevant. Record one concrete layout
+decision and the observed result outside the interface.
+
+See [NN/g's eyetracking research](https://www.nngroup.com/articles/text-scanning-patterns-eyetracking/),
+its [study of alternating image–text layouts](https://www.nngroup.com/articles/zigzag-page-layout/),
+and the [GOV.UK review-before-submission pattern](https://design-system.service.gov.uk/patterns/check-answers/).

package/references/flood-spacing/SKILL.md

@@ -74,6 +74,13 @@ and compact states. Center an icon-only rail against the full rail, not the
 remainder after a one-sided gutter. A scrollbar appearing must not shift body
 tracks relative to the fixed header/footer. Full-viewport workspaces without
 document overflow must not reserve a document scrollbar strip.
+For a floating action bar, size its host to the actual count, commands and close
+control. Keep the count slot stable across digit changes and bound the panel to
+the viewport. Measure the clearance below the last row with the panel open.
+Compare scroll height, available content width and table position before and
+after selection. Check a viewport where all rows fit and one where the last
+row needs scrolling. Put required clearance in the base layout so selection
+keeps the same scroll geometry.
 Test expanded/compact, missing icons, badges/disclosures, long labels, RTL and
 enlarged text. Measure rendered glyph centers, text starts and action centers
 across distant rows; include the header and footer. Correct the owning primitive

package/references/flood-verification/SKILL.md

@@ -8,6 +8,8 @@ description: Verify Flood component or composed-interface changes against applic
 Read [verification](../verification.md), the host's scripts and the changed
 component's contract. Use project-root flood/rules.json to identify applicable
 rule IDs; it is an index of guidance, not an automatic pass/fail policy engine.
+For visible UI changes, use [visual review](../flood-visual-review/SKILL.md) to
+exercise the affected states, inspect captures and record the evidence.
 
 ## Bound the coverage
 
@@ -81,6 +83,10 @@ about repeated copy or metadata in the verification notes.
 Use the [rendered review observer](../rendered-review.md) when local browser
 tooling is available. Inspect findings and exceptions, then review hierarchy and
 copy separately; no findings is not an editorial or visual-quality pass.
+For full-window workspaces, run the
+[workspace scroll assertion](../rendered-review.md#require-workspace-scroll-in-browser-tests)
+on overflowing content and after filtering or another action that shrinks the
+view. Use the same assertion in the independent review of each clean agent run.
 Review host JSX/CSS with inspectSourceUI from that entry too, then resolve the
 actual owner at each candidate location. Include layout and cancel/confirmation
 paths, not just fields. A native browser dialog can be absent from a DOM snapshot;
@@ -117,3 +123,29 @@ agent instruction, screenshot or accessibility scanner cannot independently prov
 all behavior or certify conformance. A local build does not prove registry
 publication, website deployment or a host backend save. Keep installation upgrades
 deliberate and preserve customized/linked destination protections.
+
+## Compare agent guidance in clean runs
+
+When evaluating a rule or skill, give each fresh session the same short task,
+starting project, reference material and tool access. Keep the model, reasoning
+effort, library implementation and review viewport fixed. Change only the
+guidance being tested. When comparing models, keep the guidance fixed too. Do
+not pass along prior attempts, reviewer feedback or fixes.
+
+Decide what to inspect before running the task. Check the same states for task
+completion, correct component ownership, hierarchy, necessary copy and behavior.
+For a discovery comparison, vary the entry point while leaving the guidance
+available in both runs. Check the trace for the entry and selected references.
+For an application comparison, make the same entry available explicitly in both
+runs and vary the instruction under test. Check what the agent actually built.
+Use an unfamiliar task as well as an example already documented in the guidance.
+
+For visual comparisons, give a fresh reviewer the task, expected behavior and
+settled renders or live previews. Hide which variant produced each result.
+Walk the same interaction in each and cite the exact state and visible evidence
+for each finding. Check API choice and mechanics through source or browser
+assertions, and use the rendered comparison for hierarchy, copy and density.
+
+Keep failed attempts and record missing evidence. A single pair of runs can
+reveal a failure mode. Repeat clean runs before attributing a difference to the
+guidance or the model.