Dechrau gyda Lily

Gosod

Cyhoeddir Lily fel repos Git ar wahân ar gyfer pob fframwaith. Y ffordd gyflymaf o'i drio yw clonio'r repo headless ar gyfer eich pentwr:

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

Mae'r un patrwm yn gweithio ar gyfer y fframweithiau eraill:

• @lilydesignsystem/html-headless — dim angen gosod; copïwch ffeiliau .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

Cynlluniwyd y llyfrgelloedd headless i'w clonio neu eu hymgorffori — trinwch y ffynhonnell fel y ffynhonnell gwirionedd a chopïwch yr hyn sydd ei angen arnoch. Mae'r cynorthwywyr dewisiadau hefyd yn cael eu cludo fel pecynnau y gellir eu gosod, gyda llinell adeiladu a chyhoeddi (npm ar gyfer y fframweithiau JS, NuGet ar gyfer Blazor).

Defnyddio cydran headless

Mae cydrannau headless yn cludo HTML semantig, ARIA, a phriodweddau — ond dim CSS. Dyma Fotwm ym mhob fframwaith:

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

Defnyddio enghraifft wedi'i harddullio

Mae'r apiau enghreifftiol yn cynnwys CSS, llwybrau, a thudalennau arddangos llawn. Y ffordd gyflymaf i arbrofi yw cychwyn yr ap enghreifftiol SvelteKit, Next, Nuxt, Analog, neu Eleventy a gweld yr arddangosiad yn /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

Yna agorwch http://localhost:5173 a phorwch /components.

Arddullio a thocynnau dylunio

Mae pob cydran yn rendro gydag un dosbarth kebab-case ar ei helfen wraidd. Er enghraifft, mae <Button> yn rendro <button class="button">. Arddullwch hi sut bynnag y dymunwch:

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

Palet lliwiau rhagosodedig Lily (a ddefnyddir yn yr apiau enghreifftiol) yw:

• Cynradd: #2563eb
• Perygl: #dc2626
• Rhybudd: #f59e0b
• Llwyddiant: #16a34a
• Cefndir tudalen: #f9fafb
• Cefndir cerdyn: #ffffff

Awgrymiadau yw'r rhain, nid gofynion. Amnewidiwch nhw gyda phalet eich brand eich hun a bydd Lily yn dod yn ei flaen yn hapus.

Themâu parod

Ddim eisiau ysgrifennu CSS o'r dechrau? Mae Lily yn cludo 45 thema gyfeirio annibynnol yn y cyfeiriadur themes/ Mae pob un yn un daflen arddull sy'n targedu bachau dosbarth Lily — cysylltwch â hi ac rydych wedi'ch arddullio:

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

Mae'r set yn cynnwys:

• Sector cyhoeddus — GIG Lloegr, GIG yr Alban, a GIG Cymru (amrywiadau sy'n wynebu cleifion ac sy'n wynebu ymarferwyr ar gyfer pob un), GOV.UK GDS, a System Dylunio Gwe yr Unol Daleithiau.
• Wedi'u hysbrydoli gan werthwyr — Adobe Spectrum, Mozilla Protocol.
• Pwrpas cyffredinol — light, dark, nord, dracula, wireframe, a thri deg a mwy yn ychwaneg.

Mae dewiswyr themâu yn defnyddio :where(...), felly mae eich CSS eich hun bob amser yn ennill o ran penodolrwydd. Pârwch nhw â'r cynorthwyydd theme-picker isod ar gyfer newid wrth redeg, neu dilynwch y tiwtorial themeiddio.

Cynorthwywyr dewisiadau

