@momoi-labs/kiso 0.1.0

package/kiso/docs/patterns/keyboard-shortcuts.md

@@ -0,0 +1,155 @@
+# Keyboard shortcuts
+
+Discoverable keyboard shortcuts for frequent actions and navigation. This
+pattern governs how shortcuts are defined, invoked, and — critically —
+discovered, so that keyboard efficiency does not become hidden knowledge.
+
+User story #24.
+
+## Purpose
+
+Keyboard shortcuts let a person who prefers the keyboard move faster: jump to
+search, open the [command palette](command-palette.md), create a new record,
+refresh, navigate rows. They are acceleration on top of visible controls, never
+the only path to an action.
+
+The central problem is **discoverability**. A shortcut that no one knows exists
+does not exist. This pattern mandates a discoverability mechanism so shortcuts
+are findable without reading documentation.
+
+## Component composition
+
+| Region | Compose with | Role |
+| --- | --- | --- |
+| Shortcut hint | inline text or [Tooltip](../components/tooltip.md) near the control | Shows the binding next to the action it triggers |
+| Shortcut legend | [Modal / Dialog](../components/modal-dialog.md) or [Popover](../components/popover.md) opened by `?` | Lists all shortcuts in one place |
+| Command palette | [CommandPalette](../components/command-palette.md) items with shortcut hints | Shortcuts visible where commands live |
+| Footer hints | palette / dialog footer | Reminds `Enter`, `↑↓`, `Esc` |
+
+## Flow
+
+1. Person works in the product with the keyboard.
+2. Person presses `?` (or `Shift+/`) anywhere a shortcut legend is available.
+3. A [Modal / Dialog](../components/modal-dialog.md) or
+   [Popover](../components/popover.md) opens listing shortcuts, grouped by
+   category (Navigation, Actions, Tables).
+4. Person closes the legend (`Escape` or click) and uses a shortcut.
+5. Shortcuts also appear as hints next to their controls (in
+   [DropdownMenu](../components/dropdown-menu.md) items, next to
+   [Button](../components/button.md)s, in the [command palette](command-palette.md)).
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| idle | Shortcuts active but not shown. Person can invoke any binding. |
+| legend open | Shortcut legend visible; focus trapped (if dialog) or moved to the legend. `Escape` closes. |
+| conflict | Two actions claim the same binding. The product must resolve this — the legend shows the winner; the loser gets a different binding or no binding. |
+
+## Layout sketch
+
+### Shortcut legend (`?`)
+
+```text
+┌──────────────────────────────────────────────┐
+│ Keyboard shortcuts                           │
+├──────────────────────────────────────────────┤
+│  Navigation                                  │
+│  ⌘K   Open command palette                   │
+│  ⌘/   Focus search                           │
+│  g r  Go to Replicas                         │
+│  g q  Go to Queries                          │
+│  g s  Go to Settings                         │
+│                                              │
+│  Actions                                     │
+│  c     Create new (context-aware)            │
+│  r     Refresh current view                  │
+│  ⌘S   Save (in an editor)                    │
+│                                              │
+│  Tables                                      │
+│  ↑ ↓  Move between rows                      │
+│  j k  Move between rows (vim)                │
+│  x     Select row                            │
+│  ?     Show this legend                      │
+│                                              │
+│                        [Close]      [Esc]    │
+└──────────────────────────────────────────────┘
+```
+
+### Inline hints
+
+```text
+[DropdownMenu]
+  ▸ New query          ⌘N
+  ▸ Duplicate          ⌘D
+  ▸ Delete             ⌫
+```
+
+Hints appear right-aligned in menu items, in `--color-muted-foreground`. They
+are decorative; the accessible name of the item does not depend on them.
+
+## Rules
+
+### Discoverability (mandatory)
+
+- **Provide a shortcut legend**, opened by `?` (or `Shift+/`). This is the
+  primary discoverability mechanism. Without it, shortcuts are hidden knowledge.
+- **Show hints next to controls** where space allows: in
+  [DropdownMenu](../components/dropdown-menu.md) items, next to
+  [Button](../components/button.md)s in toolbars, and in
+  [command palette](command-palette.md) items.
+- **Mention the legend in onboarding** or first-run help so a new person learns
+  that `?` exists.
+- Do not rely on [Tooltip](../components/tooltip.md) as the only discoverability
+  path — Tooltip is not available on touch and is progressive enhancement.
+
+### Defining shortcuts
+
+- Use platform conventions: `⌘` on macOS, `Ctrl` on Windows/Linux. Single-key
+  shortcuts (no modifier) are allowed for context-specific actions (table row
+  navigation with `j`/`k`) but must not conflict with text entry — only active
+  when the focus is not in a text field.
+- Reserve `⌘K` / `Ctrl+K` for the [command palette](command-palette.md). Do
+  not bind it to list [Search](search.md).
+- Reserve `?` for the shortcut legend. Do not bind it to an action.
+- Do not override browser or OS shortcuts (`⌘W`, `⌘R`, `⌘T`, etc.) unless the
+  product explicitly opts into a contained context (e.g. a code editor) and
+  documents the override.
+- Two-key sequences (like `g` then `r`) are allowed for navigation but must
+  show a brief "waiting for second key" state and time out cleanly.
+
+### Scope
+
+- Global shortcuts (navigation, command palette, legend) work everywhere.
+- Context shortcuts (table row navigation, editor commands) are active only in
+  their context. When the person leaves the context, the binding is released.
+- A shortcut that is context-only should not appear in the global legend as if
+  it were global; group it under its context ("Tables", "Editor").
+
+### Conflicts
+
+- No two actions may share the same binding in the same scope. The product
+  resolves conflicts; the legend shows the winner.
+- If a user-customizable shortcut system exists (future), the legend reflects
+  the current bindings, not the defaults.
+
+## Accessibility
+
+- Shortcuts are keyboard input; they are inherently accessible to keyboard
+  users. Ensure they do not trap focus or override assistive technology
+  behavior.
+- The legend is a real dialog or popover with focus management: focus moves in
+  on open, `Escape` closes, focus returns to the trigger.
+- Shortcut hints in menu items are decorative (`aria-hidden` on the hint text)
+  — the item's accessible name is the action label, not the key combination.
+- Single-key shortcuts must be inert when focus is in a text field, so they do
+  not intercept typing. The exception is `Escape` (which may blur the field or
+  close an overlay).
+- Do not make a shortcut the only way to perform an action. Every shortcut-
+  accessible action has a visible control (button, menu item, link) as well.
+
+## Related patterns
+
+- [Command palette](command-palette.md) — `⌘K` / `Ctrl+K` is the flagship
+  shortcut; the palette lists commands with their hints.
+- [Search](search.md) — a shortcut (`⌘/` or `/`) may focus the Search field.

