@flood-md/agent 0.2.8 → 0.2.10

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

@@ -0,0 +1,69 @@
+---
+name: flood-data-display
+description: Assemble Flood tables, lists, cards and file records with long or changing data. Use for content hierarchy, overflow, row actions and data-state composition.
+---
+
+# Compose meaningful data structures
+
+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.
+
+Keep visual/test fixtures separate from the host's working records unless sample
+data is explicitly part of the task. Do not seed a new user's persisted list with
+fictional business records just to fill a screen. Use isolated test state for
+populated screenshots and exercise the real empty state. When samples are required, identify their provenance in the test brief/README.
+A visible distinction is needed where it changes interpretation or action, such
+as sample records mixed with real records. Do not automatically add a permanent
+Demo badge to the shell of an explicitly requested isolated prototype; follow
+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.
+- 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.
+- Keep row actions as named Flood Button/IconButton/Menu controls. Do not turn
+  a whole row into a competing clickable wrapper around its nested actions.
+- FileItem/FileMeta/UploadItem and their list owners compose file presentation;
+  use their existing format/size/status/progress primitives. Selection, transport
+  and preview are separate host operations. Do not manufacture upload completion.
+- Preserve native image alt/fallback semantics and aspect constraints. Decorative
+  artwork should not duplicate an adjacent accessible identity.
+
+## Choose the information, not all available slots
+
+For record lists/details, apply the [records skill](../flood-records/SKILL.md)
+before filling metadata and actions. Identity, supporting context, lifecycle state,
+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.
+
+## Exercise data and geometry
+
+Test no records, one record, long/wrapping names, absent optional media/actions,
+loading, error/retry and selection/sorting where available. Keep error text useful
+without inserting a second empty-state design or moving unrelated controls.
+Align file title/metadata and status/progress by their intended row relationship;
+do not hide a StatusIndicator dot or replace Progress with a custom track.
+
+For an editable table, compare the centre of plain amounts and row actions with
+the neighbouring input controls. Table centres record/action and editable rows
+by default; opt into cellVerticalAlign="top" only for deliberate prose alignment.
+Use the shared cellVerticalAlign contract rather than
+moving text with transforms or overriding Input, NumberInput or Button internals.
+Native style on an individual host-owned td/th can express an exceptional cell.
+Do not depend on a low-specificity descendant CSS override. Check the rendered
+centres; equal cell padding alone does not establish alignment.
+
+Also inspect readable column widths with long neighbouring records. A centred
+cell can still be wrong when a status or date is fragmented into single letters.
+Table and StatusIndicator preserve word-based intrinsic width by default; keep
+that recipe rather than applying global overflow-wrap:anywhere. Deliberate
+technical identifier cells can opt into data-wrap="anywhere". Otherwise use
+local scrolling or appropriate column budgets, not an empty no-overflow claim.
+
+Use the documented local overflow owner, with a meaningful accessible name. Focus
+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.

