Skip to content

Adopt the design system tokens in the docs theme - #3264

Open
enf0rc3 wants to merge 13 commits into
mainfrom
wl/design-tokens-semantic
Open

Adopt the design system tokens in the docs theme#3264
enf0rc3 wants to merge 13 commits into
mainfrom
wl/design-tokens-semantic

Conversation

@enf0rc3

@enf0rc3 enf0rc3 commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Background

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

vars.css still defined its own theme: site variables resolving to hand-picked hex values, plus a 44-entry html[data-theme='dark'] block maintaining a second set for dark mode. Several variables had no dark value at all.

This is the first adoption — pointing the theme at the design system. It is deliberately a broad, shallow pass over vars.css only. Component-by-component tuning against the new design comes later.

Results

One file. 40 values change in light and 43 in dark, html[data-theme='dark'] goes from 44 overrides to 17, and 10 unused variables are removed.

What now comes from tokens

group site variables token
Text --color-text, --color-heading, --color-menu-link-active --colorTextPrimary
--color-text-secondary, --color-subtitle, --color-menu-link --colorTextSecondary
Links --octo-blue, --color-menu-link-alt --colorTextLinkDefault
Borders --border-color-header, --border-color-menu-open, --border-color-tab, --border-default-color, --separator-color, --header-separator-color, --theme-switcher-border --colorBorderPrimary
--border-color-tab-active --colorBorderSelected
Backgrounds --color-base-primary, --background-default, --header-bg --colorBackgroundPrimaryDefault
--bg-color-menu, --code-background, --background-light --colorBackgroundSecondaryDefault
--bg-color-tab --colorBackgroundTertiary
Callouts 15 variables across hint, info, success, warning, problem --colorCalloutText/Background/Border*
Icons --icon-fill --colorIconSecondary
--hamburger-lines-color --colorIconPrimary
Brand --blue-grey-medium --brandGrey
Scrollbar --scrollbar-color --colorScrollbarHandle
Tiles --icon-tile-border-hover --colorBorderSelected

Seven of those border variables previously carried their own dark override. Because tokens theme themselves, all seven collapse to one declaration.

Light mode: close to unchanged

23 of the 39 light changes are within a delta of 30 — border greys shifting #dae2e9#dee1e6, tinted surfaces going neutral #f2f8fd#f5f6f8, body text #10212f#282f38. Link color does not change at all (#1a77ca either way).

Two exceptions worth looking at:

  • The warning callout shifts hue — text #a23623#3b2c00, border #fc8431#b98f02. Rust and orange become olive and mustard.
  • --border-color-tab-active, the selected-tab indicator, becomes blue: #7c98b4#1a77ca.

Dark mode: a substantial change, aligned to the new design

This is where the old theme diverged most from the design system, so it moves the most.

Surfaces use three levels of the token ramp, keeping the page darkest:

--colorBackgroundPrimaryDefault    #111A23   page, header, side navigation
--colorBackgroundSecondaryDefault  #1F303F   code blocks, icon tiles
--colorBackgroundTertiary          #2E475D   icon tile hover

Because those tokens theme themselves, the page, header and code background need no dark override at all. --bg-color-menu is the only surface that does, because the navigation is a distinct panel in light and matches the page in dark.

Text and links:

--color-text      #dae2e9 -> #f4f6f8
--color-heading   #ffffff -> #f4f6f8
--octo-blue       #1fc0ff -> #87bfec

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. All five callout types now use the --colorCallout* family, whose backgrounds are translucent and whose text colors are paired to them. Measured in a browser, every callout is AAA in both themes — worst case 9.59:1.

Two accessibility fixes came out of review. The selected-tab indicator had landed on --colorBorderTertiary, which is byte-identical to --colorBorderDisabled, dropping it to 1.97:1 in light and 2.65:1 in dark against a 3:1 requirement; it now uses --colorBorderSelected at 4.63:1 and 5.87:1. The scrollbar thumb was 1.97:1 on white and now uses --colorScrollbarHandle at 3.00:1.

One main.css fix. [role='tabpanel'] set background: var(--aft), a variable defined nowhere, so every tab panel was transparent. It now uses --color-base-primary, matching the selected tab's own fill so the two read as one surface. The tabs are built at runtime by public/docs/js/modules/detail-tabs.js, which is why none of this markup appears in the static HTML. Fixed here because moving the indicator to --colorBorderSelected draws a 2px blue border around every panel, which made the missing background obvious.

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.

Still hand-themed, and why

17 dark overrides remain. Most have no token equivalent: --search-*, --badge-*, --octopus-logo-text-color, and the --blue-midnight / --blue-grey families.

Two carry a note explaining what blocks them — --navy-200 and --blue-grey are only hand-themed because main.css consumes those palette entries directly, so unpicking them means editing rules rather than variables.

Removed

Ten variables, each referenced nowhere: --navy-600, --blue-100, --blue-200, --blue-qqq, --blue-midnight, --lightest-blue were orphaned once the theme stopped pointing at them; --header-icon-stroke, --header-link-alt-bg, --image-bg were already dead; and --icon-tile-shadow was declared in both blocks but read nowhere in main.css.

Compatibility note

The callout background tokens use CSS Color 4 relative color syntax, rgb(from #CDE4F7 r g b / 0.5), which needs Chrome 119, Safari 16.4 or Firefox 128. Older browsers treat the declaration as invalid and drop the fill; callout text and the left border still render and both stay legible.

Screenshots

Every image is a side-by-side pair: octopus.com as it is now on the left, this PR on the right.

Surfaces — dark

Page, header, navigation and code block

/docs/getting-started/first-deployment

03-article-surfaces-dark

Code block

The page is the darkest surface, so code blocks move from a recessed well to a raised panel.

04-code-block-dark

Navigation, header and page surfaces

/docs/getting-started

01-getting-started-dark

Surfaces — light

Navigation, header and page surfaces

/docs/getting-started — for comparison, light is close to unchanged.

02-getting-started-light

Tab group

/docs/deployments/custom-scripts — "Scripts that block deployments". The selected-tab indicator and panel outline move from #7c98b4 to --colorBorderSelected, and the panel gains the background it was missing.

Light:
13-tabs-light

Dark:
13-tabs-dark

Callouts

Hint

/docs/administration/data/data-migration/ — 408 pages use .hint

Light:

05-hint-light

Dark:

06-hint-dark

Success

/docs/administration/data/changing-octopus-database-collation/ — 279 pages

Light:

07-success-light

Dark — previously a pale green box on a dark page, because the success callout had no dark override:

08-success-dark

Warning

Same page — 227 pages. This is the one callout whose light colors shift noticeably: text #a23623 to #3b2c00, border #fc8431 to #b98f02.

Light:

09-warning-light

Dark:

10-warning-dark

Problem

/docs/administration/data/backup-and-restore/ — 39 pages

Light:

11-problem-light

Dark:

12-problem-dark

Next steps

This is the first step, not the finished job. The intent is to go component by component and tune each against the new design. Known follow-ups:

  • main.css reaches past the theme into raw palette entries, which is what keeps --navy-200 and --blue-grey hand-themed.
  • .hint and .info now resolve identically. The design system has no separate hint concept, so they either become synonyms or .info moves to another callout family.
  • --content-bg is white in both themes and paints the mobile navigation and search overlay, so that overlay is white in dark mode. Pre-existing.
  • --bg-color-tab and --border-color-tab resolve to the same colour in both themes, so the tab border is invisible. Unchanged from main, but it now expresses one colour through two token families.
  • .icon-tile renders only on /components/, so the tile changes in this PR affect that page alone.
  • The CTA button greens have no token. #00ffa3 is the brand's Neon Green and #00e693 is not in the brand palette, but neither value appears anywhere in the token package. The nearest bright green is --brandGreen #00B065, which is far enough away to matter: against the current #113049 label it scores 4.80:1 where #00e693 scores 8.26:1, so adopting it means changing the label colour too.

Every changed value

Light — 40 values changed
variable before after
--bg-color-hint #e5f4ff rgb(from #cde4f7 r g b / 0.5)
--bg-color-info #e5f4ff rgb(from #cde4f7 r g b / 0.5)
--bg-color-problem #fff2ee rgb(from #ffd8d8 r g b / 0.5)
--bg-color-success #e8ffeb rgb(from #b8e7d3 r g b / 0.45)
--bg-color-warning #fefae9 rgb(from #ffdf62 r g b / 0.32)
--icon-tile-border-hover #cde4f7 #1a77ca
--color-warning #a23623 #3b2c00
--border-color-tab-active #7c98b4 #1a77ca
--border-color-warning #fc8431 #b98f02
--scrollbar-color #a9bbcb #959595
--color-problem #931919 #571818
--hamburger-lines-color #274b66 #282f38
--border-color-success #00b065 #00874d
--icon-fill #274b66 #515d70
--color-menu-link-active #2e475d #282f38
--color-text-secondary #2e475d #515d70
--border-color-problem #ff4848 #d63d3d
--color-success #04502f #00361f
--code-color #10212f #282f38
--color-text #10212f #282f38
--color-hint #124164 #093051
--color-info #124164 #093051
--border-default-color #cde4f7 #dee1e6
--header-icon-border #cde4f7 #dee1e6
--icon-tile-border #cde4f7 #dee1e6
--color-menu-link #3e607d #515d70
--color-subtitle #3e607d #515d70
--color-heading #152b3d #282f38
--bg-color-menu #fafdff #f5f6f8
--background-light #f2f8fd #f5f6f8
--code-background #f2f8fd #f5f6f8
--header-icon-background #f2f8fd #f5f6f8
--icon-tile-background #f2f8fd #f5f6f8
--bg-color-tab #dae2e9 #dee1e6
--border-color-header #dae2e9 #dee1e6
--border-color-menu-open #dae2e9 #dee1e6
--border-color-tab #dae2e9 #dee1e6
--header-separator-color #dae2e9 #dee1e6
--separator-color #dae2e9 #dee1e6
--theme-switcher-border #dae2e9 #dee1e6
Dark — 43 values changed
variable before after
--bg-color-hint rgba(13, 128, 216, 0.1) rgb(from #093051 r g b / 0.8)
--bg-color-info #274b66 rgb(from #093051 r g b / 0.8)
--bg-color-problem #fff2ee rgb(from #571818 r g b / 0.8)
--bg-color-success #e8ffeb rgb(from #00361f r g b / 0.75)
--bg-color-warning #fefae9 rgb(from #584201 r g b / 0.90)
--background-default #ffffff #111a23
--background-light #f2f8fd #1f303f
--color-problem #931919 #ffd8d8
--color-success #04502f #b8e7d3
--color-warning #a23623 #fff7d9
--border-default-color #cde4f7 #2e475d
--icon-fill #274b66 #a9bbcb
--scrollbar-color #a9bbcb #557999
--body-link-color #1fc0ff #87bfec
--color-menu-link-alt #1fc0ff #87bfec
--color-subtitle #f5f6f8 #a9bbcb
--header-link-color #1fc0ff #87bfec
--octo-blue #1fc0ff #87bfec
--border-color-warning #fc8431 #b98f02
--border-color-tab-active #7c98b4 #449be1
--color-text-secondary #dae2e9 #a9bbcb
--border-color-hint #1a77ca #449be1
--border-color-info #1a77ca #449be1
--icon-tile-border-hover #1fc0ff #449be1
--code-background #0c1a24 #1f303f
--code-color #dae2e9 #f4f6f8
--color-text #dae2e9 #f4f6f8
--header-link-alt #dae2e9 #f4f6f8
--header-bg #152b3d #111a23
--border-color-problem #ff4848 #ff5d5d
--icon-tile-background-hover #223950 #2e475d
--icon-tile-border #1c3f59 #2e475d
--color-hint #dae2e9 #cde4f7
--color-info #dae2e9 #cde4f7
--color-heading #ffffff #f4f6f8
--hamburger-lines-color #ffffff #f4f6f8
--icon-tile-background #132838 #1f303f
--color-base-primary #10202e #111a23
--header-icon-background #152b3d #1f303f
--bg-color-tab #314c62 #2e475d
--border-color-tab #314c62 #2e475d
--border-color-success #00b065 #00ab62
--bg-color-menu #0c1a24 #111a23

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. pnpm spellcheck passes.

🤖 Generated with Claude Code

Base automatically changed from wl/design-tokens-palette to main July 28, 2026 21:24
@enf0rc3
enf0rc3 force-pushed the wl/design-tokens-semantic branch from 97b8fe7 to 43348ab Compare July 28, 2026 21:44
@enf0rc3 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
@team-marketing-branch-protections

Copy link
Copy Markdown

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.

Comment thread public/docs/css/vars.css
--white: var(--colorScalesWhite);

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread public/docs/css/vars.css
--navy-100: var(--colorScalesNavy100);

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment thread public/docs/css/vars.css

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread public/docs/css/vars.css
--blue-200: var(--colorScalesBlue200);
--blue-100: var(--colorScalesBlue100);
/* No scale equivalent */
--blue-qqq: #fafdff;

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Image

@enf0rc3
enf0rc3 force-pushed the wl/design-tokens-semantic branch from c737e6e to 671364d Compare July 29, 2026 02:34
@enf0rc3 enf0rc3 changed the title Point the site color variables at the design system's generic tokens Adopt the design system tokens in the docs theme Jul 29, 2026
enf0rc3 and others added 13 commits July 30, 2026 14:02
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>
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>
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>
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>
The design system has a dedicated --colorCallout* family, which is a better
fit than the generic background and text tokens these were using:

  --colorCalloutText{Info,Success,Warning,Danger}
  --colorCalloutBackground{...}Default
  --colorCalloutBorder{...}

Two reasons it matters. The backgrounds are translucent by design - light is
rgb(from #CDE4F7 r g b / 0.5), dark is rgb(from #093051 r g b / 0.8) - which
is the same washed effect the site was hand-rolling, so both dark overrides
for hint and info are no longer needed and are removed.

And the family pairs its text colors with its backgrounds, unlike the generic
ones. --colorTextWarning on --colorBackgroundWarning was 2.8:1, failing WCAG
AA, which is why callout text was previously mapped to --colorTextPrimary.
Measured in a browser, every callout is now AAA in both themes, worst case
9.59:1: light #093051 on #e6f2fb is 11.85:1, dark #cde4f7 on #0b2c48 is
10.98:1.

The tokens use CSS Color 4 relative color syntax, which needs Chrome 119,
Safari 16.4 or Firefox 128. Chromium resolves it to color(srgb ...) as
expected. Older browsers treat the declaration as invalid and drop the fill;
the text and left border still render and both stay legible.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
--color-base-primary, --header-bg and --code-background declared the same
token in the dark block as in :root, so the override did nothing - the token
already themes itself.

Verified with the snapshot harness: 877 computed properties and seven
rendered elements identical in both themes.

That leaves --bg-color-menu as the only surface override, because the
navigation is a distinct panel in light and matches the page in dark.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
--border-color-tab-active used --colorBorderTertiary, which is byte-identical
to --colorBorderDisabled in both themes and so the wrong token for a selected
state. It is the only marker on the selected tab and the tabpanel outline, and
it had dropped to 1.97:1 in light and 2.65:1 in dark, failing WCAG 1.4.11.
--colorBorderSelected gives 4.63:1 and 5.87:1.

The dark icon tile had three problems, all caused by putting the fill on
--colorBackgroundTertiary, the top of the dark ramp, which left nothing lighter
for hover or the border. Dropping the fill a step lets the rest inherit:

  fill    #1f303f  inherits --background-light, dark override removed
  hover   #2e475d  --colorBackgroundTertiary, so hover lightens again
  border  #2e475d  inherits --border-default-color, dark override removed
  hover   #449be1  --colorBorderSelected, replacing off-brand #1fc0ff
  shadow  rgba(0, 0, 0, 0.4), replacing var(--bg-color-menu), which had come
          to resolve to the page color and so painted nothing

Border contrast on the fill is 1.40:1, in line with the original dark tile at
1.37:1 and light at 1.21:1. The blue hover border matches what main already
did with --octo-blue-lightest. Verified in a browser: both themes lighten on
hover.

--header-icon-background pointed at var(--blue-grey-dark) #152b3d, which sits
between two ramp steps and belongs to neither. :root already resolves it
through --background-light, so the override is removed.

Both TODO comments cited line numbers that were already stale. They now name
the selectors: code, .image, figure:has(p > img) p, .card and
.site-search-results__item for --navy-200, and .card__description for
--blue-grey.

Takes the dark block from 22 declarations to 18.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
--scrollbar-color pointed at --navy-300, a palette entry, so it carried one
value for both themes. It feeds ::-webkit-scrollbar-thumb, and the package
has --colorScrollbarHandle for exactly that.

This also fixes a contrast problem: at #a9bbcb on white the thumb was 1.97:1,
below the 3:1 that WCAG 1.4.11 asks of a non-text UI component. #959595 gives
3.00:1. Dark moves from 8.91:1 to 3.83:1, which still clears.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…border

--icon-tile-shadow was declared in both blocks and read nowhere - main.css
never references it. The rgba(0, 0, 0, 0.4) in the previous commit therefore
changed a variable nothing renders, and pointing it at --shadowMedium would
have adopted a token for dead code. Both declarations are removed.

--icon-tile-border-hover was equal to --icon-tile-border in light, so the
light tile border did not change on hover, while dark had its own override.
:root now uses --colorBorderSelected for both themes and the dark override
goes. Verified in a browser: light #dee1e6 -> #1a77ca, dark #2e475d ->
#449be1, and both themes still lighten the fill.

Takes the dark block to 17 declarations. The earlier claim of 18 was wrong -
the grep behind it excluded --navy-200 because of the digits in the name.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
[role='tabpanel'] set background: var(--aft), and --aft is defined nowhere in
the repo, so the panel had no background at all. The selected tab already uses
--color-base-primary for both its fill and its bottom border, so the panel now
uses the same variable and the two read as one surface: #ffffff in light,
#111a23 in dark.

The tabs are built at runtime by public/docs/js/modules/detail-tabs.js, which
converts <details data-group> into a tablist, so none of this markup appears in
the static HTML. Verified in a browser on /docs/deployments/custom-scripts.

Worth fixing here because moving --border-color-tab-active to
--colorBorderSelected draws a 2px blue border around every panel, which made
the missing background obvious.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@enf0rc3
enf0rc3 force-pushed the wl/design-tokens-semantic branch from e6ccb41 to 1555e40 Compare July 30, 2026 02:03
Comment thread public/docs/css/main.css
padding: 1rem;
border: 2px solid var(--border-color-tab-active);
border-radius: var(--standard-radius);
background: var(--aft);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

--aft was never defined, so this fell back to transparent and only looked
right by accident. --color-base-primary is what the selected tab already uses.

This change snuck in thanks to "claude" good fix though.

Image

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants