@ canonical/ 风格

此 README 是为两个读取器撰写的:将设计系统添加到应用程序中的人,以及 保持这个包裹的人。 可以通过测试检查债权的,以测试命名.

Canonical设计系统的全球风格表. 一个导入带来重置, 打印 引擎、设计符号、修饰家庭和布局预设。 所有这个包 本身的船舶处于一个命名的级联层中,其元素级规则将整页作为 重新设置是可行的——没有任何限制,也没有任何东西必须加以标记。 住在 @canonical/styles-typography 并随此软件包一同发布,属于同一层.

安装

bun add @canonical/styles

使用量

在任何组件之前导入一次, 作为您应用程序入口的首次导入 :

@import url("@canonical/styles");

或来自 Java 脚本或 TypeScript :

import "@canonical/styles";

然后在你的根上宣布表面:

<html class="app comfortable">

单行是根契约,它有两个部分.

色彩方案是可选的 : light 或者说 dark 标出一分,两分不开,让页面跟着 读者操作系统. 根基上没有别的东西,特别是没有一类 开关重置 。 它的适用是因为样式表已加载.

两个类都设置了继承的自定义属性,因此可以坐在文档元素上,也可以坐在任意 阅读它们的组件的祖先——参考应用程序显示: app comfortable 打开 <body>。 。 。 .

ds 这不是一个根源阶级,从来没有。 每一个组成部分都以此为根基 组件规则可以选择 .ds.button 而不是说 .button 无法与页本身相撞 分类名称.

运行另一个 CSS 框架的页面 无法让样式表重排它没有的半个 迁移,这就是 @canonical/styles-vanilla-adapter 是用来: 它运送一个副本 包的三层元素级层 限于一个团队移交的部分 保持两层 将主题信号连接起来 包里的一个测试 将其副本绑入这里的文件, 以便两者不能漂移 。 这个安排没有任何改变 软件包或不需要的页面标记.

入境点

五个. @canonical/styles 是普通页面想要的:整个样式表,顺序 见上文。 3个是样式表 部分,第5个是单项命令语句 其他四个进口.

一个例外的"改变什么," 这是值得知道之前,你导入 tokens.css设计 函数生成的主题表声明 color-scheme 打开 :root, (中文(简体) ), .light 财务报告和审定财务报表 .dark 与 颜色符号,且属性不是惰性:它决定了画布的颜色,窗体控件, 滚动条和系统颜色,无论任何事物是否读取一个符号,在混合页面上 其他框架的载体 light 或者说 dark 捡取也. 无法分割 在这里,表是生成的,声明是按与符号相同的规则排列的——因此分开 它们是对信物包的发射器的改变,追踪到PRA-149. 一定没有的申请 它声明 color-scheme 本身,在上一层 ds.modifiers 或无分层. 那三个 声明是唯一的非海关财产 tokens.css 载着;里面所有的东西都是 习惯财产,在规则读取之前,它什么都不做.

这些部分存在的原因只有一个。 运行另一个 CSS 框架的页面不能包含元素 规则:另一个框架有自己的 p 规则,只有两个人能拥有 line-height。这样 页面 tokens.css 财务报告和审定财务报表 layout.css从框架的适配器中获取其要素规则 相反,在限于页面部分的拷贝中,设计系统拥有—— @canonical/styles-vanilla-adapter 将副本建出相同的文件 elements.css 进口.

两个属性使部分可以安全地混合,两者都可见于条目的写法.

每个条目先导入订单,订单会被写入一个文件. layers.css 拿着 语句,而不是其他的;四个条目中的每一个都导入它作为第一条规则。 命令必须 在命令任何规则之前到达浏览器, 写一次意味着两个条目永远不会有异议 ——如果每一份清单重复,他们可以这样做,但将留下同样的规则仲裁 根据消费者选择的条目不同 用铬测量:读取的语句 a 一个 @import 命令进口单完全如原样.

不得进口其他条目. 一个 @layer 层块内的语句 宣告 而不是顶层,所以一个构成另一层的条目会嵌入顺序 而不是分享它。 保持它们的独立性意味着一个页面可以按任何顺序装入一、二或全部三个,而且 得到同样的结果——每个文件都一次取出、解析和应用,这很重要,因为 浏览器处理每个 @import 因为它的样式表 和去复制什么.

分层

所有这个包裹本身的船 都处于一个命名的地层, 顺序是由一个语句固定的, 住在这里 layers.css 每一个入口都先进口 此软件包所导入的打印引擎是相同的 层 :

@layer normalize, ds.tokens, ds.reset, ds.typography, ds.modifiers, ds.surfaces,
  ds.states, ds.components, ds.components.global, ds.components.sites,
  ds.components.documentation, ds.components.stores, ds.components.apps,
  lib, app;

从下而上地阅读它——每个位置都是一种争论.

lib 财务报告和审定财务报表 app 是唯一的外层名称 normalize 财务报告和审定财务报表 ds.*命令语句修正 层的相对顺序,它们第一次出现,一个后期的语句永远不能重排它们,所以 一个应用程序先导入此软件包,然后在 @layer app,没有说明 自己来的.

