@flood-md/agent 0.2.8 → 0.2.9

package/DESIGN.md

@@ -1,4 +1,4 @@
-# Flood design system · 0.2.8
+# 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

package/README.md

@@ -1,10 +1,17 @@
 # @flood-md/agent
 
 Version-matched guidance for Flood React/Next.js projects. Read the installed
-contract before composing screens. The 0.2.8 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 |
@@ -18,6 +25,7 @@ no authority to modify external services.
 | 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

@@ -21,10 +21,16 @@ invented as a package API. No external component library or parallel token syste
 | --- | --- | --- |
 | 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
@@ -32,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

@@ -56,9 +56,59 @@
       "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.8",
+  "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.8",
+  "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/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-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/rules.json

@@ -203,6 +203,308 @@
         "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 }
+  ]
+}