Mae gan bob fframwaith gatalog *-helpers cydymaith gydag wyth dewiswr bach (a picker-bar sy'n eu cydosod). Mae pob un yn fotwm eicon headless sy'n agor ffenestr naid — rhestrfocs, rhestr o gysylltiadau, ffurflen chwilio, neu (ar gyfer date-time-picker) deialog dewis dyddiad — nid <select> brodorol; mae'n ddiogel ar gyfer SSR; ac nid yw'n cludo unrhyw CSS:

• theme-picker — yn llwytho taflenni arddull themâu wrth redeg trwy gyfnewid <link> a reolir, yn gosod data-theme ar y ddogfen, ac yn dewisol yn cadw i localStorage.
• locale-picker — yn gosod lang a dir (gyda chanfod RTL awtomatig) fel y gall eich llyfrgell i18n ddilyn; nid yw'n cyfieithu ei hun.
• text-size-picker — yn gosod data-text-size ar y ddogfen; mae eich CSS yn mapio pob gwerth i faint ffont.
• motion-picker — yn gosod data-motion ar y ddogfen, gan ddechrau o osodiad symudiad llai'r ymwelydd; mae eich CSS a'ch sgriptiau yn penderfynu beth i'w atal.
• search-picker — botwm eicon sy'n agor maes chwilio; mae cyflwyno yn llywio i dudalen chwilio. Mae'n berchen ar weithred, nid dewis.
• link-picker — eicon cartref sy'n agor dewislen o'r cysylltiadau tudalen y mae eich ap yn eu diffinio (Hafan, Amdanom Ni, Cysylltu â Ni, Polisi Preifatrwydd, …). Mae'n berchen ar weithred, nid dewis.
• share-picker — yn agor y daflen rannu frodorol neu restr cyrchfannau a ddarperir gan y defnyddiwr, ynghyd â chopïo'r URL. Mae'n berchen ar weithred, nid dewis: nid yw'n gosod dim, nid yw'n cadw dim.
• date-time-picker — maes testun ynghyd â deialog dewis dyddiad APG ar gyfer dyddiad, amser, neu'r ddau. Mae'n berchen ar werth ffurflen, nid dewis: mae'r llinyn ISO yn teithio'n ôl ac ymlaen i <input type="date">.

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

Catalog Svelte yw'r cyfeirnod canonaidd; mae porthladdoedd React, Vue, Angular, HTML, Nunjucks, Web Components, a Blazor yn cyfateb iddo cytundeb wrth gytundeb. Gweler y tiwtorial cynorthwywyr.

Hygyrchedd

Mae cydrannau'n anelu at WCAG 2.2 AAA. Maen nhw'n dilyn y patrymau hyn:

• Elfennau HTML semantig yn hytrach na <div>s generig.
• <label for="id"> yn cysylltu labeli â mewnbynnau.
• aria-labelledby / aria-describedby ar gyfer croesgyfeiriadau.
• aria-invalid + aria-errormessage ar gyfer cyflyrau gwall.
• role="alert" and aria-live ar gyfer cynnwys deinamig.
• aria-pressed, aria-expanded, aria-current ar gyfer cyflwr.
• tabindex crwydrol ar gyfer gridiau.

Mae dangosyddion ffocws yn cael eu darparu gan y defnyddiwr yn fwriadol — nid yw Lily byth yn paentio cylch ffocws rhagosodedig sy'n gwrthdaro â'ch dyluniad. Mae'r apiau enghreifftiol yn cadw llinell sylfaen axe-core lân ar draws eu llwybrau.

Rhyngwladoli

Mae pob label, dalfan, neges gwall, a thestun botwm yn briodwedd. Nid oes unrhyw linynnau wedi'u codio'n galed. Gollyngwch eich fframwaith cyfieithu dewisol i mewn — Paraglide, i18next, vue-i18n, react-intl, ffeiliau .resx, unrhyw beth.

Ar gyfer dyddiadau, rhifau, ac arian cyfred, mae'r cydrannau'n derbyn llinynnau wedi'u fformatio ymlaen llaw: rydych chi'n fformatio gyda Intl.DateTimeFormat / Intl.NumberFormat / eich llyfrgell ddewisol ac yn pasio'r canlyniad.

Mae'r cynorthwyydd locale-picker yn arwyddo'r locale a ddewiswyd i'ch llyfrgell i18n trwy osod lang a dir ar wraidd y ddogfen.

Profi

Mae pob is-brosiect fframwaith yn cludo ei brofion ei hun gan ddefnyddio ei bentwr idiomatig:

• HTML: WebDriverIO yn rhedeg porwyr go iawn.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (via the Analog Vite plugin).
• Nunjucks: Vitest with a render helper.
• Blazor: bUnit.

Mae profion yn defnyddio paswyr adeiledig Vitest yn unig — byth jest-dom paswyr. Mae hyn yn cadw'r cyfresi profion yn gludadwy. Mae'r apiau enghreifftiol yn ychwanegu cyfresi Playwright o un pen i'r llall, llinellau sylfaen hygyrchedd axe-core, a ysgubiad porthladd gweld ymatebol.

Asiantau AI

Mae'r wefan hon yn cyhoeddi llms.txt and llms.json yn ei gwraidd — map wedi'i guradu o'i thudalennau pwysicaf, ar gyfer unrhyw offeryn sy'n dilyn confensiwn llms.txt.

Mae'r monorepo canonaidd hefyd yn cludo dau Sgil Claude: lily-design-system-skill, sgil pwrpas cyffredinol sy'n cwmpasu cysyniadau, terminoleg, a phatrymau cyfansoddi Lily ar gyfer unrhyw un sy'n adeiladu gyda'r system, a lily-design-system-maintainer-skill, sgil technegol sy'n cwmpasu cynllun ffeiliau gofynnol y monorepo a'r offer ar gyfer unrhyw un sy'n gweithio arno. Mae'r ddau yn byw yng ngwraidd y monorepo canonaidd.

Datrys problemau

Cyfrannu

Mae Lily yn ifanc ac yn croesawu cydweithio. Y cyfraniadau mwyaf defnyddiol ar hyn o bryd yw:

• Cydrannau newydd (yn enwedig patrymau o systemau dylunio sefydledig).
• Themâu newydd — mae pob un yn un daflen arddull annibynnol, PR cyntaf wedi'i gwmpasu'n dda.
• Gwell arddullio enghreifftiau — dangoswch yr hyn sy'n bosibl.
• Cyfieithiadau o linynnau'r apiau enghreifftiol.
• Adroddiadau namau gydag atgynhyrchiad lleiaf.
• Archwiliadau hygyrchedd gyda darllenwyr sgrin a thechnoleg gynorthwyol.

Agorwch issues a PRs yn erbyn y repo perthnasol yn github.com/LilyDesignSystem.

Cymuned a chymorth

• Cwestiynau ac adroddiadau namau — agorwch issue ar y repo perthnasol yn github.com/LilyDesignSystem.
• E-bost — mae'r cynhaliwr yn darllen joel@joelparkerhenderson.com ac yn croesawu cydweithio, arweiniad, ac adborth.
• Drychau — mae Lily hefyd yn cael ei wthio i Codeberg and GitLab, fel y gallwch gymryd rhan o'r efail sydd orau gennych.
• Ymddygiad — mae'r prosiect yn dilyn cod ymddygiad safonol; byddwch yn garedig, rhagdybiwch ewyllys da.

Cwestiynau cyffredin