Adopt the design system tokens in the docs theme - #3264
Conversation
97b8fe7 to
43348ab
Compare
|
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. |
| --white: var(--colorScalesWhite); | ||
|
|
||
| --navy-700: var(--colorScalesNavy700); | ||
| --navy-600: var(--colorScalesNavy600); |
There was a problem hiding this comment.
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
| --navy-100: var(--colorScalesNavy100); | ||
|
|
||
| --blue-500: var(--colorScalesBlue500); | ||
| --blue-200: var(--colorScalesBlue200); |
There was a problem hiding this comment.
It was used for borders, so can be removed:
https://www.octopus.design/latest/foundations/color/overview-g9Vo6fLw#section-border-5b
|
|
||
| --blue-500: var(--colorScalesBlue500); | ||
| --blue-200: var(--colorScalesBlue200); | ||
| --blue-100: var(--colorScalesBlue100); |
There was a problem hiding this comment.
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
| --blue-200: var(--colorScalesBlue200); | ||
| --blue-100: var(--colorScalesBlue100); | ||
| /* No scale equivalent */ | ||
| --blue-qqq: #fafdff; |
c737e6e to
671364d
Compare
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>
e6ccb41 to
1555e40
Compare
| padding: 1rem; | ||
| border: 2px solid var(--border-color-tab-active); | ||
| border-radius: var(--standard-radius); | ||
| background: var(--aft); |


Background
The docs site loads
@octopusdeploy/design-system-tokensas CSS custom properties (#3261), and its raw palette maps onto the token color scales (#3262). Nothing was consuming the tokens yet.vars.cssstill defined its own theme: site variables resolving to hand-picked hex values, plus a 44-entryhtml[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.cssonly. 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
--color-text,--color-heading,--color-menu-link-active--colorTextPrimary--color-text-secondary,--color-subtitle,--color-menu-link--colorTextSecondary--octo-blue,--color-menu-link-alt--colorTextLinkDefault--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--color-base-primary,--background-default,--header-bg--colorBackgroundPrimaryDefault--bg-color-menu,--code-background,--background-light--colorBackgroundSecondaryDefault--bg-color-tab--colorBackgroundTertiary--colorCalloutText/Background/Border*--icon-fill--colorIconSecondary--hamburger-lines-color--colorIconPrimary--blue-grey-medium--brandGrey--scrollbar-color--colorScrollbarHandle--icon-tile-border-hover--colorBorderSelectedSeven 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 (#1a77caeither way).Two exceptions worth looking at:
#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:
Because those tokens theme themselves, the page, header and code background need no dark override at all.
--bg-color-menuis the only surface that does, because the navigation is a distinct panel in light and matches the page in dark.Text and links:
Callouts had no dark theming at all.
--color-success,--color-warning,--color-problemand their backgrounds and borders carried no dark override, so a success callout rendered as#e8ffebpale green with#04502ftext 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--colorBorderSelectedat 4.63:1 and 5.87:1. The scrollbar thumb was 1.97:1 on white and now uses--colorScrollbarHandleat 3.00:1.One
main.cssfix.[role='tabpanel']setbackground: 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 bypublic/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--colorBorderSelecteddraws a 2px blue border around every panel, which made the missing background obvious.Two latent bugs fixed.
--background-defaultand--background-lighthad no dark override, so they resolved to#ffffffand#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-greyfamilies.Two carry a note explaining what blocks them —
--navy-200and--blue-greyare only hand-themed becausemain.cssconsumes 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-bluewere orphaned once the theme stopped pointing at them;--header-icon-stroke,--header-link-alt-bg,--image-bgwere already dead; and--icon-tile-shadowwas declared in both blocks but read nowhere inmain.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-deploymentCode block
The page is the darkest surface, so code blocks move from a recessed well to a raised panel.
Navigation, header and page surfaces
/docs/getting-startedSurfaces — light
Navigation, header and page surfaces
/docs/getting-started— for comparison, light is close to unchanged.Tab group
/docs/deployments/custom-scripts— "Scripts that block deployments". The selected-tab indicator and panel outline move from#7c98b4to--colorBorderSelected, and the panel gains the background it was missing.Light:

Dark:

Callouts
Hint
/docs/administration/data/data-migration/— 408 pages use.hintLight:
Dark:
Success
/docs/administration/data/changing-octopus-database-collation/— 279 pagesLight:
Dark — previously a pale green box on a dark page, because the success callout had no dark override:
Warning
Same page — 227 pages. This is the one callout whose light colors shift noticeably: text
#a23623to#3b2c00, border#fc8431to#b98f02.Light:
Dark:
Problem
/docs/administration/data/backup-and-restore/— 39 pagesLight:
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.cssreaches past the theme into raw palette entries, which is what keeps--navy-200and--blue-greyhand-themed..hintand.infonow resolve identically. The design system has no separate hint concept, so they either become synonyms or.infomoves to another callout family.--content-bgis white in both themes and paints the mobile navigation and search overlay, so that overlay is white in dark mode. Pre-existing.--bg-color-taband--border-color-tabresolve to the same colour in both themes, so the tab border is invisible. Unchanged frommain, but it now expresses one colour through two token families..icon-tilerenders only on/components/, so the tile changes in this PR affect that page alone.#00ffa3is the brand's Neon Green and#00e693is 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#113049label it scores 4.80:1 where#00e693scores 8.26:1, so adopting it means changing the label colour too.Every changed value
Light — 40 values changed
--bg-color-hint#e5f4ffrgb(from #cde4f7 r g b / 0.5)--bg-color-info#e5f4ffrgb(from #cde4f7 r g b / 0.5)--bg-color-problem#fff2eergb(from #ffd8d8 r g b / 0.5)--bg-color-success#e8ffebrgb(from #b8e7d3 r g b / 0.45)--bg-color-warning#fefae9rgb(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#dee1e6Dark — 43 values changed
--bg-color-hintrgba(13, 128, 216, 0.1)rgb(from #093051 r g b / 0.8)--bg-color-info#274b66rgb(from #093051 r g b / 0.8)--bg-color-problem#fff2eergb(from #571818 r g b / 0.8)--bg-color-success#e8ffebrgb(from #00361f r g b / 0.75)--bg-color-warning#fefae9rgb(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#111a23Captured 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 spellcheckpasses.🤖 Generated with Claude Code