npm - @synapsly/tokens - Versions diffs - 0.1.0 - Mend

@synapsly/tokens 0.1.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 (25) hide show

package/README.md +221 -0
package/README.zh-CN.md +221 -0
package/dist/dark.json +662 -0
package/dist/figma.dark.tokens.json +3088 -0
package/dist/figma.light.tokens.json +3088 -0
package/dist/figma.tokens.json +2886 -0
package/dist/index.cjs +1375 -0
package/dist/index.cjs.map +1 -0
package/dist/index.css +1220 -0
package/dist/index.css.map +1 -0
package/dist/index.d.cts +6674 -0
package/dist/index.d.ts +6674 -0
package/dist/index.js +1344 -0
package/dist/index.js.map +1 -0
package/dist/light.json +662 -0
package/dist/primitive.json +263 -0
package/dist/references.dark.json +662 -0
package/dist/references.json +662 -0
package/dist/references.light.json +662 -0
package/dist/resolved.json +662 -0
package/dist/semantic.dark.json +397 -0
package/dist/semantic.json +397 -0
package/dist/semantic.light.json +397 -0
package/dist/tokens.json +662 -0
package/package.json +55 -0

package/README.md ADDED Viewed

@@ -0,0 +1,221 @@
+# @synapsly/tokens
+[简体中文](./README.zh-CN.md)
+Company design tokens for Synapsly products.
+The package has two distinct layers:
+- `primitive`: fixed company materials. These are defined by this package and are not part of project theme overrides.
+- `semantic`: theme decisions grouped by usage, such as `color.bg.canvas`, `color.fg.primary`, and `color.action.primary.bg`.
+Components and product styles should prefer `vars`. Theme authors can point semantic values at `primitiveVars`.
+## Use the Default Themes
+```ts
+import "@synapsly/tokens/styles.css";
+import { themeNames } from "@synapsly/tokens";
+<html data-theme={themeNames.light} />
+```
+Dark theme uses the same attribute:
+```ts
+import "@synapsly/tokens/styles.css";
+import { themeNames } from "@synapsly/tokens";
+<html data-theme={themeNames.dark} />
+```
+Theme classes are also exported when a class-based host app needs them:
+```ts
+import { defaultDarkThemeClass, defaultLightThemeClass } from "@synapsly/tokens";
+```
+```ts
+import { style } from "@vanilla-extract/css";
+import { vars } from "@synapsly/tokens";
+export const page = style({
+  background: vars.color.bg.canvas,
+  color: vars.color.fg.primary
+});
+```
+## Override Semantic Tokens
+Project themes override semantic decisions only. Primitive tokens remain fixed. Create custom themes in a vanilla-extract file such as `theme.css.ts`.
+```ts
+// theme.css.ts
+import { createTheme, primitiveVars } from "@synapsly/tokens";
+export const appTheme = createTheme({
+  name: "acme",
+  overrides: {
+    color: {
+      action: {
+        primary: {
+          bg: primitiveVars.color.green[600],
+          bgHover: primitiveVars.color.green[700],
+          bgActive: primitiveVars.color.green[800]
+        }
+      }
+    }
+  }
+});
+```
+Attach the generated attributes in the app shell:
+```tsx
+import { appTheme } from "./theme.css";
+<html data-theme={appTheme.name} />;
+```
+Switching between multiple custom themes is just switching the theme name:
+```tsx
+import { useState } from "react";
+import { themeNames, type ThemeName } from "@synapsly/tokens";
+import { appTheme } from "./theme.css";
+type AppThemeName = ThemeName | typeof appTheme.name;
+export function AppShell({ children }: { children: React.ReactNode }) {
+  const [theme, setTheme] = useState<AppThemeName>(themeNames.light);
+  return (
+    <div data-theme={theme}>
+      <button onClick={() => setTheme(themeNames.light)}>Light</button>
+      <button onClick={() => setTheme(themeNames.dark)}>Dark</button>
+      <button onClick={() => setTheme(appTheme.name)}>Acme</button>
+      {children}
+    </div>
+  );
+}
+```
+## Derive from Existing Semantic Tokens
+Use `createThemeTokens` when a theme should build on another semantic theme before creating a class.
+```ts
+// theme.css.ts
+import {
+  createTheme,
+  createThemeTokens,
+  defaultSemanticTokens,
+  primitiveVars
+} from "@synapsly/tokens";
+const brandTokens = createThemeTokens(defaultSemanticTokens, {
+  color: {
+    fg: {
+      brand: primitiveVars.color.brand[700]
+    },
+    action: {
+      primary: {
+        bg: primitiveVars.color.brand[500],
+        bgHover: primitiveVars.color.brand[600],
+        bgActive: primitiveVars.color.brand[700]
+      }
+    }
+  }
+});
+export const brandTheme = createTheme({
+  name: "brand",
+  tokens: brandTokens
+});
+```
+## API
+- `primitiveTokens`: fixed primitive token values as a TypeScript object.
+- `primitiveVars`: fixed primitive CSS variable references.
+- `vars`: semantic CSS variable references for components and product styles.
+- `semanticVars`: alias of `vars`.
+- `themeNames`: built-in theme names, currently `light` and `dark`.
+- `themeAttribute`: the theme attribute name, currently `data-theme`.
+- `getThemeSelector(name)`: returns a selector such as `[data-theme="dark"]`.
+- `createTheme({ name, tokens?, overrides?, selector? })`: creates a named vanilla-extract theme with `data-theme` attributes and a compatibility class.
+- `createThemeTokens(base, overrides?)`: returns complete semantic tokens by deeply merging overrides into an existing semantic token object.
+- `defaultLightTheme`: named light theme definition.
+- `defaultDarkTheme`: named dark theme definition.
+- `defaultLightThemeClass`: reference light theme class.
+- `defaultDarkThemeClass`: reference dark theme class.
+- `defaultThemeClass`: alias of `defaultLightThemeClass`.
+- `defaultLightSemanticTokens`: default light semantic runtime tokens.
+- `defaultDarkSemanticTokens`: default dark semantic runtime tokens.
+- `defaultSemanticTokens`: alias of `defaultLightSemanticTokens`.
+- `defaultResolvedLightSemanticTokens`: light semantic values resolved to concrete primitive values.
+- `defaultResolvedDarkSemanticTokens`: dark semantic values resolved to concrete primitive values.
+- `defaultResolvedSemanticTokens`: alias of `defaultResolvedLightSemanticTokens`.
+- `defaultLightTokens`: publication snapshot for light.
+- `defaultDarkTokens`: publication snapshot for dark.
+- `defaultTokens`: alias of `defaultLightTokens`.
+- `defaultLightTokenReferences`: primitive values plus light semantic reference strings.
+- `defaultDarkTokenReferences`: primitive values plus dark semantic reference strings.
+- `defaultTokenReferences`: alias of `defaultLightTokenReferences`.
+- `SemanticTokens`: complete semantic token value type.
+- `SemanticTokenOverrides`: partial semantic token override type.
+## Semantic Coverage
+Semantic tokens cover foundation usage plus common product UI decisions:
+- `color.state`: shared interaction states such as hover, pressed, selected, focus, loading, visited, and readonly.
+- `color.form`: form control surfaces, borders, placeholder, caret, invalid, disabled, and readonly states.
+- `typography.text`: reusable text styles for display, headings, body, labels, captions, and code.
+- `size.control` and `size.iconButton`: standard interactive control heights.
+- `padding.control`, `gap`, and `layout`: control padding, common composition gaps, page gutters, containers, and sidebar widths.
+## Primitive Scales
+Spacing uses a 4px-based scale:
+```text
+0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24, 32, 64
+```
+Shadow uses a numeric elevation scale plus special-purpose values:
+```text
+0, 1, 2, 3, 4, 5, inner, focus
+```
+## JSON Exports
+- `@synapsly/tokens/tokens.json`: publication snapshot with primitive and resolved semantic tokens.
+- `@synapsly/tokens/resolved.json`: same resolved publication snapshot.
+- `@synapsly/tokens/light.json`: light publication snapshot.
+- `@synapsly/tokens/dark.json`: dark publication snapshot.
+- `@synapsly/tokens/primitive.json`: fixed primitive token values.
+- `@synapsly/tokens/semantic.json`: resolved default semantic token values.
+- `@synapsly/tokens/semantic.light.json`: resolved light semantic token values.
+- `@synapsly/tokens/semantic.dark.json`: resolved dark semantic token values.
+- `@synapsly/tokens/references.json`: default semantic references such as `{primitive.color.brand.500}`.
+- `@synapsly/tokens/references.light.json`: light semantic references.
+- `@synapsly/tokens/references.dark.json`: dark semantic references.
+## Figma Exports
+Two formats are emitted so teams can match their Figma workflow.
+- `@synapsly/tokens/figma.tokens.json`: [Tokens Studio for Figma](https://tokens.studio) format with `global`, `light`, and `dark` token sets. Import it through the Tokens Studio plugin and configure `light` and `dark` as two modes of one collection. Shadow and typography tokens are fully preserved.
+- `@synapsly/tokens/figma.light.tokens.json` and `@synapsly/tokens/figma.dark.tokens.json`: Figma-native DTCG (W3C) files for drag-and-drop import without a plugin. On a paid plan, drag both files into one new collection and Figma creates a mode per file. On the free plan (one mode per collection), import each file as its own collection. Only `color`, `dimension`, `fontFamily`, `duration`, `number`, and `string` tokens become variables; `shadow` and typography composite tokens are retained in the file but skipped by Figma's importer.
+Dimensions are emitted as `px` (with `1rem = 16px`), durations as `s`, and font families as a single name. See [Modes for variables](https://help.figma.com/hc/en-us/articles/15343816063383) for import details.
+## Versioning
+This package follows semver.
+- Patch: fix token values without changing meaning.
+- Minor: add new tokens or add non-breaking exports.
+- Major: remove, rename, or change the semantic meaning of an existing token.

package/README.zh-CN.md ADDED Viewed

@@ -0,0 +1,221 @@
+# @synapsly/tokens
+[English](./README.md)
+Synapsly 产品的公司级设计 token。
+这个包严格分为两层：
+- `primitive`：固定的公司设计材料。它们由本包定义，不可被项目主题覆盖。
+- `semantic`：按使用意图组织的主题决策，例如 `color.bg.canvas`、`color.fg.primary` 和 `color.action.primary.bg`。
+组件和产品样式应该优先使用 `vars`。主题作者可以把 semantic 值指向 `primitiveVars`。
+## 使用默认主题
+```ts
+import "@synapsly/tokens/styles.css";
+import { themeNames } from "@synapsly/tokens";
+<html data-theme={themeNames.light} />;
+```
+深色主题使用同一个属性：
+```ts
+import "@synapsly/tokens/styles.css";
+import { themeNames } from "@synapsly/tokens";
+<html data-theme={themeNames.dark} />;
+```
+当宿主应用需要 class 形式主题时，也可以使用导出的主题 class：
+```ts
+import { defaultDarkThemeClass, defaultLightThemeClass } from "@synapsly/tokens";
+```
+```ts
+import { style } from "@vanilla-extract/css";
+import { vars } from "@synapsly/tokens";
+export const page = style({
+  background: vars.color.bg.canvas,
+  color: vars.color.fg.primary
+});
+```
+## 覆盖 Semantic Token
+项目主题只覆盖 semantic 决策。Primitive token 保持固定。在 `theme.css.ts` 这类 vanilla-extract 文件中创建自定义主题。
+```ts
+// theme.css.ts
+import { createTheme, primitiveVars } from "@synapsly/tokens";
+export const appTheme = createTheme({
+  name: "acme",
+  overrides: {
+    color: {
+      action: {
+        primary: {
+          bg: primitiveVars.color.green[600],
+          bgHover: primitiveVars.color.green[700],
+          bgActive: primitiveVars.color.green[800]
+        }
+      }
+    }
+  }
+});
+```
+在应用壳层挂载生成的属性：
+```tsx
+import { appTheme } from "./theme.css";
+<html data-theme={appTheme.name} />;
+```
+在多个自定义主题之间切换时，只需要切换主题名：
+```tsx
+import { useState } from "react";
+import { themeNames, type ThemeName } from "@synapsly/tokens";
+import { appTheme } from "./theme.css";
+type AppThemeName = ThemeName | typeof appTheme.name;
+export function AppShell({ children }: { children: React.ReactNode }) {
+  const [theme, setTheme] = useState<AppThemeName>(themeNames.light);
+  return (
+    <div data-theme={theme}>
+      <button onClick={() => setTheme(themeNames.light)}>Light</button>
+      <button onClick={() => setTheme(themeNames.dark)}>Dark</button>
+      <button onClick={() => setTheme(appTheme.name)}>Acme</button>
+      {children}
+    </div>
+  );
+}
+```
+## 从现有 Semantic Token 派生
+当一个主题需要先基于已有 semantic 主题再创建 class 时，使用 `createThemeTokens`。
+```ts
+// theme.css.ts
+import {
+  createTheme,
+  createThemeTokens,
+  defaultSemanticTokens,
+  primitiveVars
+} from "@synapsly/tokens";
+const brandTokens = createThemeTokens(defaultSemanticTokens, {
+  color: {
+    fg: {
+      brand: primitiveVars.color.brand[700]
+    },
+    action: {
+      primary: {
+        bg: primitiveVars.color.brand[500],
+        bgHover: primitiveVars.color.brand[600],
+        bgActive: primitiveVars.color.brand[700]
+      }
+    }
+  }
+});
+export const brandTheme = createTheme({
+  name: "brand",
+  tokens: brandTokens
+});
+```
+## API
+- `primitiveTokens`：固定 primitive token 值的 TypeScript 对象。
+- `primitiveVars`：固定 primitive CSS 变量引用。
+- `vars`：供组件和产品样式使用的 semantic CSS 变量引用。
+- `semanticVars`：`vars` 的别名。
+- `themeNames`：内置主题名，目前是 `light` 和 `dark`。
+- `themeAttribute`：主题属性名，目前是 `data-theme`。
+- `getThemeSelector(name)`：返回类似 `[data-theme="dark"]` 的选择器。
+- `createTheme({ name, tokens?, overrides?, selector? })`：用 `data-theme` 属性和兼容 class 创建命名 vanilla-extract 主题。
+- `createThemeTokens(base, overrides?)`：把 overrides 深合并到已有 semantic token 对象，返回完整 semantic tokens。
+- `defaultLightTheme`：命名浅色主题定义。
+- `defaultDarkTheme`：命名深色主题定义。
+- `defaultLightThemeClass`：参考浅色主题 class。
+- `defaultDarkThemeClass`：参考深色主题 class。
+- `defaultThemeClass`：`defaultLightThemeClass` 的别名。
+- `defaultLightSemanticTokens`：默认浅色 semantic runtime tokens。
+- `defaultDarkSemanticTokens`：默认深色 semantic runtime tokens。
+- `defaultSemanticTokens`：`defaultLightSemanticTokens` 的别名。
+- `defaultResolvedLightSemanticTokens`：解析为具体 primitive 值的浅色 semantic 值。
+- `defaultResolvedDarkSemanticTokens`：解析为具体 primitive 值的深色 semantic 值。
+- `defaultResolvedSemanticTokens`：`defaultResolvedLightSemanticTokens` 的别名。
+- `defaultLightTokens`：浅色发布快照。
+- `defaultDarkTokens`：深色发布快照。
+- `defaultTokens`：`defaultLightTokens` 的别名。
+- `defaultLightTokenReferences`：primitive 值和浅色 semantic 引用字符串。
+- `defaultDarkTokenReferences`：primitive 值和深色 semantic 引用字符串。
+- `defaultTokenReferences`：`defaultLightTokenReferences` 的别名。
+- `SemanticTokens`：完整 semantic token 值类型。
+- `SemanticTokenOverrides`：局部 semantic token 覆盖类型。
+## Semantic 覆盖范围
+Semantic tokens 覆盖基础使用场景和常见产品 UI 决策：
+- `color.state`：hover、pressed、selected、focus、loading、visited、readonly 等共享交互状态。
+- `color.form`：表单控件表面、边框、placeholder、caret、invalid、disabled 和 readonly 状态。
+- `typography.text`：display、heading、body、label、caption 和 code 的可复用文本样式。
+- `size.control` 和 `size.iconButton`：标准交互控件高度。
+- `padding.control`、`gap` 和 `layout`：控件 padding、常用组合间距、页面 gutter、容器和侧边栏宽度。
+## Primitive 尺度
+Spacing 使用基于 4px 的尺度：
+```text
+0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24, 32, 64
+```
+Shadow 使用数字 elevation 尺度和特殊用途值：
+```text
+0, 1, 2, 3, 4, 5, inner, focus
+```
+## JSON 导出
+- `@synapsly/tokens/tokens.json`：包含 primitive 和已解析 semantic tokens 的发布快照。
+- `@synapsly/tokens/resolved.json`：同样的已解析发布快照。
+- `@synapsly/tokens/light.json`：浅色发布快照。
+- `@synapsly/tokens/dark.json`：深色发布快照。
+- `@synapsly/tokens/primitive.json`：固定 primitive token 值。
+- `@synapsly/tokens/semantic.json`：已解析的默认 semantic token 值。
+- `@synapsly/tokens/semantic.light.json`：已解析的浅色 semantic token 值。
+- `@synapsly/tokens/semantic.dark.json`：已解析的深色 semantic token 值。
+- `@synapsly/tokens/references.json`：默认 semantic 引用，例如 `{primitive.color.brand.500}`。
+- `@synapsly/tokens/references.light.json`：浅色 semantic 引用。
+- `@synapsly/tokens/references.dark.json`：深色 semantic 引用。
+## Figma 导出
+提供两种格式，团队可按自己的 Figma 工作流选择。
+- `@synapsly/tokens/figma.tokens.json`：[Tokens Studio for Figma](https://tokens.studio) 格式，含 `global`、`light`、`dark` 三个 token 集合。通过 Tokens Studio 插件导入，再把 `light` 和 `dark` 配为同一个集合的两个 mode。shadow 和 typography token 完整保留。
+- `@synapsly/tokens/figma.light.tokens.json` 与 `@synapsly/tokens/figma.dark.tokens.json`：Figma 原生 DTCG（W3C）格式，无需插件，直接拖入导入。付费版可把两个文件拖进同一个新集合，Figma 会为每个文件创建一个 mode。免费版每个集合只能有一个 mode，需把两个文件分别导入为各自的单 mode 集合。只有 `color`、`dimension`、`fontFamily`、`duration`、`number`、`string` 这几种 token 会成为变量；`shadow` 和 typography 复合 token 会保留在文件中，但被 Figma 导入器跳过。
+间距以 `px` 输出（按 `1rem = 16px` 换算），时长以 `s` 输出，字体族只取首个名字。导入机制参见 [Modes for variables](https://help.figma.com/hc/en-us/articles/15343816063383)。
+## 版本策略
+这个包遵循 semver。
+- Patch：修复 token 值，但不改变语义。
+- Minor：新增 token 或新增非破坏性导出。
+- Major：删除、重命名或改变已有 token 的 semantic 含义。