@flood-md/agent 0.2.10 → 0.2.11

package/manifest.json

@@ -72,6 +72,11 @@
       "target": ".agents/skills/flood-ui/references/flood-spacing/SKILL.md",
       "kind": "skill"
     },
+    {
+      "source": "references/flood-motion/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-motion/SKILL.md",
+      "kind": "skill"
+    },
     {
       "source": "references/flood-foundations/SKILL.md",
       "target": ".agents/skills/flood-ui/references/flood-foundations/SKILL.md",
@@ -146,9 +151,14 @@
       "source": "references/record-decisions.md",
       "target": ".agents/skills/flood-ui/references/record-decisions.md",
       "kind": "reference"
+    },
+    {
+      "source": "references/component-families.md",
+      "target": ".agents/skills/flood-ui/references/component-families.md",
+      "kind": "reference"
     }
   ],
-  "version": "0.2.10",
+  "version": "0.2.11",
   "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.10",
+  "version": "0.2.11",
   "type": "module",
   "description": "Versioned Flood design instructions for coding agents.",
   "license": "MIT",
@@ -22,8 +22,14 @@
     "README.md"
   ],
   "exports": {
-    "./inspect": {"types":"./lib/inspect.d.ts","import":"./lib/inspect.mjs"},
-    ".": {"types":"./lib/index.d.ts","import":"./lib/index.mjs"},
+    "./inspect": {
+      "types": "./lib/inspect.d.ts",
+      "import": "./lib/inspect.mjs"
+    },
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.mjs"
+    },
     "./dist/*": "./dist/*",
     "./DESIGN.md": "./DESIGN.md",
     "./SKILL.md": "./SKILL.md",

package/references/component-families.md

