Πρώτα βήματα με το Lily

Διάλεξε ένα πλαίσιο, κλωνοποίησε το monorepo και άνοιξε την κεφαλοχωρίς βιβλιοθήκη ή την εφαρμογή-παράδειγμά του, και ξεκίνα να συνθέτεις τις δικές σου σελίδες. Προτιμάς καθοδηγούμενη διαδρομή; Ξεκίνα με τα σεμινάρια.

Εγκατάσταση

Το Lily ζει σε ένα μόνο monorepo Git, με έναν κατάλογο για την κεφαλοχωρίς βιβλιοθήκη, τα βοηθητικά πακέτα και την εφαρμογή-παράδειγμα κάθε πλαισίου. Ο ταχύτερος τρόπος να το δοκιμάσεις είναι να κλωνοποιήσεις το monorepo και να ανοίξεις την κεφαλοχωρίς βιβλιοθήκη για τη στοίβα σου:

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

Το ίδιο μοτίβο ισχύει και για τα υπόλοιπα πλαίσια:

@lilydesignsystem/html-headless — δεν χρειάζεται εγκατάσταση· αντίγραψε τα αρχεία .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

Οι κεφαλοχωρίς βιβλιοθήκες σχεδιάστηκαν για να κλωνοποιούνται ή να ενσωματώνονται — θεώρησε τον πηγαίο κώδικα πηγή αλήθειας και αντίγραψε ό,τι χρειάζεσαι. βοηθοί προτιμήσεων παρέχονται επιπλέον ως εγκαταστάσιμα πακέτα με αγωγό δόμησης και δημοσίευσης (npm για τα πλαίσια JS, NuGet για το Blazor).

Χρήση κεφαλοχωρίς στοιχείου

Τα κεφαλοχωρίς στοιχεία παρέχουν σημασιολογικό HTML, ARIA και ιδιότητες — αλλά όχι CSS. Να ένα Button σε κάθε πλαίσιο:

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

Χρήση μορφοποιημένου παραδείγματος

Οι εφαρμογές-παραδείγματα περιλαμβάνουν CSS, διαδρομές και πλήρεις σελίδες επίδειξης. Ο ταχύτερος τρόπος πειραματισμού είναι να ξεκινήσεις την εφαρμογή-παράδειγμα SvelteKit, Next, Nuxt, Analog ή Eleventy και να δεις την επίδειξη στο /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

Έπειτα άνοιξε το http://localhost:5173 και περιηγήσου στο /components.

Μορφοποίηση και design tokens

Κάθε στοιχείο αποδίδεται με μία μόνο κλάση kebab-case στο ριζικό του στοιχείο. Για παράδειγμα, το <Button> αποδίδεται ως <button class="button">. Μορφοποίησέ το όπως θέλεις:

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

Η προεπιλεγμένη παλέτα χρωμάτων του Lily (που χρησιμοποιείται στις εφαρμογές-παραδείγματα) είναι:

Πρωτεύον: #2563eb
Κίνδυνος: #dc2626
Προειδοποίηση: #f59e0b
Επιτυχία: #16a34a
Φόντο σελίδας: #f9fafb
Φόντο κάρτας: #ffffff

Αυτές είναι προτάσεις, όχι απαιτήσεις. Αντικατάστησέ τες με την παλέτα της δικής σου επωνυμίας και το Lily ακολουθεί με χαρά.

Έτοιμα θέματα

Δεν θέλεις να γράψεις CSS από το μηδέν; Το Lily περιλαμβάνει 57 αυτόνομα θέματα αναφοράς στον κατάλογο themes/ . Καθένα είναι ένα φύλλο στυλ που στοχεύει τα αγκίστρια κλάσεων του Lily — σύνδεσέ το και είσαι μορφοποιημένος:

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

Το σύνολο καλύπτει:

Δημόσιος τομέας — NHS England, NHS Scotland και NHS Wales (το καθένα σε παραλλαγές για ασθενείς και για επαγγελματίες), GOV.UK GDS και το U.S. Web Design System.
Εμπνευσμένα από προμηθευτές — Adobe Spectrum, Mozilla Protocol.
Γενικής χρήσης — light, dark, nord, dracula, wireframe και άλλα τριάντα περίπου.

Οι επιλογείς θεμάτων χρησιμοποιούν :where(...), οπότε το δικό σου CSS κερδίζει πάντα στην ειδικότητα. Συνδύασέ τα με τον βοηθό theme-picker παρακάτω για εναλλαγή κατά την εκτέλεση ή ακολούθησε το σεμινάριο θεμάτων.

Βοηθοί προτιμήσεων

