@synapsly/tokens 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 (18) hide show
  1. package/README.md +94 -0
  2. package/README.zh-CN.md +94 -0
  3. package/dist/css-vars.css +495 -0
  4. package/dist/cssVars-edTn7tOU.d.cts +1494 -0
  5. package/dist/cssVars-edTn7tOU.d.ts +1494 -0
  6. package/dist/cssVars.cjs +963 -0
  7. package/dist/cssVars.cjs.map +1 -0
  8. package/dist/cssVars.d.cts +1 -0
  9. package/dist/cssVars.d.ts +1 -0
  10. package/dist/cssVars.js +951 -0
  11. package/dist/cssVars.js.map +1 -0
  12. package/dist/index.cjs +150 -47
  13. package/dist/index.cjs.map +1 -1
  14. package/dist/index.d.cts +6 -676
  15. package/dist/index.d.ts +6 -676
  16. package/dist/index.js +141 -48
  17. package/dist/index.js.map +1 -1
  18. package/package.json +10 -2
package/README.md CHANGED
@@ -45,6 +45,54 @@ export const page = style({
45
45
  });
46
46
  ```
47
47
 
48
+ ## Use Stable CSS Variables
49
+
50
+ Import the stable CSS variable layer when the host app uses plain CSS, Tailwind, CSS Modules, or a non-vanilla-extract styling stack.
51
+
52
+ ```ts
53
+ import "@synapsly/tokens/css-vars.css";
54
+ import { themeNames } from "@synapsly/tokens";
55
+
56
+ <html data-theme={themeNames.light} />;
57
+ ```
58
+
59
+ The exported variables use readable names derived from the semantic token paths:
60
+
61
+ ```css
62
+ .page {
63
+ background: var(--synapsly-color-bg-canvas);
64
+ color: var(--synapsly-color-fg-primary);
65
+ }
66
+
67
+ .primaryButton {
68
+ background: var(--synapsly-color-action-primary-bg);
69
+ color: var(--synapsly-color-action-primary-fg);
70
+ }
71
+ ```
72
+
73
+ The same references are also available as a typed object for Tailwind config or CSS-in-JS systems that accept raw CSS variable strings:
74
+
75
+ ```ts
76
+ import { cssVars } from "@synapsly/tokens/css-vars";
77
+
78
+ export default {
79
+ theme: {
80
+ extend: {
81
+ colors: {
82
+ canvas: cssVars.color.bg.canvas,
83
+ primary: {
84
+ bg: cssVars.color.action.primary.bg,
85
+ fg: cssVars.color.action.primary.fg
86
+ }
87
+ },
88
+ borderRadius: {
89
+ md: cssVars.radius.md
90
+ }
91
+ }
92
+ }
93
+ };
94
+ ```
95
+
48
96
  ## Override Semantic Tokens
49
97
 
50
98
  Project themes override semantic decisions only. Primitive tokens remain fixed. Create custom themes in a vanilla-extract file such as `theme.css.ts`.
@@ -134,17 +182,60 @@ export const brandTheme = createTheme({
134
182
  });
135
183
  ```
136
184
 
185
+ ## Create CSS Variable Themes
186
+
187
+ CSS variable themes keep the same single semantic source of truth. Use resolved semantic tokens and concrete primitive values, then optionally replace only the semantic decisions that differ.
188
+
189
+ ```ts
190
+ // build-theme.ts
191
+ import { createCssTheme, primitiveTokens } from "@synapsly/tokens/css-vars";
192
+
193
+ export const brandCssTheme = createCssTheme({
194
+ name: "brand",
195
+ overrides: {
196
+ color: {
197
+ action: {
198
+ primary: {
199
+ bg: primitiveTokens.color.green[600],
200
+ bgHover: primitiveTokens.color.green[700],
201
+ bgActive: primitiveTokens.color.green[800],
202
+ border: primitiveTokens.color.green[600]
203
+ }
204
+ }
205
+ }
206
+ }
207
+ });
208
+
209
+ // Write brandCssTheme.cssText into an app stylesheet or inject it in a build step.
210
+ ```
211
+
212
+ Then switch themes with the same `data-theme` attribute:
213
+
214
+ ```tsx
215
+ <html data-theme={brandCssTheme.name} />
216
+ ```
217
+
137
218
  ## API
138
219
 
139
220
  - `primitiveTokens`: fixed primitive token values as a TypeScript object.
140
221
  - `primitiveVars`: fixed primitive CSS variable references.
141
222
  - `vars`: semantic CSS variable references for components and product styles.
142
223
  - `semanticVars`: alias of `vars`.
224
+ - `cssVars`: stable semantic CSS variable references such as `var(--synapsly-color-bg-canvas)`.
225
+ - `cssVarPrefix`: CSS variable prefix, currently `synapsly`.
226
+ - `defaultResolvedLightCssTokens`: light semantic values resolved to concrete primitive values for CSS variable generation.
227
+ - `defaultResolvedDarkCssTokens`: dark semantic values resolved to concrete primitive values for CSS variable generation.
228
+ - `defaultResolvedCssTokens`: alias of `defaultResolvedLightCssTokens`.
143
229
  - `themeNames`: built-in theme names, currently `light` and `dark`.
144
230
  - `themeAttribute`: the theme attribute name, currently `data-theme`.
145
231
  - `getThemeSelector(name)`: returns a selector such as `[data-theme="dark"]`.
146
232
  - `createTheme({ name, tokens?, overrides?, selector? })`: creates a named vanilla-extract theme with `data-theme` attributes and a compatibility class.
147
233
  - `createThemeTokens(base, overrides?)`: returns complete semantic tokens by deeply merging overrides into an existing semantic token object.
234
+ - `createCssTheme({ name, tokens?, overrides?, selector? })`: creates CSS text for a named stable CSS variable theme.
235
+ - `createCssThemeTokens(base, overrides?)`: CSS-variable-friendly alias of `createThemeTokens`.
236
+ - `createCssThemeRule(selector, tokens)`: serializes complete semantic tokens as a CSS rule.
237
+ - `createDefaultCssThemes()`: serializes the built-in light and dark stable CSS variable themes.
238
+ - `getCssVarName(path)`: converts a semantic token path to a stable CSS custom property name.
148
239
  - `defaultLightTheme`: named light theme definition.
149
240
  - `defaultDarkTheme`: named dark theme definition.
150
241
  - `defaultLightThemeClass`: reference light theme class.
@@ -191,6 +282,9 @@ Shadow uses a numeric elevation scale plus special-purpose values:
191
282
 
192
283
  ## JSON Exports
193
284
 
285
+ - `@synapsly/tokens/styles.css`: vanilla-extract default themes and internal runtime variables.
286
+ - `@synapsly/tokens/css-vars.css`: stable semantic CSS variables for plain CSS and Tailwind usage.
287
+ - `@synapsly/tokens/css-vars`: JavaScript helpers for stable CSS variable usage without importing the vanilla-extract theme entry.
194
288
  - `@synapsly/tokens/tokens.json`: publication snapshot with primitive and resolved semantic tokens.
195
289
  - `@synapsly/tokens/resolved.json`: same resolved publication snapshot.
196
290
  - `@synapsly/tokens/light.json`: light publication snapshot.
package/README.zh-CN.md CHANGED
@@ -45,6 +45,54 @@ export const page = style({
45
45
  });
46
46
  ```
47
47
 
48
+ ## 使用稳定 CSS 变量
49
+
50
+ 当宿主应用使用普通 CSS、Tailwind、CSS Modules 或非 vanilla-extract 样式栈时，导入稳定 CSS 变量层。
51
+
52
+ ```ts
53
+ import "@synapsly/tokens/css-vars.css";
54
+ import { themeNames } from "@synapsly/tokens";
55
+
56
+ <html data-theme={themeNames.light} />;
57
+ ```
58
+
59
+ 导出的变量名由 semantic token 路径生成，保持可读且稳定：
60
+
61
+ ```css
62
+ .page {
63
+ background: var(--synapsly-color-bg-canvas);
64
+ color: var(--synapsly-color-fg-primary);
65
+ }
66
+
67
+ .primaryButton {
68
+ background: var(--synapsly-color-action-primary-bg);
69
+ color: var(--synapsly-color-action-primary-fg);
70
+ }
71
+ ```
72
+
73
+ 同一组引用也会以类型化对象导出，适合 Tailwind config 或接受原始 CSS 变量字符串的 CSS-in-JS 系统：
74
+
75
+ ```ts
76
+ import { cssVars } from "@synapsly/tokens/css-vars";
77
+
78
+ export default {
79
+ theme: {
80
+ extend: {
81
+ colors: {
82
+ canvas: cssVars.color.bg.canvas,
83
+ primary: {
84
+ bg: cssVars.color.action.primary.bg,
85
+ fg: cssVars.color.action.primary.fg
86
+ }
87
+ },
88
+ borderRadius: {
89
+ md: cssVars.radius.md
90
+ }
91
+ }
92
+ }
93
+ };
94
+ ```
95
+
48
96
  ## 覆盖 Semantic Token
49
97
 
50
98
  项目主题只覆盖 semantic 决策。Primitive token 保持固定。在 `theme.css.ts` 这类 vanilla-extract 文件中创建自定义主题。
@@ -134,17 +182,60 @@ export const brandTheme = createTheme({
134
182
  });
135
183
  ```