@@ -0,0 +1,146 @@
+# Author a component that belongs to Flood
+
+Use when adding a reusable primitive, extending its visual contract or composing
+a new shared component. This applies inside Flood itself and to project-owned
+composites. Keep the installed/source distinction: a consumer cannot invent a new
+package export or edit an installed dependency to implement these decisions.
+
+## Choose the family before choosing values
+
+Identify the component's role and compare the closest existing owners in their
+rendered states. A new name is not a reason for a new visual recipe. Record the
+chosen siblings and intentional differences in development notes, outside the UI.
+
+| Relationship | What should be shared |
+| --- | --- |
+| Action and icon action | Button/IconButton height, text, icon scale, insets and focus treatment |
+| Text/selection/number field | Field label relationship, control height and field-state semantics |
+| 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 |
+
+Reuse these owners inside the new component. Extend the smallest missing owner
+before adding a composite override. For example, the Toolbar that draws an
+OverflowActions background owns its shape; a playground-only border-radius does
+not establish that capability for other consumers.
+
+## Define the visual and behavioral contract together
+
+- Use matching semantic token roles. Equal-looking values are not necessarily
+  interchangeable roles; a field radius and an action radius can evolve separately.
+- Derive sizes from the family's controls. Label line height, explicit icon box,
+  interactive height and optical insets must still agree at every exposed size.
+- Name variants by a meaningful role or shape. Keep appearance separate from
+  state: selected, read-only, disabled, invalid and focus are not interchangeable.
+- Make the outer geometry deliberate. A single-row capsule action rail can use
+  a pill shape; a wrapping or vertical group may need rounded geometry. Do not
+  blindly apply a pill to a multi-row surface. Use the spacing workflow to assess
+  nested radii and the actual inset; independently interactive neighbours need
+  not share a concentric-radius formula.
+- Account for padding and stroke in the space available to children. Overflow
+  calculations use the content box, not the outer border rectangle. Check the
+  threshold at which an item moves into the overflow owner.
+- Keep behaviour in the component that owns it. A focusable read-only text field
+  still needs a visible focus indicator and selection/copy. It blocks edits and
+  its chooser; disabled has a different native contract. Do not erase focus to
+  make a state look quieter or add helper copy merely to explain that contract.
+
+## Compare the family in one scene
+
+Repeated navigation/record rows share columns, not just height and font. Before
+accepting a composition, compare glyph centers, label starts and trailing action
+centers between header, groups, iconless/icon-bearing rows and footer. Define the
+indent of descendants deliberately and reserve missing peer anatomy. Scrollbar
+visibility must not silently change only the middle pane's content tracks.
+
+NavigationItem owns shared row geometry for native Link destinations, Button
+commands and disclosure. A branch without a destination uses a full-row toggle;
+a destination with children has distinct sibling link and disclosure targets,
+never nested controls or a link click that also toggles. The complete row owns
+its current/hover surface, so selection does not end at an unrelated shorter pill
+before the chevron. Budget real trailing anatomy once. NavigationTree composes
+these rows and manages hierarchy rather than supplying a parallel visual recipe.
+
+NavigationGroup owns optional label/action/separator and independent group
+disclosure. Its compact presentation reveals destinations without discarding the
+accepted expanded choice. Hiding a title cannot remove a needed accessible name
+or make a command unreachable. Compare headed/unheaded groups and all optional
+anatomy; an available slot is not a reason to populate it.
+
+Sidebar reuses NavigationGroup and NavigationTree. Its compact branches reuse
+Popover; full destinations retain Link and normal Tab behavior. Header/footer
+adapt through slots, with opt-in shell separators. The actual brand, toggle,
+destination and account hit areas share the full compact rail axis; a centered
+wrapper around a start-aligned Menu trigger is insufficient. Expanded slots share
+icon/text tracks. Its ScrollArea uses the existing edge lane for clearance. Keep
+material at the sidebar owner, without another material behind each group.
+Separate route identity, group/branch expansion and sidebar width; compare both
+profiles beside the small owners at the same size, with long text and bounded
+height. The 0.2.11 candidate's APIs require matching installed declarations.
+Disclosure artwork stays subordinate to destination icons without reducing hit
+areas; IconButton.iconSize separates these responsibilities. Compact hints reuse
+Tooltip on the actual Link/button, preserve refs and event handlers, and disappear
+when a branch flyout opens. Pane-toggle glyphs change with accepted visibility.
+
+Material context is part of the family contract. Compare actions, fields,
+choices, selection and supporting elements on the same material. A shared
+semantic context should correct the family together; a descendant-only button
+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.
+
+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
+as another general toolbar. The host owns selected IDs, confirmation, accepted
+updates, positioning and scroll clearance.
+BulkActionBar counter can be label, number or none. Visible counters reserve
+their width across count changes; choose counterWidth for the expected localized
+summary rather than sizing it from each current count. Hiding it removes its slot.
+
+CollectionToolbar composes the search, Tag, Button and Popover families without
+adding a surface. Use normal Tab navigation for this mixed input/action group.
+Compare SearchInput and existing collection controls at the same controlSize;
+preserve the end anchor, reserved reset space and contextual action colors.
+Keep saved views and query execution in the host; filterContent supplies its draft.
+
+CollectionViewSwitcher composes Select and existing action owners on a separate
+saved-view row. One command uses Button; multiple commands use OverflowActions.
+Use its plain container variant beside peer fields so another material/inset does
+not enlarge the command group. Contained remains appropriate for standalone rails.
+Use the same controlSize and keep Select and action hit areas coherent. Queries,
+dirty-state policy, permissions, dialogs and persistence belong to the host.
+
+FilterGroup composes FilterCondition and existing matching/actions. Preserve
+stable row IDs and accepted controlled state. Addition/removal focus belongs to
+the group after acceptance; Apply/Cancel, validation and query evaluation remain
+host-owned. Do not add a nested material or empty-state narration just because
+the flat group has its own component name.
+
+Render the new control beside its nearest sibling, with the same label/content,
+size, surface and root text scale. Review rest, hover, keyboard focus and the
+states the component actually supports. Include long content, empty/optional
+slots, narrow tracks and enlarged text. The scene is verification tooling, not a
+new runtime wrapper or a mandatory product screen.
+
+Measure what looked wrong: glyph/text centres, visible insets, nested curves,
+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.
+
+## Keep the contract discoverable
+
+In Flood source, update declarations, component examples, applicable guidance
+and the version decision together; regenerate the existing knowledge catalog.
+In a host, document the project-owned composite and its actual dependencies.
+Do not add unsupported props to examples or a parallel handwritten API index.
+Report executed behavioural/visual checks separately from guidance that was
+merely read. Record deliberate family exceptions instead of making an isolated
+fix the next component's accidental default.
+
+Track actual consumers and interactions for a proposed atom. Demonstrate a shared
+responsibility in different compositions before promoting a recipe helper into
+the package. Do not insert an owner merely to increase its usage count: one
+command can remain Button while a constrained command collection uses
+OverflowActions. Reuse is judged by correct roles and reachable behaviour, not
+the length of an import list.

