@alma-oss/spirit-web

CSS实施精神设计系统.

安装

yarn add @alma-oss/spirit-web

或者说

npm install --save @alma-oss/spirit-web

使用量

快速启动 CSS

预建的Spirit CSS是小型一次性项目,原型和文档的绝佳选择.

在您的 HTML 模板中将完整、供应商前置和最小化的 CSS 与默认 Spirit 品牌链接 :

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/themes.min.css" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/foundation.min.css" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/components.min.css" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/helpers.min.css" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/utilities.min.css" />

QQ 或者,您可以使用 光盘N 当您不想安装任何 npm 包时链接.

他们

为使组件独立, 范围外观变化,"精神设计"系统使用主题. 你可以使用任何一个 提供的主题或 创建自己的。只需在基础 CSS 文件之前包含主题 CSS 文件. 鉴于命名公约 theme-<NAME OF THE THEME>,您可以在 HTML 的任意时间切换主题 :

<body class="text-primary bg-primary">
  <p>This paragraph uses the default light theme.</p>
  <section class="theme-light-on-brand bg-primary">
    <p class="text-primary">This paragraph uses the light theme on brand background.</p>
  </section>
</body>

颜色方案

灵灵 颜色方案 为: 语义表面 由设计符号建造。 他们和CSS不一样 color-scheme 属性 或 OS 轻/暗模式(prefers-color-scheme它们是Spirit自己在树下搭配前景、背景和边框的图案. 在实践中,这意味着您选择一个表层类,而Spirit为UI的这一部分保持文本,背景和边框颜色同步.

见 颜色方案 全图的指南——对齐逻辑,所有可用的方案,它们设置的CSS自定义属性,以及它们与主题和动态颜色的关系.

如何运作

1. 表面类 装入 color-scheme-on-<suffix> 容器(例如 color-scheme-on-neutral-basic, (中文(简体) ), color-scheme-on-emotion-success-basic, (中文(简体) ), color-scheme-on-accent-01-subtle,或 color-scheme-on-disabled) (中文(简体) ). 每组 当地 CSS 内容、边框和背景的自定义属性(带有 Spirit CSS 变量前缀, 例如 --spirit-local-color 财务报告和审定财务报表 --spirit-local-background-color。 。 。 .

   iQQ 每一个表层类也同时暴露出背景和内容颜色的强度,无论你选择哪一个变体 (单位:千美元)--spirit-local-background-color-basic, (中文(简体) ), --spirit-local-background-color-subtle, (中文(简体) ), --spirit-local-color-basic,以及 --spirit-local-color-subtle因此,一个 单表面类可以给结合它们的组件配色,例如带有基本颜色指示器的微妙表面. 对于 color-scheme-on-disabled,基本背景是被禁用的前景——坐落在被禁用地表上被填充元素的颜色——及其单色 内容颜色既是内容强度,又是内容强度.

2. 水电或部件 ——在同一元素上(或已经具有地表等级的祖先),使用读取这些本地人的公用事业: bg-color-scheme, (中文(简体) ), text-color-scheme,以及 border-color-scheme 所以背景、文字和边框 都放在纸盘上 而不列出每个符号 见 动态色彩帮助演示 用于实例. 或者直接在组件 CSS 类中读取颜色方案( 例如) Pill) (中文(简体) ).

3. 键 ——感官和情感计划遵循口音和情感键 spirit-design-tokens新的口音或情感 转换为附加符号 color-scheme-on-* 当主题构建时。 固定键等 neutral-*, (中文(简体) ), selected-*,以及 disabled 在同一个生成器中与它们并列定义.

高级产品执行

❗ 重要内容: 确保你有 sass 在您的工程中安装的依赖( e)sass 标记为可选对等依赖,因为您可以使用预建的分布式 CSS. 还有 配置 Sass 装载路径 页:1 @tokens, (中文(简体) ), @themes,以及 node_modules 所以所有的依赖性都是由萨斯解决的.

已配置 Sass 载入路径, 您可以导入您的 Sass 样式表所需的组件 :

// my-product-styles.scss

// Spirit themes and foundation are mandatory
@use 'node_modules/@alma-oss/spirit-web/scss/themes';
@use 'node_modules/@alma-oss/spirit-web/scss/foundation';

// Spirit components can be hand-picked
@use 'node_modules/@alma-oss/spirit-web/scss/components/Button';

// Spirit helpers and utilities are optional
@use 'node_modules/@alma-oss/spirit-web/scss/helpers';
@use 'node_modules/@alma-oss/spirit-web/scss/utilities';

混合函数的使用

本套件提供的混接器和功能仅供内部使用. 它们的稳定性在语义化版本中得不到保证. 如果你选择使用,考虑把它们复制到自己的代码库来避免可能出现的问题.

自定义主题

自动: 使用图像和超新星

建议的创建自定义主题的方法是使用Figma和Supernova来定义和导出您的设计符号,包括它们的主题变体. 一旦你得到了你的设计符号,你可以 在您的 Sass 项目中使用。 。 。 .

为了根据所提供的设计符号生成实际主题,仅包括我们 themes 在您的 Sass 项目中的文件 :

@use 'node_modules/@alma-oss/spirit-web/scss/themes';

手动创建主题

如果您不使用"Figma"和"超新星",或者您需要仅以您UI中的一个小作品为主题,您可以手动创建自己的主题. 定义您的主题变量, 以便与您在 scss/themes/_color-tokens.scss 文件在设计符号包中.

例如:

@use '@tokens' as tokens;

:root,
.my-theme-light {
  --#{tokens.$token-prefix}color-text-primary: #007bff;
}

.my-theme-dark {
  --#{tokens.$token-prefix}color-text-primary: #beddff;
}

前置 CSS 类名称

您可以在 CSS 类名称中添加前缀, 以更好地将Spi精神与其他 CSS 区分开来 在你的项目。 建议的方法是使用PostCSS和 postcss-prefix-selector 插件 :

// postcss.config.js

const postcssPrefixSelector = require('postcss-prefix-selector');

module.exports = {
  plugins: [
    postcssPrefixSelector({
      prefix: 'spirit-',
      transform(prefix, selector) {
        // Ignore interaction state classes controlled by JS: .is-* | .has-*
        const regex = /\.(?!is-|has-)/gi;
        return selector.replaceAll(regex, `.${prefix}`);
      },
    }),
  ],
};

Java 脚本

一些组件需要JavaScript插件才能完全实现功能. 可以使用单个模块或编译的捆绑.

个人或汇编

插件可单独作为ECMAScript模块(使用 import { <plugin> } from '@alma-oss/spirit-web',参见 使用 Spirit Web 作为模块),或同时使用 js/{cjs|esm|bundle}/spirit-web.js 或修改 js/{cjs|esm|bundle}/spirit-web.min.js (不包括两者),所有文件都准备好了UMD.

<script src="node_modules/@alma-oss/spirit-web/js/cjs/spirit-web.min.js" async></script>

如果使用捆绑器(Webpack, Rollup,.),可以使用 /js/*.js 文档是 ECMAScript 模块.

在浏览器中使用 Spirit Web 作为模块

我们提供精神网络的版本 ESM (单位:千美元)spirit-web.esm.js 财务报告和审定财务报表 spirit-web.esm.min.js),它允许您在浏览器中使用Spirit Web作为模块.

<script type="module">
  import { Header } from 'spirit-web.esm.min.js';

  Array.from(document.querySelectorAll('.header')).forEach((headerNode) => new Header(headerNode));
</script>

数据属性

几乎所有Spirit-Web插件都可以通过HTML单独启用并配置数据属性(我们使用JavaScript功能的首选方式). 请确定仅在单个元素上使用一组数据属性( 例如, 您不能从同一按钮触发工具提示和模式) .

iQQ 关闭此功能时不会设置 data-spirit-toggle 属性并使用程序化 API.

选择器

目前,为了查询DOM元素,我们使用本地方法 querySelector 财务报告和审定财务报表 querySelectorAll 基于性能原因,您必须使用有效的选择器. 如果使用特殊选择器,例如: collapse:Example 一定要逃脱他们.

活动

Spirit-Web为大多数插件的独特动作提供自定义事件. 一般说来,这些是无限的和过去形式的 -- -- 无限的(前). show)在事件开始时被触发,以及其过去的participle形式(ex. shown)在动作完成后被触发.

所有无限活动都提供 preventDefault() 函数. 这提供了在行动开始前停止执行的能力. 从事件处理器返回错误也会自动调用 preventDefault()。 。 。 .

var myModal = document.getElementById('my-modal');

myModal.addEventListener('show.modal', function (event) {
  if (!data) {
    return event.preventDefault(); // stops modal from being shown
  }
});

程序化 API

var myModalEl = document.getElementById('my-modal');

var modal = new Modal(myModalEl); // initialized with defaults

如果您想要获得特定插件实例, 每个插件都会曝光一个 getInstance 方法.

CSS 构造器中的选择器

您也可以使用 CSS 选择器作为第一个参数,而不是 DOM 元素来初始化插件 . 目前,插件的元素由 querySelector 方法,因为我们的插件只支持单一元素.

var modal = new Modal('#myModal');
var dropdown = new Dropdown('[data-spirit-toggle="dropdown"]');

光盘N

精神设计系统也可在CDN上访问:

考虑使用特定版本而不是 latest 在生产中.

单位 - rem

精神主要用来 rem 相距、打字、光度和阴影 以 rem 相对于a 16 个 px 根字体大小。 故意行为 px 存在例外 对于不能以根字体大小缩放的值,例如边框宽度和 隐形公用技术.

见 单位指南 详细情况,包括常设委员会 px-to-rem() 函数,以及基准字体大小与设计符号的关系.

重命名

设计符使Spirit Sass的组件和风格能够快速而轻松地被重新命名. 一旦你创建了自己的设计符号, 就把它们提供给你的 Sass 编译器, 你准备走了! 学习更多在 spirit-design-tokens 文档。 。 。 .

发展

启动本地开发服务器 yarn start 要开始。 您将在浏览器中获取所有组件和插件的活性预览 。 只要弄脏东西,改变一些东西, 你会看到改变是活的.

Dev-stack是基于 维特。 。 。 .

折旧

此套件对在下个主放出时会被去掉或被替换的道具,功能和组件使用去化警告. 检查您的浏览器控制台, 以查看您是否正在使用任何已贬值的功能 .

👉 参见 DePRECATES 文件 列出所有贬值情况.

特性旗

见 特性标记文档 如何使用它们.

实例

见 实例 现场演示.

许可证

见 自由主义 文档供参考.