@puzzle-ui/theme 0.4.0 → 0.5.1

package/README.md

@@ -1,99 +1,134 @@
----
-title: Getting Started
-description: Install Puzzle in your React app, build your first interface, and customize the theme.
----
+# @puzzle-ui/theme
 
-> \[!WARNING\] **Puzzle is not ready for production use.**
->
-> This project is under active development. APIs, component props,
-> package exports, styling, and internal implementation may change
-> without notice. Components may be incomplete, and testing,
-> accessibility, documentation, and framework compatibility are not yet
-> guaranteed. Use it for experimentation and evaluation only---not for
-> production applications.
+Design tokens, color themes, typography, fonts, and theme scoping for Puzzle.
 
-Puzzle is a TypeScript and React UI component library built around reusable components and shared design tokens. Its components are composable and router-independent, with styling supplied by `"@puzzle-ui/theme`. The framework is setup to be compatible with `Next.js`, `Tanstack Start` and `react-router`.
+**Documentation:** [https://puzzle-ui.com/docs/theme](https://puzzle-ui.com/docs/theme)
 
-**Puzzle is under active development and is not ready for production use.** APIs, props, exports, and styling may change without notice. Accessibility and framework compatibility are still being tested. Use the project for experimentation and evaluation.
+> [!WARNING]
+> **Puzzle is not ready for production use.** APIs, tokens, and package
+> exports may change without notice. Use it for experimentation and
+> evaluation.
 
-## Prerequisites
+`@puzzle-ui/theme` is the source of truth for Puzzle's visual design. Its
+`Theme` provider turns a typed token object into CSS custom properties
+(`--puzzle-*`), loads configured fonts, resolves light, dark, and system color
+schemes, and can scope a theme to the whole document or a single subtree.
+All [`@puzzle-ui/ui`](https://puzzle-ui.com/docs/ui) components consume these
+variables, so a single provider styles your application.
 
-- A package manager: npm, Bun, pnpm, or Yarn.
-- An existing React application with a bundler that supports CSS imports, such as Vite.
-- Familiarity with React and TypeScript. The UI and theme packages require React and React DOM 19 or later within the supported React 19 range.
+## Install
 
-## Set up a new project
+```bash
+npm install @puzzle-ui/theme
+# or
+bun add @puzzle-ui/theme
+# or
+pnpm add @puzzle-ui/theme
+# or
+yarn add @puzzle-ui/theme
+```
 
-Simple run our @puzzle-ui/create project template to get started.
+React and React DOM 19 are peer dependencies.
 
-npm:
+## Usage
 
-```bash
-npx @puzzle-ui/create
-```
+Wrap your application once at the root:
 
-bun:
+```tsx
+import { Theme } from "@puzzle-ui/theme";
 
-```bash
-bunx @puzzle-ui/create
+export const App = () => (
+  <Theme>
+    <YourApp />
+  </Theme>
+);
 ```
 
-Puzzle can set up a new project for you with the following framework options:
+Customize the color scheme, color theme, fonts, and tokens:
 
-- Basic React app
-- Tanstack start
-- Next.js
+```tsx
+<Theme
+  theme="system"
+  colorTheme="cobalt-sky"
+  fonts={{
+    heading: { family: "Sora" },
+    body: { family: "Inter" },
+  }}
+  tokens={{
+    radius: { md: "0.5rem" },
+  }}
+>
+  <YourApp />
+</Theme>
+```
 
-Furthermore you can choose to install tailwindcss or not.
-It directly installs all dependencies and sets up the project for you.
+## Features
 
-## Set up in an existing project:
+| Area                 | Description                                                                                       | Docs                                                                |
+| -------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Theme provider       | Injects token CSS variables, loads fonts, and applies global styles at root or local scope.       | [Theme Provider](https://puzzle-ui.com/docs/theme/theme-provider)   |
+| Design tokens        | Typed token groups for spacing, radius, shadows, elevation, borders, layout, motion, and z-index. | [Design Tokens](https://puzzle-ui.com/docs/theme/tokens)            |
+| Colors               | Semantic color roles, light/dark color schemes, and built-in color themes.                        | [Colors](https://puzzle-ui.com/docs/theme/colors)                   |
+| Typography and fonts | Named typography roles, fluid font sizes, Google Fonts, and self-hosted fonts.                    | [Typography and Fonts](https://puzzle-ui.com/docs/theme/typography) |
+| Breakpoints          | Shared responsive breakpoints for JavaScript and CSS.                                             | [Breakpoints](https://puzzle-ui.com/docs/theme/breakpoints)         |
+| Component overrides  | Global link and image components for router and framework integration.                            | [Component Overrides](https://puzzle-ui.com/docs/theme/components)  |
 
-Install the UI library and theme package in your application's directory. Choose your package manager below:
+## Self-host fonts with the theme CLI
 
-npm:
+The `@puzzle-ui/theme` package includes the `puzzle-theme` executable.
+It requires Node.js 20.19 or later.
 
 ```bash
-npm install @puzzle-ui/ui --save
+npm install @puzzle-ui/theme
+npm exec -- puzzle-theme --help
 ```
 
-bun:
+Create `puzzle-fonts.json` in your application's working directory:
 
-```bash
-bun add @puzzle-ui/create
+```json
+{
+  "body": {
+    "family": "Inter",
+    "weights": [400, 700]
+  }
+}
 ```
 
-pnpm:
+Download the fonts with either package manager:
 
 ```bash
-pnpm add @puzzle-ui/ui
+npm exec -- puzzle-theme fonts download
+# Or, with the package installed using Bun:
+bun run puzzle-theme fonts download
 ```
 
-yarn:
+The command writes WOFF2 files and `puzzle-fonts.css` to `public/fonts`.
+Use `--config <path>` or `--out-dir <path>` to change these locations.
+Unchanged downloads are skipped; `--force` downloads them again.
 
-```bash
-yarn add @puzzle-ui/ui
-```
+For variable fonts, use `"weightRange": [300, 700]` instead of `weights`
+to request a continuous range. Only use ranges supported by the font family.
+Discrete `weights` remain supported; when both are provided, the range is used.
 
-These commands install published packages; they do not clone the repository or build its workspaces. Puzzle does not require Bun in your application. React and React DOM are peer dependencies and should already be installed in your app.
+The downloader keeps all language subsets by default. Pass
+`--subsets latin,latin-ext` to retain only Latin and Latin Extended;
+missing requested subsets produce an error. Other scripts will use fallback
+fonts. Subset choices are included in the download cache key.
 
-## Your first interface
+To load the generated stylesheet, set `fontSource="local"` on `Theme`
+and pass the same configuration to its `fonts` prop. The default local
+stylesheet URL is `/fonts/puzzle-fonts.css`.
 
-Import components from `"@puzzle-ui/ui` and wrap your application in `Theme` from `"@puzzle-ui/theme`:
+When using local fonts, Puzzle automatically preloads the normal Latin
+variant of the body font. Use `fontPreload="heading"` or
+`fontPreload="accent"` to preload another configured role, or
+`fontPreload={false}` to disable preloading.
 
-```tsx
-import { Theme } from "@puzzle-ui/theme";
-import { Button } from "@puzzle-ui/ui";
+The generated stylesheet and preload link use the same font URL, avoiding
+duplicate downloads. Preloading only applies to local fonts and only one
+font is preloaded per Theme instance.
 
-export const App = () => (
-  <Theme>
-    <main>
-      <h1>Hello, Puzzle</h1>
-      <p>Build your interface with reusable components and shared tokens.</p>
-      <Button onClick={() => window.alert("Welcome to Puzzle!")}>
-        Get started
-      </Button>
-    </main>
-  </Theme>
-);
-```
+## Related packages
+
+- [`@puzzle-ui/ui`](https://puzzle-ui.com/docs/ui) — components styled by this theme.
+- [`@puzzle-ui/core`](https://www.npmjs.com/package/@puzzle-ui/core) — shared utilities such as `cn` and responsive helpers.

package/dist/cli.cjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+const require_download_google_fonts = require("./fonts/download-google-fonts.cjs");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+// src/cli.ts
+const FONT_ROLES = [
+	"heading",
+	"body",
+	"accent"
+];
+const printHelp = () => {
+	console.log(`
+Puzzle Theme CLI
+
+Usage:
+  puzzle-theme fonts download [options]
+
+Commands:
+  fonts download          Download configured Google Fonts.
+
+Options:
+  --config <path>         Configuration file (default: puzzle-fonts.json).
+  --out-dir <path>        Output directory (default: public/fonts).
+  --force                 Force a new download.
+  --subsets <names>       Comma-separated subsets (default: all).
+  --help                  Display this help.
+
+Examples:
+  puzzle-theme fonts download
+  puzzle-theme fonts download --force
+  puzzle-theme fonts download --config ./config/fonts.json
+  puzzle-theme fonts download --out-dir public/assets/fonts
+`);
+};
+const getOption = (args, name, fallback) => {
+	const inlineOption = args.find((arg) => arg.startsWith(`${name}=`));
+	if (inlineOption) {
+		const value = inlineOption.slice(name.length + 1);
+		if (!value) throw new Error(`Missing value for ${name}.`);
+		return value;
+	}
+	const index = args.indexOf(name);
+	if (index === -1) return fallback;
+	const value = args[index + 1];
+	if (!value || value.startsWith("--")) throw new Error(`Missing value for ${name}.`);
+	return value;
+};
+const isRecord = (value) => {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+const parseFontConfig = (value) => {
+	if (!isRecord(value)) throw new TypeError("The font configuration must be a JSON object.");
+	const fonts = {};
+	for (const [role, config] of Object.entries(value)) {
+		if (!FONT_ROLES.includes(role)) throw new TypeError(`Unknown font role "${role}". Expected heading, body, or accent.`);
+		if (!isRecord(config)) throw new TypeError(`Font configuration for "${role}" must be an object.`);
+		if (typeof config.family !== "string" || !config.family.trim()) throw new TypeError(`Font configuration for "${role}" requires a family.`);
+		fonts[role] = config;
+	}
+	if (Object.keys(fonts).length === 0) throw new TypeError("No fonts configured. Add at least one font role.");
+	return fonts;
+};
+const main = async () => {
+	const args = process.argv.slice(2);
+	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+		printHelp();
+		return;
+	}
+	if (args[0] !== "fonts" || args[1] !== "download") {
+		printHelp();
+		throw new Error("Unknown command.");
+	}
+	const configPath = (0, node_path.resolve)(process.cwd(), getOption(args, "--config", "puzzle-fonts.json"));
+	const outputDir = (0, node_path.resolve)(process.cwd(), getOption(args, "--out-dir", "public/fonts"));
+	const rawConfig = JSON.parse(await (0, node_fs_promises.readFile)(configPath, "utf8"));
+	const fonts = parseFontConfig(rawConfig);
+	const result = await require_download_google_fonts.downloadGoogleFonts({
+		fonts,
+		outputDir,
+		force: args.includes("--force"),
+		subsets: getOption(args, "--subsets", "all") === "all" ? void 0 : getOption(args, "--subsets", "all").split(",").map((subset) => subset.trim())
+	});
+	if (result.skipped) {
+		console.log("Google Fonts are already up to date.");
+		console.log(`Location: ${result.cssPath}`);
+		return;
+	}
+	console.log(`Downloaded ${result.fontFiles} WOFF2 font files.`);
+	console.log(`Generated: ${result.cssPath}`);
+};
+main().catch((error) => {
+	console.error(error instanceof Error ? error.message : error);
+	process.exitCode = 1;
+});
+
+//# sourceMappingURL=cli.cjs.map

package/dist/cli.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.cjs","names":["resolve","readFile","downloadGoogleFonts"],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\n\nimport { downloadGoogleFonts } from \"./fonts/download-google-fonts\";\nimport type { FontConfig, FontRole, ThemeFonts } from \"./fonts/types\";\n\nconst FONT_ROLES: readonly FontRole[] = [\"heading\", \"body\", \"accent\"];\n\nconst printHelp = () => {\n  console.log(`\nPuzzle Theme CLI\n\nUsage:\n  puzzle-theme fonts download [options]\n\nCommands:\n  fonts download          Download configured Google Fonts.\n\nOptions:\n  --config <path>         Configuration file (default: puzzle-fonts.json).\n  --out-dir <path>        Output directory (default: public/fonts).\n  --force                 Force a new download.\n  --subsets <names>       Comma-separated subsets (default: all).\n  --help                  Display this help.\n\nExamples:\n  puzzle-theme fonts download\n  puzzle-theme fonts download --force\n  puzzle-theme fonts download --config ./config/fonts.json\n  puzzle-theme fonts download --out-dir public/assets/fonts\n`);\n};\n\nconst getOption = (args: string[], name: string, fallback: string): string => {\n  const inlineOption = args.find((arg) => arg.startsWith(`${name}=`));\n\n  if (inlineOption) {\n    const value = inlineOption.slice(name.length + 1);\n\n    if (!value) {\n      throw new Error(`Missing value for ${name}.`);\n    }\n\n    return value;\n  }\n\n  const index = args.indexOf(name);\n\n  if (index === -1) {\n    return fallback;\n  }\n\n  const value = args[index + 1];\n\n  if (!value || value.startsWith(\"--\")) {\n    throw new Error(`Missing value for ${name}.`);\n  }\n\n  return value;\n};\n\nconst isRecord = (value: unknown): value is Record<string, unknown> => {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n};\n\nconst parseFontConfig = (value: unknown): ThemeFonts => {\n  if (!isRecord(value)) {\n    throw new TypeError(\"The font configuration must be a JSON object.\");\n  }\n\n  const fonts: Partial<Record<FontRole, FontConfig>> = {};\n\n  for (const [role, config] of Object.entries(value)) {\n    if (!FONT_ROLES.includes(role as FontRole)) {\n      throw new TypeError(\n        `Unknown font role \"${role}\". Expected heading, body, or accent.`,\n      );\n    }\n\n    if (!isRecord(config)) {\n      throw new TypeError(\n        `Font configuration for \"${role}\" must be an object.`,\n      );\n    }\n\n    if (typeof config.family !== \"string\" || !config.family.trim()) {\n      throw new TypeError(\n        `Font configuration for \"${role}\" requires a family.`,\n      );\n    }\n\n    fonts[role as FontRole] = config as unknown as FontConfig;\n  }\n\n  if (Object.keys(fonts).length === 0) {\n    throw new TypeError(\"No fonts configured. Add at least one font role.\");\n  }\n\n  return fonts;\n};\n\nconst main = async () => {\n  const args = process.argv.slice(2);\n\n  if (args.includes(\"--help\") || args.includes(\"-h\") || args.length === 0) {\n    printHelp();\n    return;\n  }\n\n  if (args[0] !== \"fonts\" || args[1] !== \"download\") {\n    printHelp();\n    throw new Error(\"Unknown command.\");\n  }\n\n  const configPath = resolve(\n    process.cwd(),\n    getOption(args, \"--config\", \"puzzle-fonts.json\"),\n  );\n\n  const outputDir = resolve(\n    process.cwd(),\n    getOption(args, \"--out-dir\", \"public/fonts\"),\n  );\n\n  const rawConfig = JSON.parse(await readFile(configPath, \"utf8\")) as unknown;\n\n  const fonts = parseFontConfig(rawConfig);\n\n  const result = await downloadGoogleFonts({\n    fonts,\n    outputDir,\n    force: args.includes(\"--force\"),\n    subsets: getOption(args, \"--subsets\", \"all\") === \"all\"\n      ? undefined\n      : getOption(args, \"--subsets\", \"all\").split(\",\").map((subset) => subset.trim()),\n  });\n\n  if (result.skipped) {\n    console.log(\"Google Fonts are already up to date.\");\n    console.log(`Location: ${result.cssPath}`);\n    return;\n  }\n\n  console.log(`Downloaded ${result.fontFiles} WOFF2 font files.`);\n\n  console.log(`Generated: ${result.cssPath}`);\n};\n\nvoid main().catch((error: unknown) => {\n  console.error(error instanceof Error ? error.message : error);\n\n  process.exitCode = 1;\n});\n"],"mappings":"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"}

package/dist/cli.d.cts

@@ -0,0 +1 @@
+export {}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { downloadGoogleFonts } from "./fonts/download-google-fonts.js";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+// src/cli.ts
+const FONT_ROLES = [
+	"heading",
+	"body",
+	"accent"
+];
+const printHelp = () => {
+	console.log(`
+Puzzle Theme CLI
+
+Usage:
+  puzzle-theme fonts download [options]
+
+Commands:
+  fonts download          Download configured Google Fonts.
+
+Options:
+  --config <path>         Configuration file (default: puzzle-fonts.json).
+  --out-dir <path>        Output directory (default: public/fonts).
+  --force                 Force a new download.
+  --subsets <names>       Comma-separated subsets (default: all).
+  --help                  Display this help.
+
+Examples:
+  puzzle-theme fonts download
+  puzzle-theme fonts download --force
+  puzzle-theme fonts download --config ./config/fonts.json
+  puzzle-theme fonts download --out-dir public/assets/fonts
+`);
+};
+const getOption = (args, name, fallback) => {
+	const inlineOption = args.find((arg) => arg.startsWith(`${name}=`));
+	if (inlineOption) {
+		const value = inlineOption.slice(name.length + 1);
+		if (!value) throw new Error(`Missing value for ${name}.`);
+		return value;
+	}
+	const index = args.indexOf(name);
+	if (index === -1) return fallback;
+	const value = args[index + 1];
+	if (!value || value.startsWith("--")) throw new Error(`Missing value for ${name}.`);
+	return value;
+};
+const isRecord = (value) => {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+const parseFontConfig = (value) => {
+	if (!isRecord(value)) throw new TypeError("The font configuration must be a JSON object.");
+	const fonts = {};
+	for (const [role, config] of Object.entries(value)) {
+		if (!FONT_ROLES.includes(role)) throw new TypeError(`Unknown font role "${role}". Expected heading, body, or accent.`);
+		if (!isRecord(config)) throw new TypeError(`Font configuration for "${role}" must be an object.`);
+		if (typeof config.family !== "string" || !config.family.trim()) throw new TypeError(`Font configuration for "${role}" requires a family.`);
+		fonts[role] = config;
+	}
+	if (Object.keys(fonts).length === 0) throw new TypeError("No fonts configured. Add at least one font role.");
+	return fonts;
+};
+const main = async () => {
+	const args = process.argv.slice(2);
+	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+		printHelp();
+		return;
+	}
+	if (args[0] !== "fonts" || args[1] !== "download") {
+		printHelp();
+		throw new Error("Unknown command.");
+	}
+	const configPath = resolve(process.cwd(), getOption(args, "--config", "puzzle-fonts.json"));
+	const outputDir = resolve(process.cwd(), getOption(args, "--out-dir", "public/fonts"));
+	const rawConfig = JSON.parse(await readFile(configPath, "utf8"));
+	const fonts = parseFontConfig(rawConfig);
+	const result = await downloadGoogleFonts({
+		fonts,
+		outputDir,
+		force: args.includes("--force"),
+		subsets: getOption(args, "--subsets", "all") === "all" ? void 0 : getOption(args, "--subsets", "all").split(",").map((subset) => subset.trim())
+	});
+	if (result.skipped) {
+		console.log("Google Fonts are already up to date.");
+		console.log(`Location: ${result.cssPath}`);
+		return;
+	}
+	console.log(`Downloaded ${result.fontFiles} WOFF2 font files.`);
+	console.log(`Generated: ${result.cssPath}`);
+};
+main().catch((error) => {
+	console.error(error instanceof Error ? error.message : error);
+	process.exitCode = 1;
+});
+export {};
+
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\n\nimport { downloadGoogleFonts } from \"./fonts/download-google-fonts\";\nimport type { FontConfig, FontRole, ThemeFonts } from \"./fonts/types\";\n\nconst FONT_ROLES: readonly FontRole[] = [\"heading\", \"body\", \"accent\"];\n\nconst printHelp = () => {\n  console.log(`\nPuzzle Theme CLI\n\nUsage:\n  puzzle-theme fonts download [options]\n\nCommands:\n  fonts download          Download configured Google Fonts.\n\nOptions:\n  --config <path>         Configuration file (default: puzzle-fonts.json).\n  --out-dir <path>        Output directory (default: public/fonts).\n  --force                 Force a new download.\n  --subsets <names>       Comma-separated subsets (default: all).\n  --help                  Display this help.\n\nExamples:\n  puzzle-theme fonts download\n  puzzle-theme fonts download --force\n  puzzle-theme fonts download --config ./config/fonts.json\n  puzzle-theme fonts download --out-dir public/assets/fonts\n`);\n};\n\nconst getOption = (args: string[], name: string, fallback: string): string => {\n  const inlineOption = args.find((arg) => arg.startsWith(`${name}=`));\n\n  if (inlineOption) {\n    const value = inlineOption.slice(name.length + 1);\n\n    if (!value) {\n      throw new Error(`Missing value for ${name}.`);\n    }\n\n    return value;\n  }\n\n  const index = args.indexOf(name);\n\n  if (index === -1) {\n    return fallback;\n  }\n\n  const value = args[index + 1];\n\n  if (!value || value.startsWith(\"--\")) {\n    throw new Error(`Missing value for ${name}.`);\n  }\n\n  return value;\n};\n\nconst isRecord = (value: unknown): value is Record<string, unknown> => {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n};\n\nconst parseFontConfig = (value: unknown): ThemeFonts => {\n  if (!isRecord(value)) {\n    throw new TypeError(\"The font configuration must be a JSON object.\");\n  }\n\n  const fonts: Partial<Record<FontRole, FontConfig>> = {};\n\n  for (const [role, config] of Object.entries(value)) {\n    if (!FONT_ROLES.includes(role as FontRole)) {\n      throw new TypeError(\n        `Unknown font role \"${role}\". Expected heading, body, or accent.`,\n      );\n    }\n\n    if (!isRecord(config)) {\n      throw new TypeError(\n        `Font configuration for \"${role}\" must be an object.`,\n      );\n    }\n\n    if (typeof config.family !== \"string\" || !config.family.trim()) {\n      throw new TypeError(\n        `Font configuration for \"${role}\" requires a family.`,\n      );\n    }\n\n    fonts[role as FontRole] = config as unknown as FontConfig;\n  }\n\n  if (Object.keys(fonts).length === 0) {\n    throw new TypeError(\"No fonts configured. Add at least one font role.\");\n  }\n\n  return fonts;\n};\n\nconst main = async () => {\n  const args = process.argv.slice(2);\n\n  if (args.includes(\"--help\") || args.includes(\"-h\") || args.length === 0) {\n    printHelp();\n    return;\n  }\n\n  if (args[0] !== \"fonts\" || args[1] !== \"download\") {\n    printHelp();\n    throw new Error(\"Unknown command.\");\n  }\n\n  const configPath = resolve(\n    process.cwd(),\n    getOption(args, \"--config\", \"puzzle-fonts.json\"),\n  );\n\n  const outputDir = resolve(\n    process.cwd(),\n    getOption(args, \"--out-dir\", \"public/fonts\"),\n  );\n\n  const rawConfig = JSON.parse(await readFile(configPath, \"utf8\")) as unknown;\n\n  const fonts = parseFontConfig(rawConfig);\n\n  const result = await downloadGoogleFonts({\n    fonts,\n    outputDir,\n    force: args.includes(\"--force\"),\n    subsets: getOption(args, \"--subsets\", \"all\") === \"all\"\n      ? undefined\n      : getOption(args, \"--subsets\", \"all\").split(\",\").map((subset) => subset.trim()),\n  });\n\n  if (result.skipped) {\n    console.log(\"Google Fonts are already up to date.\");\n    console.log(`Location: ${result.cssPath}`);\n    return;\n  }\n\n  console.log(`Downloaded ${result.fontFiles} WOFF2 font files.`);\n\n  console.log(`Generated: ${result.cssPath}`);\n};\n\nvoid main().catch((error: unknown) => {\n  console.error(error instanceof Error ? error.message : error);\n\n  process.exitCode = 1;\n});\n"],"mappings":";;;;;AAQA,MAAM,aAAkC;CAAC;CAAW;CAAQ;AAAQ;AAEpE,MAAM,kBAAkB;CACtB,QAAQ,IAAI;;;;;;;;;;;;;;;;;;;;;CAqBb;AACD;AAEA,MAAM,aAAa,MAAgB,MAAc,aAA6B;CAC5E,MAAM,eAAe,KAAK,MAAM,QAAQ,IAAI,WAAW,GAAG,KAAK,EAAE,CAAC;CAElE,IAAI,cAAc;EAChB,MAAM,QAAQ,aAAa,MAAM,KAAK,SAAS,CAAC;EAEhD,IAAI,CAAC,OACH,MAAM,IAAI,MAAM,qBAAqB,KAAK,EAAE;EAG9C,OAAO;CACT;CAEA,MAAM,QAAQ,KAAK,QAAQ,IAAI;CAE/B,IAAI,UAAU,IACZ,OAAO;CAGT,MAAM,QAAQ,KAAK,QAAQ;CAE3B,IAAI,CAAC,SAAS,MAAM,WAAW,IAAI,GACjC,MAAM,IAAI,MAAM,qBAAqB,KAAK,EAAE;CAG9C,OAAO;AACT;AAEA,MAAM,YAAY,UAAqD;CACrE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAEA,MAAM,mBAAmB,UAA+B;CACtD,IAAI,CAAC,SAAS,KAAK,GACjB,MAAM,IAAI,UAAU,+CAA+C;CAGrE,MAAM,QAA+C,CAAC;CAEtD,KAAK,MAAM,CAAC,MAAM,WAAW,OAAO,QAAQ,KAAK,GAAG;EAClD,IAAI,CAAC,WAAW,SAAS,IAAgB,GACvC,MAAM,IAAI,UACR,sBAAsB,KAAK,sCAC7B;EAGF,IAAI,CAAC,SAAS,MAAM,GAClB,MAAM,IAAI,UACR,2BAA2B,KAAK,qBAClC;EAGF,IAAI,OAAO,OAAO,WAAW,YAAY,CAAC,OAAO,OAAO,KAAK,GAC3D,MAAM,IAAI,UACR,2BAA2B,KAAK,qBAClC;EAGF,MAAM,QAAoB;CAC5B;CAEA,IAAI,OAAO,KAAK,KAAK,CAAC,CAAC,WAAW,GAChC,MAAM,IAAI,UAAU,kDAAkD;CAGxE,OAAO;AACT;AAEA,MAAM,OAAO,YAAY;CACvB,MAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;CAEjC,IAAI,KAAK,SAAS,QAAQ,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,WAAW,GAAG;EACvE,UAAU;EACV;CACF;CAEA,IAAI,KAAK,OAAO,WAAW,KAAK,OAAO,YAAY;EACjD,UAAU;EACV,MAAM,IAAI,MAAM,kBAAkB;CACpC;CAEA,MAAM,aAAa,QACjB,QAAQ,IAAI,GACZ,UAAU,MAAM,YAAY,mBAAmB,CACjD;CAEA,MAAM,YAAY,QAChB,QAAQ,IAAI,GACZ,UAAU,MAAM,aAAa,cAAc,CAC7C;CAEA,MAAM,YAAY,KAAK,MAAM,MAAM,SAAS,YAAY,MAAM,CAAC;CAE/D,MAAM,QAAQ,gBAAgB,SAAS;CAEvC,MAAM,SAAS,MAAM,oBAAoB;EACvC;EACA;EACA,OAAO,KAAK,SAAS,SAAS;EAC9B,SAAS,UAAU,MAAM,aAAa,KAAK,MAAM,QAC7C,KAAA,IACA,UAAU,MAAM,aAAa,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,WAAW,OAAO,KAAK,CAAC;CAClF,CAAC;CAED,IAAI,OAAO,SAAS;EAClB,QAAQ,IAAI,sCAAsC;EAClD,QAAQ,IAAI,aAAa,OAAO,SAAS;EACzC;CACF;CAEA,QAAQ,IAAI,cAAc,OAAO,UAAU,mBAAmB;CAE9D,QAAQ,IAAI,cAAc,OAAO,SAAS;AAC5C;AAEK,KAAK,CAAC,CAAC,OAAO,UAAmB;CACpC,QAAQ,MAAM,iBAAiB,QAAQ,MAAM,UAAU,KAAK;CAE5D,QAAQ,WAAW;AACrB,CAAC"}

package/dist/constants.cjs

@@ -20,26 +20,26 @@ const DEFAULT_TOKENS = {
 			background: "#FCFCFC",
 			surface: "#FFFFFF",
 			surfaceElevated: "#FFFFFF",
-			surfaceSunken: "#F7F7F7",
+			surfaceSunken: "#F0F0F0",
 			text: "#171A35",
 			textMuted: "#5F6485",
 			textSubtle: "#8B91B3",
 			border: "#E0E5F5",
 			borderStrong: "#C4CBE6",
-			primary: "#0284C7",
+			primary: "#0277B5",
 			primaryForeground: "#FFFFFF",
-			secondary: "#075985",
+			secondary: "#475569",
 			secondaryForeground: "#FFFFFF",
-			accent: "#06B6D4",
+			accent: "#6D28D9",
 			accentForeground: "#FFFFFF",
 			ring: "#A5B4FC",
 			success: "#15803D",
 			successForeground: "#FFFFFF",
-			warning: "#A16207",
+			warning: "#FABC0A",
 			warningForeground: "#FFFFFF",
 			danger: "#B91C1C",
 			dangerForeground: "#FFFFFF",
-			info: "#0369A1",
+			info: "#1D4ED8",
 			infoForeground: "#FFFFFF"
 		},
 		dark: {
@@ -54,10 +54,10 @@ const DEFAULT_TOKENS = {
 			borderStrong: "#4a555d",
 			primary: "#38BDF8",
 			primaryForeground: "#082F49",
-			secondary: "#7DD3FC",
-			secondaryForeground: "#082F49",
-			accent: "#22D3EE",
-			accentForeground: "#083344",
+			secondary: "#94A3B8",
+			secondaryForeground: "#0F172A",
+			accent: "#C4B5FD",
+			accentForeground: "#1E1B4B",
 			ring: "#93c5fd",
 			success: "#4ade80",
 			successForeground: "#052e16",
@@ -65,8 +65,8 @@ const DEFAULT_TOKENS = {
 			warningForeground: "#422006",
 			danger: "#f87171",
 			dangerForeground: "#450a0a",
-			info: "#38bdf8",
-			infoForeground: "#082f49"
+			info: "#818CF8",
+			infoForeground: "#1E1B4B"
 		}
 	},
 	typography: {
@@ -176,7 +176,7 @@ const DEFAULT_TOKENS = {
 		8: "0 25px 50px -12px rgb(0 0 0 / 0.20)",
 		12: "0 35px 60px -15px rgb(0 0 0 / 0.22)",
 		16: "0 45px 80px -20px rgb(0 0 0 / 0.25)",
-		24: "0 60px 100px -25px rgb(0 0 0 / 0.30)"
+		24: "0 60px 100px -20px rgb(0 0 0 / 0.40), 0 24px 40px -12px rgb(0 0 0 / 0.25)"
 	},
 	motion: {
 		fast: "120ms",
@@ -255,7 +255,7 @@ const COLOR_THEMES = {
 			ring: "#C4B5FD",
 			success: "#15803D",
 			successForeground: "#FFFFFF",
-			warning: "#A16207",
+			warning: "#FABC0A",
 			warningForeground: "#FFFFFF",
 			danger: "#BE123C",
 			dangerForeground: "#FFFFFF",
@@ -291,7 +291,7 @@ const COLOR_THEMES = {
 			ring: "#6EE7B7",
 			success: "#15803D",
 			successForeground: "#FFFFFF",
-			warning: "#A16207",
+			warning: "#FABC0A",
 			warningForeground: "#FFFFFF",
 			danger: "#B91C1C",
 			dangerForeground: "#FFFFFF",
@@ -327,7 +327,7 @@ const COLOR_THEMES = {
 			ring: "#FDBA74",
 			success: "#15803D",
 			successForeground: "#FFFFFF",
-			warning: "#A16207",
+			warning: "#FABC0A",
 			warningForeground: "#FFFFFF",
 			danger: "#B91C1C",
 			dangerForeground: "#FFFFFF",
@@ -399,7 +399,7 @@ const COLOR_THEMES = {
 			ring: "#5EEAD4",
 			success: "#15803D",
 			successForeground: "#FFFFFF",
-			warning: "#A16207",
+			warning: "#FABC0A",
 			warningForeground: "#FFFFFF",
 			danger: "#B91C1C",
 			dangerForeground: "#FFFFFF",
@@ -435,7 +435,7 @@ const COLOR_THEMES = {
 			ring: "#D8B4FE",
 			success: "#15803D",
 			successForeground: "#FFFFFF",
-			warning: "#A16207",
+			warning: "#FABC0A",
 			warningForeground: "#FFFFFF",
 			danger: "#B91C1C",
 			dangerForeground: "#FFFFFF",
@@ -471,7 +471,7 @@ const COLOR_THEMES = {
 			ring: "#67E8F9",
 			success: "#15803D",
 			successForeground: "#FFFFFF",
-			warning: "#A16207",
+			warning: "#FABC0A",
 			warningForeground: "#FFFFFF",
 			danger: "#B91C1C",
 			dangerForeground: "#FFFFFF",
@@ -507,7 +507,7 @@ const COLOR_THEMES = {
 			ring: "#FDBA74",
 			success: "#15803D",
 			successForeground: "#FFFFFF",
-			warning: "#A16207",
+			warning: "#FABC0A",
 			warningForeground: "#FFFFFF",
 			danger: "#B91C1C",
 			dangerForeground: "#FFFFFF",
@@ -543,7 +543,7 @@ const COLOR_THEMES = {
 			ring: "#A5B4FC",
 			success: "#15803D",
 			successForeground: "#FFFFFF",
-			warning: "#A16207",
+			warning: "#FABC0A",
 			warningForeground: "#FFFFFF",
 			danger: "#B91C1C",
 			dangerForeground: "#FFFFFF",