Κάθε πλαίσιο έχει οκτώ μικρούς επιλογείς, καθένας δικό του πακέτο lily-design-system-{framework}-{package} (και ένα picker-bar που τους συναρμολογεί). Καθένας είναι ένα κεφαλοχωρίς κουμπί εικονιδίου που ανοίγει αναδυόμενο παράθυρο — λίστα επιλογής, λίστα συνδέσμων, φόρμα αναζήτησης ή (για το date-time-picker) διάλογο επιλογής ημερομηνίας — όχι εγγενές <select>· είναι ασφαλής για SSR· και δεν περιλαμβάνει CSS:

theme-picker — φορτώνει φύλλα στυλ θεμάτων κατά την εκτέλεση αλλάζοντας ένα διαχειριζόμενο <link>, ορίζει το data-theme στο έγγραφο και προαιρετικά αποθηκεύει σταθερά στο localStorage.
locale-picker — ορίζει τα lang και dir (με αυτόματη ανίχνευση RTL) ώστε η βιβλιοθήκη i18n σου να ακολουθεί· δεν μεταφράζει τίποτα μόνο του.
text-size-picker — ορίζει το data-text-size στο έγγραφο· το CSS σου αντιστοιχίζει κάθε τιμή σε μέγεθος γραμματοσειράς.
motion-picker — ορίζει το data-motion στο έγγραφο, ξεκινώντας από τη ρύθμιση μειωμένης κίνησης του επισκέπτη· το CSS και τα scripts σου αποφασίζουν τι θα καταστείλουν.
search-picker — ένα κουμπί εικονιδίου που ανοίγει πεδίο αναζήτησης· η υποβολή οδηγεί σε σελίδα αναζήτησης. Κατέχει μια ενέργεια, όχι μια προτίμηση.
link-picker — ένα εικονίδιο σπιτιού που ανοίγει μενού με τους συνδέσμους σελίδων που ορίζει η εφαρμογή σου (Αρχική, Σχετικά με εμάς, Επικοινωνία, Πολιτική απορρήτου, …). Κατέχει μια ενέργεια, όχι μια προτίμηση.
share-picker — ανοίγει το εγγενές φύλλο κοινοποίησης ή λίστα προορισμών που παρέχει ο καταναλωτής, συν αντιγραφή του URL. Κατέχει μια ενέργεια, όχι μια προτίμηση: δεν εφαρμόζει τίποτα, δεν αποθηκεύει τίποτα.
date-time-picker — ένα πεδίο κειμένου συν ένας διάλογος επιλογής ημερομηνίας κατά APG για ημερομηνία, ώρα ή και τα δύο. Κατέχει μια τιμή φόρμας, όχι μια προτίμηση: η συμβολοσειρά ISO μετατρέπεται εκατέρωθεν σε <input type="date">.

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

Ο κατάλογος Svelte είναι η κανονική αναφορά· οι μεταφορές για React, Vue, Angular, HTML, Nunjucks, Web Components και Blazor του αντιστοιχούν συμβόλαιο προς συμβόλαιο. Δες το σεμινάριο βοηθών.

Διεθνοποίηση

Κάθε ετικέτα, κειμενοφύλακας, μήνυμα σφάλματος και κείμενο κουμπιού είναι ιδιότητα. Δεν υπάρχουν συμβολοσειρές γραμμένες στον κώδικα. Σύνδεσε το πλαίσιο μετάφρασης της επιλογής σου — Paraglide, i18next, vue-i18n, react-intl, αρχεία .resx, οτιδήποτε.

Για ημερομηνίες, αριθμούς και νομίσματα, τα στοιχεία δέχονται προμορφοποιημένες συμβολοσειρές: μορφοποιείς εσύ με Intl.DateTimeFormat / Intl.NumberFormat / τη βιβλιοθήκη που προτιμάς και περνάς το αποτέλεσμα.

Ο βοηθός locale-picker επισημαίνει την επιλεγμένη τοπική ρύθμιση στη βιβλιοθήκη i18n σου ορίζοντας lang και dir στη ρίζα του εγγράφου.

Δοκιμές

Κάθε υποέργο πλαισίου παρέχει τις δικές του δοκιμές με τη δική του ιδιωματική στοίβα:

HTML: WebDriverIO που τρέχει πραγματικούς περιηγητές.
Svelte: Vitest + @testing-library/svelte.
React: Vitest + @testing-library/react.
Vue: Vitest + @testing-library/vue.
Angular: Vitest + TestBed (μέσω του πρόσθετου Vite του Analog).
Nunjucks: Vitest με βοηθό απόδοσης.
Blazor: bUnit.

