@flood-md/agent 0.2.9 → 0.2.11

package/dist/materials/guide-layout.md

@@ -0,0 +1,222 @@
+# 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
+
+In a compact inline choice, keep the indicator and label together. The
+component's default gap is `.5rem` at the reference root. In a settings list,
+switches can share a trailing edge within a bounded column. Keep each label
+and switch in one clickable row and check that the eye can follow the pair
+across that row. See the [settings recipe](recipes/settings-workspace.md).
+
+For separate horizontal choices, `gap="4"` is a starting point. In a vertical
+list, inspect the pitch created by the existing hit areas before adding a gap:
+
+```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 their component-owned label/control gap. Pick the parent
+spacing by reading the rendered relationships. In a quiet form, compare how
+strongly each legend belongs to its first control and how clearly the next
+section begins. In a dense filter bar, control height and shared alignment
+already organize most of the row. Dialog supplies its own body inset.
+
+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.
+
+## Review visible weight
+
+Read the screen at its working size. Name the first thing to notice, the
+content that belongs together, and the edges that should line up. Compare the
+visible text and shapes alongside their boxes. A taller line box, a strong
+divider, or a filled control can make two equal gaps read differently.
+
+Choose the text role before its treatment. A short title may need more
+weight or a wider measure. A paragraph that wraps poorly often needs a
+different measure or line height. Review the actual script, digits and accents
+before adjusting tracking. For comparisons, keep repeated values on shared
+axes. [The Details of UI Typography](https://developer.apple.com/videos/play/wwdc2020/10175/)
+
+Compare two treatments with the same content and viewport. Change one variable
+at a time, then choose the closest existing token that preserves the reading
+order. For example, in a Drawer compare a quieter description in the title
+group with the same text given body weight. Then check the gap before the details
+with a long title and with the description omitted.
+
+The shared axes follow Müller-Brockmann's use of grids as a working tool. The
+attention to letterforms and blank space draws on Ruder, and the comparison of
+contrast and rhythm draws on Hofmann. These are Flood applications of those
+principles. [Grid Systems in Graphic Design](https://niggli.ch/en/products/rastersysteme-fur-die-visuelle-gestaltung) · [The Typography of Order](https://www.neugraphic.com/ruder/ruder-text2.html) · [Graphic Design Manual](https://niggli.ch/en/products/methodik-der-form-und-bildgestaltung)
+
+Recheck with wrapping, enlarged text, and the user's text spacing overrides.
+Controls and content must stay usable when those values change. [W3C Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html)

package/dist/materials/guide-motion.md

@@ -0,0 +1,69 @@
+# Motion
+
+`PageHeader` stays static. Its actions keep their own Flood interaction feedback,
+and container reflow does not animate the title or move focus.
+`AppShell` and `AppTopBar` do not animate layout or scroll position. Sidebar
+and Drawer own their own transitions.
+
+Flood uses short motion to show where an interface changed. Motion follows the
+component's own state and respects the operating system's reduced-motion preference.
+
+[Try motion and reduced motion](/playground/motion).
+
+| Event | Typical duration | What moves |
+| --- | --- | --- |
+| Press and hover | 70–100 ms | Paint on actions, rows and options, plus a slight compression while holding a standalone control |
+| Selection and disclosure | 100–160 ms | State paint, glyphs and revealed content |
+| Menus and feedback arrivals | 180 ms | Opacity and small directional movement |
+| Modal and drawer entrances | 240 ms | The arriving layer or its content |
+| Brief dismissal where safe | 120 ms | A visual part with a reliable exit lifecycle |
+
+Use `--flood-sys-motion-*` roles for Flood compositions. Set
+`data-flood-motion="reduce"` on FloodRoot to also suppress component motion in
+an application scope. This setting complements the system preference.
+
+Focus, validation, semantics and state take effect immediately. Static content
+and layout inherit behavior from their interactive owners. Sliders, drag,
+resize and scrolling track input directly. Loading remains legible when its
+indicator stops moving. Native layer dismissal is immediate where the browser
+and React lifecycle remove its content together.
+Floating toasts animate their message on arrival. Inline notices stay static
+within the surrounding reading flow.
+
+Use the versioned `workflow:motion` through the Flood CLI for implementation
+and browser verification guidance.
+
+## Component states
+
+Each row lists components that share a motion owner. Compositions inherit the
+behavior of their children. State updates and focus take effect immediately.
+
+| Components | Motion and state behavior |
+| --- | --- |
+| `FloodRoot` | Applies the motion preference to its scope. Preference changes are immediate. |
+| `Text`, `Heading`, `Kbd`, `VisuallyHidden`, `Blockquote`, `InlineCode`, `IconSlot`, `Label` | Static text and artwork. The containing control owns feedback. |
+| `Stack`, `Inline`, `Surface`, `Divider`, `Container`, `Grid`, `AspectRatio`, `Section`, `Split`, `Center`, `Fieldset` | Stable layout. Children own any appearance or interaction feedback. |
+| `ScrollArea`, `ResizablePanels`, `Slider` | Direct pointer tracking. Only scrollbar hover paint eases. Resize, scroll and slider positions stay under the pointer. |
+| `Button`, `IconButton`, `Toggle`, `CopyButton` | Hover paint and short press compression. Toggle holds selected paint. Copy shows its result glyph without resizing the button. |
+| `ButtonGroup`, `ToggleGroup`, `Toolbar`, `OverflowActions`, `BulkActionBar`, `Menubar` | Actions inherit Button and Menu feedback. Joined button surfaces keep their geometry. Bulk actions fade in when available. |
+| `CommandList`, `ListBox`, `Tree`, `NavigationItem`, `NavigationList`, `NavigationTree`, `NavigationGroup`, `Sidebar` | Row paint, disclosure glyphs and optional flyouts. NavigationTree fades in branch content in place and removes it immediately on collapse. Sidebar eases between expanded and rail widths. Focus, route and tree reflow update immediately. |
+| `Link`, `Breadcrumb`, `Pagination`, `SkipLink`, `Steps` | Navigation is immediate. Button-style actions and step rows can ease their paint. Skip links appear immediately on focus. |
+| `Tabs`, `SegmentedControl` | Selected paint and, for line tabs, an arriving indicator. Tabs reveal the visible panel with a short fade while selection and focus update immediately. |
+| `Field`, `Input`, `Textarea`, `InputGroup`, `SearchInput`, `PasswordInput`, `NumberInput`, `PinInput`, `DateField`, `TimeField`, `DateRangeField`, `Editable`, `CharacterCount` | Field hover paint and inherited action feedback. Typing, caret, counts, validation and edit-mode focus are immediate. |
+| `Checkbox`, `Radio`, `Switch`, `CheckboxGroup`, `RadioGroup`, `CheckCard`, `RadioCard`, `Rating` | Check and rating marks change paint, the switch thumb travels, and selectable cards ease selected paint. Values update immediately. |
+| `Select`, `Combobox`, `Autocomplete`, `MultiSelect`, `TreeSelect`, `DatePicker`, `DateRangePicker`, `TimePicker`, `DateTimePicker`, `DateTimeRangePicker`, `ColorPicker` | Inherit control, active option and layer motion. Typing, range editing, swatch changes and pointer tracking are immediate. |
+| `Calendar`, `RangeCalendar` | Day selection paint. Month and year changes keep the grid stable and respond immediately. |
+| `FileInput`, `Dropzone`, `TagInput`, `Tag`, `FilterCondition`, `FilterGroup`, `CollectionToolbar`, `CollectionViewSwitcher` | Inherit button, field and layer feedback. Drag targets, file changes, chip removal and applied filters update immediately. |
+| `Collapsible`, `Accordion` | Keep the header flush on press, rotate the centered disclosure mark and reveal panel content. Closing immediately hides the panel and restores focus where needed. |
+| `CodeSnippet`, `Card`, `DataList`, `DataListItem`, `FileItem`, `FileList`, `AvatarGroup` | Embedded actions and avatars own motion. Reading order and record layout remain stable. |
+| `Badge`, `DescriptionList`, `Table`, `Image`, `List`, `Figure`, `Metric`, `Timeline`, `ColorSwatch`, `FileMeta` | Static content. Changes to data, labels and supporting media render immediately. |
+| `Avatar` | Loaded image eases in within a fixed frame. Fallback text is immediately available. |
+| `DataTable` | Selected row paint and sort chevron rotation. Sorting, pagination and table geometry update immediately. |
+| `Tooltip`, `Popover`, `Menu`, `ContextMenu`, `HoverCard`, `CommandPalette`, `Dialog`, `AlertDialog`, `Drawer`, `ImagePreview` | Anchored entrances follow placement. Modal and edge panels have their own timing. Controls, focus, close and positioning retain their native behavior. |
+
+Menu, ContextMenu and title-only navigation flyouts fade in and out where
+discrete top-layer transitions are supported. Dismissal releases focus and
+pointer interaction immediately. When a sibling navigation flyout takes over
+the same rail position, the outgoing panel yields immediately.
+| `Spinner`, `Skeleton`, `Progress`, `Meter`, `ToastRegion`, `UploadItem`, `UploadList` | Busy indicators, value fill and floating toast arrivals. Upload compositions inherit the progress and action recipes. Announcements and final values are immediate. |
+| `Alert`, `EmptyState`, `StatusIndicator`, `ErrorSummary` | State and message changes are immediate. Embedded actions keep Button feedback. |

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,117 @@
+# 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-motion | Design and verify motion for Flood controls, overlays, disclosure, feedback and loading states. Use for animation, transitions, reduced motion and component motion reviews. | [Read skill](/agent/references/flood-motion/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-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) |
+
+## Motion
+
+Component motion roles, transition recipes and reduced-motion verification.
+
+| Workflow | Use when | Skill source |
+| --- | --- | --- |
+| flood-motion | Design and verify motion for Flood controls, overlays, disclosure, feedback and loading states. Use for animation, transitions, reduced motion and component motion reviews. | [Read skill](/agent/references/flood-motion/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.

package/dist/materials/guide-theming.md

@@ -0,0 +1,73 @@
+# Customization · 0.2.5
+
+Start with the neutral dark foundations profile. `FloodRoot` selects it locally;
+version 0.2.5 does not provide a light foundations profile or a theme editor.
+Use component props for everyday variations and semantic CSS roles for project
+styling. Keep typography, spacing and finite geometry in relative units.
+
+## Scope your overrides
+
+Import Flood before your own stylesheet and put a class on the same root:
+
+```tsx
+import "@flood-md/react/styles.css";
+import "./theme.css";
+import { FloodRoot, Input, Field } from "@flood-md/react";
+
+export function App() {
+  return (
+    <FloodRoot className="my-app">
+      <Field label="Workspace name">
+        {(props) => <Input {...props} />}
+      </Field>
+    </FloodRoot>
+  );
+}
+```
+
+This example uses Field's function child; in Next.js put it in a client component.
+Import global styles once from the root layout.
+
+```css
+/* theme.css: an opt-in project override, not a new Flood default. */
+.my-app[data-flood-foundations="neutral"][data-flood-theme="dark"] {
+  --flood-sys-radius-field: 1.25rem;
+  --flood-sys-type-body-size: 1rem;
+}
+```
+
+The selector targets the same scope and has enough specificity to override the
+profile declarations. A custom property set on an ancestor may be replaced by a
+profile declaration on FloodRoot. Inspect computed values in the actual host app.
+
+## Choose semantic roles
+
+Use public `sys.*` roles, exposed in CSS as `--flood-sys-*`. Families include
+surface, content, actions, fields, feedback, focus, typography, spacing, radii,
+control sizes and motion. The [foundations guide](foundations.md) explains the
+typed lookup, manifest and scope rules.
+
+Reference (`ref.*`) values are internal building blocks. Their IDs are not a
+public customization contract. Existing props such as Button size/variant,
+Input controlSize and Surface elevation handle many variations without overrides.
+
+## Preserve useful distinctions
+
+Keep primary text readable, secondary text appropriate for its size, and necessary
+field boundaries distinct from quiet decorative borders. Preserve visible keyboard
+focus and native control behavior. Check text with WCAG and APCA guidance in the
+actual composition; a token name or a screenshot does not certify accessibility.
+Test narrow layouts, increased root text size, forced colors and reduced motion.
+
+## Legacy themes outside FloodRoot
+
+Earlier controls outside FloodRoot retain the legacy `--flood-*` variables and
+OS-following light/dark behavior. Explicit `data-flood-theme="light"` or `"dark"`
+selects that legacy theme. These variables do not configure the new foundations
+profile, and changing FloodRoot's theme attribute does not create a supported
+light foundations theme.
+
+For an existing 0.1.x project, follow its installed guide and compare the
+[migration instructions](installation.md#updates-from-011) before adopting
+FloodRoot. Keep the exact Flood package versions aligned and verify your app
+after changing CSS scope or customization.