@solexllc/usx-theme 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +60 -2
  3. package/build.js +71 -7
  4. package/dist/_themes-registry.scss +948 -0
  5. package/dist/themes/aurora.css +77 -0
  6. package/dist/themes/borealis.css +104 -0
  7. package/dist/themes/carbon.css +79 -0
  8. package/dist/themes/forest.css +52 -0
  9. package/dist/themes/gov-uk.css +72 -0
  10. package/dist/themes/midnight.css +79 -0
  11. package/dist/themes/nasa.css +72 -0
  12. package/dist/themes/ocean.css +52 -0
  13. package/dist/themes/sunset.css +52 -0
  14. package/dist/themes/vads.css +38 -0
  15. package/dist/themes.css +677 -0
  16. package/package.json +17 -2
  17. package/src/_themes.scss +120 -0
  18. package/src/_variables.scss +0 -1
  19. package/src/derive.js +233 -0
  20. package/src/presets.js +348 -0
  21. package/src/theme-manifest.js +2 -2
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Alex
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -10,15 +10,22 @@ This package stores platform-agnostic tokens in JSON source files and compiles t
10
10
  - `src/radius.json`: border radius tokens
11
11
  - `src/_variables.scss`: Sass design tokens (the theme layer consumed by `@solexllc/usx`)
12
12
  - `src/theme-manifest.js`: canonical manifest of themeable tokens (names, CSS variables, defaults, derivation)
13
+ - `src/presets.js`: the prebuilt theme palettes (Forest, Carbon, GOV.UK, …)
14
+ - `src/derive.js`: shade derivation + theme serialization (CSS / Sass export), shared by the build and the Playground
15
+ - `src/_themes.scss`: the opt-in prebuilt/custom themes Sass module (`@solexllc/usx-theme/themes`)
13
16
  - `dist/tokens.css`: generated CSS variables
14
17
  - `dist/tokens.js`: generated JS export
15
18
  - `dist/theme-manifest.json`: generated theme manifest
19
+ - `dist/theme.css`: every `--usx-*` token at its default, on `:root`
20
+ - `dist/themes/<slug>.css`, `dist/themes.css`: each prebuilt theme as a `[data-theme="<slug>"]` block (and all of them together)
21
+ - `dist/_themes-registry.scss`: generated data behind `src/_themes.scss`
16
22
 
17
23
  ## Build
18
24
 
19
25
  ```sh
20
26
  pnpm build # node build.js → dist/
21
27
  pnpm dev # node build.js --watch (used by the root `pnpm dev`)
28
+ pnpm test # rebuild + test/themes-check.mjs
22
29
  ```
23
30
 
24
31
  `src/system-colors.generated.js` (the USWDS system-color palette used by the
@@ -73,6 +80,57 @@ the output contains zero `var()` references:
73
80
  Individual tokens can also opt out by nulling their hook
74
81
  (e.g. `$usx-color-primary-var: null`).
75
82
 
83
+ ### Prebuilt themes
84
+
85
+ The Playground's presets ship prebuilt. List the ones you want; nothing else
86
+ reaches your bundle. Themes apply via `data-theme`; `$default` also applies
87
+ with no attribute, `$prefersdark` under `prefers-color-scheme: dark`.
88
+
89
+ ```scss
90
+ @use 'pkg:@solexllc/usx/themed';
91
+ @use 'pkg:@solexllc/usx-theme/themes' with (
92
+ $themes: (forest, carbon, gov-uk),
93
+ $default: forest,
94
+ $prefersdark: carbon,
95
+ );
96
+ ```
97
+
98
+ ```html
99
+ <html data-theme="gov-uk">
100
+ ```
101
+
102
+ `$themes` can also be a map, to tweak a prebuilt theme or add your own — the
103
+ Playground's **Sass theme entry** export pastes straight in:
104
+
105
+ ```scss
106
+ @use 'pkg:@solexllc/usx-theme/themes' with (
107
+ $themes: (
108
+ forest: (),
109
+ carbon: (--usx-color-primary: #ff7a00),
110
+ acme: (
111
+ color-scheme: light,
112
+ --usx-color-primary: #b00020,
113
+ --usx-color-primary-hover: #8a0018,
114
+ ),
115
+ ),
116
+ $default: acme,
117
+ );
118
+ ```
119
+
120
+ Every emitted theme declares the union of tokens across all emitted themes
121
+ (falling back to the `:root` default), so switching `data-theme` — even on a
122
+ nested element — never leaks a value from the previous theme.
123
+ `themes.theme($tokens, $selector)` emits a one-off block outside that union,
124
+ and `themes.$available` lists the prebuilt names.
125
+
126
+ Without Sass, import the plain stylesheets instead (no default/prefers-dark
127
+ wiring in this form):
128
+
129
+ ```js
130
+ import '@solexllc/usx-theme/theme.css';
131
+ import '@solexllc/usx-theme/themes/forest.css'; // or .../themes.css for all
132
+ ```
133
+
76
134
  ### Notes
77
135
 
78
136
  - **Derived shades are first-class tokens.** Overriding `--usx-color-primary`
@@ -88,5 +146,5 @@ Individual tokens can also opt out by nulling their hook
88
146
 
89
147
  The Storybook page **Documentation → Theme → Playground** renders the component showcase with
90
148
  live controls for every manifest token, auto-derives shades when a base color
91
- changes, and exports a ready-to-use `:root { --usx-*: ... }` block
92
- (copy/download).
149
+ changes, and exports the result as a Sass `$themes` entry, a `[data-theme]`
150
+ stylesheet, or a plain `:root { --usx-*: ... }` block (copy/download).
package/build.js CHANGED
@@ -6,15 +6,18 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
6
6
  const srcDir = path.join(__dirname, 'src');
7
7
  const primitivesDir = path.join(srcDir, 'primitives');
8
8
  const distDir = path.join(__dirname, 'dist');
9
- const manifestPath = path.join(srcDir, 'theme-manifest.js');
9
+ const themesDistDir = path.join(distDir, 'themes');
10
10
 
11
- // Re-imports theme-manifest.js with a cache-busting query so `--watch` picks
12
- // up edits (ESM's module cache would otherwise serve the first-loaded copy
11
+ // Re-imports src modules with a cache-busting query so `--watch` picks up
12
+ // edits (ESM's module cache would otherwise serve the first-loaded copy
13
13
  // forever within this long-lived process).
14
+ async function freshImport(file) {
15
+ const url = `${pathToFileURL(path.join(srcDir, file)).href}?update=${Date.now()}`;
16
+ return import(url);
17
+ }
18
+
14
19
  async function loadThemeManifest() {
15
- const url = `${pathToFileURL(manifestPath).href}?update=${Date.now()}`;
16
- const mod = await import(url);
17
- return mod.themeManifest;
20
+ return (await freshImport('theme-manifest.js')).themeManifest;
18
21
  }
19
22
 
20
23
  const tokenFiles = [
@@ -75,8 +78,68 @@ function buildJs(tokens) {
75
78
  return `module.exports = ${JSON.stringify(tokens, null, 2)};\n`;
76
79
  }
77
80
 
81
+ const GENERATED_CSS = '/* GENERATED by build.js from presets.js — do not edit. */\n';
82
+
83
+ // Resolves every prebuilt preset (derived shades included) once, so the CSS
84
+ // files and the Sass registry are guaranteed to agree.
85
+ function resolvePresets(themeManifest, derive, PRESETS) {
86
+ return Object.entries(PRESETS).map(([name, overrides]) => {
87
+ const resolved = derive.resolveTheme(overrides, {}, themeManifest);
88
+ return {
89
+ name,
90
+ slug: derive.themeSlug(name),
91
+ colorScheme: derive.colorSchemeOf(resolved),
92
+ entries: derive.themeEntries(resolved, { manifest: themeManifest })
93
+ };
94
+ });
95
+ }
96
+
97
+ // themes/<slug>.css — one `[data-theme="<slug>"]` block per prebuilt theme,
98
+ // changed tokens only (theme.css's :root supplies the rest). "Default" has
99
+ // nothing to change and is skipped.
100
+ function buildThemeFileCss(theme) {
101
+ const lines = [` color-scheme: ${theme.colorScheme};`, ...theme.entries.map(([cssVar, value]) => ` ${cssVar}: ${value};`)];
102
+ return `${GENERATED_CSS}[data-theme="${theme.slug}"] {\n${lines.join('\n')}\n}\n`;
103
+ }
104
+
105
+ // _themes-registry.scss — data behind src/_themes.scss: every prebuilt theme
106
+ // as a Sass map keyed by CSS variable, plus the :root defaults used to fill
107
+ // in tokens a theme doesn't set.
108
+ function buildThemesRegistryScss(themeManifest, themes, derive) {
109
+ const themeBlocks = themes.map((theme) => {
110
+ const lines = [` color-scheme: ${theme.colorScheme},`, ...theme.entries.map(([cssVar, value]) => ` ${cssVar}: ${derive.toSassValue(value)},`)];
111
+ return ` ${theme.slug}: (\n${lines.join('\n')}\n ),`;
112
+ });
113
+ const defaultLines = themeManifest.map((t) => ` ${t.cssVar}: ${derive.toSassValue(t.defaultValue)},`);
114
+ return [
115
+ '// GENERATED by build.js from presets.js + theme-manifest.js — do not edit.',
116
+ '// Consumed by src/_themes.scss (`pkg:@solexllc/usx-theme/themes`).',
117
+ `$themes: (\n${themeBlocks.join('\n')}\n);`,
118
+ `$defaults: (\n${defaultLines.join('\n')}\n);`,
119
+ ''
120
+ ].join('\n');
121
+ }
122
+
123
+ function writeThemes(themeManifest, derive, PRESETS) {
124
+ const themes = resolvePresets(themeManifest, derive, PRESETS);
125
+ const withTokens = themes.filter((t) => t.entries.length > 0);
126
+
127
+ fs.rmSync(themesDistDir, { recursive: true, force: true });
128
+ fs.mkdirSync(themesDistDir, { recursive: true });
129
+ const files = withTokens.map((theme) => {
130
+ const css = buildThemeFileCss(theme);
131
+ fs.writeFileSync(path.join(themesDistDir, `${theme.slug}.css`), css, 'utf8');
132
+ return css.replace(GENERATED_CSS, '');
133
+ });
134
+ fs.writeFileSync(path.join(distDir, 'themes.css'), GENERATED_CSS + files.join('\n'), 'utf8');
135
+ fs.writeFileSync(path.join(distDir, '_themes-registry.scss'), buildThemesRegistryScss(themeManifest, themes, derive), 'utf8');
136
+ return withTokens.map((t) => t.slug);
137
+ }
138
+
78
139
  async function build() {
79
140
  const themeManifest = await loadThemeManifest();
141
+ const derive = await freshImport('derive.js');
142
+ const { PRESETS } = await freshImport('presets.js');
80
143
  const tokens = loadTokens();
81
144
 
82
145
  fs.mkdirSync(distDir, { recursive: true });
@@ -90,8 +153,9 @@ async function build() {
90
153
  JSON.stringify(themeManifest, null, 2) + '\n',
91
154
  'utf8'
92
155
  );
156
+ const slugs = writeThemes(themeManifest, derive, PRESETS);
93
157
 
94
- console.log(`[${new Date().toLocaleTimeString()}] Built tokens to dist/ (tokens.css, theme.css, _hooks.scss, tokens.js, theme-manifest.json)`);
158
+ console.log(`[${new Date().toLocaleTimeString()}] Built tokens to dist/ (tokens.css, theme.css, _hooks.scss, tokens.js, theme-manifest.json, themes.css, _themes-registry.scss, themes/{${slugs.join(',')}}.css)`);
95
159
  }
96
160
 
97
161
  // `node build.js --watch` rebuilds on every change under src/ (primitives