Bắt đầu với Lily

Cài đặt

Lily nằm trong một monorepo Git duy nhất, với một thư mục cho thư viện headless, các gói trợ thủ và ứng dụng ví dụ của từng framework. Cách nhanh nhất để thử là sao chép monorepo và mở thư viện headless cho ngăn xếp của bạn:

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

Cùng khuôn mẫu đó áp dụng cho các framework khác:

• @lilydesignsystem/html-headless — không cần cài đặt; sao chép các tệp .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

Các thư viện headless được thiết kế để sao chép hoặc đưa vào dự án — hãy coi mã nguồn là nguồn chân lý và sao chép những gì bạn cần. trợ thủ tùy chọn còn được phát hành dưới dạng gói cài đặt được với quy trình build và phát hành (npm cho các framework JS, NuGet cho Blazor).

Dùng một thành phần headless

Thành phần headless cung cấp HTML ngữ nghĩa, ARIA và prop — nhưng không có CSS. Đây là một Button trong từng framework:

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" }) }}

Dùng một ví dụ có kiểu

Các ứng dụng ví dụ bao gồm CSS, tuyến và các trang demo đầy đủ. Cách nhanh nhất để thử nghiệm là khởi động ứng dụng ví dụ SvelteKit, Next, Nuxt, Analog hoặc Eleventy và xem bản demo tại /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

Sau đó mở http://localhost:5173 và duyệt /components.

Kiểu dáng và token thiết kế

Mỗi thành phần được hiển thị với một lớp kebab-case duy nhất trên phần tử gốc. Ví dụ, <Button> hiển thị thành <button class="button">. Hãy tạo kiểu theo cách bạn muốn:

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

Bảng màu mặc định của Lily (dùng trong các ứng dụng ví dụ) là:

• Chính: #2563eb
• Nguy hiểm: #dc2626
• Cảnh báo: #f59e0b
• Thành công: #16a34a
• Nền trang: #f9fafb
• Nền thẻ: #ffffff

Đây là gợi ý, không phải yêu cầu. Hãy thay chúng bằng bảng màu thương hiệu của bạn, Lily sẽ vui vẻ đi theo.

Giao diện làm sẵn

Không muốn viết CSS từ đầu? Lily cung cấp 57 giao diện tham chiếu độc lập trong thư mục themes/ . Mỗi giao diện là một stylesheet nhắm vào các móc lớp của Lily — liên kết nó và bạn đã có kiểu:

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

Bộ giao diện bao gồm:

• Khu vực công — NHS England, NHS Scotland và NHS Wales (mỗi nơi có bản dành cho bệnh nhân và bản dành cho người hành nghề), GOV.UK GDS và U.S. Web Design System.
• Lấy cảm hứng từ nhà cung cấp — Adobe Spectrum, Mozilla Protocol.
• Đa dụng — light, dark, nord, dracula, wireframe và khoảng ba chục giao diện nữa.

Bộ chọn của giao diện dùng :where(...), nên CSS của chính bạn luôn thắng về độ ưu tiên. Hãy ghép chúng với trợ thủ theme-picker bên dưới để chuyển đổi lúc chạy, hoặc làm theo hướng dẫn giao diện.

Trợ thủ tùy chọn

Mỗi framework có tám bộ chọn nhỏ, mỗi bộ là một gói lily-design-system-{framework}-{package} riêng (và một picker-bar để lắp ráp chúng). Mỗi bộ là một nút biểu tượng headless mở ra một cửa sổ bật lên — hộp danh sách, danh sách liên kết, biểu mẫu tìm kiếm hoặc (với date-time-picker) hộp thoại chọn ngày — không phải <select>gốc; an toàn SSR; và không kèm CSS:

• theme-picker — tải stylesheet giao diện lúc chạy bằng cách đổi một <link>được quản lý, đặt data-theme trên tài liệu và tùy chọn lưu bền vào localStorage.
• locale-picker — đặt lang và dir (với tự động phát hiện RTL) để thư viện i18n của bạn có thể theo sau; bản thân nó không dịch gì.
• text-size-picker — đặt data-text-size trên tài liệu; CSS của bạn ánh xạ từng giá trị sang cỡ chữ.
• motion-picker — đặt data-motion trên tài liệu, bắt đầu từ thiết lập giảm chuyển động của khách truy cập; CSS và script của bạn quyết định cái gì bị ngăn chặn.
• search-picker — một nút biểu tượng mở ra ô tìm kiếm; gửi đi sẽ chuyển tới trang tìm kiếm. Sở hữu một hành động, không phải một tùy chọn.
• link-picker — biểu tượng ngôi nhà mở ra menu các liên kết trang mà ứng dụng của bạn định nghĩa (Trang chủ, Về chúng tôi, Liên hệ, Chính sách bảo mật, …). Sở hữu một hành động, không phải một tùy chọn.
• share-picker — mở bảng chia sẻ gốc hoặc danh sách đích do bên dùng cung cấp, cộng với sao chép URL. Sở hữu một hành động, không phải một tùy chọn: không áp dụng gì, không lưu gì.
• date-time-picker — một ô văn bản cùng hộp thoại chọn ngày APG cho một ngày, một giờ hoặc cả hai. Sở hữu một giá trị biểu mẫu, không phải một tùy chọn: chuỗi ISO được chuyển qua lại với <input type="date">.

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

