@momoi-labs/kiso 0.1.0

package/kiso/docs/components/sidebar.md

@@ -0,0 +1,74 @@
+# Sidebar
+
+A persistent navigation region for products with several destinations or
+collapsible groups.
+
+## Purpose
+
+Sidebar makes a broad product structure scannable without turning the Header
+into a menu bar. It is a layout container whose items remain Links; disclosure
+controls only expand or collapse sections.
+
+## Anatomy
+
+```
+Sidebar
+├── label (accessible, may be visually hidden)
+├── Navigation
+│   ├── Link(s)
+│   └── section(s)
+│       ├── disclosure Button
+│       └── Link(s)
+└── collapse control (optional IconButton)
+```
+
+Surface uses `--color-surface`, divider `--color-border`, primary text
+`--color-foreground`, and current items `--color-primary`. Layout uses
+`--spacing-sm` between items, `--spacing-md` section gaps, and the five
+property-qualified label typography tokens.
+
+## Variants
+
+No visual variants. Sidebar has one navigation treatment; expanded and
+collapsed are states of the same component, not separate variants.
+
+## Sizes
+
+No `sm` / `md` / `lg` sizes. Width belongs to the host layout, and internal
+spacing uses semantic tokens without changing Link or disclosure-control sizes.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | Expanded groups and their current state are visible. |
+| hover | Interactive children own hover feedback. |
+| focus | Links and disclosure controls show `--color-focus`. |
+| active | Current destination has `aria-current="page"`; expanded disclosures have `aria-expanded="true"`. |
+| disabled | Sidebar is not disabled; omit unavailable destinations or explain them adjacent to a disabled child. |
+| collapsed | Sections reduce to an explicit compact navigation; essential labels must remain available without Tooltip. |
+
+## Accessibility
+
+Wrap the links in a labelled `<nav>`. Use real Buttons with `aria-expanded`
+and `aria-controls` for section disclosures. Collapsing the whole Sidebar must
+not strand focus in hidden content; move it to the collapse control. Keep DOM
+and visual order aligned. `Tab` moves among controls; `Enter`/`Space` toggles a
+focused disclosure; Links retain native behavior.
+
+## When to use
+
+- Products with several stable top-level destinations or grouped sections.
+- Dense technical tools where persistent wayfinding reduces context switching.
+
+## When NOT to use
+
+- A handful of global destinations that fit in [Header](header.md).
+- A hierarchical path to the current page; use [Breadcrumb](breadcrumb.md).
+- Temporary controls unrelated to navigation.
+
+## Radix/shadcn mapping
+
+No Radix Sidebar primitive. shadcn Sidebar is a structural reference, but Kiso
+keeps native nav/Link semantics and semantic tokens. Disclosure behavior may
+use Radix Collapsible / shadcn Collapsible.

package/kiso/docs/components/skeleton.md

