@flood-md/agent 0.2.2 → 0.2.3

package/DESIGN.md

@@ -1,9 +1,19 @@
-# Flood design system · 0.2.2
+# Flood design system · 0.2.3
+
+Read project-root flood.json and installed declarations with this contract.
+The source bundle's SKILL.md routes to focused composition, accessibility,
+customization and verification references. Its routing matrix names prerequisites
+and sources of truth; flood/rules.json indexes observable checks. Read only the
+relevant reference. This expanded bundle belongs to 0.2.3; existing installations
+keep their matching guide set.
 
 React + TypeScript and Next.js App Router. Use this guide with matching installed
 Flood packages and flood.json. The source repository's release status does not
 grant permission to publish or assume a version is available on npm.
 
+This guide covers all 37 exports in 0.2.3 and their layout refinements. Confirm
+the matching installed declarations before using APIs absent from older versions.
+
 ## Connect
 
 Import @flood-md/react/styles.css once in the application entry or Next root
@@ -23,6 +33,13 @@ child. Keep server data fetching in server components.
 - Use CodeSnippet with a code string and optional action slot for commands or
   short examples. The host owns clipboard permission, feedback and errors;
   selectable wrapped code remains available when copying fails.
+- Use source ScrollArea for deliberately constrained overflow, with a named
+  viewport and explicit height/maxHeight for vertical content. Ref/style/native
+  div props target the native viewport. Overlay rails sit above content without
+  a gutter; default contentInset="scrollbar" protects text with inner padding.
+  Use explicit "none" only with adequate host padding or intentional overlap.
+  Keep wheel/touch/keyboard behavior and native
+  forced-colors fallback. Confirm this export exists in installed declarations.
 - Use Stack and wrapping Inline. Gap and Surface padding keys are strings
   0/1/2/3/4/6/8/12. Parent layout owns spacing; avoid redundant cards and borders.
 - Sizes use rem, line heights ratios, tracking em. Do not impose a fixed root
@@ -34,18 +51,57 @@ child. Keep server data fetching in server components.
 - Use Link for navigation and Button for actions. Button defaults to type=button;
   set type=submit deliberately. Loading disables activation and sets aria-busy;
   retain meaningful visible text and let the host announce completion.
-- Input/Textarea use controlSize sm/md/lg/xl. Preserve Input's native size prop.
+- Input/Textarea and source Select use controlSize sm/md/lg/xl. Preserve native
+  numeric size props. Select accepts native option/optgroup children and an
+  HTMLSelectElement ref. Single selection uses Flood's custom trigger/listbox,
+  with a native select form-value/ref bridge; never replace it with the OS popup.
+  Multiple or size>1 remains an inline native listbox, without a dropdown arrow.
+  For single selection, arrows/Home/End highlight, Enter/Space/Tab commits, and
+  Escape cancels; typeahead matches option labels. Preserve trigger focus and
+  aria-activedescendant rather than moving focus into each option. The ref remains
+  HTMLSelectElement; its focus() targets the trigger. In onChange, read the event's
+  currentTarget as the native select; retain name/required/defaultValue/form reset.
+  Supply ordinary text-labeled options/optgroups, not interactive option content.
   Field required forwards native required and adds a visible marker. Spread all
   callback props to preserve id, aria-describedby and aria-invalid. describedBy
   merges external description IDs with hint/error IDs.
 - Checkbox, Radio and Switch require visible labels and preserve native forms.
   Radio groups share a name and belong in a host fieldset/legend. Readonly and
   disabled are different states; explain unavailability outside disabled controls.
+  Select has no native readOnly state. Do not block its keyboard events to fake one.
 - IconSlot adapts host SVG artwork; without label it is decorative. IconButton
   requires a nonempty action label. Retain the external icon pack's license.
 - Surface elevation overlay is visual only: no portal, focus trap, dismissal or
   dialog semantics are implied. Layer tokens do not implement an overlay manager.
 
+## Layout rules
+
+- Keep Button width intrinsic to its content. Use Inline for sibling actions;
+  opt into full width only for a deliberate host layout with inlineSize:100%.
+  Do not stretch every action because its parent is a grid or vertical stack.
+- Inside a choice, keep the indicator a non-shrinking 1.125rem square and its
+  visible label .5rem away (8px at the reference root). Custom Checkbox/Radio
+  appearance still uses real native inputs; forced colors restores native marks.
+- Separate independent choices with Inline gap="4" (1rem/16px at the reference
+  root). Inline's default gap="2" remains unchanged. Internal label gap and
+  parent group gap are separate decisions; do not conflate them.
+- Center-align choice rows; keep each label close to its indicator. Do not use
+  space-between inside a Checkbox/Radio/Switch to push the label to the other edge.
+- Give form/Field parents a responsive width such as min(100%,26rem), with
+  min-inline-size:0 in grid/flex contexts. Input/Textarea/Select fill that width.
+  Check the actual wrapper tree after adding FloodRoot or Surface; do not leave
+  fields trapped in an intrinsic-width wrapper.
+- Build hierarchy with Heading, body/compact text, Field labels and supporting
+  helper text. Use gap4 within groups, gap6 between related groups, and wrap
+  action rows. Add surfaces for meaningful grouping, not around every control.
+- Keep geometry in rem, line-height unitless and tracking em; preserve the host
+  root size. Check320px widths, enlarged text and user text-spacing overrides
+  instead of shrinking type or clipping labels to make the layout fit.
+
+For inset shapes that share a contour (Select popup and highlighted rows),
+derive inner radius as max(0, outer radius - padding - border width). Keep this
+local to the composition; independent nested actions keep their own radii.
+
 ## Tokens and accessibility
 
 Use semantic --flood-sys-* roles inside FloodRoot; values are authored only in
@@ -54,7 +110,10 @@ Nested token scopes repeat both data-flood-foundations=neutral and
 data-flood-theme=dark attributes. Preserve independent surface, content, boundary,
 selection, feedback and focus roles rather than hardcoding component colors.
 
-The quiet field outline needs its stronger necessary boundary. Focus is 2px
+Default controls use the quiet field.border role, without a second bottom edge or
+inset shadow. Keep field.boundary as an explicit stronger alternative; do not apply
+it to every ordinary control. Quiet defaults do not establish 3:1 non-text
+contrast. Focus is 2px
 without offset; the configurable pink default is provisional. Keep focus visible
 with invalid and selected states. Do not mute a whole component through opacity
 to reduce one border. Never convey error, selection or status by color alone.

package/README.md

@@ -1,5 +1,35 @@
 # @flood-md/agent
 
-Version-matched DESIGN.md and SKILL.md for Flood React/Next.js projects. The CLI
-copies these into owned project files. Read the installed guide before composing
-screens. These files grant no authority to publish or modify external services.
+Version-matched guidance for Flood React/Next.js projects. Read the installed
+contract before composing screens. The 0.2.3 reference bundle includes spacing
+guidance, routing and observable rules. These files grant
+no authority to modify external services.
+
+| Source | Role |
+| --- | --- |
+| DESIGN.md | Shared versioned UI/component contract |
+| SKILL.md | Short entry and task router |
+| references/routing.md | Applicability, audience, prerequisites and governing source |
+| references/composition.md | Screen/form composition workflow |
+| references/spacing.md | Measured spacing, density, nested geometry and hit areas |
+| references/accessibility.md | Interaction and perception checks |
+| references/customization.md | Scoped semantic customization |
+| references/verification.md | Evidence before reporting completion |
+| rules.json | Stable rule IDs with conditions, sources and observable checks |
+| manifest.json | Source → installed-path mapping used by the CLI |
+
+CLI init copies every manifest entry into an unused owned path. Doctor checks
+expected regular files without linked destinations. Neither tool rewrites host
+instructions or proves agent compliance. The website serves these sources under
+/agent/ after a build. Read only relevant references; installed declarations
+govern available APIs. See [the human guide](../../docs/agents.md).
+
+DESIGN.md includes concrete composition rules: intrinsic action widths,
+responsive form parents, a close indicator/label pair, spacing between choices,
+and keyboard/native form requirements. Always check the declarations of the
+installed package before using APIs introduced by a later version.
+See the user-facing [layout guide](../../docs/layout.md) for complete examples.
+
+Manifest entry/rule guide paths identify package sources; manifest.files maps
+them to project-root targets. installedEntry points directly to the project
+skill. Keep manifest.version aligned with the package and DESIGN header.

package/SKILL.md

@@ -1,19 +1,35 @@
 ---
 name: flood-ui
-description: Build React and Next.js interfaces with Flood 0.2 dark foundations, native controls and shared layout primitives. Use for Flood components, tokens, forms and composition.
+description: Compose, customize or review React and Next.js interfaces using installed Flood components, tokens and form contracts. Use in a Flood project; not for unrelated frameworks or deployment.
 ---
 
-Read flood.json and flood/DESIGN.md first. Use matching installed package and CLI
-versions; run doctor when uncertain. Import @flood-md/react/styles.css once and
-compose new interfaces inside FloodRoot for explicit neutral/dark foundations.
+## Start with the installed project
 
-Use Text/Heading, Stack/Inline/Surface, Button/IconButton, Field/Input/Textarea
-and native Checkbox/Radio/Switch. Secondary standalone actions use subtle; ghost
-needs context. Keep associations, required/invalid semantics, keyboard focus,
-relative typography/spacing and responsive layout. Use host SVG icons through
-IconSlot and retain their licenses. Respect Next.js client boundaries.
+Read the host instructions, package.json, flood.json and flood/DESIGN.md from
+the project root. Installed declarations decide which APIs exist. A newer web
+page or repository example does not add exports to an older package. Run the
+matching installed CLI's doctor when versions or guide files are uncertain.
 