Danh mục Svelte là tham chiếu chuẩn; các bản chuyển sang React, Vue, Angular, HTML, Nunjucks, Web Components và Blazor khớp với nó từng hợp đồng một. Xem hướng dẫn trợ thủ.

Khả năng tiếp cận

Các thành phần hướng tới WCAG 2.2 AAA. Chúng tuân theo các mẫu sau:

• Phần tử HTML ngữ nghĩa thay vì <div>s.
• <label for="id"> chung chung, liên kết nhãn với ô nhập.
• aria-labelledby / aria-describedby cho các tham chiếu chéo.
• aria-invalid + aria-errormessage cho trạng thái lỗi.
• role="alert" và aria-live cho nội dung động.
• aria-pressed, aria-expanded, aria-current cho trạng thái.
• Roving tabindex cho lưới.

Chỉ báo tiêu điểm được bên dùng cung cấp một cách có chủ ý — Lily không bao giờ vẽ vòng tiêu điểm mặc định xung đột với thiết kế của bạn. Các ứng dụng ví dụ giữ đường cơ sở axe-core sạch trên mọi tuyến của chúng.

Quốc tế hóa

Mỗi nhãn, văn bản gợi ý, thông báo lỗi và chữ trên nút đều là prop. Không có chuỗi nào bị viết cứng. Hãy gắn framework dịch bạn chọn — Paraglide, i18next, vue-i18n, react-intl, tệp .resx, bất cứ thứ gì.

Với ngày, số và tiền tệ, các thành phần nhận chuỗi đã định dạng sẵn: bạn định dạng bằng Intl.DateTimeFormat / Intl.NumberFormat / thư viện bạn ưa thích rồi truyền kết quả vào.

Trợ thủ locale-picker báo ngôn ngữ đã chọn cho thư viện i18n của bạn bằng cách đặt lang và dir trên gốc tài liệu.

Kiểm thử

Mỗi dự án con framework phát hành kèm các bài kiểm thử riêng dùng ngăn xếp quen thuộc của nó:

• HTML: WebDriverIO chạy trình duyệt thật.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (qua plugin Vite của Analog).
• Nunjucks: Vitest với một trợ thủ hiển thị.
• Blazor: bUnit.

Các bài kiểm thử dùng chỉ các matcher tích hợp sẵn của Vitest — không bao giờ dùng matcher của jest-dom . Điều này giữ cho các bộ kiểm thử có tính di động. Các ứng dụng ví dụ bổ sung bộ Playwright đầu-cuối, đường cơ sở khả năng tiếp cận axe-core và đợt quét khung nhìn đáp ứng.

Tác tử AI

Trang này công bố llms.txt và llms.json ở gốc — một bản đồ được tuyển chọn của các trang quan trọng nhất, dành cho mọi công cụ tuân theo quy ước llms.txt.

Monorepo chuẩn còn cung cấp thêm hai Claude Skills: lily-design-system-skill: một skill đa dụng bao quát khái niệm, thuật ngữ và mẫu ghép của Lily dành cho bất kỳ ai xây dựng với hệ thống, và lily-design-system-maintainer-skill, một skill kỹ thuật bao quát bố cục tệp bắt buộc và công cụ của monorepo dành cho bất kỳ ai làm việc trên đó. Cả hai nằm ở gốc của monorepo chuẩn.

Khắc phục sự cố

Đóng góp

Lily còn trẻ và hoan nghênh sự hợp tác. Những đóng góp hữu ích nhất hiện nay là:

• Thành phần mới (đặc biệt là các mẫu từ những hệ thống thiết kế đã được khẳng định).
• Giao diện mới — mỗi cái là một stylesheet độc lập, một PR đầu tiên có phạm vi rõ ràng.
• Tạo kiểu ví dụ tốt hơn — cho thấy điều gì là khả thi.
• Bản dịch các chuỗi của ứng dụng ví dụ.
• Báo cáo lỗi kèm cách tái hiện tối thiểu.
• Kiểm toán khả năng tiếp cận bằng trình đọc màn hình và công nghệ hỗ trợ.

Mở issue và PR tại github.com/LilyDesignSystem/lily-design-system.

Cộng đồng và hỗ trợ

• Câu hỏi và báo cáo lỗi — mở một issue tại github.com/LilyDesignSystem/lily-design-system.
• Email — người bảo trì đọc joel@joelparkerhenderson.com và hoan nghênh sự hợp tác, hướng dẫn và phản hồi.
• Bản sao — Lily cũng được đẩy lên Codeberg và GitLab, để bạn có thể tham gia từ nền tảng mã nguồn bạn ưa thích.
• Quy tắc ứng xử — dự án theo một bộ quy tắc ứng xử chuẩn; hãy tử tế, hãy giả định thiện chí.

Hỏi đáp