package/kiso/docs/patterns/large-data-tables.md

@@ -0,0 +1,182 @@
+# Large data tables
+
+Tables with many rows — virtualization, sticky headers, column resize, and
+responsive collapse. This pattern composes [Table / DataTable](../components/table.md)
+for datasets that exceed a comfortable page or viewport, and references
+[data-interfaces.md](../data-interfaces.md) for the data-rendering rules
+(alignment, null/unknown, truncation, dangerous values) that every cell still
+follows.
+
+User story #3.
+
+## Purpose
+
+When a table holds hundreds or thousands of rows — replicas, query history,
+metrics series, log lines — the interaction model shifts. The person scrolls
+through a large loaded set, compares columns across a wide schema, and relies
+on [Search](search.md) + [filtering](filtering.md) to narrow it. This pattern
+governs the table behaviors that make that volume usable: virtualization,
+sticky headers, column resize, and responsive column collapse.
+
+It does **not** redefine how cells render. Numeric alignment, null ≠ 0 ≠
+unknown, truncation with full-value access, and dangerous-value marking are
+defined in [data-interfaces.md](../data-interfaces.md) and apply unchanged
+here. This pattern composes those rules; it does not redefine or override them.
+
+## Component composition
+
+| Concern | Compose with | Role |
+| --- | --- | --- |
+| Grid | [Table / DataTable](../components/table.md) | Structural table with sort, selection, toolbar |
+| Volume | virtualized body (guidance, not a separate component) | Only visible rows mount; header, selection, keyboard stay correct |
+| Sticky header | DataTable `sticky` header behavior | Header stays visible while the body scrolls |
+| Column width | DataTable column resize handle | Person drags to resize; width persisted in product state |
+| Narrowing | [Search](search.md) + [filtering](filtering.md) | Reduce the set the person scrolls through |
+| Paging | [Pagination](pagination.md) or virtualization | Pick one model per surface (see Rules) |
+| Cell rendering | [data-interfaces.md](../data-interfaces.md) rules | Alignment, null/unknown, truncation, dangerous values |
+| Row actions | [DropdownMenu](../components/dropdown-menu.md) | Per-row actions; does not break virtualization |
+| Empty / error | [EmptyState](../components/empty-state.md) / [Alert](../components/alert.md) | Standard states, not special large-table variants |
+
+## Flow
+
+1. Person opens a large table (e.g. 4,000 replicas). The first viewport of rows
+   loads and renders; the rest are virtualized.
+2. The header is sticky: as the person scrolls, column titles remain visible.
+3. The person uses [Search](search.md) and [filtering](filtering.md) to narrow
+   the set. The virtualized body re-renders only visible rows of the filtered
+   set.
+4. The person sorts a column ([sorting](sorting.md)); the virtualized body
+   reorders.
+5. For wide schemas, the person resizes columns or the table collapses
+   secondary columns responsively (see below).
+6. Row actions, selection, and keyboard navigation remain correct throughout
+   scroll, sort, and filter changes.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| loading | [Skeleton](../components/skeleton.md) rows matching column count and approximate viewport size. `aria-busy` on the region. Keep header and toolbar chrome. |
+| populated | Virtualized rows render; only visible rows (plus a small overscan buffer) are mounted. |
+| empty | [EmptyState](../components/empty-state.md) `no-results` or `first-run` in the body. Keep headers. |
+| error | [Alert](../components/alert.md) with retry; remove Skeletons. |
+| scrolling | Sticky header stays aligned with the body. Roving tabindex / `aria-activedescendant` keeps one focused row as the person scrolls. |
+| resizing | Column resize handle drags; minimum width keeps the header label readable. Other columns adjust or scroll. |
+
+## Layout sketch
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ Toolbar                                                              │
+│ [🔍 Search 4,000 replicas...] [Status▾] [Region▾] [Lag range▾]      │
+│ 247 replicas match · sorted by Lag ▼                                 │
+├──────────────────────────────────────────────────────────────────────┤
+│ ↓ sticky header                                                      │
+│ ┌────────────────────────────────────────────────────────────────┐  │
+│ │ Name      Host            Status   Lag ▼   Conn   Region  Ver  │  │
+│ │ replica-1 db.eu.example   ok       12 ms   42     eu      16   │  │
+│ │ replica-2 db.eu.backup    degraded 820 ms  18     eu      16   │  │
+│ │ replica-3 db.eu.dr        ok          —    9      eu      16   │  │
+│ │ replica-4 db.ap.example   ok        4 ms   31     ap      15   │  │
+│ │ ...virtualized...                                              │  │
+│ │ replica-N db.us.example   warn     2.1 s   7      us      14   │  │
+│ └────────────────────────────────────────────────────────────────┘  │
+│ ↑ body scrolls independently; header stays                          │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Responsive collapse
+
+On narrow viewports, collapse columns in a documented priority order — do not
+turn rows into cards. This follows the
+[responsive tables](../data-interfaces.md) rules in data-interfaces.md:
+
+```text
+Wide:    Name | Host | Status | Lag | Conn | Region | Ver
+Narrow:  Name | Status | Lag | [Show details ▾]
+```
+
+`Name` (key identifier), `Status` (includes danger markers), `Lag` (comparison),
+and the primary action stay visible. `Host`, `Conn`, `Region`, and `Ver` move
+into row detail under "Show details for {replica}". A danger or warning marker
+**never** moves out of the summary row.
+
+## Rules
+
+### Virtualization vs pagination
+
+- **Virtualize** when the person scrolls one large loaded set (thousands of
+  client-side rows, or a server cursor that fetches as the person scrolls).
+  Keep header, selection model, and keyboard navigation correct.
+- **Paginate** ([pagination](pagination.md)) when the dataset is known and
+  page-shaped and the person benefits from "page 7 of 40" position.
+- Do **not** combine Pagination and infinite scroll / virtualized scroll on the
+  same table. Pick one model per surface and document it.
+
+### Sticky header
+
+- Use a sticky header when the table is taller than the viewport. The header
+  uses the same `--color-surface` as the header so rows do not show through.
+- Ensure focus order still follows visual order; do not trap focus under the
+  sticky layer.
+
+### Column resize
+
+- Optional. Drag handle on the header edge. Persist width in product state
+  when useful.
+- Minimum width must keep the header label readable. Use `ch` / type-role and
+  `--spacing-*`, not raw pixels.
+- Resizing must not break virtualization, selection, or keyboard order.
+
+### Cell rendering (references data-interfaces.md)
+
+- Numeric columns are right-aligned with `--type-role-numeric` and
+  `--font-variant-numeric`; headers align to the same edge. See
+  [data-interfaces.md](../data-interfaces.md) → Numeric values.
+- `NULL`, `0`, and unknown `—` are three distinct states. See
+  [data-interfaces.md](../data-interfaces.md) → Missing and indeterminate
+  values.
+- Truncate only when a known width is necessary; keep the full value in the DOM
+  for copy, search, and accessibility. A truncated value needs visible ellipsis,
+  full value in [Tooltip](../components/tooltip.md), and a touch-safe full-value
+  path. See [data-interfaces.md](../data-interfaces.md) → Truncation.
+- Dangerous values keep the raw value visible with a `Danger` marker; never
+  replace `fsync = off` with only "Dangerous". See
+  [data-interfaces.md](../data-interfaces.md) → Warnings and dangerous values.
+
+### Selection and keyboard
+
+- Multi-select via [Checkbox](../components/checkbox.md) in the leading column.
+  Header Checkbox toggles all rows **on the current page** (paged) or **all
+  loaded rows** (virtualized) unless the product defines "select all matching
+  query" with explicit copy and confirmation.
+- Keyboard: `Tab` reaches interactive controls (toolbar, sort headers,
+  checkboxes, row actions). Optional grid navigation inside the body uses
+  `aria-activedescendant` or roving tabindex with one tab stop into the grid —
+  document it on the screen.
+- Do not break keyboard order when virtualizing: the focused row must remain
+  in view, and scrolling must not strand focus on a row that unmounts.
+
+## Accessibility
+
+- Use a real `<table>` with `<thead>`, `<tbody>`, `<th scope="col">`.
+  Virtualization must not replace the table with non-semantic divs for
+  tabular data.
+- Accessible name via `<caption>` or `aria-labelledby`.
+- `aria-busy` on the region during load; Skeletons `aria-hidden`.
+- Sticky header: focus order follows visual order; no focus trap under the
+  sticky layer.
+- Responsive collapse: hidden fields are reachable through row expansion /
+  detail with a named control ("Show details for replica-01"). Tooltip is
+  never the only path to a hidden value.
+
+## Related patterns
+
+- [Search](search.md) — narrow the large set by query.
+- [Filtering](filtering.md) — narrow the large set by facet.
+- [Sorting](sorting.md) — order the large set.
+- [Pagination](pagination.md) — the alternative model for known, page-shaped
+  sets.
+- [data-interfaces.md](../data-interfaces.md) — prescriptive cell-rendering
+  rules (alignment, null/unknown, truncation, dangerous values) that this
+  pattern composes.

