Lilyn käytön aloittaminen

Asennus

Lily asuu yhdessä Git-monorepossa, jossa on hakemisto jokaisen kehyksen päättömälle kirjastolle, apupaketeille ja esimerkkisovellukselle. Nopein tapa kokeilla on kloonata monorepo ja avata oman pinosi päätön kirjasto:

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

Sama malli toimii muille kehyksille:

• @lilydesignsystem/html-headless – asennusta ei tarvita; kopioi .html -tiedostot
• @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

Päättömät kirjastot on suunniteltu kloonattaviksi tai kopioitaviksi projektiin – pidä lähdekoodia totuuden lähteenä ja kopioi tarvitsemasi. asetusapurit toimitetaan lisäksi asennettavina paketteina rakennus- ja julkaisuputkella (npm JS-kehyksille, NuGet Blazorille).

Päättömän komponentin käyttö

Päättömät komponentit sisältävät semanttisen HTML:n, ARIA:n ja ominaisuudet – mutta eivät CSS:ää. Tässä Button kussakin kehyksessä:

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" }) }}

Tyylitellyn esimerkin käyttö

Esimerkkisovellukset sisältävät CSS:n, reitit ja täydet demosivut. Nopein tapa kokeilla on käynnistää SvelteKit-, Next-, Nuxt-, Analog- tai Eleventy-esimerkkisovellus ja katsoa demoa osoitteessa /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

Avaa sitten http://localhost:5173 ja selaa /components.

Tyylittely ja suunnittelutunnisteet

Jokainen komponentti renderöidään yhdellä kebab-case-luokalla juurielementissään. Esimerkiksi <Button> renderöityy muotoon <button class="button">. Tyylittele se haluamallasi tavalla:

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

Lilyn oletusvaripaletti (käytössä esimerkkisovelluksissa) on:

• Ensisijainen: #2563eb
• Vaara: #dc2626
• Varoitus: #f59e0b
• Onnistuminen: #16a34a
• Sivun tausta: #f9fafb
• Kortin tausta: #ffffff

Nämä ovat ehdotuksia, eivät vaatimuksia. Korvaa ne oman brändisi paletilla, niin Lily seuraa mukana mielellään.

Valmiit teemat

Etkö halua kirjoittaa CSS:ää alusta alkaen? Lily toimittaa 57 itsenäistä viiteteemaa hakemistossa themes/ . Jokainen on yksi tyylitiedosto, joka kohdistuu Lilyn luokkakoukkuihin – linkitä se, ja olet tyylitelty:

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

Joukko kattaa:

• Julkinen sektori – NHS England, NHS Scotland ja NHS Wales (kukin potilas- ja ammattilaisversiona), GOV.UK GDS ja U.S. Web Design System.
• Toimittajista innoituksensa saaneet – Adobe Spectrum, Mozilla Protocol.
• Yleiskäyttöiset – light, dark, nord, dracula, wireframe ja parikymmentä muuta.

Teemavalitsimet käyttävät :where(...):ia, joten oma CSS:äsi voittaa aina spesifisyydessä. Yhdistä ne alla olevaan theme-picker -apuriin ajonaikaista vaihtoa varten tai seuraa teemaopetusohjelmaa.

Asetusapurit

Jokaisella kehyksellä on kahdeksan pientä valitsinta, kukin omana lily-design-system-{framework}-{package} -pakettinaan (ja picker-bar , joka kokoaa ne yhteen). Jokainen on päätön kuvakepainike, joka avaa ponnahdusikkunan – luettelon, linkkiluettelon, hakulomakkeen tai (date-time-pickerin tapauksessa) päivämäärävalintaikkunan – ei natiivi <select>; on SSR-turvallinen; eikä sisällä CSS:ää:

• theme-picker – lataa teemojen tyylitiedostot ajon aikana vaihtamalla hallittua <link>:ia, asettaa data-theme -attribuutin dokumentille ja tallentaa halutessa kohteeseen localStorage.
• locale-picker – asettaa lang ja dir (automaattisella RTL-tunnistuksella), jotta i18n-kirjastosi voi seurata; ei käännä itse mitään.
• text-size-picker – asettaa data-text-size -attribuutin dokumentille; CSS:äsi kohdistaa jokaisen arvon fonttikokoon.
• motion-picker – asettaa data-motion -attribuutin dokumentille lähtien kävijän vähennetyn liikkeen asetuksesta; CSS:äsi ja skriptisi päättävät, mitä vaimennetaan.
• search-picker – kuvakepainike, joka avaa hakukentän; lähettäminen siirtyy hakusivulle. Omistaa toiminnon, ei asetusta.
• link-picker – kotikuvake, joka avaa valikon sovelluksesi määrittelemistä sivulinkeistä (Etusivu, Tietoa meistä, Ota yhteyttä, Tietosuojakäytäntö, …). Omistaa toiminnon, ei asetusta.
• share-picker – avaa natiivin jakoikkunan tai kuluttajan antaman kohdeluettelon sekä URL:n kopioinnin. Omistaa toiminnon, ei asetusta: ei sovella mitään, ei tallenna mitään.
• date-time-picker – tekstikenttä ja APG-päivämäärävalintaikkuna päivämäärälle, ajalle tai molemmille. Omistaa lomakkeen arvon, ei asetusta: ISO-merkkijono muuntuu edestakaisin muotoon <input type="date">.

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

