Style guide and design system

Colour

Surfaces

Ink

Lines

Accent

Semantic

The top bar

Status: colour and shape

A state is never told by colour alone. Each tone of chip has its own shape before its words, so the chips read apart in grey too. The chip says the API's label; its tone follows the state the API answered (toneOf in web/src/ui.ts).

Contrast

The ratios below are worked out from the hex values above, with the WCAG formula. Text needs 4.5:1, large text and the parts of a control 3:1.

Typography

One system font stack for everything, and a monospace stack for code and values. No web font is loaded: the CSP lets a page load only the console's own files.

--font: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", "Noto Sans", Arial, sans-serif;
--mono: ui-monospace, "SF Mono", "Cascadia Mono", "Roboto Mono", Menlo, Consolas, monospace;

The type scale

Spacing and shape

Space

Corners

• --radius-sm4 px: code, a file chooser's button
• --radius6 px: buttons, inputs, notices, menus, code blocks
• --radius-lg10 px: panels, cards, tables, dialogs, empty states
• 999pxChips (not a token)
• 50%Icon buttons, the avatar, a row's ⋮ button (not a token)

Shadows

• --shadow-smThe primary button, notices, a phone's row card
• --shadowMenus and popovers; the skip link
• --shadow-lgDialogs, the sign-in card, the navigation drawer

Sizes

• 36 px--controlButtons, inputs, selects
• 44 px--control, on phonesAt 640 px wide and narrower, and on any touch screen
• 56 px--bar-heightThe top bar

Components

Each is drawn below with the console's classes. Buttons and fields are live: point at them, or reach them with Tab. The top bar, the navigation, the tabs and the page header are pictures, as this site draws the console's screens.

Buttons

Disabled

At 45% opacity, with a not-allowed pointer and no fill. In the bar of actions over a table, a button that does not apply yet is muted rather than faded.

Busy

While its request runs, the control that sent it is disabled and marked aria-busy="true" (busy() in ui.ts; a form's submit gets the class sending). It keeps full colour, shows a progress pointer and a turning ring after its words, and a second tap sends nothing.

Icons

A toolbar button wears the icon its words name (Refresh, Create, Edit, Pause, Resume, Delete and the rest); the words stay the button's text.

Chips

Use it for

A state, in the API's own words: a task's, a job's last run, a key's, a usage level.

Never for

An action or a link, or a tone the page works out for itself.

Panels and summary cards

Summary cards

Use them for the few counts at the top of a details page or the dashboard (a queue's: Tasks in queue, Tasks running, Completed in the last minute, Location, Type). Never for navigation: the write-up's link cards do that. Two to a row on a phone.

Panels

Use one for a titled part of a page: a form, a list, label and value pairs. Never for a single line of text, or for a state: that is a chip or a notice.

Tables

Wide screens

A table sits in a frame (.table-frame) and scrolls inside it, never the page. Its header row stays in view while a long table scrolls, the row under the pointer is --raised, a ticked row is --accent-soft, and the last column, with the row's ⋮ menu or buttons, stays at the right edge however wide the table is.

Phones

At 640 px and narrower the header row is hidden and each row is a card. Every cell carries its column's name in data-label, shown beside its value. The Name (or Email) cell is the card's title, without a label; the tick box and the ⋮ menu sit in the card's top corners; cells marked extra wait behind Show details at the card's foot. (This site's copy puts each label above its value instead.)

Use it for

Rows of the same kind: tasks, jobs, keys, people, attempts. With no rows, an empty state in its place.

Never for

Laying out a form, or one item's details: those are label and value pairs.

Forms

Label

Every field has a visible label above it, tied to its control (form.field() in web/src/form.ts).

Hint

Muted, at --text-sm, under the control, and read with it (aria-describedby).

Field error

The API's message for that field, in red under it; the control's border turns red and it is marked aria-invalid. The page never checks what was typed: it sends it, and shows each fields message at the input its path names (headers.X-Foo goes to headers). The first field in error takes the focus.

Form message

At the form's top, red with a thick left edge and role="alert": a refusal with no field of its own, or Check these: and a list of the messages that have no input. A refusal of a chosen file lists each message with its path in the file, such as tasks.3.url.

File chooser

The text box's frame, its button drawn as the console's own in either theme (::file-selector-button), not the browser's.

Never

A placeholder in place of a label, or a page's own check of the input.

Notices and banners

Notice

One live line per page, kept in view under the top bar while the page scrolls: what was done (ok), or the API's error (bad). A new one replaces the last. It arrives with a short fade and drop, and has a Dismiss button.

Banner

Above the page's content. Warn: one for each maintenance switch that is on, with who switched it and when. Info: a newer build of the console, with Reload and Later; and on a queue's Logs tab, Only failed attempts are logged. Turn on success sampling to keep a share of the successful ones too.

Never for

A field's own problem (that goes beside the field), or anything that must stay on screen after the next action.

Tabs

A picture of a queue page's tabs, Tasks chosen.

How

44 px tall, muted words; the chosen tab in accent at 600 with a 3 px bar under it. A strip wider than the screen scrolls sideways, with a shade at an edge while more is hidden past it; on a phone it runs to the screen's edges, and the chosen tab is scrolled into view. The chosen tab is kept in the address (?tab=).

Use it for

Views of one thing: a queue's Metrics, Logs, Tasks, Configuration and Failed; a job's Logs, Results and Configuration.

Never for

Steps that must be done in order: the job form uses numbered steps with Continue and Back.

The top bar and the navigation

A picture of the console's frame: the top bar, the left navigation with Queues current, and a task page's breadcrumbs and header.

Top bar

Navy (--bar-bg) in both themes, 56 px, kept at the top while the page scrolls. From the left: the menu button (960 px and narrower), the mark and name (a link to the dashboard), the project picker, then the theme menu (System, Light, Dark) and the person's menu: who they are, the version, Your account, Sign out, and Sign out on every device.

Navigation

Grouped: Dashboard, Projects and Usage; then, with a project chosen, Cloud Tasks (Queues), Cloud Scheduler (Jobs) and Project settings (API keys, Secrets, Alerts, Export and import); then Admin (People, Audit log). An entry shows only with its permission: API keys with keys, Alerts with update, People and Audit log for admins. The current one is accent on --accent-soft with a 3 px accent edge at its left. With no project chosen it says Choose a project to see its queues, jobs and settings.

This site

The bar under this page's top bar (.subnav) is the write-up's own navigation, not the console's.

Breadcrumbs and the page header

Breadcrumbs

Muted at --text-sm, a / in --line-strong between the steps, the page itself in ink and not a link (crumbs() in ui.ts). On a phone each link's target grows taller around its line.

Page header

The title (h1), a chip with its state when it has one, then the page's own buttons, flat on the page; a line under it all. On a phone the buttons go to rows of their own under the title.

Never for

Breadcrumbs as the only way back: the navigation is always there.

Empty states and loading

Empty

The empty icon, then one line that says what would be here and, where it helps, why: No failed tasks. Failed tasks are kept for 7 days. A table with no rows is an empty state instead.

Could not load

The error in place of what could not be loaded, a red left edge, role="alert", and Try again. Never a blank page.

Loading

Until a page's first answer: its words (Loading the keys…) over a pulsing skeleton of rows, marked aria-busy.

Dialogs and values shown once

Confirm dialog

A modal over the scrim, before something that cannot be undone: the question, what it means, Cancel (quiet) and the action (danger). Escape cancels, and the focus goes back to the control that opened it (confirmAction()).

Shown once

A new API key or signing secret: warn colours, the warning, the value in a read-only field and Copy. When the clipboard is not there, the value is selected for the person to copy (The text is selected: copy it from there).

Never for

A question before a safe action, or a value the console can show again.

Icons

Each is a line drawing on a 24-unit grid, in currentColor, 18 px in a button, with a 1.8 stroke and round ends (web/src/icons.ts). An icon is hidden from screen readers: the button or link it sits in carries the words. No icon font and no CDN.

• dashboardDashboard, in the navigation
• projectsProjects, in the navigation
• usageUsage, in the navigation
• queuesQueues, in the navigation
• jobsJobs, in the navigation
• keysAPI keys, in the navigation
• secretsSecrets, in the navigation
• alertsAlerts, in the navigation
• usersPeople, and Your account
• auditAudit log, in the navigation
• refreshRefresh
• addCreate queue, Create task, Create job, Create project, Invite, Create HTTP task, Create tasks
• editEdit
• pausePause
• playResume, Run now, Force run, Run task
• retryRetry, Retry all
• deleteDelete, Delete all, Delete task
• purgePurge
• copyCopy; Export and import, in the navigation
• menuThe menu button that opens the navigation (960 px and narrower)
• moreA row's ⋮ menu, and a details page's More actions
• systemThe theme menu, and its System choice
• lightThe theme menu's Light choice
• darkThe theme menu's Dark choice
• emptyAn empty state, and what could not be loaded
• closeDismiss this message, on a notice
• columnsColumns, the column chooser
• chevronShow details, on a phone's row card
• logoThe mark: a queue of three calls leaving on a schedule. Accent tile; on the bar, --bar-logo

Motion and micro-interactions

The ring turns and the skeleton pulses. Point at this box to see the notice arrive again.

Reduced motion. With prefers-reduced-motion: reduce every animation and transition is off, on elements and on their ::before and ::after: the ring and the skeleton stand still, and notices appear at once.

Accessibility rules the console follows

Built from Cloud Console's main branch (CAP-162), 22 Oct 2026. Example values only: no real keys, emails or ids.