@momoi-labs/kiso 0.9.0 → 0.11.0

package/kiso/docs/components/form.md

@@ -0,0 +1,102 @@
+# Form
+
+## Purpose
+
+Form composes fields and their submission actions in a native HTML form.
+Every form with explicit submission includes [FormActions](form-actions.md).
+The action can sign in, create, save, search, or apply a choice.
+
+Immediate preferences and automatic filters do not need a submit action.
+Use the existing Switch and search patterns for those interactions.
+
+## Anatomy
+
+1. A native `form`, optionally named by a heading with `aria-labelledby`.
+2. A content region containing FormFields, sections, or fieldsets.
+3. FormActions after the content, with one primary submit Button and any
+   secondary actions the task needs.
+
+```tsx
+<Form onSubmit={handleSubmit} aria-labelledby="project-title">
+  <div className="form-body">
+    <h2 id="project-title">Create project</h2>
+    <FormField label="Project name" name="name" required />
+  </div>
+  <FormActions>
+    <Button type="submit" variant="primary">Create project</Button>
+  </FormActions>
+</Form>
+```
+
+The `form-body` CSS class provides content padding and field spacing. It can
+be applied to a div or fieldset. Products can instead compose content from
+Cards and existing layout utilities. Form adds no padding around its actions.
+Do not wrap FormActions in a padded content region or another footer.
+
+## React API
+
+Form accepts native form props, including `action`, `method`, `onSubmit`,
+`id`, `ref`, and ARIA attributes. It forwards them to the form element and
+merges `className` with `form`.
+
+Form does not create buttons, enforce its children at runtime, intercept
+submission, select a validation library, or track values and dirty state.
+The application owns those behaviors. Explicit-submit forms must follow the
+composition contract even though the React component accepts arbitrary content.
+
+## Layouts
+
+- Short forms keep FormActions in normal flow.
+- Long forms use sticky FormActions on a page or inside a scrolling panel.
+- A form in a bounded panel fills at least the panel height, so actions also
+  reach the panel bottom when content is short.
+- A form can contain multiple Cards. A Card is not required for Form.
+- In Dialog, compose DialogHeader and a Form containing its fields and
+  FormActions. Use `form-scroll` on the form when the dialog constrains its
+  height. Keep the dialog's existing focus and dismissal behavior.
+
+See [FormActions](form-actions.md) for scroll ownership, padded containers,
+responsive actions, and status announcements.
+
+## States and ownership
+
+| State | Application behavior |
+| --- | --- |
+| Initial | Provide fields and an explicit submit action; a status message is optional. |
+| Dirty | Compare current values with the last saved values. Show feedback and Discard when useful. |
+| Invalid | Preserve entries, show field errors, and focus the first invalid field. |
+| Submitting | Show loading on the submit Button and prevent duplicate requests. |
+| Failed | Keep entries and show a recoverable message. Use field errors for field failures. |
+| Saved | Update the saved baseline and clear dirty state. Confirm inline or navigate as appropriate. |
+
+Discard restores the saved baseline. Native reset restores initial defaults,
+which may differ after a successful save. Cancel leaves the task; it does not
+necessarily mean Discard. The application handles navigation and any warning
+needed before losing material edits.
+
+## Accessibility
+
+Preserve native submit and validation behavior. Use `type="submit"` on the
+primary Button and `type="button"` on other buttons. Never nest forms.
+Group related controls with fieldset and legend when they share a question.
+FormField continues to own label, help, and field-error associations.
+
+DOM order is content followed by actions. Sticky placement must not obscure
+focused controls or their errors; verify keyboard use and zoom in the actual
+scroll container. Do not announce the whole form as a live region.
+
+## Tokens
+
+`form-body` uses `--spacing-lg` padding and `--spacing-xl` gaps. Form delegates
+surfaces and borders to its container, and action styling to FormActions.
+
+## Related contracts
+
+- [FormField](form-field.md) for one labeled control.
+- [FormActions](form-actions.md) for submission controls and feedback.
+- [CRUD](../patterns/crud.md) and [Settings](../patterns/settings.md) for flows.
+
+## Radix/shadcn mapping
+
+Form uses native HTML semantics. It introduces no Radix primitive or form-state
+library dependency.

package/kiso/docs/components/meter.md

