@ reconsight-hub/ 设计托克

Gainsight Community Hub的设计符——CSS自定义属性,TypeScript常数,JSON,和一个Tailwind v4主题.

安装

npm install @gainsight-hub/design-tokens

这个软件包 无运行时间依赖关系 并自行工作: 平面 CSS 应用和 SCSS 应用 (例如服务器的 Preact 目的地) 只安装此软件包并导入 styles.css 和一个主题. tailwindcss (QQ 3) 是可选的对等点, 仅供 Tailwind 使用 预设。 安装 @gainsight-hub/design-system 或者说 @gainsight-hub/theme-editor 如果你需要的话 反应组件或主题编辑器 UI; 两者都依赖于此软件包, 所以拥有此软件的应用程序 符号也拥有其版本.

快开始

导入 styles.css 一次在你的应用程序入口。 大部分应用都这样.

// main.js / main.ts
import "@gainsight-hub/design-tokens/styles.css";

然后通过 CSS 自定义属性在任何地方使用符号 :

.button {
  background: var(--color-action-primary-default);
  color: var(--color-content-inverse);
  border-radius: var(--button-radius);
}

CSS 自定义属性

基础( 轻主题)

定义所有符号为 CSS 自定义属性 :root。这是默认的光线主题.

import "@gainsight-hub/design-tokens/styles.css";

所有主题已捆绑

包含一个文件中的基础符号加上所有主题覆盖 。 如果您想要在运行时切换主题而不装入额外的样式表, 请使用此选项 .

import "@gainsight-hub/design-tokens/themes.css";

个别主题

只装入您需要的主题 styles.css数字 :

import "@gainsight-hub/design-tokens/styles.css";
import "@gainsight-hub/design-tokens/themes/ocean.css";

现有主题——每艘船舶都有一个轻质块([data-theme="{name}"])和a 数据 暗块( e)[data-theme="{name}"].dark页:1 legacy,它只是轻 (这是移民前的搭桥——见下文):

基本主题本身的暗模式不需要额外导入 styles.css作为 :where(:root:not([data-theme])).dark 挡住灯光 :root 缺省数(:where() 保持与光块相同的特异性,因此运行时的覆盖仍然取胜.

运行时主题切换

data-theme 总是持有所选主题的 id( 或为 默认主题); .dark 是一种独立、添加剂的暗模式类—— 永远不是值 data-theme 它本身需要。 都活下来了 document.documentElement。 。 。 .

/* A named theme, dark mode: */
/* (written :where([data-theme="ocean"]).dark in the generated files) */
[data-theme="ocean"].dark { /* ... */ }

/* The default theme, dark mode (no data-theme attribute): */
:root.dark { /* ... (generated as :where(:root:not([data-theme])).dark) */ }

/* Scope to a tenant / white-label */
[data-tenant="acme"] {
  --color-action-primary-default: #e63946;
  --button-primary-background-color-default: #e63946;
}

脚本命名

名称是公共合同:重命名是针对主题覆盖和客户风格的突破性更改.

组件符号规则 :

• 命名 CSS 属性, 最后状态 . 颜色表示哪个颜色 : background-color, (中文(简体) ), border-color, (中文(简体) ), content-color (文字和图标), title-color, (中文(简体) ), subtitle-color, (中文(简体) ), icon-color,以及 border-top-color 编号 : border-bottom-color 对于单边. --button-primary-background-color-hover, (中文(简体) ), --sidebar-border-color-default. 国家(default, (中文(简体) ), hover, (中文(简体) ), pressed)总是最后一句话.
• 为什么 -color数字 : 一个赤 background 或者说 border 可以是颜色、图像或宽度. --widget-hero-background-image 这是一个图像, --sidebar-border-width 是一个宽度, --sidebar-border-color-default 是一种颜色.
• 其他属性保留自己的单词 : border-width, (中文(简体) ), radius, (中文(简体) ), shadow, (中文(简体) ), font-family, (中文(简体) ), font-weight, (中文(简体) ), text-transform, (中文(简体) ), height。具有单一价值的财产不需要状态后缀(--sidebar-radius) (中文(简体) ).
• 一个变体是名称的一部分,而不是状态: --button-vote-selected-background-color-default 是投票按钮的"投票"变体,它本身默认,徘徊并按下状态.
• 命名空间 : sidebar 是一个内容区域部件, sidenav 是应用程序壳侧导航,以及 navigation 是顶端的栏杆及其下垂.

值得了解的天平 :

• 阿尔法: --color-neutral-a100 改为 a500 中性 1000 在 4, 8, 16, 32 和 48% 不透明 .
• 行高 : --line-height-ratio-* 无单位倍数(头部使用紧凑,身体和代码使用放松); --line-height-grid-* 是4px网格(标签、标题、菜单、导航、按钮)上固定的还原值.
• --font-size-base 这是故意的。 它是每个 rem 步骤产生的根大小,主题编辑器的文本大小设置会写出它.

CSS 注释和 token-catalog.json。 。 。 .

类型脚本 / Java 脚本

直接导入已键入的符数常数 。 所有出口都通过捆绑输入 tokens.d.ts。 。 。 .

import {
  ColorActionPrimaryDefault,
  ColorSurfacePage,
  RadiusFull,
} from "@gainsight-hub/design-tokens";

// Use in JS logic — e.g. canvas drawing, charting libs
ctx.fillStyle = ColorActionPrimaryDefault; // "#0C66E4"

尾风 v4

只有尾风v4。 在您的 CSS 条目中先导入变量, 然后导入主题文件 :

@import "tailwindcss";
@import "@gainsight-hub/design-tokens/styles.css";        /* defines the CSS custom properties */
@import "@gainsight-hub/design-tokens/tailwind-theme.css"; /* maps them to Tailwind utilities */

tailwind-theme.css 是一个 @theme inline 块,每个条目都是 var(--token) 引用,所以没有重复值。 在任何范围内更改一个符号(例如带有一个主题),以及每一个使用它更新的效用,没有重建.

<!-- Colours: the full token name, including -default -->
<div class="bg-action-primary-default text-content-inverse">Primary</div>
<div class="bg-surface-default text-content-default border border-line-default">Card</div>

<!-- Spacing, radius, elevation -->
<div class="p-space-200 gap-space-100 rounded-100 shadow-elevation-1">Layout</div>

<!-- Type styles: one class sets size, line height and weight -->
<h2 class="text-heading-small">Heading</h2>
<p class="font-sans text-body-medium">Body text</p>

库存规模公用事业rounded-md, (中文(简体) ), text-sm, (中文(简体) ), p-3, (中文(简体) ), shadow-lg)也与符相接,因此一个主题可以改变形状,密度和高地.

