@flood-md/agent 0.2.6 → 0.2.9

package/DESIGN.md

@@ -1,17 +1,46 @@
-# Flood design system · 0.2.6
+# Flood design system · 0.2.9
+
+ListBox owns native required validation for accepted selection. Use its
+description/message/status props rather than duplicating feedback markup. Visual
+invalid/status flags alone do not block submission; validationMessage supplies a
+host-owned blocking constraint. Readonly retains values and bypasses validity;
+disabled excludes submission. TimePicker keeps its plain manual-selection list.
+
+Use TimePicker for civil time suggestions and DateTimeRangePicker for complete,
+ordered civil endpoints. Calendar switches day/month/year views in place. Resolve
+timezones and DST in the host. These are source APIs; check the installed version.
+
+## Composition is built from library primitives
+
+Use existing Flood components inside larger components, the website and playgrounds.
+Do not replace them with ordinary text or custom markup to fix a visual issue.
+When a small capability is missing, improve or create that reusable primitive
+first, then compose it. Preserve component anatomy and semantics. The manifest
+ships the composition skill from `references/flood-composition/SKILL.md` to
+project-root `.agents/skills/flood-ui/references/flood-composition/SKILL.md`.
+Apply that skill. Native semantic markup and neutral structural wrappers remain
+valid inside their proper owners.
+
+
+Readonly date/time entry bypasses native validity constraints while retaining
+accepted canonical values, including values outside current bounds, time steps or
+range availability. Do not silently clear those values. Partial, reversed ranges
+and refused controlled drafts never become accepted by setting readonly. Disabled
+values remain excluded from submission.
 
 Read project-root flood.json and installed declarations with this contract.
-The source bundle's SKILL.md routes to focused composition, accessibility,
-customization and verification references. Its routing matrix names prerequisites
-and sources of truth; flood/rules.json indexes observable checks. Read only the
-relevant reference. This expanded bundle belongs to 0.2.6; existing installations
-keep their matching guide set.
+The installed entry is .agents/skills/flood-ui/SKILL.md; its references live under
+.agents/skills/flood-ui/references/. Read only the relevant composition, spacing,
+accessibility, customization or verification reference. flood/manifest.json maps
+package sources to those installed paths; flood/rules.json indexes observable
+checks. In the Flood repository the corresponding sources are packages/agent/.
+This bundle belongs to 0.2.7; older installations keep their matching guide set.
 
 React + TypeScript and Next.js App Router. Use this guide with matching installed
 Flood packages and flood.json. The source repository's release status does not
 grant permission to publish or assume a version is available on npm.
 
-This guide covers the supported exports in 0.2.6 and their layout refinements. Confirm
+This guide covers the supported exports in 0.2.7 and their layout refinements. Confirm
 the matching installed declarations before using APIs absent from older versions.
 
 ## Connect
@@ -30,6 +59,9 @@ child. Keep server data fetching in server components.
   does not associate a form control; use Field.
 - Reserve display for a marketing headline; preserve normal page/section sizes
   inside product UI. Hosts own responsive composition.
+- Use Tree for application-object selection and NavigationTree for nested URLs.
+  Their expansion and selection/current-location contracts are separate. Do not
+  turn ordinary website navigation into an ARIA tree or treat Tree as a form field.
 - Use CodeSnippet with a code string and optional action slot for commands or
   short examples. The host owns clipboard permission, feedback and errors;
   selectable wrapped code remains available when copying fails.
@@ -160,7 +192,10 @@ export function Profile() {
 ```
 
 
-0.2.5 adds Badge, Spinner, Skeleton and Avatar. Read references/composition.md and references/accessibility.md for status announcements, fallback geometry and decorative naming. Button loading reuses Spinner. These APIs are not present in 0.2.3.
+0.2.5 adds Badge, Spinner, Skeleton and Avatar. Read the installed composition and
+accessibility references under .agents/skills/flood-ui/references/ for status
+announcements, fallback geometry and decorative naming. Button loading reuses
+Spinner. These APIs are not present in 0.2.3.
 
 Progress, Meter and Alert are also available in 0.2.5. Distinguish task completion from bounded measurements, preserve names/units, and select alert announcement priority explicitly.
 
@@ -271,3 +306,137 @@ original OFL notices. Color alone never communicates validation or progress.
 CodeSnippet codeDirection defaults to ltr independently of RTL parent action layout; choose rtl/auto explicitly for content that needs it. Native dir still applies to the wrapper. Protected ScrollArea reveals focused descendants fully when needed, composes the host focus handler and avoids scrolling to nested top-layer controls.
 
 Checkbox, Radio and Switch apply native hidden/dir/lang to their visible label wrapper as well as the input, so a component-local language/direction applies to its whole choice.
+
+## Base capabilities · 0.2.7
+
+The added exports are Editable, TagInput, CommandList, DateField, TimeField,
+Calendar, DatePicker, RangeCalendar, DateRangeField, DateRangePicker,
+ResizablePanels, ErrorSummary, ContextMenu, Tree and NavigationTree. Menu preference
+items and submenus extend Menu; a command palette is Dialog + CommandList
+composition, not a separate export. Use the matching installed declarations.
+
+### Editing and commands
+
+Editable separates draft and committed value. Enter commits, Escape cancels and
+blurAction selects commit/cancel/none. Controlled value/editing require host
+acceptance; only committed text submits. TagInput accepts free-form tokens while
+MultiSelect selects known option IDs. Only committed tags submit repeated named
+entries. Preserve IME, reset cancellation, required and readonly/disabled behavior.
+
+CommandList filters and invokes commands without a submitted selection or modal
+lifecycle. The host owns effects, routing, shortcuts and closure. Compose Dialog
+around it for a command palette; preserve input naming, active-option semantics,
+disabled/loading states and existing Escape ownership.
+
+Menu preferences expose controlled aria-checked states and labelled radio groups;
+the host owns exclusivity. Preference activation stays open unless closeOnSelect
+requests dismissal; commands dismiss and call onAction. Nested submenus and
+ContextMenu reuse this action engine. ContextMenu opens from pointer context or
+ContextMenu/Shift+F10; provide a visible Menu alternative for touch. None is a
+native form-selection control or a data-fetching service.
+
+### Civil dates, time and ranges
+
+DateField owns canonical Gregorian YYYY-MM-DD dates, not timestamps or time zones.
+Keep labelled text segments, explicit order and native required/bounds validity.
+Invalid drafts cannot submit an old canonical date. validationMessage adds a host
+native constraint without overriding own calendar errors. TimeField uses 24-hour
+HH:mm or HH:mm:ss precision and seconds-based steps; do not invent AM/PM,
+overnight bounds, zone conversion or combined date-time semantics.
+
+Calendar owns a single-date grid. DatePicker composes DateField, Calendar and
+Popover, keeping native forms, controlled state and focus ownership intact.
+onDateSelect confirms allowed activation even when the value is unchanged.
+Translate calendar labels, segment names and validation messages. Calendar Intl
+formatting is explicitly Gregorian UTC, weekStartsOn remains explicit and today
+can provide deterministic rendering.
+
+RangeCalendar selects one inclusive interval start then end; hover/focus previews
+are uncommitted. DateRangeField owns paired text entry and atomic startName/endName
+bridges; DateRangePicker composes the pair with one popup. Values are {start,end}
+with empty strings for empty/partial endpoints. Controlled hosts must accept
+partial starts to advance calendar selection. Calendar gestures normalize earlier
+endpoints; typed reversed drafts stay editable and invalid. Partial, reversed,
+unavailable or refused pairs never submit one new endpoint beside an old one.
+isDateDisabled blocks endpoints; interior blocked dates are allowed unless
+isRangeDisabled rejects the interval. Apply the same predicates to typed entry.
+Escape/outside dismissal may leave an accepted partial range; do not manufacture
+completion to make the form valid. Preserve reset cancellation and return focus.
+
+### Hierarchy, layout and error ownership
+
+Tree selects application objects through independent value and expandedValues
+contracts. Keep globally unique item values and noninteractive icons/descriptions.
+Descriptions participate in each row's accessible name; descendant labels do not.
+Arrows/Home/End/typeahead move focus independently from selection. Collapsing
+retains known selected descendants; removed/nonselectable values are excluded
+from later selection requests. Deferred hasChildren/loading branches belong to
+the host; no fetching or virtualization is implied.
+
+Tree readonly prevents selection while retaining browse/expand behavior. Translate
+readOnlyMessage for the associated explanation; tree/treeitem do not support
+aria-readonly. Disabled rows remain discoverable but cannot select/expand; item
+restrictions do not implicitly cascade. Tree submits no form values and does not
+automatically inherit a native fieldset's disabled state.
+
+NavigationTree uses native nav/list/links and normal Tab order. A destination and
+its disclosure are separate controls, so expansion does not navigate. The host
+owns currentValue, hrefs and expanded ancestors. Preserve linkProps, modifier
+navigation, localized disclosure labels and distinct disabled states.
+
+ResizablePanels owns constrained pointer/keyboard geometry and separator keys;
+its value is the main pane's percentage after the separator. The host supplies
+vertical height, content scrolling and persistence. Preserve RTL, cancellation,
+focus transfer and inert zero-sized panes. Use static Split when resizing is not
+needed. ErrorSummary receives host errors with exact field IDs. It links/focuses
+those controls without validating, expanding sections or submitting. Opt into
+autofocus/announcement deliberately for the host's submission lifecycle.
+
+Required, status, loading, empty and readonly contracts are component-specific.
+Preserve native validity and cancelled resets where supported; do not infer a
+form contract from Tree/Menu/CommandList selection or active state. Package source
+availability and focused examples do not prove registry publication, deployment
+or accessibility of the host application.
+
+## Extended controls in 0.2.8
+
+HoverCard opens a named interactive preview on hover or focus and supports explicit
+activation. Use Tooltip for short noninteractive descriptions. ColorSwatch and
+ColorPicker use opaque RGB hex colors; they do not imply alpha, gradients or a
+contrast guarantee. TreeSelect provides single hierarchical selection; Tree
+remains the standalone single/multiple control. DateTimePicker composes civil
+date and clock time with separate form values and no inferred timezone. Use
+application validation for relationships between the parts. Recipes for Select
+all, split actions and form submission live in the public user documentation.
+
+DataList/DataListItem are native list content, not selection widgets. Keep links
+in the title and actions separate; do not turn the whole row into a button.
+CheckCard/RadioCard compose the native choice primitives into clickable labels.
+Keep their description, icon and metadata noninteractive. Use one radio name and
+an enclosing Fieldset for exclusive choices; derive aggregate checkbox state
+in the host. Read-only choice cards preserve submission and block editing; apply
+readOnly to an entire radio group consistently.
+
+DataTable pages and sorts one complete client-side collection. It is not a
+server query engine or a virtualized grid. Rich cells require explicit sortValues
+when they are sortable. Select all affects the current page only and preserves
+other pages; permission-restricted rows use selectionDisabled. Native links and
+actions in cells remain independent. Compose search and filters at the host
+boundary, reset page deliberately and specify the intended selection lifetime.
+Use Table + Pagination for remote pagination rather than passing one remote page
+into the client-paginated DataTable.
+
+FileItem/FileList display host-owned attachment metadata; UploadItem/UploadList
+display explicit queued/uploading/success/error/cancelled states. Cancel and retry
+callbacks are intents, not an upload engine. Do not show success merely because
+bytes reach100%; wait for the host confirmation. Use stable IDs, not filenames,
+for identity. FileInput retains native form ownership; removing a display row
+does not alter its FileList. ImagePreview reuses Dialog; the host owns trusted
+URLs, blob URL lifetime, download permissions and image alt text. No built-in
+network, file reading or object URL creation is implied by these components.
+
+FileMeta combines a display format label and byte size in one quiet chip. FileItem
+and UploadItem place it with the filename, reserving the next line for status or
+supporting text. Filename extensions are display hints only, never validation.
+Override with format or hide the format using format=null; do not infer upload
+safety or MIME permissions from a visible chip.

package/README.md

@@ -1,22 +1,31 @@
 # @flood-md/agent
 
 Version-matched guidance for Flood React/Next.js projects. Read the installed
-contract before composing screens. The 0.2.6 reference bundle includes spacing
+contract before composing screens. The 0.2.9 reference bundle includes spacing
 guidance, routing and observable rules. These files grant
 no authority to modify external services.
 
+The source bundle also includes ten routed workflows for the existing dark base:
+composition, spacing, foundations, accessibility, forms, overlays, navigation,
+data display, feedback and verification. The lightweight flood-ui entry selects
+relevant skills; nested folders do not imply independent automatic discovery.
+workflows.json describes applicability. rules.json describes observable checks;
+neither is a completed component-audit report or executable enforcement engine.
+
 | Source | Role |
 | --- | --- |
 | DESIGN.md | Shared versioned UI/component contract |
 | SKILL.md | Short entry and task router |
 | references/routing.md | Applicability, audience, prerequisites and governing source |
 | references/composition.md | Screen/form composition workflow |
+| references/flood-composition/SKILL.md | Full primitives-first composition skill routed from flood-ui |
 | references/spacing.md | Measured spacing, density, nested geometry and hit areas |
 | references/accessibility.md | Interaction and perception checks |
 | references/customization.md | Scoped semantic customization |
 | references/verification.md | Evidence before reporting completion |
 | rules.json | Stable rule IDs with conditions, sources and observable checks |
 | manifest.json | Source → installed-path mapping used by the CLI |
+| workflows.json | Component-family applicability and routed full-skill sources |
 
 CLI init copies every manifest entry into an unused owned path. Doctor checks
 expected regular files without linked destinations. Neither tool rewrites host

package/SKILL.md

@@ -19,11 +19,18 @@ invented as a package API. No external component library or parallel token syste
 
 | Work | Read next | Required result |
 | --- | --- | --- |
+| Component, composite, website or playground UI | [Composition skill](references/flood-composition/SKILL.md) | Reused primitives; missing small capabilities implemented before composites |
 | New screen, layout or form | [Composition](references/composition.md) | Existing primitives, correct host width and form ownership |
-| Spacing, density, nested geometry or shifting previews | [Spacing](references/spacing.md) | Measured visual relationships and nonoverlapping interactive areas |
-| Keyboard, validation, names or states | [Accessibility](references/accessibility.md) | Real interaction and associations preserved |
-| Brand, colors or typography | [Customization](references/customization.md) | Scoped semantic overrides; unchanged behavior |
-| Completion, regression or upgrade review | [Verification](references/verification.md) | Checks and limits reported against the actual host |
+| Spacing, density, nested geometry or shifting previews | [Spacing skill](references/flood-spacing/SKILL.md) | Measured visual relationships and nonoverlapping interactive areas |
+| Existing dark surfaces, type, control and icon sizing | [Foundations skill](references/flood-foundations/SKILL.md) | Correct semantic roles and coherent consumers |
+| Keyboard, names, focus, perception or reflow | [Accessibility skill](references/flood-accessibility/SKILL.md) | Real interaction and associations preserved |
+| Field ownership, validation, submission and reset | [Forms skill](references/flood-forms/SKILL.md) | Actual form values and accepted/refused transitions |
+| Popup, dialog, drawer or nested layer | [Overlays skill](references/flood-overlays/SKILL.md) | Appropriate geometry, dismissal and focus ownership |
+| Destinations, panels, disclosure or hierarchy | [Navigation skill](references/flood-navigation/SKILL.md) | Navigation, selection and expansion kept distinct |
+| Tables, lists, cards, files and long content | [Data display skill](references/flood-data-display/SKILL.md) | Meaningful structures and reachable overflow |
+| Status, progress, alerts, loading or empty content | [Feedback skill](references/flood-feedback/SKILL.md) | Honest operation state with one announcement owner |
+| Brand or deliberate semantic overrides | [Customization](references/customization.md) | Scoped semantic overrides; unchanged behavior |
+| Completion, stabilization or regression review | [Verification skill](references/flood-verification/SKILL.md) | Checks and limits reported against the actual host |
 | Decide which document governs a change | [Routing and sources](references/routing.md) | Source of truth and prerequisites identified |
 
 The project-root flood/rules.json lists stable rule IDs and their observable
@@ -31,5 +38,10 @@ checks; it is an index, not executable policy. At completion report which checks
 ran, their result and any unverified behavior. Doctor checks installation only.
 Guidance cannot guarantee an agent's compliance or certify application accessibility.
 
+The workflow index lists component-family applicability, not a requirement to load
+every skill or proof that a component passed its checks. These specialized skills
+are routed references inside flood-ui; independent discovery of nested folders
+is not assumed. Resolve sources through the installed manifest when needed.
+
 Preserve existing instructions and customized guides. This skill authorizes no
 deployment, deletion, external messages or sending host source to other services.

package/manifest.json

@@ -51,9 +51,64 @@
       "source": "references/spacing.md",
       "target": ".agents/skills/flood-ui/references/spacing.md",
       "kind": "reference"
+    },
+    {
+      "source": "references/flood-composition/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-composition/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "workflows.json",
+      "target": ".agents/skills/flood-ui/workflows.json",
+      "kind": "reference"
+    },
+    {
+      "source": "references/flood-spacing/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-spacing/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-foundations/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-foundations/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-accessibility/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-accessibility/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-forms/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-forms/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-overlays/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-overlays/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-navigation/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-navigation/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-data-display/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-data-display/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-feedback/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-feedback/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/flood-verification/SKILL.md",
+      "target": ".agents/skills/flood-ui/references/flood-verification/SKILL.md",
+      "kind": "skill"
     }
   ],
-  "version": "0.2.6",
+  "version": "0.2.9",
   "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.6",
+  "version": "0.2.9",
   "type": "module",
   "description": "Versioned Flood design instructions for coding agents.",
   "license": "MIT",
@@ -13,6 +13,7 @@
     "DESIGN.md",
     "SKILL.md",
     "references",
+    "workflows.json",
     "rules.json",
     "manifest.json",
     "README.md"
@@ -22,6 +23,7 @@
     "./SKILL.md": "./SKILL.md",
     "./manifest.json": "./manifest.json",
     "./rules.json": "./rules.json",
+    "./workflows.json": "./workflows.json",
     "./references/*": "./references/*"
   },
   "publishConfig": {

package/references/composition.md

@@ -1,5 +1,15 @@
 # Compose an interface
 
+Apply the [Flood composition skill](flood-composition/SKILL.md) before building
+or changing UI. Reuse the existing semantic primitive, including inside library
+components. Fix its layout or extend its API instead of substituting custom markup.
+
+Use Tree for hierarchical application selection, with explicit value and expansion
+ownership. Use NavigationTree for nested destinations: preserve native links and
+their browser behavior rather than forcing a website sidebar into tree/menu roles.
+Do not infer cascading selection, lazy fetching, form submission or expansion of
+current-page ancestors. Keep item values globally unique and text labels present.
+
 For spacing, density or nested-geometry decisions, read [Spacing](spacing.md).
 Measure the complete row geometry before adding a gap to repeated controls.
 
@@ -267,3 +277,5 @@ host-owned. No third-party component implementation was introduced.
 Section headingLevel controls native h2–h6 semantics. Its independent headingSize
 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.

package/references/flood-accessibility/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: flood-accessibility
+description: Review Flood interface names, keyboard flow, focus, perception and reflow in the actual host. Use for interaction or accessibility acceptance.
+---
+
+# Review an actual task
+
+Use [accessibility](../accessibility.md) and the installed component's contract.
+A scanner result is supporting evidence, not certification of an application.
+
+## Trace the task from entry to completion
+
+- Identify the name, role, state and instruction for each actionable control.
+  Retain native semantics before adding ARIA. A placeholder, color or tooltip
+  alone is not an adequate field name or required instruction.
+- If a visible label is intentionally hidden, preserve the supplied label/legend
+  through the supported API and verify its contextual meaning and focus reveal.
+  Do not remove the label or invent unsupported hideLabel props on bare controls.
+- Complete the task with keyboard only, including reverse navigation, cancel,
+  invalid submission and recovery. Distinguish roving focus, selection and
+  activation; arrow behavior follows the specific component contract.
+- After pointer activation of a custom keyboard-owning control, inspect actual
+  focus before testing keys. Some browsers do not mouse-focus native buttons;
+  a custom combobox cannot rely on that default. Preserve an intentional focus
+  move made by the host callback rather than forcing focus back afterward.
+- Check the accent focus perimeter in combinations with invalid, selected and
+  read-only states. It must remain visible without changing layout or hiding
+  beneath a rail, sticky region or overlay. Closing an overlay returns focus
+  appropriately without overriding a deliberate host focus move.
+- Evaluate text with its actual size, weight and composited background using
+  applicable WCAG checks and supplementary APCA guidance. Decorative lines are
+  different from necessary control/state indicators; do not relabel a necessary
+  cue as decoration to avoid checking it. APCA is not WCAG conformance.
+- Exercise narrow width, root text enlargement, long content, RTL where supported,
+  forced colors and the existing reduced-motion fallback. These checks do not
+  introduce new animation or theme requirements.
+
+For assistive-technology announcements, inspect live-region semantics and test
+with the actual technology when available. Do not report audible announcements
+from a DOM role alone. Record any device/technology that was not tested.

package/references/flood-composition/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: flood-composition
+description: Build or review Flood UI from existing library primitives before adding composites. Use for component, website, playground and host-interface work, especially when a layout fix risks replacing a reusable element with custom markup.
+---
+
+# Compose Flood from its primitives
+
+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
+component guide first. This skill grants no additional permissions.
+
+## Choose the smallest existing owner
+
+Before changing JSX, identify the visible roles and their existing owners:
+StatusIndicator for a named state, Progress for progress, Badge/FileMeta for
+metadata, IconButton for an icon action, Dialog for modal behavior, Text/Heading
+for typography, and the appropriate form, list or table primitive for semantics.
+Check the actual installed exports and props; do not invent APIs from newer docs.
+
+- Reuse the matching component with its supported props and tokens.
+- If spacing or alignment is wrong, inspect both the primitive and the parent
+  composition. Fix the owner of the relationship. Keep the primitive intact.
+- If a primitive lacks a real reusable capability, improve that primitive first,
+  with an intentional API/variant and the matching docs and checks, then compose it.
+- If no primitive exists, build the small reusable component before the larger
+  composition. Define its semantics, anatomy, states and size before exposing it.
+
+In the Flood library, add public primitives through the source API, catalog,
+declarations, guidance and current version decision. In a consuming application,
+do not pretend that an uninstalled export exists: use the supported primitives or
+an explicitly project-owned adapter, and identify any upstream gap.
+
+## Do not bypass a component to fix its appearance
+
+Do not replace StatusIndicator with a styled span, Badge with a handmade chip,
+Progress with a local track, or Dialog with a parallel modal merely to make one
+example fit. Do not hide a component's glyph, label, focus state or other anatomy
+through descendant CSS and reproduce it beside the component. Intentional variants
+belong in the primitive's API, not in a consumer-specific imitation.
+
+For example, an upload row keeps StatusIndicator and Progress as separate reused
+components. Its parent aligns their centers and controls the gap; it does not
+remove the status dot or replace the status with ordinary text. Fix internal dot
+alignment in StatusIndicator only if the primitive itself is wrong.
+
+Native semantic markup is necessary inside primitive implementations. Content
+strings and neutral structural wrappers are also valid in compositions. They must
+not introduce a competing visual or behavioral component. A wrapper that starts
+owning a reusable role should become a named small component instead.
+
+## Review the composed result
+
+Check the reused component and its neighboring elements in the real host: wide
+and narrow layout, enlarged text, long labels, optional content and relevant
+interaction states. Measure the visible glyph/text/control centers when alignment
+is the issue. Keep focus, accessible names, callbacks and native form semantics.
+
+If changing a shared primitive, check another consumer of it. Report which
+components were reused, which primitive changed or was added, and what remains
+unverified. A new wrapper name alone is not evidence of reuse. Use the project's
+verification scope; this guidance does not require a full release run for every
+local design adjustment.

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

@@ -0,0 +1,37 @@
+---
+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.
+
+- 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.
+
+## 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.
+
+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,37 @@
+---
+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.
+
+## 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 needs a reason and an appropriate next action when available. Its
+  icon/illustration and action remain existing primitives with consistent geometry.
+
+## Evidence
+
+Trigger the operation and observe each applicable transition, including failure
+and retry. 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,45 @@
+---
+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.
+
+## 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.
+
+## 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. In a local example,
+state explicitly that changes are local.

package/references/flood-foundations/SKILL.md

@@ -0,0 +1,37 @@
+---
+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.
+
+## 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-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,45 @@
+---
+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.
+
+## 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.
+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.

package/references/flood-spacing/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: flood-spacing
+description: Diagnose Flood spacing, density, nested radii and alignment from rendered geometry. Use for large gaps, crowded rows or shifting compositions.
+---
+
+# Measure the relationship
+
+Read the [spacing reference](../spacing.md), installed component anatomy and
+host content requirements. Existing user-approved geometry governs the task.
+
+Identify what a gap separates: indicator/text, title/description, related choices,
+independent actions, sections, or nested surfaces. Do not propagate one gap to
+every wrapper. Stack and Inline organize relationships; component padding and
+line height still contribute to the visible distance.
+
+## Find the owner
+
+Inspect bounding rectangles plus computed padding, margin, gap, minimum height
+and line height. For centered repeated rows, visible glyph separation includes
+row height minus glyph height plus the row gap. A zero gap can still be spacious.
+
+Remove redundant space at the layer that creates it. Preserve the choice glyph
+and label pair, explicit icon dimensions and nonoverlapping click targets. Avoid
+negative margins or transforms that merely hide a bad parent relationship.
+
+For a nested surface, compare its radius with the outer radius minus the actual
+inset/stroke. Do not force unrelated actions to follow that formula. Compare
+top/bottom and start/end insets around a nested InputGroup action optically.
+
+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.
+
+## Evidence
+
+Check short/wrapping labels, optional descriptions/messages/actions, all relevant
+sizes, narrow width, enlarged text and both pointer modes. Rows can grow for
+content; compact spacing must not clip text or overlap touch targets. Check a
+sibling using the same recipe after a shared correction. Report actual measures
+and rendered evidence, not only the declaration that was changed.
+
+No horizontal overflow does not prove a readable layout. Inspect the actual
+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.

package/references/flood-verification/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: flood-verification
+description: Verify Flood component or composed-interface changes against applicable contracts and actual evidence. Use for stabilization, regression or completion review.
+---
+
+# Turn a rule into an observation
+
+Read [verification](../verification.md), the host's scripts and the changed
+component's contract. Use project-root flood/rules.json to identify applicable
+rule IDs; it is an index of guidance, not an automatic pass/fail policy engine.
+
+## Bound the coverage
+
+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
+from checks actually run for this source revision.
+
+Check the public contract at the boundary: installed exports/types, actual form
+values, controlled acceptance/refusal, reset, names/focus and semantic state. For
+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.
+
+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.
+
+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
+host's equivalent gates in a consuming app. Do not continually repeat a full
+release gate for every reversible visual adjustment.
+
+## Report a usable result
+
+For a failure preserve the source revision, affected state and actual trace or
+measurement; distinguish library, host recipe, assertion and infrastructure causes.
+Correct the responsible owner without weakening a meaningful assertion to get
+green. Add regression coverage for demonstrated risks rather than mirroring CSS.
+
+State what ran, results, manual observations and remaining limits. A source scan,
+agent instruction, screenshot or accessibility scanner cannot independently prove
+all behavior or certify conformance. A local build does not prove registry
+publication, website deployment or a host backend save. Keep installation upgrades
+deliberate and preserve customized/linked destination protections.

package/references/routing.md

@@ -6,6 +6,7 @@ override user authority or grant permission for unrelated operations.
 
 | Question / when | Audience | Prerequisite | Source of truth | Verify with |
 | --- | --- | --- | --- | --- |
+| Which primitive owns this role? Component/composite UI work | Developer / agent / reviewer | Matching catalog and component anatomy | flood-composition/SKILL.md | Reuse existing primitives; extend small capabilities first |
 | Which API can I import? Every component edit | Developer / agent | Installed exact versions | Installed @flood-md/react declarations; flood.json | Type-check host imports; CLI doctor for alignment |
 | What does this release mean? Setup / upgrade | Developer / agent | Matching guide | flood/DESIGN.md, package changelog | Compare version and declarations; preserve host edits |
 | How should a screen fit together? Screen / form work | Designer / developer / agent | Scope, content and current API | composition.md; host layout requirements | Narrow/wide rendered screen and native form interaction |

package/rules.json

@@ -181,6 +181,330 @@
         "Check fine/coarse pointers and nonoverlapping interactive targets",
         "Preserve keyboard focus and label activation"
       ]
+    },
+    {
+      "id": "composition.reuse",
+      "when": "Building or reviewing Flood components, composites, website or host UI",
+      "for": [
+        "designer",
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed exports and component contracts",
+        "Existing component anatomy and current composition"
+      ],
+      "sourceOfTruth": "DESIGN.md and the Flood composition skill",
+      "guide": "references/flood-composition/SKILL.md",
+      "verify": [
+        "Existing semantic primitives remain present in the rendered composition",
+        "Missing reusable capabilities are implemented in a small primitive before the larger composite",
+        "No replacement markup or hidden anatomy used to bypass a primitive",
+        "Alignment checked within each row and in the real host"
+      ]
+    },
+    {
+      "id": "foundations.roles",
+      "when": "Applying dark surfaces, type, control or icon roles",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Installed semantic roles and actual composited backgrounds",
+      "guide": "references/flood-foundations/SKILL.md",
+      "verify": [
+        "Trace changed roles to their actual consumers",
+        "Distinguish decoration, necessary boundaries, selection and accent focus",
+        "Check explicit icon sizing, heading semantics, long text and enlarged root geometry"
+      ]
+    },
+    {
+      "id": "spacing.nesting",
+      "when": "Aligning nested surfaces or controls",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Rendered anatomy, insets, radii and spacing roles",
+      "guide": "references/flood-spacing/SKILL.md",
+      "verify": [
+        "Measure both axes including line height and minimum height",
+        "Compare nested radius/inset geometry without overriding independent actions",
+        "Check shared siblings and nonoverlapping targets"
+      ]
+    },
+    {
+      "id": "spacing.preview",
+      "when": "Demonstrating size or feedback transitions",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Component behavior distinguished from preview scene ownership",
+      "guide": "references/flood-spacing/SKILL.md",
+      "verify": [
+        "Changing size does not resize the preview scene",
+        "Feedback does not move an unrelated sample",
+        "Production controls do not inherit unnecessary fixed demo space"
+      ]
+    },
+    {
+      "id": "forms.ownership",
+      "when": "Connecting controlled values or native form data",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Installed control values, callbacks and native form contract",
+      "guide": "references/flood-forms/SKILL.md",
+      "verify": [
+        "Inspect actual FormData and field ownership",
+        "Exercise accepted/refused controlled updates and incomplete drafts",
+        "Defaults match representation; no defaultValue-as-update or invented save guarantee"
+      ]
+    },
+    {
+      "id": "forms.reset",
+      "when": "Resetting a form or changing value representation",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Installed controlled/uncontrolled, reset and precision contract",
+      "guide": "references/flood-forms/SKILL.md",
+      "verify": [
+        "Normal and prevented reset preserve documented ownership",
+        "Minute/second defaults match selected precision",
+        "Advisory messages remain valid; native errors and disabled/read-only retain distinct semantics"
+      ]
+    },
+    {
+      "id": "overlays.ownership",
+      "when": "Opening or nesting a modal or anchored layer",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Installed trigger, open-state, focus and dismissal contract",
+      "guide": "references/flood-overlays/SKILL.md",
+      "verify": [
+        "One mounted trigger retains props/ref and name",
+        "Topmost Escape and host refusal behave correctly",
+        "Appropriate modal/nonmodal focus and scroll restoration"
+      ]
+    },
+    {
+      "id": "overlays.geometry",
+      "when": "Placing popups or viewport-edge drawers",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Actual anchor, viewport, scroll container and semantic surface",
+      "guide": "references/flood-overlays/SKILL.md",
+      "verify": [
+        "Check used sides, viewport edges, resize, long content and RTL",
+        "No drawer gap caused by page scrollbar gutter",
+        "Header, footer and padding leave a useful body reading area at enlarged narrow sizes; fitting rectangles alone is insufficient",
+        "Popup remains distinguishable with no rail-covered or clipped essential content"
+      ]
+    },
+    {
+      "id": "navigation.intent",
+      "when": "Choosing destinations, selection, panels or disclosure",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Installed navigation, selection and disclosure contract",
+      "guide": "references/flood-navigation/SKILL.md",
+      "verify": [
+        "Native link behavior and current destination preserved",
+        "Selection, focus and expansion remain distinct",
+        "Long labels and final sidebar items remain usable in actual supported orientations"
+      ]
+    },
+    {
+      "id": "data.structure",
+      "when": "Presenting records, file items or tables",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Installed semantic primitives and content relationships",
+      "guide": "references/flood-data-display/SKILL.md",
+      "verify": [
+        "Caption, headers and named-value relationships preserved",
+        "Row actions remain independent named controls",
+        "File metadata/status/progress reuse their existing primitives"
+      ]
+    },
+    {
+      "id": "data.overflow",
+      "when": "Presenting long, missing or changing content",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Actual data surface and overflow ownership",
+      "guide": "references/flood-data-display/SKILL.md",
+      "verify": [
+        "Empty/loading/error and absent optional slots exercised",
+        "Final item/cell action and full essential text remain accessible outside rails",
+        "Server/client locale, narrow/enlarged text and RTL checked"
+      ]
+    },
+    {
+      "id": "feedback.truth",
+      "when": "Reporting operation state or progress",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Actual host operation and installed feedback primitive",
+      "guide": "references/flood-feedback/SKILL.md",
+      "verify": [
+        "Pending/success/error/cancel/local state is truthful",
+        "Unknown progress never fabricates a percentage",
+        "Empty content explains its cause and appropriate next action"
+      ]
+    },
+    {
+      "id": "feedback.announcements",
+      "when": "Announcing status, alert or loading transitions",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Installed semantics and required urgency",
+      "guide": "references/flood-feedback/SKILL.md",
+      "verify": [
+        "One announcement owner rather than duplicate live regions",
+        "Messages do not steal focus merely to announce",
+        "Audible behavior claimed only when tested with actual assistive technology"
+      ]
+    },
+    {
+      "id": "accessibility.focus",
+      "when": "Reviewing names, keyboard or focus through a task",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Installed component behavior and actual accessibility tree",
+      "guide": "references/flood-accessibility/SKILL.md",
+      "verify": [
+        "Name, role and state observed rather than inferred visually",
+        "Keyboard completion, reverse navigation, cancel and recovery",
+        "Pointer activation gives custom keyboard owners actual focus across browsers while preserving deliberate host callback focus moves",
+        "Accent focus survives selected/invalid/read-only combinations without layout shift"
+      ]
+    },
+    {
+      "id": "accessibility.perception",
+      "when": "Reviewing readability under alternate viewing conditions",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Actual text size/weight/background and applicable WCAG criteria",
+      "guide": "references/flood-accessibility/SKILL.md",
+      "verify": [
+        "Text contrast and supplementary APCA interpretation kept distinct",
+        "Necessary cues are not reclassified as decoration",
+        "Reflow, enlargement, relevant pointer/RTL/forced-color checks and limits reported"
+      ]
+    },
+    {
+      "id": "verification.applicability",
+      "when": "Stabilizing components or declaring a composition complete",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Matching installed declarations and guide set",
+        "Runnable host and actual content/state requirements"
+      ],
+      "sourceOfTruth": "Current revision, applicable contracts and observed outcomes",
+      "guide": "references/flood-verification/SKILL.md",
+      "verify": [
+        "Explicit applicable-check disposition for every affected component",
+        "Existing coverage distinguished from checks run for this revision",
+        "Failures, source/host ownership and remaining limits recorded"
+      ]
     }
   ],
   "guideResolution": "Match guide to source in manifest.files; use its target relative to the host project root."

package/workflows.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "scope": "Task routing for the existing Flood dark base; applicability is not test evidence",
+  "workflows": [
+    { "id": "composition", "guide": "references/flood-composition/SKILL.md", "all": true },
+    { "id": "spacing", "guide": "references/flood-spacing/SKILL.md", "all": true },
+    { "id": "foundations", "guide": "references/flood-foundations/SKILL.md", "all": true },
+    { "id": "accessibility", "guide": "references/flood-accessibility/SKILL.md", "all": true },
+    { "id": "forms", "guide": "references/flood-forms/SKILL.md", "groups": ["forms"], "components": ["Button", "Label", "Fieldset", "ErrorSummary"] },
+    { "id": "overlays", "guide": "references/flood-overlays/SKILL.md", "groups": ["overlays"], "components": ["Select", "Combobox", "MultiSelect", "TreeSelect", "DatePicker", "DateRangePicker", "TimePicker", "DateTimePicker", "DateTimeRangePicker"] },
+    { "id": "navigation", "guide": "references/flood-navigation/SKILL.md", "groups": ["navigation"], "components": ["Tree", "TreeSelect", "Toolbar", "CommandList", "ListBox", "ToggleGroup", "SegmentedControl", "Accordion", "Collapsible"] },
+    { "id": "data-display", "guide": "references/flood-data-display/SKILL.md", "groups": ["content"], "components": ["UploadItem", "UploadList", "EmptyState", "ScrollArea"] },
+    { "id": "feedback", "guide": "references/flood-feedback/SKILL.md", "groups": ["feedback"], "components": ["Field", "Fieldset", "Input", "Textarea", "Select", "ListBox", "CopyButton", "Badge", "UploadItem", "UploadList"] },
+    { "id": "verification", "guide": "references/flood-verification/SKILL.md", "all": true }
+  ]
+}