确保一个设计系统

跨出所有Assure产品外观设计的唯一真理来源.

• 键 ——每个产品所消耗的语义CSS变量(颜色,类型,间隔,运动).
• 初级 ——可访问 React 组件已建于 Radix + Tailwind 4.
• 复合材料 – 常见图案 (DataTable, Pageheader, Sidebar, Kanban).

文档

• docs/components.md ——组件目录:按需要和类别划分的每个公共组件,其取而代之的取而代之的取而代之的取而代之的取而代之的取而代之. 根据API报告产生;货包中的船舶(node_modules/@assure-one/design-system/docs/components.md) (中文(简体) ).
• docs/for-ai-agents.md ——AI代理商和新贡献者的短则手册:永远不要生 HTML, the Field 食谱, className 对 classNames,则 ds: 前缀,符号,代码,测试,什么是实验,如何提出一个组件.
• CHANGELOG.md ——逐批出货记录.
• CONTRIBUTING.md ——dev循环,放出流量,版本化,陷阱.
• CLAUDE.md ——在这项回购中工作的AI助手的变动和约定.
• docs/integration/css.md ——应用程序如何加载我们的 CSS:层序,导入序列,相容性预设,去除 @source,运行时间品牌主题.
• docs/testing.md ——在应用的"杰斯特"测试中制作真实的软件包(@assure-one/design-system/testing,实验性).
• docs/forms.md 建立一种形式: Field + 设计-系统控制 + 服务器动作 + zod, 重置和 required,每个控件提交,并测试它 fillField 编号 : selectOption 编号 : pickDate。 。 。 .
• docs/data-tables.md ——构建数据表:无头 useDataTable 控制器(排序、页码、搜索、选择、列可见度、过滤器——每个可控),服务器 manual 模式,以及 URL 状态配方.
• docs/design-system/icons.md ——图标目录及其服务器安全条目(@assure-one/design-system/icons,实验性):在没有客户端边界的服务器组件中导入图标.
• docs/adr/010-design-system-provider.md - 任择性 DesignSystemProvider (信息、语言、链接适配器) /next 条目; 快速启动为 下级。 。 。 .
• claude-skills/ 用于消费项目的Claude代码技能.

安装

pnpm add @assure-one/design-system

从您的应用程序全局样式表装入设计系统的 CSS, 作为拆分 条目,在一层语句下(您构造中的 Tailwind 4) :

/* src/app/globals.css — the layer statement is the first line of the file */
@layer theme, base, ds, components, utilities;

@import "tailwindcss";

@import "@assure-one/design-system/css/tokens.css";
@import "@assure-one/design-system/css/legacy-aliases.css"; /* optional */
@import "@assure-one/design-system/css/tailwind.css";
@import "@assure-one/design-system/css/shadcn.css"; /* optional */
@import "@assure-one/design-system/css/base.css"; /* optional */
@import "@assure-one/design-system/css/components.css";

@import "./ds-preset.css"; /* your app's preset, optional */

然后使用组件 :

import { Button } from "@assure-one/design-system";

export default function Page() {
  return <Button variant="primary">Click me</Button>;
}

分割 CSS 条目

分出项是自1.40起被记录的默认CSS集成. 每个 设计系统类是 ds:- 前缀并编入 css/components.css 内部 @layer ds,所以你自己的公用事业 总是赢得组件样式和 你的"尾风"从不用扫描我们的包裹.

导入命令为 tokens.css → legacy-aliases.css (可选) tailwind.css → shadcn.css (可选) base.css (可选) components.css,在你自己之后 @import "tailwindcss" 和层下语句 @layer theme, base, ds, components, utilities;。 。 。 . docs/integration/css.md 拥有完整的 序列,每个应用程序的预置位置,为什么没有 @source 我们的包裹 需要,而固定 运行后面的每一个权利要求。 推理活着 内 ADR-004 (英语) 财务报告和审定财务报表 ADR-005 (英语)。 。 。 .

styles.css (折旧)

@assure-one/design-system/styles.css - 一张单子上都有 飞行前, 一个谷歌字体 @import 以及被冻结的未加固定的后遗症 实值 自1.40起贬值 (登记) C-CSS-STYLES) (中文(简体) ). 还是船,没有改变, 并被以 3.0 键删除; 已建文件以折旧打开 图标。 移动到拆分条目是有意的视觉变化(文档字体) 大小、字体、飞行前: docs/integration/css.md 第6条和 docs/migration/1.40.md。 。 。 .

运行时品牌主题(实验)

对于只在跑步时间才知道的租户颜色, @assure-one/design-system/tokens 出口 createBrandTheme(): 经验证的种子成为自定义属性 a 内置品牌范围宣布,准备扩展为 style 属性.

import { createBrandTheme } from "@assure-one/design-system/tokens";

<div style={{ ...createBrandTheme({ brand: "#2258d8", accent: "#f59e0b" }) }}>…</div>;

它是纯洁的,而SSR决定主义的, 夹住一个填充太苍白,不能读对面 和保证WCAG AA的每一个前方。 种子形状是 受D7号决定约束,在该决定开放期间可能改变——见 docs/integration/css.md。 。 。 .

品牌艺术

保证文字标记和标记 Logo 将船装入包裹内,下方 public/brand/由您的应用程序提供,不是进口的,所以复制一次 进入您的公共文件夹 :

cp -R node_modules/@assure-one/design-system/public/brand public/brand

从子路径调用的程序 setAssetBasePath("/my-base") 曾经 首先转换文件,而不是移动文件。 A 类 Logo 谁 艺术品不装入 回到品牌glyph + 文本锁,所以没有 需要安装可读锁.

提供者和 /next 条目(实验)

不需要一个提供者:每个组件都使英语字符串,格式 与 en-US 和(用于) LinkButton 编号 : Logo)使一个平地 <a> 编号 : <img>。 。 。 . 在下一个.js, 渲染 NextDesignSystemProvider 获取 next/link 路线和 next/image: 根导入否 next/* 从2.0. DesignSystemProvider 是一个可选的,瘦的,客户端的提供者 cSS不能做的——通用字符串,语言,文本方向, 门户容器、链接和图像适配器、共享工具提示默认以及 吐司地区 它没有DOM包装(ADR-010 (英语)) (中文(简体) ).

// app/layout.tsx (Next.js) — the Next adapters are filled in for you
import { NextDesignSystemProvider } from "@assure-one/design-system/next";

export default function RootLayout({ children }) {
  return (
    <html lang="de">
      <body>
        <NextDesignSystemProvider
          locale="de-DE"
          messages={{ select: { clear: "Auswahl löschen" }, combobox: { empty: "Keine Treffer" } }}
        >
          {children}
        </NextDesignSystemProvider>
      </body>
    </html>
  );
}

• messages 输入目录中的任何子集 DsMessages,按构成部分分列 命名空间( n)select, (中文(简体) ), searchInput, (中文(简体) ), combobox, (中文(简体) ), field, (中文(简体) ), fileUpload; 更多 加入到覆盖物上。 解决总是 组件道具 > 提供者 > 英语默认每个键。 英语列表全文为: src/foundation/messages/en.json; 参数化消息是函数 (单位:千美元)combobox.create: (query) => string) (中文(简体) ).
• locale 默认的 BCP 47 标签 "en-US" 在服务器上 财务报告和审定财务报表 客户. 通过您的应用程序已经知道服务器侧; 设计系统永远不会 读取 navigator.language 在渲染过程中,服务器和客户端HTML都同意.
• linkComponent 编号 : imageComponent - 什麽 LinkButton 财务报告和审定财务报表 Logo 提交 通过。 没有它们,部件就变成平地 <a> 编号 : <img> (全额) 页面导航)。 一个非下一个应用程序通过它的路由器链接; 一个 Next.js 应用程序使用 NextDesignSystemProvider。 。 。 . next 是一个可选的对等点, 仅由 /next 输入.
• portalContainer, (中文(简体) ), dir, (中文(简体) ), tooltip, (中文(简体) ), toasts - 记录 道具 道具 道具. toasts 举起土司地区 useToast(); 如果 您已经使 ToastProvider。 。 。 .

消费者的 Lint 配置

两艘可共享配置的飞船与包裹(实验,W7-18) 所以一个 类似的东西的产品用意 这个寄存器会自燃 每个 规则是 警告在代码上通过它,记录计数 把它切下来.

// eslint.config.mjs
import ds from "@assure-one/design-system/eslint-config";
export default [...ds.configs.recommended];

// stylelint.config.mjs  (stylelint is yours — an optional peer dependency here)
export { default } from "@assure-one/design-system/stylelint-config";

提高规则 "error" 在你自己的配置 一旦你干净。 收养人数 应用被跟踪为W7-19.

开发

pnpm install
pnpm storybook    # http://localhost:6006
pnpm build        # bundle for publishing
pnpm typecheck
pnpm lint

见 CONTRIBUTING.md 包括针对一个真正消费的应用软件的延展.

建筑

3级符号系统, 作者为 DTCG JSON in tokens/src 生成到 src/tokens/ 编辑 ./css/* 条目(ADR-003):

组件消耗 系统符号,从不直接引用值。 主题 (彩色计划,每品品牌,运行时品牌来自 createBrandTheme()(中文(简体) ) 重映射系统 ~ 引用而不触摸组件代码.

每个符号都有两种已公布的拼写: 取名空间 --ds-* 上方名称和 留下的遗产名称--color-brand, (中文(简体) ), --color-pro-fg, (中文(简体) ), --color-menu-item-hover-bg) (中文(简体) ). css/legacy-aliases.css 声明 <legacy>: var(<--ds-* name>) 因此双方都决心 价值——由 pnpm tokens:ds-check。 。 。 .

释放

由标签驱动发布到 public npm. 见 CONTRIBUTING.md ; 以往的释放 CHANGELOG.md。 。 。 .