package/references/flood-feedback/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: flood-feedback
+description: Choose Flood status, progress, alert, loading and empty-state feedback with honest operation state. Use for meaningful messages and announcement ownership.
+---
+
+# Describe what actually happened
+
+Use installed declarations and [accessibility](../accessibility.md). Assign the
+visible role before choosing color: StatusIndicator names a state, Badge marks
+metadata, Progress describes task progress, Meter describes a bounded measurement,
+Alert gives contextual feedback and EmptyState explains missing content.
+
+For several record attributes, use the [records skill](../flood-records/SKILL.md).
+A category called Error is not a failed operation; priority is not lifecycle state.
+Choose the semantic owner before its appearance, and keep essential triage data
+visible even when reducing decorative emphasis.
+
+## Keep one owner for each message
+
+- Status text must distinguish pending, success, failure, cancellation and local
+  preview state. A callback firing or elapsed timer is not a completed backend
+  operation. Do not display a success count, upload or save that did not occur.
+- Unknown Progress has no known percentage; Meter has no unknown state. A useful
+  label/valueText explains units when a percentage would be misleading.
+- Alert/Toast/live-region choices depend on urgency. Keep static explanation
+  silent unless a change requires announcement; do not add multiple live regions
+  around a composite's existing announcement. Announce does not imply a visible
+  style change or guarantee speech from every assistive technology.
+- Spinner retains a meaningful accessible label where standalone. Skeleton is
+  decoration, not another announced task. Preserve the existing reduced-motion
+  behavior without introducing a new animation system.
+- EmptyState identifies the actual condition. A title can be enough; add a
+  description only for new decision-relevant information, not an instruction
+  repeating a visible action. Its icon/action use existing primitives.
+
+## Scope feedback to its operation
+
+Associate a message with the operation and record that produced it. Preserve
+entered data after refusal and keep a useful error while that operation remains
+unresolved. A successful retry clears/replaces its failure. Explicitly discarding
+the draft ends that draft's save error; it must not follow the user to a list or
+another record. Ignore late results belonging to an abandoned operation.
+
+Do not solve this with an automatic timer inside Alert or by clearing every
+message on navigation. A collection-wide read failure can still block editing
+after changing views and must remain until resolved. The host's state model owns
+that distinction; the feedback primitive only presents the supplied state.
+
+## Evidence
+
+Trigger the operation and observe each applicable transition, including failure
+and retry. Also follow failure → explicit discard → list → reopen a saved record;
+the abandoned draft's failure must be gone and the saved data unchanged. Distinguish
+that from a still-unresolved collection-wide error. Check optional description/action/icon slots, long messages and text
+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.

package/references/flood-forms/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: flood-forms
+description: Compose and verify Flood form ownership, labels, values, validation and reset. Use for fields, selection controls or composed form inputs.
+---
+
+# Preserve the form contract
+
+Consult installed declarations and the matching component guide before choosing
+props. The [composition reference](../composition.md) documents selection and file
+ownership. Read the matching DateField/DateTimePicker component guide for its
+specific civil-value and draft contract; [accessibility](../accessibility.md)
+documents associations and feedback.
+
+For an ordinary business date field, prefer DatePicker so users can both type and
+choose visually. DateField is the lower-level segmented editor without a popup;
+choose it for an explicit entry-only interaction or inside a composition that
+already supplies Calendar. Do not silently omit the calendar just because the
+brief did not enumerate every affordance of choosing a date.
+
+## Assign ownership
+
+- Field supplies label/description/error associations through its render props;
+  spread those props onto the actual Flood control. Fieldset groups related
+  controls with a legend; each choice still needs its own meaningful label.
+- Decide controlled value/onValueChange versus uncontrolled defaultValue. A
+  default initializes; changing it is not an update contract. Handle host refusal
+  of a requested value without reporting that it was saved or losing focus.
+- Set native name/form/required and submit/reset button types deliberately.
+  Inspect FormData, including repeated checkbox names with getAll and the
+  component's documented submission shape. Visible prefixes are not submitted
+  values; Token/Tag/Toggle actions are not automatically native form inputs.
+- Read-only and disabled are different. Use readOnly only where the installed
+  API supports it; retain copy/focus/submission as documented. Disabled values
+  are excluded from native submission. Do not synthesize read-only behavior by
+  disabling unrelated controls or hiding a field's value.
+- 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 visual roles and rhythm, read the [hierarchy skill](../flood-hierarchy/SKILL.md).
+Fieldset legendSize="section" is for an independent section; a short form may
+need no inner heading. Field labels and values keep their documented sizes.
+
+## Group before laying out fields
+
+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
+value is short. Preserve corresponding vertical edges before optimizing widths. Related groups
+should share those tracks: do not independently choose a four-column grid above
+two columns below and assume their edges align. A group may span the whole layout
+when its content needs it; not every field should have the same width.
+
+For Flood record/settings forms without a denser host requirement, start with
+at most two field tracks per semantic group. Four metadata fields become two
+pairs rather than an automatic four-field strip. Use one track for a narrow group
+or long field. A denser table editor, filter toolbar or explicit host design is
+a different context; record why its structure needs more tracks.
+
+For two peer groups, use two equal outer tracks and subdivide each consistently
+when a group contains short related fields. A pair of two-field groups can read
+more clearly than four unrelated columns. This is a pattern to evaluate, not a
+rule that every form has two columns or an invoice-specific template.
+
+Keep a group's title, controls and supporting message together in reading and DOM
+order. Distinguish page, group and field roles without adding headings merely to
+fill containers. Compare shared leading/trailing edges and gutters in the rendered
+form, including absent descriptions, long labels and changed field values.
+
+Measure the controls' content edges, not only the Grid boxes. A full-width padded
+Surface containing two tracks and two separately padded Surfaces can use identical
+Grid props while their actual controls differ by one surface inset. Nested padding
+must participate in the same track budget. Compare corresponding first/second
+control starts and widths across those groups; matching outer containers is not
+sufficient. Do not insert an empty grid child merely to occupy an unexplained gap.
+For a concrete starting structure, discover recipe:grouped-form in the installed
+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.
+
+## Exercise transitions, not just props
+
+Check entry, clear, incomplete drafts, invalid input, accepted/refused controlled
+updates, submit and normal/cancelled reset where supported. Match date/time
+default values to the selected precision and remount only the demo when a changed
+representation genuinely requires it. Do not silently replace user edits.
+
+FileInput cannot receive a fabricated FileList or ordinary controlled text value.
+Separate selection from upload transport and progress. Calendar/date/time controls
+represent their documented civil values; do not infer a timezone or server save.
+Show a real success only after the host operation succeeds. Explain consequential
+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.