@@ -0,0 +1,37 @@
+# Meter and Progress
+
+## Purpose
+
+Meter shows a measurement against a known limit, such as 64 connections out
+of 100. Progress shows completion of work. A task's completion is not a meter.
+
+## Anatomy and states
+
+Both have a visible label, a value above a thin horizontal track. Meter takes
+`value`, `min` (default 0), and `max` (default 100). Progress takes an optional
+`value` and positive `max` (default 100). `valueText` supplies units or context.
+
+Bounds must be finite and ordered. Clip the filled width and ARIA value to the
+bounds, while retaining the original measurement in the visible value and
+accessible value text. Do not hide an over-limit measurement by changing it
+to the maximum. Compose a labelled Badge if that measurement is a warning.
+
+A null or nonfinite Meter value reads "Not collected" with an unfilled hatch
+track. It has no fabricated numeric ARIA state. An omitted, null, or nonfinite
+Progress value means indeterminate work, reads "In progress", and has a static
+hatch track. Zero is a known empty track; the maximum is a full track.
+
+## Accessibility
+
+Known measurements use `role="meter"` with name, minimum, maximum, current
+value, and value text. Progress uses `role="progressbar"`; omit its current
+value while indeterminate. Neither adds a tab stop or announces every update.
+Keep the label and value visible for touch and assistive technology.
+No information depends on animation or color.
+
+## Tokens and implementation
+
+The 6px track combines `--spacing-xs` and `--spacing-2xs`, with `--radius-xs`, and `--color-secondary`.
+Meter fill uses `--color-secondary-foreground`; Progress uses `--color-chart-1`. Labels use `--type-size-label` and
+`--color-foreground`. Unknown tracks use the existing hatch tokens. This
+contract adds `.meter-track`; legacy `.progress` rules remain compatible.

package/kiso/docs/components/sparkline.md

@@ -44,12 +44,14 @@ line.
 
 | State | Behavior |
 | --- | --- |
-| fewer than two samples | Renders nothing. A flat rule across a cell reads as a border, not as a measurement. Keep the cell's number; reserve height with the surrounding layout. |
+| fewer than two finite measurements | Renders nothing. A flat rule across a cell reads as a border, not as a measurement. Keep the cell's number; reserve height with the surrounding layout. |
 | loading | [Skeleton](skeleton.md) at the same height the Sparkline will occupy. |
 | error | Show the last known number as text; the shape is optional, the value is not. |
 
-The component takes plain values and does not model gaps. A series with holes
-is the caller's data problem; interpolate or truncate before passing it in.
+The component accepts numbers and null gaps on an evenly spaced window.
+Null and nonfinite values break the line and fill; they never become zero.
+Keep every expected sample position. Domains use finite measurements only.
+Do not interpolate or remove missing positions before passing them in.
 
 ## Accessibility
 
@@ -78,7 +80,7 @@ No keymap and no tab stop. A Sparkline is never an action.
 ## When NOT to use
 
 - Analysis that needs an axis, a legend, or crosshair reading. A framed,
-  interactive chart is a separate, still-deferred contract.
+  interactive [Chart](chart.md) has its own contract.
 - Multi-series overlays. Stack several Sparklines only as separate rows with
   their own labels, never as one drawing with a homemade legend.
 - A single value with no history. Use [Stat](stat.md) alone.
@@ -89,5 +91,4 @@ No Radix primitive exists for this. The component composes Recharts
 `ResponsiveContainer`, `AreaChart`, and `Area` with animation, dots, and
 axes off. Color reaches the path through `currentColor` from the
 `.sparkline` rules in `ui.css`; never pass a hex value or invent a
-categorical palette. The framed `.chart` rules in `ui.css` stay reserved for
-the later interactive chart contract.
+categorical palette. Use [Chart](chart.md) for categorical multi-series data.

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

