@alma-oss/spirit-design-tokes (英语)

精神设计系统的设计标志.

精神设计标志 与和生成 超级新星. . . . . . !

目录

1. 可用设计键
   1. 全球键
   2. 主题键
2. 主题
3. 安装
4. 基本用途
   1. 在萨斯
   2. 在 Java 脚本中
5. 单位 - rem
6. 重塑精神
   1. 使用带有类型脚本的设计套件
7. 财务问题
8. 许可证

可用设计键

技术上,设计代币被分为两类:全球代币和主题代币. 全球地标在主题上独立共享,而主题地标则针对特定主题.

他们都由我们管理 图片 并出口到我们 超新星工作空间。 。 。 .

所有内容在 src 是由超新星生成的,不应手动编辑.

这个 scss 目录包含 @tokens.scss 连接所有可用的符号(包括全局和主题符号).

全球键

这一类别包括:

• ++ 边框
• 渐变
• 其他情况
• 🎱(Radii)
• * 阴影
• * 间距
• * 类型

这些纪念物是在全球范围内独立分享的.

主题键

目前,QQ色彩组中只有符号可以被主题使用.

主题

您可以在 @themes 文档中 scss/themes 目录. 每个主题都有自己的目录,有同一套设计符号,但有不同的值.

目前,我们支持两个光模式色彩主题:

• 光默认( 先在 @themes,即默认主题)
• 点亮品牌

这两个主题都可以在同一页的任何地方使用,并根据需要合并.

使用主题

这个 scss 目录包含 @themes.scss 将所有可用的主题作为 Sass 变量链接. 从技术角度看,主题词是基于CSS变量. 然而,这个一揽子 目前不直接提供 CSS 变量. 相反,它们产生于 页:1 @themes 文档中 spirit-web 软件包.

安装

🙋🏻‍♂️ 坚持住! 您已经使用 spirit-web? 吗? 那你就不用这样了 安装此软件包是因为 spirit-design-tokens 自动安装 a. 附属公司 spirit-web。 。 。 .

如果你想使用刚刚 spirit-design-tokens 单枪匹马地跑

yarn add @alma-oss/spirit-design-tokens

或者说

npm install --save @alma-oss/spirit-design-tokens

基本用途

在萨斯

萨斯语(有SCSS语法)是用于造型"精神"组件的主要语言.

使用设计符号的最好方法是在萨斯装入他们的路径:

sass --load-path=node_modules/@alma-oss/spirit-design-tokens/scss my-styles.scss

或者把它们融入你的建筑系统:

// vite.config.js

// …
import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        includePaths: [path.resolve(__dirname, 'node_modules/@alma-oss/spirit-design-tokens/scss')],
      },
    },
  },
});
// …

// webpack.config.js

// …
module: {
  rules: [
    {
      test: /\.scss$/,
      use: [
        'style-loader',
        'css-loader',
        {
          loader: 'sass-loader',
          options: {
            sassOptions: {
              includePaths: [
                path.resolve(__dirname, 'node_modules'),
                path.resolve(__dirname, 'node_modules/@alma-oss/spirit-design-tokens/scss'),
              ],
            },
          },
        },
      ],
    },
  ];
}
// …

使用 sass-embedded 图书馆

如果你在用的话 sass-embedded,您可以指定 API 为 legacy, (中文(简体) ), modern,或 modern-compiler。更多信息可在 粗略文档。 。 。 .

我们建议使用 modern-compiler 选项. 请注意,这一变化还需要更新 includePaths 改为 loadPaths。 。 。 .

// webpack.config.js

// …
module: {
  rules: [
    {
      test: /\.scss$/,
      use: [
        'style-loader',
        'css-loader',
        {
          loader: 'sass-loader',
          options: {
            api: 'modern-compiler',
            sassOptions: {
              loadPaths: [
                path.resolve(__dirname, 'node_modules'),
                path.resolve(__dirname, 'node_modules/@alma-oss/spirit-design-tokens/scss'),
              ],
            },
          },
        },
      ],
    },
  ];
}
// …

这个 spirit-web 软件包或您自己的组件可以简单地达到这样的符号值:

@use 'sass:map';
@use '@tokens' as tokens;

.MyComponentThatMightGoToSpiritInFuture {
  margin-bottom: tokens.$space-300;
  font-family: map.get(tokens.$body-medium-regular, mobile, font-family);
  color: tokens.$text-primary;
}

对于您的组件, 您也可以直接装入符号文件 :

@use 'node_modules/@alma-oss/spirit-design-tokens/scss/@tokens' as tokens;

在 Java 脚本中

此外,设计符号也作为JavaScript对象提供.

import * as SpiritDesignTokens from '@alma-oss/spirit-design-tokens';

const desktopBreakpoint = SpiritDesignTokens.breakpoints.desktop;

其结构与萨斯语相同.

单位 - rem

