Skip to content

Give the docs site both halves of the theme toggle - #4

Merged
oneleggedswede merged 1 commit into
mainfrom
fix/docs-site-theme-toggle
Sep 6, 2026
Merged

Give the docs site both halves of the theme toggle#4
oneleggedswede merged 1 commit into
mainfrom
fix/docs-site-theme-toggle

Conversation

@oneleggedswede

@oneleggedswede oneleggedswede commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

The component previews on the documentation site followed the operating system whatever the site's own theme switch said. A reader on a dark machine who asked laradocs for light got a white preview stage with dark buttons standing on it, and the reverse on a light machine.

Cause

docs/theming.md describes a manual toggle as two halves: a @custom-variant dark so dark: compiles against the selector, and the three blocks in shape.css restated under that selector, because a media query cannot be re-pointed at a selector from outside.

workbench/resources/css/theme.src.css already writes both halves out, and both gallery builds import it — but docs.src.css carried only a hand-rolled copy of the custom variant. So the switch repainted the preview stage, which is a utility, and nothing standing on it: --shape-tone, the surface contract and the progress track were all still being set by prefers-color-scheme inside shape.css.

Fix

Import the same file the gallery imports, rather than keep a second copy of half of it. The docs site is a consuming application too, so it takes the path the documentation already describes.

The token half also carries color-scheme, which laradocs never declares at all — so the previews stop showing light native scrollbars and form-control chrome on a dark page. That applies to the whole documentation page, not only the previews.

Verification

Checked against a running composer serve with prefers-color-scheme emulated in each direction:

machine reader picks before after
dark light white stage, dark buttons light throughout
light dark dark stage, light buttons dark throughout
either auto correct unchanged

--shape-tone now flips with the switch, and the restated blocks land in the layers their originals are in — the surface contract in @layer base, the tone block and progress track in @layer components. That ordering is load-bearing: a tone restatement written in base loses to the plain [data-shape-tone] in components, and the symptom is a page that turns dark around buttons that stay light.

npm run preview and npm run preview:seed rebuild byte-identical; only comments changed in theme.src.css.

composer test passes — PHPStan clean, Pint clean, 100% type coverage, 842 tests / 2163 assertions.

The previews followed the operating system whatever the site's own switch
said. A reader on a dark machine who asked laradocs for light got a white
preview stage with dark buttons standing on it, and the reverse on a light
machine.

docs/theming.md describes a manual toggle as two halves: a custom variant so
dark: compiles against the selector, and the three blocks in shape.css
restated under it, because a media query cannot be re-pointed at a selector
from outside. theme.src.css already writes both out, and both gallery builds
import it — but docs.src.css had only a hand-rolled copy of the custom
variant. So the switch repainted the stage, which is a utility, and nothing
standing on it: --shape-tone, the surface contract and the progress track
were all still being set by prefers-color-scheme inside shape.css.

Import the same file the gallery imports rather than keeping a second copy of
half of it. The docs site is a consuming application too, so it takes the path
the documentation describes.

The token half also carries color-scheme, which laradocs never declares, so
the previews stop showing light native scrollbars and form-control chrome on a
dark page.
@oneleggedswede oneleggedswede added documentation Improvements or additions to documentation skip-changelog Left out of the generated release notes and removed documentation Improvements or additions to documentation labels Sep 6, 2026
@oneleggedswede
oneleggedswede merged commit 22034a0 into main Sep 6, 2026
13 checks passed
@oneleggedswede
oneleggedswede deleted the fix/docs-site-theme-toggle branch September 6, 2026 19:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

skip-changelog Left out of the generated release notes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant