@flood-md/agent 0.2.10 → 0.2.12

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
@@ -78,6 +85,14 @@ affected object named again, a long form may repeat its primary action at the en
 and a printed document has its own content hierarchy. Do not remove those merely
 because similar words appear elsewhere on the screen.
 
+Review shared context across the shell, page header, toolbar, list and open
+record. A page title can carry the task, a section can name the collection, and
+column labels can carry units or field meaning. Trace each repeated fact to its
+visible owner. Temporarily remove optional subtitles, count captions and labels
+beside values. Restore a string when its absence hides scope, changes a decision
+or makes a pane ambiguous when it opens on its own. Keep names required by
+assistive technology when the corresponding visible caption goes away.
+
 ## Explain only what changes a decision
 
 Prefer a clear label or unit to an added helper paragraph. Add a field hint for a
@@ -128,11 +143,16 @@ location, remove it. Read the decision examples when uncertain; reading this
 workflow without applying that review does not satisfy it. Preserve essential
 consequences and actionable errors rather than stripping every explanation.
 
-Read the whole screen in task order, including navigation, heading, fields,
-actions and the state after an action. Review visible strings together with
-accessible names, placeholders and announcements. Check repeated meaning across
-locations, not just repeated words in one file. Removing a subtitle should not
-leave its reserved space or an empty banner behind.
+Read the whole screen in task order, including navigation, heading, fields and
+actions. For a collection, repeat with populated and empty results, then with the
+record open. Compare count scope before dropping duplicates. An active filter
+count and a footer range may differ when search or pagination is active. If all
+receipts are already visible in their column, omit a routine completion caption;
+keep a missing-receipt signal if it affects approval. Name totals when two
+simultaneously visible amounts represent different scopes.
+
+Review visible strings together with accessible names, placeholders and
+announcements. Removing a subtitle should also remove its reserved space.
 
 For a writing pass, report the consequential keep/rewrite/move/remove decisions
 outside the product UI, and exercise the affected action or error. Automated
