Bidu ma’ Lily

Installazzjoni

Lily tgħix f’monorepo wieħed ta’ Git, b’direttorju għal-librerija headless, il-pakketti tal-għajnuna u l-applikazzjoni ta’ eżempju ta’ kull framework. L-aktar mod mgħaġġel biex tipprovaha huwa li tikklona l-monorepo u tiftaħ il-librerija headless għall-istack tiegħek:

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

L-istess xejra taħdem għall-frameworks l-oħra:

• @lilydesignsystem/html-headless — l-ebda installazzjoni meħtieġa; ikkopja l-fajls .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

Il-libreriji headless huma ddisinjati biex jiġu kklonati jew inkorporati — ittratta l-kodiċi sors bħala s-sors tal-verità u ikkopja dak li għandek bżonn. għajnuniet tal-preferenzi jiġu wkoll bħala pakketti installabbli b’pipeline tal-bini u tal-pubblikazzjoni (npm għall-frameworks JS, NuGet għal Blazor).

Uża komponent headless

Il-komponenti headless jipprovdu HTML semantiku, ARIA u proprjetajiet — imma l-ebda CSS. Hawn Button f’kull 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" }) }}

Uża eżempju stilizzat

L-applikazzjonijiet ta’ eżempju jinkludu CSS, rotot u paġni demo sħaħ. L-aktar mod mgħaġġel biex tesperimenta huwa li tibda l-applikazzjoni ta’ eżempju SvelteKit, Next, Nuxt, Analog jew Eleventy u tara d-demo fuq /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

Imbagħad iftaħ http://localhost:5173 u esplora /components.

Stilizzazzjoni u tokens tad-disinn

Kull komponent jiġi renderjat b’klassi waħda f’kebab-case fuq l-element għerq tiegħu. Pereżempju, <Button> jiġi renderjat bħala <button class="button">. Stilizzah kif trid:

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

Il-paletta tal-kuluri awtomatika ta’ Lily (użata fl-applikazzjonijiet ta’ eżempju) hija:

• Primarju: #2563eb
• Periklu: #dc2626
• Twissija: #f59e0b
• Suċċess: #16a34a
• Isfond tal-paġna: #f9fafb
• Isfond tal-kard: #ffffff

Dawn huma suġġerimenti, mhux rekwiżiti. Ibdilhom bil-paletta tal-marka tiegħek stess u Lily tikkonforma bil-ferħ.

Temi lesti

Ma tridx tikteb CSS mill-bidu? Lily tibgħat 57 tema ta’ referenza awtonoma fid-direttorju themes/ . Kull waħda hija stylesheet wieħed li jimmira lejn il-ganċijiet tal-klassi ta’ Lily — qabbdu u int stilizzat:

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

Is-sett ikopri:

• Settur pubbliku — NHS England, NHS Scotland u NHS Wales (kull waħda f’varjanti għall-pazjenti u għall-prattikanti), GOV.UK GDS u l-U.S. Web Design System.
• Ispirati mill-bejjiegħa — Adobe Spectrum, Mozilla Protocol.
• Użu ġenerali — light, dark, nord, dracula, wireframe u tletin oħra jew hekk.

Is-selectors tat-temi jużaw :where(...), għalhekk is-CSS tiegħek stess dejjem jirbaħ fl-ispeċifiċità. Akkoppjahom mal-għajnuna theme-picker hawn taħt għat-tibdil waqt it-tħaddim, jew segwi tutorja tat-temi.

Għajnuniet tal-preferenzi

Kull framework għandu tmien għażliet żgħar, kull wieħed pakkett lily-design-system-{framework}-{package} tiegħu stess (u picker-bar li jiġbor flimkien). Kull wieħed huwa buttuna headless b’ikona li tiftaħ popup — listbox, lista ta’ links, formola tat-tfittxija jew (għal date-time-picker) dijalogu tal-għażla tad-data — mhux <select>nattiv; huwa sigur għal SSR; u ma jibgħatx CSS:

• theme-picker — jgħabbi stylesheets tat-temi waqt it-tħaddim billi jibdel <link>ġestit, jistabbilixxi data-theme fuq id-dokument u b’mod fakultattiv jiffranka f’ localStorage.
• locale-picker — jistabbilixxi lang u dir (b’skoperta awtomatika tal-RTL) biex il-librerija i18n tiegħek tkun tista’ ssegwi; ma jittraduċi xejn waħdu.
• text-size-picker — jistabbilixxi data-text-size fuq id-dokument; is-CSS tiegħek jimmappja kull valur għad-daqs tal-font.
• motion-picker — jistabbilixxi data-motion fuq id-dokument, jibda mill-issettjar tal-moviment imnaqqas tal-viżitatur; is-CSS u l-iscripts tiegħek jiddeċiedu x’għandu jiġi mrażżan.
• search-picker — buttuna b’ikona li tiftaħ qasam tat-tfittxija; is-sottomissjoni tmur fuq paġna tat-tfittxija. Hija sid ta’ azzjoni, mhux preferenza.
• link-picker — ikona tad-dar li tiftaħ menu tal-links tal-paġni li l-applikazzjoni tiegħek tiddefinixxi (Home, Dwarna, Ikkuntattjana, Politika tal-Privatezza, …). Hija sid ta’ azzjoni, mhux preferenza.
• share-picker — tiftaħ il-folja nattiva tal-qsim jew lista ta’ destinazzjonijiet ipprovduta mill-konsumatur, flimkien mal-kopja tal-URL. Hija sid ta’ azzjoni, mhux preferenza: ma tapplika xejn, ma tiffranka xejn.
• date-time-picker — qasam tat-test flimkien ma’ dijalogu APG tal-għażla tad-data għal data, ħin, jew it-tnejn. Hija sid ta’ valur ta’ formola, mhux preferenza: is-sekwenza ISO tinbidel bidirezzjonalment għal <input type="date">.

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

Il-katalgu Svelte huwa r-referenza kanonika; il-ports ta’ React, Vue, Angular, HTML, Nunjucks, Web Components u Blazor jaqblu miegħu kuntratt b’kuntratt. Ara t- tutorja tal-għajnuniet.

Aċċessibbiltà

Il-komponenti jimmiraw lejn WCAG 2.2 AAA. Isegwu dawn ix-xejriet:

• Elementi HTML semantiċi minflok <div>s.
• <label for="id"> ġeneriċi li jorbtu t-tikketti mal-inputs.
• aria-labelledby / aria-describedby għal referenzi inkroċjati.
• aria-invalid + aria-errormessage għal stati ta’ żball.
• role="alert" u aria-live għal kontenut dinamiku.
• aria-pressed, aria-expanded, aria-current għall-istat.
• Roving tabindex għall-grids.

L-indikaturi tal-fokus huma apposta pprovduti mill-konsumatur — Lily qatt ma tpinġi ċirku tal-fokus awtomatiku li jmur kontra d-disinn tiegħek. L-applikazzjonijiet ta’ eżempju jżommu linja bażi axe-core nadifa fuq ir-rotot kollha tagħhom.

Internazzjonalizzazzjoni

Kull tikketta, placeholder, messaġġ ta’ żball u test ta’ buttuna hija proprjetà. M’hemmx sekwenzi miktuba direttament. Qabbad il-framework tat-traduzzjoni li tippreferi — Paraglide, i18next, vue-i18n, react-intl, fajls .resx, kwalunkwe.

Għal dati, numri u muniti, il-komponenti jaċċettaw sekwenzi ffurmattjati minn qabel: int tifformattja b’ Intl.DateTimeFormat / Intl.NumberFormat / il-librerija preferuta tiegħek u tgħaddi r-riżultat.

L-għajnuna locale-picker tgħarraf il-lokal magħżul lill-librerija i18n tiegħek billi tistabbilixxi lang u dir fuq l-għerq tad-dokument.

Ittestjar

Kull sottoproġett ta’ framework jibgħat it-testijiet tiegħu stess bl-istack idjomatiku tiegħu:

• HTML: WebDriverIO li jħaddem browsers reali.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (permezz tal-plugin Vite ta’ Analog).
• Nunjucks: Vitest b’għajnuna tar-renderjar.
• Blazor: bUnit.

It-testijiet jużaw biss il-matchers integrati ta’ Vitest — qatt il-matchers ta’ jest-dom . Dan iżomm is-suites tat-testijiet portabbli. L-applikazzjonijiet ta’ eżempju jżidu suites end-to-end ta’ Playwright, linji bażi tal-aċċessibbiltà axe-core u skannjar tal-viewports responsivi.

Aġenti AI

Dan is-sit jippubblika llms.txt u llms.json fl-għerq tiegħu — mappa kkurata tal-aktar paġni importanti tiegħu, għal kwalunkwe għodda li ssegwi l-konvenzjoni llms.txt.

Il-monorepo kanoniku jibgħat ukoll tnejn Claude Skills: lily-design-system-skill: ħila ta’ użu ġenerali li tkopri l-kunċetti, it-terminoloġija u x-xejriet ta’ kompożizzjoni ta’ Lily għal kull min jibni bis-sistema, u lily-design-system-maintainer-skill, ħila teknika li tkopri d-dispożizzjoni tal-fajls meħtieġa u l-għodod tal-monorepo għal kull min jaħdem fuqu. It-tnejn jinsabu fl-għerq tal- monorepo kanoniku.

Soluzzjoni tal-problemi

Kontribuzzjoni

Lily hija żagħżugħa u tilqa’ l-kollaborazzjoni. Il-kontribuzzjonijiet l-aktar utli bħalissa huma:

• Komponenti ġodda (speċjalment xejriet minn sistemi tad-disinn stabbiliti).
• Temi ġodda — kull wieħed huwa stylesheet wieħed awtonomu, PR tal-ewwel darba mdefinit sew.
• Stilizzazzjoni aħjar tal-eżempji — uri x’hu possibbli.
• Traduzzjonijiet tas-sekwenzi tal-applikazzjonijiet ta’ eżempju.
• Rapporti tal-bugs b’riproduzzjoni minima.
• Awditjar tal-aċċessibbiltà b’qarrejja tal-iskrin u teknoloġija assistiva.

Iftaħ issues u PRs fuq github.com/LilyDesignSystem/lily-design-system.

Komunità u appoġġ

• Mistoqsijiet u rapporti tal-bugs — iftaħ issue fuq github.com/LilyDesignSystem/lily-design-system.
• Email — il-manutentur jaqra joel@joelparkerhenderson.com u jilqa’ l-kollaborazzjoni, il-gwida u l-feedback.
• Mirrors — Lily tiġi wkoll imbuttata lejn Codeberg u GitLab, biex tkun tista’ tipparteċipa mill-forge li tippreferi.
• Kondotta — il-proġett isegwi kodiċi ta’ kondotta standard; kun ġentili, assumi bona fede.

FAQ