package/references/flood-foundations/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: flood-foundations
+description: Apply Flood's existing dark semantic surfaces, typography, control sizing and icon geometry. Use for foundation consistency or token-consumer review.
+---
+
+# Apply the dark foundations
+
+Use the installed declarations, token manifest and DESIGN contract. This workflow
+applies the existing dark base; it does not start a palette, theme or motion redesign.
+
+## Decide the role before the value
+
+- FloodRoot owns the dark profile; import the shared stylesheet once in the host.
+  A legacy light control outside it is not evidence of a supported new theme.
+- Distinguish reference values, semantic roles, component recipes and host layout.
+  In a consumer override an existing semantic role on a deliberate scope; never
+  edit node_modules. In Flood source, author tokens only in tokens.json.
+- Choose canvas, container, field and floating-surface roles from their actual
+  context. A floating surface must remain legible over its parent; inspect alpha
+  compositing, its perimeter and shadow together rather than darkening everything.
+- Decorative dividers, necessary control boundaries, selection and keyboard focus
+  have different jobs. Do not substitute an emphasized border for a quiet divider
+  or mute an entire control to soften one line. Focus remains a clear accent.
+- Heading level expresses document structure; visual size is a separate decision.
+  Supporting labels/descriptions stay subordinate without becoming unreadable.
+- 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.
+
+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.
+Use the project's licensed icon pack or an original SVG in IconSlot; text-only
+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.
+
+## Evidence
+
+Trace a changed role to its consumers and compare resting, hover, selected,
+focused, disabled and advisory/error states where applicable. Inspect a field on
+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.

package/references/flood-hierarchy/SKILL.md

@@ -0,0 +1,87 @@
+---
+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.
+---
+
+# Structure before emphasis
+
+Start with the user's task, reading order and installed component contracts.
+Distinguish the task title, genuinely independent groups, field labels, input
+values and actions before choosing their size or color. A short form may need
+only its task title and labels. Do not add a legend, subtitle, card or divider
+merely to create visual levels. Meaning comes from the interface-content workflow;
+this workflow makes that meaning visible.
+
+## Assign each relationship to its owner
+
+- Dialog owns its task heading and the body inset. Its dark title uses the
+  dialog-title role (1.25rem / 600); it is distinct from compact popup captions.
+- Field owns the label-to-control relationship: space-1 (.25rem) in the dark
+  profile. DateField/TimeField already use that relationship. Leave room between
+  independent fields instead of increasing the gap inside every label/control pair.
+- Field labels use field-label typography (.8125rem / 500) and readable primary
+  content color. Do not shrink every label or fade necessary labels to manufacture
+  hierarchy; units, required markers, errors and accessible associations remain.
+- Fieldset defaults to a compact label-sized legend for related choices. Use
+  legendSize="section" for a necessary independent form section: group-title
+  typography (1rem / 600) and space-4 before its fields. A legend is still a native
+  group label, not a new document heading level. Optional hint/choice relationships
+  keep their compact component-owned spacing.
+- Grid owns common tracks; Stack and Inline own relationships between fields,
+  groups and actions. Never duplicate component anatomy with styled text.
+
+These are installed recipe defaults, not permission to use missing APIs in an
+older package or to override private selectors in a host stylesheet.
+
+## Establish a shared frame
+
+Use one Grid for related rows that should share vertical edges. Two equal tracks
+are a useful starting point for four short fields; long names and descriptions
+can span the width. Numeric content being short does not by itself justify a
+narrower track in only one row. If a specialized width is necessary, preserve the
+common grid or deliberately separate that group and check its visual relationship.
+Do not repair a whole-frame mismatch with manual widths on individual controls.
+
+Choose the user's reading order first. In an ordinary date/time form, a pair of
+calendar and time controls can share tracks with a later pair of duration/status
+controls. This is an example, not an appointment-specific template. Independent
+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.
+
+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.
+
+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
+attribute equal visual emphasis.
+
+## Verify the relationships
+
+Read the actual title/group/label styles; inspect the rendered result rather
+than comparing font-size declarations alone. Check complete text and long values,
+not only empty inputs. Measure the left/right edges of corresponding controls
+across rows, including nested padding and optional fields. A shared outer Grid
+alone is not proof that the input edges align.
+
+At the host's desktop baseline include 1280px with 24px root text as well as
+normal 1280/1440px views. Ensure the final action remains reachable if the dialog
+needs to scroll. Open actual date/selection popups: a calendar needs readable
+content width even when its anchor is narrow; a selection list has a different
+width contract. Keep viewport collision limits and nested Escape/focus ownership.
+
+Report the consequential choices and actual evidence outside the product UI.
+An empty inspector result does not establish hierarchy, necessary copy or visual
+quality. Preserve a failed clean run; improve the library/guidance owner before
+starting a fresh evaluation, rather than editing the historical result.

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

