@momoi-labs/kiso 0.4.1 → 0.6.0

package/README.md

@@ -66,7 +66,11 @@ Code, config, and templates: **MIT**. Brand assets (name, logo, type):
 
 [`@momoi-labs/kiso-react`](packages/kiso-react/README.md) provides React components
 using Kiso tokens and CSS. Run `npm ci` and `npm run prototype` to open the
-Self Host simulation and the full component gallery.
+component gallery, where every entry renders the published component.
+
+The [standalone Kiso gallery](apps/kiso-gallery/README.md) has its own build
+and Cloudflare configuration for `kiso.momoi-labs.dev`. Run `npm run gallery`
+to open it locally, or `npm run build:gallery` to produce the static site.
 
 See [Publishing Kiso](docs/publishing.md) for the first npm publication, trusted
 publisher setup, release PRs, and version tags.

package/kiso/docs/components/README.md

@@ -1,55 +1,63 @@
 # Kiso component catalog
 
-Kiso defines product UI as markdown contracts rather than implementation code.
-Each contract specifies anatomy, states, accessibility, usage guidance, semantic
-token consumption, and a Radix/shadcn behavioral reference where one exists.
+Kiso documents each component in a Markdown contract covering anatomy, states,
+accessibility, usage, and token consumption. Contracts include a Radix/shadcn
+behavioral reference where one exists.
 
 ## Nucleus
 