本节为参考文献:每一层中的内容,以及位置. 命令背后的理由——如何 浏览器决定,为什么一个规则 没有任何层击败每一个层,为什么封装一个混合的页面 需要住在适配器中而不是这里,而捆绑者对语句所做的是 级联合同。 。 。 .

构成部分等级

组件层遵循设计系统的分层树: 谁拥有一个组件决定哪个分层 它的规则进入, 更深层的获胜。 有三条规则是可行的,值得说明 很明显,因为一个软件包的作者必须跟随他们.

第二层在这里取名,满分. global, (中文(简体) ), sites, (中文(简体) ), documentation, (中文(简体) ), stores 财务报告和审定财务报表 apps 是设计系统的4个二级级加共享基,本声明修正了它们 秩序。 秩序。 其中一层的软件包以自己的名将样式表包裹起来,不需要做任何事情 还有.

一个子层宣布自己的地层, 也就是上面的地层. 一个应用程序自己的软件包 ——LXD级,比如说——将其CSS条目写成分两个步骤:

@layer ds.components.apps-lxd;       /* 1. name your layer */

@import url("./Button/styles.css");  /* 2. then import your stylesheets */
/* … the rest of the package's sheets, each wrapped in that layer … */

订单声明来自应用程序加载 @canonical/styles ưμ㼯a 使用量) (中文(简体) ). 浏览器第一次与它相会时, 就会放置一个图层名称, 所以与 15 名称已经确定, ds.components.apps-lxd作为新人,在他们身后附着 ds.components在每一层以上 这是树本身的规则——更具体的层次 胜出——这意味着这个样式表从来就不用知道哪些应用程序存在.

没有什么是直接写成的 ds.components。 。 。 . 父层中的声明 那层隐含的最后一个子层, 它在每一个被命名的子层之上, 所以一个规则写在那里 排名会比每个级别都要高 与级别的目的相反.

名称是树上的分层标识,小写并用连字符表示一个分层(apps-lxd, (中文(简体) ), sites-webcomponentsprototype) (中文(简体) ). 它们不是页面根部的上下文词(app, (中文(简体) ), site, (中文(简体) ), docs: 一层表示拥有组件的是谁, 上下文表示显示的是什么样的页面 两者由不同的人选择.

何为分层

标有"是"的文件是适配器的受限拷贝必须照的. 其他的几乎都一样 自定义属性,在规则读取之前不做任何事情,而规则读取一个匹配 设计系统类。 有两个例外, 无论是有意的还是文件上的, 此包导入 而非写道:

• modifiers.theme.css 套装 color-scheme —— 说 light dark 打开 :root, (中文(简体) ), light 打开 .light, (中文(简体) ), dark 打开 .dark ——全文件. 这就是它的要点: 彩色方案就是每个 light-dark() 符号解析反对,包括浏览器自己的窗体控制和滚动条,以及 它必须到达他们.
• states.css 获取其国家频道 * – 每个元素有30个自定义属性. 这个 是一个生成的文件, 此软件包不是作者, 它只声明自定义属性, 所以 它的通用选择器花费一页, 无论如何它不会支付.

什么是故意无层次的

还有一件事: @font-face输入 fonts.css它定义了整个文档的字体,而不是样式 一个元素,这个样式表将每个面都声明一次,所以没有图层可以命令它 反之,将它放在一起不会改变计算值。 文件是选入并单独导入的 这样一来,已经为同一文件服务的应用程序就不会下载两次.

(Layers做排序) @font-face 规定其中两人申报同一家族: 高层相貌 以源顺序胜过后一. 这里根本没有重复。 )

元素级规则应用的地方

至一一页. 其中三层选择元素而不是声明自定义属性—— normalize, (中文(简体) ), ds.reset 财务报告和审定财务报表 ds.typography ——它们应用了重置总是这样的方式: 样式表已经装入,所以规则已经生效。 没有标记可以添加和 没有子树提名.

这是蓄意的裁决,而不是疏忽。 之前的释放草案 限制了这些层次 到一个标记的子树, 这样运行两个 CSS 框架的页面就可以将它们分开 。 禁闭 工作,但是它让每个普通的页面只为一个问题付费 某些页面有: 根上的类, a 浏览器地板 它不需要, 和重置 沉默无所事事 如果该类被遗忘.

这个问题是真实的,所以问题就解决了. @canonical/styles-vanilla-adapter 船舶a 这三层的限量拷贝 只应用到一个团队交出的一页内, 并且该包中的测试将复制件绑入这里的文件,使两者不能漂移. 一个需要的页面 它安装它;一个从未听说过的页面.

此套件保证

曾经坐在这里的两个保证是适配器的,而不是这个包的: 一个区域移交 在运行另一个 CSS 框架的页面中,它会像在普通页面上一样计算,而且没有 到达这样一个区域以外的一个裸露的元素. @canonical/styles-vanilla-adapter 状态和测试.

此套件不保证什么

• 未上层的应用程序 CSS 击败了这里的所有规则. 级联就是这样定义的:规则是: 层在任意层中都比规则高。 这不是个缺陷,而是逃生舱门 表示一个应用程序,它想让这个软件包的图层顺序为它自己的 CSS 所必须的设置 CSS 输入 @layer app。见下文“迁移”.
• !important 应用中或第三方 CSS 击败了这里的所有规则,对于重要的 声明层顺序倒转,所以最低层获胜。 此软件包不能做什么 改变这一点.
• 此样式表样式为整页 . 重置到达每个 <body>, (中文(简体) ), <button>, (中文(简体) ), <pre> 财务报告和审定财务报表 <legend> 在文档中,布局预设要求类名 grid, (中文(简体) ), subgrid, (中文(简体) ), responsive, (中文(简体) ), intrinsic 财务报告和审定财务报表 content-flow 无论他们出现在哪里 这就是设计系统 重置是,这也是为什么一个同样运行另一个 CSS 框架的页面需要适配器而不是 此切入点.
• color-scheme 设置在文档根上, 无论此样式表被装入何处,因为那是 这是什么 light-dark() 符号和浏览器自身的控制决定了反对。 这是一件事 在这里,消费者不能选择不使用某一类.

浏览器楼层

将表格整体阅读,而不是逐行阅读:地板是每栏中最高的数字,因为 样式表使用全部。 没有浏览器 light-dark() 将根放下 color 宣布为 无效, 并返回到它自己的文本颜色, 因此重置适用, 但页面不是主题 .

这样,这个样式表的地板就用默认引擎 Chrome 125, Safari 17.5, (英语), 火狐 120。将默认引擎转换为 baseline-trim.css 升为 Chrome 133, Safari 18.2, Firefox 154 (英语). 打印引擎也使用 round(),在同一数字上 作为 mod()· ; @canonical/styles-typography“浏览器支持”一节是完整的表格,引擎由 发动机.

设计系统以当前浏览器为目标,不为更老的浏览器携带相容性shims. 一个 应用程序中不能移动的,应当标出一个版本.

移动到分层释放

此发布会做出一个应用程序必须回答的两个更改. 标记也不行,没有什么 添加到根上,重置完全适用于它以前的位置.

1. 您的无级CSS现在击败了这个软件包中的所有规则. 在这之前, 释放大部分的东西 发送的软件包也是没有层的,所以您的软件包通过源命令与之相竞争 特异性,有时会丢失. 他们再也不能了。 如果你依靠我们的规则来取胜, 不会再这样了.

2. 把自己的CSS放进去 @layer app。 。 。 . 首先导入此软件包, 然后包装您的应用程序 样式表 :

   @import url("@canonical/styles");
   
   @layer app {
     /* your CSS */
   }
   

   软件包的语句已命名 app在设计系统层之上,所以你的规则 而不是偶然的秩序, 而你不写你自己的声明.

如果您导入了子路径而不是软件包条目—— @canonical/styles/spacing.css 和五个 其它子路径此套件导出 —— 注意一个子路径没有命令语句, 因此其层 打开时由您自己样式表中首次显示的地方命令。 导入切入点,除非 你有理由不这么做.

页面上的移动

在Chrimium中测量,这个应用程序是设计系统的全过程,在设计系统之前,在设计系统之后,在设计系统之后,在设计系统之前,在设计系统之后,在设计系统之前,在设计系统之前,在设计系统之后,在设计系统之前,在设计系统之后,在设计系统之前,在设计系统之后,在设计系统之后,在设计系统之前,在设计系统之后,在设计系统之前,在设计系统之后,在设计系统之前,在设计系统之前,在设计系统之前,在设计系统之后,在设计系统之后,在设计系统的基础上,在设计系统的基础上,在设计系统中,在设计系统上,在设计系统的基础上,在设计系统上 根本没增加什么 四件事在每一个元素上都有变化 一个在 <hr>;没有别的了.

昔有二事而无相

• 这个 normalize.css 软件包不再是依赖。 此软件包会自写重置, 因此可以 被复制到适配器的封闭构件中,使其只包含设计系统的规则 实际上依赖。 狦 导入应用程序 normalize.css 通过我们,并想要它的其余部分,直接依赖它.
• 旧的README说组件样式凌驾于修饰样式"不管源顺序". 没错 而不是:地层被宣布,但几乎没有被写进地层。 他们现在知道了.

设计托肯斯

以下符号集来自 @canonical/design-tokens 包括:

依赖关系

软件包结构

src/
  index.css                       -- entry point: the layer statement, then the imports
  normalize.css                   -- this package's own reset
  reset.css                       -- the document root's baseline
  spacing.css                     -- spacing tokens
  motion.css                      -- motion tokens, and reduced motion
  overflow.css                    -- scroll overflow affordance
  grid.css                        -- layout presets
  modifiers.density.css           -- the context x density family
  modifiers.*.shim.css            -- temporary shims for unfinished generated modifiers
  controls.hover.shim.css         -- temporary shim for control selected/hover channels
  fonts.css                       -- opt-in @font-face, unlayered