@@ -0,0 +1,57 @@
+# StepBar
+
+## Purpose
+
+StepBar summarises a run in one row: one segment per step, coloured by the
+step's state. It answers "how far" and "where it stopped" at a glance, in the
+places a [StepList](step-list.md) does not fit: a summary tab, a table cell,
+a Toast. [Progress](meter.md) shows a continuous ratio; StepBar shows discrete
+steps, so a failure is visible as a red segment in its place.
+
+## Anatomy
+
+```
+StepBar (role="img", named)
+└── segment (repeated, one per step)
+```
+
+The bar is the whole component. The product places the count ("4 of 11"),
+the current step's label, or the last output line beside it in its own
+markup; StepBar does not render text.
+
+## States
+
+Segments take the same five states as StepList: pending in
+`--color-secondary`, running and done in `--color-success`, skipped hatched in
+`--color-success`, failed in `--color-danger`. A running segment may show a
+partial fill from `progress` (0 to 1); without it, running fills fully.
+
+## Sizes
+
+One height, `--spacing-xs`. Width comes from the container. In a table cell,
+give the cell a fixed width and keep the bar to one line beside the Badge;
+do not add the ticker there. Hide the bar when the machine is not running and
+has not failed; the Badge alone says "Stopped".
+
+## Accessibility
+
+`role="img"` with a name that says the count and the current step, such as
+"Create: step 4 of 11, running System packages" or
+"Create: failed at step 4 of 11, System packages". The segments are
+decorative. Nothing depends on colour alone.
+
+## Tokens and implementation
+
+Segments use `--radius-xs` and a `--spacing-2xs` gap. The hatch for a skipped
+segment reuses the existing hatch tokens. No Radix primitive.
+
+## When to use
+
+- A machine's summary tab or card while an action runs or after it fails.
+- A machines table, one line per row, next to the status Badge.
+- A progress Toast for a run started from another screen.
+
+## When NOT to use
+
+- The run's own page. Use StepList there; the bar would repeat it.
+- A continuous measurement. Use Meter or Progress.

package/kiso/docs/components/step-list.md

@@ -0,0 +1,86 @@
+# StepList
+
+## Purpose
+
+StepList shows the steps of a run a machine walks through, one row per step,
+with a state, a label, and a timing. While the run goes it is the progress;
+afterwards it is the account of what happened. The reader does not walk the
+steps; the machine does, and the reader reads how it went.
+
+It is not the [Pagination](pagination.md) step indicator. That one shows a
+person's position in a flow they drive. StepList has a state per step, a
+timing, and an output the reader may open.
+
+## Anatomy
+
+```
+StepList (ordered list, labelled)
+└── Step (repeated)
+    ├── rail: connector and mark, with a text alternative
+    ├── label
+    ├── meta (mono, muted)
+    └── detail (optional slot, below the row)
+```
+
+The rail is one vertical line through every mark. Each mark is a dot; the
+connector above it takes the colour of the step's state, so the line fills as
+the run advances and the list is itself the progress. Nothing else measures
+completion: do not add a Progress track above a StepList.
+
+Each row is a button when the list has `onSelect`; the product then shows the
+selected step's output beside the list, usually in the second [Pane](split.md)
+of a Split with a [LogView](log-view.md) filling it. On a narrow viewport,
+where the Split cannot fit, pass the output as the selected step's `detail`
+and it renders under the row.
+
+## States
+
+| State | Mark | Default meta |
+| --- | --- | --- |
+| pending | empty dot, muted row | none; the product passes "Not run" after a failure |
+| running | dot ringed in `--color-success`, pulsing, bold label | "Running" |
+| done | filled `--color-success` dot | none; the product passes the duration |
+| skipped | hollow `--color-success` dot, muted label | "Not needed" |
+| failed | filled `--color-danger` dot, bold label in `--color-danger` | none; the product passes the duration |
+
+The running step is `aria-current="step"`. Five states, not a status badge's
+tones: running is alive, so it is the success colour; neutral is what is not
+happening; danger is what stopped the run.
+
+The product owns which step is selected. Follow the running step by default,
+keep a step the reader chose, and offer a way back to the current one.
+
+## Accessibility
+
+An `ol` with an accessible name, one `li` per step. Each mark carries its
+state as text (`role="img"` with the state as its name), so colour is never
+the only signal. Rows that select are native buttons with `aria-pressed`;
+rows that do not are plain text. The connector is decorative and hidden.
+Under reduced motion the running mark does not pulse.
+
+### Keyboard
+
+No custom keymap. Tab reaches each selectable row; Enter or Space selects it.
+
+## Tokens and implementation
+
+Rail and marks use `--color-border-strong`, `--color-success`,
+`--color-success-surface`, and `--color-danger`. Labels use
+`--type-size-label`; the running and failed labels use
+`--type-weight-semibold`. Meta uses `--font-mono`, `--type-size-label`, and
+`--color-muted-foreground`. Rows are spaced with `--spacing-sm`; the rail
+column is `--spacing-xl` wide, room for the running mark's glow. Focus uses `--color-focus`. No Radix
+primitive is involved.
+
+## When to use
+
+- A lifecycle action on a machine: create, update, or a bootstrap with a
+  known list of stages.
+- An image build or a collection whose phases are known before it starts.
+
+## When NOT to use
+
+- A flow the person walks through. Use Pagination's step indicator.
+- A plan that is not known before it runs. Append rows as they happen, and
+  pair the list with an indeterminate Progress rather than a [StepBar](step-bar.md).
+- A single indeterminate wait. Use Spinner.

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

