@flood-md/agent 0.2.3 → 0.2.5

package/DESIGN.md

@@ -1,17 +1,17 @@
-# Flood design system · 0.2.3
+# Flood design system · 0.2.5
 
 Read project-root flood.json and installed declarations with this contract.
 The source bundle's SKILL.md routes to focused composition, accessibility,
 customization and verification references. Its routing matrix names prerequisites
 and sources of truth; flood/rules.json indexes observable checks. Read only the
-relevant reference. This expanded bundle belongs to 0.2.3; existing installations
+relevant reference. This expanded bundle belongs to 0.2.5; existing installations
 keep their matching guide set.
 
 React + TypeScript and Next.js App Router. Use this guide with matching installed
 Flood packages and flood.json. The source repository's release status does not
 grant permission to publish or assume a version is available on npm.
 
-This guide covers all 37 exports in 0.2.3 and their layout refinements. Confirm
+This guide covers the supported exports in 0.2.5 and their layout refinements. Confirm
 the matching installed declarations before using APIs absent from older versions.
 
 ## Connect
@@ -158,3 +158,116 @@ export function Profile() {
   );
 }
 ```
+
+
+0.2.5 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.5. Distinguish task completion from bounded measurements, preserve names/units, and select alert announcement priority explicitly.
+
+DescriptionList and Table are also available in 0.2.5. 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.5; 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.5)
+
+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.5)
+
+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.5
+
+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,7 +1,7 @@
 # @flood-md/agent
 
 Version-matched guidance for Flood React/Next.js projects. Read the installed
-contract before composing screens. The 0.2.3 reference bundle includes spacing
+contract before composing screens. The 0.2.5 reference bundle includes spacing
 guidance, routing and observable rules. These files grant
 no authority to modify external services.
 

package/manifest.json

@@ -53,7 +53,7 @@
       "kind": "reference"
     }
   ],
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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.3",
+  "version": "0.2.5",
   "type": "module",
   "description": "Versioned Flood design instructions for coding agents.",
   "license": "MIT",

package/references/accessibility.md

@@ -46,8 +46,10 @@ when a read-only field uses a dashed resting perimeter.
 External-label visibility: source Field/Fieldset hideLabel preserves the actual
 label/legend and accessible name while removing its visual row. RadioGroup,
 CheckboxGroup and SegmentedControl inherit it. Keep label/legend supplied and
-textual; do not hide interactive label content. Use it only where surrounding
-context supplies the visible meaning. Input/Textarea/Select/InputGroup configure
+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.
 
@@ -61,3 +63,17 @@ configurable. Provide a visible title and safe initialFocusRef when needed. Clos
 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

@@ -139,3 +139,131 @@ 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.
+
+NumberInput composes InputGroup/Input/IconButton for finite numeric values or null.
+Use Field for label and feedback, min/max/step for native validity and explicit
+translated increaseLabel/decreaseLabel for step actions. Do not replace it with a
+styled text box that loses numeric forms. Slider receives an array of one value or
+an ordered pair; use thumbLabels to distinguish bounds, preserve native keyboard
+controls and keep explanatory feedback visible. Range handles cannot cross.
+Both support controlled/uncontrolled state, form reset and read-only presentation.
+Available in 0.2.5; do not imply registry availability.
+
+Combobox is editable single selection from explicit option values. Use Field for
+its input name/description associations, never submit typed search text as an ID.
+Arrow keys move the active suggestion; Enter commits, Escape cancels the search.
+Use descriptive labels/keywords, keep disabled choices inert, and translate the
+list/clear/toggle/empty/validation messages. Read-only selection remains selectable
+for copying. Native forms/reset and required validity apply to the selected ID.
+Do not imply freeform values, async fetching, multiple selection or virtualization.
+
+Tag is label content with an optional named native removal action; it is not a
+status Badge or Toggle. The host owns removal/state and standalone focus recovery.
+Provide removeLabel for rich content and localization. MultiSelect composes Tag
+and the shared Combobox search/layer model with an array of selected option IDs.
+Never pass arrays to Combobox or submit search text as selected values. Use Field
+for associations/feedback. Preserve repeated form entries, reset and required
+selection validity. Disabled selected items stay selected through clear/remove;
+read-only blocks edits. Do not shrink touch targets to force tags into a row.
+Let tags wrap while the search editor and its suffix actions remain together.
+
+Keep selection-field chrome calm: Combobox/MultiSelect show only the chevron by
+default. Add clearable=true only when a separate clear-selection action is useful;
+individual MultiSelect tags already expose named removal actions.
+
+
+SearchInput and PasswordInput are field controls in 0.2.5.
+Compose them with Field and pass its control props. SearchInput uses native search
+editing and one clear action (clearable=true); the host owns filtering/submission.
+Read-only hides clear. PasswordInput has a single show/hide action with localized
+showPasswordLabel/hidePasswordLabel, controlled visible/onVisibleChange or initial
+defaultVisible. Read-only still allows reveal. Native refs, autocomplete and forms
+remain owned by the host. Do not add another suffix chevron or browser clear icon.
+
+
+FileInput (0.2.5) composes a native file input with Flood field geometry,
+IconSlot and one optional clear IconButton. Pass Field's render props for its
+accessible name/description/status. Native name, form, required, accept, multiple,
+capture and input ref remain available. onChange is a native React change handler;
+onFilesChange receives a new readonly File array for selection and clear. Do not
+pass value/defaultValue/readOnly; FileList belongs to the browser. Uncontrolled
+form reset clears the summary; cancelling the chooser keeps its prior selection.
+Localize placeholder and clearLabel. Long names truncate visually, and the host
+owns upload, file validation and progress. accept only guides the chooser.
+
+
+FileInput multiple selection exposes a collapsible file list with full names and
+localized file sizes (lang controls number formatting), and a count in the picker.
+Translate selectionLabel and removeFileLabel. Individual removal updates the native
+FileList through DataTransfer, then emits the same change callbacks as selection.
+Focus moves to the next/previous remove action, or back to the input when empty.
+clearable=false disables individual and global removal UI. In multiple mode, picking again appends files to the current selection; cancel
+preserves it. Repeated files are deduplicated by name, size, type, lastModified and
+relative path, without reading their contents. Single mode replaces its selection. The host remains responsible for upload.
+
+
+AlertDialog (0.2.5) is a concise confirmation, composed from Flood's
+native modal layer and Button. Supply title, description, trigger and onConfirm.
+Cancel receives initial focus; Escape cancels; outside clicks do not dismiss.
+Tab containment, background inertness, scroll lock and return focus reuse Dialog.
+Translate confirmLabel/cancelLabel. onConfirm runs before requesting close, while
+onCancel covers Cancel/Escape. Use open/onOpenChange for controlled state and
+confirmDisabled to disable confirmation. Callbacks are not awaited; the host owns
+async requests, pending UI and errors. Use Dialog for forms/complex content.
+
+
+Drawer (0.2.5) reuses Dialog's modal behavior with an edge-panel layout.
+side is logical start/end (default end) or top/bottom; size sm/md/lg sets the
+cross-axis extent to 20/26/34rem within the viewport. Vertical panels fill height,
+horizontal panels fill width. Use footer for host-owned actions; only body content
+scrolls with Flood ScrollArea. Header/close action/footer remain visible. Native
+ref, controlled open/onOpenChange, outside dismissal and initialFocusRef match
+Dialog. Translate closeLabel/title/description; reduced motion disables entry
+animation. Closing is immediate. There is no swipe/drag gesture or auto-save logic.
+
+
+The 0.2.5 separates floating surfaces from modal surfaces.
+Nine additional semantic roles bring the dark profile to 193 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.
+
+
+Version 0.2.5 expansion includes AvatarGroup/StatusIndicator/Figure/
+Blockquote/InlineCode/Metric/Timeline; NavigationList/Steps/Section/Split/Center/
+SkipLink; ListBox/PinInput/Rating/Dropzone/CharacterCount; CopyButton/ToastRegion.
+Compose these before inventing equivalent host wrappers. Read each generated
+component contract and docs/base-components.md. Keep collection IDs stable, form
+names explicit, labels localized, state meaning independent of color and visible
+content within relative geometry. Native chooser/clipboard/OTP semantics do not
+supply upload/auth/server logic. Toast queues, actions and navigation state remain
+host-owned. No third-party component implementation was introduced.
+
+
+Section headingLevel controls native h2–h6 semantics. Its independent headingSize
+uses the existing Heading roles (section/page/large/display), defaulting to section.
+Keep document hierarchy meaningful when changing visual emphasis.

package/references/verification.md

@@ -26,3 +26,5 @@ 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

@@ -37,7 +37,10 @@
       "verify": [
         "Rendered narrow/wide screen",
         "Intrinsic actions and responsive form parent",
-        "Close choice label and independent group spacing"
+        "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"
       ]
     },
     {