@simple-base/tokens 0.1.0 → 0.1.1

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 (2) hide show
  1. package/README.md +89 -14
  2. package/package.json +6 -1
package/README.md CHANGED
@@ -1,32 +1,107 @@
1
1
  # @simple-base/tokens
2
2
 
3
- Generated design tokens for Simple Base.
3
+ Design tokens for Simple Base: primitives, semantic roles, and nine color themes, generated with [Terrazzo](https://terrazzo.app/).
4
4
 
5
- ## JavaScript and TypeScript
5
+ Every token is emitted as a CSS custom property named `--sb-<token-path>`, and the full set is also available as JavaScript objects for tooling.
6
6
 
7
- Use the package root for the resolver and token types:
7
+ ## Install
8
8
 
9
- ```ts
10
- import { resolver, type Tokens } from "@simple-base/tokens";
11
-
12
- const tokens: Tokens = resolver.apply({ theme: "simple-base-dark" });
9
+ ```sh
10
+ pnpm add @simple-base/tokens
13
11
  ```
14
12
 
15
- ## Stylesheets
13
+ ## Quick start
16
14
 
17
- Import CSS custom properties through a CSS-aware bundler:
15
+ Load the token stylesheet once, before component or application styles:
18
16
 
19
17
  ```css
20
18
  @import "@simple-base/tokens/css";
21
19
  ```
22
20
 
23
- For Tailwind CSS v4 integration, use the generated theme instead. It includes
24
- Tailwind and the token stylesheet and requires Tailwind in the consuming project:
21
+ Then use the custom properties anywhere:
22
+
23
+ ```css
24
+ .panel {
25
+ background: var(--sb-semantic-color-background-surface);
26
+ color: var(--sb-semantic-color-foreground-primary);
27
+ border: 1px solid var(--sb-semantic-color-border-default);
28
+ border-radius: var(--sb-semantic-radius-md);
29
+ }
30
+ ```
31
+
32
+ ## Theming
33
+
34
+ `simple-base-dark` is the default and applies to `:root`. Every other theme activates through `data-theme`, on the document root or any nested element:
35
+
36
+ ```html
37
+ <html data-theme="nord"></html>
38
+ ```
39
+
40
+ | Theme | Color scheme |
41
+ | ---------------------- | ------------ |
42
+ | `simple-base-dark` | dark |
43
+ | `simple-base-light` | light |
44
+ | `catppuccin-latte` | light |
45
+ | `catppuccin-frappe` | dark |
46
+ | `catppuccin-macchiato` | dark |
47
+ | `catppuccin-mocha` | dark |
48
+ | `dracula` | dark |
49
+ | `tokyo-night` | dark |
50
+ | `nord` | dark |
51
+
52
+ Each theme is a scoped selector, so different regions of a page can use different themes. The matching `color-scheme` is set alongside the variables.
53
+
54
+ ## Tailwind CSS
55
+
56
+ For Tailwind CSS v4, use the generated theme instead of importing the token stylesheet directly. It imports Tailwind and the tokens, and maps the semantic roles onto Tailwind theme variables:
25
57
 
26
58
  ```css
27
59
  @import "@simple-base/tokens/tailwind";
28
60
  ```
29
61
 
30
- Utilities reference the same semantic CSS variables as the component styles, so
31
- `data-theme` works on the root or a nested region. Breakpoints are generated as
32
- literal dimensions because CSS media queries cannot resolve custom properties.
62
+ ```html
63
+ <div class="bg-background-surface text-foreground-primary rounded-md">…</div>
64
+ ```
65
+
66
+ Tailwind must be installed in the consuming project. Utilities resolve the same semantic CSS variables as the component styles, so they follow `data-theme` too. Each theme also gets a `@custom-variant` for conditional utilities:
67
+
68
+ ```html
69
+ <div class="nord:bg-background-raised">…</div>
70
+ ```
71
+
72
+ Breakpoints are generated as literal dimensions, because CSS media queries cannot resolve custom properties.
73
+
74
+ ## JavaScript and TypeScript
75
+
76
+ The package root exposes the token resolver and full token types:
77
+
78
+ ```ts
79
+ import { resolver, type Tokens } from "@simple-base/tokens";
80
+
81
+ const tokens: Tokens = resolver.apply({ theme: "dracula" });
82
+
83
+ tokens["semantic.color.foreground.primary"].$value;
84
+ ```
85
+
86
+ | Export | Description |
87
+ | ----------------------------- | -------------------------------------------------------------------------------- |
88
+ | `resolver.apply()` | Resolves a permutation (for example `{ theme: "nord" }`) and returns its tokens. |
89
+ | `resolver.listPermutations()` | Lists every available permutation. |
90
+ | `PERMUTATIONS` | All permutations keyed by their serialized input. |
91
+ | `Tokens` | Type of a resolved token set; individual value types are exported too. |
92
+
93
+ ## Reference
94
+
95
+ **Variable naming.** Dots in a token path become hyphens: `semantic.color.foreground.primary` becomes `--sb-semantic-color-foreground-primary`.
96
+
97
+ **Primitives versus semantic roles.** Primitive tokens such as `--sb-primitive-color-accent` are raw values. Semantic tokens name a purpose and are the stable public surface — prefer them in application and component styles, since a theme changes semantics rather than primitives.
98
+
99
+ ## Links
100
+
101
+ - [Repository](https://github.com/redasalmi/simple-base)
102
+ - [Styling layer](https://www.npmjs.com/package/@simple-base/css)
103
+ - [Solid components](https://www.npmjs.com/package/@simple-base/solid)
104
+
105
+ ## License
106
+
107
+ [MIT](https://github.com/redasalmi/simple-base/blob/main/LICENSE)
package/package.json CHANGED
@@ -1,7 +1,12 @@
1
1
  {
2
2
  "name": "@simple-base/tokens",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "license": "MIT",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/redasalmi/simple-base.git",
8
+ "directory": "packages/tokens"
9
+ },
5
10
  "files": [
6
11
  "dist"
7
12
  ],