Design Language#
This page gives the visual rules of the OSPREY browser interfaces and the
shared parts that put them into practice. The token contract and the
enforcement details are in src/osprey/interfaces/design_system/DESIGN.md.
Read both before you change a token, a shared primitive, or the web terminal
shell.
Principles#
The operator comes first. The chrome is quiet, and the content of a pane gets the space.
Each pane has one header row. A panel never draws a second title row in its body.
State is never shown by hue only. Add a shape or a word: a bar, an outline, a check mark, a label. The high-contrast themes have no hue.
Use the shared tokens and the shared primitives. Do not make a local copy with other values.
Popovers and tooltips sit at body level with fixed position, so a scrolled container does not cut them.
Token layers#
The tokens have three layers. The generator in
design_system/generator/ reads all three and writes tokens.css,
tokens.js and theme-boot.js.
Core primitives (
tokens/core.json): the color ramps and the scales for type, weight, leading, space, radius, z-index and duration. Color steps are never emitted directly.Themes (
tokens/themes/*.json): eight themes, four families in a dark and a light mode. Each theme aliases a core color step, one hop away, into a semantic name such asbg.primaryorsurface.card.Interface extensions (
tokens/interfaces/*.json): values that only one interface needs, for example the web terminal’s--wt-*sizes.
Never edit the generated files. Edit the JSON, then run the build (see Change process).
Surfaces#
There are four surfaces, from the deepest to the highest:
Surface |
Token |
Use |
|---|---|---|
Canvas |
|
The page under the cards. The sidebar sits on the canvas, with no card. |
Card |
|
A pane. Cards have a |
Raised |
|
The tooltip and a small badge on a card. |
Floating |
|
Popovers and flyouts. |
--surface-well is a recessed area in a card, for example the body of the
artifact viewer. It is between the canvas and the card in every theme.
The washes mark state on these surfaces: --surface-hover,
--surface-press (pressed or open), --surface-selected and
--surface-focus (the focus halo). They are alpha values, so they work on
every surface.
Use the surface tokens, not a --bg-* token, for the shell. The bg.*
steps do not keep the same depth order in all eight themes. The surface group
does.
Type and space#
Size text with
--text-*, weight with--weight-*and line height with--leading-*.Use
--space-*for padding, margin and gap.Use
--radius-*for corners:--radius-lgfor buttons and rows,--radius-xlfor cards and popovers.Use
--duration-*for motion, with--wt-ease-outfor the sidebar and for disclosure.--wt-transition-*is legacy. Do not use it in new CSS.Buttons use the display font (
--font-display), never the mono font.Panel titles and sidebar labels use title case, not capital letters only.
Color and state#
Use the semantic color tokens:
--text-*,--color-accent,--color-success,--color-warning,--color-error.A selected row gets
--surface-selectedand an accent bar at its left edge.A status dot (
.osprey-dot) shows the state by fill and shape..okadds a halo..hollowis an outline with no fill, for a closed pane.The validator applies WCAG contrast gates to the text tokens on
bg.primary. The high-contrast family must pass AAA. Text on a card is not gated, so keep it on the same text tokens.
Layout shell#
The web terminal uses one shell:
A sidebar on the canvas at the left. It is
--wt-sidebar-width(232 px) with labels, 180–400 px by the handle on its right edge, or--wt-sidebar-collapsed-width(56 px) with icons only. The state isdata-sidebaron<html>.sidebar-boot.jssets it, and the stored width, before the first paint.From top to bottom, the sidebar holds the OSPREY mark and the collapse toggle, the control-system block, search, the
WorkspaceandAppssections, and a footer with Docs, Feedback and More. Only theWorkspacesection gives up height.The panes are cards in the dock. Each pane has one header row,
--wt-pane-head-height(40 px) high.The agent pane can close. Then
<html>getsdata-agent="closed", and the sidebarAgentrow opens the pane again.
Primitives#
The shared primitives are in design_system/static/css/primitives.css.
Load it after base.css. Their behaviour is in the modules in
design_system/static/js/:
Part |
What it gives |
|---|---|
|
The sidebar row (icon, label, badge, disclosure) and the group heading. |
|
The child row of a sidebar list, with a title and a time. |
|
Icon button, text button, row action and segmented control. |
|
The inset card, its header row and the breadcrumb. |
|
Menus and flyouts. |
|
One tooltip layer for the whole page. It shows a label and a one-line
explanation ( |
|
The collapse state, its storage, and the pre-paint stamp. |
|
|
|
Status dot, keyboard hint, count pill, switch and search field. |
|
The panel toolbar, the text segmented control, the search field and the status chip of a panel. |
|
The panel sidebar. It is 260 px wide, it resizes, and it is stored for each user. In a narrow panel it opens over the content. |
|
The centred state, the info popover and the content strip. |
DESIGN.md section 9 lists every class and the API of each module. The
reference page, /design-system/reference.html, shows each primitive in all
eight themes.
Keyboard and focus#
Every control shows
:focus-visiblewith a 2 px accent outline.A popover moves focus to its first item when it opens. Escape closes it and moves focus back to the control that opened it.
⌘\on macOS, orCtrl+\on other systems, collapses and expands the sidebar.⌘KorCtrl+Kopens search.Get the modifier for a hint from
platform.js(isMacPlatform()). Do not write⌘for all systems.A collapsed sidebar row has an
aria-label. The tooltip repeats the label but is not the accessible name.Use
focus-trap.jsin a dialog.
External panels#
A panel that runs in its own process links the shared files by root-absolute paths. The terminal proxy serves its own copy:
<link rel="stylesheet" href="/design-system/css/tokens.css">
<link rel="stylesheet" href="/design-system/css/base.css">
<link rel="stylesheet" href="/design-system/css/primitives.css">
When the terminal embeds a panel, the panel hides its own top bar and sends
its controls to the pane header through header-contrib.js (header
contract version 1). Panels gives the panel
contract, and Theming gives the theme families.
Enforcement#
generator.build --checkfails when a generated file differs from the token JSON. The validator ingenerator/validate.pychecks one-hop aliases, the same token set in each theme, the interface groups for each theme, and the WCAG gates.tests/interfaces/design_system/test_hygiene.pyfails on a color literal, on avar()that no token defines, and on a local:rootcopy of a token. Inweb_terminal,design_system,arielandchannel_finderit also fails on a raw font size, weight, line height, radius or duration.tests/interfaces/test_js_module_tests.pyfails when a module instatic/js/has no Vitest file with the same name.tests/interfaces/design_system/test_visual.pycompares screenshots with committed baselines for the dark and light themes.
Change process#
Edit the token JSON in
design_system/tokens/. Add a new token to all eight themes.Run the build from the repository root:
uv run python -m osprey.interfaces.design_system.generator.build
Run the build again with
--check. It must exit with code 0.Add a specimen to
design_system/static/reference.htmlfor a new primitive.Update
DESIGN.md.Add a fragment to
changelog.d/.
Adding a token name is safe. Renaming or removing a token breaks external panels that use it, so keep the old name until every panel has moved.