@flood-md/agent 0.2.8 → 0.2.10

package/dist/materials/guide-installation.md

@@ -0,0 +1,79 @@
+# Installation · 0.2.10
+
+The commands below target version 0.2.10. Verify registry availability before installation; for local source evaluation, see the tarball instructions at the end of this guide.
+
+Use Node.js 22.12 or newer and an existing npm-based React/Next.js project.
+React 18.3/19 is supported; React 19 and Next.js App Router are integration targets.
+
+## Connect once, import by name
+
+The base set ships in one package. Set it up once for your project, then use
+named imports such as `import { Button, Input } from "@flood-md/react"`.
+There is no per-component `add` command or source-copy registry. You do not
+repeat installation when you start using another component.
+
+## Connect with the CLI
+
+```sh
+npx @flood-md/cli@0.2.10 init --dry-run
+npx @flood-md/cli@0.2.10 init
+```
+
+The installer adds exact matching tokens, React and agent packages. It creates
+`flood.json`, `flood/DESIGN.md` and `.agents/skills/flood-ui/SKILL.md`, preserves
+host instructions and refuses existing files or linked destinations. It does
+not modify application source. Import CSS once in the React entry or Next
+`app/layout.tsx`, then wrap new UI in `FloodRoot`:
+
+```tsx
+import "@flood-md/react/styles.css";
+import { Button, FloodRoot } from "@flood-md/react";
+
+export function App() {
+  return <FloodRoot><Button>Start something</Button></FloodRoot>;
+}
+```
+
+Use a client component for callbacks, state or Field's function child. See
+[components](components.md) and the [base inventory](base-components.md).
+No Tailwind configuration or font CDN is needed. The foundations profile is dark
+only; legacy theme behavior remains available outside `FloodRoot`.
+
+```sh
+npx @flood-md/cli@0.2.10 doctor
+```
+
+Doctor checks package versions and guide presence, not stylesheet imports or
+application behavior. If your agent does not discover the installed skill,
+reference `flood/DESIGN.md` from its existing instructions.
+
+## Manual package installation
+
+```sh
+npm install --save-exact @flood-md/tokens@0.2.10 @flood-md/react@0.2.10 @flood-md/agent@0.2.10
+```
+
+Import the stylesheet and use `FloodRoot` as above. Manual installation does not
+create the CLI's project configuration or copied instruction files; read the
+matching agent package's guides directly or use CLI init in an unconfigured
+project. All components ship together and are imported by name.
+
+## Updates from 0.1.1
+
+Upgrade tokens, React and agent together to the same exact version. Existing
+controls outside `FloodRoot` retain their earlier theme behavior. Adopt the new
+dark recipes explicitly by adding `FloodRoot`; move customization to scoped
+`--flood-sys-*` roles instead of assuming old variables change the new profile.
+
+Compare the new package's agent guides with customized local copies before
+updating them. Update `flood.json` after a successful migration and run the
+matching CLI doctor. Do not rerun init to overwrite existing instructions.
+Run the host build/tests and browser checks after upgrading.
+
+## Evaluate repository changes locally
+
+For source development, run `npm ci` and `npm run build:packages`, then
+`npm pack --workspace=@flood-md/tokens` (and likewise React/agent). Install the
+three generated tarballs together using their local paths with
+`npm install --save-exact`. This evaluates local source without implying that a
+future version is already available from the registry.

package/dist/materials/guide-interface-content.md