所有数字"灵"设计符号(相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相相去相去相去相去相去相去相去相去相去相去相去相去相去相 rem 单位 相对于根字体大小,默认为 16 个 px。 。 。 .

import { space700, space1000 } from '@alma-oss/spirit-design-tokens';

console.log(space700); // → '1rem'  (= 16 px at default root size)
console.log(space1000); // → '2rem'  (= 32 px at default root size)

@use '@tokens' as tokens;

.MyComponent {
  margin-bottom: tokens.$space-700; // → 1rem
}

每个设备在 fontSizeBaseMobile, (中文(简体) ), fontSizeBaseTablet,以及 fontSizeBaseDesktop (所有项目) 16px (默认情况下). 如果你改变了你的 项目的根字体大小, 全部 rem 符号值将相应缩放——这是故意的 并保持布局与用户字体大小偏好的比例.

充分解释转换如何运作以及精神中有哪些公用事业可用 软件包,参见 单位指南。 。 。 .

重塑精神

该系统的设计容易被重新命名. 为此,你需要提供 您自己的设计标志和使用 @tokens 财务报告和审定财务报表 @themes 文档。 然后把信物转过来 并设置 正确的加载路径 你的项目.

您的标志应该包含 与精神标志相同的结构。 最简单的 这样做的方法是在您的 Figma 文件里有相同的结构并导出它 使用超新星. 如果不可能的话,你可以复制我们的代币并调整其价值 满足你的需求。 也可以添加您设计系统所需的新标志.

使用带有类型脚本的设计套件

如果您想要使用自己的一组设计符号, 而不是由 @alma-oss/spirit-design-tokens, (中文(简体) ), 您需要调整您的项目的 TypeScript 配置和构建系统设置,以正确解决导入问题.

添加以下路径到您的 tsconfig.json数字 :

{
  "compilerOptions": {
    "paths": {
      "@alma-oss/spirit-design-tokens": ["path-to-your-design-tokens-directory-or-package/js"],
      "@alma-oss/spirit-design-tokens/*": ["path-to-your-design-tokens-directory-or-package/*"]
    }
  }
}

然后,调整您的构建系统设置,以正确解决导入问题. 下面可以看到不同构建系统的例子:

import path from 'path';

export default config({
  resolve: {
    alias: {
      '@alma-oss/spirit-design-tokens': path.resolve(__dirname, 'path-to-your-design-tokens-directory-or-package'),
    },
  },
});

import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@alma-oss/spirit-design-tokens': path.resolve(__dirname, 'path-to-your-design-tokens-directory-or-package'),
    },
  },
});

import type, { NextConfig } from "next";
import path, {dirname} from "path";
import { fileURLToPath } from "url";

const pathDir = dirname(fileURLToPath(import.meta.url));

const nextConfig: NextConfig = {
  transpilePackages: ['@alma-oss/spirit-web-react'],
  reactStrictMode: true,
  sassOptions: {
    implementation: 'sass-embedded',
    includePaths: [
      path.join(pathDir, './node_modules'),
      path.join(pathDir, 'path-to-your-design-tokens-directory-or-package/scss'),
    ],
  },
  webpack: (config) => {
    config.resolve.alias['@alma-oss/spirit-design-tokens'] = path.resolve('path-to-your-design-tokens-directory-or-package');
    return config;
  },
};

export default nextConfig;

组件半径覆盖

要覆盖所有大小的组件默认半径, 请使用此模式在设备收藏中添加一个符号 : device/<component-name>/radius。 。 。 .

要覆盖一个组件大小, 使用 : device/<component-name>/<size>/radius。 。 。 .

例如:

device/tag/radius
device/tag/xsmall/radius

每个令牌槽必须提供移动,平板和桌面模式. 当一个槽不完整时 Sass 编译失败 。 当两者 槽存在,大小特有半径优先于组件级半径. 组件默认半径 当两个槽都不存在时,仍然是倒数.

半径 CSS 仅为存在的符号槽生成. 按键和窗体字段大小槽包含在默认的精神中 符号,所以其半径CSS总是生成.

只有主表面半径受到影响。 特别是"神通"(Avatar sord)只适用于方形"神通". 纸牌 适用于盒式卡片和 CardMedia 每张卡上都有. device/skeleton/radius 适用于文本、标题和 形状骨架; --spirit-skeleton-shape-radius 仍然在形状上覆盖设备符号 。 组件名称通常 符合他们的CSS课程。 以下符号使用公共组件名来代替拥有地表的类:

• device/dropdown/radius 适用于 DropdownPopover· ;
• device/form-field/<size>/radius 适用于 InputContainer· ;
• device/form-field/medium/radius 也适用于 FileUploadInput__dropZone· ;
• device/modal/radius 适用于 ModalDialog· ;
• device/toast/radius 适用于 ToastBar· ;
• device/tooltip/radius 适用于 TooltipPopover。 。 。 .

在互动面上测试极端自定义辐射,以确保焦点指标和内容不被视觉剪接.

组件颜色覆盖

关于彩色方案如何运作以及这些套接字在哪些地方适合,请参见 颜色方案 向导.

要覆盖组件的默认颜色方案,您可以使用以下模式添加符号: component-<component-name>-<token-name>-<suffix>。 。 。 .

例如,要覆盖默认的微妙颜色 Pill 联合国 emotion-success 颜色,您可以添加以下符号:

component/pill/emotion-success-content-subtle

或更改 emotion-success (不是微妙的)变体完全,你可以添加以下符号:

component/pill/emotion-success-background-basic
component/pill/emotion-success-content-subtle

这些符号是可选的,它们为组件生成了新的类.

财务问题

Error: Invalid Sass identifier "@tokens"
  ╷
1 │ @use '@tokens';
  │ ^^^^^^^^^^^^^^

// _Button.scss

@use 'tools'; // Calls './_tools.scss'. You don't have to explain this to me.
@use 'tokens'; // Wait, this file doesn't exist… What's going on here? Is it
// an error?

// _Button.scss

@use 'tools'; // Calls './_tools.scss'.
@use '@tokens' as tokens; // OK, './[email protected]' is not here, but the at-sign
// prefix suggests a special behavior. Maybe I'll learn more in the docs?

许可证

见 自由主义 文档供参考.