种子 — Bloom 组件库
这个包裹是 布鲁姆其核心UI组件,意在从各种应用内部导入. 种子取代了Bloom之前的"ui-组件"包.
种子使用TypeScript,React,和Sass来构建. 它使用"故事本"作为混凝土组件示例,并使用"杰斯"作为测试.
我们建议在装入种子时使用节点版本22.
设计系统文档
此逗号页面 是补充种子文档的中心.
同样在"概念"中,我们使用 零高到文档符号、组件和图案 种子设计系统.
对于代码级别随着时间的推移的变化, 参见 GitHub 更改日志的发布。 。 。 .
使用量
下一个.js
为了建立种子,首先增加 @bloom-housing/ui-seeds 包通过 npm 或纱线。 下一个, 更新 next.config.js 将软件包名称纳入其 transpilePackages 配置选项 :
transpilePackages: [
"@bloom-housing/ui-seeds"
]
您需要安装 Sass & PostCSS , 同时安装 @csstools/postcss-global-data 打开 postcss-custom-media 软件包。 确保通过《公约》提供 postcss.config.js 文件 :
plugins: {
"@csstools/postcss-global-data": {
// in the Bloom monorepo, this starts with `../../`:
files: ["node_modules/@bloom-housing/ui-seeds/src/global/tokens/screens.scss"],
},
"postcss-custom-media": {},
...
}
最后,在您输入种子的主要 CSS 切入点 _app.tsx 文件 :
import "@bloom-housing/ui-seeds/src/global/app-css.scss"
现在您可以在您需要使用种子的页面上导入单个种子反应组件 .
捐款
种子主要包括: 设计符号 财务报告和审定财务报表 组件. 有一些全球风格规则和实用类,但被故意保持在最低限度。 尽可能采用组件范围样式规则.
对于设计标志、组件类别和公用事业类别,一般建议从 seeds 前缀.
设计托肯斯
设计标志分为两层: 基础符号 财务报告和审定财务报表 语义符号语义符号 消费 基础标志。 只要有可能,组件就应当依赖语义符号而不是基号. 这将使下游主题易于定制(鼓励消费者推翻语义符号, 没有 基础符号).
譬如说, --seeds-color-blue-500 设置为 #0077da此外, --seeds-color-primary 设置为 var(--seeds-color-blue-500)您的组件应当使用 --seeds-color-primary 而不是说 --seeds-color-blue-500除非你知道这一点 永远 需要使用这种特定的颜色,无论下游主题的变化如何.
鼓励组件设置自己的组件特有符号,这些符号既能发挥语义符号的作用,又能发挥基础符号的作用(当合适的语义符号没有可用时). 例如:
.seeds-card {
--card-spacing-md: var(--seeds-s6); /* a base token */
--card-background-color: var(--seeds-bg-color-surface); /* a semantic token */
}
在一个组件中的各种部件/子组件中,许多组件消耗了在这个顶层定义的组件符号.
我们不鼓励在顶层以下定义符号, 因为消费者需要知道一个组件的内部DOM结构, 这不利于未来兼容性.
/* Bad */
.seeds-component {
--component-token-1: var(--seeds-s3);
padding: var(--component-token-1);
> .seeds-component-section {
--component-token-2: var(--seeds-s5);
padding: var(--component-token-2);
}
}
/* Good */
.seeds-component {
--component-token-1: var(--seeds-s3);
--component-section-token-1: var(--seeds-s5);
> .seeds-component-section {
padding: var(--component-section-token-1);
}
}
构成部分定义
组件被构建为功能回放组件,有文件名来匹配组件名称. 这么说吧 FieldValue.tsx 导出一个命名的组件 FieldValue。组件文件位于“侧车”旁边 .scss 包含组件样式的文件.
组件类是前缀组件的kebab cased名 seeds。这样 FieldValue 构成部分将与 seeds-field-value 类名.
部件可能提供多种变体,如颜色/类型变体,大小等. 鼓励使用 data-* 要指定这些变量的 HTML 属性 :
<span
id={props.id}
className={classNames.join(" ")}
data-variant={props.variant || "primary"}
data-size={props.size}
aria-label={props.ariaLabel}
>
{props.children}
</span>
在您的样式表中, 您可以根据这些属性添加样式规则 :
.seeds-tag {
&[data-variant="primary"] {
background-color: var(--seeds-color-primary-light);
color: var(--seeds-color-primary-dark);
}
&[data-size="lg"] {
font-size: var(--tag-font-size-lg);
font-weight: var(--tag-font-weight-lg);
}
}
一些布尔式的变体或"状态"作为条件类更直接. 在这种情况下,我们通常使用 is- 或者说 has- 前缀,例如:. .is-fullwidth 或者说 .has-lead-icon。 。 。 .
一些州也通过使用ARIA的角色和属性得到更好的表达. 如果ARIA无论如何都需要通过HTML标记来管理,那么最好将样式从那些上挂起,而不是通过额外的属性/类引入重复.
文档
故事记录在 __stories__ 文件夹在 .stories.tsx 文档。 然后这些故事可以在零高度范围内被显示在文档中.
此外 .docs.mdx 文件将显示道具和造型信息.
组件道具与JSDoc评论一起使用TypeScript接口来记录. 这些评论将在《故事书》中使用 ArgsTable mDX文件中的组件.
组件符也使用故事MDX文件中的Markdown表来记录.
在"零高"中,由于设置的集成,故事很容易被一一地嵌入. 然而,要嵌入道具/样式的docs页面,您需要打开"故事本",点击"Docs"选项卡一个组件,并将URL复制到"iframe"嵌入于零高度以内.
测试
单位测试设在 __tests__ 文件夹,用 React 的测试库编写,并通过 Jest 执行 。 单元测试的目的是核查一个组件的基本功能以及显示逻辑中的任何主要分支.