Svelte-luettelo on kanoninen viite; React-, Vue-, Angular-, HTML-, Nunjucks-, Web Components- ja Blazor-portit vastaavat sitä sopimus sopimukselta. Katso apuriopetusohjelma.

Saavutettavuus

Komponentit tavoittelevat WCAG 2.2 AAA-tasoa. Ne noudattavat näitä malleja:

• Semanttiset HTML-elementit yleisten <div>s.
• <label for="id"> -elementtien sijaan, jotka yhdistävät nimiöt syötteisiin.
• aria-labelledby / aria-describedby ristiviittauksiin.
• aria-invalid + aria-errormessage virhetiloihin.
• role="alert" ja aria-live dynaamiseen sisältöön.
• aria-pressed, aria-expanded, aria-current tilaan.
• Liikkuva tabindex ruudukoille.

Kohdistuksen ilmaisimet ovat tarkoituksella kuluttajan toimittamia – Lily ei koskaan piirrä oletuskohdistusrengasta, joka olisi ristiriidassa suunnittelusi kanssa. Esimerkkisovellukset pitävät puhtaan axe-core-perustason kaikilla reiteillään.

Kansainvälistäminen

Jokainen nimiö, paikkamerkki, virheilmoitus ja painiketeksti on ominaisuus. Kovakoodattuja merkkijonoja ei ole. Liitä valitsemasi käännyskehys – Paraglide, i18next, vue-i18n, react-intl, .resx-tiedostot, mikä tahansa.

Päivämäärille, luvuille ja valuutoille komponentit hyväksyvät valmiiksi muotoiltuja merkkijonoja: muotoilet itse käyttäen Intl.DateTimeFormat / Intl.NumberFormat / haluamaasi kirjastoa ja välität tuloksen.

Apuri locale-picker ilmoittaa valitun kielen i18n-kirjastollesi asettamalla lang ja dir dokumentin juureen.

Testaus

Jokainen kehyksen aliprojekti toimittaa omat testinsä käyttäen sen omaa tyypillistä pinoa:

• HTML: WebDriverIO, joka ajaa oikeita selaimia.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (Analog Vite -laajennuksen kautta).
• Nunjucks: Vitest renderöintiapurilla.
• Blazor: bUnit.

Testit käyttävät vain Vitestin sisäänrakennettuja vertaajia – ei koskaan jest-dom -vertaajia. Tämä pitää testisarjat siirrettävinä. Esimerkkisovellukset lisäävät Playwright-päästä päähän -sarjat, axe-core-saavutettavuusperustasot ja responsiivisen näkymäalueen läpikäynnin.

Tekoälyagentit

Tämä sivusto julkaisee llms.txt ja llms.json juuressaan – kuratoidun kartan tärkeimmistä sivuistaan, mille tahansa työkalulle, joka noudattaa llms.txt-käytäntöä.

Kanoninen monorepo toimittaa lisäksi kaksi Claude Skills: lily-design-system-skill: yleiskäyttöinen taito, joka kattaa Lilyn käsitteet, terminologian ja kokoamismallit kaikille, jotka rakentavat järjestelmällä, ja lily-design-system-maintainer-skill, tekninen taito, joka kattaa monorepon pakollisten tiedostojen rakenteen ja työkalut kaikille, jotka työskentelevät sen parissa. Molemmat sijaitsevat kanonisen monorepon juuressa.

Vianmääritys

Osallistuminen

Lily on nuori ja toivottaa yhteistyön tervetulleeksi. Hyödyllisimmät panokset juuri nyt ovat:

• Uudet komponentit (erityisesti vakiintuneiden suunnittelujärjestelmien mallit).
• Uudet teemat – kukin on yksi itsenäinen tyylitiedosto, hyvin rajattu ensimmäinen PR.
• Parempi esimerkkien tyylittely – näytä, mikä on mahdollista.
• Esimerkkisovellusten merkkijonojen käännökset.
• Virheraportit minimaalisella toistotavalla.
• Saavutettavuusauditoinnit näytönlukijoilla ja apuvälineteknologialla.

Avaa issuet ja PR:t osoitteessa github.com/LilyDesignSystem/lily-design-system.

Yhteisö ja tuki

• Kysymykset ja virheraportit – avaa issue osoitteessa github.com/LilyDesignSystem/lily-design-system.
• Sähköposti – ylläpitäjä lukee osoitetta joel@joelparkerhenderson.com ja toivottaa tervetulleeksi yhteistyön, ohjauksen ja palautteen.
• Peilit – Lily työnnetään myös palveluihin Codeberg ja GitLab, jotta voit osallistua haluamastasi forgesta.
• Käytös – projekti noudattaa tavallista käytännesääntöä; ole ystävällinen, oleta hyvää tahtoa.

UKK