136
184
 
185
+ ## 创建 CSS 变量主题
186
+
187
+ CSS 变量主题仍然保持同一个 semantic 真相源。使用已解析的 semantic tokens 和具体 primitive 值，再按需替换不同的 semantic 决策。
188
+
189
+ ```ts
190
+ // build-theme.ts
191
+ import { createCssTheme, primitiveTokens } from "@synapsly/tokens/css-vars";
192
+
193
+ export const brandCssTheme = createCssTheme({
194
+ name: "brand",
195
+ overrides: {
196
+ color: {
197
+ action: {
198
+ primary: {
199
+ bg: primitiveTokens.color.green[600],
200
+ bgHover: primitiveTokens.color.green[700],
201
+ bgActive: primitiveTokens.color.green[800],
202
+ border: primitiveTokens.color.green[600]
203
+ }
204
+ }
205
+ }
206
+ }
207
+ });
208
+
209
+ // 把 brandCssTheme.cssText 写入应用样式表，或在构建步骤中注入。
210
+ ```
211
+
212
+ 切换主题仍然使用同一个 `data-theme` 属性：
213
+
214
+ ```tsx
215
+ <html data-theme={brandCssTheme.name} />
216
+ ```
217
+
137
218
  ## API
138
219
 
139
220
  - `primitiveTokens`：固定 primitive token 值的 TypeScript 对象。
140
221
  - `primitiveVars`：固定 primitive CSS 变量引用。
141
222
  - `vars`：供组件和产品样式使用的 semantic CSS 变量引用。
142
223
  - `semanticVars`：`vars` 的别名。
224
+ - `cssVars`：稳定 semantic CSS 变量引用，例如 `var(--synapsly-color-bg-canvas)`。
225
+ - `cssVarPrefix`：CSS 变量前缀，目前是 `synapsly`。
226
+ - `defaultResolvedLightCssTokens`：为 CSS 变量生成准备的浅色 semantic 具体值。
227
+ - `defaultResolvedDarkCssTokens`：为 CSS 变量生成准备的深色 semantic 具体值。
228
+ - `defaultResolvedCssTokens`：`defaultResolvedLightCssTokens` 的别名。
143
229
  - `themeNames`：内置主题名，目前是 `light` 和 `dark`。
144
230
  - `themeAttribute`：主题属性名，目前是 `data-theme`。
145
231
  - `getThemeSelector(name)`：返回类似 `[data-theme="dark"]` 的选择器。
146
232
  - `createTheme({ name, tokens?, overrides?, selector? })`：用 `data-theme` 属性和兼容 class 创建命名 vanilla-extract 主题。
147
233
  - `createThemeTokens(base, overrides?)`：把 overrides 深合并到已有 semantic token 对象，返回完整 semantic tokens。
234
+ - `createCssTheme({ name, tokens?, overrides?, selector? })`：为命名稳定 CSS 变量主题创建 CSS 文本。
235
+ - `createCssThemeTokens(base, overrides?)`：适合 CSS 变量主题使用的 `createThemeTokens` 别名。
236
+ - `createCssThemeRule(selector, tokens)`：把完整 semantic tokens 序列化为 CSS rule。
237
+ - `createDefaultCssThemes()`：序列化内置浅色和深色稳定 CSS 变量主题。
238
+ - `getCssVarName(path)`：把 semantic token 路径转换为稳定 CSS 自定义属性名。
148
239
  - `defaultLightTheme`：命名浅色主题定义。
149
240
  - `defaultDarkTheme`：命名深色主题定义。
150
241
  - `defaultLightThemeClass`：参考浅色主题 class。
@@ -191,6 +282,9 @@ Shadow 使用数字 elevation 尺度和特殊用途值：
191
282
 
192
283
  ## JSON 导出
193
284
 
285
+ - `@synapsly/tokens/styles.css`：vanilla-extract 默认主题和内部运行时变量。
286
+ - `@synapsly/tokens/css-vars.css`：供普通 CSS 和 Tailwind 使用的稳定 semantic CSS 变量。
287
+ - `@synapsly/tokens/css-vars`：稳定 CSS 变量用法的 JavaScript helper，不导入 vanilla-extract 主题入口。
194
288
  - `@synapsly/tokens/tokens.json`：包含 primitive 和已解析 semantic tokens 的发布快照。
195
289
  - `@synapsly/tokens/resolved.json`：同样的已解析发布快照。
196
290
  - `@synapsly/tokens/light.json`：浅色发布快照。