DESIGN.md@apps/ui ยท diff

alpha to alpha

12 added, 13 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
version: alpha
name: Slate
description: Everruns design system, sharp-cornered, grayscale-dominant, navy primary with a single gold accent.
colors:
# Mirrors the light-mode CSS custom properties in src/app/design-system.css,
# which is the runtime single source of truth. Values use hsl() to match those
# variables exactly; dark-mode equivalents are documented in the Colors prose.
background: "hsl(0 0% 98%)"
foreground: "hsl(0 0% 10%)"
card: "hsl(0 0% 100%)"
card-foreground: "hsl(0 0% 10%)"
popover: "hsl(0 0% 100%)"
popover-foreground: "hsl(0 0% 10%)"
primary: "hsl(220 62% 13%)"
primary-foreground: "hsl(0 0% 98%)"
secondary: "hsl(0 0% 96%)"
secondary-foreground: "hsl(0 0% 10%)"
muted: "hsl(0 0% 96%)"
muted-foreground: "hsl(0 0% 42%)"
accent: "hsl(43 60% 53%)"
accent-foreground: "hsl(43 60% 30%)"
success: "hsl(163 94% 24%)"
success-foreground: "hsl(0 0% 98%)"
warning: "hsl(26 90% 37%)"
warning-foreground: "hsl(0 0% 98%)"
info: "hsl(201 96% 32%)"
info-foreground: "hsl(0 0% 98%)"
destructive: "hsl(0 72% 51%)"
destructive-foreground: "hsl(0 0% 98%)"
border: "hsl(0 0% 88%)"
input: "hsl(0 0% 85%)"
ring: "hsl(43 60% 38%)"
typography:
# Font families come from CSS variables: --font-sans (Geist Sans) and
# --font-mono (Geist Mono). Body copy carries -0.01em global tracking.
headline-lg:
fontFamily: Geist Sans
fontSize: 1.875rem
fontWeight: 600
lineHeight: 1.2
letterSpacing: -0.02em
headline-md:
fontFamily: Geist Sans
fontSize: 1.75rem
fontWeight: 600
lineHeight: 1.25
letterSpacing: -0.015em
title:
fontFamily: Geist Sans
fontSize: 1.125rem
fontWeight: 600
lineHeight: 1.4
letterSpacing: -0.01em
body-lg:
fontFamily: Geist Sans
fontSize: 1rem
fontWeight: 400
lineHeight: 1.6
letterSpacing: -0.01em
body-md:
fontFamily: Geist Sans
fontSize: 0.875rem
fontWeight: 400
lineHeight: 1.5
letterSpacing: -0.01em
label-md:
fontFamily: Geist Sans
fontSize: 0.75rem
fontWeight: 500
lineHeight: 1
letterSpacing: 0em
code:
fontFamily: Geist Mono
fontSize: 0.875rem
fontWeight: 400
lineHeight: 1.6
rounded:
# Sharp corners are a defining brand trait: every radius is 0.
none: 0px
sm: 0px
md: 0px
lg: 0px
spacing:
# 4px base scale (Tailwind defaults are used in practice); the branded dot
# grid background repeats on a 24px cell.
xs: 4px
sm: 8px
md: 16px
lg: 24px
xl: 32px
2xl: 48px
dot-grid: 24px
components:
button-primary:
backgroundColor: "{colors.primary}"
textColor: "{colors.primary-foreground}"
rounded: "{rounded.none}"
typography: "{typography.label-md}"
padding: "0.5rem 1rem"
button-primary-hover:
backgroundColor: "hsl(220 62% 13% / 0.9)"
button-secondary:
backgroundColor: "{colors.secondary}"
textColor: "{colors.secondary-foreground}"
rounded: "{rounded.none}"
typography: "{typography.label-md}"
padding: "0.5rem 1rem"
input:
backgroundColor: "{colors.card}"
textColor: "{colors.foreground}"
rounded: "{rounded.none}"
padding: "0.5rem 0.75rem"
card:
backgroundColor: "{colors.card}"
textColor: "{colors.card-foreground}"
rounded: "{rounded.none}"
padding: "1rem"
---
# Slate Design System
Slate is the Everruns design system. The normative token values live in the YAML
front matter above and in `src/app/design-system.css` (the runtime source of
truth); the prose below explains how to apply them.
## Reference and authority
- Use the [Everruns design project](https://claude.ai/design/p/019e0a57-7d4b-70aa-a3c2-8c3d3746126e)
- as a visual reference for Slate's page archetypes, density, and component anatomy. Exported design
- project archives are snapshots for review; they are not copied into the application and do not
- override repository sources.
-
- The reviewed ZIP export is pinned by filename, SHA-256 checksum, and review date in
- `design-reference.json`. Update that manifest whenever a newer export is adopted, then reconcile
- intent here and verify both `/dev/design-reference` and `/dev/ui-components`.
+ The public [Slate design system pages](https://everruns.com/docs/design-system/) (source:
+ `docs/design-system/` and `apps/docs/src/components/design-system/`) show the foundations,
+ components, page layouts, icons, and writing rules as live examples. They read their tokens,
+ dot grid, motion, and Facet icons from this app at build time, so those cannot drift; the
+ example markup reproduces production components by hand. A redesign starts there, and the
+ pull request that ships it updates the matching page. Intent and the maintenance contract:
+ `knowledge/ui/design-system.md`.
When references disagree, use this order:
1. `src/app/design-system.css` for runtime tokens, utilities, and animation.
2. This file for visual intent, hierarchy, and composition rules.
3. Production components in `src/components/` for exact behavior and component APIs.
4. `/dev/ui-components` for an interactive rendering of those production components.
- 5. The external design project for visual comparison and page-level examples.
+ 5. The design system pages for page-level examples and the starting point of new designs.
- The external project should stay recognizably close to the product, but application code remains
- canonical. Reconcile meaningful drift here rather than introducing parallel CSS or mock components.
+ Reconcile meaningful drift in the code and this file, then update the design system page,
+ rather than introducing parallel CSS or mock components in the app.
## Overview
Slate feels like precision instrumentation: sober, dense, and engineered. The
product manages and monitors AI agents, so the UI favors legibility and calm
over decoration. The personality is **architectural**: sharp corners, a
grayscale foundation, and a single gold accent reserved for moments that matter.
When a rule is not spelled out, prefer the restrained, professional, slightly
utilitarian choice over the playful or ornamental one.
## Colors
The palette is grayscale-dominant, anchored by a deep navy primary and a single
gold accent. Descriptive brand names map to systematic tokens as follows:
- **Navy (`primary`, light `hsl(220 62% 13%)` โ‰ˆ `#0A1636`):** The brand color,
used for primary buttons, key actions, and the loading-wave ramp. In dark mode
`primary` inverts to near-white (`hsl(0 0% 95%)`) so actions stay prominent.
- **Gold (`accent`, `hsl(43 60% 53%)` โ‰ˆ `#D4A43A`):** The sole accent,
reserved for active states, focus rings, highlights, and the dark-mode dot
grid. Use it sparingly, never as a large text surface. The light-mode focus
`ring` is a deeper gold (`hsl(43 60% 38%)`) so it keeps 3:1 against the page;
dark mode uses the accent gold.
- **Ink (`foreground`, `hsl(0 0% 10%)`):** Core text on light surfaces.
- **Surfaces (`background` `hsl(0 0% 98%)`, `card` white):** A near-white page
with pure-white cards. Dark mode shifts to a navy-tinted charcoal
(`background hsl(220 15% 8%)`, `card hsl(220 15% 10%)`).
- **Muted (`muted` / `muted-foreground`):** Quiet grays for secondary text,
metadata, and disabled states. Light `muted-foreground` (`hsl(0 0% 42%)`)
stays at 4.5:1 on the `muted` surface too.
- **Success (`success` / `success-foreground`):** Positive outcomes and healthy
states. Use `success` for indicators and translucent surfaces, and
`success-foreground` on a solid success fill.
- **Warning (`warning` / `warning-foreground`):** Conditions that need
attention, including degraded and waiting states. Use the foreground pair on
a solid warning fill.
- **Info (`info` / `info-foreground`):** Active, running, and informational
states. Use the foreground pair on a solid info fill.
- **Destructive (`hsl(0 72% 51%)`):** Errors and irreversible actions only.
Every token has a light and dark value in `design-system.css`; the tokens above
capture the light theme as the canonical reference. Dark mode uses lighter
status colors with dark foreground pairs so indicators remain legible on
charcoal surfaces and solid fills. Dark mode is class-based: `.dark` on
`<html>`, set from the `everruns_theme` cookie by `ThemeProvider`. Never use a
raw palette color for a themed surface unless it is one of the deliberate
exceptions below.
## Typography
Two families carry the system: **Geist Sans** for everything structural and
**Geist Mono** for code, logs, and telemetry. Do not introduce handwritten or display fonts.
Experimental features use the Lucide flask marker in navigation rather than a page-title stamp.
- **Headlines (`headline-lg`, `headline-md`):** Geist Sans Semi-Bold with tight
negative tracking for an engineered, condensed feel.
- **Body (`body-lg`, `body-md`):** Geist Sans Regular. Dense SaaS surfaces lean
on `body-md` (14px); long-form reading uses `body-lg` (16px). Global letter
spacing is `-0.01em`.
- **Labels (`label-md`):** Compact Geist Sans Medium for buttons, chips, and
metadata.
- **Code (`code`):** Geist Mono for inline code and code blocks.
## Layout
Layouts use a 4px base spacing scale (`xs`โ€“`2xl`) consistent with the Tailwind
defaults already in use. Content sits on a near-white page textured by a branded
**dot grid**: navy dots at 3.5% opacity in light mode, gold dots at 4.5% in dark
mode, repeating on a 24px cell (`spacing.dot-grid`). Group related items into
white cards with generous internal padding to separate them from the textured
background.
## Elevation & Depth
Slate is intentionally **flat**. Hierarchy comes from tonal layering and
borders rather than decorative elevation: a near-white background, pure-white
cards, and 1px borders (`colors.border`). Inputs and buttons may use `shadow-xs`;
popovers and dialogs may rise as far as `shadow-md`. Content cards do not cast
shadows. Focus and active emphasis is signaled with the gold `ring`. Subtle
motion (row-enter, tool-pulse, loading-wave, and a progress sheen) conveys state
changes in place.
## Shapes
The shape language is **uncompromisingly sharp**: every corner radius is `0px`
(`--radius` and all `--radius-*` tokens). Icons reinforce this with squared
line caps and mitered joins (`.icon-sharp`). The only round elements are semantic
status dots, circular Lucide glyphs, and the rings in the Everruns logo.
## Components
- **Buttons:** `button-primary` is navy with near-white label text and sharp
corners; it uses 90% opacity on hover (`button-primary-hover`). `button-secondary` uses
the light gray `secondary` surface for lower-emphasis actions. Both use the
`label-md` token. Action hierarchy is semantic: `accent` creates a new entity,
`default` commits changes, `outline` handles secondary actions, and destructive
list actions use a red ghost icon rather than a filled button.
- **Inputs:** White surface, `input` border color, sharp corners, comfortable
padding; focus draws the gold `ring`.
- **Cards:** White surface on the textured background, 1px border, no radius,
no shadow. Card action groups keep the highest-priority action visible and
collapse secondary or destructive actions into an ellipsis menu when the
card is too narrow for the full action row.
### Overview density
Overview screens keep enough context to compare entities: name and lifecycle first,
a readable description second, then configuration, relationships, channels, and usage.
Use the existing neutral palette in both themes. Reduce repeated framing and metadata
rather than removing useful configuration.
- Descriptions use foreground with reduced opacity for more contrast than muted metadata.
- Lifecycle status is a small semantic dot and a text label, without a filled badge.
Informational labels and diagnostics can still use badges where they convey extra meaning.
- Domain identity uses the custom Facet family: original solid Intent for Agents and
quiet geometric outlines for supporting domains. Glyphs inherit semantic foreground
color. Vector masters and `/dev/icons` own the geometry and size comparisons;
`knowledge/ui/iconography.md` owns the philosophy. Official integration marks and
conventional action/status glyphs retain their identities.
- Entity icons are plain glyphs; only masthead icons use a lightly tinted tile.
- Slugs, exact-ID copy actions, and creation dates belong in details, unless the identifier
itself is needed to distinguish technical resources. Keep operational recency and errors.
- Capabilities are icon-and-name details; four show initially. Tags have a quiet neutral fill;
three show initially. Keyboard-accessible overflow controls reveal each complete set.
- Card footers align usage and actions. Body content can grow naturally; never clip channels
or enforce a fixed card height to match a visual reference.
Agent channels are core configuration, placed above tags in the card body. Preserve transport
names, lifecycle indicators, empty/unloaded states, management permissions, and links to
Integrations. Container width controls the visible channel count and accurate overflow.
Agent suspension and lifecycle override a channel's live indicator. Harnesses have no channels
because endpoints belong to agents. The production behavior lives in
`src/components/agents/agent-card-channels.tsx`.
List screens give the main content the available width. Put status filtering and counts in
one control strip; omit duplicate masthead counts and summary rails. Preserve genuine filters
such as category and provider as toolbar controls. Contextual rails remain useful on detail,
editing, and operational screens with richer filtering. Footers are optional and explain
partial results or pagination rather than repeating the tabs.
Example discovery shows one compact row of previews with descriptions and import/setup actions;
the full example gallery keeps its configuration details. Navigation selection uses a narrow
primary marker and a faint primary tint, with section spacing instead of repeated separator rules.
### Composition invariants
- Top-level entity screens compose the five-zone primitives in
`src/components/layout/page-layout.tsx`: breadcrumb, masthead, control strip,
body, and optional footer. Lists use the main column; contextual screens can add a rail.
List, detail, and edit pages supply content without
inventing a parallel shell.
- Domain cards compose shared primitives. For example, `AgentCard` composes
`EntityCard`, which composes `Card`; previews must render `AgentCard` when they
claim to show an agent card.
- Entity-specific styling belongs in the domain component, while navigation,
identifiers, responsive action behavior, border treatment, and card anatomy
belong in the shared primitive.
- Create actions use one `accent` button at the far right. Edit forms use one
`default` commit button followed by an `outline` discard action. Read-only
action clusters are otherwise `outline` or `ghost`.
- Headings, buttons, menu items, and badges use sentence case. API-facing names
and identifiers remain verbatim and use Geist Mono when code-adjacent.
## Do's and Don'ts
- **Do** keep every corner sharp.
- **Do** reserve gold (`accent`) for active states, focus rings, and highlights;
use navy (`primary`) for the single most important action per screen.
- **Do** use `success`, `warning`, `info`, and `destructive` for status meaning;
keep raw palette colors only for categorical or ordinal encodings.
- **Do** keep explicit palette ramps for pass-rate and worker-load thresholds,
categorical dashboard and cost series, workflow event types, file-type icons,
folder icons, model-family labels, and favorite stars. These colors
distinguish values rather than communicate status.
- **Do** keep the loading-wave ramp as direct HSL values so its ordered
navy-to-gold sequence remains stable in each theme.
- **Do** keep white text on saturated destructive fills, black scrims, and the
white document canvas used for file previews.
- - **Don't** place dark text on a gold surface or use gold for body text, its
- contrast is too low for WCAG AA.
+ - **Don't** use gold for body text or as a text surface. The one solid gold fill is
+ the create button, whose label is navy (`primary`); other gold uses are tints.
- **Don't** add decorative shadows to content cards or exceed `shadow-md` on overlays.
- **Do** edit `src/app/design-system.css` and this file together, they must
stay in sync.
- **Don't** create lookalike domain examples from lower-level primitives; render
the real domain component.