Lily Design System™

Hướng dẫn React

Thành phần hàm có kiểu, mỗi cái một tệp, được điều khiển theo mẫu chuẩn value + onChange — mọi thứ hoạt động đúng như React vốn làm.

Bạn sẽ xây dựng gì

Một biểu mẫu liên hệ nhỏ — ô nhập có nhãn, nút gửi, trạng thái được điều khiển, hành vi bàn phím và trình đọc màn hình thật — lúc đầu để trơn, sau đó thêm kiểu dáng, trong khoảng 10 phút.

Trước khi bắt đầu

Bạn cần git, Node 22 trở lên và pnpm 10 trở lên. Dự án React 18+ nào cũng được — Next.js, Vite hoặc React thuần.

Bước 1 — Lấy mã

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-react-headless
pnpm install
pnpm test        # vitest + @testing-library/react
pnpm run storybook   # browse all 571 components

Các thành phần là những tệp phẳng trong components/ — Button.tsx, TextInput.tsx — mỗi cái có bài kiểm thử, story và tài liệu bên cạnh. Sao chép các tệp bạn cần vào ứng dụng, hoặc đưa kho mã vào rồi nhập từ đó.

Bước 2 — Thành phần đầu tiên của bạn

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

export function SaveBar() {
  return <Button onClick={save}>Save</Button>;
}

Hiển thị <button class="button" type="button">. Thuộc tính: type, disabled, pressed (hiển thị aria-pressed), label ( aria-label để ghi đè), className, và mọi thuộc tính bổ sung được trải lên phần tử gốc.

Bước 3 — Ghép một biểu mẫu nhỏ

import { useState } from "react";
import Form from ".../components/Form";
import Field from ".../components/Field";
import TextInput from ".../components/TextInput";
import Button from ".../components/Button";

export function ContactForm() {
  const [name, setName] = useState("");
  return (
    <Form label="Contact form" onSubmit={handleSubmit}>
      <Field label="Full name" required>
        <TextInput id="name" label="Full name" value={name} onChange={setName} required />
      </Field>
      <Button type="submit">Save</Button>
    </Form>
  );
}

Field nhận label làm thuộc tính riêng thay vì thành phần nhãn lồng bên trong — chỉ truyền một lần, trên Fieldvà TextInputtương ứng label cung cấp tên có thể tiếp cận.

Đã xác minh 2026-08-29: bản nháp trước lồng một thành phần Label bên trong Field, khiến hiển thị hai nhãn (một cái rỗng) vì Field đã tự hiển thị nhãn của nó từ label thuộc tính — phát hiện nhờ biên dịch đoạn mã chính xác. Tuyến Tuyến biểu mẫu liên hệ ghép sẵn cũng theo mẫu này, được kiểm chứng bằng các bài kiểm thử e2e và axe thật.

Bước 4 — Tạo kiểu dáng

Mọi thứ ở trên hiển thị thành cấu trúc thuần, sẵn sàng cho kiểu dáng của bạn. Tạo kiểu cho các hook — .button, .text-input, .label, .field — trong bảng kiểu của bạn, xếp lớp tiện ích Tailwind qua className, hoặc liên kết một chủ đề dựng sẵn: 

<link rel="stylesheet" href="/themes/united-states-web-design-system.css" />

Bước 5 — Xem mọi thứ hoạt động

Ứng dụng ví dụ Next.js là toàn bộ danh mục có kiểu dáng và bản demo, cùng Playwright e2e và đường cơ sở axe-core: 

git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-react-next-examples
pnpm install && pnpm run dev

Các bước tiếp theo

Có thắc mắc trên đường đi? Trang trợ giúp có đầy câu trả lời — và nếu một bước có thể rõ ràng hơn, hãy cho chúng tôi biết và chúng tôi sẽ vui lòng cải thiện hướng dẫn.