@momoi-labs/kiso 0.1.0

package/kiso/docs/patterns/destructive-actions.md

@@ -0,0 +1,137 @@
+# Destructive actions
+
+Require confirmation with clear consequences before an irreversible or
+high-impact action. This pattern composes [Modal / Dialog](../components/modal-dialog.md)
+and the destructive [Button](../components/button.md) variant, and governs when
+confirmation is mandatory, what it must say, and how it behaves.
+
+User stories #11, #12.
+
+## Purpose
+
+A destructive action cannot be undone, or its undo is expensive, slow, or
+hidden: delete a database, drop a table, disconnect a live connection, purge
+logs, revoke a key. The person must understand the consequence **before** the
+action commits, and must be able to cancel without penalty.
+
+This pattern is the gate; [confirmations](confirmations.md) is the broader
+dialog spec (risk explanation, acknowledgment, copy structure). A destructive
+action always uses a confirmation; not every confirmation is destructive.
+
+## Component composition
+
+| Region | Compose with | Role |
+| --- | --- | --- |
+| Trigger | [Button](../components/button.md) `destructive` or [IconButton](../components/icon-button.md) `destructive` | Opens the confirmation; does not commit directly |
+| Confirmation dialog | [Modal / Dialog](../components/modal-dialog.md) | Blocks the page; requires explicit confirm or cancel |
+| Confirm action | [Button](../components/button.md) `destructive` inside the dialog | Commits the destructive action; the only destructive control in the dialog |
+| Cancel action | [Button](../components/button.md) `default` or `ghost` inside the dialog | Closes without committing; always available |
+| Progress | [Spinner](../components/spinner.md) inside the confirm Button | While the action is in flight; `aria-busy` |
+| Success / failure | [Toast](../components/toast.md) or [Alert](../components/alert.md) | After the dialog closes (see States) |
+
+The destructive `Button` variant uses `--color-danger` for its border/text (not
+a filled danger panel that shouts past contrast). The confirm Button inside the
+dialog is the **only** destructive-styled control; the dialog surface itself
+does not use danger color.
+
+## Flow
+
+1. Person activates a destructive trigger (e.g. "Delete replica").
+2. A [Modal / Dialog](../components/modal-dialog.md) opens with focus moved to
+   the first meaningful element (usually the cancel Button, to make the safe
+   path the default).
+3. The dialog names the action and its consequence in plain language (see
+   [confirmations](confirmations.md) for copy structure).
+4. Person confirms or cancels:
+   - **Cancel** (or `Escape`, or overlay click when safe): dialog closes, focus
+     returns to the trigger, nothing changes.
+   - **Confirm**: the confirm Button enters loading
+     ([Spinner](../components/spinner.md), `aria-busy`). Cancel stays available
+     while the action is in flight, unless the action cannot be safely
+     interrupted.
+5. On success, the dialog closes and a [Toast](../components/toast.md) confirms
+   the outcome ("Replica 'prod-eu' deleted"). On failure, an
+   [Alert](../components/alert.md) explains what/why/now and the dialog may stay
+   open with the error next to the confirm action.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| closed | Trigger available; no dialog. |
+| open | Page behind is inert; focus trapped in dialog. Cancel and confirm available. |
+| submitting | Confirm Button shows [Spinner](../components/spinner.md), `aria-busy`. Duplicate submission prevented. Cancel stays available unless interruption is unsafe. |
+| error | Recoverable error shown next to the confirm action or as an [Alert](../components/alert.md) inside the dialog. Dialog stays open. The destructive action did **not** commit. |
+| success | Dialog closes; [Toast](../components/toast.md) confirms. If the deleted entity was the current view, navigate to the parent list. |
+
+`Escape` closes the dialog **unless** the destructive operation is in flight
+and cannot be safely interrupted — in that case, `Escape` is inert or shows a
+brief "Action in progress" status. Document this per surface.
+
+## Layout sketch
+
+```text
+┌─────────────────────────────────────────────┐
+│                                             │
+│  ┌───────────────────────────────────────┐  │
+│  │ Delete "prod-eu"?                     │  │
+│  │                                       │  │
+│  │ This replica will be removed from the │  │
+│  │ workspace. Active queries to it will  │  │
+│  │ be terminated. This cannot be undone. │  │
+│  │                                       │  │
+│  │           [Cancel]  [Delete replica]  │  │
+│  └───────────────────────────────────────┘  │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+`Delete replica` is the only destructive-styled control. `Cancel` is the
+default focus target so the safe path is one `Enter` away.
+
+## Rules
+
+- **Always confirm destructive actions.** Do not commit on the trigger alone.
+  A single-click delete with no confirmation is a spec violation, even if the
+  trigger has a destructive variant.
+- Name the action and its consequence. "Delete 'prod-eu'?" with "This cannot
+  be undone" or "Active queries will be terminated." Follow
+  [voice-and-tone](../voice-and-tone.md): match the confirmation's weight to
+  the action's irreversibility — do not wrap a low-stakes action in danger
+  color, and do not under-state a high-stakes one.
+- The confirm Button is the **only** destructive control in the dialog. Do not
+  style the dialog surface, title, or body with `--color-danger`.
+- Cancel is always available and is the safe default. Prefer focusing Cancel on
+  open so a reflexive `Enter` does the safe thing.
+- Do not use "Are you sure?" as the only confirmation. State what will happen:
+  "This replica will be removed. Active queries will be terminated."
+- For type-to-confirm (delete a named resource by typing its name), require the
+  exact name. Use an [Input](../components/input.md) in the dialog; the confirm
+  Button stays disabled until the typed value matches. Reserve this for the
+  highest-stakes actions (drop database, delete workspace).
+- After success, do not leave the person on a deleted entity. Navigate to the
+  parent list or a neutral state.
+- A destructive action triggered from the [command palette](command-palette.md)
+  still opens a confirmation dialog — the palette is acceleration, not a bypass
+  for the gate.
+
+## Accessibility
+
+- Dialog: `role="dialog"`, `aria-modal="true"`, `aria-labelledby` (title),
+  `aria-describedby` (consequence) when the description is not the title.
+- Focus moves to the first meaningful element on open (usually Cancel). `Tab`
+  and `Shift+Tab` cycle inside; `Escape` closes unless the action is
+  uninterruptible.
+- The confirm Button's accessible name includes the action: "Delete replica",
+  not "Confirm" or "OK".
+- On error, move focus to the error [Alert](../components/alert.md) or the
+  confirm action so the person lands on the recovery path.
+- Type-to-confirm: the [Input](../components/input.md) has a
+  [Label](../components/label.md) ("Type 'prod-eu' to confirm"); the disabled
+  confirm Button has an accessible explanation of why it is disabled.
+
+## Related patterns
+
+- [Confirmations](confirmations.md) — the broader dialog spec: risk
+  explanation, acknowledgment, copy structure.
+- [Command palette](command-palette.md) — destructive commands still confirm.

package/kiso/docs/patterns/developer-oriented-interfaces.md

@@ -0,0 +1,162 @@
+# Developer-oriented interfaces
+
+Raw value vs friendly display toggling for technical data. This pattern governs
+how a surface lets a developer switch between a human-friendly presentation and
+the exact machine-readable value, and composes the
+[data-interfaces.md](../data-interfaces.md) rules into an interaction.
+
+User story #26.
+
+## Purpose
+
+Developer tools show data that has both a friendly form and a raw form: a
+timestamp as "2 minutes ago" vs `2026-08-19T02:54:26Z`, a byte count as
+`1.50 GiB` vs `1610612736`, a connection string as `postgresql://analytics…`
+vs the full URI, a config value as `on` vs `true`. Developers often need the
+exact raw value — to paste into a script, compare against a source, or debug —
+while scanning benefits from the friendly form.
+
+This pattern gives the person a consistent way to toggle between the two,
+without losing the [data-interfaces.md](../data-interfaces.md) rules that govern
+each form.
+
+## Component composition
+
+| Region | Compose with | Role |
+| --- | --- | --- |
+| Display cell | [Table / DataTable](../components/table.md) cell or definition value | Shows friendly or raw form per current mode |
+| Toggle control | [Switch](../components/switch.md), [Button](../components/button.md), or [Tabs](../components/tabs.md) | Switches the region between friendly and raw |
+| Copy action | [IconButton](../components/icon-button.md) "Copy {value type}" | Copies the exact source value regardless of display mode |
+| Full-value access | [Tooltip](../components/tooltip.md) + row/detail | Full value on hover/focus/touch (per [data-interfaces.md](../data-interfaces.md)) |
+| Code rendering | `--type-role-code` / `--font-mono` | Raw values use code type; friendly values use their normal role |
+
+## Flow
+
+1. Person views a data-heavy surface (table, detail panel) in friendly mode by
+   default. Timestamps are relative, byte counts are humanized, connection
+   strings are truncated with ellipsis.
+2. Person activates the toggle ("Show raw values" [Switch](../components/switch.md),
+   or a [Tabs](../components/tabs.md) "Friendly / Raw", or a per-cell
+   [IconButton](../components/icon-button.md)).
+3. The region re-renders in raw mode: absolute timestamps, exact byte counts,
+   full connection strings (or full where space allows; truncation rules still
+   apply per [data-interfaces.md](../data-interfaces.md)).
+4. Person can copy any value — [copy](../data-interfaces.md) always uses the
+   exact source value, not the displayed form.
+5. Toggling back restores friendly mode. The toggle preference may persist per
+   surface or per person (documented).
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| friendly (default) | Human-readable forms: relative time, humanized bytes, truncated long values with full-value access. |
+| raw | Machine-readable forms: absolute time (ISO 8601), exact byte counts, full values where space allows. Numeric alignment and `--type-role-numeric` still apply. |
+| mixed | Rare: some columns raw, others friendly. Use per-column toggles only when the product needs it; default is one region-wide toggle. |
+
+## Layout sketch
+
+### Region-wide toggle
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ Replicas                          [Friendly ● Raw]  [Show raw values]│
+├──────────────────────────────────────────────────────────────────────┤
+│ Table (raw mode)                                                     │
+│ ┌────────────────────────────────────────────────────────────────┐  │
+│ │ Name       Created                  Memory         Conn string   │  │
+│ │ replica-01 2026-08-19T02:54:26Z    1610612736 B   postgresql://… │  │
+│ │ replica-02 2026-08-19T01:12:08Z    2147483648 B   postgresql://… │  │
+│ └────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Friendly (default) mode
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ Replicas                          [Friendly ● Raw]                    │
+├──────────────────────────────────────────────────────────────────────┤
+│ Table (friendly mode)                                                │
+│ ┌────────────────────────────────────────────────────────────────┐  │
+│ │ Name       Created        Memory      Conn string               │  │
+│ │ replica-01 2 minutes ago  1.50 GiB    postgresql://analytics…  │  │
+│ │ replica-02 1 hour ago     2.00 GiB    postgresql://analytics…  │  │
+│ └────────────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+Copy (`[Copy]` [IconButton](../components/icon-button.md) adjacent to a value)
+copies the exact source: `1610612736 B` even in friendly mode where the cell
+shows `1.50 GiB`.
+
+## Rules
+
+### What changes between modes
+
+| Value type | Friendly | Raw |
+| --- | --- | --- |
+| Timestamp | Relative ("2 minutes ago") or localized | ISO 8601 (`2026-08-19T02:54:26Z`) or source epoch |
+| Byte count | Humanized (`1.50 GiB`) | Exact (`1610612736 B`) |
+| Duration | Humanized (`820 ms`, `1.2 s`) | Exact source unit (ms, µs) |
+| Connection string / URI | Truncated (`postgresql://analytics…`) | Full value, or full where space allows |
+| Config value | Friendly (`on`, `enabled`) | Source (`true`, `1`) |
+| Identifier | Same in both (identifiers are already raw) | Same |
+
+### What does not change
+
+- **Numeric alignment.** Raw numeric columns are still right-aligned with
+  `--type-role-numeric` and `--font-variant-numeric`. See
+  [data-interfaces.md](../data-interfaces.md) → Numeric values.
+- **null ≠ 0 ≠ unknown.** `NULL`, `0`, and `—` are distinct in both modes.
+  See [data-interfaces.md](../data-interfaces.md) → Missing and indeterminate
+  values.
+- **Dangerous values.** A dangerous value (`fsync = off`) keeps its
+  `Danger` marker and raw visibility in both modes. The friendly form does not
+  soften danger. See [data-interfaces.md](../data-interfaces.md) → Warnings and
+  dangerous values.
+- **Copy always uses the source value.** Whether the display is friendly or
+  raw, [copy](../data-interfaces.md) copies the exact source — not the rounded,
+  humanized, or truncated presentation.
+- **Truncation rules.** In raw mode, long values may still truncate per the
+  [data-interfaces.md](../data-interfaces.md) truncation rules (visible
+  ellipsis, full value in [Tooltip](../components/tooltip.md), touch-safe
+  full-value path). Raw mode does not mean "ignore layout"; it means "show the
+  source form where space allows."
+
+### Toggle mechanics
+
+- Default is **friendly**. Raw is opt-in.
+- The toggle is region-wide by default (one [Switch](../components/switch.md)
+  or [Tabs](../components/tabs.md) "Friendly / Raw" above the table). Per-column
+  or per-cell toggles are allowed only when the product needs mixed mode and
+  the toggle is clearly scoped.
+- The toggle preference may persist per surface or per person. Document which.
+- Toggling does not reload data — the underlying values are the same; only
+  presentation changes. Do not show a loading state for a display-mode toggle.
+- In raw mode, use `--type-role-code` / `--font-mono` for values that are
+  machine-readable (connection strings, config keys, timestamps in ISO). In
+  friendly mode, use the normal type role (numeric role for numbers, body for
+  prose timestamps).
+
+## Accessibility
+
+- The toggle control has an accessible name ("Show raw values", "Display mode")
+  and its state is announced.
+- When the display mode changes, the updated values are in the DOM; do not
+  require a live-region announcement for every cell. If the person is focused
+  on a cell, its new value is read on the next interaction.
+- Copy [IconButton](../components/icon-button.md) accessible name includes the
+  value type: "Copy memory (raw)", "Copy connection string". The copied value
+  is always the source, regardless of mode.
+- Full-value access ([Tooltip](../components/tooltip.md) + row/detail) must work
+  in both modes per [data-interfaces.md](../data-interfaces.md) truncation
+  rules.
+
+## Related patterns
+
+- [Large data tables](large-data-tables.md) — tables where raw/friendly toggle
+  is most useful.
+- [data-interfaces.md](../data-interfaces.md) — the prescriptive cell-rendering
+  rules (alignment, null/unknown, truncation, copy, dangerous values) that both
+  modes compose.

