@momoi-labs/kiso 0.9.0 → 0.11.0

package/kiso/docs/components/README.md

@@ -12,6 +12,8 @@ behavioral reference where one exists.
 - [Card](card.md): Groups related content and actions with visual separation.
 - [Checkbox](checkbox.md): Toggles an option in a list or selects multiple values.
 - [ChipInput](chip-input.md): Collects several structured values in one field, each with its own options.
+- [Form](form.md): Composes fields and explicit submission actions in a native form.
+- [FormActions](form-actions.md): Groups form actions and optional feedback, with inline or sticky placement.
 - [FormField](form-field.md): Composes Label, a form control, HelperText, and ValidationMessage with consistent ID and ARIA wiring.
 - [HelperText](helper-text.md): Provides persistent, non-error context for a form control.
 - [IconButton](icon-button.md): Triggers a compact icon-only action with a required accessible name.
@@ -24,11 +26,17 @@ behavioral reference where one exists.
 - [Switch](switch.md): Changes one immediately applied boolean setting.
 - [Textarea](textarea.md): Collects multi-line free-form text.
 - [ThemeSelector](theme-selector.md): Chooses between following the system colour scheme, forcing light, or forcing dark.
+- [AccentSelector](accent-selector.md): Chooses which accent the interface uses: violet, terracotta, teal, cobalt, or nocturne.
 - [Tooltip](tooltip.md): Adds nonessential pointer or keyboard context as progressive enhancement.
 - [ValidationMessage](validation-message.md): Explains a field-level validation error and how to fix it.
 
 ## Data
 
+- [Chart](chart.md): Framed lines and stacked areas with synchronized inspection and exact values.
+- [ChartLegend](chart-legend.md): Tabular series summaries.
+- [Meter / Progress](meter.md): Measurements against limits and task completion.
+- [BarGauge](bar-gauge.md): Labelled bars on a shared scale.
+
 - [CommandPalette](command-palette.md): Searches and runs global actions or navigation from a keyboard-first overlay.
 - [Dot](dot.md): Adds a decorative status mark beside readable text.
 - [DropdownMenu](dropdown-menu.md): Presents contextual actions anchored to a specific object or trigger.
@@ -38,10 +46,16 @@ behavioral reference where one exists.
 - [Search](search.md): Filters visible content such as a list or table.
 - [Sparkline](sparkline.md): Draws the shape of one metric series at cell size.
 - [Stat](stat.md): Presents a named metric with optional change and context.
+- [StepBar](step-bar.md): Summarises a run as one segment per step, coloured by state.
+- [StepList](step-list.md): Lists a run's steps with a state, a label, a timing, and an output.
 - [Table / DataTable](table.md): Presents structured records with optional sorting, selection, filtering, and pagination.
 
 ## Navigation and structure
 
+- [Disclosure](disclosure.md): Native collapsible sections.
+- [TimeRangeControl](time-range-control.md): Presets and exact UTC collection windows.
+- [DashboardGrid](dashboard-grid.md): Responsive twelve-column panel layout.
+
 - [AppShell / ApplicationShell](app-shell.md): Provides low-level columns or the complete shared application frame (sidebar console or top-bar surface).
 - [BrandMark](brand-mark.md): Decorative letter or icon beside a product name.
 - [Breadcrumb](breadcrumb.md): Shows the current location within a hierarchy.
@@ -63,6 +77,8 @@ behavioral reference where one exists.
 
 ## Required compositions
 
+- [Form](form.md) with explicit submission includes fields and [FormActions](form-actions.md).
+
 - [FormField](form-field.md) composes [Label](label.md) + [Input](input.md) (or another form control) + [HelperText](helper-text.md) + [ValidationMessage](validation-message.md).
 - [ApplicationShell](app-shell.md) composes [Sidebar](sidebar.md) + [Navigation](navigation.md) + [Header](header.md) + page content, or a top-bar-only frame with brand in [Header](header.md).
 - [Header](header.md) composes [Link](link.md) + [IconButton](icon-button.md) + optional [DropdownMenu](dropdown-menu.md).

package/kiso/docs/components/accent-selector.md