package/references/composition.md

@@ -138,9 +138,9 @@ Link defaults to text; opt-in solid/subtle/outline/ghost and
 Button sizes share the button recipe without changing native anchor semantics.
 Use href/target for navigation, Button for actions; never nest the two or add
 role=button. Link has no disabled/loading contract. Available in 0.2.3.
-Tabs switches linked content panels (not modes or radio values) on a shared
-contained surface. Avoid a second enclosing card inside the panel; selected fill
-joins the panel without an additional underline. Arrows activate by default,
+Tabs switches linked content panels. Use the default contained variant for a
+shared surface where the selected fill joins the panel. Use variant="line" for
+page-level sections whose content sits on the page canvas. Arrows activate by default,
 or focus only with activationMode=manual; Enter/Space commit. One tab
 stop, RTL/orientation aware, disabled skip. Panels stay mounted/hidden and retain
 native form constraints. Controlled/missing/disabled selected values derive first
@@ -278,4 +278,4 @@ Section headingLevel controls native h2–h6 semantics. Its independent headingS
 uses the existing Heading roles (section/page/large/display), defaulting to section.
 Keep document hierarchy meaningful when changing visual emphasis.
 
-For a command palette, compose Dialog and CommandList. The host owns commands, permissions, query reset and shortcuts; keep Escape available to the dialog. Avoid a duplicate modal or command-search engine. The project recipe lives in docs/recipes/command-palette.md in the source repository.
+Use CommandPalette for modal navigation and command search. The host owns commands, permissions, controlled query reset and shortcuts. Keep CommandList for inline search. The project recipe lives in docs/recipes/command-palette.md in the source repository.

package/references/customization.md

@@ -18,6 +18,20 @@ Keep reference values separate from semantic roles. Component recipes consume
 roles, and screen composition consumes components. An accent/material experiment
 must be scoped; it must not silently alter ordinary fields, text or focus.
 
+Filled material owners establish contextual neutral recipes for their children.
+Customize context-filled/base roles for a shared change; a direct consumer-role
+override on the owning material can refine that one scope. Verify canvas and
+elevated recipes together when increasing boundary contrast. Do not override
+surface.canvas to soften nested controls: it also supplies contrasting content
+and document/media wells. Use surface.current and the contextual supporting or
+readonly roles for those jobs. Explicit data-flood-surface attributes change
+context only, not the rendered material or overlay behavior.
+
+For a tinted theme, map the floating surface, translucent floating surface,
+floating border and floating selection alongside canvas and base/filled field
+roles. Open a Select on both canvas and a filled surface and check its trigger,
+panel and highlighted option. Check the opaque fallback as well.
+
 Keep layout/typography in rem, role line heights and tracking intact unless the
 task explicitly changes them. Never impose a root 16px or 62.5% reset. Bundled
 Inter retains its OFL notice; external icon/font assets keep their own notices.

package/references/flood-composition/SKILL.md

@@ -5,6 +5,10 @@ description: Build or review Flood UI from existing library primitives before ad
 
 # Compose Flood from its primitives
 
+When adding a reusable component or changing its visual contract, read
+[component families](../component-families.md) before choosing anatomy, sizing,
+shape or states. It governs Flood's own components as well as host composites.
+
 Existing Flood components are the building blocks, including inside other Flood
 components. Preserve their anatomy and behavior when improving a composition.
 Read the governing project instructions, matching declarations and relevant

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

@@ -5,6 +5,40 @@ description: Assemble Flood tables, lists, cards and file records with long or c
 
 # Compose meaningful data structures
 
