@flood-md/agent 0.2.8 → 0.2.10

package/dist/materials/component-upload-item.md

@@ -0,0 +1,52 @@
+# UploadItem
+
+A host-controlled upload row with explicit progress and applicable actions.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, UploadList, UploadItem } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <UploadList label="Uploads">
+        <UploadItem name="Brand guidelines.pdf" size={2400000} state="uploading" progress={45} />
+      </UploadList>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Queued/uploading can expose cancel; error/cancelled can expose retry; settled rows can expose remove.
+- Unknown progress is indeterminate. StatusIndicator and Progress remain distinct reused primitives; their row can wrap when the list container is constrained. No network or upload queue is built in.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `name` | `string` | `Required` |
+| `size` | `number` | `—` |
+| `mimeType` | `string` | `—` |
+| `format` | `string \| null` | `—` |
+| `thumbnail` | `ReactNode` | `—` |
+| `href` | `string` | `—` |
+| `download` | `boolean` | `—` |
+| `onPreview` | `() => void` | `—` |
+| `onRemove` | `() => void` | `—` |
+| `disabled` | `boolean` | `—` |
+| `labels` | `FileActionLabels` | `—` |
+| `formatSize` | `(bytes: number) => string` | `—` |
+| `state` | `"queued" \| "uploading" \| "success" \| "error" \| "cancelled"` | `Required` |
+| `progress` | `number` | `—` |
+| `error` | `string` | `—` |
+| `onCancel` | `() => void` | `—` |
+| `onRetry` | `() => void` | `—` |
+| `Native HTML props` | `Omit<Omit<HTMLAttributes<HTMLLIElement>, "children" \| "title">, "description">` | `Forwarded` |

package/dist/materials/component-upload-list.md

@@ -0,0 +1,40 @@
+# UploadList
+
+A named native list of host-controlled upload rows.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, UploadList, UploadItem } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <UploadList label="Uploads">
+        <UploadItem name="Brand guidelines.pdf" state="uploading" progress={45} />
+        <UploadItem name="Logo.svg" state="success" />
+        <UploadItem name="Cover.png" state="error" error="Connection interrupted" />
+      </UploadList>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Each row has its own state and stable host identity.
+- Cancellation, retry and removal callbacks are intents for the application.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `density` | `"compact" \| "comfortable"` | `—` |
+| `dividers` | `boolean` | `—` |
+| `label` | `string` | `Required` |
+| `Native HTML props` | `Omit<HTMLAttributes<HTMLUListElement>, "role">` | `Forwarded` |

package/dist/materials/component-visually-hidden.md