@@ -0,0 +1,142 @@
+---
+name: flood-interface-content
+description: Write or review Flood interface content with editorial decisions about copy, labels, hierarchy and states. Use for visible UI text and reference adaptation; not typography styling, campaigns or rewriting user documents.
+---
+
+# Edit the information, then the wording
+
+Read the task, existing product vocabulary and the relevant component contracts.
+Keep the requested audience, language, surface and scope. A test host is not an
+invitation to add a product story, onboarding, promotional banners or new flows.
+User-authored records and document bodies remain data; changing interface copy
+does not authorize rewriting them.
+
+## Give every text element a job
+
+Before adding copy, identify the user's current task and state. Each visible
+string should identify an object or control, distinguish choices, supply needed
+input guidance, explain a relevant consequence, report a real state or support
+recovery in the current task/state. A fact being potentially useful someday is
+not sufficient. If its removal changes none of those, remove the element rather than
+replace it with another friendly sentence.
+
+Make the decision in context:
+
+- **Keep** a necessary label, distinction, constraint, consequence at the relevant decision or recovery step after a real failure.
+- **Rewrite** an ambiguous or inaccurate message using the product's terms.
+- **Move** secondary, occasionally needed information to a relevant help surface.
+- **Remove** duplication, routine interface narration and filler added to fill space.
+
+Do not turn this into a shortest-copy contest. A longer explanation can be the
+correct choice for an unfamiliar decision, an exceptional state or a material
+consequence of an action being considered here. An ordinary list/editor is not a
+storage-selection or data-deletion decision: do not add a standing browser/storage
+warning just because clearing browser data could lose records. Put implementation
+limits in documentation/help; explain deletion/replacement consequences before
+the applicable action and actual persistence failures when they occur.
+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.
+
+## Separate prototype provenance from product state
+
+An explicitly requested local prototype or fixture-backed test app does not need
+an always-visible Demo, Prototype, Local only or Test environment badge merely
+because of its development context. Put that provenance and its implementation
+limits in the project README, test brief or review handoff. Do not fill a sidebar
+footer, header or empty region with a reminder, or replace a removed badge with
+a differently worded banner.
+
+Keep a visible distinction when it changes a decision on this surface: sample
+records mixed with real records, a meaningful selectable simulation mode, or an
+action whose effect/destination differs between environments. Place it beside the
+affected record, choice or action. Do not invent a mode switch or warning flow to
+justify an environment label. An isolated prototype is not a mixed live workspace.
+
+Removing prototype chrome does not authorize claims of real live video, delivered
+messages, production connectivity or other unimplemented capabilities. Keep
+accurate object/media accessible names and action wording; document the simulation
+in the handoff. Real Draft/Pending/Offline record states are not prototype labels
+and must not be removed by a word-matching rule.
+
+## Keep one vocabulary and an honest hierarchy
+
+Use the user's domain nouns and existing action terms. Name destinations by what
+they contain and actions by the result they cause. Avoid vague completion labels
+when several outcomes are possible. A validation check does not establish expert
+review; preparing a document does not send it; exporting a PDF does not create a
+restorable backup of editable records.
+
+A page title identifies its task or object. Add an eyebrow or subtitle only when
+it conveys another useful distinction. Do not automatically stack a category,
+the same category in a title, and a sentence describing that title. Section titles
+name actual groups; they do not each require an explanation. Semantic heading
+levels reflect the document structure, independently of visual sizing.
+
+Keep necessary repetition across different contexts: a dialog may need the
+affected object named again, a long form may repeat its primary action at the end,
+and a printed document has its own content hierarchy. Do not remove those merely
+because similar words appear elsewhere on the screen.
+
+## Explain only what changes a decision
+
+Prefer a clear label or unit to an added helper paragraph. Add a field hint for a
+non-obvious format, source or choice; do not narrate typing or repeat its label.
+Technical properties of the implementation belong in developer documentation
+unless the user is making a decision about them. A document preview usually
+does not need a caption about embedded fonts or selectable PDF text.
+
+Check actual behavior before writing states:
+
+- Errors say what failed and how the user can recover, without raw exception text
+  or unsupported assurances. Keep entered data and associate errors with controls.
+- Success names an operation that actually completed. Avoid celebratory filler
+  and repeated announcements for routine edits. The feedback workflow owns timing.
+- Empty results and a first-use empty collection are different states. Use the
+  shortest useful explanation and next action for the actual case.
+- A sample-data label is justified when it prevents a real misunderstanding.
+  Put it where that distinction matters. Do not repeat demo disclaimers throughout
+  a test interface whose context is already established.
+
+For list/detail metadata, apply the [records workflow](../flood-records/SKILL.md).
+Use its decision examples to distinguish useful priority/recency from redundant
+labels and counts; the right amount of information depends on the user task.
+
+## Adapt reference content by purpose
+
+For each reference pattern, identify the question it answers and the capability
+that makes its wording true. Transfer that relationship to the host's actual
+objects, actions and states. Do not transplant a competitor's role names, approval
+stages, promises, regulatory language or marketing line into a different product.
+If the host has no equivalent capability, omit that element rather than invent one.
+
+Borrowing a two-pane editor does not imply borrowing an OCR claim or a payment
+workflow. Product references inform structure; user records and confirmed product
+facts supply content. Keep unavailable capabilities explicit in guidance, not as
+decorative warnings on every screen.
+
+## Review the composed surface
+
+Default optional subtitles and descriptions to absent. A page title plus its
+primary action normally needs no sentence narrating that action. An empty-state
+title identifies the missing content; it is not a slogan. Add explanation only
+when it changes the user's next decision or supplies a needed constraint.
+
+After rendering, identify each supporting sentence's new information. If it only
+restates the title, predicts obvious typing/calculation, or repeats another help
+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.
+
+For a writing pass, report the consequential keep/rewrite/move/remove decisions
+outside the product UI, and exercise the affected action or error. Automated
+phrase scans cannot establish editorial quality. Use [decision examples](../interface-content-examples.md)
+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.

