開始使用 Lily

安裝

Lily 住喺一個 Git 單一倉庫入面,每個框架嘅無頭函式庫、輔助套件同範例應用程式都有一個目錄。最快試用嘅方法係複製單一倉庫並打開你技術棧嘅無頭函式庫:

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

無頭函式庫係設計成可以複製或 vendor 嘅 — 將原始碼當作真相來源,複製你需要嘅部分。 偏好輔助工具 另外亦以可安裝套件形式提供,附帶建置同發佈流程(JS 框架用 npm,Blazor 用 NuGet)。

使用無頭元件

無頭元件提供語義化 HTML、ARIA 同屬性 — 但冇 CSS。以下係各框架嘅 Button:

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,同 U.S. Web Design System。
• 受供應商啟發 — Adobe Spectrum、Mozilla Protocol。
• 通用 — light、dark、nord、dracula、wireframe,仲有三十幾個。

主題選擇器使用 :where(...),所以你自己嘅 CSS 喺特異性上永遠勝出。將佢哋同下面嘅 theme-picker 輔助工具配對作執行時切換,或者跟隨 主題教學.

偏好輔助工具

每個框架有八個細細個嘅選擇器,各自喺佢自己嘅 lily-design-system-{framework}-{package} 套件入面(同埋 picker-bar 將佢哋組裝埋一齊)。每個都係打開彈出視窗嘅無頭圖示按鈕 — 清單方塊、連結清單、搜尋表單,或者(date-time-picker)嘅日期選擇器對話框 — 唔係原生嘅 <select>;SSR 安全;而且冇附帶 CSS:

• theme-picker — 透過替換受管理嘅 <link>喺執行時載入主題樣式表,喺文件上設定 data-theme ,並可選擇性咁持久化到 localStorage.
• locale-picker — 設定 lang 同 dir (附自動 RTL 偵測)等你嘅 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>s.
• <label for="id"> 將標籤連結到輸入欄位。
• aria-labelledby / aria-describedby 用於交叉引用。
• aria-invalid + aria-errormessage 用於錯誤狀態。
• role="alert" 同 aria-live 用於動態內容。
• aria-pressed, aria-expanded, aria-current 用於狀態。
• Roving 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 Skills: lily-design-system-skill,一個涵蓋 Lily 概念、術語同組合模式嘅通用技能,供任何用呢套系統構建嘅人使用,以及 lily-design-system-maintainer-skill,一個涵蓋單一倉庫必要檔案佈局同工具嘅技術技能,供任何喺度工作嘅人使用。兩者都喺 標準單一倉庫.

疑難排解

貢獻

Lily 仲年輕,歡迎協作。而家最有用嘅貢獻係:

• 新元件(尤其係來自成熟設計系統嘅模式)。
• 新主題 — 每個都係一份獨立樣式表,範圍清晰嘅第一個 PR。
• 更好嘅範例樣式 — 展示有咩可能。
• 範例應用程式字串嘅翻譯。
• 附最小重現嘅錯誤報告。
• 用螢幕閱讀器同輔助科技進行嘅無障礙審核。

喺以下位置開 issue 同 PR github.com/LilyDesignSystem/lily-design-system.

社群同支援

• 問題同錯誤報告 — 喺以下位置開一個 issue github.com/LilyDesignSystem/lily-design-system.
• 電郵 — 維護者會閱讀 joel@joelparkerhenderson.com 並歡迎協作、指引同意見。
• 鏡像 — Lily 亦會推送到 Codeberg 同 GitLab,等你可以喺自己鍾意嘅平台參與。
• 行為 — 項目遵循標準行為守則;待人和善,假設對方出於善意。

常見問題