@@ -0,0 +1,37 @@
+# VisuallyHidden
+
+Nonvisual content with optional reveal when keyboard focus enters.
+
+Connect Flood once using [the installation guide](https://flood.md/docs/installation). Then import the components you use; no per-component add command is needed.
+
+## Example
+
+```tsx
+"use client";
+
+import { FloodRoot, Text, VisuallyHidden } from "@flood-md/react";
+import "@flood-md/react/styles.css";
+
+export function Example() {
+  return (
+    <FloodRoot>
+      <Text>Project updated.</Text><VisuallyHidden>Changes save automatically.</VisuallyHidden>
+    </FloodRoot>
+  );
+}
+```
+
+## Design notes
+
+- Content remains in the accessibility tree. Default is for noninteractive text only.
+- Use focusable for a skip link or another focusable descendant: the wrapper becomes visible while it contains focus. Supply visible focus styling on the actual control.
+- This is not aria-hidden, display:none or a conditional unmount. as accepts span/div.
+- Available in 0.2.4; use matching installed declarations.
+
+## API reference
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `as` | `"span" \| "div"` | `"span"` |
+| `focusable` | `boolean` | `false` |
+| `Native HTML props` | `HTMLAttributes<HTMLElement>` | `Forwarded` |

package/dist/materials/guide-agent-knowledge.md

@@ -0,0 +1,88 @@
+# Agent knowledge
+
+Flood 0.2.10 adds a versioned read-only catalog and reader. Use the CLI matching
+the project's flood.json; source availability does not prove npm publication.
+The same package sources build the website, CLI results and agent instructions.
+
+## Discover, then read
+
+```sh
+npx @flood-md/cli@0.2.10 info --json
+npx @flood-md/cli@0.2.10 catalog --kind workflow --group foundations
+npx @flood-md/cli@0.2.10 catalog --kind component --search table
+npx @flood-md/cli@0.2.10 read recipe:table-bulk-actions
+npx @flood-md/cli@0.2.10 read component:data-table
+```
+
+These commands return JSON and do not install dependencies, edit files, execute
+skill text or contact a Flood server. The package runner may fetch the CLI if
+it is not installed locally; keep its version deliberate. Existing project and
+agent instructions remain authoritative.
+
+info reports actual installed package versions, the configured guide version,
+framework detection, catalog identity and capability declarations. A version
+mismatch prevents catalog/read from serving an ambiguous guide train. A
+bundle-only result describes the CLI's bundle; it is not proof that the host has
+installed Flood or imported its stylesheet. doctor remains the installation check.
+
+## Material types and groups
+
+Stable IDs distinguish workflows, references, components, recipes, guides and
+semantic token records. Groups organize Foundations, Composition, Interaction,
+Data & feedback, Quality and existing Motion tokens. They are navigation labels;
+one task can use several groups. Current capability gaps are explicit in info.
+
+For example, page-transition workflows and additional foundation themes are not
+supplied. Existing motion tokens do not create a PageTransition export. Scoped
+brand overrides do not add a brand Button variant. Read reference:customization
+and the actual token records before changing semantic roles.
+
+## Bounded output and version identity
+
+catalog accepts --kind, --group, --search, --limit and --cursor. Search matches
+literal metadata case-insensitively; it is not model-based intent routing.
+The default limit is 12, maximum 50, and each metadata page is capped at 16 KiB.
+If truncated is true, follow nextCursor. A changed query or catalog invalidates
+that cursor. This remains bounded as the number of components increases.
+
+read accepts --offset and --length. Its default is 10,000 Unicode code points,
+maximum 40,000; follow nextOffset to finish a selected instruction. Related links
+are limited to 32 per read; use --links-offset with nextLinksOffset for more.
+Required prerequisites are separate from optional links. A workflow applying to
+many components does not require reading all of them.
+
+The reader checks schema, relationships, package version and selected content
+integrity. It reads only the selected body. The catalog is capped at 8 MiB and
+each material at 1 MiB. Limits fail explicitly; they are not silent omissions.
+The current protocol permits up to 16 semantic groups, 32 capability declarations,
+16 direct prerequisites and 256 related links per material. Prerequisite depth
+is limited to 32. Expanding these limits is a reviewed protocol decision, not a
+reason to delete safeguards when the catalog grows.
+
+## Customized project guides
+
+For material copied by init, read defaults to the existing project guide. The
+response identifies source=project, its hash and customized status. Other
+materials come from the matching package. Missing or linked project guides fail
+explicitly; they are not silently replaced by upstream instructions.
+
+Use --source package to compare canonical upstream content. It never overwrites
+customized files. flood/catalog.json is an installed snapshot, not executable
+configuration or permission to redirect reads. Instructions cannot authorize
+external actions that the user did not request.
+
+## API and contribution checks
+
+The Node API exports createKnowledgeReader and validateKnowledgeCatalog from
+@flood-md/agent, with matching TypeScript declarations. It has info(), list(query)
+and read(id, range) methods and performs no network operations. Pass an explicit
+package root when reading an isolated package; otherwise it uses its own package.
+
+Contributors edit canonical code, guides and knowledge.json annotations. Build
+regenerates content and hashes; stale/unmapped workflows, unknown imports,
+duplicate IDs, broken guidance links and prerequisite cycles stop compilation.
+The compatibility fixture records established public IDs. Growth tests exercise
+5,000 metadata entries, pagination, stale cursors, selected-content integrity and
+host customization. Clean tarball and browser checks verify the consumer boundary.
+None of these checks independently proves model routing accuracy, general
+accessibility or visual quality.

package/dist/materials/guide-agents.md

@@ -0,0 +1,96 @@
+# Using Flood with an agent
+
+Start with the host's instructions, package.json, flood.json and installed
+flood/DESIGN.md. Use matching package/CLI versions and declarations. A newer
+website example does not add APIs to an older installation.
+
+Version 0.2.3 includes the expanded skill, rules and reference bundle, including
+spacing guidance. Existing projects keep their installed files; compare new
+guidance before updating customized instructions.
+
+Version 0.2.9 adds ten specialized routed skills for stabilizing and
+composing the dark base. See [Skills](skills.md) for their applicability and full
+sources. The website index is generated from the same bundle metadata rather
+than a second handwritten skill catalog. Source additions do not update an
+already installed package; use the guide set matching your installation.
+
+Version 0.2.10 adds [versioned knowledge discovery](agent-knowledge.md):
+info reports installation context, catalog discovers compact metadata, and read
+loads a selected contract or workflow. The catalog includes typed recipes and
+semantic token records. Unknown capabilities and version mismatches are explicit;
+copied host guides remain project-owned.
+
+For discovery, give an agent [flood.md/llms.txt](https://flood.md/llms.txt).
+It identifies deployed status and entry points. Follow [installation](installation.md);
+preview the matching CLI's init with --dry-run before applying it within the user's
+scope. The CLI does not install an agent runtime or require a hosted Flood service.
+
+## Compose from primitives
+
+Flood includes the [Flood composition skill](../packages/agent/references/flood-composition/SKILL.md).
+The main Flood skill routes component, website and playground work to it. The
+manifest installs the full skill under
+`.agents/skills/flood-ui/references/flood-composition/SKILL.md`; it is loaded by
+that router rather than relying on independent discovery of nested skills.
+Existing installations must compare and merge new guidance deliberately.
+
+Reuse the existing library component; fix the relationship in its proper owner.
+If a reusable primitive is missing, build or extend it before the composition.
+Do not replace StatusIndicator with custom text, hide its anatomy, or duplicate
+a Badge/Progress/Dialog implementation just to make one layout fit.
+
+## Files and responsibilities
+
+| Project file | For whom / when | Prerequisite | Source of truth | What to check |
+| --- | --- | --- | --- | --- |
+| flood.json | Developer / agent, setup or upgrade | Existing React project | Exact installed release, framework and paths | Matching CLI doctor |
+| flood/DESIGN.md | Designer / developer / agent, every composition | Installed declarations | Version-matched UI contracts | Supported props and rendered states |
+| .agents/skills/flood-ui/SKILL.md | Skill-aware client, Flood UI work | Project context | Short task router | Load only the relevant reference |
+| references/routing.md in the skill folder | Human / agent, resolve ownership | Matching guide set | Responsibility and source matrix | Correct source and prerequisites |
+| references/composition.md in the skill folder | Screen/form author | User content and installed APIs | Composition workflow | Intrinsic actions, responsive forms, close choice labels |
+| references/spacing.md in the skill folder | Designer / developer / agent | Installed tokens and rendered host | Spacing and density decisions | Visible gaps, row pitch, wrapping and nonoverlapping touch targets |
+| references/accessibility.md in the skill folder | Control author / reviewer | Runnable host | Interaction and perception | Names, keyboard, focus, forms and contrast context |
+| references/customization.md in the skill folder | Theme author | Installed token manifest | Semantic override workflow | Resolved roles and affected states/surfaces |
+| references/verification.md in the skill folder | Developer / reviewer, completion | Host checks | Evidence requirements | Commands, manual results and gaps |
+| flood/rules.json | Human / agent / project tooling | Same bundle | Rule IDs, conditions, sources and checks | Evidence for each applicable rule |
+| flood/manifest.json | Installer / reviewer | Matching package | Explicit source → project-path mapping | Complete files; existing files preserved |
+| workflows.json in the skill folder | Agent / reviewer, task selection | Same installed bundle | Workflow applicability | Read relevant skills; applicability is not behavioral proof |
+
+Manifest `entry` and rule `guide` paths are package-source paths. Resolve them
+through `manifest.files`: each source maps to a target relative to the host
+project root. `installedEntry` names the installed skill directly. Manifest
+version and DESIGN header are checked by doctor alongside package alignment;
+customized guide contents are preserved and must be merged deliberately.
+
+The package publishes DESIGN.md, SKILL.md, rules.json, manifest.json and
+references/*.md. The website exposes the same sources under /agent/.
+The [routing reference](../packages/agent/references/routing.md) connects each
+question with its governing source and verification method.
+
+## Use only the context needed
+
+For a settings form, read DESIGN.md and SKILL.md, then composition/accessibility.
+Consult installed declarations for actual Field/Select props and read only those
+component pages. Before completion use verification. For a color-only change,
+load customization and the relevant token roles; unrelated guides stay unloaded.
+
+Clients supporting the skill-folder convention can discover it. Others can read
+it explicitly or link it from existing instructions. The installer preserves
+AGENTS.md; it does not configure clients or guarantee automatic discovery.
+
+The rules index is data, not an executable policy engine. It cannot make an agent
+obey guidance or certify accessibility. Host checks and Flood's repository
+verification supply evidence. Doctor checks package alignment and expected regular
+files; it does not parse CSS imports or assess visual quality/completed user flows.
+
+## Safe installation and upgrades
+
+Init refuses existing owned files and linked destinations before npm runs, then
+rechecks after installation. During upgrades compare new package sources with
+installed copies, merge deliberately and retain host requirements. Do not delete
+customized guides merely to make init succeed.
+
+Import @flood-md/react/styles.css once and compose new dark interfaces in
+FloodRoot. See [layout](layout.md), [components](components.md) and
+[customization](theming.md). Flood guidance governs UI use; it grants no authority
+to publish, delete data, transmit source or bypass the user's instructions.

package/dist/materials/guide-faq.md

@@ -0,0 +1,84 @@
+# Frequently asked questions
+
+## Does Flood use shadcn, Radix, Base UI or Tailwind?
+
+No. Flood's controls, CSS tokens and CLI are authored in this repository. React
+and browser-native form elements provide the underlying platform APIs.
+
+## Does it support Next.js?
+
+Yes. Import the global stylesheet in app/layout.tsx. Flood's React entry preserves
+its use-client boundary. Compose callbacks, state and Field's function child in
+your own client component. The integration fixture tests React 19 and Next.js App
+Router. Clean-package checks also exercise React 18.3 and 19 server rendering;
+the full interactive Next.js fixture uses React 19.
+
+## Is this the same installation model as shadcn?
+
+Flood currently installs versioned npm dependencies. It does not copy editable
+component source into your application or provide a source-file merge engine.
+Customize semantic tokens and component props; use source changes in a fork when
+you need behavior outside the public API.
+
+## Why is there no add button command?
+
+The base set ships together in @flood-md/react: ten foundation primitives and
+eight native controls. Import the components you need; see the
+[base component set](base-components.md). The CLI provides init, init --dry-run
+and doctor.
+
+## Which package managers work?
+
+The installer uses npm. Other package managers can install the library manually,
+but their integration is not currently covered by the installer tests.
+
+## The controls look unstyled. What should I check?
+
+Import @flood-md/react/styles.css once at the app root. Doctor checks package
+versions and instruction files, not the application's stylesheet imports.
+Wrap a new interface in FloodRoot to select the neutral dark foundations profile.
+Outside that scope, controls retain the legacy theme. Check project CSS overrides
+if the import and wrapper are already present.
+
+## Can I rerun init or use it as an updater?
+
+Init refuses existing flood.json or owned instruction files. It does not overwrite
+project instructions. Follow the [upgrade guide](installation.md) and
+review customized instructions when moving to a new release.
+
+## Does making the website source public grant server access?
+
+No. Source visibility does not grant GitHub write access, hosting credentials or
+server execution. Browser-delivered HTML, JavaScript and CSS are visible to users
+regardless of repository visibility. This does not make a website immune to bugs:
+deployment permissions, dependencies and server behavior still need review.
+Credentials belong in service secret stores, never in a public or private Git repo.
+
+## Does Flood require an account or send my project to a service?
+
+No Flood account, backend or telemetry is required. The installer contacts npm to
+download packages. Components run inside your application and do not send project
+contents to Flood.
+
+## Where do I report problems?
+
+Use [GitHub issues](https://github.com/tillwithered/flood.md/issues) for reproducible
+bugs and API requests. For vulnerabilities, follow [SECURITY.md](../SECURITY.md)
+and avoid posting exploit details or credentials in a public issue.
+
+## Which fonts and icons does Flood use?
+
+Flood's component implementations are original. Fonts and icon artwork have their
+own authors and licenses:
+
+| Asset | Where it is used | License |
+| --- | --- | --- |
+| [Inter](https://github.com/rsms/inter) | Locally bundled variable font in the React stylesheet | [SIL Open Font License 1.1](/licenses/inter.txt) |
+| [Lucide](https://github.com/lucide-icons/lucide) | Website icons and documentation examples | [ISC, with included Feather-derived MIT notices](/licenses/lucide.txt) |
+| [GitHub Primer Octicons](https://github.com/primer/octicons) | GitHub link mark on the website | [MIT](/licenses/github-mark.txt) |
+
+The React component package does not depend on an icon pack. IconSlot and
+IconButton accept SVG artwork from the host. Examples importing `lucide-react`
+require that optional dependency in your project; you may substitute your own
+icons. Preserve the corresponding license notices when redistributing assets.
+The full Inter font provenance and license accompany the installed package.

package/dist/materials/guide-foundations.md

@@ -0,0 +1,232 @@
+# Foundations tokens · 0.2.5
+
+This guide describes the **0.2.5** foundation exports. Keep Flood packages at
+matching exact versions. Existing 0.1.1 installs use their earlier token contract.
+
+Foundations separates fixed reference values (`ref`) from semantic roles (`sys`).
+The compiler also supports component aliases (`comp`) and isolated experiments
+(`exp`); no component-specific tokens are shipped in this first profile.
+
+The 0.2.3 neutral dark profile has 168 public semantic roles. Five roles added
+since 0.2.2 define scrollbar size, inset, minimum
+thumb length and thumb/rest-hover colors. Geometry uses rem; the viewport stays
+natively scrollable and overlay tracks reserve no layout gutter. Version 0.2.2 adds
+`sys.type.display.*` (5.5rem size, 1.12 line height, 500 weight, -.04em tracking)
+for marketing headings, `sys.type.lead.*` (1.375rem, 1.45, 400, -.01em) for
+supporting marketing copy, and `sys.font.mono` for code. Existing product typography
+retains its metrics. Responsive page composition remains the host's responsibility.
+
+## Use the neutral dark profile
+
+```tsx
+import "@flood-md/tokens/foundations.css";
+
+<section data-flood-foundations="neutral" data-flood-theme="dark">
+  <p className="example">Content</p>
+</section>;
+```
+
+```css
+.example {
+  color: var(--flood-sys-color-content-default);
+  background: var(--flood-sys-color-surface-canvas);
+}
+```
+
+Both attributes belong on the same scope element. This opt-in token stylesheet
+defines tokens and `color-scheme`; React components adopt these roles inside
+`FloodRoot` when the React stylesheet is imported. It does not enable an
+incomplete light theme. The preset and theme are
+separate dimensions. Only `neutral` + `dark` is currently supplied.
+
+## Inspect names and decisions
+
+```ts
+import { tokenNames, type TokenName } from "@flood-md/tokens/foundations";
+
+const role: TokenName = "sys.color.content.default";
+const cssVariable = tokenNames[role]; // --flood-sys-color-content-default
+```
+
+`foundations.manifest.json` describes public roles, types, status, usage limits,
+resolved values, aliases and dependencies for each supplied context. Internal
+reference tokens are absent from the TypeScript lookup and are not listed as
+public manifest entries; alias/dependency metadata can still name their IDs.
+`neutral.dark.tokens.json` is a resolved diagnostic DTCG document including the
+internal reference graph's values. Internal names are not customization promises.
+
+The dark profile covers surfaces, content, filled primary/subtle actions,
+contextual ghost actions, field and feedback colors, focus, typography, spacing,
+radii, control sizing, motion and local stacking levels. Subtle content is for
+short supplementary metadata, not a universal small-body-text color or an
+automatic APCA pass. Required small helper text uses `sys.color.content.helper`.
+
+### Role families
+
+All IDs below have the `sys.` prefix; CSS names replace dots with hyphens and
+prepend `--flood-`. The generated typed lookup is the complete contract.
+
+| Family | Roles |
+| --- | --- |
+| `font` | `sans` (Inter, Arial, sans-serif), `mono` |
+| `type` | `display`, `lead`, `large`, `page`, `section`, `body`, `compact`, `label`, `helper`, `control`; each has `size`, `line-height`, `weight`, `tracking` |
+| `space` | `0`, `1`, `2`, `3`, `4`, `6`, `8`, `12`; one step = .25rem |
+| `radius` | `field` 1rem, `block` 1.5rem, `surface` 2rem, `action` pill, `indicator` .375rem |
+| `control` | `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`; each has `height`, `text-size`, `line-height`, `padding-inline`, `icon-size`, `gap` |
+| `size` | `touch`, `choice`, `switch-width`, `switch-height`, `switch-thumb`, `indicator.sm/md/lg`, `keycap.sm/md/lg`, `container.sm/md/lg`, `grid.min-item` |
+| `color.action` | `primary`, `subtle`, `on-surface`, `ghost`; each has `rest`, `hover`, `pressed`, `content`, `disabled`, `disabled-content`; destructive action content has its own `danger.content` |
+| `color.field` | `background`, `border`, `boundary`, `content`, `placeholder`, `disabled`, `disabled-content` |
+| `color.feedback` | `error`, `success`, `warning`, `info` |
+| `color.selection` | `background`, `content` |
+| `focus`, `stroke` | Focus width/offset and decorative stroke width; independent of field validation |
+| `scrollbar` | `size`, `inset`, `min-thumb`; thumb colors live under color.scrollbar |
+| `color` | Surface/content, decorative border/divider, accent, focus, loading placeholder, indicator track/fill/accent and scrollbar rest/hover |
+| `motion` | `duration-fast`, `duration-normal`, `duration-reduced`, `easing` |
+| `layer` | `base`, `sticky`, `popover`, `modal`, `toast` |
+
+### Inter typography
+
+Size equivalents assume a 16px root for illustration. Flood does not set the
+host's root font size. Sizes use rem, line heights use ratios and tracking uses
+em. Font weights are 400/500. The React stylesheet bundles the Inter variable
+normal/italic fonts and their SIL Open Font License; it loads locally from the installed package.
+The token-only stylesheet does not load fonts: token-only consumers supply
+their own font setup with Latin/Cyrillic coverage as needed. Fallback metrics
+can differ.
+
+| Role | Size / line height | Weight | Tracking |
+| --- | --- | --- | --- |
+| display | 88 / 98.56 | 500 | -.04em |
+| lead | 22 / 31.9 | 400 | -.01em |
+| large | 32 / 40 | 500 | -.02em |
+| page | 24 / 32 | 500 | -.02em |
+| section | 20 / 28 | 500 | -.015em |
+| body | 16 / 24 | 400 | -.01em |
+| compact | 14 / 20 | 400 | -.01em |
+| label | 13 / 18 | 400 | -.01em |
+| helper | 12 / 18 | 400 | -.01em |
+| control | 14 / 20 | 500 | -.005em |
+
+Control heights are 24/28/32/40/44/48/56px equivalents. Their icon sizes are
+14/16/16/20/20/24/24px equivalents. These are minimum visual heights, not fixed
+clipping boxes. Touch target size, neighboring targets, long translations and
+increased text spacing require separate checks. Small controls are not ordinary
+text-field defaults.
+
+### Boundaries, focus and motion
+
+Version 0.2.3 uses the quiet `color.field.border` (#383838), matching the
+container-outline tone, for ordinary Input, Textarea, Select, unchecked choices,
+Switch and outline Button borders. It is one uniform perimeter, with no extra
+bottom edge or inset contour. The stronger `color.field.boundary` (#8a8a8a)
+remains available for an explicit contrast requirement; it is not the default.
+
+The quiet outline and field fill do not reach 3:1 against neighboring dark
+surfaces. This visual profile therefore does not establish WCAG 1.4.11 compliance
+for controls whose recognition depends on those signals. Preserve labels and
+evaluate the complete host composition; use a stronger role when required.
+Text contrast and APCA guidance remain separate from outline styling.
+
+A host can opt into stronger fields without overriding the independent focus role:
+
+```css
+/* Import after the Flood stylesheet; apply this attribute to FloodRoot. */
+.flood-root[data-control-contrast="strong"] {
+  --flood-sys-color-field-border: var(--flood-sys-color-field-boundary);
+}
+```
+
+Error, selected and focus
+states need semantic markup and a visible cue beyond color where applicable.
+
+Focus uses `focus.width` 2px and `focus.offset` 0px. `color.focus.ring` currently
+uses provisional pink #ff5ca8; it is configurable and is not a finalized brand
+palette. It must remain visible when error or selected styles are present.
+Color-pair tests cover supplied dark surfaces; these are not a whole-component
+WCAG or APCA conformance claim. Validate text role, size and weight together.
+
+For example, APCA `apca-w3` 0.1.9 gives white text on canvas Lc −106.77,
+helper #ededed on canvas Lc −95.00 (overlay: −91.00), and subtle #b2b2b2 on
+overlay Lc −55.54. These values do not certify the 12px/400 helper recipe:
+that version's font lookup recommends approximately 15.5px at weight 400 for
+Lc 95. Small helper text is a compact supporting role; provide readable main
+instructions and validate the actual content, device and enlargement behavior.
+Do not use subtle text or feedback accent colors for small required instructions
+merely because a WCAG color-pair calculation passes.
+
+Motion values are an initial interaction recipe: 100ms fast, 160ms normal,
+0ms reduced, with state easing. Consumers must apply the reduced value under
+`prefers-reduced-motion: reduce` and avoid relying on motion to convey state.
+Layer values express local order only; they do not implement portals, trapping
+focus, dismissal, scroll locking or an overlay stack.
+
+## Override and scope
+
+Override a public `sys` variable on its scope element, using inline styles or a
+stylesheet loaded afterward. Aliases remain CSS `var()` references. Nested
+scopes repeat both attributes so dependent aliases resolve against the nested
+values rather than inheriting already computed aliases from the parent.
+
+Arbitrary descendant overrides without a new scope are not supported. Portal
+containers must explicitly receive the same scope attributes and overrides.
+Changing an internal `ref` value is useful for diagnostics but not a stable API.
+
+## Source and compiler profile
+
+Only `packages/tokens/src/tokens.json` authors values. Its versioned Flood
+envelope contains `legacy`, `sets.shared`, `sets.palette`, `sets.theme` and
+`presets`. This envelope is not itself a DTCG Format document. Sets contain
+nested tokens with explicit `$type`, `$value`, `$description` and `md.flood`
+metadata. Build artifacts are generated and must not be edited.
+
+The first compiler profile supports sRGB color, nonnegative px/rem dimension,
+signed em dimension (for tracking),
+ms/s duration, finite number, numeric fontWeight, fontFamily and cubicBezier.
+Aliases refer to whole tokens using `{sys.color.content.default}` syntax.
+Composite types, JSON Pointer references, group inheritance, density modifiers,
+other color spaces and the full DTCG Resolver API are not supported; unsupported
+input fails instead of being silently coerced. This is not a full DTCG
+implementation or a claim of accessibility conformance.
+
+Build rejects missing/cyclic references, mismatched types, overlapping sets,
+invalid names and CSS-name collisions, disallowed layer dependencies,
+cross-component aliases, and stable-to-experimental dependencies. All supplied
+contexts must expose the same public role/type contract. Palette/reference
+values are fixed; themes choose roles instead of changing reference values.
+
+## Compatibility
+
+Existing `@flood-md/tokens` JSON and `tokens.css` retain their shared/light/dark
+contract and `--flood-*` names. Existing React controls outside `FloodRoot` keep
+using those tokens; old custom overrides continue to apply there. Inside
+`FloodRoot`, the dark foundation roles control the component recipe. Legacy
+overrides do not automatically override separately scoped foundation roles.
+
+Version 0.2.2 adds these exports without replacing an existing npm version.
+Publication must be verified separately; source version numbers are not proof.
+
+
+Version 0.2.5 adds twenty-five semantic roles, bringing the dark profile
+to 193 roles. Existing role values remain unchanged:
+
+- sys.color.accent.content and sys.color.loading.placeholder separate accent text
+  and loading fills from focus and action states.
+- sys.color.indicator.track/fill/accent and sys.size.indicator.sm/md/lg control
+  bounded indicators without borrowing control or focus roles.
+- sys.color.action.danger.content styles destructive actions independently from
+  validation messages and keyboard focus.
+
+- sys.size.keycap.sm/md/lg provide independent relative heights for keyboard hints.
+
+- sys.size.container.sm/md/lg and sys.size.grid.min-item supply relative layout bounds.
+
+
+The 0.2.5 separates floating surfaces from modal surfaces.
+The floating material uses nine of those new semantic roles; previous token
+values remain intact. surface.floating is the opaque fallback;
+surface.floating-translucent, border.floating, selection.floating, shadow.floating
+and effect.floating blur/saturation/shadow-offset/shadow-blur define the floating
+material. Select, Combobox, MultiSelect, Menu, Popover and Tooltip share it; Dialog
+and Drawer retain surface.overlay. Backdrop filtering is progressive enhancement;
+reduced transparency uses the opaque fill and forced colors use system colors.
+Keep text opaque and evaluate it against the actual composited background.