@flood-md/agent 0.2.10 → 0.2.11

package/dist/materials/guide-installation.md

@@ -1,6 +1,6 @@
-# Installation · 0.2.10
+# Installation · 0.2.11
 
-The commands below target version 0.2.10. Verify registry availability before installation; for local source evaluation, see the tarball instructions at the end of this guide.
+The commands below target version 0.2.11. Verify registry availability before installation; for local source evaluation, see the tarball instructions at the end of this guide.
 
 Use Node.js 22.12 or newer and an existing npm-based React/Next.js project.
 React 18.3/19 is supported; React 19 and Next.js App Router are integration targets.
@@ -15,8 +15,8 @@ repeat installation when you start using another component.
 ## Connect with the CLI
 
 ```sh
-npx @flood-md/cli@0.2.10 init --dry-run
-npx @flood-md/cli@0.2.10 init
+npx @flood-md/cli@0.2.11 init --dry-run
+npx @flood-md/cli@0.2.11 init
 ```
 
 The installer adds exact matching tokens, React and agent packages. It creates
@@ -40,7 +40,7 @@ No Tailwind configuration or font CDN is needed. The foundations profile is dark
 only; legacy theme behavior remains available outside `FloodRoot`.
 
 ```sh
-npx @flood-md/cli@0.2.10 doctor
+npx @flood-md/cli@0.2.11 doctor
 ```
 
 Doctor checks package versions and guide presence, not stylesheet imports or
@@ -50,7 +50,7 @@ reference `flood/DESIGN.md` from its existing instructions.
 ## Manual package installation
 
 ```sh
-npm install --save-exact @flood-md/tokens@0.2.10 @flood-md/react@0.2.10 @flood-md/agent@0.2.10
+npm install --save-exact @flood-md/tokens@0.2.11 @flood-md/react@0.2.11 @flood-md/agent@0.2.11
 ```
 
 Import the stylesheet and use `FloodRoot` as above. Manual installation does not

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

@@ -48,7 +48,7 @@ Its promotional language is not a vocabulary for the host's working interface.
 See the full [interface content skill](/agent/references/flood-interface-content/SKILL.md)
 and [decision examples](/agent/references/interface-content-examples.md). The
 matching installed CLI can discover and read workflow:interface-content. This
-additive guidance is part of 0.2.10; installed projects
+additive guidance is part of 0.2.11; installed projects
 keep their current versions and customized guide copies.
 
 ## Review the result

package/dist/materials/guide-introduction.md

@@ -18,17 +18,19 @@ them without a separate content service.
 | [Components](components.md) | Available controls, props and form composition |
 | [Base component inventory](base-components.md) | Available primitives and controls in the base release |
 | [Customization](theming.md) | Scoped dark foundations overrides and legacy theme boundaries |
-| [Foundations](foundations.md) | Typed semantic tokens and neutral dark profile for 0.2.10 |
+| [Foundations](foundations.md) | Typed semantic tokens and neutral dark profile for 0.2.11 |
 | [Agents](agents.md) | Installing and using the matching agent instructions |
 | [Agent knowledge](agent-knowledge.md) | Versioned discovery, selected reads and preserved project guides |
 | [FAQ](faq.md) | Compatibility, customization, updates and common problems |
 | [Command palette](recipes/command-palette.md) | Compose Dialog and CommandList with host-owned actions |
 | [Table bulk actions](recipes/table-bulk-actions.md) | Controlled cross-page selection and local confirmation |
 | [Grouped form](recipes/grouped-form.md) | Shared tracks, semantic groups and optional fields |
+| [Record management](recipes/record-management.md) | Search, filter and edit records without losing the working list |
+| [Settings workspace](recipes/settings-workspace.md) | Group settings, validate a draft and save changes |
 
 ## Versions
 
-This branch documents **version 0.2.10**; source availability does
+This branch documents **version 0.2.11**; source availability does
 not establish npm publication. Use matching exact versions of the Flood packages. Documentation on `main` can describe later work; the
 [release tags](https://github.com/tillwithered/flood.md/releases) preserve the
 source and docs for each release. Installed `flood/DESIGN.md` takes precedence

package/dist/materials/guide-layout.md

@@ -30,13 +30,14 @@ translation may increase a control's height; do not hide overflowing labels.
 
 ## Keep labels close and groups distinct
 
-The indicator and its visible label are one choice control: their gap is
-`.5rem` (8px at the reference root). Do not add `justify-content: space-between`
-or a large spacer between a checkbox/radio/switch and its own label.
+In a compact inline choice, keep the indicator and label together. The
+component's default gap is `.5rem` at the reference root. In a settings list,
+switches can share a trailing edge within a bounded column. Keep each label
+and switch in one clickable row and check that the eye can follow the pair
+across that row. See the [settings recipe](recipes/settings-workspace.md).
 
-The gap between separate choices should usually be `1rem` (16px at the reference
-root). These two gaps serve different purposes. Preserve `Inline`'s default
-`gap="2"` for compatibility; choose `gap="4"` explicitly for a choice group:
+For separate horizontal choices, `gap="4"` is a starting point. In a vertical
+list, inspect the pitch created by the existing hit areas before adding a gap:
 
 ```tsx
 <Inline gap="4" align="center">
@@ -181,13 +182,41 @@ explain a short form. For a necessary independent group use Fieldset with
 legendSize="section"; the default label-sized legend remains appropriate for
 choices. It preserves native fieldset semantics rather than adding a heading.
 
-Named fields keep a .25rem inner label/control gap. For ordinary desktop forms,
-start with Stack gap="6" between field rows and gap="8" between independent groups
-or before actions. Dialog already supplies its body inset. Choice lists, compact
-filters and table editors have different spacing budgets.
+Named fields keep their component-owned label/control gap. Pick the parent
+spacing by reading the rendered relationships. In a quiet form, compare how
+strongly each legend belongs to its first control and how clearly the next
+section begins. In a dense filter bar, control height and shared alignment
+already organize most of the row. Dialog supplies its own body inset.
 
 Place four related short fields in one Grid columns={2} so their row edges align.
 A short numeric value alone does not justify a narrower column in only one row;
 long text fields can use a separate full-width row. Verify actual control edges
 with long labels, optional content and 24px root text, not just Grid boxes.
 See [Skills](skills.md) for the shipped hierarchy workflow.
+
+## Review visible weight
+
+Read the screen at its working size. Name the first thing to notice, the
+content that belongs together, and the edges that should line up. Compare the
+visible text and shapes alongside their boxes. A taller line box, a strong
+divider, or a filled control can make two equal gaps read differently.
+
+Choose the text role before its treatment. A short title may need more
+weight or a wider measure. A paragraph that wraps poorly often needs a
+different measure or line height. Review the actual script, digits and accents
+before adjusting tracking. For comparisons, keep repeated values on shared
+axes. [The Details of UI Typography](https://developer.apple.com/videos/play/wwdc2020/10175/)
+
+Compare two treatments with the same content and viewport. Change one variable
+at a time, then choose the closest existing token that preserves the reading
+order. For example, in a Drawer compare a quieter description in the title
+group with the same text given body weight. Then check the gap before the details
+with a long title and with the description omitted.
+
+The shared axes follow Müller-Brockmann's use of grids as a working tool. The
+attention to letterforms and blank space draws on Ruder, and the comparison of
+contrast and rhythm draws on Hofmann. These are Flood applications of those
+principles. [Grid Systems in Graphic Design](https://niggli.ch/en/products/rastersysteme-fur-die-visuelle-gestaltung) · [The Typography of Order](https://www.neugraphic.com/ruder/ruder-text2.html) · [Graphic Design Manual](https://niggli.ch/en/products/methodik-der-form-und-bildgestaltung)
+
+Recheck with wrapping, enlarged text, and the user's text spacing overrides.
+Controls and content must stay usable when those values change. [W3C Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html)

package/dist/materials/guide-motion.md

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

package/dist/materials/guide-skills.md

@@ -70,10 +70,19 @@ Accessibility, evidence and regression checks.
 
 | Workflow | Use when | Skill source |
 | --- | --- | --- |
+| flood-motion | Design and verify motion for Flood controls, overlays, disclosure, feedback and loading states. Use for animation, transitions, reduced motion and component motion reviews. | [Read skill](/agent/references/flood-motion/SKILL.md) |
 | flood-interface-content | Write or review Flood interface content with editorial decisions about copy, labels, hierarchy and states. Use for visible UI text and reference adaptation; not typography styling, campaigns or rewriting user documents. | [Read skill](/agent/references/flood-interface-content/SKILL.md) |
 | flood-accessibility | Review Flood interface names, keyboard flow, focus, perception and reflow in the actual host. Use for interaction or accessibility acceptance. | [Read skill](/agent/references/flood-accessibility/SKILL.md) |
 | flood-verification | Verify Flood component or composed-interface changes against applicable contracts and actual evidence. Use for stabilization, regression or completion review. | [Read skill](/agent/references/flood-verification/SKILL.md) |
 
+## Motion
+
+Component motion roles, transition recipes and reduced-motion verification.
+
+| Workflow | Use when | Skill source |
+| --- | --- | --- |
+| flood-motion | Design and verify motion for Flood controls, overlays, disclosure, feedback and loading states. Use for animation, transitions, reduced motion and component motion reviews. | [Read skill](/agent/references/flood-motion/SKILL.md) |
+
 See [Workspace review](/docs/recipes/workspace-review) for a runnable form and file
 drawer assembled with these workflows. Its source, ownership choices and host
 checks are documented together.