Design system

Shipyard's dashboard is built on Drydock: graphite and concrete neutrals carry the interface, one signal colour marks what you can act on, and status colours are reserved for state. It is deliberately quiet. The interesting thing on screen should be your services, not the chrome around them.

The source of truth is frontend/src/routes/layout.css (tokens) and frontend/src/lib/components/ui/ (components). This page documents both. If you are building a screen, an extension or a generated UI, follow it.

#Principles

1. One signal. --accent (orange) means this is the action or this is where you are. Never use it for decoration, charts or illustration.
2. Status is state. Green, red, yellow and blue only describe the state of something — running, failed, pending, informational. They never decorate.
3. Never colour alone. Every status also has a shape or a word: a glyph, a label, a badge. Colour-blind users and grayscale screenshots must read the same.
4. Flat by default. Surfaces are separated by 1px rules, not shadows. Shadows exist only on things that float: menus, drawers, dialogs.
5. Machines speak mono. IBM Plex Mono is for what a machine produced or will read — image refs, ports, hashes, slugs, log lines. Prose is always Plex Sans.

#Colour

All colours are CSS custom properties on :root, redefined under [data-theme="dark"]. Components reference tokens, never hex values.

#Surfaces

#Navigation rail

The rail is graphite in both themes so navigation reads as one fixed object.

#Signal

#Status

Each status has a solid, a -muted fill for backgrounds and a -text for words on that fill.

#Text

#Terminal

Logs, build output and exec sessions sit on a dark surface in both themes, so output looks the same wherever it appears.

#Typography

Fonts are bundled with @fontsource rather than fetched from Google Fonts: Shipyard is self-hosted and often runs on networks without outside access.

#Shape, elevation, motion

All motion respects prefers-reduced-motion. Focus is always a 2px --accent outline with a 2px offset.

#Components

Components live in $lib/components/ui and are imported from its index:

<script lang="ts">
  import { Button, Badge, SearchInput, Select, Toggle, PageHeader } from '$lib/components/ui';
</script>

#Buttons

<Button variant size> with variants primary, secondary, ghost, danger, danger-outline and sizes sm (30px), md (36px), icon (32px square). Hover and press are a currentColor overlay at 8% / 12%, so every variant gets the same feedback. One primary button per view.

#Badges and status

<Badge tone> for a state word (green, red, yellow, blue, neutral); <StatusDot> for a compact live state next to a name. Pair a dot with text whenever there is room.

#Segmented control

Filters with a handful of mutually exclusive options (time range, log level, source) use a segmented group: one surface with a 1px border, the selected segment filled with --accent-muted and labelled in --accent. Levels add a glyph so the state is not carried by colour alone: ◆ error, ■ warn, ● info, ○ debug.

#Navigation rail

The rail is the app's primary navigation: a 64px graphite column with the brand mark, destinations and account controls. Each destination is one target containing its icon tile and label.

The current destination gets three cues together:

• a 3px --accent bar flush with the rail's leading edge, 22px tall and rounded on its outer side — it sits outside the icon tile so the tile's radius never clips it;
• the icon tile filled with --rail-active-bg and the icon stroke thickened;
• the label in --rail-fg-active at weight 600.

Hovering an idle destination previews the bar as an 8px neutral tick. On phones the rail becomes a 56px bottom bar and the indicator moves to the top edge.

#Panels and drawers

• Nav drawer — opens beside the rail for a group's sub-pages (admin) or the project list (tenant). Active item: --accent-muted fill, --accent label.
• Slide panel — detail views for one resource open from the right at --slide-panel-width, stacked through uiStore.pushPanel(). Actions inside a detail panel push a sub-panel; they never inline a form.
• Dialog — confirmation for destructive actions, always requiring the resource name to be typed.

#Log console

Runtime logs use the terminal surface. Columns are time, level, origin and message; rows are 12px mono at 1.55 line height. Error and warn rows carry a 2px leading bar in their level colour; the selected row uses the signal bar instead. Masked secrets render as a dim ••• [kind] chip. Selecting a row opens a detail pane beside the console with the full message, metadata and structured fields.

#Page layout

• Tenant pages: rail → project drawer (collapsible) → page content on --bg-base, padded 20px 28px.
• Admin pages: rail → modal nav drawer → page content, padded 24px 28px.
• Every page opens with <PageHeader eyebrow title subtitle actions>; the eyebrow names the area ("Observability"), the title names the page.
• Content width follows the content: tables and consoles go full width, forms cap at about 640px.

#Do and don't