@puzzle-ui/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.
- package/README.md +113 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# @puzzle-ui/theme
|
|
2
|
+
|
|
3
|
+
Puzzle's theme system: semantic design tokens, light/dark color schemes,
|
|
4
|
+
typography, Google Fonts, and configurable link and image components.
|
|
5
|
+
|
|
6
|
+
> Puzzle is under active development. APIs and framework compatibility may
|
|
7
|
+
> change; use it for experimentation and evaluation rather than production.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npm install @puzzle-ui/theme
|
|
13
|
+
# or
|
|
14
|
+
bun add @puzzle-ui/theme
|
|
15
|
+
# or
|
|
16
|
+
pnpm add @puzzle-ui/theme
|
|
17
|
+
# or
|
|
18
|
+
yarn add @puzzle-ui/theme
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Requires React and React DOM 19 (`^19.0.0`) and a CSS-aware application
|
|
22
|
+
bundler. Styles are imported by the package; no separate stylesheet or
|
|
23
|
+
Tailwind setup is required.
|
|
24
|
+
|
|
25
|
+
## Usage
|
|
26
|
+
|
|
27
|
+
```tsx
|
|
28
|
+
import { Theme } from "@puzzle-ui/theme";
|
|
29
|
+
|
|
30
|
+
export const App = () => (
|
|
31
|
+
<Theme
|
|
32
|
+
theme="system"
|
|
33
|
+
tokens={{ radius: { md: "0.5rem" } }}
|
|
34
|
+
>
|
|
35
|
+
<main>Your application</main>
|
|
36
|
+
</Theme>
|
|
37
|
+
);
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Use one root theme for your application. By default it follows the system
|
|
41
|
+
color scheme, emits `--puzzle-*` CSS custom properties, and applies global
|
|
42
|
+
styles. Set `globalStyles={false}` to opt out of the global defaults.
|
|
43
|
+
|
|
44
|
+
## Configuration
|
|
45
|
+
|
|
46
|
+
| Prop | Purpose |
|
|
47
|
+
| --- | --- |
|
|
48
|
+
| `theme` | `"light"`, `"dark"`, or `"system"`; defaults to `"system"`. |
|
|
49
|
+
| `scope` | `"root"` for document-wide styling or `"local"` for a subtree. |
|
|
50
|
+
| `tokens` | Deep-partial overrides of color, typography, spacing, radius, layout, motion, and other design tokens. |
|
|
51
|
+
| `colorTheme` | Select a built-in palette, such as `"cobalt-sky"`. |
|
|
52
|
+
| `fonts` | Configure Google Fonts for heading, body, and accent roles. |
|
|
53
|
+
| `components` | Override link and image rendering. |
|
|
54
|
+
| `nonce` | CSP nonce for injected style elements. |
|
|
55
|
+
|
|
56
|
+
Local themes do not apply global styles. Fonts configured through `fonts`
|
|
57
|
+
load external Google Fonts stylesheets; omit this prop to avoid those
|
|
58
|
+
requests.
|
|
59
|
+
|
|
60
|
+
## Use tokens in your styles
|
|
61
|
+
|
|
62
|
+
```css
|
|
63
|
+
.panel {
|
|
64
|
+
color: var(--puzzle-color-text);
|
|
65
|
+
background: var(--puzzle-color-surface);
|
|
66
|
+
padding: var(--puzzle-space-4);
|
|
67
|
+
border-radius: var(--puzzle-radius-md);
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Router integration
|
|
72
|
+
|
|
73
|
+
For routers whose links use `to`, configure the destination prop:
|
|
74
|
+
|
|
75
|
+
```tsx
|
|
76
|
+
import { Link } from "@tanstack/react-router";
|
|
77
|
+
|
|
78
|
+
<Theme components={{ link: { component: Link, hrefProp: "to" } }}>
|
|
79
|
+
<AppContent />
|
|
80
|
+
</Theme>;
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Components using `href` can be passed directly. Use `link: null` or
|
|
84
|
+
`image: null` to restore native elements in a subtree.
|
|
85
|
+
|
|
86
|
+
## Exports
|
|
87
|
+
|
|
88
|
+
The root exports `Theme`, `GoogleFont`, `createGoogleFontUrl`, `BREAKPOINTS`,
|
|
89
|
+
and their configuration types. Context helpers are available through
|
|
90
|
+
`@puzzle-ui/theme/components-context` and `@puzzle-ui/theme/scope-context`.
|
|
91
|
+
|
|
92
|
+
ESM and CommonJS builds with matching TypeScript declarations are included.
|
|
93
|
+
CSS imports require a bundler rather than a bare Node.js runtime.
|
|
94
|
+
|
|
95
|
+
See the repository's [theme documentation](../../apps/site/content/docs/theme)
|
|
96
|
+
for token references, fonts, colors, and component overrides.
|
|
97
|
+
|
|
98
|
+
## Development
|
|
99
|
+
|
|
100
|
+
```sh
|
|
101
|
+
# From the repository root
|
|
102
|
+
npm run build --workspace=@puzzle-ui/theme
|
|
103
|
+
|
|
104
|
+
# From this package directory
|
|
105
|
+
bun run vitest
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`prepack` rebuilds the package before packing or publishing. See the root
|
|
109
|
+
[publishing guide](../../README.md#publishing-packages).
|
|
110
|
+
|
|
111
|
+
## License
|
|
112
|
+
|
|
113
|
+
MIT. See [LICENSE](../../LICENSE); the published license is at `dist/LICENSE`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@puzzle-ui/theme",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Theme components for Puzzle",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"publishConfig": {
|
|
@@ -57,7 +57,7 @@
|
|
|
57
57
|
"prepack": "tsdown"
|
|
58
58
|
},
|
|
59
59
|
"dependencies": {
|
|
60
|
-
"@puzzle-ui/core": "^0.
|
|
60
|
+
"@puzzle-ui/core": "^0.2.0"
|
|
61
61
|
},
|
|
62
62
|
"peerDependencies": {
|
|
63
63
|
"react": "^19.0.0",
|