@flood-md/agent 0.2.10 → 0.2.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/DESIGN.md +8 -5
- package/README.md +1 -1
- package/SKILL.md +11 -0
- package/dist/catalog.json +1914 -278
- package/dist/materials/component-app-shell.md +49 -0
- package/dist/materials/component-app-top-bar.md +36 -0
- package/dist/materials/component-autocomplete.md +54 -0
- package/dist/materials/component-bulk-action-bar.md +52 -0
- package/dist/materials/component-button.md +1 -0
- package/dist/materials/component-card.md +2 -2
- package/dist/materials/component-collapsible.md +1 -0
- package/dist/materials/component-collection-toolbar.md +69 -0
- package/dist/materials/component-collection-view-switcher.md +49 -0
- package/dist/materials/component-combobox.md +10 -0
- package/dist/materials/component-command-palette.md +53 -0
- package/dist/materials/component-copy-button.md +1 -0
- package/dist/materials/component-data-table.md +34 -4
- package/dist/materials/component-date-picker.md +1 -0
- package/dist/materials/component-date-range-picker.md +1 -0
- package/dist/materials/component-date-time-picker.md +2 -0
- package/dist/materials/component-date-time-range-picker.md +4 -0
- package/dist/materials/component-drawer.md +1 -0
- package/dist/materials/component-editable.md +4 -0
- package/dist/materials/component-figure.md +1 -1
- package/dist/materials/component-filter-condition.md +53 -0
- package/dist/materials/component-filter-group.md +55 -0
- package/dist/materials/component-heading.md +1 -1
- package/dist/materials/component-icon-button.md +2 -0
- package/dist/materials/component-menubar.md +41 -0
- package/dist/materials/component-multi-select.md +10 -0
- package/dist/materials/component-navigation-group.md +51 -0
- package/dist/materials/component-navigation-item.md +59 -0
- package/dist/materials/component-navigation-tree.md +8 -0
- package/dist/materials/component-overflow-actions.md +47 -0
- package/dist/materials/component-page-header.md +40 -0
- package/dist/materials/component-popover.md +2 -1
- package/dist/materials/component-radio-card.md +2 -2
- package/dist/materials/component-section.md +1 -1
- package/dist/materials/component-segmented-control.md +6 -4
- package/dist/materials/component-sheet.md +49 -0
- package/dist/materials/component-sidebar.md +64 -0
- package/dist/materials/component-sparkline.md +41 -0
- package/dist/materials/component-table.md +2 -0
- package/dist/materials/component-tabs.md +2 -0
- package/dist/materials/component-text.md +2 -2
- package/dist/materials/component-toggle.md +1 -0
- package/dist/materials/component-toolbar.md +5 -0
- package/dist/materials/component-tooltip.md +1 -1
- package/dist/materials/guide-agent-knowledge.md +13 -6
- package/dist/materials/guide-agents.md +8 -1
- package/dist/materials/guide-foundations.md +45 -2
- package/dist/materials/guide-installation.md +6 -6
- package/dist/materials/guide-interface-content.md +1 -1
- package/dist/materials/guide-introduction.md +4 -2
- package/dist/materials/guide-layout.md +39 -10
- package/dist/materials/guide-motion.md +66 -0
- package/dist/materials/guide-skills.md +9 -0
- package/dist/materials/recipe-collection-views.md +670 -0
- package/dist/materials/recipe-command-palette.md +31 -52
- package/dist/materials/recipe-filter-bar.md +12 -3
- package/dist/materials/recipe-grouped-form.md +5 -0
- package/dist/materials/recipe-navigation-workspace.md +222 -0
- package/dist/materials/recipe-record-management.md +310 -0
- package/dist/materials/recipe-record-workspace.md +207 -0
- package/dist/materials/recipe-settings-workspace.md +232 -0
- package/dist/materials/token-sys.color.context.base.action-disabled.json +41 -0
- package/dist/materials/token-sys.color.context.base.action-hover.json +41 -0
- package/dist/materials/token-sys.color.context.base.action-pressed.json +41 -0
- package/dist/materials/token-sys.color.context.base.action-rest.json +41 -0
- package/dist/materials/token-sys.color.context.base.avatar-background.json +41 -0
- package/dist/materials/token-sys.color.context.base.border-decorative.json +41 -0
- package/dist/materials/token-sys.color.context.base.divider-decorative.json +41 -0
- package/dist/materials/token-sys.color.context.base.field-background.json +41 -0
- package/dist/materials/token-sys.color.context.base.field-border.json +41 -0
- package/dist/materials/token-sys.color.context.base.field-disabled.json +41 -0
- package/dist/materials/token-sys.color.context.base.field-readonly.json +41 -0
- package/dist/materials/token-sys.color.context.base.indicator-track.json +41 -0
- package/dist/materials/token-sys.color.context.base.loading-placeholder.json +41 -0
- package/dist/materials/token-sys.color.context.base.muted-background.json +41 -0
- package/dist/materials/token-sys.color.context.base.on-surface-action-disabled.json +41 -0
- package/dist/materials/token-sys.color.context.base.on-surface-action-hover.json +41 -0
- package/dist/materials/token-sys.color.context.base.on-surface-action-pressed.json +41 -0
- package/dist/materials/token-sys.color.context.base.on-surface-action-rest.json +41 -0
- package/dist/materials/token-sys.color.context.base.selection-background.json +41 -0
- package/dist/materials/token-sys.color.context.base.supporting-background.json +41 -0
- package/dist/materials/token-sys.color.context.filled.action-disabled.json +41 -0
- package/dist/materials/token-sys.color.context.filled.action-hover.json +41 -0
- package/dist/materials/token-sys.color.context.filled.action-pressed.json +41 -0
- package/dist/materials/token-sys.color.context.filled.action-rest.json +41 -0
- package/dist/materials/token-sys.color.context.filled.avatar-background.json +41 -0
- package/dist/materials/token-sys.color.context.filled.border-decorative.json +41 -0
- package/dist/materials/token-sys.color.context.filled.divider-decorative.json +41 -0
- package/dist/materials/token-sys.color.context.filled.field-background.json +41 -0
- package/dist/materials/token-sys.color.context.filled.field-border.json +41 -0
- package/dist/materials/token-sys.color.context.filled.field-disabled.json +41 -0
- package/dist/materials/token-sys.color.context.filled.field-readonly.json +41 -0
- package/dist/materials/token-sys.color.context.filled.indicator-track.json +41 -0
- package/dist/materials/token-sys.color.context.filled.loading-placeholder.json +41 -0
- package/dist/materials/token-sys.color.context.filled.muted-background.json +41 -0
- package/dist/materials/token-sys.color.context.filled.selection-background.json +41 -0
- package/dist/materials/token-sys.color.context.filled.supporting-background.json +41 -0
- package/dist/materials/token-sys.color.field.readonly.json +41 -0
- package/dist/materials/token-sys.color.surface.avatar.json +41 -0
- package/dist/materials/token-sys.color.surface.current.json +41 -0
- package/dist/materials/token-sys.color.surface.muted.json +41 -0
- package/dist/materials/token-sys.color.surface.supporting.json +41 -0
- package/dist/materials/token-sys.motion.distance-panel.json +36 -0
- package/dist/materials/token-sys.motion.distance-small.json +36 -0
- package/dist/materials/token-sys.motion.duration-enter.json +36 -0
- package/dist/materials/token-sys.motion.duration-exit.json +36 -0
- package/dist/materials/token-sys.motion.duration-layer.json +36 -0
- package/dist/materials/token-sys.motion.duration-loop.json +36 -0
- package/dist/materials/token-sys.motion.duration-press.json +36 -0
- package/dist/materials/token-sys.motion.easing-enter.json +38 -0
- package/dist/materials/token-sys.motion.easing-exit.json +38 -0
- package/knowledge.json +115 -2
- package/lib/inspect.mjs +11 -0
- package/manifest.json +11 -1
- package/package.json +9 -3
- package/references/component-families.md +150 -0
- package/references/composition.md +16 -4
- package/references/customization.md +14 -0
- package/references/flood-composition/SKILL.md +4 -0
- package/references/flood-data-display/SKILL.md +146 -0
- package/references/flood-feedback/SKILL.md +37 -0
- package/references/flood-forms/SKILL.md +31 -0
- package/references/flood-foundations/SKILL.md +36 -0
- package/references/flood-hierarchy/SKILL.md +27 -7
- package/references/flood-interface-content/SKILL.md +33 -5
- package/references/flood-motion/SKILL.md +47 -0
- package/references/flood-navigation/SKILL.md +195 -0
- package/references/flood-overlays/SKILL.md +41 -0
- package/references/flood-records/SKILL.md +65 -2
- package/references/flood-spacing/SKILL.md +45 -0
- package/references/flood-verification/SKILL.md +20 -0
- package/references/interface-content-examples.md +4 -0
- package/references/rendered-review.md +5 -0
- package/references/spacing.md +30 -0
- package/rules.json +98 -8
- package/workflows.json +28 -3
|
@@ -30,7 +30,10 @@ export function Example() {
|
|
|
30
30
|
- Use Button, IconButton, Toggle, native buttons/links and Menu triggers. Keep inputs, Select, Tabs and ToggleGroup outside this action-only toolbar.
|
|
31
31
|
- Arrows move focus without activation; Home/End jump to the ends. Disabled and hidden actions are skipped. One Tab entry is established after hydration; before JavaScript native child tab order remains.
|
|
32
32
|
- Horizontal arrows follow writing direction. Vertical arrows move between actions; open a vertical toolbar Menu with Enter/Space. Horizontal menus retain ArrowUp/Down opening.
|
|
33
|
+
- A vertical pill centers its controls on one axis. Use consistently sized icon-only actions with accessible names. Use the rounded shape for a vertical group of labeled actions.
|
|
33
34
|
- loop defaults to true. Native div props/ref target the toolbar; preserve a meaningful label. Available in 0.2.4.
|
|
35
|
+
- shape defaults to rounded; pill uses the action radius and a horizontal single scrollable rail.
|
|
36
|
+
- variant="plain" removes the material and outer inset for grouping peer controls; contained remains the default. Keyboard ownership is unchanged.
|
|
34
37
|
|
|
35
38
|
## API reference
|
|
36
39
|
|
|
@@ -39,4 +42,6 @@ export function Example() {
|
|
|
39
42
|
| `label` | `string` | `Required` |
|
|
40
43
|
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
|
|
41
44
|
| `loop` | `boolean` | `true` |
|
|
45
|
+
| `shape` | `"rounded" \| "pill"` | `—` |
|
|
46
|
+
| `variant` | `"contained" \| "plain"` | `—` |
|
|
42
47
|
| `Native HTML props` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | `Forwarded` |
|
|
@@ -32,7 +32,7 @@ export function Example() {
|
|
|
32
32
|
| Prop | Values | Default |
|
|
33
33
|
| --- | --- | --- |
|
|
34
34
|
| `content` | `string` | `Required` |
|
|
35
|
-
| `trigger` | `(props:
|
|
35
|
+
| `trigger` | `(props: TooltipTriggerProps) => ReactNode` | `Required` |
|
|
36
36
|
| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` |
|
|
37
37
|
| `align` | `"start" \| "center" \| "end"` | `"center"` |
|
|
38
38
|
| `delay` | `number` | `300` |
|
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
# Agent knowledge
|
|
2
2
|
|
|
3
|
-
Flood 0.2.
|
|
3
|
+
Flood 0.2.11 includes a versioned read-only catalog and reader. Use the CLI matching
|
|
4
4
|
the project's flood.json; source availability does not prove npm publication.
|
|
5
5
|
The same package sources build the website, CLI results and agent instructions.
|
|
6
6
|
|
|
7
7
|
## Discover, then read
|
|
8
8
|
|
|
9
9
|
```sh
|
|
10
|
-
npx @flood-md/cli@0.2.
|
|
11
|
-
npx @flood-md/cli@0.2.
|
|
12
|
-
npx @flood-md/cli@0.2.
|
|
13
|
-
npx @flood-md/cli@0.2.
|
|
14
|
-
npx @flood-md/cli@0.2.
|
|
10
|
+
npx @flood-md/cli@0.2.12 info --json
|
|
11
|
+
npx @flood-md/cli@0.2.12 catalog --kind workflow --group foundations
|
|
12
|
+
npx @flood-md/cli@0.2.12 catalog --kind component --search table
|
|
13
|
+
npx @flood-md/cli@0.2.12 read recipe:table-bulk-actions
|
|
14
|
+
npx @flood-md/cli@0.2.12 read component:data-table
|
|
15
15
|
```
|
|
16
16
|
|
|
17
17
|
These commands return JSON and do not install dependencies, edit files, execute
|
|
@@ -19,6 +19,13 @@ skill text or contact a Flood server. The package runner may fetch the CLI if
|
|
|
19
19
|
it is not installed locally; keep its version deliberate. Existing project and
|
|
20
20
|
agent instructions remain authoritative.
|
|
21
21
|
|
|
22
|
+
For a screen that filters one table between two views, start with
|
|
23
|
+
`read component:segmented-control` and follow its link to `workflow:records`.
|
|
24
|
+
If the screen switches between independent panels, read `component:tabs`.
|
|
25
|
+
Before delivery, open the list and a selected record together, then use
|
|
26
|
+
`workflow:interface-content` and `reference:interface-content-examples` to
|
|
27
|
+
decide which labels, counts and status messages the user needs in each view.
|
|
28
|
+
|
|
22
29
|
info reports actual installed package versions, the configured guide version,
|
|
23
30
|
framework detection, catalog identity and capability declarations. A version
|
|
24
31
|
mismatch prevents catalog/read from serving an ambiguous guide train. A
|
|
@@ -14,7 +14,7 @@ sources. The website index is generated from the same bundle metadata rather
|
|
|
14
14
|
than a second handwritten skill catalog. Source additions do not update an
|
|
15
15
|
already installed package; use the guide set matching your installation.
|
|
16
16
|
|
|
17
|
-
Version 0.2.
|
|
17
|
+
Version 0.2.11 adds [versioned knowledge discovery](agent-knowledge.md):
|
|
18
18
|
info reports installation context, catalog discovers compact metadata, and read
|
|
19
19
|
loads a selected contract or workflow. The catalog includes typed recipes and
|
|
20
20
|
semantic token records. Unknown capabilities and version mismatches are explicit;
|
|
@@ -41,6 +41,13 @@ a Badge/Progress/Dialog implementation just to make one layout fit.
|
|
|
41
41
|
|
|
42
42
|
## Files and responsibilities
|
|
43
43
|
|
|
44
|
+
For reusable components, the composition skill also routes to
|
|
45
|
+
[component families](../packages/agent/references/component-families.md): choose
|
|
46
|
+
the closest existing anatomy and compare sizing, shape, nested insets and states
|
|
47
|
+
in the same scene. Flood's repository instructions require that same guide for
|
|
48
|
+
its own authors. Installed projects receive it through the matching manifest and
|
|
49
|
+
knowledge catalog; existing customized guides are not silently overwritten.
|
|
50
|
+
|
|
44
51
|
| Project file | For whom / when | Prerequisite | Source of truth | What to check |
|
|
45
52
|
| --- | --- | --- | --- | --- |
|
|
46
53
|
| flood.json | Developer / agent, setup or upgrade | Existing React project | Exact installed release, framework and paths | Matching CLI doctor |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# Foundations tokens · 0.2.
|
|
1
|
+
# Foundations tokens · 0.2.12 candidate
|
|
2
2
|
|
|
3
|
-
This guide describes the **0.2.
|
|
3
|
+
This guide describes the **0.2.12 candidate** foundation exports. Keep Flood packages at
|
|
4
4
|
matching exact versions. Existing 0.1.1 installs use their earlier token contract.
|
|
5
5
|
|
|
6
6
|
Foundations separates fixed reference values (`ref`) from semantic roles (`sys`).
|
|
@@ -84,6 +84,49 @@ prepend `--flood-`. The generated typed lookup is the complete contract.
|
|
|
84
84
|
| `motion` | `duration-fast`, `duration-normal`, `duration-reduced`, `easing` |
|
|
85
85
|
| `layer` | `base`, `sticky`, `popover`, `modal`, `toast` |
|
|
86
86
|
|
|
87
|
+
### Material and nested control context
|
|
88
|
+
|
|
89
|
+
Absolute `color.surface.canvas/default/raised/overlay/floating` roles describe
|
|
90
|
+
materials. A component that draws a material establishes the context for its
|
|
91
|
+
children: Surface, Dialog/Drawer, anchored popups and selection menus, Toast,
|
|
92
|
+
Toolbar/BulkActionBar, standalone Calendar and other shared material owners.
|
|
93
|
+
Stack, Inline, Grid and other transparent layout wrappers inherit that context.
|
|
94
|
+
Nesting a default Surface inside an overlay returns to the default material;
|
|
95
|
+
DOM depth does not increment elevation.
|
|
96
|
+
|
|
97
|
+
Neutral actions, fields, read-only/disabled fills, choices, selection, supporting
|
|
98
|
+
chips/keycaps, skeletons and progress tracks consume inherited semantic roles.
|
|
99
|
+
On filled materials, `color.context.filled.*` supplies translucent neutral state
|
|
100
|
+
overlays: secondary actions use white 5% / 8% / 12% at rest / hover / press,
|
|
101
|
+
fields use 5%, and quiet borders use 8%. This keeps a secondary action secondary
|
|
102
|
+
on both a card and a floating panel. The canvas retains its established defaults.
|
|
103
|
+
Primary actions, content, focus and semantic feedback colors remain independent.
|
|
104
|
+
|
|
105
|
+
`color.surface.current` supplies the opaque material base for tinted feedback;
|
|
106
|
+
`surface.supporting`, `surface.muted`, `surface.avatar` and `field.readonly`
|
|
107
|
+
separate contextual fills from the absolute canvas color. Do not repurpose canvas
|
|
108
|
+
to recolor controls: it also supplies contrasting content and document/media wells.
|
|
109
|
+
|
|
110
|
+
Automatic owners require no extra Button/Input props. For an application-owned
|
|
111
|
+
material boundary, `data-flood-surface="base|filled|floating"` selects the neutral
|
|
112
|
+
control context. The attribute does not paint a background or implement a popup.
|
|
113
|
+
Choose the actual material and override `color.surface.current` on that same
|
|
114
|
+
scope if it differs from Flood's material. A transparent wrapper should not
|
|
115
|
+
declare another material context.
|
|
116
|
+
|
|
117
|
+
Customize contextual recipes using `--flood-sys-color-context-filled-*` and
|
|
118
|
+
`--flood-sys-color-context-base-*` at the root. A direct consumer role override
|
|
119
|
+
on the material owner can refine one scope; a canvas-only field override does
|
|
120
|
+
not silently replace all elevated recipes. Review both contexts when opting into
|
|
121
|
+
strong boundaries. The generated manifest is the complete list of roles.
|
|
122
|
+
|
|
123
|
+
Floating panels use an opaque fallback, with glass enabled only where supported.
|
|
124
|
+
`prefers-reduced-transparency: reduce` and `data-flood-transparency="reduced"`
|
|
125
|
+
on a FloodRoot or an owning subtree request opaque panels without backdrop blur.
|
|
126
|
+
Forced colors retain system backgrounds, boundaries and selection indicators.
|
|
127
|
+
Translucency is a visual recipe, not an accessibility guarantee: inspect the
|
|
128
|
+
composited background, content contrast and focus in the actual host.
|
|
129
|
+
|
|
87
130
|
### Inter typography
|
|
88
131
|
|
|
89
132
|
Size equivalents assume a 16px root for illustration. Flood does not set the
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# Installation · 0.2.
|
|
1
|
+
# Installation · 0.2.12
|
|
2
2
|
|
|
3
|
-
The commands below target version 0.2.
|
|
3
|
+
The commands below target version 0.2.12. Verify registry availability before installation; for local source evaluation, see the tarball instructions at the end of this guide.
|
|
4
4
|
|
|
5
5
|
Use Node.js 22.12 or newer and an existing npm-based React/Next.js project.
|
|
6
6
|
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.
|
|
|
15
15
|
## Connect with the CLI
|
|
16
16
|
|
|
17
17
|
```sh
|
|
18
|
-
npx @flood-md/cli@0.2.
|
|
19
|
-
npx @flood-md/cli@0.2.
|
|
18
|
+
npx @flood-md/cli@0.2.12 init --dry-run
|
|
19
|
+
npx @flood-md/cli@0.2.12 init
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
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
|
|
|
40
40
|
only; legacy theme behavior remains available outside `FloodRoot`.
|
|
41
41
|
|
|
42
42
|
```sh
|
|
43
|
-
npx @flood-md/cli@0.2.
|
|
43
|
+
npx @flood-md/cli@0.2.12 doctor
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
Doctor checks package versions and guide presence, not stylesheet imports or
|
|
@@ -50,7 +50,7 @@ reference `flood/DESIGN.md` from its existing instructions.
|
|
|
50
50
|
## Manual package installation
|
|
51
51
|
|
|
52
52
|
```sh
|
|
53
|
-
npm install --save-exact @flood-md/tokens@0.2.
|
|
53
|
+
npm install --save-exact @flood-md/tokens@0.2.12 @flood-md/react@0.2.12 @flood-md/agent@0.2.12
|
|
54
54
|
```
|
|
55
55
|
|
|
56
56
|
Import the stylesheet and use `FloodRoot` as above. Manual installation does not
|
|
@@ -48,7 +48,7 @@ Its promotional language is not a vocabulary for the host's working interface.
|
|
|
48
48
|
See the full [interface content skill](/agent/references/flood-interface-content/SKILL.md)
|
|
49
49
|
and [decision examples](/agent/references/interface-content-examples.md). The
|
|
50
50
|
matching installed CLI can discover and read workflow:interface-content. This
|
|
51
|
-
additive guidance is part of 0.2.
|
|
51
|
+
additive guidance is part of 0.2.11; installed projects
|
|
52
52
|
keep their current versions and customized guide copies.
|
|
53
53
|
|
|
54
54
|
## Review the result
|
|
@@ -18,17 +18,19 @@ them without a separate content service.
|
|
|
18
18
|
| [Components](components.md) | Available controls, props and form composition |
|
|
19
19
|
| [Base component inventory](base-components.md) | Available primitives and controls in the base release |
|
|
20
20
|
| [Customization](theming.md) | Scoped dark foundations overrides and legacy theme boundaries |
|
|
21
|
-
| [Foundations](foundations.md) | Typed semantic tokens and neutral dark profile for 0.2.
|
|
21
|
+
| [Foundations](foundations.md) | Typed semantic tokens and neutral dark profile for 0.2.11 |
|
|
22
22
|
| [Agents](agents.md) | Installing and using the matching agent instructions |
|
|
23
23
|
| [Agent knowledge](agent-knowledge.md) | Versioned discovery, selected reads and preserved project guides |
|
|
24
24
|
| [FAQ](faq.md) | Compatibility, customization, updates and common problems |
|
|
25
25
|
| [Command palette](recipes/command-palette.md) | Compose Dialog and CommandList with host-owned actions |
|
|
26
26
|
| [Table bulk actions](recipes/table-bulk-actions.md) | Controlled cross-page selection and local confirmation |
|
|
27
27
|
| [Grouped form](recipes/grouped-form.md) | Shared tracks, semantic groups and optional fields |
|
|
28
|
+
| [Record management](recipes/record-management.md) | Search, filter and edit records without losing the working list |
|
|
29
|
+
| [Settings workspace](recipes/settings-workspace.md) | Group settings, validate a draft and save changes |
|
|
28
30
|
|
|
29
31
|
## Versions
|
|
30
32
|
|
|
31
|
-
This branch documents **version 0.2.
|
|
33
|
+
This branch documents **version 0.2.11**; source availability does
|
|
32
34
|
not establish npm publication. Use matching exact versions of the Flood packages. Documentation on `main` can describe later work; the
|
|
33
35
|
[release tags](https://github.com/tillwithered/flood.md/releases) preserve the
|
|
34
36
|
source and docs for each release. Installed `flood/DESIGN.md` takes precedence
|
|
@@ -30,13 +30,14 @@ translation may increase a control's height; do not hide overflowing labels.
|
|
|
30
30
|
|
|
31
31
|
## Keep labels close and groups distinct
|
|
32
32
|
|
|
33
|
-
|
|
34
|
-
`.5rem`
|
|
35
|
-
|
|
33
|
+
In a compact inline choice, keep the indicator and label together. The
|
|
34
|
+
component's default gap is `.5rem` at the reference root. In a settings list,
|
|
35
|
+
switches can share a trailing edge within a bounded column. Keep each label
|
|
36
|
+
and switch in one clickable row and check that the eye can follow the pair
|
|
37
|
+
across that row. See the [settings recipe](recipes/settings-workspace.md).
|
|
36
38
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
`gap="2"` for compatibility; choose `gap="4"` explicitly for a choice group:
|
|
39
|
+
For separate horizontal choices, `gap="4"` is a starting point. In a vertical
|
|
40
|
+
list, inspect the pitch created by the existing hit areas before adding a gap:
|
|
40
41
|
|
|
41
42
|
```tsx
|
|
42
43
|
<Inline gap="4" align="center">
|
|
@@ -181,13 +182,41 @@ explain a short form. For a necessary independent group use Fieldset with
|
|
|
181
182
|
legendSize="section"; the default label-sized legend remains appropriate for
|
|
182
183
|
choices. It preserves native fieldset semantics rather than adding a heading.
|
|
183
184
|
|
|
184
|
-
Named fields keep
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
185
|
+
Named fields keep their component-owned label/control gap. Pick the parent
|
|
186
|
+
spacing by reading the rendered relationships. In a quiet form, compare how
|
|
187
|
+
strongly each legend belongs to its first control and how clearly the next
|
|
188
|
+
section begins. In a dense filter bar, control height and shared alignment
|
|
189
|
+
already organize most of the row. Dialog supplies its own body inset.
|
|
188
190
|
|
|
189
191
|
Place four related short fields in one Grid columns={2} so their row edges align.
|
|
190
192
|
A short numeric value alone does not justify a narrower column in only one row;
|
|
191
193
|
long text fields can use a separate full-width row. Verify actual control edges
|
|
192
194
|
with long labels, optional content and 24px root text, not just Grid boxes.
|
|
193
195
|
See [Skills](skills.md) for the shipped hierarchy workflow.
|
|
196
|
+
|
|
197
|
+
## Review visible weight
|
|
198
|
+
|
|
199
|
+
Read the screen at its working size. Name the first thing to notice, the
|
|
200
|
+
content that belongs together, and the edges that should line up. Compare the
|
|
201
|
+
visible text and shapes alongside their boxes. A taller line box, a strong
|
|
202
|
+
divider, or a filled control can make two equal gaps read differently.
|
|
203
|
+
|
|
204
|
+
Choose the text role before its treatment. A short title may need more
|
|
205
|
+
weight or a wider measure. A paragraph that wraps poorly often needs a
|
|
206
|
+
different measure or line height. Review the actual script, digits and accents
|
|
207
|
+
before adjusting tracking. For comparisons, keep repeated values on shared
|
|
208
|
+
axes. [The Details of UI Typography](https://developer.apple.com/videos/play/wwdc2020/10175/)
|
|
209
|
+
|
|
210
|
+
Compare two treatments with the same content and viewport. Change one variable
|
|
211
|
+
at a time, then choose the closest existing token that preserves the reading
|
|
212
|
+
order. For example, in a Drawer compare a quieter description in the title
|
|
213
|
+
group with the same text given body weight. Then check the gap before the details
|
|
214
|
+
with a long title and with the description omitted.
|
|
215
|
+
|
|
216
|
+
The shared axes follow Müller-Brockmann's use of grids as a working tool. The
|
|
217
|
+
attention to letterforms and blank space draws on Ruder, and the comparison of
|
|
218
|
+
contrast and rhythm draws on Hofmann. These are Flood applications of those
|
|
219
|
+
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)
|
|
220
|
+
|
|
221
|
+
Recheck with wrapping, enlarged text, and the user's text spacing overrides.
|
|
222
|
+
Controls and content must stay usable when those values change. [W3C Text Spacing](https://www.w3.org/WAI/WCAG22/Understanding/text-spacing.html)
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Motion
|
|
2
|
+
|
|
3
|
+
Flood uses short motion to show where an interface changed. Motion follows the
|
|
4
|
+
component's own state and respects the operating system's reduced-motion preference.
|
|
5
|
+
|
|
6
|
+
[Try motion and reduced motion](/playground/motion).
|
|
7
|
+
|
|
8
|
+
| Event | Typical duration | What moves |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| Press and hover | 70–100 ms | Paint on actions, rows and options, plus a slight compression while holding a standalone control |
|
|
11
|
+
| Selection and disclosure | 100–160 ms | State paint, glyphs and revealed content |
|
|
12
|
+
| Menus and feedback arrivals | 180 ms | Opacity and small directional movement |
|
|
13
|
+
| Modal and drawer entrances | 240 ms | The arriving layer or its content |
|
|
14
|
+
| Brief dismissal where safe | 120 ms | A visual part with a reliable exit lifecycle |
|
|
15
|
+
|
|
16
|
+
Use `--flood-sys-motion-*` roles for Flood compositions. Set
|
|
17
|
+
`data-flood-motion="reduce"` on FloodRoot to also suppress component motion in
|
|
18
|
+
an application scope. This setting complements the system preference.
|
|
19
|
+
|
|
20
|
+
Focus, validation, semantics and state take effect immediately. Static content
|
|
21
|
+
and layout inherit behavior from their interactive owners. Sliders, drag,
|
|
22
|
+
resize and scrolling track input directly. Loading remains legible when its
|
|
23
|
+
indicator stops moving. Native layer dismissal is immediate where the browser
|
|
24
|
+
and React lifecycle remove its content together.
|
|
25
|
+
Floating toasts animate their message on arrival. Inline notices stay static
|
|
26
|
+
within the surrounding reading flow.
|
|
27
|
+
|
|
28
|
+
Use the versioned `workflow:motion` through the Flood CLI for implementation
|
|
29
|
+
and browser verification guidance.
|
|
30
|
+
|
|
31
|
+
## Component states
|
|
32
|
+
|
|
33
|
+
Each row lists components that share a motion owner. Compositions inherit the
|
|
34
|
+
behavior of their children. State updates and focus take effect immediately.
|
|
35
|
+
|
|
36
|
+
| Components | Motion and state behavior |
|
|
37
|
+
| --- | --- |
|
|
38
|
+
| `FloodRoot` | Applies the motion preference to its scope. Preference changes are immediate. |
|
|
39
|
+
| `Text`, `Heading`, `Kbd`, `VisuallyHidden`, `Blockquote`, `InlineCode`, `IconSlot`, `Label` | Static text and artwork. The containing control owns feedback. |
|
|
40
|
+
| `Stack`, `Inline`, `Surface`, `Divider`, `Container`, `Grid`, `AspectRatio`, `Section`, `Split`, `Center`, `Fieldset` | Stable layout. Children own any appearance or interaction feedback. |
|
|
41
|
+
| `PageHeader`, `AppShell`, `AppTopBar` | Titles, layout and scroll position stay stable during reflow. Actions, Sidebar and Drawer own their interaction feedback. |
|
|
42
|
+
| `ScrollArea`, `ResizablePanels`, `Slider` | Direct pointer tracking. Only scrollbar hover paint eases. Resize, scroll and slider positions stay under the pointer. |
|
|
43
|
+
| `Button`, `IconButton`, `Toggle`, `CopyButton` | Hover paint and short press compression. Toggle holds selected paint. Copy shows its result glyph without resizing the button. |
|
|
44
|
+
| `ButtonGroup`, `ToggleGroup`, `Toolbar`, `OverflowActions`, `BulkActionBar`, `Menubar` | Actions inherit Button and Menu feedback. Joined button surfaces keep their geometry. Bulk actions fade in when available. |
|
|
45
|
+
| `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 and truncates its row text to keep it on one line. Its toggle shows a filled keyboard focus state, with the system outline in forced colors. Focus, route and tree reflow update immediately. |
|
|
46
|
+
| `Link`, `Breadcrumb`, `Pagination`, `SkipLink`, `Steps` | Navigation is immediate. Button-style actions and step rows can ease their paint. Skip links appear immediately on focus. |
|
|
47
|
+
| `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. |
|
|
48
|
+
| `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. |
|
|
49
|
+
| `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. |
|
|
50
|
+
| `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. |
|
|
51
|
+
| `Calendar`, `RangeCalendar` | Day selection paint. Month and year changes keep the grid stable and respond immediately. |
|
|
52
|
+
| `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. |
|
|
53
|
+
| `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. |
|
|
54
|
+
| `CodeSnippet`, `Card`, `DataList`, `DataListItem`, `FileItem`, `FileList`, `AvatarGroup` | Embedded actions and avatars own motion. Reading order and record layout remain stable. |
|
|
55
|
+
| `Badge`, `DescriptionList`, `Table`, `Image`, `List`, `Figure`, `Metric`, `Timeline`, `ColorSwatch`, `FileMeta` | Static content. Changes to data, labels and supporting media render immediately. |
|
|
56
|
+
| `Sparkline` | Hover briefly strengthens the latest point and area. Data changes render immediately. |
|
|
57
|
+
| `Avatar` | Loaded image eases in within a fixed frame. Fallback text is immediately available. |
|
|
58
|
+
| `DataTable` | Selected row paint, chevron rotation and a short height transition for row details. Sorting, pagination and column resize update geometry immediately. |
|
|
59
|
+
| `Tooltip`, `Popover`, `Menu`, `ContextMenu`, `HoverCard`, `CommandPalette`, `Dialog`, `AlertDialog`, `Drawer`, `Sheet`, `ImagePreview` | Anchored entrances follow placement. Modal and edge panels have their own timing. Sheet uses the bottom Drawer entrance. Controls, focus, close and positioning retain their native behavior. |
|
|
60
|
+
| `Spinner`, `Skeleton`, `Progress`, `Meter`, `ToastRegion`, `UploadItem`, `UploadList` | Busy indicators and value fill. A floating toast enters as a card from its placement edge; an inline toast fades in place. Upload compositions inherit the progress and action recipes. Announcements and final values are immediate. |
|
|
61
|
+
| `Alert`, `EmptyState`, `StatusIndicator`, `ErrorSummary` | State and message changes are immediate. Embedded actions keep Button feedback. |
|
|
62
|
+
|
|
63
|
+
Menu, ContextMenu and title-only navigation flyouts fade in and out where
|
|
64
|
+
discrete top-layer transitions are supported. Dismissal releases focus and
|
|
65
|
+
pointer interaction immediately. When a sibling navigation flyout takes over
|
|
66
|
+
the same rail position, the outgoing panel yields immediately.
|
|
@@ -70,10 +70,19 @@ Accessibility, evidence and regression checks.
|
|
|
70
70
|
|
|
71
71
|
| Workflow | Use when | Skill source |
|
|
72
72
|
| --- | --- | --- |
|
|
73
|
+
| 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) |
|
|
73
74
|
| 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) |
|
|
74
75
|
| 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) |
|
|
75
76
|
| 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) |
|
|
76
77
|
|
|
78
|
+
## Motion
|
|
79
|
+
|
|
80
|
+
Component motion roles, transition recipes and reduced-motion verification.
|
|
81
|
+
|
|
82
|
+
| Workflow | Use when | Skill source |
|
|
83
|
+
| --- | --- | --- |
|
|
84
|
+
| 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) |
|
|
85
|
+
|
|
77
86
|
See [Workspace review](/docs/recipes/workspace-review) for a runnable form and file
|
|
78
87
|
drawer assembled with these workflows. Its source, ownership choices and host
|
|
79
88
|
checks are documented together.
|