@@ -0,0 +1,76 @@
+# Interface content
+
+Flood's interface-content workflow covers the information and wording in a UI:
+labels, actions, hierarchy, hints, states and adaptation of reference content.
+It is separate from typography sizing. Use it when introducing visible copy or
+reviewing an existing interface; it does not authorize rewriting user documents.
+
+## Start with the task
+
+Identify the user, their current task and the state they are in. Give each text
+element a purpose: identify, distinguish, guide, explain a relevant consequence,
+report a real state or support recovery. Keep, rewrite, move or remove it based
+on that purpose. A component's optional description prop is not a requirement to
+write a description.
+
+An invoice list can simply be titled “Invoices”. A category label, the same noun
+in a heading and a sentence describing the obvious workflow need separate reasons
+to remain. Necessary breadcrumbs, section headings and the printed document's
+own title still have valid jobs; there is no universal maximum heading count.
+
+During completion, review each supporting sentence in screen order and record
+its new information. If it only narrates the obvious next action, leave the
+optional slot empty. The optional @flood-md/agent/inspect browser observer can
+inventory copy and geometry; it cannot judge whether a sentence belongs in the
+product. See [rendered review](/agent/references/rendered-review.md).
+
+## Concise content keeps necessary detail
+
+Remove routine narration, decorative assurances and implementation facts that do
+not affect the task. An ordinary preview does not need to announce its embedded
+fonts. An export-format choice may need to explain selectable text. A field may
+need a non-obvious unit or constraint. A destructive action may need a clear
+consequence. Do not hide essential information just to reduce visible text.
+
+Name actions by their actual result and preserve accessible names. An error
+should support recovery; success must match a completed operation. Local
+validation does not establish expert review. A PDF export is not a restorable
+backup of editable records. Sample-data distinctions belong where they prevent
+a real misunderstanding, rather than repeated throughout an established test host.
+
+## Learn from references in context
+
+Transfer the question a pattern answers, then use the host's actual objects,
+actions and states. A bill-processing product's approval or payment stages do
+not become capabilities of an invoice generator because their layout is useful.
+Its promotional language is not a vocabulary for the host's working interface.
+
+See the full [interface content skill](/agent/references/flood-interface-content/SKILL.md)
+and [decision examples](/agent/references/interface-content-examples.md). The
+matching installed CLI can discover and read workflow:interface-content. This
+additive guidance is part of 0.2.10; installed projects
+keep their current versions and customized guide copies.
+
+## Review the result
+
+Read the composed screen in task order. Check visible and accessible copy,
+repeated meaning across regions and the state after an action. Remove empty
+wrappers or reserved gaps when a subtitle or banner is removed. Explain important
+editorial decisions in the review, rather than adding those explanations to the UI.
+Phrase scans and word counts cannot establish content quality or agent compliance.
+
+Further reading: [Fluent content design](https://fluent2.microsoft.design/content-design)
+relates content to user intent and timing; [DWP hint guidance](https://design-system.dwp.gov.uk/guidance/hint-text)
+asks whether a hint is needed; [GOV.UK error messages](https://design-system.service.gov.uk/components/error-message/)
+connect failure to recovery. These inform the workflow; their service-specific
+wording and punctuation conventions are not universal Flood rules.
+
+## Prototype context
+
+An explicitly requested local prototype does not require a permanent Demo or
+Prototype badge in the shell. Keep provenance and implementation limits in its
+README/test handoff. A visible distinction still belongs beside an affected
+record, choice or action when it changes interpretation, such as sample records
+mixed with real data or an existing simulation/live choice. Preserve accurate
+action and media names; removing a badge does not imply real connectivity or
+delivery. Draft, Pending and Offline remain meaningful record states.

package/dist/materials/guide-introduction.md

@@ -0,0 +1,40 @@
+# Flood documentation
+
+Flood provides original React components, semantic CSS tokens and versioned
+instructions for coding agents. Start with the guide for your task:
+
+The website renders these guides at [/docs](https://flood.md/docs) and provides
+live examples at [/components](https://flood.md/components). Edit the Markdown
+here and review changes through a pull request; the next website build includes
+them without a separate content service.
+
+| Guide | What it covers |
+| --- | --- |
+| [Skills](skills.md) | Task-focused composition and verification workflows |
+| [Interface content](interface-content.md) | Editorial decisions, purposeful copy and contextual reference adaptation |
+| [Installation](installation.md) | React, Next.js, CLI setup and manual installation |
+| [Project UI](project-ui.md) | Optional semantic @/ui/button imports in your application |
+| [Layout](layout.md) | Intrinsic actions, responsive forms, choice sizing, gaps and hierarchy |
+| [Components](components.md) | Available controls, props and form composition |
+| [Base component inventory](base-components.md) | Available primitives and controls in the base release |
+| [Customization](theming.md) | Scoped dark foundations overrides and legacy theme boundaries |
+| [Foundations](foundations.md) | Typed semantic tokens and neutral dark profile for 0.2.10 |
+| [Agents](agents.md) | Installing and using the matching agent instructions |
+| [Agent knowledge](agent-knowledge.md) | Versioned discovery, selected reads and preserved project guides |
+| [FAQ](faq.md) | Compatibility, customization, updates and common problems |
+| [Command palette](recipes/command-palette.md) | Compose Dialog and CommandList with host-owned actions |
+| [Table bulk actions](recipes/table-bulk-actions.md) | Controlled cross-page selection and local confirmation |
+| [Grouped form](recipes/grouped-form.md) | Shared tracks, semantic groups and optional fields |
+
+## Versions
+
+This branch documents **version 0.2.10**; source availability does
+not establish npm publication. Use matching exact versions of the Flood packages. Documentation on `main` can describe later work; the
+[release tags](https://github.com/tillwithered/flood.md/releases) preserve the
+source and docs for each release. Installed `flood/DESIGN.md` takes precedence
+over website guidance when working in an existing project.
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md), [architecture](architecture.md),
+[releases](releases.md) and the [security policy](../SECURITY.md).

package/dist/materials/guide-layout.md

@@ -0,0 +1,193 @@
+# Layout and composition
+
+Flood provides controls and small layout primitives. The application owns page
+width, grouping and responsive composition. Use the rules below inside
+`FloodRoot` instead of fixing each screen with unrelated spacing values.
+
+## Separate the three kinds of size
+
+A control's `size` or `controlSize` selects its minimum height, typography and
+internal padding. Its width is a separate layout decision. The root font size
+is a user or host preference, not a density setting.
+
+- Buttons normally fit their content. Put sibling actions in `Inline`; do not
+  make every action fill a form or grid cell. Flood 0.2.3 styles keep Button
+  width intrinsic and cap it at the available width.
+- Input, Textarea and Select fill the width their parent assigns. Give their
+  form or Field a responsive width; do not size each field independently.
+- Checkbox and Radio indicators keep a `1.125rem` square footprint and do not
+  shrink in a flex row. A long label wraps beside the indicator rather than
+  compressing it. Switch has its own track geometry.
+
+For a deliberate full-width action, opt in at the application boundary:
+
+```tsx
+<Button style={{ inlineSize: "100%" }}>Continue</Button>
+```
+
+Use this for a specific layout, not as a global rule for all buttons. A long
+translation may increase a control's height; do not hide overflowing labels.
+
+## Keep labels close and groups distinct
+
+The indicator and its visible label are one choice control: their gap is
+`.5rem` (8px at the reference root). Do not add `justify-content: space-between`
+or a large spacer between a checkbox/radio/switch and its own label.
+
+The gap between separate choices should usually be `1rem` (16px at the reference
+root). These two gaps serve different purposes. Preserve `Inline`'s default
+`gap="2"` for compatibility; choose `gap="4"` explicitly for a choice group:
+
+```tsx
+<Inline gap="4" align="center">
+  <Checkbox label="Product updates" name="updates" value="yes" />
+  <Checkbox label="Weekly summary" name="summary" value="yes" />
+</Inline>
+```
+
+Keep row alignment centered. Do not align native indicators to the font baseline
+or allow grid stretch to change their shape. A choice's complete label row is a
+click target; its visible glyph and its target area are different dimensions.
+Compact neighboring targets must remain distinct and usable.
+
+For a radio group, the host provides a real fieldset, legend and shared name:
+
+```tsx
+<fieldset className="preference-group">
+  <legend>Visibility</legend>
+  <Inline gap="4" align="center">
+    <Radio label="Private" name="visibility" value="private" defaultChecked />
+    <Radio label="Public" name="visibility" value="public" />
+  </Inline>
+</fieldset>
+```
+
+```css
+.preference-group {
+  min-inline-size: 0;
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+.preference-group legend {
+  margin-block-end: var(--flood-sys-space-2);
+}
+```
+
+## Give forms a responsive parent width
+
+Use rem for the preferred width and percentages for the available space. A
+`26rem` form can become narrower on a small viewport and follows root scaling:
+
+```css
+.profile-form {
+  inline-size: min(100%, 26rem);
+  min-inline-size: 0;
+}
+```
+
+Keep the width on the actual form/field container. Adding a wrapper changes
+which element a direct-child selector reaches; check the rendered field after
+introducing a scope, Surface or grid cell. Avoid a narrow intrinsic wrapper
+around a full-width textarea.
+
+```tsx
+"use client";
+
+import { Button, Field, FloodRoot, Heading, Inline, Input, Stack, Text } from "@flood-md/react";
+
+export function ProfileForm() {
+  return (
+    <FloodRoot>
+      <form className="profile-form" onSubmit={(event) => event.preventDefault()}>
+        <Stack gap="6">
+          <Stack gap="2">
+            <Heading level={1}>Profile</Heading>
+            <Text as="p" size="compact" tone="subtle">How your team sees you.</Text>
+          </Stack>
+          <Field label="Display name" hint="Visible to your team" required>
+            {(control) => <Input {...control} name="displayName" autoComplete="name" />}
+          </Field>
+          <Inline gap="2" align="center">
+            <Button type="submit">Save changes</Button>
+            <Button type="reset" variant="subtle">Reset</Button>
+          </Inline>
+        </Stack>
+      </form>
+    </FloodRoot>
+  );
+}
+```
+
+Import the package stylesheet once at the application entry. In Next.js, keep
+Field's function child and event handlers in a client component. See
+[Installation](installation.md) and [Components](components.md).
+
+## Establish hierarchy before adding containers
+
+Use Heading for section semantics, compact body text for supporting explanations,
+Field for the visible label and associations, and helper text for supplementary
+details. Text's label appearance alone does not create a form label.
+
+Start with `Stack gap="4"` within a group and `gap="6"` between related groups;
+increase separation for independent sections. Use `Inline` with wrapping for
+actions. Add Surface for an actual surface boundary, not around every field.
+Prominence comes from solid/subtle variants, not from stretching one button.
+
+For a responsive form grid, let CSS determine how many columns fit:
+
+```css
+.profile-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr));
+  gap: var(--flood-sys-space-4);
+}
+```
+
+Do not impose `html { font-size: 16px }`, shrink type to hide overflow, or stretch
+the indicator to make a row fit. Check narrow widths, root text scaling, user
+text-spacing overrides and long translations. Preserve visible focus, native
+form semantics, forced colors and reduced motion while changing composition.
+
+## Coordinate nested corners only where shapes share an inset
+
+A menu's selected/hovered row follows the same outer contour as its popup. For
+uniform padding, derive the inner radius from the outer border-box radius:
+
+`inner radius = max(0, outer radius - padding - border width)`.
+
+The Select popup uses its field-radius role, space-1 padding and stroke-width
+role. At a 16px root these are 16px, 4px and 1px, so the option radius is 11px.
+The relation follows root scaling and semantic overrides; do not reuse the
+independent checkbox indicator radius for menu rows.
+
+The recipe is local to the popup, not a global rule for every descendant.
+Independent Buttons inside Surface or CodeSnippet keep their own action radius.
+Pill tracks/thumbs and segmented controls already derive their curves from their
+actual heights; do not subtract arbitrary padding from an effectively infinite
+pill token. For unequal insets, derive each corner/axis from its actual inset.
+
+## Source additions and compatibility
+
+Select's custom single-choice popup and the refined intrinsic sizing/custom choice appearance are
+included in 0.2.3; older immutable npm releases are unchanged. Use the guide matching your installed declarations. The examples with
+Input, Button, Inline and native form props also work without Select; wrapping
+actions in Inline provides an explicit composition boundary for earlier installs.
+
+## Form hierarchy and rhythm
+
+Use a task title once. Keep optional group titles absent when field labels already
+explain a short form. For a necessary independent group use Fieldset with
+legendSize="section"; the default label-sized legend remains appropriate for
+choices. It preserves native fieldset semantics rather than adding a heading.
+
+Named fields keep a .25rem inner label/control gap. For ordinary desktop forms,
+start with Stack gap="6" between field rows and gap="8" between independent groups
+or before actions. Dialog already supplies its body inset. Choice lists, compact
+filters and table editors have different spacing budgets.
+
+Place four related short fields in one Grid columns={2} so their row edges align.
+A short numeric value alone does not justify a narrower column in only one row;
+long text fields can use a separate full-width row. Verify actual control edges
+with long labels, optional content and 24px root text, not just Grid boxes.
+See [Skills](skills.md) for the shipped hierarchy workflow.

package/dist/materials/guide-privacy.md

@@ -0,0 +1,23 @@
+# Website privacy
+
+The footer on flood.md shows an approximate all-time count of unique browsers
+since the counter was enabled. It is not a count of people or page views.
+
+The website stores one random identifier in your browser's local storage under
+`flood.visitor.v1`. It sends this identifier to a same-origin endpoint to avoid
+counting repeat visits. The counter database stores only a SHA-256 hash of the
+identifier, the aggregate total and the date counting began. It does not store
+IP addresses, page history, referrers, account information or device fingerprints.
+Hashed browser identifiers are retained for deduplication while the counter runs.
+
+Clearing website storage, using private browsing or another browser/device can
+count as another visitor. Known automated user agents are excluded, but the number
+is not audited analytics or an abuse-proof measurement. If local storage is
+unavailable, the site displays the total without registering a visitor. Requests
+that only read HTML or Markdown do not increment the counter.
+
+The hosting provider can maintain its own operational request logs. This counter
+does not control those logs. No third-party analytics script is loaded.
+
+This feature is specific to flood.md. Installing Flood's npm packages does not
+add visitor tracking to your project.

package/dist/materials/guide-project-ui.md

@@ -0,0 +1,127 @@
+# Project UI imports
+
+Flood works with direct named package imports. If you prefer project-owned paths,
+add a thin UI boundary such as `@/ui/button`:
+
+```tsx
+import { Button } from "@/ui/button";
+```
+
+The file name describes the UI responsibility. The package implementation remains
+behind that boundary, so most application files do not need its vendor name.
+This is optional. Both import styles use the same Flood component and receive
+the same installed package updates.
+
+## Connect the package once
+
+Follow [Installation](installation.md) for your React/TypeScript or Next.js project.
+All base components ship together in `@flood-md/react`; there is no per-component
+add command or component source-copy registry. Importing another component does
+not require another installation.
+
+The CLI creates package configuration and agent instructions. It does not create
+these adapters, rewrite application imports or overwrite existing source files.
+Create and review the small files below in your own project. Preserve any existing
+UI wrappers and aliases instead of replacing them blindly.
+
+## Configure the project alias
+
+For the `src/` structure used in this guide, merge the following into your existing
+`tsconfig.json`. Keep the other compiler options and existing path mappings.
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+Configure the same `@` alias in your bundler if it does not read TypeScript paths.
+Next.js supports [TypeScript import aliases](https://nextjs.org/docs/app/getting-started/installation).
+If your application uses another source folder or an existing alias, use the
+matching paths consistently; adding this snippet alone does not move files.
+
+## Add thin adapters
+
+Create `src/ui/button.ts`:
+
+```ts
+export { Button } from "@flood-md/react";
+```
+
+The value re-export already preserves the component's inferred props and ref
+types. If your application also imports the named public props type, expose it
+explicitly from the same file:
+
+```ts
+export { Button } from "@flood-md/react";
+export type { ButtonProps } from "@flood-md/react";
+```
+
+Create `src/ui/flood-root.ts` for the scope used by this example:
+
+```ts
+export { FloodRoot } from "@flood-md/react";
+```
+
+Other adapters follow the explicit component name and slug shown in the catalog:
+`Input` uses `src/ui/input.ts`, `IconButton` uses `src/ui/icon-button.ts`.
+Create only the files your application uses. Adapters contain re-exports; they
+do not copy Flood's component implementation into your project.
+
+## Import styles once
+
+Create `src/ui/styles.css`:
+
+```css
+@import "@flood-md/react/styles.css";
+```
+
+Import that file once at the React application entry. In Next.js App Router, place
+the import in `src/app/layout.tsx` (or `app/layout.tsx` if that is your structure):
+
+```tsx
+import "@/ui/styles.css";
+```
+
+Do not import both the adapter stylesheet and the package stylesheet throughout
+individual component files. `FloodRoot` still explicitly selects neutral/dark;
+the path name does not change the theme or styling contract.
+
+## Use the project imports
+
+```tsx
+"use client";
+
+import { Button } from "@/ui/button";
+import { FloodRoot } from "@/ui/flood-root";
+
+export function SaveAction() {
+  return (
+    <FloodRoot>
+      <Button onClick={() => console.log("Saved locally")}>Save</Button>
+    </FloodRoot>
+  );
+}
+```
+
+Use a client host component for state, callbacks or Field's function child.
+The wrappers do not replace React, remove Next.js client boundaries or make the
+components framework-independent. React 18.3/19 and Next.js support remain as
+described in [Architecture](architecture.md).
+
+## Updates and customization
+
+Keep the installed Flood packages on the same exact version and follow their
+matching release guidance. A re-export automatically uses the installed version;
+upgrades still require application builds and behavior checks. The adapter path
+does not automatically update packages, migrate renamed props or repair breaking
+changes.
+
+Add project defaults in the adapter later if needed, while preserving accessible
+names, native props and refs. This creates a deliberate application policy layer;
+it should not become a second copy of the design system. Keep styles and component
+API expectations aligned with the package version your project actually installs.

package/dist/materials/guide-skills.md

@@ -0,0 +1,108 @@
+# Skills
+
+Flood's agent package includes a lightweight `flood-ui` entry that routes work to
+specialized skills. Start with the [agent guide](agents.md), the host instructions
+and matching installed declarations. Load the skills relevant to the current task,
+not the entire library of instructions.
+
+[Interface content](interface-content.md) covers labels, wording and information
+hierarchy. Its workflow removes unnecessary narration while keeping meaningful
+constraints, consequences, recovery and accessible names.
+
+The hierarchy workflow covers task/group/field roles, common control tracks and
+relationship spacing. It complements editorial decisions and the spacing workflow;
+it does not prescribe one screen template.
+
+The records workflow covers list/detail information selection, stable scan
+positions and the distinction between category, lifecycle state, priority and
+time. It includes examples where those attributes should remain visible, rather
+than a universal rule to hide metadata or limit badge counts.
+
+Use [Agent knowledge](agent-knowledge.md) to discover these workflows by semantic
+group and read the installed version. The catalog separates prerequisites from
+optional related components; grouping is not a request to load every skill.
+
+## Foundations
+
+Semantic colors, type, geometry, spacing and scoped customization.
+
+| Workflow | Use when | Skill source |
+| --- | --- | --- |
+| flood-hierarchy | Establish visual hierarchy, shared form tracks and vertical rhythm in Flood screens, forms and overlays. Use when titles, groups and labels compete or a composed interface feels flat; not a fixed page template. | [Read skill](/agent/references/flood-hierarchy/SKILL.md) |
+| flood-spacing | Diagnose Flood spacing, density, nested radii and alignment from rendered geometry. Use for large gaps, crowded rows or shifting compositions. | [Read skill](/agent/references/flood-spacing/SKILL.md) |
+| flood-foundations | Apply Flood's existing dark semantic surfaces, typography, control sizing and icon geometry. Use for foundation consistency or token-consumer review. | [Read skill](/agent/references/flood-foundations/SKILL.md) |
+
+## Composition
+
+Layout and task recipes assembled from existing primitives.
+
+| Workflow | Use when | Skill source |
+| --- | --- | --- |
+| flood-composition | 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. | [Read skill](/agent/references/flood-composition/SKILL.md) |
+| flood-interface-content | Write or review Flood interface content with editorial decisions about copy, labels, hierarchy and states. Use for visible UI text and reference adaptation; not typography styling, campaigns or rewriting user documents. | [Read skill](/agent/references/flood-interface-content/SKILL.md) |
+| flood-hierarchy | Establish visual hierarchy, shared form tracks and vertical rhythm in Flood screens, forms and overlays. Use when titles, groups and labels compete or a composed interface feels flat; not a fixed page template. | [Read skill](/agent/references/flood-hierarchy/SKILL.md) |
+| flood-spacing | Diagnose Flood spacing, density, nested radii and alignment from rendered geometry. Use for large gaps, crowded rows or shifting compositions. | [Read skill](/agent/references/flood-spacing/SKILL.md) |
+| flood-records | Compose record lists and detail views with a clear metadata hierarchy. Use for crowded status/category/priority/date rows, drifting scan positions or deciding between a list and a comparison table. | [Read skill](/agent/references/flood-records/SKILL.md) |
+
+## Interaction
+
+Forms, selection, navigation and transient layers.
+
+| Workflow | Use when | Skill source |
+| --- | --- | --- |
+| flood-forms | Compose and verify Flood form ownership, labels, values, validation and reset. Use for fields, selection controls or composed form inputs. | [Read skill](/agent/references/flood-forms/SKILL.md) |
+| flood-overlays | Compose or review Flood dialogs, drawers, popovers, menus and anchored selection surfaces. Use for popup geometry, nested dismissal or focus ownership. | [Read skill](/agent/references/flood-overlays/SKILL.md) |
+| flood-navigation | Choose and verify Flood links, tabs, disclosure and hierarchical navigation. Use when destination, selection and expansion semantics can be confused. | [Read skill](/agent/references/flood-navigation/SKILL.md) |
+
+## Data & feedback
+
+Structured content, files and honest operation states.
+
+| Workflow | Use when | Skill source |
+| --- | --- | --- |
+| flood-data-display | Assemble Flood tables, lists, cards and file records with long or changing data. Use for content hierarchy, overflow, row actions and data-state composition. | [Read skill](/agent/references/flood-data-display/SKILL.md) |
+| flood-records | Compose record lists and detail views with a clear metadata hierarchy. Use for crowded status/category/priority/date rows, drifting scan positions or deciding between a list and a comparison table. | [Read skill](/agent/references/flood-records/SKILL.md) |
+| flood-feedback | Choose Flood status, progress, alert, loading and empty-state feedback with honest operation state. Use for meaningful messages and announcement ownership. | [Read skill](/agent/references/flood-feedback/SKILL.md) |
+
+## Quality
+
+Accessibility, evidence and regression checks.
+
+| Workflow | Use when | Skill source |
+| --- | --- | --- |
+| flood-interface-content | Write or review Flood interface content with editorial decisions about copy, labels, hierarchy and states. Use for visible UI text and reference adaptation; not typography styling, campaigns or rewriting user documents. | [Read skill](/agent/references/flood-interface-content/SKILL.md) |
+| flood-accessibility | Review Flood interface names, keyboard flow, focus, perception and reflow in the actual host. Use for interaction or accessibility acceptance. | [Read skill](/agent/references/flood-accessibility/SKILL.md) |
+| flood-verification | Verify Flood component or composed-interface changes against applicable contracts and actual evidence. Use for stabilization, regression or completion review. | [Read skill](/agent/references/flood-verification/SKILL.md) |
+
+See [Workspace review](/docs/recipes/workspace-review) for a runnable form and file
+drawer assembled with these workflows. Its source, ownership choices and host
+checks are documented together.
+
+[Table bulk actions](/docs/recipes/table-bulk-actions) demonstrates controlled
+cross-page selection, protected rows and an explicit confirmation using existing
+Flood primitives. Its operation changes only the local in-memory example.
+
+These skills use the existing dark base. They help apply and verify component
+contracts; they do not imply new themes, animations, unavailable APIs or automatic
+agent compliance. The component-family index describes applicability, not a test
+report or an accessibility certification.
+
+## Use a skill
+
+The matching CLI installs the full sources beneath
+`.agents/skills/flood-ui/references/`. The root `flood-ui` router links the relevant
+workflow. Independent automatic discovery of nested skill directories is not
+assumed; an agent can also read the selected installed `SKILL.md` explicitly.
+
+The same versioned sources are served under `/agent/`. Raw skill links above are
+readable Markdown and can be saved directly. Existing projects should compare
+and merge newer guidance rather than overwrite customized instruction files.
+
+For example, a settings form needs composition and forms, with spacing when
+geometry is being tuned. A drawer with a selection popup additionally needs the
+overlay workflow. Before handing off, use verification and report actual checks,
+failures and any behavior that remains unverified.
+
+The shared [rules index](/agent/rules.json) provides stable rule IDs and observable
+checks; the [workflow index](/agent/workflows.json) describes routing. Neither is
+an executable policy engine or authority to change external systems.