+Enable selection when it has a real consequence: a bulk operation, comparison or
+another requested selection task. Do not add checkboxes merely because the table
+supports them. Exercise the resulting action with the actual accepted scope.
+
+For search, multiple conditions or saved query definitions, read
+recipe:collection-views from the installed catalog when available. Separate the
+working query, an uncommitted condition draft, a named saved definition and the
+result/selection state. Save filters and supported sort, not result IDs. Name-only
+edits must not commit dirty filters; deleting a view must not delete records.
+Reset/revalidate page and selection when the query changes. Preferences read
+failure need not hide an independently loaded collection, but must block writes
+to that failed store and must not be disguised as an empty saved-view list.
+
+Use CollectionViewSwitcher for accepted view choice and applicable commands,
+separate from CollectionToolbar's working query controls. Offer update only for
+an editable changed definition; keep rename name-only. The component requests IDs,
+while the host owns acceptance, persistence and confirmation. Return naming and
+deletion dialogs to its selectRef when their original action may disappear.
+
+For one finite-choice property/operator/value row, use FilterCondition rather
+than reassembling differently sized controls. A property change clears the
+previous property's values in the proposed draft. Empty values are incomplete,
+not an instruction to broaden the accepted query. The host owns Apply/Cancel,
+duplicate-property policy and focus to another condition or Add after removal.
+Text/date/number predicates need a deliberate supported editor; do not pretend
+the finite-choice row implements arbitrary query semantics.
+
+FilterGroup composes those rows for a flat finite-choice draft. It owns row IDs,
+all/any controls and accepted row-change focus; the host owns Apply/Cancel and
+query evaluation. Preserve accepted rows when addition limits or duplicate
+policies change. Do not turn a new empty row into a broad accepted query or
+wrap an empty group in decorative onboarding. Keep group labels contextual;
+individual hidden legends/control names remain available to assistive technology.
+
 Use the installed component contracts and
 [composition workflow](../flood-composition/SKILL.md). Start with the content's
 relationships, not a wrapper around every piece of text.
@@ -21,6 +55,11 @@ the interface-content workflow for contextual placement.
 - Table/DataTable preserve caption, headers, cell relationships and documented
   sorting/selection behavior. A footer represents a summary and should be
   visually distinguishable without relying on a heavy border everywhere.
+  Mark comparable quantities and amounts with DataTable column `numeric` or
+  Table header/cell `data-numeric` for logical end alignment and tabular digits.
+  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.
 - 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.
@@ -39,6 +78,11 @@ before filling metadata and actions. Identity, supporting context, lifecycle sta
 priority and timestamps have different purposes. Use Table/DataTable when users
 need several named comparisons; a trailing Inline of values is not a column model.
 
+Use Table for short static details, such as receipt lines. When DataTable owns
+sorting or selection and its result range adds no useful information, set
+`showResults={false}`. Keep the range when it helps explain pagination or
+the scope of filtered results. Selection feedback and page controls remain.
+
 ## Exercise data and geometry
 
 Test no records, one record, long/wrapping names, absent optional media/actions,
@@ -67,3 +111,76 @@ Use the documented local overflow owner, with a meaningful accessible name. Focu
 the last action/cell and check that a rail or rounded corner does not cover it.
 Compare narrow/wide, enlarged text and RTL. Locale-sensitive text in prerendered
 examples needs consistent server/client locale to avoid hydration differences.