package/kiso/docs/patterns/empty-states.md

@@ -0,0 +1,76 @@
+# Empty states
+
+Use an empty state when a collection or bounded region has no content to show.
+It is a successful, known result—not loading, failure, or denied access.
+
+## Component composition
+
+- [EmptyState](../components/empty-state.md) owns the title, description, and
+  optional action.
+- Use [Button](../components/button.md) when the action changes the current
+  view, such as creating a record or clearing filters.
+- Use [Link](../components/link.md) when the next step navigates elsewhere.
+- In a [Table / DataTable](../components/table.md), keep useful headers and
+  place EmptyState in the body region. A list screen must not reinvent search,
+  filters, pagination, and empty state.
+
+The surrounding region uses `--color-background` or `--color-surface`.
+EmptyState copy uses `--color-foreground` and `--color-muted-foreground`;
+actions retain their component tokens. Do not use a status color: empty is not
+an error or warning.
+
+## Flow
+
+1. Resolve the collection request before deciding that it is empty.
+2. Distinguish first use, no matches, and expected informational emptiness.
+3. State what is empty and why, when the reason is useful.
+4. Offer one next action only when the person can change the state.
+5. After the action, move to loading, then populated, empty, or error based on
+   the result.
+
+The action is optional. Do not add a disabled or dead-end action merely to
+balance the layout. Informational copy is complete when no useful action exists.
+
+| Situation | Copy and action |
+| --- | --- |
+| First use | “No queries yet. Create your first query to see it here.” + **Create query** Button. |
+| No matches | “No queries match these filters.” + **Clear filters** Button when filters can be reset. |
+| Informational | “No completed runs in this period.” No action when the person cannot produce one here. |
+
+## States
+
+| State | Treatment |
+| --- | --- |
+| Loading | Do not show EmptyState. Preserve the region with Skeleton; lists use Skeleton rows. |
+| Empty | Show the matching EmptyState variant with an optional Button or Link. |
+| Error | Replace the empty treatment with the errors pattern and Alert. A failed request is not zero records. |
+| Permission denied | Use the permission-denied pattern. Do not imply the protected collection is empty. |
+| Populated | Replace EmptyState with the collection without moving surrounding controls. |
+
+## Layout sketch
+
+```text
+PageHeader: Queries                         [Create query]
+Search / filters / result count remain in place
+┌─────────────────────────────────────────────────────────┐
+│ Name                 Owner                 Updated       │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│                    No queries yet                       │
+│       Create your first query to see it here.           │
+│                    [Create query]                       │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+For no matches, keep Search and filters visible and replace the central action
+with **Clear filters**. For informational emptiness, omit the action row.
+
+## Accessibility and copy
+
+- Give the region an accessible name from the EmptyState title. Announce a
+  change to no results politely when it follows search or filtering.
+- Do not make the whole empty region interactive. Keyboard focus reaches the
+  Button or Link only.
+- Follow [voice and tone](../voice-and-tone.md): what is empty, why when useful,
+  and what to do. Avoid jokes, apologies, and terminal flourish.

package/kiso/docs/patterns/errors.md

@@ -0,0 +1,93 @@
+# Errors
+
+Use an error state when an operation failed or valid content could not be
+loaded. Every error must explain a recovery path; a code, danger color, or
+“Something went wrong” is not sufficient.
+
+Permission denied is not a generic error. When the system succeeded in
+determining that access is missing, use the
+[permission-denied pattern](permission-denied.md).
+
+## Component composition
+
+- [Alert](../components/alert.md) presents page-, section-, and operation-level
+  errors in context with an optional recovery Button or Link.
+- [ValidationMessage](../components/validation-message.md) presents a
+  field-level error beside its FormField and points to the affected control.
+- [Button](../components/button.md) performs an immediate recovery such as
+  retry; [Link](../components/link.md) navigates to settings or documentation.
+- [Toast](../components/toast.md) is only for a brief failure whose recovery is
+  already available in context. Never put the only explanation or action in a
+  transient Toast.
+
+Error meaning uses `--color-danger`; primary and supporting copy use
+`--color-foreground` and `--color-muted-foreground` on `--color-surface`.
+Recovery controls retain their semantic component tokens, including
+`--color-focus`. Do not fill the whole region with danger color.
+
+## Mandatory what / why / now structure
+
+Every error follows the hard rule in
+[voice and tone](../voice-and-tone.md), in this order:
+
+1. **What happened.** Name the failed operation or unavailable content.
+2. **Why, when known.** Give a brief verified cause. Omit this part when the
+   cause is unknown; never guess.
+3. **What to do now.** Give a concrete recovery action or next step.
+
+```text
+What: Connection to the database failed.
+Why:  The server at db.example.com:5432 did not respond within 5 seconds.
+Now:  Check that the database is reachable, then retry.        [Retry]
+```
+
+Keep diagnostic identifiers as secondary, copyable details when they help
+support or debugging. They never replace the human explanation.
+
+## Flow
+
+1. Stop the pending presentation and preserve the person's input and context.
+2. Classify the scope: field, operation/section, or whole page.
+3. Write what happened, the known reason, and what the person can do now.
+4. Place the message beside the affected content and expose the recovery as a
+   Button or Link when it can be performed directly.
+5. Move or announce focus appropriately. On retry, keep the Alert visible with
+   its Button loading until the outcome is known.
+6. On success, remove the resolved error; on repeated failure, update verified
+   details without stacking duplicate Alerts.
+
+## States
+
+| State | Treatment |
+| --- | --- |
+| Loading / retrying | Keep the error explanation visible; the recovery Button shows Spinner and the affected region is busy. |
+| Field error | ValidationMessage follows what/why/now at the smallest useful scale and is linked to the invalid control. |
+| Section or page error | One persistent Alert sits before or in place of the affected content. |
+| Unknown cause | State what failed and what to do now; omit why. |
+| Permission denied | Switch to the permission-denied pattern, without error severity or retry loops. |
+| Recovered | Remove the Alert, clear stale invalid state, and restore the content without a redundant success message unless confirmation is needed. |
+
+## Layout sketch
+
+```text
+PageHeader: Query results
+┌─ Alert: error ───────────────────────────────────────────┐
+│ Query results could not be loaded.                       │  What
+│ The database connection closed during execution.        │  Why
+│ Reconnect, then retry the query.       [Reconnect]       │  Now
+└──────────────────────────────────────────────────────────┘
+
+FormField: Connection name
+[production db___________________________________________]
+ValidationMessage: Use letters, numbers, hyphens, or underscores. [What/now]
+```
+
+## Accessibility and copy
+
+- Use one assertive Alert for a newly introduced blocking error. Avoid several
+  competing live regions.
+- On failed submission, focus the error summary or first invalid control.
+  Recovery actions remain reachable by keyboard and use visible focus.
+- Error meaning must be present in text and iconography, not color alone.
+- Be direct and non-accusatory. Do not apologize, joke, add terminal flourish,
+  or expose cryptic codes without context.

package/kiso/docs/patterns/filtering.md

@@ -0,0 +1,147 @@
+# Filtering
+
+Structured filter controls that narrow a collection by attribute, not by free
+text. This pattern composes [Select](../components/select.md),
+[DropdownMenu](../components/dropdown-menu.md), [Popover](../components/popover.md),
+[Checkbox](../components/checkbox.md), and [Switch](../components/switch.md) into
+a consistent filter bar alongside [Search](search.md).
+
+User story #2.
+
+## Purpose
+
+Filters let the person narrow a collection by known attributes — status,
+region, engine version, tagged label — with controls whose options are a closed
+or bounded set. They complement [Search](search.md): Search narrows by free
+text; filters narrow by discrete facet. A list screen composes both rather than
+reinventing either.
+
+**Canonical rule:** A list screen must not reinvent search, filters,
+pagination, and empty state. Compose filter controls in the toolbar — do not
+invent a per-list filter kit.
+
+## Component composition
+
+| Filter shape | Compose with | Example |
+| --- | --- | --- |
+| One value from a set | [Select](../components/select.md) | "Status: any / healthy / degraded / down" |
+| Toggle a single facet on/off | [Switch](../components/switch.md) or [Checkbox](../components/checkbox.md) | "Show only replicas with lag" |
+| Multiple values from a set | [Checkbox](../components/checkbox.md) group inside a [Popover](../components/popover.md) | "Region: ☑ eu ☑ us ☐ ap" |
+| Range or complex facet | [Popover](../components/popover.md) with form controls | "Lag: 0–500 ms" |
+| Quick toggles (few, stable) | [Button](../components/button.md) `ghost` toggle or [Tabs](../components/tabs.md) | "All / Active / Archived" |
+| Active-filter summary | [Badge](../components/badge.md) per active filter or a text line | "Status: degraded ×" |
+
+Filters live in the list toolbar, beside [Search](search.md) and above
+[Pagination](../components/pagination.md). They are siblings of the table, not
+columns.
+
+## Flow
+
+1. Person opens the list. No filters active; full collection (or default
+   filter) is visible.
+2. Person activates a filter control (Select, Popover trigger, Switch).
+3. The collection re-queries or re-filters. The results region shows
+   [Skeleton](../components/skeleton.md) rows for server-side filters; for
+   client-side filters the set updates without a loading flash.
+4. Active filters are summarized as removable [Badge](../components/badge.md)s
+   or a text line in the toolbar.
+5. If filters exclude everything, the collection body shows
+   [EmptyState](../components/empty-state.md) `no-results` with a
+   "Clear filters" action.
+6. Clearing a filter (via its Badge × or a "Clear filters" control) restores
+   the wider set.
+
+## States
+
+| State | Behavior |
+| --- | --- |
+| idle | No filters active. Default set visible. |
+| applying | Server-side: results region `aria-busy`, Skeleton rows. Client-side: set updates immediately. |
+| active | One or more filters active. Summarized as Badges or a text line. |
+| no matches | Filters exclude everything → [EmptyState](../components/empty-state.md) `no-results`. Offer "Clear filters". Keep filter controls visible and editable. |
+| error | Server query failed → [Alert](../components/alert.md) with retry. Do not show EmptyState for a failure. |
+
+Filter controls themselves follow their component states (Select open/closed,
+Switch on/off). The list-level states above describe the collection.
+
+## Layout sketch
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ PageHeader: Replicas                       [Add replica]             │
+├──────────────────────────────────────────────────────────────────────┤
+│ Toolbar                                                              │
+│ [🔍 Search replicas...] [Status▾] [Region▾] [Show lag only ◯]       │
+│                                                                      │
+│ Active: [degraded ×] [eu ×]                    [Clear filters]       │
+│ 3 of 18 replicas                                                     │
+├──────────────────────────────────────────────────────────────────────┤
+│ Table / DataTable                                                    │
+│ ┌────────────────────────────────────────────────────────────────┐  │
+│ │ Name        Host            Status     Lag      Region          │  │
+│ │ replica-01  db.eu.example   degraded   820 ms   eu              │  │
+│ │ replica-03  db.eu.backup    degraded   1.2 s    eu              │  │
+│ │ replica-07  db.eu.dr        degraded   —        eu              │  │
+│ └────────────────────────────────────────────────────────────────┘  │
+│ ← 1 (of 1) →                                                         │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+When filters exclude everything:
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│ Toolbar                                                              │
+│ [🔍 ...] [Status▾] [Region▾] [Show lag only ●]                      │
+│ Active: [down ×] [ap ×]                       [Clear filters]       │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│        No replicas match these filters                               │
+│        No replicas with status "down" in region "ap".                │
+│                          [Clear filters]                             │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## Rules
+
+- Filters and [Search](search.md) narrow the collection **together**. The
+  active query and active filters form one result set. Document whether
+  "Clear search" also clears filters (default: no — they are independent unless
+  the surface offers a single "Reset all").
+- Active filters must be visible and removable individually. A person should
+  not have to open a Popover to discover which filters are active.
+- Default filters are allowed when they reflect a sensible default view
+  ("Active only"). The active-filter summary must still show the default as
+  active so it is not a hidden filter.
+- Do not invent a filter UI that competes with [Select](../components/select.md)
+  / [Checkbox](../components/checkbox.md) / [Popover](../components/popover.md).
+  If the facet is one-of-many, use Select; if many-of-many, use a Checkbox
+  group in a Popover.
+- Filter state is part of the list's state, not global. Navigating away and
+  back may restore it (documented per surface) but filters must not leak into
+  unrelated lists.
+- A filter that changes the set dramatically (e.g. "Show deleted") should make
+  the change obvious — a visible Badge and, if the consequence is surprising, a
+  short note.
+- Combine filters with [sorting](sorting.md) and [pagination](pagination.md)
+  consistently: filter narrows, sort orders, pagination pages.
+
+## Accessibility
+
+- Each filter control has an accessible name ("Status", "Region", "Show only
+  replicas with lag"). Placeholder alone is not a name for Select.
+- Active-filter Badges that are removable are [IconButton](../components/icon-button.md)s
+  or Buttons with `aria-label` like "Remove status filter: degraded".
+- When filters change the result set, update a polite live region or the result
+  count so screen reader users know the set changed.
+- No-matches [EmptyState](../components/empty-state.md) must be reachable and
+  announced; keep filter controls in the tab order so the person can adjust.
+
+## Related patterns
+
+- [Search](search.md) — free-text narrowing that composes with filters.
+- [Sorting](sorting.md) — ordering the filtered set.
+- [Pagination](pagination.md) — paging the filtered set.
+- [Large data tables](large-data-tables.md) — tables where filters are
+  essential to manage volume.