Astellungs-Helperen

Wat Dir bauen wäert

E Panel mat Astellungen, wou d'Benotzer hir Sprooch an hir Textgréisst wielen — Choixen, déi fir dat ganzt Dokument gëllen, tëscht Visitte bleiwen a Iech zwou Komponenten a puer Zeilen CSS kaschten. Ongeféier 15 Minutten.

Ier Dir ufänkt

Maacht fir d'éischt de Framework-Tutorial fir Äre Stack fäerdeg. D'Beispiller hei drënner sinn Svelte; d'Helperen fir React, Vue, Angular, HTML, Nunjucks a Blazor entspriechen hinnen Kontrakt fir Kontrakt.

D'Form, déi si deelen

• E Headless-Ikonknäppchen, dat eng WAI-ARIA APG-Listbox opmaacht (oder, bei date-time-picker, en Datumsauswiel-Dialog) — kee nativen <select>, sou datt all Framework datselwecht Tastaturverhalen an dëselwechte Styling-Hooks kritt.
• Ee Klassen-Hook pro Package (.locale-picker, .text-size-picker, .share-picker, .date-time-picker), null CSS geliwwert.
• SSR-sécher: DOM-Schreiwen geschitt just am Mount-/Effect-Liewenszyklus.
• I18n-propper: all String, deen de Benotzer gesäit, ass eng Prop.
• Verfügbar fir Svelte (kanonesch), React, Vue, Angular, HTML-Custom-Element, Nunjucks a Blazor — an all enger dee selwechte Kontrakt.