package/kiso/docs/patterns/list-detail.md

@@ -0,0 +1,118 @@
+# List-detail
+
+Master list plus a detail pane for one selected record. Navigation and context
+stay consistent: the list remains visible (or recoverable), and the detail
+shows the same entity the person selected.
+
+User story #5.
+
+## Purpose
+
+Browse many similar entities, select one, and inspect or act on it without
+losing list context. Typical Momoi uses: connections, instances, queries,
+parameters.
+
+**Canonical rule:** A list screen must not reinvent search, filters,
+pagination, and empty state. Compose [Search](../components/search.md),
+filtering controls, [Pagination](../components/pagination.md), and
+[EmptyState](../components/empty-state.md) through
+[Table / DataTable](../components/table.md) (and related components) — do not
+invent a parallel list kit.
+
+How Search, filters, sorting, and Pagination behave is specified elsewhere;
+this layout pattern only places those controls consistently.
+
+## Component composition
+
+| Region | Compose with | Role |
+| --- | --- | --- |
+| Page chrome | [PageHeader](../components/page-header.md) | Page title, subtitle, primary create/import [Button](../components/button.md) |
+| List toolbar | [Search](../components/search.md); optional filters via [Select](../components/select.md), [DropdownMenu](../components/dropdown-menu.md), and/or [Popover](../components/popover.md); optional bulk [Button](../components/button.md)s | Narrows the collection; owned by the list, not reinvented per product |
+| List body | [Table / DataTable](../components/table.md) or a selectable list of rows | Master collection; row selection drives the detail |
+| List paging | [Pagination](../components/pagination.md) | Below the table when the set is paged |
+| Detail pane | content region, often a [Card](../components/card.md) or definition stack | Selected entity; may include [Tabs](../components/tabs.md), [Badge](../components/badge.md), [DropdownMenu](../components/dropdown-menu.md) for entity actions |
+| Location | optional [Breadcrumb](../components/breadcrumb.md) | When the entity sits in a hierarchy deeper than Sidebar alone |
+| Shell | [Application shell](application-shell.md) | Header + Sidebar + main around this page |
+
+Tokens: list and detail panels use `--color-surface` on `--color-background`,
+dividers `--color-border`, primary text `--color-foreground`, secondary
+`--color-muted-foreground`, selection/current `--color-primary`, focus
+`--color-focus`.
+
+## Flow
+
+1. Person opens the list route inside the application shell.
+2. List loads; Search / filters / Pagination appear in their standard places
+   when the collection supports them.
+3. Selecting a row (or opening its Link) loads that entity in the detail pane
+   or detail route while preserving list context.
+4. Detail actions (edit, delete, connect) follow [CRUD](crud.md) and action
+   patterns; they do not replace the list chrome.
+5. Clearing selection returns focus to the list; changing Search/filters
+   updates the list and clears or reconciles an obsolete selection.
+
+Split view (list | detail) is preferred on wide viewports. On narrow
+viewports, push detail as a full main view with an explicit back control
+(Link or Button) that restores the list — same pattern, stacked presentation.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| loading (list) | Keep PageHeader and toolbar chrome; show Skeleton rows inside the table body — not a lone Spinner replacing the list. |
+| loading (detail) | Keep the selected row highlighted; detail pane shows Skeleton for known structure. |
+| empty (no items) | EmptyState in the list body with optional create action; detail pane hidden or shows a neutral prompt to select an item once items exist. |
+| empty (no matches) | EmptyState explaining no matches; offer clear-filters action. Do not pretend the collection was never populated. |
+| error (list) | Alert above or in place of the list body (what / why / now); retry Button; shell navigation remains. |
+| error (detail) | Alert inside the detail pane; list stays interactive so the person can pick another row. |
+| no selection | List visible; detail shows a short prompt ("Select a connection") — not an error, not EmptyState for the whole page. |
+
+## Layout sketch
+
+Wide (split):
+
+```text
+┌─────────────────────────────────────────────────────────────────────────┐
+│ PageHeader: Connections                              [Create connection]│
+├──────────────────────────────────┬──────────────────────────────────────┤
+│ List                             │ Detail                               │
+│ [Search..............] [Filter▾] │ Connection · prod-eu                 │
+│                                  │ [Badge: healthy]        [Actions ▾]  │
+│ ┌──────────────────────────────┐ │                                      │
+│ │ Name         Host      Status│ │ Host        db.example.com:5432      │
+│ │ prod-eu ●    db.eu…    ok    │ │ User        app_readonly             │
+│ │ staging      db.st…    warn  │ │ SSL         required                 │
+│ │ analytics    db.an…    ok    │ │                                      │
+│ └──────────────────────────────┘ │ [Edit]  [Test connection]            │
+│ ← Pagination →                   │                                      │
+└──────────────────────────────────┴──────────────────────────────────────┘
+```
+
+Narrow (stacked detail):
+
+```text
+┌──────────────────────────────────────┐
+│ ← Connections                        │
+│ PageHeader: prod-eu      [Actions ▾] │
+│                                      │
+│ Host     db.example.com:5432         │
+│ User     app_readonly                │
+│ ...                                  │
+└──────────────────────────────────────┘
+```
+
+## When to use
+
+- Collections where inspecting one item while keeping list context matters.
+- Entities that share the same columns and detail shape.
+
+## When NOT to use
+
+- Single-record settings pages — use [Settings](settings.md).
+- Dashboards of unrelated widgets — use [Dashboard](dashboard.md).
+- Create/edit full-page forms with no master list — use [CRUD](crud.md).
+
+## Related patterns
+
+- [Application shell](application-shell.md) — outer frame.
+- [CRUD](crud.md) — create/edit/delete of the selected entity.