-Only use the API provided by the installed version. Preserve host instructions;
-do not introduce another component library, hardcode a parallel token system,
-or assume npm publication from the repository version. This skill does not
-authorize deployment, data deletion or sending host source elsewhere.
+Import @flood-md/react/styles.css once; compose new dark interfaces in FloodRoot.
+Use Flood's existing components before introducing a local adapter. Keep user
+scope and host conventions; missing Flood behavior must be stated rather than
+invented as a package API. No external component library or parallel token system.
+
+## Read only the relevant reference
+
+| Work | Read next | Required result |
+| --- | --- | --- |
+| 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 |
+| 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
+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.
+
+Preserve existing instructions and customized guides. This skill authorizes no
+deployment, deletion, external messages or sending host source to other services.

package/manifest.json

@@ -0,0 +1,59 @@
+{
+  "schemaVersion": 1,
+  "entry": "SKILL.md",
+  "files": [
+    {
+      "source": "DESIGN.md",
+      "target": "flood/DESIGN.md",
+      "kind": "contract"
+    },
+    {
+      "source": "rules.json",
+      "target": "flood/rules.json",
+      "kind": "rules"
+    },
+    {
+      "source": "manifest.json",
+      "target": "flood/manifest.json",
+      "kind": "manifest"
+    },
+    {
+      "source": "SKILL.md",
+      "target": ".agents/skills/flood-ui/SKILL.md",
+      "kind": "skill"
+    },
+    {
+      "source": "references/routing.md",
+      "target": ".agents/skills/flood-ui/references/routing.md",
+      "kind": "reference"
+    },
+    {
+      "source": "references/composition.md",
+      "target": ".agents/skills/flood-ui/references/composition.md",
+      "kind": "reference"
+    },
+    {
+      "source": "references/accessibility.md",
+      "target": ".agents/skills/flood-ui/references/accessibility.md",
+      "kind": "reference"
+    },
+    {
+      "source": "references/customization.md",
+      "target": ".agents/skills/flood-ui/references/customization.md",
+      "kind": "reference"
+    },
+    {
+      "source": "references/verification.md",
+      "target": ".agents/skills/flood-ui/references/verification.md",
+      "kind": "reference"
+    },
+    {
+      "source": "references/spacing.md",
+      "target": ".agents/skills/flood-ui/references/spacing.md",
+      "kind": "reference"
+    }
+  ],
+  "version": "0.2.3",
+  "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.2",
+  "version": "0.2.3",
   "type": "module",
   "description": "Versioned Flood design instructions for coding agents.",
   "license": "MIT",
@@ -12,11 +12,17 @@
   "files": [
     "DESIGN.md",
     "SKILL.md",
+    "references",
+    "rules.json",
+    "manifest.json",
     "README.md"
   ],
   "exports": {
     "./DESIGN.md": "./DESIGN.md",
-    "./SKILL.md": "./SKILL.md"
+    "./SKILL.md": "./SKILL.md",
+    "./manifest.json": "./manifest.json",
+    "./rules.json": "./rules.json",
+    "./references/*": "./references/*"
   },
   "publishConfig": {
     "access": "public"

package/references/accessibility.md

@@ -0,0 +1,63 @@
+# Preserve interaction and perception
+
+Read the installed component contract before changing its behavior. Do not add
+ARIA to replace functioning native semantics or describe behavior that is absent.
+
+- Every field needs a visible associated label. Spread Field callback props;
+  preserve id, required, aria-describedby and aria-invalid. Hint/error content
+  must describe the field. A placeholder is not its label.
+- Keep the visible 2px focus perimeter with zero offset, including invalid and
+  selected states. Focus should not move layout or create another noisy contour.
+  Verify the actual foreground/background when overriding its accent.
+- Checkbox, Radio and Switch keep native inputs, values, reset and keyboard.
+  Radios share name and use a host fieldset/legend. Disabled and readOnly differ;
+  Select has no native readOnly behavior.
+- If installed Select exists: single choice uses Flood's custom popup, not an OS
+  dropdown. Arrows/Home/End highlight; Enter/Space/Tab commits; Escape cancels.
+  The native select bridge owns the form/ref contract. Multiple or size>1 is an
+  inline listbox. Do not turn the option text into another interactive control.
+- Name icon-only actions by their effect, not glyph. Keep decorative SVGs out of
+  accessible names. Loading disables activation; announce host completion/errors
+  separately. Explain disabled actions in text outside the disabled element.
+- Evaluate text contrast using WCAG and APCA guidance with actual size, weight
+  and background. APCA does not replace applicable WCAG requirements. Decorative
+  separators differ from necessary control boundaries; never mute a whole
+  component with opacity just to soften a border.
+- Root font sizing belongs to the host. Preserve rem geometry, text wrapping,
+  forced-colors indicators and reduced-motion preferences.
+
+Test keyboard start-to-finish, focus visibility, labels and descriptions,
+validation, native form reset, long text, 320px layout and root text enlargement.
+An automated scanner alone cannot establish application accessibility or WCAG 3
+conformance. Record what was actually checked; see [verification](verification.md).
+## Field status and read-only values
+
+Use status on Field/Input/Textarea/Select for error, warning, success or info.
+With Field, provide message and spread its callback props onto the Flood control.
+Only error marks aria-invalid; warning/success/info are advisory. Existing error
+or invalid takes precedence. Include a useful description instead of relying on
+color alone. Status does not implement host validation or native constraints.
+
+readOnly on text-like Input/Textarea prevents editing while preserving focus,
+selection, copy and submission. Do not substitute disabled or apply readOnly to
+Select/checkboxes. Explain the restriction. Preserve the solid accent focus even
+when a read-only field uses a dashed resting perimeter.
+
+External-label visibility: source Field/Fieldset hideLabel preserves the actual
+label/legend and accessible name while removing its visual row. RadioGroup,
+CheckboxGroup and SegmentedControl inherit it. Keep label/legend supplied and
+textual; do not hide interactive label content. Use it only where surrounding
+context supplies the visible meaning. Input/Textarea/Select/InputGroup configure
+this on their Field wrapper, not the control. Placeholder never replaces naming;
+choice option labels and button names have separate contracts. Available in 0.2.3.
+
+Overlay source APIs: forward trigger render props/ref onto one actual button;
+keep trigger mounted/visible. Tooltip is noninteractive text help, not the only
+name/instruction; hover/focus opens, Escape dismisses, focus stays. Popover is a
+named nonmodal dialog; outside/focus-leave/Escape close without trapping Tab.
+Dialog uses native showModal and inert background, cycles focus, restores scroll
+and opener. Escape dismisses the top layer; outside closing is independently
+configurable. Provide a visible title and safe initialFocusRef when needed. Closed
+Popover/Dialog children unmount; host owns persistent values and controlled open.
+Modern native APIs required. DOM/theme scope stays intact; no body portal needed.
+Available in 0.2.3.

package/references/composition.md

@@ -0,0 +1,141 @@
+# Compose an interface
+
+For spacing, density or nested-geometry decisions, read [Spacing](spacing.md).
+Measure the complete row geometry before adding a gap to repeated controls.
+
+Start with content and the user's interaction. Use the installed exports shown
+in flood/DESIGN.md; no invented props, new component library or copied registry.
+
+1. Choose semantic Heading levels independently of visual size. Text handles
+   supporting copy; keep the content hierarchy quieter than the primary task.
+2. Compose vertical rhythm with Stack and wrapping rows with Inline. Surface
+   represents a real container/elevation, not a wrapper around every element.
+3. Keep action widths intrinsic. A full-width action is an explicit host choice.
+   Controls fill a responsive form parent such as min(100%, 26rem); min-inline-size:0
+   belongs on constrained grid/flex children. Inspect the actual wrapper tree.
+4. Keep a choice glyph and its label together: .5rem within Checkbox/Radio/Switch;
+   use an explicit Inline gap="4" (1rem) between separate choices. Center the row;
+   never use space-between to pull a single label away from its indicator.
+5. Use Field's callback props on the control. Keep name/value/required/form/reset
+   behavior and wire submission/validation in the host. Button type defaults to
+   button, so choose submit/reset deliberately. Link navigates.
+6. Standalone secondary actions use subtle. Ghost needs an existing toolbar or
+   clear parent context. Loading must leave a meaningful action name.
+
+In Next.js import CSS once in app/layout.tsx. State, event callbacks and Field's
+function child belong in a client component. Keep serializable compositions on
+the server where useful. Flood does not save data or define permissions.
+
+Use IconSlot for host SVGs and IconButton for named icon-only actions. Retain
+the icon license; slot dimensions must control the artwork. A local semantic
+adapter such as @/ui/button may re-export Flood, but does not change React APIs.
+
+Before handing off, inspect a real composed screen at narrow and wide widths,
+not only isolated controls. See [verification](verification.md).
+
+For constrained overflow, use installed ScrollArea when available. Set height or
+maxHeight on its viewport, choose the needed axis, and provide a useful accessible
+name. Rails overlay content with insets; keep essential content out of the rail
+zone through the default `contentInset="scrollbar"`. Use explicit `"none"` only
+when host padding already protects essential content, or overlap is intentional.
+The engine
+shortens rails near rounded clipping corners; do not add ad-hoc per-page rail
+offsets. Do not hide native scrolling as a CSS-only
+substitute for an overlay engine. Check wheel, touch, keyboard, thumb drag, resize
+and RTL; preserve the native forced-colors fallback.
+
+## label and group foundations
+
+Field already composes Label. Use standalone Label when assembling an associated
+control outside Field; its required marker does not set native required. Keep IDs
+unique. Use Fieldset and its legend for related controls, with hint/message/error
+on the group and individual labels on each control. A disabled native fieldset
+disables descendants except controls in its first legend. Fieldset does not own
+selected values or replace a RadioGroup/CheckboxGroup selection contract. Preserve
+these semantics in nested groups and native form submission.
+
+## selection groups
+
+Use RadioGroup for one string value and CheckboxGroup for a string array. Supply
+name, legend and options with unique values; disable individual options when
+needed. Use value/onValueChange for host-controlled selection, or defaultValue
+for local selection. RadioGroup required is native; validate CheckboxGroup
+selection counts in the host. Read repeated checkbox form values with getAll.
+The group forwards Fieldset descriptions/status and native form ownership.
+Form reset restores uncontrolled defaults and preserves controlled values;
+canceled reset is ignored and reset does not emit onValueChange.
+
+## connected controls
+
+ButtonGroup contains direct Button/IconButton actions with compatible sizes and
+an accessible group label. Tab navigation is ordinary; do not invent toolbar
+arrow-key behavior. InputGroup wraps one native text-like Input; Field callback
+props and ref target that input. start/end slots provide host-owned text/icons/
+actions; they are not submitted values or labels. className/style own the wrapper.
+Disable addon actions explicitly when the task needs it. Preserve a single field
+perimeter and distinguish input focus from action focus. Use supported installed
+exports; these constructs are available in 0.2.3.
+
+Nested actions in InputGroup use the group's height and equal space-1 optical
+insets, with inner radius = field radius minus inset. Button size still controls
+text/icon/padding; do not compensate with extra margins. Touch targets may grow
+the shell. Text-only addons keep the field's reading padding.
+
+ButtonGroup accepts Button and named IconButton children, including mixed groups;
+full separators follow its orientation. InputGroup start/end independently accept
+short text, decorative icons or named actions. Plain addons are subtle; actions
+keep action colors. Explain units in the label/description. Prefixes are not masks
+or automatically submitted value fragments; compose complete values in the host.
+
+Toggle is a pressed native action: keep its name stable, use pressed/onPressedChange
+or defaultPressed, and label iconOnly artwork. ToggleGroup uses unique options
+and string-array values in both single/multiple modes; single can be cleared.
+Arrow/Home/End navigate focus; Enter/Space activate; ordinary Tab order remains.
+Do not use these as form inputs, required radios or tabs. No automatic native
+form reset/submission is provided. Default props initialize only; host state owns
+controlled values. Available in 0.2.3.
+
+SegmentedControl composes native RadioGroup for one value/mode: label, unique form
+name and string-label options, with optional artwork. Use value/onValueChange or
+defaultValue; it does not clear when the selected item is pressed again. Arrows
+select, Home/End select endpoints, Space checks; Enter keeps native form behavior.
+Native form/required/disabled/reset behavior remains. Use actual tabs for panels,
+not SegmentedControl. Choose short labels, icons or vertical orientation for
+constrained widths; fullWidth distributes segments equally. iconOnly retains
+accessible option labels. Available in 0.2.3.
+
+Collapsible: title + children, open/onOpenChange or defaultOpen. Accordion composes
+Collapsible via unique value/title/content items; string-array selection in single
+(one or none) or multiple expansionMode. Choose headingLevel for host structure.
+Enter/Space activate; Accordion Up/Down/Home/End focus enabled top-level headers,
+not nested disclosures. Panels stay mounted and hidden, so form values and native
+constraints persist. Disabled only prevents trigger activation. Programmatic
+closing returns panel focus to an enabled trigger if focus has not moved elsewhere;
+host owns focus for removed/disabled triggers. Only chevron motion, reduced-motion
+aware; no height animation or per-panel landmark flood. Available in 0.2.3.
+
+Tooltip/Popover/Dialog: trigger is a render function; forward every
+supplied prop/ref to one connected visible Button in the same document. Tooltip
+content is text only. Use Popover for interactive contextual UI and Dialog for a
+modal task. Controlled open/onOpenChange needs host updates; initial defaults are
+not synchronization. Closed Popover/Dialog children unmount, so keep persistent
+form values in host state. initialFocusRef chooses a safe element in the panel;
+closeLabel localizes the explicit close action. Native top-layer APIs preserve
+FloodRoot theme scope without body portals. Avoid overriding positioning fields.
+Native Popover/dialog support is required, no legacy polyfill. Available in 0.2.3.
+
+Link defaults to text; opt-in solid/subtle/outline/ghost and
+Button sizes share the button recipe without changing native anchor semantics.
+Use href/target for navigation, Button for actions; never nest the two or add
+role=button. Link has no disabled/loading contract. Available in 0.2.3.
+Tabs switches linked content panels (not modes or radio values) on a shared
+contained surface. Avoid a second enclosing card inside the panel; selected fill
+joins the panel without an additional underline. Arrows activate by default,
+or focus only with activationMode=manual; Enter/Space commit. One tab
+stop, RTL/orientation aware, disabled skip. Panels stay mounted/hidden and retain
+native form constraints. Controlled/missing/disabled selected values derive first
+available; host reconciles values. Breadcrumb is an ordered native link hierarchy,
+last item current. Pagination is controlled page/pageCount with onPageChange or
+getHref; host owns data/routes and empty states. Counts must be positive safe
+integers in range; siblingCount 0/1/2 bounds window size. Native modifier navigation,
+localized names, unavailable endpoints and narrow wrapping stay intact. Available in 0.2.3.

package/references/customization.md

@@ -0,0 +1,27 @@
+# Customize without a parallel system
+
+Use FloodRoot for the neutral/dark foundations profile. The new light foundations
+profile is not supplied; do not infer it from legacy controls outside FloodRoot.
+
+Read the installed @flood-md/tokens foundation manifest and matching DESIGN.md.
+Override semantic --flood-sys-* variables on a deliberate host scope after the
+Flood stylesheet. Reuse existing content, surface, state, typography, spacing,
+radius and control roles before adding a local application token. State which
+role changes, why and which components consume it.
+
+Do not edit generated node_modules assets, paste a second raw color scale into
+components or invent unsupported token names. In the Flood source repository,
+tokens are authored only in packages/tokens/src/tokens.json; generated files
+are outputs. A consuming application's overrides remain application-owned.
+
+Keep reference values separate from semantic roles. Component recipes consume
+roles, and screen composition consumes components. An accent/material experiment
+must be scoped; it must not silently alter ordinary fields, text or focus.
+
+Keep layout/typography in rem, role line heights and tracking intact unless the
+task explicitly changes them. Never impose a root 16px or 62.5% reset. Bundled
+Inter retains its OFL notice; external icon/font assets keep their own notices.
+
+Verify resolved token values, all affected states and surfaces, WCAG/APCA text
+context, focus/non-text contrast, forced colors, narrow layout and text scaling.
+An attractive default screenshot does not validate an override across a product.

package/references/routing.md

@@ -0,0 +1,26 @@
+# Route work to its source
+
+Read the host's instructions before Flood guidance. User requirements define the
+task; Flood's contracts explain supported implementation. These files do not
+override user authority or grant permission for unrelated operations.
+
+| Question / when | Audience | Prerequisite | Source of truth | Verify with |
+| --- | --- | --- | --- | --- |
+| Which API can I import? Every component edit | Developer / agent | Installed exact versions | Installed @flood-md/react declarations; flood.json | Type-check host imports; CLI doctor for alignment |
+| What does this release mean? Setup / upgrade | Developer / agent | Matching guide | flood/DESIGN.md, package changelog | Compare version and declarations; preserve host edits |
+| How should a screen fit together? Screen / form work | Designer / developer / agent | Scope, content and current API | composition.md; host layout requirements | Narrow/wide rendered screen and native form interaction |
+| Why does spacing look wrong? Density / nested geometry | Designer / developer / agent | Installed tokens and actual wrapper tree | spacing.md; host content hierarchy | Measured visible gaps, row pitch, text reflow and touch targets |
+| What must remain accessible? Control/state work | Developer / reviewer / agent | Named controls and actual host context | accessibility.md; installed component contract | Keyboard, accessible names, validation and focus checks |
+| How can appearance change? Theme / density work | Designer / developer / agent | Existing semantic roles | customization.md; installed token manifest | Inspect resolved roles, contrast and reflow |
+| Is this done? Completion / regression | Reviewer / agent | Runnable host and checks | verification.md; project scripts | Report commands, manual checks and gaps |
+| Which rules apply? Planning / review | Human / agent / tooling | Same installed guide set | flood/rules.json | Rule IDs linked to evidence, not a blanket pass |
+
+References are beside this file. In an initialized project the contract and
+rules are under project-root flood/. On the website these files are under
+/agent/references/ and /agent/. Use installed files for existing applications;
+the deployed website describes its own source/release status.
+
+For exact per-component examples and API tables, read the matching component
+Markdown page. Do not load every component page or all references by default.
+Public source catalog/declarations generate website API tables during builds;
+the website is not a replacement for the host's installed declarations.

package/references/spacing.md

@@ -0,0 +1,61 @@
+# Spacing, density and nested geometry
+
+Use this guide when composing Flood controls or correcting excessive gaps,
+inconsistent grouping or shifting previews. Start with host instructions, the
+installed declarations and token manifest. User-approved geometry takes precedence
+over a generic recipe; newer website examples do not add APIs to an older package.
+
+## Identify the relationship
+
+Decide what each space separates: an indicator and its label, a title and its
+description, choices in one group, independent actions, sections or nested surfaces.
+Keep related content together and give unrelated sections a stronger separation.
+One gap value should not be repeated indiscriminately through nested wrappers.
+
+| Relationship | Starting point; check the installed recipe |
+| --- | --- |
+| Indicator and its own label | Existing choice component geometry; do not add another wrapper gap |
+| Title and supporting description | A close pair, typically space-1 in the current Fieldset recipe |
+| Repeated choices | Group row height already provides separation; inspect it before adding gap |
+| Separate horizontal actions | Explicit parent spacing; space-4 is a starting point |
+| Sections | Host content hierarchy and available width |
+
+These are contextual defaults rather than a universal scale. Prefer supported
+Stack/Inline spacing props and scoped semantic tokens. Host layout CSS owns host
+spacing. Do not edit installed package files or invent unavailable component props
+to change density. Use relative units and preserve the host's root font size.
+
+## Measure visible geometry
+
+Inspect the rendered interface, wrapper tree and computed gap, padding, margin,
+line-height, minimum height and alignment. Measure the visible indicator/text as
+well as the full interactive row. A zero flex gap can still look widely spaced.
+
+For equal centered rows, indicator separation is approximately row height minus
+indicator height plus row gap. A 40px row plus an 8px gap creates 48px row pitch;
+the gap declaration alone does not describe perceived density. Those numbers
+illustrate the calculation, not a fixed recipe for every installed release.
+
+Remove redundant space at its owning layer. Preserve explicit icon dimensions,
+the relationship between indicator and label, and independent form semantics.
+Avoid negative margins or transforms that conceal a layout problem or overlap
+click targets. For nested surfaces, compare inner radius with outer radius minus
+padding and stroke; independent controls retain their own radius recipe.
+
+## Check the composition
+
+- Inspect short and wrapping labels, narrow/wide widths and larger root text.
+  Rows may grow for content; do not clip text to enforce a compact height.
+- Check hint, error, status, loading and disabled cases where applicable.
+  Different content must not unexpectedly reposition an unrelated demo control.
+- Distinguish the component from its preview host. Fixed scenes and reserved
+  message rows belong to a demo when needed, not automatically to a host product.
+- Check fine and coarse pointers separately. Compact mouse geometry must preserve
+  the supported touch-target minimum and nonoverlapping hit areas on touch.
+- Recheck keyboard focus, label activation and a sibling that shares the recipe.
+
+Use actual screenshots and measured geometry to judge the result. Follow the
+host's verification workflow; add a regression check for a repeated failure rather
+than a test that merely repeats a CSS declaration. Report what was measured and
+what remains unverified. See [accessibility](accessibility.md) and
+[verification](verification.md) for related contracts.

package/references/verification.md

@@ -0,0 +1,28 @@
+# Verify the actual change
+
+Use the host's scripts and conventions; do not assume Flood's repository scripts
+exist in a consumer. Run the matching CLI doctor for version/file alignment when
+setup or upgrades changed. Doctor does not parse CSS imports or certify UI.
+
+| Change | Evidence needed |
+| --- | --- |
+| Imports / package upgrade | Host type-check/build; installed versions and declarations match |
+| Form / control behavior | Labels/descriptions, keyboard, value/submission, required/invalid, reset, disabled/loading and focus |
+| Layout / typography | Actual narrow and wide screen, long content, root 24px text sizing and increased text spacing; no accidental page overflow |
+| Appearance / tokens | Resolved roles and actual surfaces/states; contrast, focus, forced colors and reduced motion |
+| Copy / external actions | Exact clipboard payload where applicable; honest local/saved/sent state and error feedback |
+
+For visual changes capture and inspect the rendered screen. A passing build does
+not show alignment, hierarchy or wrapping. Use meaningful existing browser tests
+and an accessibility scanner when available; also perform keyboard checks.
+
+In the Flood source repository run npm run verify, and browser tests for changed
+behavior/styles. In a consuming project use its equivalent checks. Report commands
+run and results, manual visual/keyboard checks, and anything left unverified.
+Use rule IDs from project-root flood/rules.json when useful to connect findings
+to the specific contract. Do not report a rule as tested from prose alone.
+
+Never infer npm publication, a deployment or a backend save from a local build.
+Updating an installed guide is a review/merge task: preserve customized files;
+do not rerun init to overwrite them. No reference grants authority to deploy,
+delete data or transmit private source.

package/rules.json

@@ -0,0 +1,184 @@
+{
+  "schemaVersion": 1,
+  "scope": "Installed Flood React/Next.js projects",
+  "rules": [
+    {
+      "id": "api.installed",
+      "when": "Importing or changing Flood APIs",
+      "for": [
+        "developer",
+        "agent"
+      ],
+      "requires": [
+        "Host package.json",
+        "flood.json"
+      ],
+      "sourceOfTruth": "Installed @flood-md/react declarations",
+      "guide": "references/routing.md",
+      "verify": [
+        "Host type-check",
+        "Matching CLI doctor for package alignment"
+      ]
+    },
+    {
+      "id": "composition.primitives",
+      "when": "Composing screens or forms",
+      "for": [
+        "designer",
+        "developer",
+        "agent"
+      ],
+      "requires": [
+        "Supported installed exports",
+        "User interaction requirements"
+      ],
+      "sourceOfTruth": "DESIGN.md",
+      "guide": "references/composition.md",
+      "verify": [
+        "Rendered narrow/wide screen",
+        "Intrinsic actions and responsive form parent",
+        "Close choice label and independent group spacing"
+      ]
+    },
+    {
+      "id": "forms.associations",
+      "when": "Changing fields or submission",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Visible labels",
+        "Host validation and submission flow"
+      ],
+      "sourceOfTruth": "Installed Field/control contract",
+      "guide": "references/accessibility.md",
+      "verify": [
+        "Accessible names and descriptions",
+        "Native values, required and reset",
+        "Invalid focus and disabled/loading behavior"
+      ]
+    },
+    {
+      "id": "interaction.keyboard",
+      "when": "Changing interactive controls",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Runnable screen",
+        "Installed control keyboard contract"
+      ],
+      "sourceOfTruth": "Installed component behavior and DESIGN.md",
+      "guide": "references/accessibility.md",
+      "verify": [
+        "Keyboard-only full interaction",
+        "Visible focus in every relevant state",
+        "Select commit/cancel if present"
+      ]
+    },
+    {
+      "id": "theme.semantic",
+      "when": "Customizing visual roles",
+      "for": [
+        "designer",
+        "developer",
+        "agent"
+      ],
+      "requires": [
+        "Installed token manifest",
+        "Actual affected surfaces"
+      ],
+      "sourceOfTruth": "Installed token roles; source tokens.json when developing Flood",
+      "guide": "references/customization.md",
+      "verify": [
+        "Resolved scoped semantic values",
+        "Text and non-text contrast",
+        "No parallel raw palette"
+      ]
+    },
+    {
+      "id": "layout.reflow",
+      "when": "Changing layout or type",
+      "for": [
+        "designer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Actual composed screen"
+      ],
+      "sourceOfTruth": "DESIGN.md and host content requirements",
+      "guide": "references/composition.md",
+      "verify": [
+        "320px width",
+        "Root 24px and increased text spacing",
+        "No glyph shrink or unintended page overflow"
+      ]
+    },
+    {
+      "id": "verification.evidence",
+      "when": "Reporting completion",
+      "for": [
+        "developer",
+        "reviewer",
+        "agent"
+      ],
+      "requires": [
+        "Host verification scripts",
+        "Task scope"
+      ],
+      "sourceOfTruth": "Observed command and rendered behavior results",
+      "guide": "references/verification.md",
+      "verify": [
+        "Commands and actual results recorded",
+        "Manual checks distinguished",
+        "Untested behavior stated"
+      ]
+    },
+    {
+      "id": "installation.preserve",
+      "when": "Installing or updating guidance",
+      "for": [
+        "developer",
+        "agent"
+      ],
+      "requires": [
+        "Existing host instructions",
+        "User scope"
+      ],
+      "sourceOfTruth": "Host files and version-matched guide set",
+      "guide": "references/routing.md",
+      "verify": [
+        "Existing files preserved",
+        "No linked destinations followed",
+        "No publication inferred from source version"
+      ]
+    },
+    {
+      "id": "layout.spacing",
+      "when": "Composing or reviewing spacing, density, nested surfaces or moving previews",
+      "for": [
+        "designer",
+        "developer",
+        "agent"
+      ],
+      "requires": [
+        "Installed token manifest",
+        "Rendered host and actual wrapper tree"
+      ],
+      "sourceOfTruth": "Installed component recipe and host layout requirements",
+      "guide": "references/spacing.md",
+      "verify": [
+        "Measure visible gaps and row pitch, including padding and minimum height",
+        "Check wrapping and enlarged text",
+        "Check fine/coarse pointers and nonoverlapping interactive targets",
+        "Preserve keyboard focus and label activation"
+      ]
+    }
+  ],
+  "guideResolution": "Match guide to source in manifest.files; use its target relative to the host project root."
+}