+
+## Declare remote and selection ownership
+
+Group collection controls by the task they affect. At a wide viewport, use the
+available inline space for related search and filter controls. Keep view selection
+and its management actions together, and make the result list reachable without
+passing several sparse control rows. Add a row when it improves grouping or is
+needed for wrapping, rather than assigning a row to each control type. Preserve
+logical reading and keyboard order when the same groups wrap at enlarged text or
+a narrow viewport. A collection host chooses the layout for its actual content.
+Match the heights and typography of fields and actions sharing a control row.
+Review the rendered sizes together. Keep management actions beside the view they
+affect unless the wider composition gives their separation a clear purpose.
+
+Default to at most two secondary filter controls beside a collection search.
+When more than two filter properties are available, put the secondary choices
+behind one Filters trigger. Count properties, including inactive filters, rather
+than counting component names. Search, view selection, sorting and record actions
+have different roles and do not count toward this filter limit. Keep applied
+conditions visible as removable summaries and keep Clear filters reachable.
+An explicitly primary filter can stay visible when the task warrants it. Move
+secondary controls earlier if their labels or enlarged text already crowd the
+row. Preserve draft/apply/cancel semantics and meaningful labels inside the panel.
+When its trigger supplies the shared context, a nearby value can omit repeated
+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.
+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.
+Inactive Clear filters reserves space and leaves the accessibility tree. Removal
+and reset focus the persistent Filters trigger, or search without a panel.
+
+DataTable supports ready/loading/error states. Use emptyContent to compose
+EmptyState and a meaningful next action inside a ready empty table instead of
+removing its headers. Distinguish no records from no matches; only the latter
+offers reset of an active query. Custom empty content must not stand in for a
+read failure or pending request. After reset removes the action, focus a persistent
+query control. Omit emptyContent for the ordinary labels.empty message.
+
+Client DataTable receives the complete local collection. Server paginationMode
+receives one already sorted page, controlled page/onPageChange and totalRows;
+sortable server columns require controlled sort/onSortChange. Do not locally
+slice or sort a server page. Reconcile page when a filter reduces its total.
+The host owns query identity and abort/request generations so a late response
+cannot replace the current query. Present loading/error explicitly rather than
+labeling old rows as an accepted new page.
+
+Server page selection covers supplied rows only. Dataset scope requires controlled
+selectedIds and host validation of IDs beyond that page. Select-page never means
+select every search result. Clear/revalidate selection on query or permission
+changes. Capture confirmed IDs and keep the proposal after an operation refusal.
+Use BulkActionBar for a compact selected-record command rail; it composes
+Toolbar and OverflowActions and keeps one row with a pill exterior. Prefer two
+visible commands; at most three, with lower-priority commands in More. Use a
+general Toolbar for unrelated editing controls rather than adding them here.
+Show the actual selected count, distinguish page selection from the collection
+scope, and keep clearing selection separate from resetting filters. Confirm
+consequential actions against a captured list of IDs. Pending work targets that
+snapshot even if the visible query changes. On success remove only those IDs
+from current selection and reconcile pagination. Preserve accepted records and
+selection after rejection, and retry the captured proposal. Give disappearing
+action bars an intentional focus destination. Keep confirmation dialogs outside
+the Toolbar's roving descendants.
+A floating selection bar can keep record layout stable while selection changes.
+Anchor it to the viewport with safe-area spacing and a bounded width. Measure
+actual height and reserve scroll clearance so final rows and pagination remain
+reachable. Verify its menus near the viewport edge and keep modal confirmation
+in the dialog layer.
+Read recipe:record-workspace from the matching installed catalog for a working
+composition and its limits.

package/references/flood-feedback/SKILL.md

@@ -56,3 +56,28 @@ enlargement. Keep content visible without stealing focus merely to announce it.
 Reserve feedback space in a demo when needed for a stable sample, not universally
 inside every production component. Report audible announcement behavior only
 when it was actually tested with the relevant assistive technology.
+
+## Distinguish persistence failures from emptiness
+
+Missing, valid, malformed, read-failed and write-failed are distinct states. A
+read/parse failure is not permission to initialize samples or overwrite records.
+Keep the raw snapshot where available and block editing/writes until recovery
+succeeds or the user explicitly replaces that collection. Offer a named retry
+and, when useful, a recovery export. A missing key can initialize an empty list;
+fixture records declared in a test brief must not mask read failure.
+
+A refused write preserves the last accepted collection and the current draft.
+Discarding that draft ends its own save error, not an unresolved collection read
+error. Accept results only for the current request/draft generation. These are
+host-state decisions; Alert itself does not read storage or own recovery.
+
+Describe the observed failure without inventing its cause. A refused browser
+write can mean quota, denied access or another storage failure; do not prescribe
+clearing data or freeing space unless that cause is actually known. Retain the
+draft and offer an applicable retry/recovery action first.
+
+Build write proposals without mutating the accepted collection or the current
+draft in place. A rejected save must not append history, change status or alter
+the next retry before acceptance. Retry should propose one operation, not repeat
+side effects from the failed attempt. When a read failed, do not present invented
+zero totals or an empty collection as if the data had loaded successfully.

