# Slate Components

> Buttons, badges, status, tags, inputs, tabs, cards, navigation, notices and empty states in the Everruns UI, with the rules for each.

Source: <https://everruns.com/docs/design-system/components/>

Each example reproduces a production component from [`apps/ui/src/components/`](https://github.com/everruns/everruns/tree/main/apps/ui/src/components). The file named under each heading is the canonical version; build from it, not from this markup.

## Buttons

`components/ui/button.tsx`. 32px high, 14px medium label, 16px icon. Hover is the same fill at 90%. Focus is a 3px ring in `ring / 0.5` with the border switching to `ring`.

Create, commit, secondary, quiet, and destructive actions. The last button shows the focus ring.

The tier matters more than the look:

| Tier        | Variant                         | Used for                                                                                                                              |
| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Create      | `accent`: gold fill, navy label | The one “make a new thing” action on a page: New agent, New harness, Add model, Test in Playground.                                   |
| Commit      | `default`: navy fill            | Saving an edit: Save changes. Never on a read-only page.                                                                              |
| Secondary   | `outline`                       | Everything else in an action cluster: Edit, Copy, Export, Discard, Analyze.                                                           |
| Quiet       | `ghost`                         | Card footers, toolbars, Cancel in dialogs.                                                                                            |
| Destructive | ghost icon in `destructive`     | Row-level delete. Never a filled red button in a list. A filled `destructive` button is for the confirm step of a destructive dialog. |

* One create or one commit action per page, never both. The create button sits last (far right) in its cluster; Save changes sits first, with Discard to its right.
* An action cluster holds at most six buttons. More go into the `⋯` menu, which also holds History, Manager notes, Archive, and Delete ([entity actions menu](https://github.com/everruns/everruns/blob/main/knowledge/ui/entity-actions-menu.md)).
* Labels are verbs in sentence case: “New session”, not “New Session” or “Create”.

## Badges, status, and tags

Three different things that look alike. Do not interchange them.

* **Badge** (`components/ui/badge.tsx`): an informational label. 11px medium, sentence case, sharp corners. `success` for positives such as Enabled, `secondary` for neutral facts (Built-in, Idle), `accent` for a transient mode (Editing, Draft), `outline` for plain labels, `destructive` only for failure. The id chip is mono with a navy 6% tint.
* **Status** (`components/ui/entity-status.tsx`): lifecycle on overview surfaces such as cards and rows. A 6px dot and a 12px muted label. Color is a second cue; the word carries the meaning. The masthead of a detail page may use a filled badge for the same state.
* **Tag** (`components/ui/tag-input.tsx` for editing): a quiet `muted / 0.6` fill, 12px, no border. Three show on a card, then `+N`.

## Inputs and fields

`components/ui/input.tsx`, `textarea.tsx`, `select.tsx`, `search-input.tsx`. 32px high, card surface, `input` border, the gold ring on focus. Labels are 12px medium muted, above the control.

Editable values wear bordered controls. Read-only facts are plain text: a 13px medium label over a muted value, no border. An archived record shows every value as read-only.

## Tabs and view toggle

`SectionTabs` in `components/ui/tabs.tsx`. 13px, optional icon and muted count; the selected tab is 600 weight with a 2px navy underline. Tabs filter a list by status, or switch the sections of a detail page. The grid and list toggle sits at the end of a list’s control strip.

## Cards

`components/ui/card.tsx` and `components/ui/entity-card.tsx`. Every list page shows its records as entity cards; domain cards such as `AgentCard` compose `EntityCard`, which composes `Card`.

Anatomy, top to bottom:

1. A plain 20px domain glyph (no tile; only the page masthead uses a tile), an 18px semibold linked title, and the lifecycle status at the top right.
2. The description at `foreground / 0.75`, clamped to two lines.
3. Detail rows: `icon · label · value`, such as the harness. Agent channels sit here, above tags; harness cards have no channels.
4. Capabilities as icon and name, four, then `+N`. Tags, three, then `+N`. Overflow controls are keyboard accessible and reveal the full set.
5. A footer strip with usage on the left and ghost actions on the right.

Rules: only the title and explicit links navigate, the card itself is inert. Never fix a card’s height; let the body grow. No shadow; hover darkens the border. Slugs, ids, and creation dates belong on the detail page.

### Rows

Dense registries (Models, MCP tools) use a full-width row per record instead of a grid.

A row that stands for a record with its own page is a link as a whole: the name carries the link and the row is its click target. Columns hold what the reader scans for (status, last used), the ⋯ menu holds quick commands, and a chevron ends the row. Configuration and budgets live on the record’s page, never in a row that expands. Below about 40rem the columns fold under the name. Agent channels use this list.

## Navigation

`components/layout/sidebar-navigation.tsx`, with the items in `lib/navigation.ts`. A 240px sidebar: the logo row, the organization switcher, search, then the groups.

* Groups, in order: Chat and Overview (no label), Build, Observability, Blocks, Quality, then Settings, System (collapsed), and Dev in development builds. The navigation model in `lib/navigation.ts` owns the item list; breadcrumbs take their group name from it.
* Group labels are 12px medium muted sentence case. Groups are separated by 12px of space, never by rules.
* An item is a 13px label with its 16px Facet glyph. Selected: a 2px navy left marker, a `primary / 0.05` tint, 600 weight. Hover: a border-colored marker and a light fill.
* Experimental items carry the Lucide flask after the label.

## Notices, banners, and empty states

* **Banner**: one full-width strip above the app shell, gold 10% tint, a glyph, a bold lead and a muted continuation, one link, and a dismiss button. One at a time, never stacked.
* **Notice** (`components/ui/notice.tsx`): an inline bordered message inside a page.
* **Empty state**: teach what the thing is and offer the first action. Zero counters are hidden rather than shown as “0”.
* Errors shown to ordinary users are short and generic. Full error detail belongs to the developer surfaces, such as the session trace.

## Choose the control by the task

| Task                                 | Shared component      | Behavior                                                              |
| ------------------------------------ | --------------------- | --------------------------------------------------------------------- |
| A short, fixed set of values         | `Select`              | Keyboard selection with a named trigger.                              |
| One resource from a growing catalog  | `Combobox`            | Search names and IDs; keep the selected label when results change.    |
| Several bound resources              | `ResourceMultiSelect` | Searchable checkboxes; selected unavailable records remain removable. |
| A change to the current presentation | `SegmentedControl`    | One selected view; keyboard navigation through the choices.           |
| Navigation to another section        | `SectionTabs`         | Use links when the destination has its own URL.                       |
| Commands on a record                 | `EntityActionsMenu`   | Shared record and lifecycle groups, with destructive actions last.    |
| Tags                                 | `TagInput`            | Enter or comma adds a chip; Backspace removes the last chip.          |
| A numeric range                      | `Slider`              | Native range keyboard semantics, Slate colors and focus.              |

Resource wrappers such as `ModelPicker`, `AgentSelect`, `HarnessSelect` and `VirtualUserSelect` own fetching, eligibility and lifecycle rules. They compose the same searchable control; a new picker must not build another popup or keyboard implementation. Keep model provider names visible because several accounts can serve the same model. Harness options include their purpose. Never silently clear an unavailable saved selection.

Searchable picker anatomy. The app's component gallery exercises keyboard selection, empty results and asynchronous states.

### Field and selection states

Use `Field` to associate the label, hint and validation message with the control. Pass its hint ID through `aria-describedby`, and set `aria-invalid` when validation fails. Keep errors next to the field and announce them as alerts. A field label is never replaced by a placeholder.

Searchable pickers support disabled options, grouping, descriptions, loading, request failure, no matching results, and a pagination footer. Search results must not change the current value. Closing a popup with Escape returns focus to its trigger. Popups use a portal and remain within the available viewport, including when opened inside a dialog.

### Actions and feedback

Use the shared `Button` with `loading` for a pending operation: it displays a spinner, disables repeat clicks and exposes `aria-busy`. Use `ConfirmDialog` for asynchronous destructive actions; failure keeps the dialog open with a retryable error. Routine confirmation requests use the page’s `ConfirmationProvider` instead of browser confirmation popups. Navigation or an organization change cancels an unanswered request.

`Pagination` owns Previous, page count and Next for numbered lists. Cursor-based lists retain a Load more footer rather than inventing a total page count. `QueryStateWrapper` composes `Notice` and `EmptyState`; distinguish no resources from no matches for the current filters.

The production implementations live in [`apps/ui/src/components/ui/`](https://github.com/everruns/everruns/tree/main/apps/ui/src/components/ui). Interactive examples use those components at `/dev/ui-components` in a local development build.