@@ -104,11 +104,13 @@ server round-trip to repaint, and do not show a Toast for it.
   which is the default and the most common choice.
 - A theme entry buried inside a DropdownMenu as the only access point. A menu
   may mirror the control, but the setting lives in a settings row.
-- Any control that offers colour options beyond these three. Kiso has two
-  themes.
+- Any control that offers colour scheme options beyond these three. Kiso has
+  two themes. The accent is a separate axis with its own control,
+  [AccentSelector](accent-selector.md).
 
 ## Related
 
 - [tokens](../tokens.md) — how `light-dark()` and `color-scheme` resolve.
 - [Settings](../patterns/settings.md#theme) — where the row lives.
+- [AccentSelector](accent-selector.md) — the other appearance row.
 - [Switch](switch.md) — for actual booleans.

package/kiso/docs/components/time-range-control.md

@@ -0,0 +1,48 @@
+# TimeRangeControl
+
+## Purpose and anatomy
+
+Select the visible interval within a collected run. A labelled Button opens a
+compact Popover with a vertical preset list. Custom range reveals exact
+start/end fields. This control scopes an
+artifact's timestamps, not a live polling schedule or date-only calendar.
+
+## Data and behavior
+
+`bounds` and controlled `value` are `{ from, to }` epoch-millisecond pairs.
+Both must be finite, valid dates with start before end; value must fit inside
+bounds. `onValueChange` receives an applied range. The consumer filters panels
+and recalculates their summaries from that interval.
+
+Presets default to the last 5, 15, and 30 minutes relative to the end of the
+run. Durations are positive milliseconds; clip their start to the run start.
+"Entire run" restores bounds. Selecting a preset applies it and closes the
+popover. Custom fields are explicitly UTC, including milliseconds; local
+machine timezone and daylight-saving changes cannot shift the selection.
+
+Editing a field does not apply it. Apply validates that the start precedes
+the end and both fit inside the collection window. Invalid input keeps the
+popover open with field-associated feedback. Escape or outside dismissal
+cancels edits. Reopening starts with the applied value. `disabled` disables
+the trigger while a run is unavailable.
+
+## Accessibility
+
+Compose [Button](button.md), [Popover](popover.md), and labelled
+[Input](input.md) controls. Tab follows the visible preset buttons or custom form fields and Apply. Native
+date/time inputs retain platform keyboard behavior. Escape dismisses; Radix
+restores focus to the trigger. Errors use an alert and field descriptions.
+The trigger shows a short interval and UTC. Its accessible name includes
+both full timestamps; visible dates appear when the interval crosses a day. Touch can use every action.
+
+## Tokens and implementation
+
+Use existing Button, Input, and Popover tokens. Use `--spacing-xs` between
+presets and `--spacing-md` between regions. The trigger wraps long ranges;
+the popover fits the viewport. No new calendar, timezone, or date dependency.
+
+## Custom range form
+
+The custom range editor composes [Form](form.md) with
+[FormActions](form-actions.md). Apply range is the explicit submit action;
+validation stays next to the range fields. Presets still apply immediately.

package/kiso/docs/evolution.md

@@ -10,22 +10,28 @@ the system needs them. This is the honest roadmap for those choices.
 | --- | --- | --- |
 | **Component implementation code** | V1 ships Markdown contracts and tokens, not React components. Keeping the specification separate lets product needs shape an implementation instead of freezing an assumed API. This boundary was set in [epic #3](https://github.com/momoi-labs/blueprint/issues/3). | When repeated product implementations make a stable reference API evident. Build it as Kiso v2 or in a separate `kiso-ui` repository, using shadcn/Radix behavior adapted to Kiso rather than copied unchanged. |
 | **Radio / RadioGroup** | Select and Switch cover the v1 choice cases, so [epic #3](https://github.com/momoi-labs/blueprint/issues/3) did not add another selection primitive without a product need. | When a product genuinely needs mutually exclusive selection from a small, fixed set whose options should remain visible. |
-| **Interactive framed charts** | [#84](https://github.com/momoi-labs/blueprint/issues/84) shipped [Sparkline](components/sparkline.md) for the single-series metric shapes products actually had. No product has yet needed an axis, a legend, or crosshair reading. | When a product needs exploratory reading of a series: axes, multi-series overlays, or hover inspection. Settle the framed `.chart` contract then. |
 | **Figma Tokens Studio integration** | [Epic #2](https://github.com/momoi-labs/blueprint/issues/2) kept the token pipeline focused on its committed outputs. Tokens Studio is a Figma plugin workflow built through Style Dictionary and `@tokens-studio/sd-transforms`, not a standalone emitter. | When design-to-code synchronization through Figma becomes a real team workflow rather than a hypothetical integration. |
 | **DTCG 2025.10 Resolver module** | The multiple-context and theme Resolver considered in [epic #2](https://github.com/momoi-labs/blueprint/issues/2) is a preview draft marked “do not implement.” V1 uses an explicit, stable theme model instead. | When the Resolver module reaches stable status and Kiso has a concrete context or theme problem it would solve. |
 | **`--shadow-lg`** | The elevation scale intentionally stops at `--shadow-sm` and `--shadow-md`; [#25](https://github.com/momoi-labs/blueprint/issues/25) fixed component references without inventing a larger elevation. | When a real overlay or hierarchy cannot be expressed clearly with `--shadow-md`. Propose the token in the source, then regenerate its outputs. |
-| **A dedicated multi-step-flow pattern** | [#26](https://github.com/momoi-labs/blueprint/issues/26) added step indication as a Pagination variant, which satisfies the current bounded-flow need without another pattern. | When recurring multi-step flows need behavior, composition, or guidance beyond Pagination's scope. |
+| **A dedicated multi-step-flow pattern** | [#26](https://github.com/momoi-labs/blueprint/issues/26) added step indication as a Pagination variant, which satisfies the current bounded-flow need without another pattern. [#98](https://github.com/momoi-labs/blueprint/issues/98) added StepList for the other case, a run a machine walks and a person reads; person-driven flows still use Pagination. | When recurring person-driven flows need behavior, composition, or guidance beyond Pagination's scope. |
 | **Additional patterns** | The pattern set from [epic #4](https://github.com/momoi-labs/blueprint/issues/4) is an intentionally lean cut of roughly 21 recurring product structures. Speculative completeness would encode guesses. | When a real product exposes a repeated structure that the current patterns cannot express without an ad-hoc solution. |
 | **Additional components** | The roughly 28-component cut from [epic #3](https://github.com/momoi-labs/blueprint/issues/3) covers the intended v1 product surface. Adding primitives in anticipation would enlarge the interface before their contracts are understood. | When a need recurs across products. Propose a component and its contract; do not invent one locally or copy one in unchanged. |
 | **Heavy governance** | A two-person lab does not need a contribution bureaucracy or design-review board. For v1, the propose-don't-copy rule in [`kiso/AGENTS.md`](../AGENTS.md) is the governance mechanism, as scoped by [epic #5](https://github.com/momoi-labs/blueprint/issues/5). | When more contributors, products, or incompatible proposals make ownership and decision-making unclear. Add only the process needed to resolve an observed coordination problem. |
 
 ## Accepted additions
 
+[Issue #93](https://github.com/momoi-labs/blueprint/issues/93) opens the framed
+chart deferral with pg-probe collection data. Chart, ChartLegend, Meter,
+Progress, BarGauge, Disclosure, TimeRangeControl, DashboardGrid, and Sparkline
+gaps now cover that workflow. Five categorical slots cover the demonstrated
+maximum. More slots require a product case and palette review.
+
 The growth model below is not theory. What it has produced so far:
 
 | What | Evidence | Where |
 | --- | --- | --- |
 | **[ChipInput](components/chip-input.md)** | A self-hosted console had to collect a development image's dependencies: a list a person types, where every entry carries a backend, a version, and installer options. One form section per entry grew without limit and buried the list. | Added as a component contract with the segmented chip, the in-place value, and one segment per option. |
+| **[StepList](components/step-list.md) and [StepBar](components/step-bar.md)** | The self-host console's Last run tab walks a machine through eleven lifecycle steps over several minutes and wrote its own list of steps with a state each, replacing a progress bar and a two-thousand-line log to search. An image build and the Host's own bootstrap were about to copy it. [#98](https://github.com/momoi-labs/blueprint/issues/98) records the evidence. | Added as two contracts: the list inside a Split with the step's LogView beside it, and the bar for a summary, a table cell, or a toast. |
 | **[Sparkline](components/sparkline.md)** | The self-host console collects metrics in-process, one sample per tick on an evenly spaced window, and needed the same shape three times over: a trend cell per application row, context under a KPI value, and one series per container. [#84](https://github.com/momoi-labs/blueprint/issues/84) records the evidence. | Added as a component contract and a Recharts-based component, single series, neutral by default, primary only for the series a tile is about. |
 
 ## Growth model: grow with real products

package/kiso/docs/patterns/crud.md

@@ -21,7 +21,7 @@ specified separately and must still run before destruction.
 | Page framing | [PageHeader](../components/page-header.md) | Title ("New connection", "Edit connection"); optional cancel secondary action |
 | Fields | [FormField](../components/form-field.md) | Each field = [Label](../components/label.md) + control ([Input](../components/input.md), [Textarea](../components/textarea.md), [Select](../components/select.md), [Checkbox](../components/checkbox.md), …) + optional [HelperText](../components/helper-text.md) + [ValidationMessage](../components/validation-message.md) |
 | Grouping | [Card](../components/card.md) or section headings | Related field groups (connection, credentials, advanced) |
-| Primary actions | [Button](../components/button.md) | Save / Create (primary); Cancel (secondary/ghost) |
+| Primary actions | [FormActions](../components/form-actions.md) + [Button](../components/button.md) | Save / Create (primary); Cancel (secondary/ghost) |
 | Overlays | [Modal / Dialog](../components/modal-dialog.md) or [Drawer](../components/drawer.md) | Compact create/edit; Drawer preferred on small viewports for the same task |
 | Inline errors | [ValidationMessage](../components/validation-message.md) on FormField | Field-level recovery; page [Alert](../components/alert.md) is for non-field failures |
 | Form / load errors | [Alert](../components/alert.md) | Submit or load failures that are not field-local (what / why / now) |
@@ -36,6 +36,19 @@ invalid fields and ValidationMessage use `--color-danger`, focus
 `--color-focus`, destructive Buttons use `--color-danger` per the Button
 contract.
 
+## Form actions
+
+Every explicit-submit form composes [Form](../components/form.md) and
+[FormActions](../components/form-actions.md). Place one primary submit action
+and any secondary actions after the fields. Use sticky actions when the form
+extends beyond the page or panel viewport. Follow the FormActions contract for
+scroll ownership, optional messages, and responsive layout.
+
+The product owns dirty tracking, validation, submission, and navigation.
+Discard restores the last saved values; Cancel leaves the task. Keep entries
+on failure. Announce feedback in the message region, not around the buttons.
+Immediate preferences and automatic filters do not require FormActions.
+
 ## Flow
 
 ### Create
@@ -87,7 +100,7 @@ Full-page create/edit:
 
 ```text
 ┌──────────────────────────────────────────────────────────────────────┐
-│ PageHeader: Edit connection                         [Cancel] [Save]  │
+│ PageHeader: Edit connection                                          │
 ├──────────────────────────────────────────────────────────────────────┤
 │ Alert (only if submit/load error — what / why / now)                 │
 │                                                                      │

package/kiso/docs/patterns/dashboard.md

@@ -16,7 +16,7 @@ tables, or dedicated tool routes.
 
 | Region | Compose with | Role |
 | --- | --- | --- |
-| Page framing | [PageHeader](../components/page-header.md) | Dashboard title; optional time-range or environment [Select](../components/select.md); optional refresh [IconButton](../components/icon-button.md) / [Button](../components/button.md) |
+| Page framing | [PageHeader](../components/page-header.md) | Dashboard title; optional [TimeRangeControl](../components/time-range-control.md) or environment [Select](../components/select.md); optional refresh [IconButton](../components/icon-button.md) / [Button](../components/button.md) |
 | Widget unit | [Card](../components/card.md) | One concern per Card (metric cluster, short table, status list) |
 | Status | [Badge](../components/badge.md) | Compact health/severity labels inside Cards |
 | Dense lists | [Table / DataTable](../components/table.md) | Short "needs attention" tables — still compose Search/EmptyState/Pagination only when those behaviors are truly present |
@@ -36,8 +36,11 @@ semantic colors, focus `--color-focus`. Prefer quiet surfaces and strong
 hierarchy ([principles](../principles.md)).
 
 [Sparkline](../components/sparkline.md) carries metric shape inside Cards and
-table cells; it composes like any other widget payload. An interactive framed
-chart remains deferred.
+table cells; it composes like any other widget payload. Use
+[Chart](../components/chart.md) with its legend and exact-values table for
+exploratory metrics. Share a timestamp grid, time range, and syncId across
+related panels. Compose [DashboardGrid](../components/dashboard-grid.md) and
+[Disclosure](../components/disclosure.md) for responsive panel groups.
 
 ## Flow
 

package/kiso/docs/patterns/settings.md

@@ -15,13 +15,13 @@ immediate vs deferred persistence, and unambiguous save feedback.
 
 | Region | Compose with | Role |
 | --- | --- | --- |
-| Page framing | [PageHeader](../components/page-header.md) | "Settings" or section title; optional save actions when the page uses explicit save |
+| Page framing | [PageHeader](../components/page-header.md) | "Settings" or section title; section context; submit actions belong in FormActions |
 | Section nav | [Tabs](../components/tabs.md) or Sidebar sub-nav [Link](../components/link.md)s | Split General / Notifications / API, etc. |
 | Groups | [Card](../components/card.md) | One settings group per Card |
 | Text / choice fields | [FormField](../components/form-field.md) | [Label](../components/label.md) + [Input](../components/input.md) / [Select](../components/select.md) / [Textarea](../components/textarea.md) + [HelperText](../components/helper-text.md) + [ValidationMessage](../components/validation-message.md) |
 | Repeated values with their own options | [ChipInput](../components/chip-input.md) | One field for a list a person types, such as dependencies or scopes, instead of a form section per entry |
 | Booleans | [Switch](../components/switch.md) (immediate) or [Checkbox](../components/checkbox.md) inside FormField (part of a saved form) | Switch for single immediate preferences; Checkbox when the value submits with Save |
-| Actions | [Button](../components/button.md) | Save (primary), Reset/Cancel (secondary) for explicit-save sections |
+| Actions | [FormActions](../components/form-actions.md) + [Button](../components/button.md) | Save (primary), Reset/Cancel (secondary) for explicit-save sections |
 | Feedback | [Toast](../components/toast.md), [Alert](../components/alert.md), [ValidationMessage](../components/validation-message.md) | Saved confirmation; section errors; field errors |
 | Shell | [Application shell](application-shell.md) | Authenticated framing |
 
@@ -50,8 +50,27 @@ Three points bind here rather than there:
 ```text
 Card: Appearance
   Theme                                   [ ▣ ][ ☀ ][ ☾ ]
+  Accent                                  [ ● ][ ● ][ ● ][ ● ]
 ```
 
+The accent is the second row of the same card, with
+[AccentSelector](../components/accent-selector.md). It follows the same three
+points: `violet` is the default, the choice is local and instant, and it
+persists under `kiso-accent` outside the section's Save button.
+
+## Form actions
+
+Every explicit-submit form composes [Form](../components/form.md) and
+[FormActions](../components/form-actions.md). Place one primary submit action
+and any secondary actions after the fields. Use sticky actions when the form
+extends beyond the page or panel viewport. Follow the FormActions contract for
+scroll ownership, optional messages, and responsive layout.
+
+The product owns dirty tracking, validation, submission, and navigation.
+Discard restores the last saved values; Cancel leaves the task. Keep entries
+on failure. Announce feedback in the message region, not around the buttons.
+Immediate preferences and automatic filters do not require FormActions.
+
 ## Flow
 
 ### Explicit save (default for multi-field sections)

package/kiso/docs/tokens.md

@@ -157,10 +157,68 @@ dark because `dark.500` misses the 3:1 non-text and large-text gates on
 `dark.800` and `dark.700`; they share a step on dark exactly as they share
 `neutral.500` on light.
 
+## Accents
+
+The accent is a second axis over the same custom properties, orthogonal to the
+theme. Five accents ship: `violet` (the default), `terracotta`, `teal`,
+`cobalt`, and `nocturne`. The first four are hue turns: each is a primitive
+ramp (`color.violet.*`, `color.terracotta.*`, and so on) with the same
+lightness per step, so every role keeps the contrast it was gated at.
+`color.accent.*` is the *active* ramp: an alias layer that points at violet by
+default.
+
+`nocturne` is different in kind. It is the marketing site's palette: the
+violet ramp and ink over cool slate neutrals (hue 278) instead of the warm
+ones. It is the one accent that restates the neutral roles, surfaces, text,
+borders, and neutral fills alike, because the slate is the palette, not a
+tint on it. A hue accent nested inside a nocturne container keeps the slate
+and changes only the accent. Its surface, text, and accent values are the
+site's own, gated like every other accent; the roles the site never named are
+Kiso's lightness in the slate hue.
+
+An accent is chosen with `data-accent` on `<html>`, or on any container:
+
+```html
+<html data-accent="teal">
+```
+
+No attribute means violet. The build emits one `[data-accent="<name>"]` block
+per accent from the `accent.<name>` group in `tokens/tokens.json`. That block
+restates only the roles that follow the hue:
+
+- the active ramp, `--color-accent-50` to `--color-accent-950` and
+  `--color-accent-base`, remapped to the named ramp. `link`, `focus`, `ring`,
+  `accent`, and the light-theme tints alias the ramp, so they follow without
+  being restated;
+- the raw-hex dark fills: `primary`, `primary-hover`, `primary-foreground`,
+  `accent-surface`, `accent-surface-hover`, and `selected`.
+
+The neutral roles are not restated. The warm grey carries the interface under
+every hue accent, and only the accent changes: a teal product and a violet
+product share the same canvas, text, and borders. Tinting the neutrals toward
+the hue was tried and rejected; at any visible strength it reads as a filter
+over the screen rather than as a colour choice.
+
+Values inside the block still use `light-dark()`, so accent and theme compose
+without a cross product: five accents and two themes are five blocks, not
+ten. Nesting resets cleanly: a `data-accent="violet"` container inside a
+teal page is violet again.
+
+Chart series do not follow the accent. `chart-1` is pinned to the violet ink
+because a terracotta, teal, or cobalt series collapses into the warning, success,
+or info series; see [Categorical chart colors](#categorical-chart-colors).
+Status roles do not follow it either. Red, amber, and green were rejected as
+accents for the same reason: a primary button in the danger hue reads as
+destructive.
+
+Applications own the choice and its persistence, exactly as with the theme.
+Use [AccentSelector](components/accent-selector.md) for the control.
+
 ## AA gate
 
 `scripts/check-contrast.mjs` is the build-time AA gate. In both dark and light
-themes it resolves the semantic aliases and checks:
+themes, for the default and for every accent, it resolves the semantic aliases
+and checks:
 
 - `foreground`, `muted-foreground`, `link`, `accent`, `success`, `warning`,
   `danger`, and `info` at **4.5:1** or better against `background`, `surface`,
@@ -311,3 +369,31 @@ Published releases expose the artifacts as `@momoi-labs/kiso/tokens.css`,
 `@momoi-labs/kiso/tokens.d.ts`. Kiso's Markdown contracts are available below
 `@momoi-labs/kiso/contracts/` so consumers can pin the contracts and generated
 tokens to the same version.
+
+## Categorical chart colors
+
+Issue #93 adds `--color-chart-1` through `--color-chart-5` for series identity.
+The roles derive from violet.base, status.success, status.warning, status.info,
+and status.danger, in that order. `chart-1` is the violet ink under every
+accent, not the active accent: a series must stay distinguishable from the
+status series whatever the product's accent is. Their meaning inside a chart is categorical,
+never health or severity. Existing status roles keep their meaning elsewhere.
+
+Each slot meets 3:1 on background, surface, and elevated-surface in both
+themes, enforced by the contrast gate. Lines use full-opacity strokes; area
+fills are secondary at 0.2 opacity. Every series also has a numbered label,
+an interactive highlight, a legend value, and exact sample values. Do not
+use filled bands or hue alone to identify data. Five slots cover pg-probe;
+the epic's proposed eight-slot headroom is deferred until needed.
+
+The palette gate also checks Oklab lightness bands (0.40 to 0.65 in light mode,
+0.70 to 0.90 in dark mode), chroma of at least 0.08, all-pair normal-vision
+distance of at least 0.10, and adjacent-pair distance of at least 0.05 under
+full protanopia and deuteranopia simulation. These are product regression
+floors, not accessibility standards or a guarantee of hue discrimination.
+Keep the canonical slot order in stacks; changing adjacency needs review.
+
+The calculation uses [Oklab](https://bottosson.github.io/posts/oklab/) and
+[Machado's simulation model](https://pubmed.ncbi.nlm.nih.gov/19834201/).
+Run `node scripts/check-chart-palette.mjs` for both themes and every accent. Numbered labels,
+highlighting, and tables remain required even when these checks pass.