package/references/flood-forms/SKILL.md

@@ -43,6 +43,12 @@ need no inner heading. Field labels and values keep their documented sizes.
 
 ## Group before laying out fields
 
+For settings with one Save action, keep a draft and the last saved values
+separate. Group related fields under named sections, validate the complete
+draft, and keep entered values available after a refused save. Reset returns
+to the latest saved values. Confirm a successful save only after the host
+accepts it. See `recipe:settings-workspace` for a working local example.
+
 Choose the form's reading order and semantic groups before placing controls in
 columns. Establish shared outer tracks, gap and group padding. Use a single Grid for
 related rows; do not narrow one numeric field in only one row merely because its
@@ -78,6 +84,11 @@ catalog. It demonstrates shared tracks and two-field peer groups in a workspace
 form. Adapt its grouping to the host; do not copy its business content or add
 unrequested sample records.
 
+Choose the number of field tracks from the width available to the form. A wide
+viewport can still contain a narrow drawer or a form squeezed by a sidebar.
+Verify the same field group in wide and narrow hosts at the same viewport width.
+Check reading order, control widths and labels after the group wraps.
+
 ## Exercise transitions, not just props
 
 Check entry, clear, incomplete drafts, invalid input, accepted/refused controlled
@@ -92,3 +103,23 @@ Show a real success only after the host operation succeeds. Explain consequentia
 storage limits once where they matter; a local example does not require a banner
 or repeated captions about its implementation. Follow the interface-content
 workflow for placement and wording.
+
+## Search values and remote collections
+
+Selected chips supply a MultiSelect's visible context. Its empty query should
+not reserve a redundant placeholder row; account for actual action/caret space
+and let real search or overflowing chip content grow. Do not hide the combobox
+or its keyboard entry to force a fixed-height appearance.
+
+Combobox/MultiSelect submit selected IDs. Autocomplete accepts arbitrary text and
+submits that text; choosing a suggestion does not turn it into an ID field.
+Do not weaken a fixed-choice requirement merely to accept a failed search.
+Manual filtering requires controlled query (Autocomplete: value), optionsQuery
+identifying the accepted result and explicit loadState. Keep selectedOptions
+while result pages change. The host owns fetching, cancellation and stale response
+rejection; the control also prevents choosing options for another query.
+
+Keep errors/loading distinct from zero matches and provide onRetry when useful.
+Test Enter, Escape, blur, native reset, controlled refusal, IME, disabled/readonly
+and actual FormData. Query completion, selection and text editing are separate
+events. Do not announce success merely because a fetch callback fired.

package/references/flood-foundations/SKILL.md

@@ -26,6 +26,8 @@ applies the existing dark base; it does not start a palette, theme or motion red
 - Preserve rem sizing, the host root font, role line height and tracking. IconSlot
   owns explicit artwork dimensions; IconButton owns the accessible action/target.
   A large control does not mean an unconstrained SVG or oversized supporting copy.
+  Supporting disclosure can use a smaller IconButton iconSize while preserving
+  its control size, focus area and touch target. Do not size all glyph roles alike.
 
 Action icons are artwork with an explicit IconSlot size, not a plus, arrow or
 cross typed into the label. Font glyph bounds vary even at the same font size.
@@ -34,6 +36,27 @@ actions can omit the icon. Keep real symbols that are content, such as currency,
 phone prefixes or mathematical expressions, as text. Inspect the actual artwork
 and its centre relative to the label at the chosen Button size.
 
+## Surface context
+
+Choose a material owner before tuning the nested controls. Surface, Dialog,
+Drawer, Popover, selection popups and floating action bars establish their own
+context. Neutral action fills, fields, selection and supporting elements adapt
+to that nearest owner. Preserve solid action prominence, feedback meaning,
+content contrast and the independent accent focus.
+
+Do not fix a dark secondary button on an elevated panel with a page-specific
+button color. Inspect the shared context roles and another consumer first.
+Avoid broad ancestor selectors: a nested Surface owns its own context, while
+a transparent layout wrapper inherits the current one. Material levels do not
+count DOM nesting depth. Never alternate light/dark fills for every wrapper.
+
+Review the same controls on canvas, default, raised, modal and floating surfaces.
+Include nested surface resets, top-layer menus, read-only/disabled fields,
+selection, supporting chips and progress tracks, not only Button screenshots.
+Check the opaque fallback when transparency is reduced or unsupported and
+system colors under forced colors. A token's alpha is not evidence of sufficient
+contrast: inspect the composited color over the actual backing content.
+
 ## Evidence
 
 Trace a changed role to its consumers and compare resting, hover, selected,
@@ -42,3 +65,16 @@ a Surface and a popup over that field; inspect long text and enlarged root text.
 Do not claim visual consistency from token names or matching hex values alone.
 See [customization](../customization.md) and
 [accessibility](../accessibility.md) for perception/override details.
+
+## Destructive action tone
+
+Button and IconButton accept tone="danger" for an actual destructive command,
+independent of solid/subtle/outline/ghost prominence. It uses existing semantic
+color roles in FloodRoot; keep the normal accent focus and disabled behavior.
+A red label is not confirmation or permission to delete. Preserve that intent
+when OverflowActions moves the command into Menu.
+
+A numeric stepper is one horizontal control, not three wrapping fields. Keep its
+minimum action/value budget inside a dense table's local scroll region. Test the
+actual control at enlarged text in its narrowest repeated track; widening an
+unrelated outer wrapper is not evidence that its internal geometry is sound.

package/references/flood-hierarchy/SKILL.md

@@ -3,6 +3,11 @@ name: flood-hierarchy
 description: Establish visual hierarchy, shared form tracks and vertical rhythm in Flood screens, forms and overlays. Use when titles, groups and labels compete or a composed interface feels flat; not a fixed page template.
 ---
 
+Use PageHeader for the page's main heading and page-wide actions. Use Section
+for a named block within the page. Keep breadcrumbs outside the header and
+collection filters next to the collection. Add supporting copy only when it
+changes what the user can understand or do on this page.
+
 # Structure before emphasis
 
 Start with the user's task, reading order and installed component contracts.
@@ -49,19 +54,30 @@ semantic grouping can justify another order. Do not turn every group into a box.
 
 ## Choose a rhythm, not a uniform gap
 
-For an ordinary desktop form, start with space-6 between field rows and space-8
-between independent groups or before the closing action row. The Dialog body
-inset is already space-6: do not add the same inset again to the first child.
-Keep a label nearer its control than the next field and a group title nearer
-its own fields than the next group. Dense filters, table editors and choice lists
-have different budgets; apply their component recipes instead of spreading this
-form rhythm everywhere.
+For a compact settings form, start with the page heading, section legends,
+and ordinary Field labels. Check that each level is recognizable by size,
+weight and proximity. Use space-6 between sections as a starting point.
+Repeated switch rows already provide a full hit area. Keep those rows close
+and align the switches on one shared edge within a readable column.
+Check actual row centers and wrapping at enlarged text.
+
+Keep a label visually nearer its control than the next field and a group title
+nearer its own fields than the next group. Inspect the rendered line height,
+control padding and fill before adjusting a parent gap. Dialog already supplies
+its body inset. Compare one change in size, weight, contrast, or spacing at a
+time using the [spacing review](../spacing.md#judge-the-space-you-can-see).
 
 Treat action order/alignment as part of the task. An end-aligned cancel/primary
 pair can finish a short desktop dialog clearly. This is not a universal order:
 respect host conventions, direction, destructive confirmation and keyboard flow.
 Do not add a footer surface or separator unless it resolves a real boundary.
 
+Choose the strongest action within the current task region. Check the page,
+each repeated row and any open overlay separately. In a settings form, Save
+can lead and Discard can stay secondary. In a filtered empty list, clearing
+filters may become the most useful action. A read-only detail can have no
+primary action. Keep the intended next action recognizable across states.
+
 Record lists and details need an information budget as well as type hierarchy.
 Use the [records workflow](../flood-records/SKILL.md) for metadata placement,
 comparison columns and status/category/priority meanings; do not give every

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

@@ -78,6 +78,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 +136,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 +153,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.