Refresh docs site theme toward neutral GitHub-style surfaces#40422
Conversation
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR retunes the docs site styling toward more neutral GitHub-like surfaces by introducing shared --aw-* theme tokens, shifting most docs chrome away from all-over purple treatments, and keeping the homepage intentionally more branded/purple (including the slide hero framing).
Changes:
- Added shared
--aw-*theme tokens for backgrounds, borders, muted text, shadows, and accent tinting (light + dark). - Updated global chrome styling (header/sidebar/buttons/cards/blockquotes) to use more neutral surfaces with purple reserved for emphasis/interaction.
- Refined landing-page-only glow behavior by keying it to the homepage slide hero (
[data-slide-hero]) and strengthenedWorkflowHeroframing.
Show a summary per file
| File | Description |
|---|---|
| docs/src/styles/custom.css | Introduces --aw-* tokens and rebalances light/dark theme surfaces; updates glow gating and various UI surfaces. |
| docs/src/components/WorkflowHero.astro | Adjusts hero feature/frame styling to keep homepage visually distinct after theme neutralization. |
| docs/src/components/CustomHeader.astro | Updates hover/accent and dropdown surface styling to use the new shared theme tokens. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 3/3 changed files
- Comments generated: 3
|
@copilot run to their side and take screenshots. |
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR #40422 does not have the 'implementation' label (has_implementation_label=false) and has 0 new lines of code in business logic directories (default_business_additions=0, below the 100-line threshold). requires_adr_by_default_volume=false. |
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
✅ Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. The PR only changes docs/src/components/CustomHeader.astro, docs/src/components/WorkflowHero.astro, and docs/src/styles/custom.css (styling/UI changes). Test Quality Sentinel skipped. |
|
✅ PR Code Quality Reviewer completed the code quality review. |
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Done in |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /zoom-out and /improve-codebase-architecture — requesting changes on three real issues (animation perf, browser compat, body text contrast), with four lower-priority token consistency notes.
📋 Key Themes & Highlights
Issues to address
- Animation still runs on all pages —
opacity: 0does not stop the 24 s CSS animation loop onbody::before; usedisplay: noneinstead (or document why animation-in-background is intentional). - Missing
-webkit-backdrop-filteron dropdown — the header correctly uses both prefixed and unprefixed variants, but the new dropdown blur only has the unprefixed version and will silently break on Safari. - Body paragraph text demoted to muted colour —
--aw-text-mutedis reserved for secondary/hint text, but is now applied to.sl-markdown-content pandli, reducing the contrast of primary reading content in light mode.
Token consistency (lower priority)
- Light card/panel shadow hardcoded instead of using
var(--aw-shadow) WorkflowHero.astrohero card uses hardcodedrgbavalues outside the token system (no comment explaining this is intentional)- Light blockquote background hardcoded instead of using an
--aw-*surface token [data-slide-hero]couples global body glow logic to a component-internal attribute — a comment documenting this as a stable contract would help future contributors
Positive Highlights
- ✅ Clean
--aw-*token system is a solid foundation — replacing hundreds of scatteredrgbaliterals with a small set of named variables is the right direction - ✅ Scoping the animated glow to the landing page is a clear improvement in both UX and architecture intent
- ✅ Light theme buttons and card/panel light shadows were genuinely missing before; good catch
- ✅ Consistent
rgba(var(--aw-accent-rgb), ...)pattern for accent tints is elegant
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 87.5 AIC · ⌖ 10.2 AIC · ⊞ 6.9K
| :root[data-theme='light'] .card, | ||
| :root[data-theme='light'] .panel { | ||
| background-color: rgba(255, 255, 255, 0.88); | ||
| box-shadow: 0 10px 28px rgba(31, 35, 40, 0.06); |
There was a problem hiding this comment.
[/improve-codebase-architecture] The dark theme card/panel uses box-shadow: var(--aw-shadow) (line 1071), but the light theme override hardcodes a separate value instead of referencing the same token. This breaks the abstraction: if you later want to tune card shadows, you need to change two places rather than one.
💡 Fix
:root[data-theme='light'] .card,
:root[data-theme='light'] .panel {
background-color: rgba(255, 255, 255, 0.88);
box-shadow: var(--aw-shadow); /* already defined as the lighter value in light :root */
}--aw-shadow is already set to 0 18px 42px rgba(31, 35, 40, 0.08) in the light theme :root, so this gives the same visual result while keeping the token as the single source of truth.
There was a problem hiding this comment.
Addressed in ff00ee8: light .card/.panel now use shared tokens (var(--aw-bg-elevated) and var(--aw-shadow)).
| :root[data-theme='light'] .sl-markdown-content p, | ||
| :root[data-theme='light'] .sl-markdown-content li { | ||
| color: #424a53; | ||
| color: var(--aw-text-muted); |
There was a problem hiding this comment.
[/zoom-out] --aw-text-muted (#57606a in light mode) is defined as the muted/secondary text token — the PR description itself calls it out as for muted text. Applying it to .sl-markdown-content p and li demotes the primary body text of every docs page to secondary contrast. This is the text users come to read; it should use the primary text colour, not the muted one.
💡 Suggestion
Leave body paragraph text at its default (the Starlight --sl-color-text it already inherits), or explicitly set color: var(--sl-color-text). Reserve var(--aw-text-muted) for captions, helper text, and sidebars where reduced contrast is intentional.
There was a problem hiding this comment.
Fixed in 6a14821: light-theme .sl-markdown-content p and li now use var(--sl-color-text) instead of the muted token.
| background: rgba(208, 215, 222, 0.15); | ||
| border-left-color: rgba(var(--aw-accent-rgb), 0.34); | ||
| color: var(--aw-text-muted); | ||
| background: rgba(208, 215, 222, 0.22); |
There was a problem hiding this comment.
[/improve-codebase-architecture] The dark blockquote background uses the tokenised rgba(110, 118, 129, 0.1) (line 940), but the light override hardcodes rgba(208, 215, 222, 0.22) instead of deriving from an --aw-* token. Minor inconsistency, but it's the kind of stray hardcoded value the token system was introduced to eliminate.
💡 Suggestion
Either define --aw-bg-blockquote in both theme roots, or use the already-defined --aw-bg-subtle as the background base:
background: var(--aw-bg-subtle); /* = #f6f8fa in light, #161b22 in dark */This keeps blockquote surfaces in sync with the broader neutral surface palette.
There was a problem hiding this comment.
Updated in 6a14821: light-theme blockquote now uses var(--aw-bg-subtle) background and var(--sl-color-text) for primary readability.
|
@copilot run pr finisher skill |
There was a problem hiding this comment.
REQUEST_CHANGES — 2 new issues + 3 pre-existing issues need fixing before merge
🔍 Summary of all blocking issues
New findings (this review)
-
Medium —
--aw-text-mutedon primary body text (light theme) (custom.css:734)
--aw-text-muted: #57606ais GitHubfg.muted— meant for metadata and secondary annotations. Applying it to.sl-markdown-content pandlidrops body text contrast from ~7.9:1 to ~5.8:1 on white. Documentation body copy should use the primary text color or a dedicated body token. The same issue applies to light-theme blockquotecolorat line 948. -
Low — Missing
-webkit-backdrop-filteron dropdown (CustomHeader.astro:125)
The rest of the codebase pairsbackdrop-filterwith-webkit-backdrop-filter(e.g. the header). The new dropdown only has the unprefixed form.
Pre-existing open comments (require resolution)
-
Medium — Animation runs at
opacity: 0on all non-home dark-theme pages (custom.css:433): switching fromdisplay: nonetoopacity: 0means the compositor still ticksglow-moveon every non-homepage, wasting GPU work. -
Medium — Same animation waste on light-theme non-home pages (
custom.css:131):light-glow-moveruns continuously even where the element is invisible. -
Medium —
.card/.panellight theme reintroduces hardcoded surface values (custom.css:1078):rgba(255,255,255,0.88)and0 10px 28px ...bypass the--aw-bg-elevated/--aw-shadowtokens introduced by this same PR.
The structural approach (tokenizing via --aw-*, restricting the glow to [data-slide-hero] pages) is the right direction. The issues above are fixable without rearchitecting.
🔎 Code quality review by PR Code Quality Reviewer · 157.2 AIC · ⌖ 7.32 AIC · ⊞ 5.1K
| :root[data-theme='light'] .sl-markdown-content p, | ||
| :root[data-theme='light'] .sl-markdown-content li { | ||
| color: #424a53; | ||
| color: var(--aw-text-muted); |
There was a problem hiding this comment.
Readability regression: --aw-text-muted is applied to primary paragraph and list-item text in the light theme, reducing contrast from ~7.9:1 (#424a53) to ~5.8:1 (#57606a) against a white background.
💡 Details and suggested fix
--aw-text-muted (GitHub fg.muted) is semantically designed for secondary/helper content — timestamps, captions, metadata labels. Applying it to .sl-markdown-content p and li means every paragraph in every light-theme docs page renders at reduced contrast.
GitHub itself uses #1f2328 (fg.default) for body text and reserves #57606a (fg.muted) for secondary annotations. The old #424a53 was closer to the right level for body copy.
Suggested fix:
:root[data-theme='light'] .sl-markdown-content p,
:root[data-theme='light'] .sl-markdown-content li {
color: var(--sl-color-text); /* use the theme primary text color, not muted */
}Or introduce a dedicated --aw-text-body token that resolves to a darker value (e.g. #424a53) rather than reusing the muted token.
The same issue applies to blockquote { color: var(--aw-text-muted) } in light mode (line 948) — blockquote content is still primary text, not metadata.
There was a problem hiding this comment.
Fixed in 6a14821: reverted light-theme body/list text to var(--sl-color-text) and updated light blockquote text to primary text color.
| z-index: 1000; | ||
| box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4); | ||
| box-shadow: var(--aw-shadow, 0 8px 24px rgba(0, 0, 0, 0.4)); | ||
| backdrop-filter: blur(16px); |
There was a problem hiding this comment.
Missing -webkit-backdrop-filter: The new dropdown uses backdrop-filter: blur(16px) alone, but the header in custom.css still pairs it with -webkit-backdrop-filter: blur(12px) for consistency across older Safari/WebKit.
💡 Suggested fix
Add the vendor-prefixed form to match the codebase convention:
-webkit-backdrop-filter: blur(16px);
backdrop-filter: blur(16px);While current Safari (18+) supports the unprefixed form, iOS Safari 15/16 which still has noticeable usage, required the prefix. Since the header already uses the paired form, the inconsistency here is the main concern.
There was a problem hiding this comment.
Fixed in 6a14821: added -webkit-backdrop-filter: blur(16px) to match the unprefixed backdrop-filter rule.
| border-left-color: #d0d7de; | ||
| color: #424a53; | ||
| background: rgba(208, 215, 222, 0.15); | ||
| border-left-color: rgba(var(--aw-accent-rgb), 0.34); |
There was a problem hiding this comment.
Silent border drop on CSS variable failure: rgba(var(--aw-accent-rgb), 0.34) has no fallback for --aw-accent-rgb, so if that variable is unresolved the entire border-left-color declaration is silently discarded by the browser (CSS spec guarantees an invalid computed value when a custom property inside a function has no fallback).
💡 Suggested fix
Add an inline fallback to the var() call:
border-left-color: rgba(var(--aw-accent-rgb, 130, 80, 223), 0.34);The existing uses of --aw-accent-rgb in CustomHeader.astro and elsewhere already do this correctly (e.g. rgba(var(--aw-accent-rgb, 130, 80, 223), 0.12)). This is the only occurrence that omits the fallback.
There was a problem hiding this comment.
Fixed in 6a14821: added fallback in rgba(var(--aw-accent-rgb, 130, 80, 223), 0.34) for the blockquote border color.
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Ran PR finisher pass. Addressed in |
|
@copilot review all comments and address unresolved review feedback.
|
|
Refresh CI to clear stale checks and surface the current blocker.
|
|
@copilot review all comments and address unresolved review feedback.
|
|
@copilot render screenshots |
Rendered screenshots from the current branch state:
No repository file changes were needed for this request. |
The docs site had drifted into a heavily purple treatment across all pages. This change pulls the shared light and dark themes back toward neutral GitHub-like surfaces while preserving a more distinctly purple visual identity on the landing page.
Theme tokens and shared surfaces
--aw-*tokens for neutral page backgrounds, elevated surfaces, borders, muted text, shadows, and accent tinting.Non-homepage docs chrome
Homepage remains intentionally purple
WorkflowHeroframe styling so the homepage still reads as branded and visually distinct.Navigation polish
Example of the new shared theme model: