@flood-md/agent 0.2.2 → 0.2.4

package/DESIGN.md

@@ -1,9 +1,19 @@
-# Flood design system · 0.2.2
+# Flood design system · 0.2.4
+
+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.4; 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 the supported exports in 0.2.4 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.
@@ -99,3 +158,116 @@ export function Profile() {
   );
 }
 ```
+
+
+0.2.4 adds Badge, Spinner, Skeleton and Avatar. Read references/composition.md and references/accessibility.md for status announcements, fallback geometry and decorative naming. Button loading reuses Spinner. These APIs are not present in 0.2.3.
+
+Progress, Meter and Alert are also available in 0.2.4. Distinguish task completion from bounded measurements, preserve names/units, and select alert announcement priority explicitly.
+
+DescriptionList and Table are also available in 0.2.4. Preserve native description-list/table structure, table captions and header relationships. Range of displayed data and formatting remain host-owned; DataTable behavior is outside these primitives.
+
+Menu adds a real action-menu keyboard contract in 0.2.4; it reuses the layer engine and ScrollArea while remaining distinct from Select and Popover. onAction business effects belong to the host.
+
+### Toolbar and Kbd (0.2.4)
+
+Toolbar groups Button, IconButton, Toggle, native buttons/links and Menu triggers
+under one named action panel. After hydration it uses one Tab entry, directional
+arrows, Home/End and optional looping. Disabled/hidden actions are skipped. Arrows
+move focus, not activation. Horizontal order follows writing direction. In vertical
+toolbars open Menu with Enter/Space; horizontal menus retain Up/Down opening.
+Keep text inputs and independent selection widgets outside this action-only API.
+Native child handlers and refs remain attached; Toolbar owns their tabIndex while
+mounted and restores original attributes on cleanup. Without JavaScript, native
+child Tab order remains available. Use a meaningful required label.
+
+Kbd renders native kbd markup with sm/md/lg sizes and relative keycap heights.
+It displays a key or combination; the host implements real shortcuts. It is not
+interactive. Menu shortcut hints reuse Kbd and remain hidden from item names.
+
+```tsx
+<Toolbar label="Editor actions">
+  <Button variant="ghost">Undo</Button>
+  <Toggle variant="ghost">Bold</Toggle>
+  <Button variant="ghost">Share</Button>
+</Toolbar>
+<Kbd>Ctrl</Kbd> + <Kbd>K</Kbd>
+```
+
+### Card (0.2.4)
+
+Card composes Surface into a header, body and footer. Optional title, description,
+actions and footer accept React content; children are the body. Missing slots
+create no empty section. Use Surface when only a background/padding is needed.
+
+Card is a noninteractive div. Put Button, Link or Menu in actions/footer and keep
+its container out of the Tab order. Do not make the entire card clickable around
+nested controls. Native div props, styles and HTMLDivElement ref target the root.
+The title prop is heading content, not an HTML tooltip; supply phrasing content.
+headingLevel defaults to 2; choose the correct hierarchy for the host page.
+
+Compact/comfortable density controls existing spacing tokens. Header actions wrap
+without clipping menus or focus indicators. Footer uses a quiet separator; a
+footer-only card has no redundant separator. Elevation is default or raised.
+No data access, selection or interactive-card behavior is implied.
+
+```tsx
+<Card title="Project details" description="Keep your team in sync."
+  footer={<Button variant="subtle">Open project</Button>}>
+  <Text as="p" size="compact">A calm place for the next idea.</Text>
+</Card>
+```
+
+## Structural, media and accessible primitives · 0.2.4
+
+Container centers a max-width box with logical gutters. size sm/md/lg uses
+40/64/80rem bounds including padding; full removes the max. gutter uses Space.
+Grid defaults to auto-fit with a16rem semantic minimum clamped to available
+width. gap uses Space. minItemWidth overrides the auto minimum; explicit columns
+(1/2/3/4/6/12) remain fixed. Grid is ordinary layout, never an ARIA grid widget.
+
+VisuallyHidden preserves content in the accessibility tree using span/div. Default
+is for noninteractive content. Use focusable for a skip link: focus-within reveals
+its wrapper; style the actual link's focus. This is different from aria-hidden or
+conditional rendering. Native captions/legends may use the same hiding utility
+without an invalid generic wrapper. Spinner and hidden indicator captions compose
+VisuallyHidden. Field hideLabel and Fieldset hideLabel use focusable hiding so
+valid interactive label/legend descendants reveal their label while focused;
+keep primary actions visible in ordinary compositions.
+
+AspectRatio reserves responsive media geometry before loading, accepting a finite
+positive ratio (16/9 default). Direct img/video/iframe children fill its box. It
+does not clip focus or make arbitrary long content fit; the host owns alternative
+text, captions, media controls and deliberate cropping. Image is a native img
+with required alt (empty for decorative content), cover/contain fit and preserved
+srcSet/sizes/loading/decoding/dimensions/events/ref. No optimizer, fetch engine or
+fallback is implied. Avatar composes Image for its own loading lifecycle. Supply
+image dimensions or AspectRatio to reserve space.
+
+List renders native ul/ol with native li children and token gap. ordered selects
+ol; start/reversed apply there. start must be a safe integer. marker=false retains
+explicit list semantics for platforms that drop lists without visible markers.
+This is content, not ListBox selection or arrow navigation.
+
+EmptyState composes Stack, Heading, Text, IconSlot and Inline. Required title,
+optional description, decorative icon and actions explain absent content; choose
+headingLevel for the host hierarchy. It is static, with no automatic focus or
+announcement. compact/comfortable density controls padding. The host implements
+real actions and decides whether asynchronously changed results need announcing.
+
+Checkbox adds indeterminate for a host-controlled mixed presentation after
+hydration. checked independently determines form submission; mixed does not mean
+a third submitted value. The host owns aggregate/select-all values. Native reset
+and ref access remain available. Radio and Switch do not expose indeterminate.
+
+ButtonGroup/ToggleGroup retain their keyboard contracts and locally scroll when
+a connected row cannot fit. InputGroup actions keep words intact and can wrap to
+a new row while the input retains usable space. Plain string adornments are bidi
+isolated; for protocols/phones with explicit direction pass a bdi dir=ltr node.
+Keep very long addon content concise. Hidden native choices hide their label too.
+
+Dark foundations bundle both normal and italic Inter, including Cyrillic, with
+original OFL notices. Color alone never communicates validation or progress.
+
+CodeSnippet codeDirection defaults to ltr independently of RTL parent action layout; choose rtl/auto explicitly for content that needs it. Native dir still applies to the wrapper. Protected ScrollArea reveals focused descendants fully when needed, composes the host focus handler and avoids scrolling to nested top-layer controls.
+
+Checkbox, Radio and Switch apply native hidden/dir/lang to their visible label wrapper as well as the input, so a component-local language/direction applies to its whole choice.

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.4 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.4",
+  "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.4",
   "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,79 @@
+# 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 and keep actions visibly discoverable. In 0.2.4 a hidden Field label or
+Fieldset legend reveals while its descendant has focus, preserving native names
+and child state. Use hideLabel 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.
+
+
+For 0.2.4 loading primitives: localize standalone Spinner label, avoid duplicate live announcements, and keep Skeleton hidden from AT. Reduced motion stops their animations. Avatar exposes one named image, or decorative presentation when the adjacent text already supplies identity. Badge text must express status without relying on its color.
+
+
+Progress and Meter are not live regions. Keep their labels even with hideLabel, and provide meaningful valueText when percentages would be misleading. Unknown Progress omits aria-valuenow; Meter has no unknown state. Alert defaults to silent static content; opt into announcement=polite (status) or assertive (alert) only for the required urgency. Do not move focus to these messages or claim every screen reader announces initial markup. Verify with actual assistive technology.
+
+
+Retain DescriptionList native dl/dt/dd semantics without redundant ARIA term/definition roles. Table needs a meaningful caption (hideCaption keeps its name) and host-owned header associations; never convert table rows into display:block cards without preserving relationships. Name the horizontal scroll viewport, retain keyboard scrolling and check that focusable cell controls remain reachable. Native table ref points to table, not viewport.
+
+
+Menu: preserve menu/menuitem/separator semantics and trigger aria-haspopup/expanded/controls. Disabled items remain arrow-focusable with aria-disabled and must never activate. Use arrows/Home/End/typeahead within the menu, Escape to close, Tab out and Shift+Tab to trigger. Do not turn ordinary navigation lists into application menus. Restore focus unless the host deliberately moved it; test nested Dialog behavior and actual assistive technology separately.
+
+Toolbar requires a meaningful label. After hydration it manages child tabIndex, skips hidden/disabled actions, supports Home/End, orientation and RTL, and restores original child tabIndex attributes on cleanup. Native child handlers/refs remain attached. Before JavaScript native child Tab order remains. Kbd has native keyboard-input semantics and adds no focus stop or handler; do not present unimplemented bindings as working shortcuts.

package/references/composition.md

@@ -0,0 +1,161 @@
+# 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.
+
+
+## Metadata, loading and identity · 0.2.4
+
+Use Badge for noninteractive metadata with meaningful text. Spinner is indeterminate loading; use decorative inside a control already named by its owner. Button loading already composes it. Skeleton reserves geometry and is always hidden from AT; the host owns aria-busy and loading text. Avatar requires name and supports src/fallback; choose decorative beside an equivalent visible name. Keep image and fallback geometry fixed. None of these primitives fetch data or provide upload behavior.
+
+
+Progress is task completion; omit value for unknown progress. Meter is a bounded measurement and always requires value. Both need label and finite increasing ranges; invalid values throw. Use valueText for localized units and hideLabel for visually hidden captions. Wrapper refs and native div props do not replace the internal range semantics. Alert is inline feedback: title optional, host actions inside children, icon=null to omit artwork. Tone and announcement are independent. No task manager, validation engine, automatic dismissal or Toast queue is supplied. Available in 0.2.4.
+
+
+DescriptionList uses native dl/dt/dd for related readonly properties; use unique item IDs, meaningful term text and formatted description content. Inline layout stacks according to container width; it does not label editable controls. Table owns caption and a horizontal Flood ScrollArea. Supply native table sections and correct th scope/id/headers relationships; className/style/ref target the actual table. Use data-numeric for numeric cells and style.minWidth for wide tables. Cell actions stay ordinary focusable controls; do not imply DataTable sorting, selection or fetching. Available in 0.2.4.
+
+
+Menu is a dedicated action-menu contract, not Popover with arbitrary buttons. Forward supplied trigger props/ref to Button/IconButton. Use unique IDs and nonempty labels; separators are noninteractive, disabled items discoverable but inert, danger is visual intent only. onAction requests closing then calls host logic. No href, submenu or checkbox/radio behavior is supplied. Items/shortcuts do not install global key bindings. Place Table row actions inside a cell, with an IconButton name that includes the row identity. Available in 0.2.4.
+
+Toolbar groups actions with one Tab entry after hydration. Use Button/IconButton/Toggle, native buttons/links and Menu triggers. Arrows move focus; Enter/Space activate the native control. Keep independent selection widgets and text fields outside this action-only toolbar. In a vertical toolbar Enter/Space opens Menu; Up/Down remain toolbar navigation. Use Kbd for display-only keyboard hints and implement actual bindings in the host. Available in 0.2.4.
+
+Card is structured Surface containment: title/description/header actions, body children and footer. Missing slots add no empty sections. Choose compact/comfortable density; preserve the tight title-description relationship. Use appropriate headingLevel. Keep root noninteractive and place named controls inside, never a card-wide click handler around nested actions. Use Surface for unstructured containment.
+
+Compose lower-level responsibilities: Container/Grid and Stack/Inline arrange; Surface contains; Card structures; Image/AspectRatio reserve media; List preserves native li. EmptyState composes the shared typography/icon/action atoms. Use VisuallyHidden for supplemental noninteractive text or focusable reveal for skip links. Do not replace native caption/legend structures with generic wrappers solely for reuse. Mixed Checkbox is host-owned aggregation, with checked still controlling submission.

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,30 @@
+# 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.
+
+Check both normal and italic font loading where emphasis is used; matching font-family text alone does not establish that the face loaded. For responsive geometry verify320px plus enlarged root text/RTL in the actual served production assets, not only injected source CSS. Exercise local overflow by focusing the final action/item and verify content is not beneath a scrollbar. Test failed/missing images and absent component slots without inventing loading/fallback promises.

package/rules.json

@@ -0,0 +1,187 @@
+{
+  "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",
+        "Reuse shared atoms while preserving specialized native semantics",
+        "Container/grid/media geometry at320px and enlarged RTL text",
+        "No invisible focusable content without reveal behavior"
+      ]
+    },
+    {
+      "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."
+}