-- [Alert](alert.md) — Communicates persistent in-page information, success, warnings, or errors.
-- [Badge](badge.md) — Labels status or compact metadata without becoming an action.
-- [Button](button.md) — Triggers a visible, text-labeled action without changing the URL.
-- [Card](card.md) — Groups related content and actions with visual separation.
-- [Checkbox](checkbox.md) — Toggles an option in a list or selects multiple values.
-- [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.
-- [Input](input.md) — Collects a single-line text-like value.
-- [Label](label.md) — Gives a form control its visible, programmatically associated name.
-- [Link](link.md) — Navigates to a URL while preserving native link behavior.
-- [Select](select.md) — Chooses one value from a predefined set of options.
-- [Skeleton](skeleton.md) — Preserves known layout while its content is loading.
-- [Spinner](spinner.md) — Signals indeterminate work when the final layout is not represented.
-- [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.
-- [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.
+- [Alert](alert.md): Communicates persistent in-page information, success, warnings, or errors.
+- [Badge](badge.md): Labels status or compact metadata without becoming an action.
+- [Button](button.md): Triggers a visible, text-labeled action without changing the URL.
+- [Card](card.md): Groups related content and actions with visual separation.
+- [Checkbox](checkbox.md): Toggles an option in a list or selects multiple values.
+- [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.
+- [Input](input.md): Collects a single-line text-like value.
+- [Label](label.md): Gives a form control its visible, programmatically associated name.
+- [Link](link.md): Navigates to a URL while preserving native link behavior.
+- [Select](select.md): Chooses one value from a predefined set of options.
+- [Skeleton](skeleton.md): Preserves known layout while its content is loading.
+- [Spinner](spinner.md): Signals indeterminate work when the final layout is not represented.
+- [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.
+- [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
 
-- [CommandPalette](command-palette.md) — Searches and runs global actions or navigation from a keyboard-first overlay.
-- [DropdownMenu](dropdown-menu.md) — Presents contextual actions anchored to a specific object or trigger.
-- [EmptyState](empty-state.md) — Replaces an empty collection with an explanation and optional next action.
-- [Search](search.md) — Filters visible content such as a list or table.
-- [Table / DataTable](table.md) — Presents structured records with optional sorting, selection, filtering, and pagination.
+- [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.
+- [EmptyState](empty-state.md): Replaces an empty collection with an explanation and optional next action.
+- [KV](kv.md): Describes one object through named facts.
+- [LogView](log-view.md): Displays scrollable log output with follow-tail behavior.
+- [Search](search.md): Filters visible content such as a list or table.
+- [Stat](stat.md): Presents a named metric with optional change and context.
+- [Table / DataTable](table.md): Presents structured records with optional sorting, selection, filtering, and pagination.
 
 ## Navigation and structure
 
-- [Breadcrumb](breadcrumb.md) — Shows the current location within a hierarchy.
-- [Header](header.md) — Composes persistent application navigation and global actions.
-- [Navigation](navigation.md) — Provides a generic semantic container for destination links.
-- [PageHeader](page-header.md) — Composes a page title, optional subtitle, and page-scoped action Buttons.
-- [Pagination](pagination.md) — Moves through known pages while exposing the current position.
-- [Sidebar](sidebar.md) — Organizes persistent navigation into optionally collapsible sections.
-- [Tabs](tabs.md) — Switches among related content panels within the same page context.
+- [AppShell](app-shell.md): Places Sidebar navigation beside the main application content.
+- [BrandMark](brand-mark.md): Decorative letter or icon beside a product name.
+- [Breadcrumb](breadcrumb.md): Shows the current location within a hierarchy.
+- [Header](header.md): Composes persistent application navigation and global actions.
+- [Navigation](navigation.md): Provides a generic semantic container for destination links.
+- [PageHeader](page-header.md): Composes a page title, optional subtitle, and page-scoped action Buttons.
+- [Pagination](pagination.md): Moves through known pages while exposing the current position.
+- [Separator](separator.md): Marks a visual or semantic boundary in either orientation.
+- [Sidebar](sidebar.md): Organizes persistent navigation into optionally collapsible sections.
+- [Split / Pane / Splitter](split.md): Allocates width between related panes with pointer and keyboard resizing.
+- [Tabs](tabs.md): Switches among related content panels within the same page context.
 
 ## Overlay
 
-- [Drawer](drawer.md) — Presents a viewport-adaptive panel, including a mobile alternative to Modal/Dialog.
-- [Modal / Dialog](modal-dialog.md) — Blocks the page for a focused task that requires attention or a decision.
-- [Popover](popover.md) — Shows rich, interactive contextual content anchored to a trigger.
-- [Toast](toast.md) — Reports transient system feedback without replacing in-page status or field errors.
+- [Drawer](drawer.md): Presents a viewport-adaptive panel, including a mobile alternative to Modal/Dialog.
+- [Modal / Dialog](modal-dialog.md): Blocks the page for a focused task that requires attention or a decision.
+- [Popover](popover.md): Shows rich, interactive contextual content anchored to a trigger.
+- [Toast](toast.md): Reports transient system feedback without replacing in-page status or field errors.
 
 ## Required compositions
 

package/kiso/docs/components/app-shell.md

@@ -0,0 +1,68 @@
+# AppShell
+
+## Purpose
+
+AppShell places persistent [Sidebar](sidebar.md) navigation beside the main
+application content. It owns the page columns, not navigation state.
+
+## Anatomy
+
+```
+AppShell
+├── Sidebar
+└── AppShellMain
+    ├── Header or PageHeader (optional)
+    └── page content
+```
+
+The two slots are direct children. AppShell is a `div`; AppShellMain is a
+`main` with `min-width: 0`, so wide tables and log lines cannot push the
+Sidebar off screen. Sidebar owns its header, body, and footer.
+
+## Variants
+
+One layout. No variant prop. Compose [Header](header.md) and
+[PageHeader](page-header.md) inside the main slot as the page requires.
+
+## Sizes
+
+The Sidebar column uses `--size-sidebar`; the main column takes the remaining
+width with a zero minimum. The shell has a minimum height of one viewport.
+At widths of 1023px or less, the layout becomes one column and Sidebar is
+hidden. The product must provide access to navigation at that width, for
+example through a [Drawer](drawer.md).
+
+## States
+
+The shell stays in place while page content loads, fails, or becomes empty.
+Those states belong inside AppShellMain. There is no disabled or active shell.
+
+## Accessibility
+
+- Use one main landmark for the page. Do not nest another `main` inside
+  AppShellMain.
+- Give the Sidebar's navigation an accessible name and provide a skip link to
+  the main content.
+- Keep navigation available when the Sidebar is hidden. AppShell does not
+  create a mobile menu or manage its focus.
+
+### Keyboard
+
+No shell keymap. Tab follows the controls in DOM order; navigation and Drawer
+retain their own keyboard behavior.
+
+## When to use
+
+- An application with persistent navigation beside a changing page.
+- A console containing tables, detail panes, and logs in its main column.
+
+## When NOT to use
+
+- A standalone login or centered form. Use [Card](card.md) within the page.
+- Two resizable content panes. Use [Split](split.md) inside the main content.
+
+## Radix/shadcn mapping
+
+No dedicated Radix primitive. Compose Sidebar and a semantic main region.
+AppShell supplies Kiso's column layout; it does not add a Sidebar provider,
+routing, or collapse state.

package/kiso/docs/components/brand-mark.md

@@ -0,0 +1,43 @@
+# BrandMark
+
+## Purpose
+
+BrandMark is the small rounded square next to a product name in a sidebar or
+login header. It holds a letter or a single inline SVG. The self-host console
+uses the momoi-labs terminal prompt logo, as shown in
+[self-host PR #48](https://github.com/momoi-labs/self-host/pull/48).
+
+## Anatomy and variants
+
+- A decorative `span` with the existing `.brand-mark` class.
+- Letter content, such as "S", keeps the class's font weight and font size.
+- Icon content uses `.icon.icon-sm`. The icon inherits `currentColor`, has no
+  fill, and uses a 1.75 stroke width with round caps and joins.
+- The adjacent product name supplies the accessible name.
+
+In React, pass either content through `children`, as with Button and Badge.
+BrandMark adds the icon classes to an element child without an extra wrapper.
+Custom icon components must forward `className` to their inline SVG.
+
+`TerminalIcon` supplies the momoi-labs `>_` glyph on a 16 by 16 viewBox. Its
+paths are `M4 4.5L8 8l-4 3.5` and `M9.5 11.5H13`.
+
+## States and accessibility
+
+BrandMark is static and always has `aria-hidden="true"`, including when a
+consumer passes a different value. Keep the product name visible beside it.
+Do not put interactive or focusable content inside the mark. If the brand
+navigates, wrap the mark and product name together in a Link.
+
+## Token consumption
+
+The existing `.brand-mark` CSS remains unchanged. Grid placement centers the
+content; `--size-control-sm` sets both dimensions and `--radius-lg` rounds the
+corners. The background uses `--color-primary` and the foreground uses
+`--color-primary-foreground`. Letter typography uses `--type-weight-bold` and
+`--type-size-label`; icon dimensions use `--size-icon-sm`.
+
+## Radix/shadcn mapping
+
+There is no dedicated behavioral primitive. The React implementation uses
+Radix Slot to merge icon classes onto the child SVG.

package/kiso/docs/components/dot.md

@@ -0,0 +1,69 @@
+# Dot
+
+## Purpose
+
+Dot adds a small decorative status cue beside text. [Badge](badge.md) carries
+a status label; Dot supplies only the colored mark. Keep readable status text
+beside it, whether inside a Badge or elsewhere in the row.
+
+## Anatomy
+
+A single `span`, hidden from assistive technology with `aria-hidden="true"`.
+An optional pulse adds a halo behind the mark. Dot contains no label or control.
+
+## Variants
+
+Status is spelled `variant`, matching Badge.
+
+| Variant | Meaning | Color |
+| --- | --- | --- |
+| `neutral` (default) | No severity. | Inherits `currentColor` from its context. |
+| `info` | Informational state. | `--color-info` |
+| `success` | Healthy or complete. | `--color-success` |
+| `warning` | Needs attention. | `--color-warning` |
+| `danger` | Failed or blocked. | `--color-danger` |
+
+`pulse` defaults to `false`. Enable it only for a live activity cue that the
+adjacent text also explains. The halo uses `currentColor` and a two-second
+animation with `--motion-easing-standard`.
+
+## Sizes
+
+`size="md"` is the default 6px mark; `size="lg"` is 8px. Both use
+`--radius-full` and do not shrink in a flex row. These are visual marks,
+not pointer targets.
+
+## States
+
+The mark is static unless `pulse` is enabled. A status change updates the
+variant and accompanying text together. There are no hover, focus, active,
+or disabled states.
+
+## Accessibility
+
+- Keep Dot decorative. Do not use it as the only indication of status or
+  override its hidden semantics to make an icon-only status label.
+- Communicate status and activity with text; color and motion are extra cues.
+- Respect reduced-motion preferences by leaving `pulse` off for those users.
+  Dot does not detect the preference itself.
+- Necessary status announcements belong to the surrounding region, not Dot.
+
+### Keyboard
+
+No keymap and no tab stop. Dot is never an action.
+
+## When to use
+
+- A health cue beside "Running", "Degraded", or "Stopped".
+- A decorative mark inside a Badge that already names the state.
+
+## When NOT to use
+
+- A status with no accompanying text. Use Badge with a label.
+- Notification counts or clickable indicators.
+- Indeterminate work that needs a loading indicator. Use [Spinner](spinner.md).
+
+## Radix/shadcn mapping
+
+No dedicated Dot primitive. A decorative span consumes Kiso status colors;
+Badge remains the reference for variant names and meanings.

package/kiso/docs/components/kv.md

@@ -0,0 +1,67 @@
+# KV
+
+## Purpose
+
+KV presents named facts about one object, such as its region, image, and
+restart policy. A description list expresses the relationship between each
+term and its value without implying tabular records.
+
+## Anatomy
+
+```
+KV (dl)
+├── KVKey (dt)
+├── KVValue (dd)
+└── further key/value pairs
+```
+
+Keep keys and values as direct children, in reading order. Each key names the
+fact described by the following value. Values can contain text, a
+[Badge](badge.md), or a [Link](link.md).
+
+## Variants
+
+One description-list layout. No variant prop.
+
+## Sizes
+
+One size. The key column has a 96px minimum and grows with its content; the
+value column takes remaining space with a zero minimum. Row and column gaps
+use `--spacing-sm` and `--spacing-lg`. Keys use
+`--color-muted-foreground` and `--type-size-label`; values use `--font-mono`
+and `--type-size-label`. Long values wrap anywhere to stay within the column.
+
+## States
+
+Static facts have no hover, active, or disabled state. The product supplies
+loading placeholders and explicit unknown or unavailable values. Keep the
+key visible when a value is missing so the reader knows which fact is absent.
+
+## Accessibility
+
+Preserve native `dl`, `dt`, and `dd` semantics. Do not replace them with generic
+containers or table roles just to align text. The list describes one object;
+it has no column headers, row selection, or sorting. Name any controls within
+a value according to their own contracts.
+
+### Keyboard
+
+No list keymap or tab stop. Links and controls inside values remain in normal
+tab order.
+
+## When to use
+
+- Fixed facts in a resource detail pane.
+- Configuration summaries that the reader scans by name.
+
+## When NOT to use
+
+- Repeated records with the same fields across columns. Use [Table](table.md).
+- Editable settings. Compose [FormField](form-field.md) and controls.
+- One prominent metric and its trend. Use [Stat](stat.md).
+
+## Radix/shadcn mapping
+
+No dedicated primitive. Use native HTML description-list semantics with Kiso's
+layout and typography. A two-column shadcn Table is not a substitute for a
+list of facts about one object.

package/kiso/docs/components/log-view.md

@@ -0,0 +1,91 @@
+# LogView
+
+## Purpose
+
+LogView displays log lines in a bounded, scrollable frame and follows new
+output while the reader stays at the end. It owns the scroller and follow-tail
+behavior; the product owns the log source and any toolbar controls.
+
+## Anatomy
+
+```
+LogView (frame)
+└── internal scroller
+    └── LogViewLine (repeated)
+        ├── LogViewTime (optional)
+        ├── LogViewLevel (optional)
+        └── message
+```
+
+Set height on LogView. Its internal scroller takes the available space and
+owns overflow. Do not add a second scrolling wrapper around the lines. Root
+props target the frame; the ref exposes a handle, not its DOM element.
+Time and level slots accept text supplied by the product.
+
+## Variants
+
+LogView has one dark log treatment. LogViewLevel uses `level`, with `info`
+(default), `warn`, and `error` mapped to `--color-info-on-dark`,
+`--color-warning-on-dark`, and `--color-danger-on-dark`. Include readable level
+text such as "WARN"; the component does not generate it from the prop.
+
+## Sizes
+
+No size variants. The product chooses the frame height. The frame uses
+`--color-neutral-950`, text `--color-neutral-300`, `--color-border`,
+`--radius-surface`, and `--spacing-md` padding. Log text uses `--font-mono`,
+`--type-size-label`, and `--type-line-height-relaxed`. Timestamps use
+`--color-neutral-600` with `--spacing-sm` after them.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| following (initial default) | Changed children scroll to the end before paint. |
+| reading older output | Scrolling away from the bottom pauses automatic following. |
+| returned to end | Scrolling within 8px of the bottom resumes uncontrolled following. |
+| controlled | `follow` determines whether child updates scroll to the end. |
+
+Omit `follow` for internal state. To connect a Follow switch, pass `follow` and
+update it in `onFollowChange`. The callback reports whether scrolling reaches
+or leaves the bottom; the product must apply that value in controlled mode.
+`follow=false` prevents automatic following even at the bottom.
+
+The `LogViewHandle` ref exposes `scrollToBottom(behavior?: ScrollBehavior)`
+for a "Jump to end" action. This scrolls the internal element; it does not set
+a controlled `follow` value. Turning `follow` on also moves to the end.
+
+The product supplies empty, loading, disconnected, and failed-source states.
+A line at `level="error"` describes log content, not a failure of LogView.
+
+## Accessibility
+
+Use an accessible label for the surrounding log region and visible labels for
+Follow and Jump to end controls. Keep timestamps and levels readable as text.
+LogView does not assign `role="log"`, a live region, or a tab stop by default.
+Choose announcement behavior for the task; announcing every line of a busy
+stream can overwhelm the reader. Verify keyboard access to the internal
+scroller in the target browser. Root props do not configure that scroller.
+
+### Keyboard
+
+No custom keymap. Scrolling uses browser behavior when the scroller is focused.
+Follow and Jump to end use their Switch and Button keyboard contracts.
+
+## When to use
+
+- A bounded stream of operational output beside configuration or resource details.
+- Log history where readers can pause following by scrolling back.
+
+## When NOT to use
+
+- Unbounded datasets requiring virtualization. LogView renders every supplied
+  child; the product must bound retention or choose a virtualized viewer.
+- An editable terminal or command input. LogView does not emulate a terminal.
+- Search, filtering, parsing, or fetching log data. Those belong to the product.
+
+## Radix/shadcn mapping
+
+No dedicated log primitive. Kiso uses a native internal overflow scroller and
+owns follow-tail state. A ScrollArea alone does not provide that behavior or
+the `LogViewHandle` contract.

package/kiso/docs/components/separator.md

@@ -0,0 +1,58 @@
+# Separator
+
+## Purpose
+
+Separator draws a rule between adjacent content or controls. It can mark a
+semantic section break when that boundary is not already expressed by markup.
+
+## Anatomy
+
+A single rule with no children. Use `orientation` to choose its axis and
+`decorative` to choose whether it carries separator semantics.
+
+## Variants
+
+| Prop | Values | Meaning |
+| --- | --- | --- |
+| `orientation` | `horizontal` (default), `vertical` | Direction of the rule. |
+| `decorative` | `true` (default), `false` | Visual-only rule or semantic content boundary. |
+
+## Sizes
+
+A horizontal rule is 1px high. A vertical rule is 1px wide and stretches along
+the parent's cross axis; its container must provide a height. Both consume
+`--color-border`. Spacing around the rule belongs to its parent.
+
+## States
+
+Static. No hover, focus, active, disabled, loading, or error state.
+
+## Accessibility
+
+With `decorative=true`, the rule has no separator semantics. Use this when
+headings, sections, or groups already express the boundary.
+
+Set `decorative=false` when the rule itself communicates a meaningful break
+between content sections. Hiding that boundary would remove information for
+screen-reader users. Radix supplies `role="separator"` and the appropriate
+orientation semantics. Neither mode is focusable or resizable.
+
+### Keyboard
+
+No keymap and no tab stop.
+
+## When to use
+
+- A quiet visual boundary between groups in a toolbar or detail view.
+- A thematic break between content sections with `decorative=false`.
+
+## When NOT to use
+
+- A draggable pane boundary. Use [Split / Splitter](split.md).
+- A box around a content unit. Use [Card](card.md).
+- Every list row when spacing already makes the grouping clear.
+
+## Radix/shadcn mapping
+
+Uses Radix Separator, as does shadcn Separator. Kiso maps horizontal and
+vertical orientations to its rule classes and defaults to decorative mode.

package/kiso/docs/components/split.md

@@ -0,0 +1,93 @@
+# Split / Pane / Splitter
+
+## Purpose
+
+Split places related content side by side and lets the reader allocate width
+between panes. Use it for a list and its detail, or configuration beside logs.
+Two [Cards](card.md) group separate content; Split expresses a shared workspace
+whose divider changes the space available to each side.
+
+## Anatomy
+
+```
+Split
+├── Pane (sized by Splitter)
+├── Splitter
+└── Pane (fills remaining space)
+```
+
+Keep the parts as direct siblings. Splitter owns the size and writes a
+percentage `flex-basis` onto the preceding Pane. The second Pane must fill
+the remaining width, using the `grow` class in the React composition. Pane has
+a zero minimum width and owns overflow scrolling. The product sets the layout
+height and pane padding.
+
+## Variants
+
+One horizontal arrangement of panes with a vertical divider. There is no
+orientation prop or stacked resize mode. Omitting Splitter produces a static
+split whose sizes belong to the product.
+
+## Sizes
+
+| Splitter prop | Default | Contract |
+| --- | --- | --- |
+| `defaultSize` | `50` | Initial preceding-pane basis, as a percentage of Split width. |
+| `min` | `25` | Lower bound for resize operations, in percent. |
+| `max` | `75` | Upper bound for resize operations, in percent. |
+| `step` | `2` | Percentage points moved by each arrow key press. |
+
+Supply bounds within 0 to 100, `min <= defaultSize <= max`, and a positive
+`step`. The initial value is used as supplied; resize operations clamp to the
+bounds. `defaultSize` initializes internal state and is not a controlled size
+prop. `onSizeChange(size)` reports changed percentages for optional product
+persistence; the product can restore a saved value as `defaultSize` on mount.
+
+The divider is 1px wide with an expanded pointer area. It consumes
+`--color-border`, changing to `--color-ring` on hover or drag.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | The preceding Pane uses the current percentage. |
+| hover | The divider highlights and shows the column-resize cursor. |
+| dragging | Pointer capture keeps resizing active outside the divider until release or cancellation. |
+| focus | The divider remains keyboard operable and must have a visible focus indicator. |
+| at a bound | Further movement toward that bound leaves the size unchanged. |
+
+No disabled, loading, or error state. Content inside each Pane owns those states.
+
+## Accessibility
+
+Splitter is a focusable `role="separator"` with `aria-orientation="vertical"`.
+It exposes `aria-valuemin`, `aria-valuemax`, and a rounded `aria-valuenow`.
+Its default accessible name is "Resize panes"; use a more specific `aria-label`
+when the page has several splits. Keep the separator exposed to assistive
+technology. A resizable divider is not decorative.
+
+### Keyboard
+
+| Key | Result |
+| --- | --- |
+| Tab | Focus or leave the divider in normal tab order. |
+| ArrowLeft / ArrowRight | Decrease / increase the preceding Pane by `step`. |
+| Home / End | Set the preceding Pane to `min` / `max`. |
+
+## When to use
+
+- A list-detail workspace where the reader needs more room on either side.
+- Configuration and output that remain visible together.
+
+## When NOT to use
+
+- Independent summary tiles. Use Cards in a grid.
+- A static dividing rule. Use [Separator](separator.md).
+- A narrow viewport that cannot fit both panes. The product must choose an
+  appropriate single-pane flow; Split does not collapse automatically.
+
+## Radix/shadcn mapping
+
+No Radix resize primitive. shadcn Resizable is a behavioral reference, but
+Kiso's Splitter owns its percentage directly. It does not expose panel-group
+state, vertical layouts, or collapsible panels.

package/kiso/docs/components/stat.md

@@ -0,0 +1,85 @@
+# Stat
+
+## Purpose
+
+Stat presents one named metric with an optional change and context. It supplies
+the metric layout and typography. [Card](card.md) supplies the surrounding
+surface and border when the metric needs a tile.
+
+## Anatomy
+
+```
+Stat
+├── StatHeader
+│   ├── StatLabel (required)
+│   └── StatDelta (optional)
+├── StatValue (required)
+└── StatFoot (optional)
+```
+
+StatHeader puts the label and delta on one line. StatValue includes the value
+and any unit needed to read it. StatFoot explains the time window, baseline,
+or supporting fact. StatDelta accepts content; the product supplies its sign,
+arrow, number, and unit.
+
+## Variants
+
+Stat has no variants. StatDelta uses the same `variant` names as
+[Badge](badge.md), with an outline badge treatment.
+
+| StatDelta variant | Meaning | Color token |
+| --- | --- | --- |
+| `neutral` (default) | Change without a judgment of health. | `--color-foreground` |
+| `info` | Informational change. | `--color-info` |
+| `success` | A beneficial or healthy change. | `--color-success` |
+| `warning` | A change needing attention. | `--color-warning` |
+| `danger` | A harmful or failed condition. | `--color-danger` |
+
+Direction does not determine severity. Lower latency can be `success`; fewer
+successful requests can be `danger`. State the direction and comparison in
+text so color is not the only explanation.
+
+## Sizes
+
+One size. Stat uses `--spacing-lg` padding and `--spacing-2xs` between slots.
+The label and foot use `--type-size-label` and `--color-muted-foreground`.
+The value uses `--type-size-display`, `--type-weight-semibold`,
+`--type-line-height-tight`, `--type-letter-spacing-display`, and tabular
+numerals. The foot has `--spacing-sm` above it. Delta uses
+`--type-size-metadata`, `--type-weight-medium`, and `--spacing-xs` between
+its content parts.
+
+## States
+
+The default is a readable metric. The product replaces unknown values with
+[Skeleton](skeleton.md), describes unavailable data explicitly, and supplies
+stale or error context. Do not display zero as a substitute for missing data.
+Stat has no interactive or disabled state.
+
+## Accessibility
+
+The root and header are `div` elements; the text slots are `span` elements.
+Keep the label, value, and comparison together in reading order. Include units
+and time windows in text. Decorative arrows are hidden from assistive
+technology. Stat does not create a live region; announce updates only when
+the task needs them.
+
+### Keyboard
+
+No keymap. Any accompanying action uses its own Button or Link.
+
+## When to use
+
+- A dashboard metric with a label, value, and comparison period.
+- A compact summary inside a Card or an existing section.
+
+## When NOT to use
+
+- Comparing many records across columns. Use [Table](table.md).
+- A set of descriptive facts about one object. Use [KV](kv.md).
+- A status without a metric. Use Badge.
+
+## Radix/shadcn mapping
+
+No dedicated Radix or shadcn Stat primitive. Compose metric text and Badge
+visuals, with Card supplying an optional outer surface.

package/kiso/docs/tokens.md

@@ -76,7 +76,7 @@ outline — which is how a violet design system ends up rendering grey.
 | `secondary` | Neutral button fill, range track, count badge; never text. | `neutral.700` | `neutral.300` |
 | `secondary-foreground` | Text on a `secondary` fill. | `foreground` | `foreground` |
 | `secondary-hover` | `secondary` fill on hover; never text. | `neutral.600` | `neutral.400` |
-| `selected` | Selected row, active nav item, highlighted result; never text. | `accent.900` | `accent.200` |
+| `selected` | Selected row, active nav item, highlighted result; never text. One step past `accent-surface-hover`, so selection and hover stay apart. | `accent.800` | `accent.300` |
 | `selected-foreground` | Text on a `selected` fill. | `foreground` | `foreground` |
 
 `primary-foreground` and `danger-foreground` invert with their fill: near-black

package/kiso/ui.css

@@ -745,6 +745,7 @@ table.table { width: 100%; border-collapse: collapse; font-size: var(--type-size
 .nav-group { display: grid; gap: var(--spacing-2xs); }
 .nav-group > .t-caps { padding-inline: var(--spacing-sm); margin-block-end: var(--spacing-2xs); }
 .nav-item {
+  position: relative; /* the current marker is drawn beside the item */
   display: flex; align-items: center; gap: var(--spacing-sm);
   height: var(--size-control-sm);
   padding-inline: var(--spacing-sm);
@@ -758,15 +759,53 @@ table.table { width: 100%; border-collapse: collapse; font-size: var(--type-size
 }
 .nav-item .icon { color: var(--color-subtle-foreground); }
 .nav-item:hover { background: var(--color-accent-surface-hover); color: var(--color-foreground); text-decoration: none; }
+
+/* The current destination is marked beside the item rather than on it. A fill
+   would put "current" and "hovered" in the same language, one tint apart, in a
+   column where the pointer is usually resting on some other item. Leaving the
+   fill to hover keeps the two signals different in kind, and it gives the
+   marker the one thing a rail needs and a floating pill cannot offer — an edge
+   shared with every sibling, which in a column is the gutter. */
 .nav-item[aria-current="page"], .nav-item.active {
-  background: var(--color-selected);
-  box-shadow: inset 2px 0 0 var(--color-primary);
   color: var(--color-selected-foreground);
   font-weight: var(--type-weight-medium);
 }
+.nav-item[aria-current="page"]::before, .nav-item.active::before {
+  content: "";
+  position: absolute;
+  inset-inline-start: calc(-1 * var(--spacing-sm)); /* the sidebar's own padding */
+  inset-block: 2px;
+  width: 2px;
+  border-radius: var(--radius-full);
+  background: var(--color-primary);
+}
 .nav-item[aria-current="page"] .icon, .nav-item.active .icon { color: currentColor; }
 .nav-item .badge { margin-inline-start: auto; }
 
+/* Navigation laid out in a row. The shared edge is now the bottom, so the same
+   marker moves there and the row grows a baseline for it to sit on — the
+   arrangement `.tabs` already uses. Without this the rail points at a gutter
+   that a horizontal row does not have. */
+.nav-row {
+  display: flex; gap: var(--spacing-lg);
+  margin: 0; padding: 0; list-style: none;
+  border-bottom: 1px solid var(--color-border);
+}
+.nav-row .nav-item {
+  width: auto;
+  height: var(--size-control-lg);
+  padding-inline: 0;
+  border-radius: 0;
+}
+.nav-row .nav-item:hover { background: none; color: var(--color-foreground); }
+.nav-row .nav-item[aria-current="page"]::before, .nav-row .nav-item.active::before {
+  inset-inline: 0;
+  inset-block: auto;
+  bottom: -1px;
+  width: auto;
+  height: 2px;
+}
+
 .brand { display: flex; align-items: center; gap: var(--spacing-sm); min-width: 0; }
 .brand-mark {
   display: grid; place-items: center;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@momoi-labs/kiso",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Kiso design-system contracts and generated design tokens",
   "license": "MIT",
   "repository": {

package/tokens/build/tokens.css

@@ -59,7 +59,7 @@
   --color-link: var(--color-primary);
   --color-accent-surface: light-dark(var(--color-accent-50), var(--color-accent-950));
   --color-accent-surface-hover: light-dark(var(--color-accent-200), var(--color-accent-900));
-  --color-selected: light-dark(var(--color-accent-200), var(--color-accent-900));
+  --color-selected: light-dark(var(--color-accent-300), var(--color-accent-800));
   --color-selected-foreground: var(--color-foreground);
   --color-secondary: light-dark(var(--color-neutral-300), var(--color-neutral-700));
   --color-secondary-foreground: var(--color-foreground);

package/tokens/build/tokens.d.ts

@@ -100,7 +100,7 @@ export const semanticLink: string;
 export const semanticAccentSurface: string;
 /** Accent tint one step stronger. Non-text role. */
 export const semanticAccentSurfaceHover: string;
-/** Selected row, active navigation item, highlighted palette result. Non-text role. */
+/** Selected row, active navigation item, highlighted palette result. One ramp step past accent-surface-hover, so a selected item and a hovered sibling never paint the same surface. Non-text role. */
 export const semanticSelected: string;
 /** Text on a selected row. */
 export const semanticSelectedForeground: string;

package/tokens/build/tokens.json

@@ -56,7 +56,7 @@
   "semantic-link": {"colorSpace":"srgb","components":[0.7961,0.7412,0.9686],"hex":"#cbbdf7"},
   "semantic-accent-surface": {"colorSpace":"srgb","components":[0.1294,0.0902,0.2549],"hex":"#211741"},
   "semantic-accent-surface-hover": {"colorSpace":"srgb","components":[0.1804,0.1294,0.4392],"hex":"#2e2170"},
-  "semantic-selected": {"colorSpace":"srgb","components":[0.1804,0.1294,0.4392],"hex":"#2e2170"},
+  "semantic-selected": {"colorSpace":"srgb","components":[0.2745,0.1882,0.6196],"hex":"#46309e"},
   "semantic-selected-foreground": {"colorSpace":"srgb","components":[0.9804,0.9765,0.9686],"hex":"#faf9f7"},
   "semantic-secondary": {"colorSpace":"srgb","components":[0.1922,0.1843,0.2157],"hex":"#312f37"},
   "semantic-secondary-foreground": {"colorSpace":"srgb","components":[0.9804,0.9765,0.9686],"hex":"#faf9f7"},

package/tokens/build/tokens.scss

@@ -58,7 +58,7 @@ $semantic-primary-hover: #ded5fb; // Primary fill on hover — one ramp step awa
 $semantic-link: #cbbdf7; // Inline and standalone links.
 $semantic-accent-surface: #211741; // Faintest accent tint: row hover, ghost-button hover. Non-text role.
 $semantic-accent-surface-hover: #2e2170; // Accent tint one step stronger. Non-text role.
-$semantic-selected: #2e2170; // Selected row, active navigation item, highlighted palette result. Non-text role.
+$semantic-selected: #46309e; // Selected row, active navigation item, highlighted palette result. One ramp step past accent-surface-hover, so a selected item and a hovered sibling never paint the same surface. Non-text role.
 $semantic-selected-foreground: #faf9f7; // Text on a selected row.
 $semantic-secondary: #312f37; // Neutral button fill, range track, count badge. Non-text role.
 $semantic-secondary-foreground: #faf9f7; // Text on a secondary fill.