package/kiso/docs/patterns/loading.md

@@ -0,0 +1,80 @@
+# Loading
+
+Loading tells the person that requested work is in progress while preserving
+context. Match the affordance to what is known: Skeleton for known structure,
+Spinner only for indeterminate work whose result has no honest layout yet.
+
+## Component composition
+
+- [Skeleton](../components/skeleton.md) preserves known content geometry.
+- [Table / DataTable](../components/table.md) composes Skeleton cells into
+  rows. **Lists and tables use Skeleton rows, never a centered Spinner.**
+- [Card](../components/card.md) keeps its frame and replaces known content with
+  shaped Skeletons.
+- [Spinner](../components/spinner.md) belongs in an indeterminate region or in
+  a loading [Button](../components/button.md), not over a list.
+- Keep [Search](../components/search.md) and
+  [Pagination](../components/pagination.md) stable during a refetch when their
+  current values are still meaningful.
+
+Loading surfaces use `--color-background` or `--color-surface`; Skeleton uses
+`--color-border`, while Spinner uses `--color-primary` and `--color-border`.
+Motion consumes `--motion-duration-normal` and
+`--motion-easing-standard`. Never invent raw placeholder dimensions; match
+semantic type and spacing tokens.
+
+## Flow
+
+1. Start the request and set `aria-busy="true"` on the affected region.
+2. Preserve stable chrome, headings, controls, and known dimensions.
+3. Render Skeletons matching the content that will arrive. For a list, repeat
+   a representative row rather than drawing one large block.
+4. Announce one concise status such as “Loading queries…”, not one per row.
+5. Swap placeholders for populated, empty, error, or permission-denied content
+   in one update and clear the busy state.
+
+For a pagination or filter refetch, keep the person's query and page context.
+Prevent duplicate requests without presenting loading as disabled. If existing
+rows remain safe to read, they may stay visible with the region marked busy;
+otherwise replace only the rows with Skeleton rows.
+
+## States
+
+| State | Treatment |
+| --- | --- |
+| Initial loading | Known layout uses Skeletons; unknown layout may use a labeled Spinner. |
+| Refetching | Keep controls and current context; replace or mark only the results region busy. |
+| Empty | Remove Skeletons and show EmptyState. Never let placeholders linger as an empty result. |
+| Error | Remove Skeletons and show the errors pattern. Retry returns to loading. |
+| Permission denied | Stop loading and use the permission-denied pattern; do not retry indefinitely. |
+| Loaded | Replace the loading presentation with real content in the same geometry. |
+
+## Layout sketch
+
+```text
+PageHeader: Queries                         [Create query]
+[Search queries________________] [Status v]       1–25 of 86
+┌─────────────────────────────────────────────────────────┐
+│ Name                 Owner                 Updated       │
+├─────────────────────────────────────────────────────────┤
+│ ███████████████      ███████               ██████████   │
+│ ██████████           ██████████            ███████      │
+│ █████████████        ██████                █████████    │
+│ █████████            ████████              ██████       │
+└─────────────────────────────────────────────────────────┘
+Status: Loading queries…                  [Previous] [Next]
+```
+
+The blocks are decorative Skeleton cells aligned to final columns. Do not
+replace this table body with a centered Spinner or erase its headers.
+
+## Accessibility and copy
+
+- Skeleton graphics are `aria-hidden="true"`; the containing region carries
+  `aria-busy` and one polite status.
+- Keep focus on the initiating control or stable page heading. Loading content
+  does not enter the tab order.
+- Under reduced motion, Skeletons stay static and Spinner uses a static graphic
+  plus its label.
+- State what is happening in direct language. Do not use chatty filler or
+  promise a duration the system does not know.

