Guidelines
Color
Palette
--bw-* in packages/design-system/styles/system/colors.css and exposed as Tailwind colours: bg-bw-black, text-bw-dark-gray, border-bw-light-gray. Each chip shows the better of black or off-white type on it, with its WCAG contrast.Neutrals
Most of every page. Black type on off-white, greys for everything that should step back.
Black
#0e0f11
bg-bw-black
Type, the dark theme's background, the solid button.
Darkest gray
#373737
bg-bw-darkest-gray
Raised surfaces on black: cards and panels in the dark theme.
Dark gray
#5c595c
bg-bw-dark-gray
Secondary text on light: leads, captions, metadata.
Medium gray
#adaaad
bg-bw-medium-gray
Secondary text on dark, placeholders, quiet labels.
Light gray
#d9d9d9
bg-bw-light-gray
Rules, dividers and card borders on light.
Lightest gray
#f7f8f9
bg-bw-lightest-gray
Hover fills and wells: a card behind a specimen.
Off-white
#f9f7f5
bg-bw-off-white
The page. Warmer than white, so photography sits softly on it.
White
#ffffff
bg-bw-white
Pure white: type on black in the dark theme, and cards on the page.
Brand
One brand colour per theme, never both on one surface. Reach them through the brand token, not by name.
Blue
#185cf6
bg-bw-blue
The brand colour in the light theme: links, underlines, selection.
Orange
#fb3e03
bg-bw-orange
The brand colour in the dark theme, and the poster moments.
Supporting
Used sparingly, in campaigns and prototypes, and for state. Never as a page background.
Green
#076248
bg-bw-green
Success and the Do column; campaign accents like the startup sprint.
Purple
#783bfa
bg-bw-purple
Campaign accent. Illustrations, stickers, a highlighted plan.
Pink
#f9beff
bg-bw-pink
Campaign accent, paired with black type. Never with white.
Red
#e11837
bg-bw-red
Errors and the Don't column. Nothing decorative.
Brand and accent
--brand is Builtwell's colour: bw-blue in the light theme, bw-orange in the dark one. Use it for the things that say Builtwell: links, underlines, the key call to action, text selection. --accent is not a brand colour. It is the neutral grey that shadcn menus, selects and commands use for hover and highlighted rows. If it should look like Builtwell, it is brand; if it is a hover state, it is accent.Read the case study, then start a project.
Light: brand is bw-blue, accent is a near-white grey.
Read the case study, then start a project.
Dark: brand is bw-orange, accent is a dark grey.
// The brand, whatever the theme
<a className="text-brand underline">Read the case study</a>
<Button className="bg-brand text-brand-foreground">Claim your sprint</Button>
<div className="border-brand border-b-2" />
// Not the brand: hover and highlight in menus
<DropdownMenuItem /> // uses bg-accent on highlight, set by shadcnSemantic tokens
.light, :root and .dark in packages/design-system/styles/globals.css. Each chip is painted with the live variable inside that theme. Use them as utilities: bg-background, text-muted-foreground, bg-brand.| Token | Light | Dark | Use |
|---|---|---|---|
--background | bw-off-white | bw-black | The page. bg-background. |
--foreground | bw-black | bw-white | Body type on the page. text-foreground. |
--primary | oklch(0.205 0 0) | bw-white | The solid button and strong fills. Ink, not a colour. |
--primary-foreground | oklch(0.985 0 0) | bw-black | Type on primary. |
--muted | oklch(0.97 0 0) | oklch(0.269 0 0) | Quiet wells: skeletons, disabled fills, code backgrounds. |
--muted-foreground | bw-dark-gray | bw-medium-gray | Secondary text: descriptions, helper text, captions. |
--accent | oklch(0.97 0 0) | oklch(0.269 0 0) | Neutral hover and highlighted rows in menus, selects and commands. |
--accent-foreground | oklch(0.205 0 0) | oklch(0.985 0 0) | Type on accent. |
--brand | bw-blue | bw-orange | The brand colour. bg-brand, text-brand, border-brand. |
--brand-foreground | bw-off-white | bw-black | Type on brand. Also the ::selection text colour. |
--border | oklch(0.922 0 0) | rgb(from var(--bw-white) r g b / 0.2) | Every default border, through the base layer. |
--input | oklch(0.922 0 0) | oklch(0.325 0 0) | Field borders. |
--ring | oklch(0.708 0 0) | oklch(0.556 0 0) | Focus rings. |
--destructive | oklch(0.577 0.245 27.325) | oklch(0.704 0.191 22.216) | Errors and destructive actions only. |
Contrast
Type on the page
bw-black on bw-off-white
Leads and captions
bw-dark-gray on bw-off-white
Placeholders and quiet labels only
bw-medium-gray on bw-off-white
Type in the dark theme
bw-off-white on bw-black
Secondary text in the dark theme
bw-medium-gray on bw-black
text-brand, light theme
bw-blue on bw-off-white
brand-foreground on brand, light
bw-off-white on bw-blue
text-brand, dark theme
bw-orange on bw-black
brand-foreground on brand, dark
bw-black on bw-orange
Rules
- Reach the brand colour through
bg-brand,text-brandandborder-brand, never bw-blue or bw-orange by name, so it follows the theme. - One brand colour on a surface. Blue and orange never share a screen.
- No big orange fills. Orange is for a line, a button, a word; the poster moments are the exception, and they are rare.
accentis for hover and highlighted rows. Don't use it to make something look on brand.- Medium gray is not for body text on off-white: it fails AA. Use dark gray.
- Green and red mean success and error before they mean anything else. Use them as accents only in campaigns.
destructiveis for errors and destructive actions, and nothing decorative.