npm - @momoi-labs/kiso - Versions diffs - 0.10.0 → 0.12.0 - Mend

@momoi-labs/kiso 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/kiso/docs/components/README.md +7 -0
package/kiso/docs/components/accent-selector.md +136 -0
package/kiso/docs/components/card.md +11 -5
package/kiso/docs/components/drawer.md +1 -1
package/kiso/docs/components/form-actions.md +145 -0
package/kiso/docs/components/form-field.md +3 -0
package/kiso/docs/components/form.md +102 -0
package/kiso/docs/components/modal-dialog.md +1 -1
package/kiso/docs/components/step-bar.md +57 -0
package/kiso/docs/components/step-list.md +86 -0
package/kiso/docs/components/theme-selector.md +4 -2
package/kiso/docs/components/time-range-control.md +6 -0
package/kiso/docs/evolution.md +2 -1
package/kiso/docs/patterns/crud.md +15 -2
package/kiso/docs/patterns/settings.md +21 -2
package/kiso/docs/tokens.md +100 -9
package/kiso/ui.css +244 -39
package/package.json +1 -1
package/tokens/build/tokens.css +179 -16
package/tokens/build/tokens.d.ts +184 -23
package/tokens/build/tokens.json +160 -12
package/tokens/build/tokens.scss +161 -13

package/kiso/docs/components/README.md CHANGED Viewed

@@ -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,6 +26,7 @@ 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.
@@ -43,6 +46,8 @@ 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
@@ -72,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 ADDED Viewed

@@ -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/card.md CHANGED Viewed

@@ -69,7 +69,7 @@ it is a section with a heading, not a Card.
 This is the shared panel contract. Card, [Table](table.md) wrapper,
 [ModalDialog](modal-dialog.md), [Drawer](drawer.md),
 [CommandPalette](command-palette.md), and code or log blocks are **panels**:
-square (`--radius-surface`) with corner marks. Popover, DropdownMenu, Toast,
+square (`--radius-surface`) with corner marks by default. Popover, DropdownMenu, Toast,
 Alert, and Tooltip are transient chrome, not panels: they keep a small radius
 and carry no marks.
@@ -91,11 +91,11 @@ accidental.
 The gap is the mark. Close it and this is just a thicker border.
-Marks go on every panel, without exception. There is no rounded mode and no
-`data-corners` attribute; the corner language was decided once and is not a
-per-product setting.
+Applications can change panel borders, radii, mark shapes, and mark sizes
+with the [appearance attributes](../tokens.md#appearance-attributes).
+Without these attributes, panels keep the square frame and tick marks.
-Draw them on one pseudo-element inset by `calc(-1 * (var(--corner-mark-tick) +
+Draw default ticks on one pseudo-element inset by `calc(-1 * (var(--corner-mark-tick) +
 var(--corner-mark-gap)))`, so no markup and no images are needed. If the panel
 scrolls, move `overflow` to an inner element — the marks sit just outside the
 frame and a scrolling wrapper clips them away.
@@ -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/drawer.md CHANGED Viewed

@@ -27,7 +27,7 @@ Drawer Root
 Content uses `--color-elevated-surface`, `--color-foreground`,
 `--color-border`, `--spacing-lg` padding, `--radius-surface`, and
-`--shadow-lg`. The scrim uses `--color-overlay`. Panels are square (`--radius-surface`) and carry corner marks. See
+`--shadow-lg`. The scrim uses `--color-overlay`. Panels are square (`--radius-surface`) and carry corner marks by default. See
 [Card](card.md#corner-marks) for the shared panel contract.
 Entry/exit uses `--motion-duration-normal` and `--motion-easing-standard`, with
 no travel under reduced motion.

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

@@ -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 CHANGED Viewed

@@ -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:

package/kiso/docs/components/form.md ADDED Viewed

@@ -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/modal-dialog.md CHANGED Viewed

@@ -26,7 +26,7 @@ Dialog Root
 Content uses `--color-elevated-surface`, `--color-foreground`,
 `--color-border`, `--radius-surface`, `--spacing-lg` padding, and
 `--shadow-lg`. A Dialog is a panel: it carries corner marks. The scrim uses
-`--color-overlay`. Panels are square (`--radius-surface`) and carry corner marks. See
+`--color-overlay`. Panels are square (`--radius-surface`) and carry corner marks by default. See
 [Card](card.md#corner-marks) for the shared panel contract.
 Overlay transitions use `--motion-duration-normal` and
 `--motion-easing-standard`.

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

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -40,3 +40,9 @@ both full timestamps; visible dates appear when the interval crosses a day. Touc
 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.