package/kiso/docs/patterns/login-authentication.md

@@ -0,0 +1,101 @@
+# Login / authentication
+
+Pre-authenticated entry: sign-in, and the minimal adjacent flows (sign-out
+landing, session expired). No product Sidebar; focus on one credential task.
+
+User story #29.
+
+## Purpose
+
+Authenticate the person with a calm, single-purpose layout. Authentication is
+a gate, not a product tour. After success, enter the
+[application shell](application-shell.md).
+
+## Component composition
+
+| Region | Compose with | Role |
+| --- | --- | --- |
+| Page canvas | centered content on `--color-background` | No Header/Sidebar product chrome |
+| Brand | product name / home [Link](../components/link.md) or mark | Identity only; not a marketing hero |
+| Form surface | [Card](../components/card.md) | Contains the auth form |
+| Fields | [FormField](../components/form-field.md) | Email/username [Input](../components/input.md), password Input (`type="password"`), optional OTP Input |
+| Submit | [Button](../components/button.md) | "Sign in" primary; full width of the Card content is acceptable |
+| Errors | [Alert](../components/alert.md) and/or [ValidationMessage](../components/validation-message.md) | Auth failures use Alert (what / why / now); field format errors use ValidationMessage |
+| Secondary nav | [Link](../components/link.md) | Forgot password, SSO, create account — text Links, not a Sidebar |
+| Busy | Button loading Spinner; optional [Spinner](../components/spinner.md) only if no Button loading affordance | Prevent double submit |
+
+Tokens: canvas `--color-background`, Card `--color-surface` / `--color-border`,
+text `--color-foreground` / `--color-muted-foreground`, primary action
+`--color-primary`, focus `--color-focus`. Keep flourish out of error copy
+([voice-and-tone](../voice-and-tone.md)).
+
+## Flow
+
+1. Unauthenticated person hits a protected route or opens the login URL.
+2. Show login Card; focus the first FormField.
+3. Person submits credentials.
+4. On success: establish session and route into the application shell (deep
+   link to the originally requested path when safe).
+5. On failure: keep credentials where safe (usually clear password); show Alert
+   with recovery (retry, reset password, contact admin) — never a cryptic code
+   alone.
+6. Sign-out returns to this pattern (or a signed-out confirmation that Links
+   back to Sign in).
+7. Session expired: same layout with an Alert explaining the session ended and
+   that signing in continues to the previous destination when possible.
+
+SSO: primary Button or Link "Continue with …" above or instead of password
+fields; do not hide password auth without a documented product decision.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| default | Brand + Card + fields + Sign in. |
+| loading (submit) | Primary Button loading; inputs read-only or inert; no full-page Spinner that hides the form. |
+| invalid fields | ValidationMessage on email/password format; focus first invalid field. |
+| error (auth) | Alert with what / why / now (for example wrong credentials, locked account, IdP failure); form remains. |
+| empty | Not applicable as a collection; do not use EmptyState for "no session". |
+| success | Brief transition into the shell; optional Toast is unnecessary if navigation is immediate. |
+
+## Layout sketch
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ --color-background                                                   │
+│                                                                      │
+│                         Momoi Product                                │
+│                   ┌────────────────────────┐                         │
+│                   │ Card: Sign in          │                         │
+│                   │                        │                         │
+│                   │ Alert (auth error)     │                         │
+│                   │                        │                         │
+│                   │ FormField  Email       │                         │
+│                   │ FormField  Password    │                         │
+│                   │                        │                         │
+│                   │ [ Sign in ]            │                         │
+│                   │                        │                         │
+│                   │ Forgot password?       │                         │
+│                   │ Continue with SSO      │                         │
+│                   └────────────────────────┘                         │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## When to use
+
+- Sign-in, session-expired re-auth, and post sign-out entry.
+- Minimal invite-accept screens that only establish a session.
+
+## When NOT to use
+
+- Authenticated account preference editing — [Settings](settings.md).
+- Product navigation or first-run feature tours after sign-in — use the
+  [application shell](application-shell.md), not this gate.
+- Permission failures inside an authenticated session — explain the blocked
+  action in-product; do not reuse this login layout as a stand-in.
+
+## Related patterns
+
+- [Application shell](application-shell.md) — post-auth destination.
+- [Settings](settings.md) — profile and security preferences after login.