package/references/flood-navigation/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: flood-navigation
+description: Choose and verify Flood links, tabs, disclosure and hierarchical navigation. Use when destination, selection and expansion semantics can be confused.
+---
+
+# Separate destination, selection and disclosure
+
+Use installed declarations and the [composition reference](../composition.md).
+Choose Link/NavigationList/NavigationTree for destinations; Tree for application
+object selection; Tabs for associated panels; Accordion/Collapsible for disclosure.
+SegmentedControl selects one value and is not a tab panel controller. Do not use
+Menu just because links appear vertically.
+
+## Preserve browser and keyboard behavior
+
+- Links retain real href, modifier/open-in-new-tab behavior and current-page
+  indication. A route change and a selection change are not interchangeable.
+- Hierarchical items need stable unique values and readable labels. Expansion,
+  current destination, selection and keyboard focus have separate owners. Do not
+  infer cascading selection, automatic fetching or ancestor expansion.
+- Apply each component's keyboard contract. ButtonGroup keeps ordinary Tab
+  navigation; Toolbar, Tabs and selection widgets have their own focus models.
+  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.
+
+## Evidence
+
+Exercise forward/back navigation, current state, disabled/empty items, long labels,
+both orientations when supported and keyboard entry/exit. For breadcrumbs, check
+intrinsic text width and wrapping in each supported browser: a final letter on a
+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.

package/references/flood-overlays/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: flood-overlays
+description: Compose or review Flood dialogs, drawers, popovers, menus and anchored selection surfaces. Use for popup geometry, nested dismissal or focus ownership.
+---
+
+# Give each layer an owner
+
+Use the actual installed overlay and trigger contract; see
+[accessibility](../accessibility.md) for native/dialog/menu behavior. Tooltip is
+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.
+
+## Preserve trigger and state
+
+Forward trigger props/ref onto one mounted native action. Preserve its accessible
+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.
+
+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.
+
+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.
+
+## Inspect the actual host
+
+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.
+DatePicker calendar panels have a 20rem preferred minimum, bounded by available
+viewport width; narrow anchors need not force cramped calendar content. Selection
+lists and time lists retain their separate contracts.
+Verify nested radii/insets, surface distinction over a parent Surface and that
+essential content stays outside scrollbar rails. No clipping or noisy duplicate
+contours should be concealed with extra wrappers.
+
+Drawers must reach the selected viewport edge even with a page scrollbar gutter.
+For a shared Drawer correction check all supported sides; in a host composition
+check the sides that host actually uses. Check long scrollable content, title/description spacing
+and the close IconButton. Verify scroll locking/restoration and nested focus in
+the real composition. CSS elevation tokens alone do not implement these behaviors.
+
+Inspect the useful reading area, not only whether the panel fits the viewport.
+At enlarged text, inherited padding and a long fixed header/footer can consume
+the body. Keep enough width for readable text and enough height to review it;
+allow a reachable whole-panel scroll fallback when fixed chrome cannot fit.
+Do not shorten every host title or reduce the user's font size to conceal a
+shared Drawer sizing problem.