Point the site color variables at the design system's generic tokens by enf0rc3 · Pull Request #3264 · OctopusDeploy/docs

enf0rc3 · 2026-07-28T21:21:19Z

Background

The docs site now loads @octopusdeploy/design-system-tokens as CSS custom properties (#3261), and its raw palette already maps onto the token color scales (#3262). Nothing was consuming the tokens yet.

vars.css still defined its own semantic layer — text, borders, surfaces, links, callouts — with a hand-rolled html[data-theme='dark'] block maintaining a second set of values for dark mode. That block had drifted: the docs site's light theme was close to the design system, but its dark theme came from a different palette, and several variables had no dark value at all.

This points the site's color variables at the design system's generic tokens — the Text, Border, Background and Icon families intended for consumers.

Results

Visual change, deliberately. Most of it lands in dark mode.

	before	after
`html[data-theme='dark']` overrides	44	23
variables removed as unused	—	9
values changed, light theme	—	39
values changed, dark theme	—	39

What changed

Text, surfaces, borders and links now come from tokens, so they theme themselves:

--color-text        #dae2e9 -> #f4f6f8   (dark)
--color-heading     #ffffff -> #f4f6f8   (dark)
--octo-blue         #1fc0ff -> #87bfec   (dark, links)
--header-bg         #152b3d -> #111a23   (dark)
--code-background   #0c1a24 -> #1f303f   (dark)

Light shifts are small: borders #dae2e9 → #dee1e6, tinted surfaces going neutral #f2f8fd → #f5f6f8, body text #10212f → #282f38. Link color in light does not change (#1a77ca either way).

Callouts were not dark-themed at all. --color-success, --color-warning, --color-problem and their backgrounds and borders had no dark override, so a success callout rendered as #e8ffeb pale green with #04502f text on a dark page. Backgrounds and borders now use the status tokens; text uses --colorTextPrimary rather than --colorTextSuccess and friends, because main.css colors the whole callout block and the status text tokens fail WCAG for body copy (#b98f02 on #fff7d9 is 2.8:1). Contrast improves everywhere in light and stays AA or better in dark:

callout	light before	light after	dark after
hint / info	9.52 AAA	12.63 AAA	8.84 AAA
success	9.09 AAA	12.63 AAA	8.86 AAA
warning	6.50 AA	12.59 AAA	6.18 AA
problem	8.02 AAA	12.46 AAA	8.83 AAA

One override kept on purpose. The side navigation is a recessed panel, darker than the page. The design system's dark backgrounds only step lighter from --colorBackgroundPrimaryDefault (#111A23 → #1F303F → #2E475D), so no token describes a surface below the page. Mapping it to a token turned the nav from #0c1a24 into #1f303f, well above the page, so --bg-color-menu stays hand-themed in dark with a comment saying why. Worth raising upstream as a missing token.

Code blocks and icon tiles move the other way for the same reason — #0c1a24 → #1f303f and #132838 → #1f303f. Those are raised surfaces, so sitting above the page is defensible, but see the screenshots.

Two latent bugs fixed. --background-default and --background-light had no dark override, so they resolved to #ffffff and #f2f8fd — white and pale blue — in dark mode.

Off-brand link color corrected. The dark-mode link color was #1fc0ff, which the brand palette lists as Bright Blue, restricted to "UI mockups and illustrations". Link styling belongs to Octopus Cyan.

Nine variables removed, each declared once and referenced nowhere: --navy-600, --blue-100, --blue-200, --blue-qqq, --blue-midnight and --lightest-blue were orphaned when the semantic layer stopped pointing at them; --header-icon-stroke, --header-link-alt-bg and --image-bg were already dead.

Screenshots

Article body — light

before	after

Article body — dark

before	after

Callouts — light

before	after

Callouts — dark

before	after

Navigation and header — dark

before	after

Every changed value

Light theme — 39 values changed

variable	before	after
`--background-light`	`#f2f8fd`	`#f5f6f8`
`--bg-color-hint`	`#e5f4ff`	`#f2f8fd`
`--bg-color-info`	`#e5f4ff`	`#f2f8fd`
`--bg-color-menu`	`#fafdff`	`#f5f6f8`
`--bg-color-problem`	`#fff2ee`	`#fff3f3`
`--bg-color-success`	`#e8ffeb`	`#eefaf5`
`--bg-color-tab`	`#dae2e9`	`#dee1e6`
`--bg-color-warning`	`#fefae9`	`#fff7d9`
`--border-color-header`	`#dae2e9`	`#dee1e6`
`--border-color-menu-open`	`#dae2e9`	`#dee1e6`
`--border-color-problem`	`#ff4848`	`#d63d3d`
`--border-color-success`	`#00b065`	`#00874d`
`--border-color-tab`	`#dae2e9`	`#dee1e6`
`--border-color-tab-active`	`#7c98b4`	`#b2b9c5`
`--border-color-warning`	`#fc8431`	`#b98f02`
`--border-default-color`	`#cde4f7`	`#dee1e6`
`--code-background`	`#f2f8fd`	`#f5f6f8`
`--code-color`	`#10212f`	`#282f38`
`--color-heading`	`#152b3d`	`#282f38`
`--color-hint`	`#124164`	`#282f38`
`--color-info`	`#124164`	`#282f38`
`--color-menu-link`	`#3e607d`	`#515d70`
`--color-menu-link-active`	`#2e475d`	`#282f38`
`--color-problem`	`#931919`	`#282f38`
`--color-subtitle`	`#3e607d`	`#515d70`
`--color-success`	`#04502f`	`#282f38`
`--color-text`	`#10212f`	`#282f38`
`--color-text-secondary`	`#2e475d`	`#515d70`
`--color-warning`	`#a23623`	`#282f38`
`--hamburger-lines-color`	`#274b66`	`#282f38`
`--header-icon-background`	`#f2f8fd`	`#f5f6f8`
`--header-icon-border`	`#cde4f7`	`#dee1e6`
`--header-separator-color`	`#dae2e9`	`#dee1e6`
`--icon-fill`	`#274b66`	`#515d70`
`--icon-tile-background`	`#f2f8fd`	`#f5f6f8`
`--icon-tile-border`	`#cde4f7`	`#dee1e6`
`--icon-tile-border-hover`	`#cde4f7`	`#dee1e6`
`--separator-color`	`#dae2e9`	`#dee1e6`
`--theme-switcher-border`	`#dae2e9`	`#dee1e6`

Dark theme — 39 values changed

variable	before	after
`--background-default`	`#ffffff`	`#111a23`
`--background-light`	`#f2f8fd`	`#1f303f`
`--bg-color-hint`	`rgba(13, 128, 216, 0.1)`	`#0f4778`
`--bg-color-info`	`#274b66`	`#0f4778`
`--bg-color-menu`	`#0c1a24`	`#1f303f`
`--bg-color-problem`	`#fff2ee`	`#802424`
`--bg-color-success`	`#e8ffeb`	`#00502e`
`--bg-color-tab`	`#314c62`	`#2e475d`
`--bg-color-warning`	`#fefae9`	`#745801`
`--body-link-color`	`#1fc0ff`	`#87bfec`
`--border-color-hint`	`#1a77ca`	`#449be1`
`--border-color-info`	`#1a77ca`	`#449be1`
`--border-color-problem`	`#ff4848`	`#ff5d5d`
`--border-color-success`	`#00b065`	`#00ab62`
`--border-color-tab`	`#314c62`	`#2e475d`
`--border-color-tab-active`	`#7c98b4`	`#3e607d`
`--border-color-warning`	`#fc8431`	`#e5b203`
`--border-default-color`	`#cde4f7`	`#2e475d`
`--code-background`	`#0c1a24`	`#1f303f`
`--code-color`	`#dae2e9`	`#f4f6f8`
`--color-base-primary`	`#10202e`	`#111a23`
`--color-heading`	`#ffffff`	`#f4f6f8`
`--color-hint`	`#dae2e9`	`#f4f6f8`
`--color-info`	`#dae2e9`	`#f4f6f8`
`--color-menu-link-alt`	`#1fc0ff`	`#87bfec`
`--color-problem`	`#931919`	`#f4f6f8`
`--color-subtitle`	`#f5f6f8`	`#a9bbcb`
`--color-success`	`#04502f`	`#f4f6f8`
`--color-text`	`#dae2e9`	`#f4f6f8`
`--color-text-secondary`	`#dae2e9`	`#a9bbcb`
`--color-warning`	`#a23623`	`#f4f6f8`
`--hamburger-lines-color`	`#ffffff`	`#f4f6f8`
`--header-bg`	`#152b3d`	`#111a23`
`--header-link-alt`	`#dae2e9`	`#f4f6f8`
`--header-link-color`	`#1fc0ff`	`#87bfec`
`--icon-fill`	`#274b66`	`#a9bbcb`
`--icon-tile-background`	`#132838`	`#1f303f`
`--icon-tile-shadow`	`0px 6px 20px 0px #0c1a24`	`0px 6px 20px 0px #1f303f`
`--octo-blue`	`#1fc0ff`	`#87bfec`

Captured by snapshotting all computed custom properties plus the rendered color, background, border and font of seven elements, in both themes, before and after. Production build clean: 2,697 pages.

🤖 Generated with Claude Code

22 declarations in vars.css now reference generic tokens from @octopusdeploy/design-system-tokens - --colorTextPrimary/Secondary, --colorBorderPrimary/Tertiary, --colorBackgroundPrimaryDefault and SecondaryDefault, and --colorTextLinkDefault. Because those tokens theme themselves, 19 html[data-theme='dark'] overrides become redundant and are deleted, taking the block from 44 entries to 25. This is a visual change. The site's light theme was already close to the design system, so most of the shift is in dark mode: body text #dae2e9 -> #f4f6f8, links #1fc0ff -> #87bfec, header #152b3d -> #111a23, code background #0c1a24 -> #1f303f. Light shifts are small - borders #dae2e9 -> #dee1e6, tinted surfaces going neutral, body text #10212f -> #282f38 - and link colour in light does not change at all. Fixes two latent bugs: --background-default and --background-light had no dark override, so they resolved to white and pale blue in dark mode. Verified by snapshotting all 886 computed custom properties plus the rendered colour, background, border and font of seven elements, in both themes, before and after. 23 values change per theme and every one is accounted for; nothing shifted that wasn't intended or a documented knock-on through an existing alias. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Once the site's color variables point at generic tokens, five palette entries have no remaining references: --navy-600, --blue-100, --blue-200, --blue-qqq and --blue-midnight. Each was declared once and referenced nowhere, so they are deleted. Verified with the snapshot harness: the five properties disappear from the computed set (886 -> 881) and nothing else changes - zero differences on the seven rendered elements in either theme. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

team-marketing-branch-protections · 2026-07-28T21:57:45Z

Pull request environment is available at https://stoctodocspr3264.z22.web.core.windows.net.

You can view the ephemeral environment status in Octopus Deploy.

This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity.

An audit of every color in vars.css against the installed token stylesheets found three hardcoded values with an exact equivalent: --blue-grey-medium #113049 -> var(--brandGrey) --border-color-success #00b065 -> var(--brandGreen) --scrollbar-color #a9bbcb -> var(--navy-300) The first two are the only brand tokens the package defines that the site already used as literals; the third duplicated a palette entry. Verified with the snapshot harness: 881 computed properties and seven rendered elements identical in both themes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Callouts had no dark theming at all: --color-success, --color-warning, --color-problem and their backgrounds and borders carried no dark override, so a success callout rendered as #e8ffeb pale green with #04502f text on a dark page. Backgrounds and borders now use the status tokens, which theme themselves, and the four redundant dark overrides are gone. Callout text maps to --colorTextPrimary rather than the matching --colorText{Info,Success,Warning,Danger}. main.css sets `color` on the whole callout block (.hint, .success and friends), so that is body copy, and the status text tokens are not built for it - #b98f02 on #fff7d9 is 2.8:1, which fails WCAG AA. With --colorTextPrimary every callout lands at 12.5:1 or better in light, up from 6.5-9.5:1, and AA or better in dark. Also maps --bg-color-tab to --colorBackgroundTertiary, --icon-fill to --colorIconSecondary and --hamburger-lines-color to --colorIconPrimary, retiring one more dark override. --border-color-success moves from var(--brandGreen) to var(--colorBorderSuccess), superseding the earlier commit in this branch: the brand token does not theme, the border token does. Removes five variables with no remaining references: --header-icon-stroke, --header-link-alt-bg and --image-bg were already dead, and --lightest-blue became dead when the callout backgrounds stopped using it. Resolves the two "update with design system" TODOs, which are now done, and rewrites the three that remain to say what actually blocks them. The green-400 note claimed one usage where there are two, both icon colors that --colorIconSuccess could take. --navy-200 and --blue-grey are still hand-themed only because main.css consumes those palette entries directly, so both notes now point at the specific rules that need moving. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Keeps the comment as it was on main. The CTA greens keep their original "Brand greens, no scale equivalent" note too - neither value has a token equivalent, and choosing a replacement is a design decision about the button rather than something to resolve here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

enf0rc3 · 2026-07-28T22:47:25Z

  --white: var(--colorScalesWhite);

  --navy-700: var(--colorScalesNavy700);
-  --navy-600: var(--colorScalesNavy600);


was only used below for --colorTextSecondary

--color-subtitle: var(--navy-600); // Is now: --color-subtitle: var(--colorTextSecondary);

See color.text.secondary https://www.octopus.design/latest/foundations/color/overview-g9Vo6fLw#section-text-f6

It has slate being "light mode" as 600 so colorTextSecondary is correct here, it will also mean the dark mode will be navy.300

enf0rc3 · 2026-07-28T22:48:52Z

  --navy-100: var(--colorScalesNavy100);

  --blue-500: var(--colorScalesBlue500);
-  --blue-200: var(--colorScalesBlue200);


It was used for borders, so can be removed:

https://www.octopus.design/latest/foundations/color/overview-g9Vo6fLw#section-border-5b

enf0rc3 · 2026-07-28T22:49:46Z


  --blue-500: var(--colorScalesBlue500);
-  --blue-200: var(--colorScalesBlue200);
-  --blue-100: var(--colorScalesBlue100);


It was used for background below, so can be removed, we use the theme color now

https://www.octopus.design/latest/foundations/color/overview-g9Vo6fLw#section-background-04

color.background.secondary

Mapping --bg-color-menu to --colorBackgroundSecondaryDefault turned the side navigation from a recessed panel into a raised one: it went from #0c1a24, darker than the page, to #1f303f, well above it. The design system's dark backgrounds only step lighter from --colorBackgroundPrimaryDefault (#111A23 -> #1F303F -> #2E475D), so no token describes a surface below the page. The dark override is restored with a comment explaining why. Light mode keeps the token. Measured against production: the nav is #0c1a24 in both, and recessed relative to the page again (#111a23 here, #10202e on live). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

enf0rc3 · 2026-07-28T23:34:27Z

-  --blue-200: var(--colorScalesBlue200);
-  --blue-100: var(--colorScalesBlue100);
-  /* No scale equivalent */
-  --blue-qqq: #fafdff;


used for light mode --bg-color-menu This now uses color.background.secondary and has changed the color:

Mapping every background straight onto its token flattened dark mode: the page dropped to --colorBackgroundPrimaryDefault #111A23, which is close enough to the navigation and code wells that the whole page read as one colour, and the recessed surfaces ended up lighter than the page. The site uses three levels of depth in dark, so it now uses three tokens: --colorBackgroundPrimaryDefault #111A23 navigation, code blocks --colorBackgroundSecondaryDefault #1F303F page and header --colorBackgroundTertiary #2E475D icon tiles That means the page takes Secondary rather than Primary in dark, which diverges from the portal's use of Primary as the page, but it reproduces the relationships the docs site already had: nav and code recessed below the page, cards raised above it. Light mode is untouched and keeps Primary. Measured against production, ordered by lightness: sidebar/code #111a23 (was #0c1a24) page/header #1f303f (was #10202e) hint callout #1d384e (was #102a3f) The hint and info callout backgrounds are restored byte-for-byte to their original values - a 10% Octopus Cyan wash and var(--blue-grey-light). The design system has no translucent background token, and the wash is a deliberate effect that a solid #0F4778 fill replaced with a heavy block. Of the 44 overrides originally in this block, 23 resolve to values identical to their tokens, notably seven navy-700 borders collapsing onto --colorBorderPrimary. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Base automatically changed from wl/design-tokens-palette to main July 28, 2026 21:24

enf0rc3 and others added 2 commits July 29, 2026 09:31

enf0rc3 force-pushed the wl/design-tokens-semantic branch from 97b8fe7 to 43348ab Compare July 28, 2026 21:44

enf0rc3 changed the title ~~Point the semantic layer at the design system's tokens~~ Point the site color variables at the design system's generic tokens Jul 28, 2026

enf0rc3 and others added 3 commits July 29, 2026 10:16

enf0rc3 commented Jul 28, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Point the site color variables at the design system's generic tokens - #3264

Point the site color variables at the design system's generic tokens#3264
enf0rc3 wants to merge 7 commits into
mainfrom
wl/design-tokens-semantic

enf0rc3 commented Jul 28, 2026 •

edited

Loading

Uh oh!

team-marketing-branch-protections commented Jul 28, 2026

Uh oh!

enf0rc3 Jul 28, 2026

Uh oh!

enf0rc3 Jul 28, 2026

Uh oh!

enf0rc3 Jul 28, 2026

Uh oh!

enf0rc3 Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

enf0rc3 commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Results

What changed

Screenshots

Article body — light

Article body — dark

Callouts — light

Callouts — dark

Navigation and header — dark

Every changed value

Uh oh!

team-marketing-branch-protections commented Jul 28, 2026

Uh oh!

enf0rc3 Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

enf0rc3 Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

enf0rc3 Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

enf0rc3 Jul 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

enf0rc3 commented Jul 28, 2026 •

edited

Loading