Memulai dengan Lily

Pemasangan

Lily diterbitkan sebagai repositori Git terpisah untuk setiap framework. Cara tercepat mencobanya adalah mengklon repositori headless untuk tumpukan teknologi Anda:

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

Pola yang sama berlaku untuk framework lain:

• @lilydesignsystem/html-headless — tidak perlu dipasang; salin berkas .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

Pustaka headless dirancang untuk diklon atau dimasukkan ke proyek — perlakukan kode sumbernya sebagai sumber kebenaran dan salin yang Anda butuhkan. Asisten preferensi juga dikirim sebagai paket yang dapat dipasang dengan alur build dan penerbitan (npm untuk framework JS, NuGet untuk Blazor).

Memakai komponen headless

Komponen headless menyertakan HTML semantik, ARIA, dan properti — tetapi tanpa CSS. Berikut sebuah tombol di setiap 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" }) }}

Memakai contoh bertata

Aplikasi contoh mencakup CSS, rute, dan halaman demo lengkap. Cara tercepat bereksperimen adalah menjalankan aplikasi contoh SvelteKit, Next, Nuxt, Analog, atau Eleventy dan melihat demonya di /components.

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

Lalu buka http://localhost:5173 dan telusuri /components.

Penataan dan token desain

Setiap komponen dirender dengan satu kelas kebab-case pada elemen akarnya. Misalnya, <Button> merender <button class="button">. Tata sesuka Anda:

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

Palet warna bawaan Lily (dipakai di aplikasi contoh) adalah:

• Utama: #2563eb
• Bahaya: #dc2626
• Peringatan: #f59e0b
• Berhasil: #16a34a
• Latar halaman: #f9fafb
• Latar kartu: #ffffff

Ini hanya saran, bukan keharusan. Ganti dengan palet merek Anda sendiri dan Lily akan menyesuaikan dengan senang hati.

Tema siap pakai

Tidak ingin menulis CSS dari awal? Lily menyertakan 45 tema acuan mandiri di direktori themes/. Masing-masing adalah satu stylesheet yang menargetkan kelas pengait Lily — tautkan dan tampilan Anda langsung tertata:

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

Kumpulan ini mencakup:

• Sektor publik — NHS England, NHS Scotland, dan NHS Wales (masing-masing varian untuk pasien dan praktisi), GOV.UK GDS, dan Sistem Desain Web AS.
• Terinspirasi vendor — Adobe Spectrum, Mozilla Protocol.
• Serbaguna — terang, gelap, nord, dracula, wireframe, dan tiga puluhan lainnya.

Selektor tema memakai :where(...), sehingga CSS Anda sendiri selalu menang dalam hal spesifisitas. Padukan dengan asisten theme-picker di bawah untuk pergantian saat runtime, atau ikuti tutorial tema.

Asisten preferensi

Setiap framework memiliki katalog pendamping *-helpers dengan delapan pemilih kecil (dan picker-bar yang merangkainya). Masing-masing adalah tombol ikon headless yang membuka popup — daftar pilihan, daftar tautan, formulir pencarian, atau (untuk date-time-picker) dialog pemilih tanggal — bukan <select> native; aman untuk SSR; dan tidak menyertakan CSS:

• theme-picker — memuat stylesheet tema saat runtime dengan menukar <link> yang dikelola, mengatur data-theme pada dokumen, dan secara opsional menyimpannya ke localStorage.
• locale-picker — mengatur lang dan dir (dengan deteksi otomatis kanan-ke-kiri) agar pustaka i18n Anda dapat mengikuti; tidak melakukan penerjemahan sendiri.
• text-size-picker — mengatur data-text-size pada dokumen; CSS Anda memetakan setiap nilai ke ukuran huruf.
• motion-picker — mengatur data-motion pada dokumen, dimulai dari pengaturan pengurangan gerak pengunjung; CSS dan skrip Anda yang menentukan apa yang ditekan.
• search-picker — tombol ikon yang membuka kolom pencarian; pengiriman menavigasi ke halaman pencarian. Memegang sebuah aksi, bukan preferensi.
• link-picker — ikon beranda yang membuka menu tautan halaman yang ditetapkan aplikasi Anda (Beranda, Tentang Kami, Hubungi Kami, Kebijakan Privasi, …). Memegang sebuah aksi, bukan preferensi.
• share-picker — membuka lembar berbagi native atau daftar tujuan dari konsumen, ditambah salin-URL. Memegang sebuah aksi, bukan preferensi: tidak menerapkan apa pun, tidak menyimpan apa pun.
• date-time-picker — kolom teks ditambah dialog pemilih tanggal APG untuk tanggal, waktu, atau keduanya. Memegang nilai formulir, bukan preferensi: string ISO bolak-balik dengan <input type="date">.

git clone https://github.com/LilyDesignSystem/lily-design-system-svelte-helpers

Katalog Svelte adalah acuan kanonis; port React, Vue, Angular, HTML, Nunjucks, Web Components, dan Blazor mencocokkannya kontrak demi kontrak. Lihat tutorial asisten.

Aksesibilitas

Komponen menargetkan WCAG 2.2 AAA. Komponen mengikuti pola berikut:

• Elemen HTML semantik alih-alih <div> generik.
• <label for="id"> yang menghubungkan label ke input.
• aria-labelledby / aria-describedby untuk rujukan silang.
• aria-invalid + aria-errormessage untuk status galat.
• role="alert" dan aria-live untuk konten dinamis.
• aria-pressed, aria-expanded, aria-current untuk status.
• tabindex bergerak (roving) untuk kisi.

Indikator fokus sengaja disediakan oleh konsumen — Lily tidak pernah menggambar cincin fokus bawaan yang bertentangan dengan desain Anda. Aplikasi contoh mempertahankan garis dasar axe-core yang bersih di seluruh rutenya.

Internasionalisasi

Setiap label, placeholder, pesan galat, dan teks tombol adalah properti. Tidak ada teks yang tertanam di kode. Pasang framework terjemahan pilihan Anda — Paraglide, i18next, vue-i18n, react-intl, berkas .resx, apa saja.

Untuk tanggal, angka, dan mata uang, komponen menerima string yang sudah diformat: Anda memformat dengan Intl.DateTimeFormat / Intl.NumberFormat / pustaka pilihan Anda dan meneruskan hasilnya.

Asisten locale-picker memberi tahu pustaka i18n Anda tentang lokal yang dipilih dengan mengatur lang dan dir pada akar dokumen.

Pengujian

Setiap subproyek framework menyertakan pengujiannya sendiri dengan tumpukan idiomatiknya:

• HTML: WebDriverIO yang berjalan di peramban sungguhan.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (melalui plugin Vite Analog).
• Nunjucks: Vitest dengan helper render.
• Blazor: bUnit.

Pengujian hanya memakai matcher bawaan Vitest — tidak pernah matcher jest-dom. Ini menjaga rangkaian pengujian tetap portabel. Aplikasi contoh menambahkan rangkaian Playwright ujung ke ujung, garis dasar aksesibilitas axe-core, dan penyisiran ukuran jendela responsif.

Agen AI

Situs ini menerbitkan llms.txt dan llms.json di akarnya — peta terkurasi dari halaman terpentingnya, untuk perangkat apa pun yang mengikuti konvensi llms.txt.

Monorepo kanonis juga menyertakan dua Skill Claude: lily-design-system-skill, skill serbaguna yang mencakup konsep, istilah, dan pola komposisi Lily bagi siapa pun yang membangun dengan sistem ini, dan lily-design-system-maintainer-skill, skill teknis yang mencakup tata letak berkas wajib dan perangkat monorepo bagi siapa pun yang mengerjakannya. Keduanya berada di akar monorepo kanonis.

Pemecahan masalah

Berkontribusi

Lily masih muda dan menyambut kolaborasi. Kontribusi yang paling berguna saat ini adalah:

• Komponen baru (terutama pola dari sistem desain yang sudah mapan).
• Tema baru — masing-masing adalah satu stylesheet mandiri, pull request pertama yang ruang lingkupnya jelas.
• Penataan contoh yang lebih baik — tunjukkan apa yang mungkin.
• Terjemahan teks aplikasi contoh.
• Laporan bug dengan reproduksi minimal.
• Audit aksesibilitas dengan pembaca layar dan teknologi bantu.

Buka isu dan pull request di repositori terkait pada github.com/LilyDesignSystem.

Komunitas dan dukungan

• Pertanyaan dan laporan bug — buka isu di repositori terkait pada github.com/LilyDesignSystem.
• Surel — pemelihara membaca joel@joelparkerhenderson.com dan menyambut kolaborasi, bimbingan, dan masukan.
• Cermin — Lily juga didorong ke Codeberg dan GitLab, sehingga Anda dapat berpartisipasi dari platform pilihan Anda.
• Perilaku — proyek ini mengikuti kode etik standar; bersikaplah baik, berprasangka baiklah.

FAQ