组件符号( CSS 模块)

对于组件内部,使用CSS模块,其中 var() 直接 :

/* Button.module.css */
.root {
  background: var(--button-primary-background-color-default);
  color: var(--button-primary-label-default);
  border-radius: var(--button-radius);
  padding: var(--space-100) var(--space-200);
}

.root:hover {
  background: var(--button-primary-background-color-hover);
}

// Button.tsx
import styles from "./Button.module.css";

export function Button({ children }: { children: React.ReactNode }) {
  return <button className={styles.root}>{children}</button>;
}

贾森

原始符号值作为嵌入的 JSON 值 。 用于工具化,构建脚本,或非网络目标(如React Introduct,Figma插件).

import tokens from "@gainsight-hub/design-tokens/tokens.json" with { type: "json" };

const primary = tokens.color.action.primary.default.value; // "#0C66E4"
const gutter = tokens.space.layout.gutter.value;            // "12px"

托肯目录

结构化目录,包含已解析的值,描述,别名链条,以及遗留的映射. 被设计门户和设计工具使用.

import catalog from "@gainsight-hub/design-tokens/token-catalog.json" with { type: "json" };

// 224 tokens with cssVar, path, type, value, description, references, legacyMapping
catalog.all.forEach(token => console.log(token.cssVar, token.value));

运行时主题切换

applyThemeConfig(config, mode) 应用已保存 ThemeConfig (主题 id + 任意) 每款模式覆盖)到当前页面——同步,不重装页面. 它设置 data-theme 改为真实的主题 id(或为默认主题删除)和 切换 .dark 独立类 mode,然后插入主题的 自己的变量加上任何作为 CSS 自定义属性的覆盖 .

要求主题的自有CSS已经装入(例如. themes.css,或 具体 themes/{name}.css )——此函数只管理 data-theme编号 :.dark 和上层配置级别覆盖; 它不获取 样式表.

import "@gainsight-hub/design-tokens/themes.css"; // base + all themes
import { applyThemeConfig } from "@gainsight-hub/design-tokens";

// Switch to Ocean, light mode
applyThemeConfig({ themeId: "ocean", overrides: { light: {}, dark: {} } }, "light");

// Same theme, dark mode
applyThemeConfig({ themeId: "ocean", overrides: { light: {}, dark: {} } }, "dark");

// Default theme + a custom brand color override
applyThemeConfig(
  { themeId: "gainsight-light", overrides: { light: { "--theme-brand-700": "#FF6600" }, dark: {} } },
  "light",
);

可用的主题ID : gainsight-light (违约), ocean, (中文(简体) ), ember, (中文(简体) ), meadow, (中文(简体) ), violet, (中文(简体) ), slate, (中文(简体) ), legacy。 。 。 .

可用出口

软件包结构

packages/design-tokens/
├── src/                   Token source files (Style Dictionary format)
│   ├── primitive/         Raw scales — color, space, radius, font, shadow
│   ├── semantic/          Semantic roles — action, surface, content, line, status
│   └── component/         Component tokens — button, card, feed, navigation, widget
├── config/                Style Dictionary config and custom formats
│   └── themes/            Theme override definitions
├── migration/             Legacy variable mapping tools
├── build.js               Build entry point
└── dist/                  Published output (generated, do not edit)
    ├── index.js            Root entry — applyThemeConfig + token constants
    ├── index.d.ts          TypeScript declarations for root entry
    ├── applyTheme.js       Runtime theme switcher (lazy CSS loading)
    ├── applyTheme.d.ts     TypeScript declarations for applyThemeConfig
    ├── tokens.js           JS named constants
    ├── tokens.d.ts         TypeScript declarations for token constants
    ├── styles.css          CSS custom properties (base light theme)
    ├── themes.css          All themes combined (styles.css + all theme overrides)
    ├── tokens.json         Nested JSON
    ├── token-catalog.json  Full token catalog
    ├── tailwind-theme.css    Tailwind v4 theme mapping
    └── themes/             Individual theme CSS files

建筑和出版

# Build from the monorepo root
turbo run build --filter=@gainsight-hub/design-tokens

# Publish
npm publish --access public -w packages/design-tokens