Lily 入门

安装

Lily 位于一个 Git 单体仓库中，每个框架个 headless 库、辅助包搭示例应用各有一个目录。最快个试用方法是克隆单体仓库，然后打开侬所用技术栈个 headless 库：

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-react-headless
pnpm install

同样个模式也适用于其伊框架：

• @lilydesignsystem/html-headless — 无需安装；复制 .html 文件即可
• @lilydesignsystem/svelte-headless — pnpm install
• @lilydesignsystem/react-headless — pnpm install
• @lilydesignsystem/vue-headless — pnpm install
• @lilydesignsystem/angular-headless — pnpm install
• @lilydesignsystem/nunjucks-headless — pnpm install
• lily-design-system-blazor-headless — dotnet build

headless 库个设计目的是被克隆或直接纳入侬个项目——把源代码当作事实来源，需要啥就复制啥。偏好辅助组件还以可安装软件包个形式提供，并有构建与发布流水线（JS 框架用 npm，Blazor 用 NuGet）。

使用 headless 组件

headless 组件自带语义化 HTML、ARIA 搭属性——但呒没 CSS。下面是各框架中个一个按钮：

HTML

<button class="button" type="button" aria-label="Save">
  Save
</button>

Svelte

<script>
  import Button from "lily-design-system-svelte-headless/components/Button/Button.svelte";
</script>

<Button onclick={save}>Save</Button>

React

import Button from "lily-design-system-react-headless/components/Button";

<Button onClick={save}>Save</Button>

Vue

<script setup>
  import Button from "lily-design-system-vue-headless/components/Button.vue";
</script>

<Button @click="save">Save</Button>

Angular

import { Button } from "@lilydesignsystem/angular-headless";

@Component({
  imports: [Button],
  template: `<lily-button (click)="save()">Save</lily-button>`,
})

Blazor

<Button OnClick="Save">Save</Button>

Nunjucks

{% from "components/button/macro.njk" import button %}

{{ button({ text: "Save", type: "button" }) }}

使用带样式个示例

示例应用包含 CSS、路由搭完整个演示页面。最快个实验方式是启动 SvelteKit、Next、Nuxt、Analog 或 Eleventy 示例应用，并在 /components 查看演示。

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-svelte-sveltekit-examples
pnpm install
pnpm run dev

然后打开 http://localhost:5173 并浏览 /components。

样式与设计令牌

每个组件在其根元素上渲染一个 kebab-case 类。例如，<Button> 会渲染 <button class="button">。侬想哪能设置样式侪行：

.button {
  background: var(--my-primary);
  color: #fff;
  padding: 0.75rem 1.5rem;
  border-radius: 0.5rem;
}
.button:hover { background: var(--my-primary-hover); }

Lily 默认个调色板（用于示例应用）是：

• 主色：#2563eb
• 危险：#dc2626
• 警告：#f59e0b
• 成功：#16a34a
• 页面背景：#f9fafb
• 卡片背景：#ffffff

搿眼只是建议，不是要求。换成侬自己品牌个调色板，Lily 会欣然配合。

现成主题

勿想从零开始写 CSS？Lily 附带 57 个独立个参考主题，位于 themes/ 目录中。每一个侪是针对 Lily 类钩子个一份样式表——链接伊，样式就生效了：

<link rel="stylesheet" href="/assets/themes/united-kingdom-government-digital-service.css" />

这一组主题涵盖：

• 公共部门 — NHS England、NHS Scotland 搭 NHS Wales（各有面向患者搭面向从业者个版本）、GOV.UK GDS，以及美国网页设计系统。
• 受厂商启发 — Adobe Spectrum、Mozilla Protocol。
• 通用 — 浅色、深色、nord、dracula、wireframe，以及三十多个其伊主题。

主题选择器使用 :where(...)，所以在优先级上侬自己个 CSS 总是胜出。把伊拉与下面个 theme-picker 辅助组件搭配即可在运行时切换，或参阅主题教程。

偏好辅助组件

每个框架侪有八个小型选择器，每个侪是独立个 lily-design-system-{framework}-{package} 包（以及一个把伊拉组装在一起个 picker-bar）。每个侪是打开弹出层个 headless 图标按钮——选项列表、链接列表、搜索表单，或（对 date-time-picker 而言）日期选择对话框——而不是原生个 <select>；伊对 SSR 安全，也勿附带任何 CSS：

• theme-picker — 通过替换一个受管理个 <link> 在运行时加载主题样式表，在文档上设置 data-theme，并可选择持久化到 localStorage。
• locale-picker — 设置 lang 搭 dir（自动检测从右到左），以便侬个 i18n 库跟随；伊自己勿做任何翻译。
• text-size-picker — 在文档上设置 data-text-size；侬个 CSS 把每个值映射为字体大小。
• motion-picker — 在文档上设置 data-motion，起点是访问者个减弱动效设置；由侬个 CSS 搭脚本决定要抑制啥。
• search-picker — 打开搜索框个图标按钮；提交后跳转到搜索页面。伊拥有个是一个操作，而不是偏好。
• link-picker — 一个主页图标，打开由侬个应用定义个页面链接菜单（首页、关于阿拉、联系阿拉、隐私政策……）。伊拥有个是一个操作，而不是偏好。
• share-picker — 打开原生分享面板或使用方提供个目的地列表，外加复制网址。伊拥有个是一个操作，而不是偏好：勿应用任何东西，也勿保存任何东西。
• date-time-picker — 一个文本字段加上用于日期、时间或两者个 APG 日期选择对话框。伊拥有个是一个表单值，而不是偏好：ISO 字符串可与 <input type="date"> 来回转换。

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-svelte-theme-picker

Svelte 目录是规范参考；React、Vue、Angular、HTML、Nunjucks、Web Components 搭 Blazor 个移植版逐项契约与之一致。参见辅助组件教程。

无障碍

组件以 WCAG 2.2 AAA 为目标。伊拉遵循搿眼模式：

• 用语义化 HTML 元素而不是通用个 <div>。
• 用 <label for="id"> 把标签与输入关联起来。
• 用 aria-labelledby / aria-describedby 做相互引用。
• 用 aria-invalid + aria-errormessage 表示错误状态。
• 用 role="alert" 搭 aria-live 表示动态内容。
• 用 aria-pressed、aria-expanded、aria-current 表示状态。
• 为网格使用漫游式 tabindex。

焦点指示器刻意由使用方提供——Lily 从勿绘制与侬个设计冲突个默认焦点环。示例应用在其所有路由上侪保持干净个 axe-core 基线。

国际化

每个标签、占位符、错误消息搭按钮文字侪是一个属性。呒没硬编码个字符串。接入侬选择个翻译框架——Paraglide、i18next、vue-i18n、react-intl、.resx 文件，啥侪行。

对于日期、数字搭货币，组件接受预先格式化个字符串：侬用 Intl.DateTimeFormat / Intl.NumberFormat / 侬喜欢个库进行格式化，然后传入结果。

locale-picker 辅助组件通过在文档根上设置 lang 搭 dir，向侬个 i18n 库传达所选个区域设置。

测试

每个框架子项目侪使用其惯用技术栈附带自己个测试：

• HTML：在真实浏览器中运行个 WebDriverIO。
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular：Vitest + TestBed（通过 Analog 个 Vite 插件）。
• Nunjucks：带渲染辅助函数个 Vitest。
• Blazor: bUnit.

测试只使用 Vitest 个内置匹配器——从勿使用 jest-dom 匹配器。这让测试套件保持可移植。示例应用还增加了 Playwright 端到端套件、axe-core 无障碍基线搭响应式视口扫描。

AI 代理

本站在根目录发布 llms.txt 搭 llms.json——最重要页面个精选地图，供任何遵循 llms.txt 约定个工具使用。

规范单体仓库还提供两个 Claude 技能：lily-design-system-skill，一个通用技能，为使用该系统构建个人涵盖 Lily 个概念、术语搭组合模式；以及 lily-design-system-maintainer-skill，一个技术技能，为在其上工作个人涵盖单体仓库所需个文件布局搭工具。两者侪位于规范单体仓库个根目录。

故障排查

参与贡献

Lily 还老年轻，欢迎协作。目前最有用个贡献是：

• 新组件（尤其是来自成熟设计系统个模式）。
• 新主题——每个侪是一份独立样式表，范围明确个首个拉取请求。
• 更好个示例样式——展示啥是可能个。
• 示例应用字符串个翻译。
• 附带最小复现个缺陷报告。
• 借助屏幕阅读器搭辅助技术进行个无障碍审计。

请在 github.com/LilyDesignSystem/lily-design-system 提交议题搭拉取请求。

社区与支持

• 问题与缺陷报告 — 请在 github.com/LilyDesignSystem/lily-design-system 提交议题。
• 电子邮件 — 维护者会阅读 joel@joelparkerhenderson.com，欢迎协作、指导搭反馈。
• 镜像 — Lily 还会推送到 Codeberg 搭 GitLab，这样侬可以在自己喜欢个平台上参与。
• 行为准则 — 项目遵循标准个行为准则；请友善待人，以善意揣度伊人。

常见问题