@flood-md/agent 0.2.12 → 0.2.13

package/knowledge.json

@@ -21,6 +21,11 @@
       "name": "Data & feedback",
       "description": "Structured content, files and honest operation states."
     },
+    {
+      "id": "charts",
+      "name": "Charts",
+      "description": "Visualize trends, comparisons, distributions and change."
+    },
     {
       "id": "quality",
       "name": "Quality",
@@ -65,10 +70,16 @@
     "verification": [
       "quality"
     ],
+    "visual-review": [
+      "quality"
+    ],
     "interface-content": [
       "composition",
       "quality"
     ],
+    "screen-composition": [
+      "composition"
+    ],
     "hierarchy": [
       "foundations",
       "composition"
@@ -247,6 +258,10 @@
     "content": [
       "data-feedback"
     ],
+    "charts": [
+      "charts",
+      "data-feedback"
+    ],
     "feedback": [
       "data-feedback"
     ]
@@ -328,6 +343,7 @@
     }
   ],
   "documentGroups": {
+    "charts.md": ["charts", "data-feedback", "composition"],
     "recipes/record-management.md": ["data-feedback", "composition"],
     "recipes/settings-workspace.md": ["interaction", "composition"],
     "README.md": [

package/lib/inspect.d.ts

@@ -1,5 +1,5 @@
 export interface InspectionTarget {tag:string;id:string|null;className:string;label:string;}
-export interface InspectionIssue {id:'icons.text-glyph'|'icons.unslotted-svg'|'table.mixed-row-centre'|'table.word-fragment'|'copy.action-echo'|'copy.unowned-support'|'forms.track-drift'|'forms.content-track-drift'|'layout.page-overflow';target:InspectionTarget;related?:InspectionTarget;message:string;offset?:number;word?:string;}
+export interface InspectionIssue {id:'icons.text-glyph'|'icons.unslotted-svg'|'table.mixed-row-centre'|'table.word-fragment'|'copy.action-echo'|'copy.unowned-support'|'forms.track-drift'|'forms.content-track-drift'|'layout.page-overflow'|'layout.record-scroll-owner';target:InspectionTarget;related?:InspectionTarget;message:string;offset?:number;word?:string;}
 export interface RenderedUIInspection {
   schemaVersion:1;issues:InspectionIssue[];copy:InspectionTarget[];
   fields:(InspectionTarget&{x:number;y:number;width:number;height:number})[];
@@ -7,6 +7,18 @@ export interface RenderedUIInspection {
 }
 /** Invoke inside a browser document, e.g. page.evaluate(inspectRenderedUI). No mutation or network calls. */
 export declare function inspectRenderedUI(options?:{rootSelector?:string;maxElements?:number}):RenderedUIInspection;
-export interface SourceUIIssue {id:'composition.native-dialog'|'composition.native-control'|'composition.layout-owner'|'composition.scaled-minimum';line:number;column:number;excerpt:string;owner:string;message:string;}
+export interface WorkspaceScrollOptions {
+  /** Selector for one full-window AppShell. Defaults to .flood-app-shell. */
+  rootSelector?: string;
+  /** Set true for overflowing fixtures or false for fixtures whose content must fit. */
+  expectOverflow?: boolean;
+}
+/** Run with page.evaluate after the workspace settles. Throws on a broken scroll contract. */
+export declare function assertWorkspaceScroll(options?: WorkspaceScrollOptions): {
+  documentGutter: number;
+  documentOverflow: number;
+  workspaceOverflow: number;
+};
+export interface SourceUIIssue {id:'composition.native-dialog'|'composition.native-control'|'composition.page-scroll'|'composition.layout-owner'|'composition.scaled-minimum';line:number;column:number;excerpt:string;owner:string;message:string;}
 /** Text observations, not an AST or conformance check. No file access, execution or network. */
 export declare function inspectSourceUI(source:string,options?:{format?:'jsx'|'css';maxFindings?:number}):{schemaVersion:1;issues:SourceUIIssue[];truncated:boolean;notChecked:string[]};

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');
@@ -53,15 +98,24 @@ export function inspectRenderedUI(options = {}) {
   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;
-  if (documentGutter > 1 && scrollOwner && scrollOwner.scrollHeight > scrollOwner.clientHeight + 1) {
-    const table = select('.flood-data-table').find(visible);
-    if (table) addIssue({
-      id: 'layout.record-scroll-owner',
-      target: target(table),
-      offset: documentGutter,
-      message: 'A document scrollbar consumes width on this record view. Compare full and filtered views with classic scrollbars. For a full-window workspace, use AppShell content scrolling so changes in row count keep the table edges in place.',
-    });
-  }
+  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.12",
+  "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.12",
+  "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
@@ -132,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/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,13 @@ 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
@@ -100,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)
@@ -169,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-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-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

package/references/flood-records/SKILL.md

@@ -72,10 +72,13 @@ 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. Keep fixed actions
-outside that ScrollArea. Test a populated view and a filtered or empty view in a
-browser with space-reserving scrollbars. Compare the table's inline edges
-and the document's client width across those views.
+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
@@ -140,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-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.

package/references/flood-visual-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: flood-visual-review
+description: 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.
+---
+
+# Review the UI in the browser
+
+Open the actual route or component preview with representative data. For a
+reported issue, reproduce its state with the user's viewport, input and browser
+engine when relevant and available. For a new or changed UI, start with the user's
+main task and exercise the affected states. A visual review request can produce
+findings alone. When implementing a fix, repeat the same interaction after it.
+
+## Capture and inspect
+
+Use the project's Playwright setup or equivalent browser tooling. Reach states
+with clicks, keyboard and scroll. Wait for fonts and the intended stable state
+before a still capture. Keep motion enabled when investigating a jump or flicker;
+use consecutive frames, video or a trace with screenshots. Confirm layout shifts
+with measurements before and after the action when possible.
+
+Save a screenshot of the changed region in its surrounding layout, then open the
+image and inspect it at its intended size. Crop a detail if needed. For a fix,
+capture before and after with the same data, viewport, scroll position and state
+when the original is available. Keep the artifacts in the host's test output or
+another ignored local directory and link the relevant evidence in the handoff.
+
+| Surface | What to exercise and look for |
+| --- | --- |
+| Table or collection | Select and clear rows, apply a filter through to zero results, then open any affected row detail. Compare column tracks, clipping at rounded edges and whether the toolbar, scrollbar or selection actions shift the table. |
+| Drawer, dialog or popup | Inspect the open state with real content, scroll to the last action and close it. Check the rhythm between title, description and body, internal clipping, overlay placement and visible keyboard focus. |
+| Form or navigation | Walk the relevant keyboard path. Compare label/control gaps, peer text and icon axes, long labels and hierarchy. Exercise an affected error, expansion or selection. For failed submit, verify the message is readable during correction and check what receives focus. |
+
+When a workspace changes height, use a browser with classic scrollbars enabled
+and force overflow. Verify that the intended region scrolls. Compare its content
+edges and `innerWidth - document.documentElement.clientWidth` before and after
+filtering. A browser with hidden or overlay system rails can mask the gutter.
+Use the [workspace scroll assertion](../rendered-review.md#require-workspace-scroll-in-browser-tests)
+in both states so the browser test fails if the document takes over scrolling.
+
+Check the affected scope at the normal viewport and at a supported narrow or
+enlarged-text setting when space is part of the risk. Read the rendered copy as
+part of the task. Look for duplicated labels, decorative status and instructions
+that repeat what the surrounding UI already says. Use the existing [rendered
+review observer](../rendered-review.md) for additional clues if available.
+
+## Resolve and verify
+
+For each material finding, record the route and state, the action to reproduce
+it, the visible symptom, and a screenshot or measurement. Start with problems
+that block the task, hide content or confuse the next action. If a bug repeats,
+locate its shared owner using the [component family contract](../component-families.md)
+and check another affected use after the fix.
+
+Use browser assertions for stable invariants such as bounds, focus or scroll
+position. A passing assertion still leaves visual hierarchy, copy and balance
+to inspect. Report the states actually reviewed and any missing evidence. If the
+target cannot run, or images cannot be inspected, say which visual checks remain
+open and report the evidence you could obtain.