@@ -0,0 +1,140 @@
+# Skeleton
+
+A layout-preserving loading placeholder. It occupies the space of the
+content that will arrive, so the page does not jump.
+
+## Purpose
+
+Skeleton is for *known* structure and *unknown* data: the table will have
+rows, the Card will have a title and two lines, the form will have four
+fields. Draw that shape now; swap in the real content when it exists.
+
+User story #22: [Spinner](spinner.md) is indeterminate; Skeleton preserves
+layout.
+
+Table/DataTable (data slice) composes Skeleton for loading rows, together
+with [EmptyState](empty-state.md) (no data) and [Pagination](pagination.md)
+(known data). This doc defines the
+placeholder; it does not define the table.
+
+## Anatomy
+
+```
+Skeleton (one placeholder)
+└── shape (text line | block | circle)
+
+Region (the thing that is loading)
+├── aria-busy="true"
+├── accessible name / live status ("Loading replicas")
+└── one or more Skeletons matching the eventual layout
+```
+
+- **Shape.** Geometric stand-in. No letters, no shimmering brand mark, no
+  fake data.
+- **Region.** The parent is the accessible loading state. Individual
+  Skeletons are decorative.
+
+## Variants
+
+Variants are shapes, not colors.
+
+| Variant | Shape tokens | Stands in for |
+| --- | --- | --- |
+| `text` | Height of the target role's `--type-role-body-line-height`, `--type-role-label-line-height`, or `--type-role-heading-line-height`; width a fraction of the column; radius `--radius-sm` | Titles, labels, table cells, descriptions. |
+| `block` | Radius `--radius-md` (or `--radius-lg` when replacing a Card) | Cards, images, chart frames, table bodies as a whole. |
+| `circle` | Radius `--radius-full`, equal width and height | Avatars and circular IconButtons. |
+
+Fill is `--color-border` on the surrounding `--color-surface` or
+`--color-background` (whichever the real content sits on). Do not use
+`--color-primary` or status colors — loading is not a status.
+
+Pulse (if any) interpolates opacity between the fill and `--color-surface`
+using `--motion-duration-normal` and `--motion-easing-standard`.
+
+**Reduced motion:** no pulse. Static `--color-border` placeholders. The
+tokens already zero out `--motion-duration-fast` and
+`--motion-duration-normal`; do not add a second
+animation that ignores them.
+
+## Sizes
+
+Skeleton has no independent size scale. It **matches the content it
+replaces**:
+
+| Replacing | Skeleton |
+| --- | --- |
+| Body line | `text` at `--type-role-body-line-height`, width ~ ⅔ of the column |
+| Label / heading | `text` at that role's height, shorter width |
+| Button | `block` with the Button size's padding box |
+| Table row | A row of `text` cells aligned to column widths |
+| Card | Header `text` + Content `block` or stacked `text` |
+
+Approximate widths are layout choices, not new tokens. Do not specify
+placeholder geometry in raw pixels; size against type roles and spacing.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | Visible placeholder while `aria-busy` is true. |
+| hover / focus / active | N/A. Skeletons are not controls and must not be in the tab order. |
+| disabled | N/A. |
+| loading | Skeleton *is* the loading presentation. |
+| error | Remove Skeletons; show [Alert](alert.md) (and optionally a retry Button). Do not leave placeholders up after failure. |
+
+When data arrives, replace the Skeleton region with the real content in
+one swap. Do not leave a Skeleton sitting next to the loaded widget.
+
+## Accessibility
+
+- Each Skeleton graphic is `aria-hidden="true"`.
+- The **region** communicates loading: `aria-busy="true"` and a polite
+  status (`role="status"` or `aria-live="polite"`) with a short label
+  ("Loading queries"). Announce once, not once per row.
+- Do not put focus inside the placeholder. Focus stays on the control that
+  triggered the load, or on the page heading for initial page load.
+- When loading finishes, set `aria-busy="false"` and let the status
+  announce completion only if the person would otherwise miss it (e.g.
+  the region was empty). Prefer the content itself over a "Done loading"
+  toast.
+- Skeleton is not a progressbar.
+
+### Keyboard
+
+No keymap. Placeholders are skipped.
+
+## When to use
+
+- First load of a list, table, Card, or form whose structure is known.
+- Pagination and refetch of Table/DataTable rows (compose Skeleton rows
+  in place of data rows; keep table chrome).
+- Replacing a known block inside a Card while the rest of the page stays
+  put.
+
+## When NOT to use
+
+- **Indeterminate, structure-unknown waits** (submit, connect, a one-off
+  action). [Spinner](spinner.md), usually inside the Button.
+- **Empty results.** That is EmptyState, not an eternal Skeleton.
+- **Errors.** Alert, not a grey box.
+- **Content that is already on screen.** Do not skeletonize a field the
+  person is editing.
+- **Fake completed UI.** Never put real-looking numbers or names in a
+  Skeleton; placeholders stay empty shapes.
+
+## Radix/shadcn mapping
+
+No Radix Skeleton primitive.
+
+| Kiso | Reference |
+| --- | --- |
+| Placeholder primitive | shadcn [Skeleton](https://ui.shadcn.com/docs/components/skeleton) |
+| Table rows | shadcn Skeleton "Table" example — restyle to `--color-border` / `--color-surface` and type-role heights |
+| Card / text / avatar | shadcn Card / Text / Avatar examples as shape references only |
+
+Do not copy shadcn examples that set raw pixel widths. Map height to type
+roles and padding to one of `--spacing-xs`, `--spacing-sm`, `--spacing-md`,
+`--spacing-lg`, or `--spacing-xl`, matching the content being replaced.
+
+Compose with Table/DataTable in the data slice: loading → Skeleton rows;
+empty → EmptyState; error → Alert; populated → rows + Pagination.

package/kiso/docs/components/spinner.md

@@ -0,0 +1,125 @@
+# Spinner
+
+An indeterminate loading indicator. It tells the person that work is
+happening when the shape or duration of the result is not yet known.
+
+## Purpose
+
+Spinner is for *unknown* progress: a request has started, there is nothing
+honest to draw yet, and the person must wait.
+
+User story #22: Spinner is indeterminate; [Skeleton](skeleton.md) is
+layout-preserving. If you already know the layout of what will appear
+(table rows, a Card body, a form), use Skeleton. If you do not (a
+submission, a reconnect, a short inline wait inside a Button), use Spinner.
+
+## Anatomy
+
+```
+Spinner
+├── graphic (required)
+└── label (required in accessible name; visible when the wait is the
+    primary thing on screen)
+```
+
+- **Graphic.** A circular (or otherwise looping) indicator. Color
+  `--color-primary` on a track of `--color-border`. It is decorative once
+  the name exists: the accessible name carries "Loading".
+- **Label.** Visible text when Spinner is the main content of a region:
+  "Loading queries…", "Connecting to database…". Follow
+  [voice-and-tone](../voice-and-tone.md): state what is happening, no
+  chatter. When Spinner is inside a Button, the Button label is the name
+  ("Saving…") and the graphic has `aria-hidden="true"`.
+
+## Variants
+
+One visual variant. Meaning comes from placement, not color.
+
+| Placement | Label |
+| --- | --- |
+| Inside [Button](button.md) / [IconButton](icon-button.md) | Button keeps a loading verb; graphic is decorative. |
+| Inline next to a value or [Badge](badge.md) | Visible short word ("syncing") or `aria-label` on the Spinner. |
+| Region / page | Visible label required. Centered in the region, not over unrelated chrome. |
+
+Do not recolor Spinner to `--color-danger` to mean failed — a failed wait
+is an [Alert](alert.md). Do not use `--color-success` to mean done — hide
+the Spinner.
+
+## Sizes
+
+| Size | Scale | Use |
+| --- | --- | --- |
+| `sm` | Matches `--type-role-metadata-font-size` | Inside Button `sm`, Badge, inline meta. |
+| `md` (default) | Matches `--type-role-label-font-size` | Inside Button `md`, IconButton `md`, inline waits. |
+| `lg` | Matches `--type-role-body-font-size` | Region-level wait when layout is unknown. |
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | Animating (unless reduced motion). |
+| hover / focus / active | N/A. Spinner is not a control. |
+| disabled | N/A. |
+| loading | Spinner *is* the loading state of something else. It has no nested loading state. |
+| error | Replace Spinner with [Alert](alert.md). Do not freeze a Spinner as an error cue. |
+
+Motion uses `--motion-duration-normal` and `--motion-easing-standard` for
+fade-in. The spin loop itself is continuous.
+
+**Reduced motion:** the generated tokens set `--motion-duration-fast` and
+`--motion-duration-normal` to `0s`
+under `prefers-reduced-motion: reduce`. A spinning loop with duration zero
+is invisible or broken. In that case show a **static** indicator (the same
+graphic, not rotating) plus the label. Never communicate loading only with
+motion.
+
+## Accessibility
+
+- When the Spinner is the only loading cue in a region: `role="status"`,
+  `aria-live="polite"`, `aria-label` (or visible text) that says what is
+  loading. `aria-busy="true"` on the region that is waiting.
+- When composed inside a busy Button: the Button has `aria-busy="true"`;
+  the graphic is `aria-hidden="true"` so "Loading" is not announced twice.
+- Do not use `role="progressbar"` unless you have a real value. Spinner is
+  indeterminate; a progress bar with no `aria-valuenow` is the wrong
+  promise.
+- Color is not the only cue; the label (visible or `aria-label`) is.
+
+### Keyboard
+
+No keymap. Focus stays on the control that started the wait (the Button),
+or in the region if the whole view is replacing. Do not move focus to the
+Spinner graphic.
+
+## When to use
+
+- A short, indeterminate wait: submitting a form, retrying a connection,
+  refreshing one value.
+- Inside a Button or IconButton loading state (user story #12).
+- A region whose forthcoming layout is genuinely unknown (first paint of a
+  custom view with no stable structure).
+
+## When NOT to use
+
+- **The layout is known.** [Skeleton](skeleton.md) — especially table rows,
+  Card bodies, and form stacks. Table/DataTable (data slice) composes
+  Skeleton for loading rows, not a Spinner over an empty table.
+- **Progress is measurable** (percent, step n of m). Use a determinate
+  progress pattern, not Spinner.
+- **The wait is done or failed.** Hide Spinner; show content or Alert.
+- **Decoration.** A never-ending Spinner next to idle content is a lie.
+- **Blocking the whole app by default.** A page-level Spinner is a last
+  resort when nothing else can render. Prefer Skeleton of the shell.
+
+## Radix/shadcn mapping
+
+No Radix Spinner primitive.
+
+| Kiso | Reference |
+| --- | --- |
+| Graphic + `role="status"` + `aria-label="Loading"` | shadcn [Spinner](https://ui.shadcn.com/docs/components/spinner) |
+| Inside Button | shadcn Button "Spinner" example, composed with Kiso Button loading rules |
+| Size | shadcn size utilities restyled to the type-role matching sizes above, not arbitrary `size-*` pixels |
+
+Replace shadcn's default icon color with `--color-primary`. Honor reduced
+motion as specified above; do not rely on `animate-spin` alone.

package/kiso/docs/components/switch.md

@@ -0,0 +1,92 @@
+# Switch
+
+## Purpose
+
+Switch changes one boolean setting between on and off. The change normally
+takes effect immediately, like a physical switch, rather than waiting for form
+submission.
+
+## Anatomy
+
+1. **Root/track** — focusable control and on/off state owner.
+2. **Thumb** — moves to make state visible; motion is supportive, not the only
+   signal.
+3. **Label** — names the setting, not the action (for example, “Query logging,”
+   not “Enable query logging”).
+4. **Description (optional)** — explains effect or scope.
+
+## Variants
+
+- **Off / on** — the two stable setting values.
+- **With description** — for settings whose effect is not obvious from Label.
+- **Controlled** — application owns state, including persistence and rollback.
+- **Uncontrolled** — primitive owns initial state; use only when persistence and
+  external synchronization are unnecessary.
+
+Switch is one immediate boolean setting. Checkbox is an independent form choice
+or member of a multi-select list; Select chooses one value from many.
+
+## Sizes
+
+- **Small** — dense settings tables, with a full-sized Label target.
+- **Medium** — default.
+
+Track, thumb, and gap scale as a unit with semantic tokens. Do not encode state
+only through thumb position or color; the accessible state remains required.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| Default | Clearly presents off or on state. |
+| Hover | Track/label pair receives quiet interactive emphasis. |
+| Focus | Root has a visible `--color-focus` ring. |
+| Active | Brief pressed feedback; thumb movement uses `--motion-duration-fast` and `--motion-easing-standard`. |
+| Disabled | Cannot toggle and uses `--color-disabled`. |
+| Loading | Retains the intended or confirmed state, shows pending status, and prevents duplicate changes only when necessary. |
+| Error | Persistence failure is explained with `--color-danger` feedback and a recovery action; do not leave the displayed state ambiguous. |
+
+Loading differs from disabled: it communicates an in-progress state change.
+If the request fails, either revert to the confirmed state or retain the choice
+with an explicit retry path.
+
+## Accessibility
+
+- Radix supplies `role="switch"` and `aria-checked`; preserve these semantics.
+- Associate Label using matching `for`/`id` or a single, unambiguous
+  `aria-labelledby` relationship.
+- Expose disabled and busy status. Link description or failure feedback via
+  `aria-describedby`.
+- Keyboard: `Tab` focuses; `Space` toggles. `Enter` may toggle where the
+  primitive/browser contract supports it consistently. Do not require drag.
+- State must be announced as on/off and remain discernible without color or
+  animation. Honor reduced-motion tokens.
+
+## When to use
+
+- For a single preference that applies immediately.
+- In settings surfaces where current on/off state must remain visible.
+- When toggling does not require a separate Save action.
+
+## When NOT to use
+
+- Do not use for a value submitted only with the rest of a form; use Checkbox.
+- Do not use for multiple related selections; use a Checkbox group.
+- Do not use for choosing among three or more values; use Select.
+- Do not use when changing state has a destructive or complex consequence that
+  needs explicit confirmation; use a clearly named action flow.
+
+## Tokens
+
+Use `--color-border`, `--color-surface`, `--color-foreground`,
+`--color-primary`, `--color-focus`, `--color-disabled`, and `--color-danger`,
+plus `--spacing-sm` label gap, `--radius-full`, the five property-qualified
+label typography tokens, `--motion-duration-fast`, and
+`--motion-easing-standard`.
+
+## Radix/shadcn mapping
+
+Maps to [Radix Switch](https://www.radix-ui.com/primitives/docs/components/switch)
+and [shadcn/ui Switch](https://ui.shadcn.com/docs/components/switch). Keep
+Radix's switch role, checked state, form behavior, and keyboard interaction as
+the behavioral reference.