@puzzle-ui/theme 0.3.0 → 0.5.0

package/README.md

@@ -1,113 +1,153 @@
-# @puzzle-ui/theme
+# Getting Started
 
-Puzzle's theme system: semantic design tokens, light/dark color schemes,
-typography, Google Fonts, and configurable link and image components.
+Install Puzzle in your React app, build your first interface, and customize the theme.
 
-> Puzzle is under active development. APIs and framework compatibility may
-> change; use it for experimentation and evaluation rather than production.
+> \[!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.
 
-## Installation
+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`.
 
-```sh
-npm install @puzzle-ui/theme
-# or
-bun add @puzzle-ui/theme
-# or
-pnpm add @puzzle-ui/theme
-# or
-yarn add @puzzle-ui/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.
+
+## Prerequisites
+
+- 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.
+
+## Set up a new project
+
+Simple run our @puzzle-ui/create project template to get started.
+
+npm:
+
+```bash
+npx @puzzle-ui/create
 ```
 
-Requires React and React DOM 19 (`^19.0.0`) and a CSS-aware application
-bundler. Styles are imported by the package; no separate stylesheet or
-Tailwind setup is required.
+bun:
 
-## Usage
+```bash
+bunx @puzzle-ui/create
+```
 
-```tsx
-import { Theme } from "@puzzle-ui/theme";
+Puzzle can set up a new project for you with the following framework options:
 
-export const App = () => (
-  <Theme
-    theme="system"
-    tokens={{ radius: { md: "0.5rem" } }}
-  >
-    <main>Your application</main>
-  </Theme>
-);
+- Basic React app
+- Tanstack start
+- Next.js
+
+Furthermore you can choose to install tailwindcss or not.
+It directly installs all dependencies and sets up the project for you.
+
+## Set up in an existing project:
+
+Install the UI library and theme package in your application's directory. Choose your package manager below:
+
+npm:
+
+```bash
+npm install @puzzle-ui/ui --save
 ```
 
-Use one root theme for your application. By default it follows the system
-color scheme, emits `--puzzle-*` CSS custom properties, and applies global
-styles. Set `globalStyles={false}` to opt out of the global defaults.
-
-## Configuration
-
-| Prop | Purpose |
-| --- | --- |
-| `theme` | `"light"`, `"dark"`, or `"system"`; defaults to `"system"`. |
-| `scope` | `"root"` for document-wide styling or `"local"` for a subtree. |
-| `tokens` | Deep-partial overrides of color, typography, spacing, radius, layout, motion, and other design tokens. |
-| `colorTheme` | Select a built-in palette, such as `"cobalt-sky"`. |
-| `fonts` | Configure Google Fonts for heading, body, and accent roles. |
-| `components` | Override link and image rendering. |
-| `nonce` | CSP nonce for injected style elements. |
-
-Local themes do not apply global styles. Fonts configured through `fonts`
-load external Google Fonts stylesheets; omit this prop to avoid those
-requests.
-
-## Use tokens in your styles
-
-```css
-.panel {
-  color: var(--puzzle-color-text);
-  background: var(--puzzle-color-surface);
-  padding: var(--puzzle-space-4);
-  border-radius: var(--puzzle-radius-md);
-}
+bun:
+
+```bash
+bun add @puzzle-ui/create
 ```
 
-## Router integration
+pnpm:
 
-For routers whose links use `to`, configure the destination prop:
+```bash
+pnpm add @puzzle-ui/ui
+```
 
-```tsx
-import { Link } from "@tanstack/react-router";
+yarn:
 
-<Theme components={{ link: { component: Link, hrefProp: "to" } }}>
-  <AppContent />
-</Theme>;
+```bash
+yarn add @puzzle-ui/ui
 ```
 
-Components using `href` can be passed directly. Use `link: null` or
-`image: null` to restore native elements in a subtree.
+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.
 
-## Exports
+## Download fonts with the theme CLI
 
-The root exports `Theme`, `GoogleFont`, `createGoogleFontUrl`, `BREAKPOINTS`,
-and their configuration types. Context helpers are available through
-`@puzzle-ui/theme/components-context` and `@puzzle-ui/theme/scope-context`.
+The `@puzzle-ui/theme` package includes the `puzzle-theme` executable.
+It requires Node.js 20.19 or later.
 
-ESM and CommonJS builds with matching TypeScript declarations are included.
-CSS imports require a bundler rather than a bare Node.js runtime.
+```bash
+npm install @puzzle-ui/theme
+npm exec -- puzzle-theme --help
+```
 
-See the repository's [theme documentation](../../apps/site/content/docs/theme)
-for token references, fonts, colors, and component overrides.
+Create `puzzle-fonts.json` in your application's working directory:
 
-## Development
+```json
+{
+  "body": {
+    "family": "Inter",
+    "weights": [400, 700]
+  }
+}
+```
 
-```sh
-# From the repository root
-npm run build --workspace=@puzzle-ui/theme
+Download the fonts with either package manager:
 
-# From this package directory
-bun run vitest
+```bash
+npm exec -- puzzle-theme fonts download
+# Or, with the package installed using Bun:
+bun run puzzle-theme fonts download
 ```
 
-`prepack` rebuilds the package before packing or publishing. See the root
-[publishing guide](../../README.md#publishing-packages).
+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.
+
+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.
+
+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.
+
+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`.
+
+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.
 
-## License
+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.
 
-MIT. See [LICENSE](../../LICENSE); the published license is at `dist/LICENSE`.
+## Your first interface
+
+Import components from `"@puzzle-ui/ui` and wrap your application in `Theme` from `"@puzzle-ui/theme`:
+
+```tsx
+import { Theme } from "@puzzle-ui/theme";
+import { Button } from "@puzzle-ui/ui";
+
+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>
+);
+```

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",