open/playground-design-system
1
0
Fork 0
Code Issues Releases 1 Activity

docs: document theme-bootstrap script in README Quick start

Browse source 
Both ms-ai-architect and llm-security run an identical FOUC-prevention
script (localStorage read, matchMedia fallback, HTML-attribute default)
before their stylesheet links, keyed per plugin. The shared README's
Quick start example didn't show it, so a reader copying the example
verbatim would get a flash-of-wrong-theme.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RwqsYBS9ZuEEAMSURJURiR
This commit is contained in:
Kjell Tore Guttormsen 2026-08-18 17:11:10 +02:00
commit 0fa22b9f83
1 changed files with 32 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

32
README.md
View file

@ -98,6 +98,30 @@ To use the design system from a plugin's Playground:
<html lang="nb" data-theme="light"> <html lang="nb" data-theme="light">
<head> <head>
<meta charset="utf-8"> <meta charset="utf-8">
<!-- Theme bootstrap. Must run before the stylesheets parse to avoid a
flash-of-wrong-theme (FOUC). Priority order:
1) saved choice (localStorage '<plugin-name>-theme')
2) OS preference via matchMedia('(prefers-color-scheme: dark)')
3) the HTML attribute default ('light' above)
Sets both data-theme + colorScheme for native form controls and scrollbars.
Wrapped in try/catch — file:// + private mode can block localStorage. -->
<script>
(function () {
var theme = null;
try {
var saved = localStorage.getItem('<plugin-name>-theme');
if (saved === 'light' || saved === 'dark') theme = saved;
} catch (e) { /* localStorage unavailable */ }
if (!theme && window.matchMedia) {
theme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
}
if (!theme) theme = document.documentElement.getAttribute('data-theme') || 'light';
document.documentElement.setAttribute('data-theme', theme);
document.documentElement.style.colorScheme = theme;
})();
</script>
<link rel="stylesheet" href="vendor/playground-design-system/tokens.css"> <link rel="stylesheet" href="vendor/playground-design-system/tokens.css">
<link rel="stylesheet" href="vendor/playground-design-system/base.css"> <link rel="stylesheet" href="vendor/playground-design-system/base.css">
<link rel="stylesheet" href="vendor/playground-design-system/components.css"> <link rel="stylesheet" href="vendor/playground-design-system/components.css">
@ -130,6 +154,14 @@ The relative path `vendor/playground-design-system/` assumes the plugin's Playgr
in) at `<plugin-name>/playground/vendor/playground-design-system/`. Adjust the prefix to match your in) at `<plugin-name>/playground/vendor/playground-design-system/`. Adjust the prefix to match your
plugin's structure. plugin's structure.
The theme-bootstrap script is not part of the vendored CSS — copy it into each Playground's own
`<head>`, replacing `<plugin-name>-theme` with a key unique to that plugin (both `ms-ai-architect`
and `llm-security` follow this pattern today). The `data-theme-toggle` button's own click handler
(written per Playground, not vendored) is what writes that key via `localStorage.setItem` when the
reader switches theme — the bootstrap script only reads it back on the next load. Without the
bootstrap script, the page renders in the HTML attribute's default theme for one frame before
JavaScript applies the saved/OS preference — the FOUC it exists to prevent.
## Design principles ## Design principles
1. **Aksel/Digdir-aligned.** Inter font, body 17px, Digdir blue `#0062BA`, semantic CSS tokens. Norwegian public sector users recognize this DNA. 1. **Aksel/Digdir-aligned.** Inter font, body 17px, Digdir blue `#0062BA`, semantic CSS tokens. Norwegian public sector users recognize this DNA.