Pagsisimula sa Lily

I-install

Nakatira ang Lily sa isang Git monorepo, na may direktoryo para sa headless na library, mga helper package, at halimbawang app ng bawat framework. Ang pinakamabilis na paraan para subukan ito ay i-clone ang monorepo at buksan ang headless na library para sa iyong stack:

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

Gumagana ang parehong pattern para sa iba pang framework:

• @lilydesignsystem/html-headless — hindi kailangan ng install; kopyahin ang .html mga file
• @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

Ang mga headless na library ay idinisenyo para i-clone o i-vendor — ituring ang source bilang pinagmumulan ng katotohanan at kopyahin ang kailangan mo. Ang mga preference helper ay dumarating din bilang mga mai-install na package na may build at publish pipeline (npm para sa mga JS framework, NuGet para sa Blazor).

Gumamit ng headless na component

Naghahatid ang mga headless na component ng semantic HTML, ARIA, at mga prop — pero walang CSS. Narito ang isang Button sa bawat 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" }) }}

Gumamit ng halimbawang may istilo

Kasama sa mga halimbawang app ang CSS, mga ruta, at buong demo page. Ang pinakamabilis na paraan para mag-eksperimento ay simulan ang SvelteKit, Next, Nuxt, Analog, o Eleventy na halimbawang app at tingnan ang demo sa /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

Pagkatapos ay buksan ang http://localhost:5173 at mag-browse sa /components.

Istilo at mga design token

Nire-render ang bawat component na may isang kebab-case na klase sa root element nito. Halimbawa, <Button> ay nagre-render ng <button class="button">. Bigyan ito ng istilo ayon sa gusto mo:

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

Ang default na color palette ng Lily (ginagamit sa mga halimbawang app) ay:

• Primary: #2563eb
• Panganib: #dc2626
• Babala: #f59e0b
• Tagumpay: #16a34a
• Background ng pahina: #f9fafb
• Background ng card: #ffffff

Mga mungkahi ang mga ito, hindi mga kinakailangan. Palitan ang mga ito ng sarili mong brand palette at sasabay ang Lily nang masaya.

Mga handa nang tema

Ayaw mong magsulat ng CSS mula sa simula? May kasamang 57 standalone na reference na tema ang Lily sa direktoryong themes/ . Bawat isa ay isang stylesheet na tumututok sa mga class hook ng Lily — i-link ito at may istilo ka na:

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

Saklaw ng hanay:

• Pampublikong sektor — NHS England, NHS Scotland, at NHS Wales (bawat isa ay may variant para sa pasyente at practitioner), GOV.UK GDS, at ang U.S. Web Design System.
• Inspirasyon ng vendor — Adobe Spectrum, Mozilla Protocol.
• Pangkalahatang gamit — light, dark, nord, dracula, wireframe, at tatlumpung iba pa.

Gumagamit ang mga selector ng tema ng :where(...), kaya palaging mananalo ang sarili mong CSS sa specificity. Ipares ang mga ito sa theme-picker helper sa ibaba para sa runtime na pagpapalit, o sundan ang tutorial sa theming.

Mga preference helper

May walong maliliit na picker ang bawat framework, bawat isa ay nasa sarili nitong lily-design-system-{framework}-{package} package (at isang picker-bar na nag-aassemble sa kanila). Bawat isa ay headless na icon button na nagbubukas ng popup — listbox, listahan ng mga link, search form, o (para sa date-time-picker) date-picker dialog — hindi native na <select>; ligtas sa SSR; at walang kasamang CSS:

• theme-picker — naglo-load ng mga stylesheet ng tema sa runtime sa pamamagitan ng pagpapalit ng pinamamahalaang <link>, nagtatakda ng data-theme sa dokumento, at opsyonal na nagpe-persist sa localStorage.
• locale-picker — nagtatakda ng lang at dir (na may awtomatikong pagtukoy ng RTL) para masundan ito ng iyong i18n library; hindi ito mismo nagsasalin.
• text-size-picker — nagtatakda ng data-text-size sa dokumento; imamapa ng iyong CSS ang bawat halaga sa laki ng font.
• motion-picker — nagtatakda ng data-motion sa dokumento, simula sa setting ng nabawasang galaw ng bisita; ang iyong CSS at mga script ang magpapasya kung ano ang pipigilan.
• search-picker — isang icon button na nagbubukas ng search field; ang pagsumite ay nagna-navigate sa isang search page. May-ari ng isang aksyon, hindi ng preference.
• link-picker — isang home icon na nagbubukas ng menu ng mga link ng pahina na tinutukoy ng iyong app (Home, Tungkol sa Amin, Makipag-ugnayan, Patakaran sa Privacy, …). May-ari ng isang aksyon, hindi ng preference.
• share-picker — nagbubukas ng native na share sheet o listahan ng mga destinasyon na ibinigay ng consumer, kasama ang pagkopya ng URL. May-ari ng isang aksyon, hindi ng preference: walang inilalapat, walang pinapanatili.
• date-time-picker — isang text field kasama ang APG date-picker dialog para sa petsa, oras, o pareho. May-ari ng isang halaga ng form, hindi ng preference: ang ISO string ay bumabalik-balik sa <input type="date">.

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

Ang Svelte catalog ang canonical na reference; tumutugma ang mga port ng React, Vue, Angular, HTML, Nunjucks, Web Components, at Blazor dito kontrata-kontrata. Tingnan ang tutorial sa mga helper.

Accessibility

Tinututukan ng mga component ang WCAG 2.2 AAA. Sinusunod nila ang mga pattern na ito:

• Mga semantic na HTML element kaysa sa pangkalahatang <div>s.
• <label for="id"> na nag-uugnay ng mga label sa mga input.
• aria-labelledby / aria-describedby para sa mga cross-reference.
• aria-invalid + aria-errormessage para sa mga state ng error.
• role="alert" at aria-live para sa dinamikong nilalaman.
• aria-pressed, aria-expanded, aria-current para sa state.
• Roving tabindex para sa mga grid.

Sadyang ibinibigay ng consumer ang mga tagapagpahiwatig ng focus — hindi kailanman nagpipinta ang Lily ng default na focus ring na maaaring sumalungat sa disenyo mo. Pinapanatili ng mga halimbawang app ang malinis na axe-core baseline sa lahat ng ruta nila.

Internationalization

Bawat label, placeholder, mensahe ng error, at teksto ng button ay prop. Walang naka-hardcode na string. Ilagay ang iyong piniling translation framework — Paraglide, i18next, vue-i18n, react-intl, mga .resx file, anuman.

Para sa mga petsa, numero, at pera, tumatanggap ang mga component ng mga string na naka-format na: ikaw ang magfo-format gamit ang Intl.DateTimeFormat / Intl.NumberFormat / iyong paboritong library at ipapasa ang resulta.

Ang locale-picker helper ay nagsisignal ng napiling locale sa iyong i18n library sa pamamagitan ng pagtatakda ng lang at dir sa root ng dokumento.

Pagsusuri

Nagpapadala ang bawat subproject ng framework ng sarili nitong mga pagsusuri gamit ang idiomatic na stack nito:

• HTML: WebDriverIO na nagpapatakbo ng tunay na browser.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (sa pamamagitan ng Analog Vite plugin).
• Nunjucks: Vitest na may render helper.
• Blazor: bUnit.

Gumagamit ang mga pagsusuri ng mga built-in na matcher lang ng Vitest — hindi kailanman jest-dom mga matcher. Pinananatili nitong portable ang mga test suite. Nagdaragdag ang mga halimbawang app ng mga Playwright end-to-end suite, axe-core accessibility baseline, at responsive viewport sweep.

Mga AI agent

Naglalathala ang site na ito ng llms.txt at llms.json sa root nito — isang piniling mapa ng pinakamahahalagang pahina nito, para sa anumang tool na sumusunod sa kombensyon ng llms.txt.

Nagpapadala rin ang canonical na monorepo ng dalawang Claude Skills: lily-design-system-skill, isang pangkalahatang kasanayan na sumasaklaw sa mga konsepto, terminolohiya, at pattern ng komposisyon ng Lily para sa sinumang bumubuo gamit ang sistema, at lily-design-system-maintainer-skill, isang teknikal na kasanayan na sumasaklaw sa kinakailangang layout ng mga file at tooling ng monorepo para sa sinumang nagtatrabaho rito. Parehong nasa root ng canonical na monorepo.

Pag-troubleshoot

Pag-aambag

Bata pa ang Lily at malugod na tumatanggap ng pakikipagtulungan. Ang pinakakapaki-pakinabang na kontribusyon ngayon ay:

• Mga bagong component (lalo na ang mga pattern mula sa mga matatag na design system).
• Mga bagong tema — bawat isa ay isang standalone na stylesheet, mahusay ang saklaw na unang PR.
• Mas magandang istilo ng halimbawa — ipakita kung ano ang posible.
• Mga pagsasalin ng mga string ng halimbawang app.
• Mga ulat ng bug na may minimal na reproduction.
• Mga accessibility audit gamit ang screen reader at assistive tech.

Magbukas ng mga issue at PR sa github.com/LilyDesignSystem/lily-design-system.

Komunidad at suporta

• Mga tanong at ulat ng bug — magbukas ng issue sa github.com/LilyDesignSystem/lily-design-system.
• Email — binabasa ng maintainer ang joel@joelparkerhenderson.com at malugod na tinatanggap ang pakikipagtulungan, gabay, at puna.
• Mga mirror — Itinutulak din ang Lily sa Codeberg at GitLab, para makalahok ka mula sa forge na gusto mo.
• Asal — sinusunod ng proyekto ang karaniwang code of conduct; maging mabait, ipalagay ang mabuting layunin.

FAQ