Οι δοκιμές χρησιμοποιούν μόνο τους ενσωματωμένους matchers του Vitest — ποτέ τους matchers του jest-dom . Αυτό κρατά τις σουίτες δοκιμών φορητές. Οι εφαρμογές-παραδείγματα προσθέτουν σουίτες Playwright end-to-end, βάσεις προσβασιμότητας axe-core και σάρωση ανταποκρινόμενων viewports.

Πράκτορες AI

Αυτός ο ιστότοπος δημοσιεύει llms.txt και llms.json στη ρίζα του — έναν επιμελημένο χάρτη των σημαντικότερων σελίδων του, για οποιοδήποτε εργαλείο ακολουθεί τη σύμβαση llms.txt.

Το κανονικό monorepo παρέχει επιπλέον δύο Claude Skills: lily-design-system-skill: μια δεξιότητα γενικής χρήσης που καλύπτει τις έννοιες, την ορολογία και τα μοτίβα σύνθεσης του Lily για όποιον χτίζει με το σύστημα, και lily-design-system-maintainer-skill, μια τεχνική δεξιότητα που καλύπτει τη διάταξη των απαιτούμενων αρχείων και τα εργαλεία του monorepo για όποιον δουλεύει σε αυτό. Και οι δύο βρίσκονται στη ρίζα του κανονικού monorepo.

Αντιμετώπιση προβλημάτων

Ένα στοιχείο αποδίδεται αλλά φαίνεται αμορφοποίητο

Αυτό είναι το κεφαλοχωρίς που λειτουργεί όπως προβλέπεται — κανένα CSS δεν συνοδεύει το στοιχείο. Είτε γράψε CSS για την κλάση kebab-case του στοιχείου (εμφανίζεται σε κάθε σελίδα του καταλόγου) είτε σύνδεσε ένα από τα 57 έτοιμα θέματα.

Το CSS μου δεν φαίνεται να εφαρμόζεται πάνω από ένα θέμα

Θα έπρεπε — οι επιλογείς των θεμάτων είναι τυλιγμένοι σε :where(...), που έχει μηδενική ειδικότητα. Αν ένας κανόνας εξακολουθεί να χάνει, έλεγξε ότι το φύλλο στυλ σου φορτώνει μετά το <link> του θέματος και ότι ο επιλογέας ταιριάζει πράγματι με το αγκίστρι κλάσης του στοιχείου.

Το pnpm install αποτυγχάνει με σφάλμα peer ή έκδοσης

Χρησιμοποίησε ένα τρέχον pnpm (v10+) και Node 22+. Κάθε υποέργο καρφιτσώνει τις εκδόσεις του πλαισίου του στο δικό του package.json· αν η καθολική αλυσίδα εργαλείων σου είναι παλαιότερη, το pnpm env use --global lts είναι η ταχύτερη διόρθωση.

Ο αναγνώστης οθόνης ανακοινώνει λάθος όνομα για ένα στοιχείο ελέγχου

Έλεγξε την απαιτούμενη ιδιότητα label του στοιχείου — τα στοιχεία που δεν έχουν ορατό κείμενο απαιτούν μία, και τα aria-label / aria-labelledby που παρέχει ο καταναλωτής και περνούν μέσω rest-props υπερισχύουν σκόπιμα της ενσωματωμένης καλωδίωσης. Κάθε σελίδα του καταλόγου τεκμηριώνει το συμβόλαιο ARIA του στοιχείου.

Ο βοηθός theme-picker δεν εναλλάσσει φύλλα στυλ

Επιβεβαίωσε ότι το themesUrl δείχνει σε κατάλογο που μπορεί να ανακτήσει ο περιηγητής (σέρβιρε τα αρχεία themes/ ως στατικούς πόρους) και ότι τα slugs των θεμάτων στην ιδιότητα themes ταιριάζουν με τα ονόματα των αρχείων. Ο βοηθός αλλάζει το href ενός διαχειριζόμενου <link data-lily-theme-picker> — έλεγξέ το στα εργαλεία προγραμματιστή για να δεις το URL που ζητείται.

Κάτι άλλο είναι χαλασμένο

Άνοιξε ένα issue με ελάχιστη αναπαραγωγή στο github.com/LilyDesignSystem/lily-design-system — ή δες την κοινότητα και υποστήριξη.

Συνεισφορά

Το Lily είναι νεαρό και καλωσορίζει τη συνεργασία. Οι πιο χρήσιμες συνεισφορές αυτή τη στιγμή είναι:

Νέα στοιχεία (ιδίως μοτίβα από καθιερωμένα συστήματα σχεδίασης).
Νέα θέματα — καθένα είναι ένα αυτόνομο φύλλο στυλ, ένα καλά οριοθετημένο πρώτο PR.
Καλύτερη μορφοποίηση παραδειγμάτων — δείξε τι είναι δυνατό.
Μεταφράσεις των συμβολοσειρών των εφαρμογών-παραδειγμάτων.
Αναφορές σφαλμάτων με ελάχιστη αναπαραγωγή.
Έλεγχοι προσβασιμότητας με αναγνώστες οθόνης και υποστηρικτικές τεχνολογίες.

Άνοιξε issues και PRs στο github.com/LilyDesignSystem/lily-design-system.

Κοινότητα και υποστήριξη

Ερωτήσεις και αναφορές σφαλμάτων — άνοιξε ένα issue στο github.com/LilyDesignSystem/lily-design-system.
Email — ο συντηρητής διαβάζει το joel@joelparkerhenderson.com και καλωσορίζει τη συνεργασία, την καθοδήγηση και τα σχόλια.
Καθρέφτες — Το Lily προωθείται επίσης στα Codeberg και GitLab, ώστε να συμμετέχεις από το forge που προτιμάς.
Συμπεριφορά — το έργο ακολουθεί έναν τυπικό κώδικα δεοντολογίας· να είσαι ευγενικός, υπόθετε καλή πίστη.

Συχνές ερωτήσεις

Γιατί κεφαλοχωρίς αντί για μορφοποιημένο;

Τα προ-μορφοποιημένα στοιχεία είναι βολικά — μέχρι να μην ταιριάζουν με την επωνυμία σου. Τα κεφαλοχωρίς στοιχεία απαιτούν λίγη περισσότερη δουλειά εξαρχής, αλλά σου δίνουν πλήρη έλεγχο του οπτικού σχεδιασμού. Οι εφαρμογές-παραδείγματα και τα 57 θέματα δείχνουν τρόπους μορφοποίησης· μπορείς να τους πάρεις ή να τους αντικαταστήσεις εντελώς. Το πιο εκτενές επιχείρημα βρίσκεται στο Γιατί Lily.

Γιατί τόσα πολλά στοιχεία;

Το Lily στοχεύει να καλύψει τα μοτίβα που χρειάζονται οι περισσότερες εφαρμογές χωρίς να σε αναγκάζει να τα χτίσεις από το μηδέν — συμπεριλαμβανομένων εξειδικευμένων πραγμάτων όπως εισόδων εθνικών αναγνωριστικών και συντακτικού scrollytelling. Ο κατάλογος αντλεί από δώδεκα καθιερωμένα συστήματα σχεδίασης συν πρωτότυπη δουλειά — δες το Σχετικά.

Μπορώ να χρησιμοποιήσω το Lily με Tailwind;

Ναι. Κάθε στοιχείο εκθέτει μία μόνο ριζική κλάση kebab-case συν ένα className / classπου παρέχει ο καταναλωτής. Στρώσε βοηθητικές κλάσεις Tailwind από πάνω όπως θέλεις.

Μπορώ να χρησιμοποιήσω το Lily με σημασιολογικά πλαίσια CSS όπως το DaisyUI;

Ναι. Τα ονόματα κλάσεων kebab-case στο ριζικό στοιχείο λειτουργούν ως σημασιολογικά αγκίστρια CSS. Συνδύασε το Lily με ένα σημασιολογικό πλαίσιο και παίρνεις προ-μορφοποιημένα στοιχεία που εξακολουθούν να σέβονται το ARIA και το i18n.

Υπάρχει πακέτο npm;

Οι βοηθοί προτιμήσεων παρέχονται ως πακέτα με αγωγό δημοσίευσης npm/NuGet. Οι κεφαλοχωρίς βιβλιοθήκες στοιχείων σχεδιάστηκαν για να κλωνοποιούνται ή να ενσωματώνονται — ο πηγαίος κώδικας είναι το παραδοτέο, ώστε να διαβάζεις, να κόβεις και να κατέχεις ακριβώς ό,τι αποστέλλεις. Η δημοσίευση των κεφαλοχωρίς βιβλιοθηκών σε μητρώα παραμένει στον οδικό χάρτη.

Γιατί πολλαπλές άδειες;

Διαφορετικά έργα έχουν διαφορετικές ανάγκες αδειοδότησης. Οι BSD και MIT είναι επιτρεπτικές, η Apache-2.0 έχει παραχώρηση ευρεσιτεχνίας και οι επιλογές GPL υποστηρίζουν copyleft. Διάλεξε ό,τι ταιριάζει στην περίπτωσή σου.

Πώς αναφέρω ένα σφάλμα ή ζητώ μια λειτουργία;

Άνοιξε ένα issue στο αποθετήριο GitHub ή στείλε email στο joel@joelparkerhenderson.com.