@@ -140,3 +160,11 @@ phrase scans cannot establish editorial quality. Use [decision examples](../inte
 when a similar-looking string needs different treatment in another context.
 Do not claim an independent agent evaluation when the author already knows the
 implementation or corrected the initial output manually.
+
+## Make canonical examples teach the same standard
+
+Apply these decisions to playground defaults and copied recipes. Optional
+descriptions start absent. When demonstrating one, use a real distinction or
+constraint, such as a plan's member limit, rather than a friendly sentence
+repeating its title. Marketing prose belongs to a deliberate marketing surface,
+not default field/dialog content. Review the printed example as well as its DOM.

package/references/flood-motion/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: flood-motion
+description: Design and verify motion for Flood controls, overlays, disclosure, feedback and loading states. Use for animation, transitions, reduced motion and component motion reviews.
+---
+
+# Choose the event before the animation
+
+Read the installed motion tokens and the component's behavior contract.
+Choose motion by what changed and how far the eye needs to travel.
+
+| Event | Flood recipe |
+| --- | --- |
+| Hover, press, current or checked | Brief paint transition. Standalone controls may compress slightly while held, then return to rest. Selection can move a glyph or thumb that represents the state. |
+| Disclosure | Change content availability immediately. Rotate the indicator and reveal newly shown content only where the component owns that region. |
+| Anchored popup, modal or drawer | Start from the anchor direction, a small opacity change, or the drawer edge. Larger layers get more time. Dismissal should be shorter where the lifecycle can preserve it safely. |
+| Progress, loading or result | Animate the indicator or arriving message. Keep text and state legible during the motion. |
+| Focus, validation, drag, resize, scrubbing or text input | Immediate focus, feedback and geometry. The pointer and selection own their position. |
+| Typography, layout and static content | Inherit motion from the interactive owner. Avoid mount effects on structural wrappers and ordinary rows. |
+
+Use Flood semantic timing roles and narrow transition-property lists. Prefer
+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
+background flush during press and rotate the centered glyph around its own center.
+
+Keep focus, ARIA, routing, scroll locks and form state independent from animation
+completion. For native top-layer exits, verify that content, inertness and focus
+all remain correct. Use an immediate close when an exit would keep an empty or
+interactive shell visible. Rapid reversal must settle to the accepted state.
+
+Honor `prefers-reduced-motion: reduce` with immediate state changes and static
+loading indicators. Never require motion to distinguish two states. For infinite
+motion, verify the activity ends with its actual loading state.
+
+Review actual controls in the same screen and at their supported density. Verify
+pointer, keyboard, touch, interrupted transitions and reduced motion. For
+overlays, also check repeated open/close, focus restoration and nested dismissal
+in Chromium, Firefox and WebKit. Record deliberately static behavior by family.
+Use the Motion guide in the matching catalog for the component-by-component
+contract. When adding a component, give its states an owner in that guide.

package/references/flood-navigation/SKILL.md

@@ -11,6 +11,13 @@ object selection; Tabs for associated panels; Accordion/Collapsible for disclosu
 SegmentedControl selects one value and is not a tab panel controller. Do not use
 Menu just because links appear vertically.
 
+For the 0.2.11 source candidate, NavigationItem is the shared small row owner and
+NavigationGroup owns an optional section heading/action, separator and independent
+group disclosure. NavigationTree composes rows into a hierarchy; Sidebar owns
+fixed regions and bounded scrolling. Consumers must discover these APIs in their
+installed version before using them. Atomic composition separates responsibilities;
+it does not require a new export for every wrapper or spacing token.
+
 ## Preserve browser and keyboard behavior
 
 - Links retain real href, modifier/open-in-new-tab behavior and current-page
@@ -23,6 +30,58 @@ Menu just because links appear vertically.
   Avoid adding generic arrow-key handlers around nested interactive content.
 - Disclosure state must match its trigger and panel. Check whether content remains
   mounted, and preserve any native form/focus consequences of the installed API.
+- A branch with no destination can use one full-row disclosure button. A branch
+  with a destination uses a real link plus a separate sibling disclosure action.
+  Do not nest the toggle inside the link or make a normal link click also toggle
+  expansion. Command rows retain Button semantics; vertical navigation is not
+  automatically an application Menu.
+
+## Shared rows and configurable groups
+
+Use AppShell for workspace regions and AppTopBar for shared application
+context and actions. PageHeader belongs inside the main region. Sidebar and
+NavigationTree own the destinations and expanded branches. Keep the selected
+route, responsive presentation and a mobile Drawer's open state separate.
+Use AppShell navigationDrawer for a single dock that needs to switch based on
+container width. Verify the switch inside a narrow parent at a wide viewport,
+including resizing while a navigation link or the Drawer has focus.
+
+Hide the visible caption of a single group when its title repeats the app or
+workspace context. Keep the group's accessible name with `hideLabel`. Align
+visible captions with destination labels, and check both settled sidebar widths.
+
+NavigationItem owns the complete row surface, including the visual relationship
+between its primary control and disclosure. A shorter selected background behind
+only the label/link makes the trailing action look unrelated. Keep distinct click
+and focus targets within a coherent current/hover surface; current destination,
+ancestor-current, expansion and focus remain separate. Budget actual trailing
+anatomy once rather than adding another empty inset or column in the shell.
+Align disclosure and badge centers on the trailing track. The disclosure target
+already contributes half its width as clearance, so use the compact edge inset
+there and preserve the full target.
+Use trailing for noninteractive metadata and trailingAction for an independent
+named action. Keep both visible on the trailing track at rest and during
+interaction. On an already filled row, use a glyph-level hover response for a
+ghost accessory and keep its keyboard focus visible. Use branchGuides for dense hierarchies where
+indentation alone is hard to follow. Keep section separators optional and
+distinct from branch guides.
+Use Sidebar headerLayout inline when the expanded identity and toggle should
+share a row. Use the stacked recipe when the toggle must stay on the same axis
+through collapse and expansion.
+
+NavigationGroup starts with optional presentation empty. Add a heading to name a
+real group, headingAction for a real command, and separator for a relationship
+that needs one. Do not fill every slot to make a demo look complete. A collapsible
+group requires a label; hiding its visual label does not remove the disclosure's
+accessible name. collapseDisabled disables that disclosure, not its child links.
+Group expansion is not NavigationTree expandedValues and is not Sidebar compact
+state. A proposal callback does not prove the host accepted the change.
+
+Compact groups keep destinations available without requiring an invisible group
+toggle. Preserve the accepted expanded choice for the return to expanded mode;
+do not overwrite it merely to reveal compact destinations. Meaningful heading
+actions remain available. Test headed/unheaded groups, actions present/absent,
+separator on/off, accepted/refused collapse and compact transitions separately.
 
 ## Evidence
 
@@ -33,3 +92,139 @@ new line can indicate a sizing error rather than a legitimate responsive layout.
 For sidebar navigation, scroll/focus the final item and keep its selected surface
 clear of the scrollbar. Verify the actual navigation composition at narrow width
 and enlarged text; an isolated item's screenshot is insufficient.
+Verify shared inline tracks from header through footer: leading glyph center,
+text start and trailing badge/disclosure center. Group labels inherit the chosen
+text track. Missing peer icons reserve their column; iconless nested links use
+an intentional parent-text indent. Sidebar places its scrollbar in existing edge
+spacing, without a permanent extra column or a shift when overflow appears.
+Other scroll surfaces must still protect content that reaches their tracks.
+In compact mode compare the actual brand, pane-toggle, destination and account
+control centers against the full rail center. A balanced body or centered footer
+container does not prove its Menu trigger is on the same axis. Adapt the fixed
+identity/utility slots through the accepted compact state instead of inserting
+an unrelated small button and assuming inherited alignment will fix it.
+
+Use Sidebar for bounded workspace navigation: NavigationTree owns the destinations
+and disclosure, ScrollArea owns the middle scroll viewport, and fixed header/footer
+slots adapt through the collapsed render state. Give the host a meaningful height;
+do not add several competing scroll owners. Route/current value, compact width and
+branch expansion are independent controlled states. A callback is a proposal,
+not acceptance. Keep groups and item IDs stable; item values are globally unique.
+Collapsed branches open a full NavigationTree in Popover, not an application Menu.
+Leaf links preserve href and modifier behavior. Do not claim an active ancestor
+is the current page. Count metadata uses trailing with Badge; icons retain explicit
+IconSlot sizing. Compact destinations use Flood Tooltip on hover and keyboard
+focus while keeping their actual Link or disclosure button. Do not layer a
+native title with the same text over the tooltip. Suppress the branch hint while
+its flyout is open; tooltip behavior must not replace navigation or steal focus.
+Sidebar owns no routing, preference persistence, mobile drawer or keyboard shortcut.
+Add those in the host only for an explicit requirement. On a programmatic width
+change, keep surviving focus or restore it within the navigation; do not move
+unrelated outside focus. Verify footer reachability and flyout text at both widths.
+
+## Compose global and contextual navigation
+
+For a multi-domain application, distinguish global module choice, contextual
+page destination, branch expansion and context-pane visibility. A GlobalRail
+profile can compose a flat, permanently compact Sidebar; the adjacent ContextBar
+profile composes another Sidebar for the accepted module. Use distinct landmark
+names and keep global utilities separate from contextual destinations.
+
+Do not duplicate the context list in both an open ContextBar and a rail flyout.
+Re-clicking the active module does not implicitly hide its context: give that
+pane an explicit visibility control. Use currentKind="location" for a current
+global module and the default page kind for an actual contextual destination.
+Keep genuine hrefs and derive accepted routes from the host router. Modifier
+clicks/open-in-new-tab must not change the current tab's accepted module.
+
+Read recipe:navigation-workspace from the installed catalog for the full host
+composition. Keep filters/search scoped to the accepted module; resetting one
+module must not change another module's query. Validate complete route identities
+before deriving titles and current state. If a focused row/pane/action disappears,
+restore a stable host destination only after the previous focus was disconnected
+and focus fell to the document body. Do not reset surviving focus on every render.
+Include dialog-close after its original trigger disappeared in that check.
+
+SidebarGroup.hideLabel omits a redundant visual heading while retaining the
+named nav landmark. Start optional headings, captions, counters and helper slots
+empty; add them only for information needed for recognition or a decision.
+Group headingAction, separator and collapse configuration belong to the section;
+Sidebar headerSeparator/footerSeparator are independent opt-in shell choices.
+Do not equate every group boundary with a visible line.
+Use the live workspace composition before introducing separate public aliases:
+an identical wrapper name is not a new component responsibility.
+
+Keep a shared top reading anchor across composed panes. A header without a
+collapse action still needs the family header height; removing an optional button
+must not shift its entire navigation above the neighboring rail.
+
+Evaluate the navigation with its main workspace at real desktop width and height,
+not only as a centered object in a docs column. Keep visible chrome subdued
+relative to task content, expose current destinations clearly, and budget badges.
+Record deliberate scoped semantic theme overrides rather than styling around
+the reused primitives. Evidence from another product informs a decision; it does
+not authorize copying implementation or presenting an undated page as a new release.
+
+## Give navigation a deliberate visual grammar
+
+NavigationItem owns a row, not a hidden hierarchy. For a compact row that has
+both a destination and children, use NavigationTree's branch composition: its
+flyout retains the parent destination and the children. Do not hide one of two
+actions merely to fit an icon target. Keep Tooltip mounted and disable its hint
+while the interactive flyout is open; replacing that wrapper can remount the
+trigger and break focus return.
+
+Separate destination artwork from supporting disclosure. Use the IconButton
+iconSize capability to reduce a chevron independently of its size/hit area;
+never shrink the clickable target just to make the glyph quieter. Compare the
+actual artwork, not merely its SVG box. Sidebar's sm/md disclosure uses 2xs
+artwork, lg uses xs; these are the current family recipe, not universal pixel
+requirements for every action. Keep the shared trailing action center.
+
+A pane toggle depicts the pane, with distinct open/close directional states.
+A multi-panel layout icon is not automatically a recognizable visibility action.
+Keep its accessible name and aria-expanded synchronized with the accepted state;
+resolve side and RTL before choosing the arrow direction. Check inherited
+direction changes after mount too: panel edge, arrow and flyout side must update
+together without requiring an unrelated interaction to refresh them.
+
+Do not make every relationship a new pill, divider or group title. Peer items,
+children, separate groups and fixed footer actions need distinct parent-owned
+spacing. Start optional captions, counters and descriptions empty. Give each
+visible addition a recognition, navigation or task purpose; remove decorative
+status claims and labels that repeat their inherited context. Apply the content
+workflow to the actual rendered navigation, including hidden and empty states.
+
+A professional result requires both a coherent family and a working interaction.
+Review expanded/compact side by side with real short/long labels and a populated
+workspace. Check whether a user can identify destinations, discover hidden labels,
+change the current route and reopen a pane. A generic "anti-slop" checklist or
+passing build is not evidence that these rendered checks passed. Learn from
+references without importing another product's branding or taste bans wholesale.
+
+## Coordinate actions and workspace anchors
+
+For a persistent pane toggle, keep its viewport position while its pane changes
+width or visibility and test consecutive clicks at the same coordinates. If a
+compact rail swaps the service mark for the toggle, keep both in the same slot
+and reveal the toggle on hover and keyboard focus. Keep the toggle visible on
+devices without hover. When context is hidden, a rail module can open its
+destinations in a compact NavigationTree flyout. Keep links and expansion state
+shared with the docked context. Escape dismisses the flyout without changing the
+route or pinning the pane.
+
+For a rail hover preview, use the compact item's flyout options. Opening from
+hover preserves focus and allows the pointer to cross the gap into the panel.
+Explicit activation still opens the same destinations on keyboard and touch.
+Anchor a tall context flyout to the rail so it shares the workspace top edge.
+
+Menubar coordinates desktop commands and one open menu, not website destinations.
+Reuse Menu for its child menus; native links still own destinations. OverflowActions
+composes Toolbar/Button/Menu. Preserve command identity, disabled state and danger
+tone when moving into More. Choose priorities by task, not label length. Exercise
+focus when resize hides an action or removes the More trigger.
+
+Keep a common top reading anchor across short/long workspace pages. Use logical
+inline centering for content width: margin:auto on a grid child can also center
+a short page vertically. Name each pane's scroll owner. Check short/long lists,
+detail and editor at the same viewport; a Drawer/table cannot fix its parent.

package/references/flood-overlays/SKILL.md

@@ -10,6 +10,9 @@ Use the actual installed overlay and trigger contract; see
 noninteractive help; interactive content needs the appropriate Popover or dialog.
 Do not put an action inside a tooltip or apply application-menu roles to site links.
 
+For a short Select trigger, verify that the open list can fit the longest
+ordinary label, then repeat near the viewport edge with a very long label.
+
 ## Preserve trigger and state
 
 Forward trigger props/ref onto one mounted native action. Preserve its accessible
@@ -17,6 +20,13 @@ name and open/controls semantics. Choose host-controlled open state or a default
 and test a host refusing an open/close request. Do not claim control state changed
 merely because a callback ran. The host owns persistent values in unmounted panels.
 
+Tooltip can attach to a real Link or Button through HTMLElement-safe trigger
+props. Preserve the ref, hover/focus handlers and descriptions together with the
+host handlers. Do not turn a navigation link into a button to add a hint. Raw
+tooltip buttons in forms keep an explicit type="button". A control sharing Tooltip
+and Popover composes both refs and suppresses its hint while the popover is open;
+the interactive layer owns Escape and focus then.
+
 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
@@ -26,8 +36,39 @@ Task Dialog titles and body insets use their own recipe; do not reuse compact
 popup caption typography for the modal task. The
 [hierarchy workflow](../flood-hierarchy/SKILL.md) owns title/group/field relations.
 
+Use CommandPalette for modal search. Its search header and results share one
+overlay surface. Forward the trigger and keep the modal title and input label
+specific to the task. Use loading for an in-flight request, and let the host
+control permissions, navigation and shortcuts.
+
 ## Inspect the actual host
 
+Use a Drawer for a short record task that needs the list as context. Use a
+route when the record needs a shareable address, substantial editing space, or
+its own navigation and history. After a Drawer save, restore the initiating
+control if it remains in the result set. Choose a stable list control when the
+edit changes filter membership. See `recipe:record-management`.
+
+Choose Drawer width using the longest real title, body copy and form controls.
+Compare `md` and `lg` with a populated record. Use the description slot for
+brief context and compose independent body sections with Section, Stack,
+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
+surface distinction behind a strong border/shadow. Glass needs an opaque
+fallback and a reduced-transparency path. A nested Surface resets its own
+material; a nested chooser becomes a new floating owner. Verify both cases.
+
 Check placement at viewport edges, resize, narrow/enlarged text, RTL and parent
 scrolling. Selection popups and calendar popups have distinct content geometry;
 use the supported field/anchor sizing behavior, not a universal fixed width.

package/references/flood-records/SKILL.md

@@ -25,8 +25,9 @@ planning text in the interface. Read the
 - If users compare several independent attributes across records, use Table or
   DataTable with actual named columns. A long Inline of unrelated values at each
   row end is not a substitute for comparison columns.
-- Use DescriptionList for named values in details. A detail view can expose more
-  information than a list; it does not need to repeat the list's chip arrangement.
+- Use DescriptionList for named values in details. Each item requires a unique,
+  stable string `id` alongside `term` and `description`. A detail view can expose
+  more information than a list; it does not need to repeat the list's chip arrangement.
 - Selection is not navigation. A record list does not become ListBox merely
   because users click its entries. Retain a real Link and independent actions.
 
@@ -61,6 +62,57 @@ a default low/medium priority does not automatically need a separate visual acce
 
 ## Distribute information between list and details
 
+For a table row whose main action opens an in-place Drawer, use DataTable's
+`primaryAction` when the installed version provides it. Title and metadata
+share a compact cell, pointer activation extends across the row, and a native
+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. 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.
+
+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
+separate metric surface before spending the first viewport on summaries.
+
+Classify a collection toolbar control by the thing it changes:
+
+| What changes | Owner |
+| --- | --- |
+| One selected value filters the same table | SegmentedControl for a few visible choices, Select when the choices need a compact menu |
+| The current panel and its associated content | Tabs |
+| The current destination | Link |
+| An operation runs | Button |
+
+For example, Pending and Reviewed can filter one table even when each state shows
+different columns. Use the installed SegmentedControl when its value model fits.
+Read its component contract before composing the toolbar. Keep one table and
+preserve applicable search and sorting; reset a page or close a detail only when
+the new result invalidates it. Keep focus on the selected control. Exercise arrow
+keys and check that the selected value updates the rows and accessible state.
+
 Protect enough width for the identity and useful summary. Category and recency
 can read as secondary information near the title; status may stay in a stable
 trailing position. This is one pattern, not a required arrangement. DataListItem
@@ -81,6 +133,17 @@ instead of suppressing the distinction based only on equal formatted dates.
 
 ## Compose collection states deliberately
 
+Use the `recipe:record-management` material when users need to find a record,
+edit it and continue working through the same list. Keep the applied query,
+filters, ordering, page and scroll with the mounted collection. After saving,
+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.
+
+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.
+
 First-use empty, filtered no-results, loading and read failure are different
 states. Keep a relevant reset/action and meaningful feedback. A result count can
 help filtering or pagination; do not automatically add Found: 0 beside an empty

package/references/flood-spacing/SKILL.md

@@ -7,6 +7,8 @@ description: Diagnose Flood spacing, density, nested radii and alignment from re
 
 Read the [spacing reference](../spacing.md), installed component anatomy and
 host content requirements. Existing user-approved geometry governs the task.
+Use the [visible spacing review](../spacing.md#judge-the-space-you-can-see)
+when a rendered relationship feels crowded or loose despite matching tokens.
 
 Identify what a gap separates: indicator/text, title/description, related choices,
 independent actions, sections, or nested surfaces. Do not propagate one gap to
@@ -47,6 +49,44 @@ Distinguish a real component from its preview scene. Fixed preview height and
 reserved feedback space can prevent a demo from jumping; they should not impose
 an empty message row or fixed height on every production field.
 
+## Establish shared alignment tracks
+
+Before composing repeated rows, define the logical start inset, leading glyph
+column, text start and trailing action center. Header, group label, body rows and
+footer that belong to one navigation/record surface must inherit those tracks;
+independent local padding on every row is not a shared grid. Reserve a missing
+icon column when peer rows have icons. Align badges and disclosure controls by
+their centers even when their visible shapes and hit areas differ.
+
+Nested content needs a deliberate rule: an iconless child can begin on its
+parent's text track; a deeper hierarchy may have another consistent indent.
+Do not let a child start between the parent icon and label merely because a
+generic padding token happened to fit. Larger brand art is an intentional size
+exception, not permission to move its label off the shared text track.
+
+Keep alignment stable when a scrollbar appears. Budget its clearance once at the
+surface owner; use existing edge spacing when it safely contains the track rather
+than adding a permanent empty column to every slot. Sidebar uses that edge lane.
+Generic ScrollArea still needs contentInset="scrollbar" when content would reach
+under its track. Do not disable that protection globally.
+Compare outer start/end clearance against the actual container in both expanded
+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
+or parent track instead of adding per-item offsets, transforms or replacement UI.
+A build, equal row height or zero overflow does not prove these axes align.
+
 ## Evidence
 
 Check short/wrapping labels, optional descriptions/messages/actions, all relevant
@@ -60,3 +100,8 @@ remaining copy width and body height after padding, title/description, fixed
 actions and scrollbar space. A thin scrolling slot or words broken into fragments
 is a failure even when every rectangle technically fits. Correct the owning
 container's responsive budget without shrinking the user's enlarged text.
+For settings and detail drawers, measure title-to-description,
+description-to-body, and the pitch between visible controls independently.
+An optional description should sit in the header slot. Separate that group
+from the body with more space than the gap inside it. For repeated switches,
+count their existing hit-area height before adding row gaps.

package/references/flood-verification/SKILL.md

@@ -11,6 +11,12 @@ rule IDs; it is an index of guidance, not an automatic pass/fail policy engine.
 
 ## Bound the coverage
 
+Run the screen's task trace with real interactions. Check the starting state,
+the accepted result and a relevant refusal or empty result. After rejection,
+verify that the user can find the correction, keep their input and try again.
+After success, inspect the updated data and the next focus target. For read-only
+screens, use a reachable navigation or recovery path where one applies.
+
 Record the affected primitive, its real consumers, supported states and ownership.
 Mark an inapplicable check with a reason rather than forcing keyboard behavior
 onto decoration or readOnly onto every control. Distinguish existing test coverage
@@ -36,11 +42,21 @@ visual changes inspect rendered geometry, long/optional content, narrow/wide,
 enlarged text and the relevant pointer/RTL/forced-color modes. A CSS declaration
 or component count is not evidence that the user-visible relationship works.
 
+Check that key controls have usable visible space. For search, read the
+placeholder and enter a realistic query at each relevant layout breakpoint.
+Inspect the field and text area width, including when a clear action appears.
+Check computed layout if a host class changes an existing layout primitive.
+
 For geometry and screenshots, wait for fonts, pending animations and a settled
 rendering frame. A zero running-animation count alone may precede final
 presentation. Preserve real motion and strict geometry tolerances; distinguish
 an entry frame from the final layout rather than accepting either as proof.
 
+For a spacing or typography decision, keep two settled renders of the same
+state and compare them at the working size. State which visible relationship
+improved and use measurements to explain why. Test enlarged text separately
+from the user's line, paragraph, letter and word spacing overrides.
+
 During local iteration run focused checks and show the result promptly. A shared
 primitive correction also checks its consumers. At a consolidated Flood source
 candidate run npm run verify and the required applicable browser matrix; use the
@@ -55,6 +71,10 @@ For record composition, apply the [records workflow](../flood-records/SKILL.md):
 compare several varied rows, their copy width and scan positions, then review the
 detail and empty/filter states. Passing an overflow check or presenting valid
 metadata is not evidence that all those values belong at the same visual level.
+When the same table has a view selector, use the keyboard to change its value.
+Verify the selected state, matching rows, surviving query and focus. Read the
+shell, toolbar, list and opened detail together and record one concrete decision
+about repeated copy or metadata in the verification notes.
 
 ## Report a usable result
 

package/references/interface-content-examples.md

@@ -24,6 +24,10 @@ Keep the user's language, task and domain vocabulary.
 | A record is Draft or a camera is Offline inside a prototype | Keep the meaningful record state | Removing prototype narration is not permission to strip operational information |
 | A mixed production list includes sample records that could be mistaken for real ones | Keep a clear sample distinction on the affected records | It prevents a concrete misunderstanding |
 | A printed invoice has a document title, number and party headings | Keep the meaningful document hierarchy | A document is not the application's decorative page header |
+| An approval queue has a task title, an instruction to review the queue, and a workspace label that adds no scope | Keep the task title and remove the redundant supporting copy | The title, rows and available decisions already describe the task |
+| The selected filter says “Reviewed 4” and the footer says “1–4 of 4” in an unpaginated list | Keep one count if useful; check both again when search or pagination changes their meaning | A total for all reviewed records and a range in the current results can serve different decisions |
+| The detail pane repeats “3 receipts attached” beside three visible receipt rows | Omit the routine caption; surface a missing receipt when it affects approval | The ordinary state is visible, and the exception changes the decision |
+| The page shows a queue-wide amount and the open record's amount | Keep short labels distinguishing the amounts | Nearby values alone cannot identify their scope |
 
 ## Contextual adaptation
 

package/references/rendered-review.md

@@ -41,6 +41,11 @@ does not open controls or wait for layout on your behalf. It traverses the curre
 document, not iframes or shadow roots. It performs no network requests or writes.
 Keep reports local: labels and copy inventories may contain the host's user data.
 
+For a visual layout change, compare screenshots of the same content, viewport
+and settled state. Name what should stand out and which elements should read
+together. Use measured boxes to explain the difference. The observer cannot
+judge painted glyph edges, perceived contrast or the balance of empty space.
+
 Observations include likely text glyphs used as button icons, unslotted SVGs,
 passive cells offset from neighbouring input centres and complete cell blocks in
 record/action rows, supporting copy echoing a visible action label, a copy inventory