theme-picker, locale-picker an text-size-picker besëtzen jidd eng Benotzer- Astellung vun Ufank bis Enn (Auswiel, Uwendung op den DOM, optionell localStorage Persistenz iwwer d'Prop storageKey ). share-picker an date-time-picker sinn anerer Aart: share-picker besëtzt eng Aktioun — si wend näischt um Dokument un a behält näischt — an date-time-picker besëtzt e Formulairewäert, well en Datum an engem Formulaire Daten an keng Astellung ass.

locale-picker — Sprooch a Richtung

Léisst de Benotzer e Lokal wielen an schreift dann lang an dir op d'Wuerzel vum Dokument, sou datt Är i18n-Bibliothéik, Äre CSS an Hëllefstechnologien et all verfollegen. RTL gëtt automatesch erkannt fir Arabesch, Hebräesch an aner Schrëften vu riets no lénks. Et konzentréiert sech just op d'Signaliséieren — Är i18n-Bibliothéik këmmert sech ëm d'Iwwersetzung.

<script>
  import LocalePicker from "@lilydesignsystem/svelte-locale-picker";

  let locale = $state("en-US");
</script>

<LocalePicker
  label="Language"
  locales={["en-US", "fr", "ar", "he", "ja"]}
  bind:value={locale}
  storageKey="my-app-locale"
/>

D'Optioune ginn aus enger agebauter Tabell vu Lokalnimm beschrëft (iwwerschreifbar iwwer localeLabels), all Optioun huet säin eegent lang -Attribut, sou datt Écranliesser „Français“ op Franséisch aussprécheen, a Coden mat Ënnerstréch wéi en_US ginn ouni Verloscht op BCP 47 an zréck ëmgewandelt en-US. Verbënnt onChange (oder de gebonnene Wäert) mat i18next, Paraglide, vue-i18n oder wat Dir benotzt.

text-size-picker — Gréisst, vum Lieser kontrolléiert

E Gewënn fir d'Zougänglechkeet, dat just Minutte brauch: den Helper setzt data-text-size="{slug}" op d'Wuerzel vum Dokument, an Äre CSS ordnet all Wäert enger Gréisst zou.

<script>
  import TextSizePicker from "@lilydesignsystem/svelte-text-size-picker";
</script>

<TextSizePicker
  label="Text size"
  sizes={["small", "medium", "large", "x-large"]}
  storageKey="my-app-text-size"
/>

:root[data-text-size="small"]   { font-size: 87.5%; }
:root[data-text-size="medium"]  { font-size: 100%; }
:root[data-text-size="large"]   { font-size: 112.5%; }
:root[data-text-size="x-large"] { font-size: 125%; }

Dimensionéiert Äre Layout a rem an déi ganz App skaléiert mat der Wiel vum Benotzer. D'Etikette ginn aus de Slugs mat grousse Buschtawen erstallt („X Large“) oder iwwerschriwwen mat sizeLabels.

share-picker — dës Säit schécken

E Knäppchen mat engem eenzege Glyph, dat dat native Deelen-Blat vum Apparat opmaacht, wou et een gëtt, an soss op eng Lëscht vun Destinatioune zréckfällt, déi Dir ubitt, plus eng Aktioun fir d'URL ze kopéieren. Et liwwert keng URLe vu sozialen Netzwierker — wéi eng Netzwierker an Äre Produkt gehéieren, ass Är Entscheedung, net déi vum Designsystem.

<script>
  import SharePicker from "@lilydesignsystem/svelte-share-picker";

  const targets = [
    { id: "mastodon", label: "Mastodon",
      href: (url, title) => `https://mastodon.social/share?text=${encodeURIComponent(title)}%20${encodeURIComponent(url)}` },
    { id: "email", label: "Email",
      href: (url, title) => `mailto:?subject=${encodeURIComponent(title)}&body=${encodeURIComponent(url)}`, newTab: false },
  ];
</script>

<SharePicker
  label="Share this page"
  title="An article worth reading"
  {targets}
  copyLabel="Copy link"
  copiedLabel="Link copied"
/>

url ass standardméisseg location.hrefsou datt de Normalfall keng Verdrahtung brauch. Erzwéngt e Wee mat strategy="list" oder strategy="native" wann Dir konsequent Verhalen iwwer Plattformen fir Tester oder Screenshots braucht.

date-time-picker — en Datum, eng Zäit oder béides

E Textfeld, an dat Dir tippe kënnt, plus e Ikonknäppchen, dat en WAI-ARIA APG-Datumsauswiel-Dialog opmaacht. Vun der Konstruktioun hier lokalgerecht — Monatsnimm, Wochendagsnimm, den éischten Dag vun der Woch an 12- oder 24-Stonne-Auer kommen all aus Intl — an de Wäert ass ëmmer e sortéierbare ISO-String ouni Zäitzon: "2026-03-15" fir mode="date", "09:30" fir mode="time", "2026-03-15T09:30" fir mode="datetime".

<script>
  import DateTimePicker from "@lilydesignsystem/svelte-date-time-picker";

  let appointment = $state("");
</script>

<DateTimePicker
  inputId="appointment"
  name="appointment"
  label="Choose an appointment date"
  locale="en-GB"
  bind:value={appointment}
  labels={{
    previousYear: "Previous year",
    previousMonth: "Previous month",
    nextMonth: "Next month",
    nextYear: "Next year",
    confirm: "OK",
    cancel: "Cancel",
  }}
/>

Den ISO-Wäert ass identesch mat deem, wat <input type="date"> schéckt, sou datt Dir déi nativ Kontroll eran- oder erausschalte kënnt ouni Äre Backend ze beréieren.

motion-picker — reduzéiert Bewegung respektéieren

Den Helper setzt data-motion="{slug}" op d'Wuerzel vum Dokument. Säin éischte Wäert kënnt aus der prefers-reduced-motion -Astellung vum Betribssystem vum Visiteur — ëmmer, ouni Opt-in-Flag, well Bewegung e richtege Zougänglechkeetsbedarf ass (WCAG 2.3.3). Äre CSS an Är Skripte entscheeden, wat ënnerdréckt gëtt.

<script>
  import MotionPicker from "@lilydesignsystem/svelte-motion-picker";
</script>

<MotionPicker
  label="Motion"
  motions={["no-preference", "reduce"]}
  storageKey="my-app-motion"
/>

:root[data-motion="reduce"] *,
:root[data-motion="reduce"] *::before,
:root[data-motion="reduce"] *::after {
  animation: none !important;
  transition: none !important;
  scroll-behavior: auto !important;
}

search-picker — eng Sichbox, déi net am Wee ass

E Ikonknäppchen, dat e Sichfeld opmaacht. D'Drécke vun Return, oder vum ⏎-Knäppchen niewent dem Feld, navigéiert mat enger einfacher GET-Ufro op /?<text> (den Text gëtt getrimmt an URI-kodéiert; eng eidel Ufro féiert nirgendwuer hin). Seng dräi zougänglech Nimm sinn Pflicht, well den Helper keen Englesch liwwert.

<script>
  import SearchPicker from "@lilydesignsystem/svelte-search-picker";
  import { goto } from "$app/navigation";
</script>

<SearchPicker
  label="Search this site"
  inputLabel="Search terms"
  submitLabel="Search"
  placeholder="Search…"
  action="/search"
  navigate={(href) => goto(href)}
/>

action ännert de Wee (/search?foo), an navigate hält d'Navigatioun an der App; ouni dat rifft den Helper location.assign.

picker-bar — déi ganz Kopzeil op eemol

picker-bar rendert Sich, Thema, Lokal, Textgréisst an Deelen an enger Zeil, mam kompletten Set vu Referenzthemen an der siwenstufeger Textskala virverbonnen. All zougänglechen Numm kënnt an engem erfuerderlechen labels -Objet.

<script>
  import PickerBar from "@lilydesignsystem/svelte-picker-bar";
</script>

<PickerBar
  labels={{
    search: "Search", searchInput: "Search terms", searchSubmit: "Search",
    theme: "Theme", locale: "Language", textSize: "Text size", share: "Share",
  }}
  themesUrl="/themes/"
  locales={["en", "fr", "es"]}
  shareTargets={targets}
/>

Erreecht all agepackte Wieler mat searchProps, themeProps, localeProps, textSizeProps an shareProps.

Tooltips sinn agebaut

All Wieler weist säin Etikett an engem Tooltip, wann de Pointer op sengem Knäppchen rascht oder d'Knäppchen Tastatur-Fokus huet. Den Tooltip bleift, während de Pointer op en geet, Escape mécht en zou, egal wou de Fokus ass, an hie gëtt ni gewisen, wärend dem Wieler säi Popup op ass. Hie fiert datselwecht Text wéi den zougängleche Numm vum Knäppchen, sou datt näischt ze konfiguréieren oder zweemol z'iwwersetzen ass; d'Referenzthemen gestalten en.

E Panel mat Astellungen op engem Plaz

Déi véier Astellungs-Helperen setzen sech natierlech zesummen:

<fieldset class="fieldset">
  <legend>Preferences</legend>
  <ThemePicker    label="Theme"     themesUrl="/themes/" themes={themes} storageKey="pref-theme" />
  <LocalePicker   label="Language"  locales={locales}    storageKey="pref-locale" />
  <TextSizePicker label="Text size" sizes={sizes}        storageKey="pref-text-size" />
  <MotionPicker   label="Motion"    motions={motions}    storageKey="pref-motion" />
</fieldset>

Wou Dir se kritt

# one directory per package in the monorepo, e.g.
git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-svelte-theme-picker
# or lily-design-system-react-theme-picker, -vue- / -angular- / -html- / -web-components- / -nunjucks- / -blazor-

All Package huet seng eege Spec, Tester, déi un d'Spec-Klauselen gebonne sinn, ausféierbar Beispiller (och SSR-Cookie-Muster) an eng Build- a Verëffentlechungs-Pipeline. D'Svelte-Packagen sinn déi kanonesch; am Zweiwelsfall gewannen hir Kontrakter.

Nächst Schrëtt

• Komponentekatalog — déi komplett Referenz vun de 571 Komponenten.
• Hëllef — Feelersich an FAQ.
• Firwat Lily — a wéi Dir de Projet ënnerstëtzt.

Froen ënnerwee? D'Hëllefsäit ass voller Äntwerten — a wann e Schrëtt méi kloer kéint sinn, soot et eis a mir verbesseren den Tutorial gär.