Design system

Harbor is the StackShip visual language. This page is the specification: every token, every value, and the rules that decide where each one is allowed to appear. If you are building a new page, a new panel, or a new component, build it from this page and nothing else.

The source of truth for the values below is apps/web/app/globals.css. The docs site restates the same palette in apps/docs/src/styles/globals.css using Nimbus --nb-* custom properties. When a value changes, it changes in both files in the same commit.

Where Harbor comes from

StackShip is a system of record for infrastructure change. The register it needs is a Bloomberg terminal or an aviation checklist, not a consumer SaaS landing page. Harbor takes its material from port and freight infrastructure:

• Ink — the deep navy of a hull and of a terminal window. Carries hero bands, footers, plan output, and the docs dark mode.
• Steel — cool neutrals for type, hairlines, and quiet fills. Steel does the majority of the work on every screen.
• Limestone — the near-white canvas panels sit on. Warmer than a blue-gray page and quieter than pure white.
• Signal — one safety orange, the color of a high-visibility vest and a container crane. Rare by construction, so it always means “act here”.

Density is the point. A compact panel carrying twelve facts beats a large card carrying two.

Two implementations, one contract

The same tokens reach the two surfaces through different mechanisms. Neither app may define a palette of its own.

Both files declare the identical ramps with identical hex values. The divergences are deliberate and listed in docs-specific mappings.

The three palette rules

These are not style preferences. A change that breaks one of them is a regression.

1. Signal orange is interface only

Signal marks intent to act and nothing else. It is allowed on:

• primary buttons and primary links,
• the active item in a navigation rail or sidebar,
• focus rings,
• eyebrow labels,
• the brand mark and lockup,
• at most one accent rule per band.

Signal never encodes system state. A run is never orange. A metric is never orange. A chart series is never orange — that is why the chart ramp deliberately excludes it. If orange appears twice in a viewport for two different reasons, one of them is wrong.

2. State is semantic, and always labelled

System state is carried by exactly four families — success, info, attention, danger — and every state indicator carries a text label plus an icon. Color is never the only channel.

3. No new color literals

Components use tokens. No #hex, rgb(), oklch(), or hsl() in a component file. Opacity modifiers on tokens (bg-white/5, border-white/10, text-white/60) and SVG geometry fills that reference tokens are fine. If you need a value that does not exist, the answer is a discussion about the ramp, not a literal.

Surface families

There are exactly two surface families. There is never a third.

Light — reading and operating

Ink — hero bands, terminals, plan output

A white panel that sits on top of an ink band uses shadow-ink. Mixing the two families inside one panel — a limestone fill inside an ink card, steel-500 body copy on navy — produces the muddy third family the rules exist to prevent.

Token contract

Ink ramp

Navy surfaces. Six stops, all absolute.

Steel ramp and limestone

Cool neutrals. Steel carries type, hairlines, and quiet fills.

Signal ramp

The brand accent. Interface only — see rule 1.

Semantic state

Every family has three variants: the saturated value for text, icons, and borders on light; a -soft tint for fills on light; and an -on-ink lift for navy surfaces.

Utilities are text-success / bg-success-soft / text-success-on-ink and the equivalents for the other three. The base values are chosen to clear 4.5:1 on limestone and white; the -on-ink values clear it on ink-950 and ink-900. Do not use a base value on ink, and do not use an -on-ink value on white.

A destructive control needs the label, the icon, and a confirmation step. danger on its own is not a guardrail.

Chart ramp

Data visualization gets its own ramp, deliberately excluding signal so a chart series can never be mistaken for an action.

When a chart encodes state rather than an arbitrary category — a run outcome breakdown, for example — use the semantic families instead, so the chart agrees with the tables next to it.

shadcn semantic mappings

These are the tokens shadcn/ui primitives read. Use the semantic name in components, not the ramp stop it resolves to.

--secondary-foreground and --accent-foreground resolve to #2c4260, an ink mid-tone that exists only as a semantic value. Do not copy that literal into a component; use text-secondary-foreground or text-accent-foreground.

Control plane shell tokens:

Docs-specific mappings

The docs site adds a small number of properties the dashboard does not need, and renames one family to match what Nimbus internals expect. Values are unchanged.

Docs layout measurements, also tokens:

Typography

Three faces, each with one job. The dashboard loads them through next/font (apps/web/app/layout.tsx); the docs site self-hosts them with @fontsource.

Both apps set font-feature-settings: "cv02", "cv03", "cv04", "cv11", "ss03" on the document so Inter’s single-storey glyphs stay legible in dense tables.

Tracking is load-bearing

IBM Plex Sans sets wide and reads soft at display sizes. Negative tracking is part of the specification, not a flourish. The dashboard applies letter-spacing: -0.022em and text-wrap: balance to h1–h4 in the base layer; the docs site sets per-level values.

Type scale

Headings are sentence case, always. Never Title Case.

Where mono is mandatory

Not a stylistic option. Use font-mono for:

• run ids — run_01K3F8PJ2M
• commit shas — 8f4b0ac
• resource addresses — module.network.aws_vpc.main
• versions and provider constraints — ~> 5.0
• plan output and plan counts — +12 ~3 −1
• CLI commands — stackship run watch run_01K3F8PJ2M
• endpoint paths — POST /v1/runs
• any number compared down a column

Tables and elements marked data-numeric get font-variant-numeric: tabular-nums from the base layer in both apps, so figures line up without extra classes. Plan counts use the real minus sign, U+2212 (−), not a hyphen.

Shape

One radius base, --radius: 0.5rem, with five derived steps.

No pill shapes. The only exceptions are avatars and status dots, which are circles.

Elevation

Shadows are cool-tinted, shallow, and never colored. A glow is never applied to a button.

The docs site exposes the same first three as --nb-shadow-sm, --nb-shadow, and --nb-shadow-lg, and darkens them in dark mode where a cool tint would be invisible.

Motion contract

Named animations, defined once in globals.css:

Not allowed: parallax, autoplaying carousels, scroll-jacking, animated gradients, more than one harbor-glow per band.

Both apps zero out animation and transition durations under prefers-reduced-motion: reduce in globals.css. Do not defeat that with inline styles or JavaScript-driven animation that ignores the query. If an animation carries meaning, the meaning must also be present in text.

Surface utilities

Hand-written classes that exist in both apps. Reuse them rather than reimplementing the effect.

Any code, terminal, table, or log region that can overflow must remain keyboard reachable. Give a standalone scroll container role="region", tabIndex={0}, and a specific accessible name so keyboard and screen-reader users can identify and scroll the region without a pointer.

Density and layout

The dashboard is an operating surface, not a marketing page.

• A persistent left rail carries organization, project, and workspace hierarchy. The active item is the one place signal appears in the rail.
• The page header keeps the current scope, documentation, and identity controls reachable.
• Overview pages lead with health and run state, then workspace inventory, then recent audit activity.
• Run pages expose durable planning, policy, approval, apply, and terminal states, each with its own state label and icon.
• Dense data lives in tables. Cards carry summaries and bounded workflows. Prefer an information-rich panel over a large empty one.
• Plan output and log streams sit on an ink surface in font-mono, with harbor-scroll-ink.
• Loading, empty, unavailable, and error states are explicit and never represented as invented sample product data.

At narrow widths the rail becomes a sheet, tables drop secondary columns rather than scrolling horizontally, and the run lifecycle becomes a vertical list. Primary actions stay reachable without horizontal scrolling. Long identifiers wrap or truncate inside their owning panel; a monospace workspace, run, state, or commit identifier never creates horizontal page overflow.

Identity surfaces

Sign-in, sign-up, and OAuth consent use the same language as the control plane — they are the first screen a security reviewer sees.

• Pair a single focused form with product and security context. No decorative illustration.
• Keep enterprise SSO visually distinct from consumer login methods, and label it as such.
• Error states are explicit, in danger, with a label and an icon, and they say what to do next.
• OAuth consent explains each scope in plain language, names the client, and accurately describes the token’s tenancy, lifetime, and available revocation behavior. It does not invent settings controls or audit events.

The brand mark is a sanctioned use of signal. apps/web/components/stackship-mark.tsx exports StackShipGlyph, StackShipMark, and StackShipLockup.

Use tone="ink" when the lockup sits on a light surface next to a primary orange action, so the logo does not compete with the button.

The production browser icon is served from /favicon.ico. It uses the same StackShipGlyph geometry with signal-500 behind an ink-950 glyph; keep the root metadata and favicon route synchronized when the mark changes.

Accessibility floor

Part of the definition of done, not a later pass.

• Body copy holds at least 4.5:1 against its surface. Concretely: never text-steel-400 body copy on white or limestone, and never text-steel-500 on ink. Use steel-500 as the lightest text on light surfaces and steel-300 as the lightest on ink.
• Every interactive element has a visible focus indicator. The dashboard uses outline-ring/45 from the base layer; the docs site uses a 2px --nb-ring outline with a 2px offset. Do not remove either.
• Icon-only controls carry aria-label. Decorative SVG carries aria-hidden.
• State is never color alone — label plus icon, every time.
• Real button and a elements. Never a clickable div.
• Heading levels run in order with no skipped levels.
• Tables have real th elements with a scope.
• No emoji, in interface copy or documentation.

shadcn rules

• Generate primitives with the shadcn CLI. They live in apps/web/components/ui.
• Build product components by composing primitives. Do not fork a primitive to change its color.
• Reference semantic utilities — bg-background, bg-card, text-foreground, border-border, bg-primary, text-muted-foreground — rather than ramp stops, wherever a semantic name exists. Reach for ink-*, steel-*, and signal-* directly only for ink bands and brand moments, where no semantic token applies.
• Do not paste in arbitrary component collections, and do not introduce a second token system.

Changing a token

1. Edit apps/web/app/globals.css. It is the source of truth.
2. Mirror the change in apps/docs/src/styles/globals.css, including the [data-mode="dark"] block and the @theme mapping.
3. Update the tables on this page. Documentation is part of the definition of done — see the engineering rules.
4. Check contrast for both surface families before and after.