@@ -0,0 +1,136 @@
+# AccentSelector
+
+## Purpose
+
+AccentSelector chooses which accent the interface uses: violet, terracotta,
+teal, cobalt, or nocturne. It is the only sanctioned control for that choice. The theme
+(light, dark, system) is a separate axis with its own control,
+[ThemeSelector](theme-selector.md); the two compose.
+
+## The five values
+
+| Value | Meaning | `data-accent` on `<html>` |
+| --- | --- | --- |
+| `violet` (default) | The violet ink and fill on the warm neutrals. | Either no attribute or `data-accent="violet"`. |
+| `terracotta` | Same roles, hue turned to terracotta. Neutrals unchanged. | `data-accent="terracotta"` |
+| `teal` | Same roles, hue turned to teal. Neutrals unchanged. | `data-accent="teal"` |
+| `cobalt` | Same roles, hue turned to cobalt. Neutrals unchanged. | `data-accent="cobalt"` |
+| `nocturne` | The marketing site's palette: cool slate neutrals under the violet ink. | `data-accent="nocturne"` |
+
+The attribute may also sit on a container, in which case only that subtree
+takes the accent. A nested `data-accent="violet"` resets to the default. See
+[Accents](../tokens.md#accents) for what the accent does and does not change.
+
+An application that offers fewer accents passes the subset it supports; the
+control does not have to show all five.
+
+## Persistence
+
+- An explicit choice persists under the key `kiso-accent`, with the value
+  `violet`, `terracotta`, `teal`, `cobalt`, or `nocturne`.
+- Read the stored value in a blocking inline script in `<head>`, before first
+  paint, and apply it as `data-accent`. Anything later flashes.
+- Storage may be unavailable. Wrap reads and writes so a failure degrades to
+  `violet` rather than throwing.
+- An application with a fixed accent does not render the control at all; it
+  sets the attribute once, in the document.
+
+## Anatomy
+
+1. **Row label**: the word "Accent", on the left.
+2. **Pills**: one per value, on the right, as a group. Each pill is a dot in
+   that accent's `primary` fill followed by the accent's name.
+3. **Preview**: below the row, one panel that shows the *selected* accent
+   applied: a sidebar strip with a current-item marker, a heading, a link, a
+   primary and a secondary button, and a selected row.
+
+| Value | Pill | Accessible name |
+| --- | --- | --- |
+| `violet` | violet dot, "Violet" | "Violet" |
+| `terracotta` | terracotta dot, "Terracotta" | "Terracotta" |
+| `teal` | teal dot, "Teal" | "Teal" |
+| `cobalt` | cobalt dot, "Cobalt" | "Cobalt" |
+| `nocturne` | nocturne dot, "Nocturne" | "Nocturne" |
+
+The pill names the accent, so no hover is needed to tell which is which. The
+preview answers the choice: it is decorative and hidden from assistive
+technology, because the names already carry the meaning. Each pill and the
+preview carry their own `data-accent`, so their colours resolve under that
+accent with no inline values.
+
+The preview may be omitted where the row is inline chrome, such as a header
+toolbar. In a settings card it is always present.
+
+## Layout
+
+A configuration row directly below the Theme row in the same card, with the
+preview spanning the row's width beneath it. See
+[Settings](../patterns/settings.md#theme).
+
+```text
+Theme                                   [ ▣ ][ ☀ ][ ☾ ]
+Accent      (● Violet)(● Terracotta)(● Teal)(● Cobalt)(● Nocturne)
+                     ┌──┬──────────────────────────────────┐
+                     │  │ ▬▬▬▬▬▬                           │
+                     │▬ │ ▬▬▬                              │
+                     │  │ [primary] [secondary]            │
+                     │  │ ░░░░░░░░░░░░░░░░ selected        │
+                     └──┴──────────────────────────────────┘
+```
+
+Narrower than 360px (a sidebar footer), the label stacks over the pills and
+the pills form a two-column grid, so no name wraps mid-word.
+
+## Tokens
+
+Pill: height `--size-control-xs`, radius `--radius-full`, border
+`--color-border`, fill `--color-card`, text `--color-muted-foreground` at
+`--type-size-label`, dot `--spacing-md` square in `--color-primary`.
+
+Selected pill: border `--color-primary`, fill `--color-accent-surface`, text
+`--color-foreground` at `--type-weight-medium`. The pill is outlined and
+tinted, not filled with `--color-primary`: the fill is already on the dot,
+and a solid pill would compete with the page's actual primary action.
+
+Preview: 120px tall, border `--color-border`, radius `--radius-lg`, canvas
+`--color-background`, strip `--color-sidebar`, marker and link `--color-link`,
+buttons `--color-primary` and `--color-card` with `--color-border-strong`,
+row `--color-selected`. Transitions on `--motion-duration-fast` /
+`--motion-easing-standard`.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | The offered options, exactly one selected; the preview shows it. |
+| hover | Unselected pill takes `--color-accent-surface` and `--color-foreground`. |
+| focus | Visible ring using `--color-ring`. Never remove it. |
+| selected | Outlined and tinted pill as above, plus the accessible selected state. The preview repaints at once. |
+| disabled | Not a state. The accent is always changeable where the control is shown. |
+
+There is no loading state. The change is local and instant; do not wait on a
+server round-trip to repaint, and do not show a Toast for it.
+
+## Accessibility
+
+- A group of mutually exclusive options with exactly one selected, each named
+  by its visible text.
+- The preview is `aria-hidden`; it repeats what the pill already says.
+- Announce the selection, not the resulting colours.
+- Every accent passes the same [AA gate](../tokens.md#aa-gate) as the default,
+  so the control does not need to warn about contrast.
+
+## When NOT to use
+
+- A free colour picker. Kiso has five accents; a product colour that is not
+  one of them is a token proposal, not an option.
+- A way to mark status or severity. Red, amber, and green are not accents for
+  that reason: a primary button in the danger hue reads as destructive.
+- Per-user branding inside a single product. One accent per product, or per
+  product area, chosen by the product.
+
+## Related
+
+- [tokens](../tokens.md#accents): what an accent changes and how it is built.
+- [ThemeSelector](theme-selector.md): the other appearance row.
+- [Settings](../patterns/settings.md#theme): where the row lives.

package/kiso/docs/components/bar-gauge.md

@@ -0,0 +1,29 @@
+# BarGauge
+
+## Purpose and anatomy
+
+Compare labelled measurements on horizontal bars with a value column.
+Each row composes [Meter](meter.md). All rows share a positive finite `max`
+and start at zero. Give the group a descriptive `label`, including its unit.
+Use [Chart](chart.md) when the task requires history.
+
+## Data, states, and behavior
+
+Rows have a stable key, label, and numeric or null value. `formatValue` applies
+the same unit and precision to every known value. Preserve row order across
+refreshes so a reader can compare changes. Bars clip at their bounds while
+text retains the actual number. A missing row value reads "Not collected";
+zero draws an empty track. An empty group reads "No measurements."
+
+## Accessibility
+
+The group has an accessible name; each measured row has Meter semantics and
+its own name and value text. Labels and numbers remain visible. There is no
+hover requirement, animation, or keyboard interaction. Wrap long labels and
+keep values aligned. Color does not encode the identity of a row.
+
+## Tokens and implementation
+
+Use Meter's track and fill tokens, `--spacing-md` between rows, and
+`--spacing-sm` within each row. No separate charting or Radix primitive is
+required. The old `.bars` vertical mini-bars are unrelated and stay compatible.

package/kiso/docs/components/card.md

@@ -188,3 +188,9 @@ No Radix Card primitive. Structure follows shadcn
 
 Ignore shadcn's invitation to hard-code spacing utilities. Card spacing
 consumes `--spacing-md`, `--spacing-lg`, or `--spacing-xl` only.
+
+## Form submission
+
+Use [FormActions](form-actions.md) for form submission controls and feedback.
+It can replace CardFooter at the bottom of a form inside a Card. Do not nest
+the two footers. CardFooter remains a general content-and-actions container.

package/kiso/docs/components/chart-legend.md

@@ -0,0 +1,42 @@
+# ChartLegend
+
+## Purpose and anatomy
+
+A native summary table for a [Chart](chart.md), available without hovering.
+Each row has the series' numbered label and stroke sample, then min, max,
+arithmetic average, and current. The visible caption names the metric and unit.
+
+## Data and states
+
+Accept the same `data` and `series` as the chart. Keep ordering and slots
+identical. Min, max, and average use finite measurements only. Current is the
+measurement at the final timestamp. Missing statistics read "Not collected";
+zero remains zero. An empty window retains the named series and headers.
+
+`formatValue` controls all summary cells. Use one unit and precision across
+the table. The chart's exact-values table preserves unrounded source data.
+The legend alone is a summary, not a replacement for the full sample table.
+
+## Accessibility and behavior
+
+Use native table, caption, column headers, and row headers. Numeric cells align
+to the end with tabular figures. By default rows are informational. With `onHighlightSeriesChange`, series
+labels become buttons with pressed state from `highlightSeries`. Selection
+emphasizes a series without hiding values. The table scrolls horizontally inside its frame at narrow
+widths. Numbered labels, highlighting, and the exact sample table supplement color.
+
+## Tokens and implementation
+
+Text uses `--color-foreground` and `--color-muted-foreground`. Borders use
+`--color-border`; spacing uses `--spacing-xs` and `--spacing-sm`. Series
+swatches consume the same five semantic chart roles as Chart. There is no
+Radix primitive; use a native table.
+
+## Display forms
+
+`variant="table"` is the default. `inline` wraps series labels and current
+values into a short row. `sidebar` places them in a column beside the plot,
+falling below it on narrow screens. Both use native description lists.
+`activeTimestamp` selects the sidebar sample, otherwise it shows the last
+sample. `formatTime` formats its timestamp. A missing measurement stays
+"Not collected". Sidebar changes use a polite live region.

package/kiso/docs/components/chart.md

@@ -0,0 +1,120 @@
+# Chart
+
+## Purpose
+
+Read several metric series across a collection window. pg-probe needs to
+correlate CPU, memory, disk, and database activity at the same instant.
+[Issue #93](https://github.com/momoi-labs/blueprint/issues/93) records that need.
+Use [Sparkline](sparkline.md) for a small, single-series trend.
+
+## Anatomy and forms
+
+A named figure contains axes, horizontal grid lines, a plot, an inspection
+readout, [ChartLegend](chart-legend.md), and a disclosure of exact samples.
+`line` is the default. `stacked-area` shows nonnegative contributions to a
+total. No gradients, curves that overshoot observations, or animation.
+
+One to five series share a unit and timestamp axis. Put the unit in the figure
+label, such as "CPU by state (%)". Give each series a unique key and label.
+An optional slot from 1 to 5 fixes its color and numbered label across
+panels. Slots must be unique within a chart. Keep ascending slot order in stacks. Never encode health with a slot.
+
+In standard layout, `height` defaults to 200 pixels. Width follows the parent. Axes and their labels
+remain visible. `min` and `max` establish comparable scales across panels;
+otherwise lines use their extent and stacks start at zero. Stacks reject
+negative values. Use lines for signed data.
+
+## Data and gaps
+
+`data` contains `{ timestamp, values }`, where timestamps are epoch
+milliseconds in strictly increasing order. Supply every expected collection
+timestamp, including slots the collector missed. Values are keyed by series.
+A null, absent, or nonfinite measurement is unavailable, never zero. The
+component does not infer a sampling interval or interpolate missing samples.
+
+Lines break at gaps. A stack breaks across all series when any contribution
+is missing, because its total is unknown. The readout and tables retain known
+contributions at that timestamp. An isolated sample draws a point.
+
+The summary ignores missing samples for min, max, and arithmetic mean. Current
+means the final timestamp, including an unavailable value. It never silently
+substitutes an older sample. Statistics describe the supplied window only.
+
+## Interaction and accessibility
+
+The figure has a visible caption and an accessible name. Tab focuses the plot;
+Left and Right inspect adjacent samples through Recharts' accessibility layer.
+Pointer hover and touch inspect the same readout. The floating readout or sidebar names the
+selected timestamp and every series, including "Not collected" values.
+
+Pass the same `syncId` to related charts to synchronize by timestamp. Products
+must supply the same expected timestamp grid and window to that group. Array
+positions alone do not establish correspondence. Panels retain their own
+series and scales.
+
+Series use continuous strokes. Numbered labels, per-series highlighting,
+and the exact table provide identification beyond color. Select a legend
+label with pointer, touch, Enter, or Space to highlight that series; select
+it again to clear. The active label is underlined and exposes `aria-pressed`.
+Other series stay in the plot and in every readout. The
+"View exact values" disclosure exposes every sample as a native table, with
+full UTC timestamps and unrounded source numbers. Include units in the chart
+label; formatters change display text, never the exact table. Scrolling stays
+inside the table at narrow widths.
+
+Tab reaches the exact-values summary. Enter or Space opens it. No essential
+information requires hover, color discrimination, animation, or a live
+announcement on every background refresh. Keep series labels descriptive.
+
+## States
+
+- Empty or wholly unavailable data: retain the caption, summary, exact table,
+  and plot height; show "No collected samples in this window."
+- Partial collection: draw gaps and preserve the available numbers.
+- One sample: show a point and the tables.
+- Loading: compose a [Skeleton](skeleton.md) at the expected plot height.
+- Error: compose an [Alert](alert.md) with the cause and retry action. Label
+  retained data as stale. An empty chart is not an error message.
+
+## Tokens and implementation
+
+Series use `--color-chart-1`, `--color-chart-2`, `--color-chart-3`,
+`--color-chart-4`, and `--color-chart-5`. Axes use
+`--color-muted-foreground`; grid lines use `--color-border`; the crosshair
+uses `--color-border-strong`. Focus uses `--color-focus`. The readout uses
+`--color-elevated-surface`, `--color-foreground`, and `--shadow-md`.
+
+## Presentation options
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `variant` | `line`, `stacked-area` | `line` |
+| `layout` | `standard`, `compact`, `split` | `standard` |
+| `legend` | `table`, `inline`, `sidebar` | `table` |
+| `highlightSeries` | A series key or null | Local selection |
+
+Standard uses a 200-pixel plot; compact uses 165 pixels and tighter spacing.
+Split gives each series a labelled 90-pixel lane on one shared numeric scale,
+with synchronized timestamps. Explicit `height` overrides the plot or lane
+height. Split accepts only line charts; combining it with stacked-area throws
+an error because a stack must retain one common plot.
+
+Table keeps min, max, average, and current visible. Inline shows current values
+in a wrapping legend. Sidebar shows current values at rest and the inspected
+instant on hover, keyboard navigation, or touch, without a floating readout.
+At narrow widths it moves below the plot. All forms keep the exact table.
+
+`highlightSeries` makes highlighting controlled; pass null to clear it. Pair
+it with `onHighlightSeriesChange` to update selection from the legend. Omitting
+it enables local selection. Unknown keys produce no highlight, including when
+a series disappears after a data change. Highlighting changes emphasis only;
+it never removes contributions or changes the stack's total or scale.
+
+Keyboard instructions remain available through the plot's accessible
+description instead of taking permanent space above every plot.
+
+The React component composes Recharts `ComposedChart`, `Line`, `Area`, axes,
+and Tooltip, with animation disabled and `connectNulls={false}`. Synchronization
+uses `syncMethod="value"`. See the [Recharts API](https://recharts.github.io/en-US/api/AreaChart/).
+The existing `.chart` SVG helpers remain compatible; the component frame uses
+`.framed-chart` to avoid changing older SVG consumers.

package/kiso/docs/components/dashboard-grid.md

@@ -0,0 +1,28 @@
+# DashboardGrid
+
+## Purpose and anatomy
+
+Arrange metric panels in a responsive twelve-column grid. DashboardGrid owns
+layout; DashboardPanel owns a column span and wraps a Card or other widget.
+The grid adds no visual panel treatment or ARIA roles of its own.
+
+## Sizes and responsive behavior
+
+Panel `span` accepts 3, 4, 6 (default), 8, or 12. Above 1024 pixels it uses that
+many columns. At 1024 pixels and below, panels use six columns, except full
+width panels which keep twelve. At 640 pixels and below, every panel uses one
+full-width column. Internal tables may scroll; the page must not overflow.
+
+## States and accessibility
+
+Each widget owns its loading, empty, stale, and error states. Reserve its
+space with Skeleton while loading. The layout never reorders DOM content or
+adds tab stops. Reading order, focus order, and visual order stay aligned.
+Give sections meaningful headings and each chart its own name.
+
+## Tokens and composition
+
+Use `--spacing-lg` for gaps. Span is layout metadata, not a new spacing token.
+Compose [Card](card.md), [Chart](chart.md), [Disclosure](disclosure.md), and
+[TimeRangeControl](time-range-control.md) under the
+[Dashboard pattern](../patterns/dashboard.md). CSS Grid needs no dependency.

package/kiso/docs/components/disclosure.md

@@ -0,0 +1,29 @@
+# Disclosure
+
+## Purpose and anatomy
+
+Collapse a related section without leaving the page. A native `details`
+contains a `summary` and content region. `summary` provides the visible name;
+children provide the section content. Do not put links or buttons inside the
+summary. Multiple sections may remain open independently.
+
+## States and behavior
+
+Closed is the default. Pass native `open` to start open. The browser maintains
+open and closed states and dispatches `onToggle`. Closed content remains in
+the document but is hidden and removed from keyboard navigation. Preserve
+application state inside the content; opening does not fetch data by itself.
+
+## Accessibility
+
+Use native semantics and the browser's disclosure marker. Tab reaches the
+summary; Enter or Space toggles it and focus stays there. Content follows the
+summary in DOM order. Keep heading levels appropriate to the surrounding page.
+On a coarse pointer, the summary is at least the minimum touch target height.
+Do not animate the content or add redundant expanded-state ARIA.
+
+## Tokens and implementation
+
+Spacing uses `--spacing-sm`; the summary uses `--type-weight-medium`.
+Focus uses `--color-focus`. Touch targets use `--size-touch-min` only inside
+`@media (pointer: coarse)`. Native details needs no Radix dependency.

package/kiso/docs/components/form-actions.md

@@ -0,0 +1,145 @@
+# FormActions
+
+## Purpose
+
+FormActions gives an explicit-submit form one place for its primary action,
+secondary actions, and optional feedback. It works for sign-in, creation,
+editing, and applying choices. It does not assume that submission saves a record.
+
+## Anatomy
+
+1. An action region after the form content.
+2. An optional visible message in a persistent status region.
+3. An action group with one primary Button and any secondary actions.
+
+The message comes before the buttons in DOM order. Buttons align to the end
+of the region. The layout wraps when the available width cannot hold both
+message and actions. Labels and messages can wrap without horizontal scrolling.
+
+## React API
+
+| Prop | Default | Meaning |
+| --- | --- | --- |
+| `children` | None | Consumer-provided Buttons or navigation Links. |
+| `message` | None | React content rendered inside the status region. |
+| `tone` | `neutral` | `neutral`, `warning`, or `danger` presentation. |
+| `sticky` | `false` | Stick to the bottom of the nearest scrolling ancestor, within the form. |
+| Native div props | None | Includes `className`, `style`, `ref`, and ARIA attributes. |
+
+```tsx
+<FormActions
+  sticky
+  tone={error ? "danger" : dirty ? "warning" : "neutral"}
+  message={error || (dirty ? "Unsaved changes." : undefined)}
+>
+  {dirty && <Button type="button" onClick={discard}>Discard changes</Button>}
+  <Button type="submit" variant="primary" disabled={saving || !dirty}>
+    {saving ? "Saving..." : "Save changes"}
+  </Button>
+</FormActions>
+```
+
+Loading indicators and `aria-busy` belong on the submitting Button. The
+consumer prevents duplicate submission and decides whether cancellation is safe.
+No buttons, labels, dirty tracking, or network behavior are built in.
+
+## Tones and messages
+
+| Situation | Presentation |
+| --- | --- |
+| Initial or create | Neutral; no message required. |
+| Unsaved edits | Warning with a message identifying the unsaved changes. |
+| Submitting | A short progress message and loading submit Button. |
+| Submission failed | Danger with a recovery message; preserve entries. |
+| Saved | Neutral confirmation when the form stays open; clear dirty state. |
+
+Tone does not encode business state. A product decides what "saved, awaiting
+application" means and supplies suitable copy. FormActions does not model
+machines, deployments, or synchronization. Use text to communicate meaning;
+color alone is insufficient. An icon and bold lead are optional.
+
+A new record can show Cancel and Create without a message. Discard appears
+only when there are edits to discard. Avoid an always-visible "Saved" caption
+that remains unchanged after editing.
+
+## Placement and scrolling
+
+For page scrolling, put FormActions last inside Form and pass `sticky`.
+Its bottom offset defaults to zero. When the page has outer padding, set
+`inset-block-end` to the same spacing token so the floating actions respect
+that inset. Cover the space below the floating bar with the page background,
+including the container border, so scrolling fields do not show through the
+outer padding. An offset alone does not create that visual separation.
+When page scrolling moves a marked Card behind sticky actions, keep the top
+marks on the Card and move both bottom corner marks to the sticky action edge.
+Draw them above the inset cover so each corner retains its horizontal and
+vertical tick. Do not leave
+a second pair attached to the scrolling Card bottom.
+For example, use `var(--spacing-xl)` for a page padded by
+`--spacing-xl`, and match any responsive padding changes. The form must remain
+in document flow: an ancestor with scrolling overflow changes the sticky
+container.
+
+For a bounded panel, put Form inside a height-constrained `form-scroll` region.
+That region owns overflow and has no padding. Put padding on `form-body`
+instead. Actions then span the container width without negative margins.
+Form fills at least the panel height and pushes actions to its bottom.
+
+```tsx
+<TabsContent value="general" className="form-scroll" style={{ height: "28rem" }}>
+  <Form onSubmit={save}>
+    <div className="form-body">{/* FormFields */}</div>
+    <FormActions sticky>{/* Buttons */}</FormActions>
+  </Form>
+</TabsContent>
+```
+
+Keep an outer Card's corner marks outside the scrolling region. Do not nest
+FormActions inside CardFooter or DialogFooter; it provides its own border and
+padding. CardFooter stays a general visual container without form status.
+
+If an existing scroller must retain padding, the consumer must account for it:
+set `style={{ insetBlockEnd: "calc(-1 * var(--spacing-lg))" }}` when the
+scroller's bottom padding is `--spacing-lg`. Align the form with the horizontal
+edges separately. Use lengths such as `0px` when supplying values to CSS math.
+Prefer the unpadded composition above for new screens.
+
+The background layers semantic tint over an opaque card surface. Scrolled
+content must not show through the message or buttons. The bar stops at the
+form's end; it is not fixed to the viewport across unrelated content.
+
+## Accessibility
+
+Only the message region has `role="status"` and `aria-atomic="true"`. Keep it
+mounted when empty so updates can be announced. Do not put these attributes
+on the entire action region, and do not put interactive controls in `message`.
+
+Buttons retain their native semantics and tab order. The primary Button has
+`type="submit"`; secondary Buttons have `type="button"`. Use a Link for an
+actual navigation destination. Avoid duplicate announcements from an inline
+message and a Toast for the same event.
+
+Field validation stays beside its field. Keep form-level failures visible
+until the person edits or retries. Verify sticky actions at narrow widths,
+zoom, and keyboard focus. Shared scroll spacing reserves room for typical
+wrapped actions; consumers must increase that space for unusually tall bars.
+
+## Tokens
+
+Spacing uses `--spacing-sm`, `--spacing-md`, and `--spacing-lg`. Scroll spacing
+uses `--spacing-4xl`. Text uses `--type-size-label` and
+`--type-weight-semibold`. The base uses `--color-card`,
+`--color-card-foreground`, and `--color-border`. Warning uses
+`--color-warning-surface` and `--color-warning-border`; danger uses
+`--color-danger-surface` and `--color-danger-border`.
+
+## When not to use
+
+Do not add submission actions to immediate preferences or automatic filters.
+Do not use this component for page-wide record actions unrelated to the form,
+a generic Card footer, or a toolbar for selecting table rows.
+
+## Radix/shadcn mapping
+
+FormActions is a Kiso composition of native grouping, a status region, and
+Buttons. It does not add a keyboard interaction model or a Radix dependency.

package/kiso/docs/components/form-field.md

@@ -7,6 +7,9 @@ identification, entry, guidance, and field-level feedback so their visual and
 accessible relationships remain intact. FormField is not a primitive and does
 not replace the semantics of its children.
 
+Use [Form](form.md) and [FormActions](form-actions.md) for the whole form and
+its submission actions. FormField remains responsible for one control.
+
 ## Anatomy
 
 The canonical composition is: