Aan de slag met Lily

Installeren

Lily woont in één Git-monorepo, met een map voor de headless bibliotheek, de helperpakketten en de voorbeeldapp van elk framework. De snelste manier om het te proberen is de monorepo klonen en de headless bibliotheek voor jouw stack openen:

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

Hetzelfde patroon werkt voor de andere frameworks:

• @lilydesignsystem/html-headless – geen installatie nodig; kopieer .html -bestanden
• @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

De headless bibliotheken zijn bedoeld om te worden gekloond of gevendord – beschouw de broncode als de bron van waarheid en kopieer wat je nodig hebt. voorkeurshelpers worden bovendien geleverd als installeerbare pakketten met een build- en publicatiepijplijn (npm voor de JS-frameworks, NuGet voor Blazor).

Een headless component gebruiken

Headless componenten bevatten semantische HTML, ARIA en props – maar geen CSS. Hier is een Button in elk 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" }) }}

Een opgemaakt voorbeeld gebruiken

De voorbeeldapps bevatten CSS, routes en volledige demopagina's. De snelste manier om te experimenteren is de voorbeeldapp voor SvelteKit, Next, Nuxt, Analog of Eleventy te starten en de demo te bekijken op /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

Open dan http://localhost:5173 en blader naar /components.

Opmaak en designtokens

Elke component wordt gerenderd met één kebab-case klasse op het rootelement. Bijvoorbeeld rendert <Button> als <button class="button">. Maak het op zoals je wilt:

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

Het standaard kleurenpalet van Lily (gebruikt in de voorbeeldapps) is:

• Primair: #2563eb
• Gevaar: #dc2626
• Waarschuwing: #f59e0b
• Succes: #16a34a
• Paginaachtergrond: #f9fafb
• Kaartachtergrond: #ffffff

Dit zijn suggesties, geen vereisten. Vervang ze door je eigen merkpalet en Lily past zich vrolijk aan.

Kant-en-klare thema's

Wil je CSS niet vanaf nul schrijven? Lily levert 57 zelfstandige referentiethema's in de map themes/ . Elk is één stylesheet die de klassenhaken van Lily target – koppel het en je bent opgemaakt:

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

De set omvat:

• Publieke sector – NHS England, NHS Scotland en NHS Wales (elk met varianten voor patiënten en voor professionals), GOV.UK GDS en het U.S. Web Design System.
• Door leveranciers geïnspireerd – Adobe Spectrum, Mozilla Protocol.
• Algemeen gebruik – light, dark, nord, dracula, wireframe en nog zo'n dertig andere.

Themaselectors gebruiken :where(...), dus je eigen CSS wint altijd op specificiteit. Combineer ze met de theme-picker -helper hieronder om tijdens runtime te wisselen, of volg de themahandleiding.

Voorkeurshelpers

Elk framework heeft acht kleine kiezers, elk een eigen lily-design-system-{framework}-{package} -pakket (en een picker-bar die ze samenvoegt). Elk is een headless pictogramknop die een pop-up opent – een keuzelijst, een lijst met links, een zoekformulier of (voor date-time-picker) een datumkiezerdialoog – geen native <select>; is SSR-veilig; en bevat geen CSS:

• theme-picker – laadt themastylesheets tijdens runtime door een beheerde <link>te verwisselen, zet data-theme op het document en slaat optioneel op in localStorage.
• locale-picker – zet lang en dir (met automatische RTL-detectie) zodat je i18n-bibliotheek kan volgen; vertaalt zelf niets.
• text-size-picker – zet data-text-size op het document; jouw CSS koppelt elke waarde aan een lettergrootte.
• motion-picker – zet data-motion op het document, uitgaand van de instelling voor verminderde beweging van de bezoeker; jouw CSS en scripts bepalen wat er wordt onderdrukt.
• search-picker – een pictogramknop die een zoekveld opent; verzenden navigeert naar een zoekpagina. Beheert een actie, geen voorkeur.
• link-picker – een huispictogram dat een menu opent met de paginalinks die je app definieert (Home, Over ons, Contact, Privacybeleid, …). Beheert een actie, geen voorkeur.
• share-picker – opent het native deelvenster of een door de gebruiker aangeleverde lijst met bestemmingen, plus de URL kopiëren. Beheert een actie, geen voorkeur: past niets toe, slaat niets op.
• date-time-picker – een tekstveld plus een APG-datumkiezerdialoog voor een datum, een tijd of beide. Beheert een formulierwaarde, geen voorkeur: de ISO-tekenreeks wordt heen en weer omgezet naar <input type="date">.

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

De Svelte-catalogus is de canonieke referentie; de React-, Vue-, Angular-, HTML-, Nunjucks-, Web Components- en Blazor-poorten komen contract voor contract met hem overeen. Zie de helperhandleiding.

Toegankelijkheid

Componenten streven naar WCAG 2.2 AAA. Ze volgen deze patronen:

• Semantische HTML-elementen boven generieke <div>s.
• <label for="id"> die labels aan invoer koppelt.
• aria-labelledby / aria-describedby voor kruisverwijzingen.
• aria-invalid + aria-errormessage voor foutstatussen.
• role="alert" en aria-live voor dynamische inhoud.
• aria-pressed, aria-expanded, aria-current voor status.
• Roving tabindex voor rasters.

Focusindicatoren worden bewust door de gebruiker aangeleverd – Lily tekent nooit een standaard focusring die botst met je ontwerp. De voorbeeldapps houden een schone axe-core-basislijn aan op al hun routes.

Internationalisering

Elk label, elke plaatsaanduiding, foutmelding en knoptekst is een prop. Er zijn geen hardgecodeerde tekenreeksen. Koppel het vertaalframework van je keuze – Paraglide, i18next, vue-i18n, react-intl, .resx-bestanden, alles.

Voor datums, getallen en valuta nemen de componenten vooraf opgemaakte tekenreeksen aan: jij maakt op met Intl.DateTimeFormat / Intl.NumberFormat / je voorkeursbibliotheek en geeft het resultaat door.

De locale-picker -helper geeft de gekozen taal door aan je i18n-bibliotheek door lang en dir op de documentroot te zetten.

Testen

Elk frameworksubproject levert eigen tests met zijn idiomatische stack:

• HTML: WebDriverIO met echte browsers.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (via de Analog Vite-plug-in).
• Nunjucks: Vitest met een renderhelper.
• Blazor: bUnit.

Tests gebruiken alleen de ingebouwde matchers van Vitest – nooit jest-dom -matchers. Dat houdt de testsuites draagbaar. De voorbeeldapps voegen end-to-end-suites met Playwright, toegankelijkheidsbasislijnen met axe-core en een sweep over responsieve viewports toe.

AI-agenten

Deze site publiceert llms.txt en llms.json in zijn root – een samengestelde kaart van de belangrijkste pagina's, voor elke tool die de llms.txt-conventie.

De canonieke monorepo levert daarnaast twee Claude Skills: lily-design-system-skill: een algemene skill die de concepten, terminologie en samenstellingspatronen van Lily behandelt voor iedereen die met het systeem bouwt, en lily-design-system-maintainer-skill, een technische skill die de indeling met verplichte bestanden en de tooling van de monorepo behandelt voor iedereen die eraan werkt. Beide staan in de root van de canonieke monorepo.

Probleemoplossing

Bijdragen

Lily is jong en verwelkomt samenwerking. De nuttigste bijdragen op dit moment zijn:

• Nieuwe componenten (vooral patronen uit gevestigde designsystemen).
• Nieuwe thema's – elk is één op zichzelf staande stylesheet, een goed afgebakende eerste PR.
• Betere opmaak van voorbeelden – laat zien wat mogelijk is.
• Vertalingen van de tekenreeksen van de voorbeeldapps.
• Bugmeldingen met een minimale reproductie.
• Toegankelijkheidsaudits met schermlezers en hulptechnologie.

Open issues en PR's op github.com/LilyDesignSystem/lily-design-system.

Community en ondersteuning

• Vragen en bugmeldingen – open een issue op github.com/LilyDesignSystem/lily-design-system.
• E-mail – de beheerder leest joel@joelparkerhenderson.com en verwelkomt samenwerking, begeleiding en feedback.
• Spiegels – Lily wordt ook gepusht naar Codeberg en GitLab, zodat je kunt meedoen vanaf de forge die je prefereert.
• Gedrag – het project volgt een standaard gedragscode; wees vriendelijk en ga uit van goede trouw.

FAQ