Whale Design System

The Whale Design System is the single source of truth for how Whale products look and feel. It defines the brand and the foundational design tokens — color, typography, radius, spacing, elevation, and iconography — that every Whale surface consumes, from operator back-office and product applications to embedded client experiences and this documentation portal.

Its job is to make Whale feel like one product. Individual surfaces differ in their workflows and density, but they share one brand color, one type system, one neutral scale, and one set of interaction primitives.

This foundation defines tokens and brand, not components. Read it when you are choosing a color, a type size, a corner radius, a control height, or an icon — or when you are setting up a new Whale surface and need the shared base.

Every surface consumes the same foundation. Where a surface adds product-specific components or page patterns, those extend this foundation — they never redefine its tokens.

• Declare tokens once, centrally. Each surface holds the canonical values in one theme layer and references them by semantic role (primary, foreground, border, …). Product code never hardcodes a brand or neutral hex.
• Derive interaction states from tokens. Hover, pressed, focus, and disabled states are derived centrally from the ramp, not sampled ad hoc per component.
• Opt into color modes explicitly. Light is the authoritative baseline. A surface declares which modes it supports; some are light-only (see Color → Color modes).
• Adopt incrementally. A surface that predates this foundation converges its outliers (brand hex, neutral scale, fonts) over time rather than in one rewrite.

• This foundation owns brand and token values and their semantic roles.
• Product surfaces own their own components, layouts, and page patterns, built on top of these tokens.
• Proposed changes to a token affect every surface — treat them as system-level changes, not local tweaks.