Gettin stairtit wi Lily

Install

Lily lives in ae Git monorepo, wi a directory for ilka framework's headless library, helper packages an example app. The fastest wey tae try it is tae clone the monorepo an open the headless library for yer stack:

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

The same pattern wirks for the ither frameworks:

• @lilydesignsystem/html-headless — nae install needit; copy .html files
• @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

The headless libraries are designit tae be clonit or vendorit — treat the source as the source o truth an copy whit ye need. The preference helpers additionally come as installable packages wi a build an publish pipeline (npm for the JS frameworks, NuGet for Blazor).

Uise a headless component

Headless components ship semantic HTML, ARIA, an props — but nae CSS. Here's a Button in ilka 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" }) }}

Uise a styled example

The example apps include CSS, routes, an full demo pages. The fastest wey tae experiment is tae stairt the SvelteKit, Next, Nuxt, Analog, or Eleventy example app an view the demo at /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

Then open http://localhost:5173 an brouse /components.

Stylin an design tokens

Ilka component renders wi a single kebab-case class on its root element. For example, <Button> renders <button class="button">. Style it hooever ye like:

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

The defauld Lily colour palette (uised in the example apps) is:

• Primary: #2563eb
• Danger: #dc2626
• Warnin: #f59e0b
• Success: #16a34a
• Page backgrund: #f9fafb
• Caird backgrund: #ffffff

Thir are suggestions, no requirements. Replace them wi yer ain brand palette an Lily comes alang happily.

Ready-made themes

Dinnae want tae write CSS frae scart? Lily ships 57 standalane reference themes in the themes/ directory. Ilkane is ae stylesheet targetin the Lily class hooks — link it an ye're styled:

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

The set covers:

• Public sector — NHS England, NHS Scotland, an NHS Wales (patient-facin an practitioner-facin variants ilkane), GOV.UK GDS, an the U.S. Web Design System.
• Vendor-inspired — Adobe Spectrum, Mozilla Protocol.
• General purpose — light, dark, nord, dracula, wireframe, an thirty-odd mair.

Theme selectors uise :where(...), sae yer ain CSS aye wins on specificity. Pair them wi the theme-picker helper ablow for runtime switchin, or follae the theming tutorial.

Preference helpers

Ilka framework haes aicht wee pickers, ilkane its ain lily-design-system-{framework}-{package} package (an a picker-bar that assembles them). Ilkane is a headless icon-button that opens a popup — a listbox, a list o links, a seek form, or (for date-time-picker) a date-picker dialog — no a native <select>; is SSR-safe; an ships nae CSS:

• theme-picker — loads theme stylesheets at runtime bi swappin a managed <link>, sets data-theme on the document, an optionally persists tae localStorage.
• locale-picker — sets lang an dir (wi automatic RTL detection) sae yer i18n library can follae; it performs nae translation itsel.
• text-size-picker — sets data-text-size on the document; yer CSS maps ilka value tae font sizin.
• motion-picker — sets data-motion on the document, stairtin frae the visitor's reduced-motion settin; yer CSS an scripts decide whit tae suppress.
• search-picker — an icon button that opens a seek field; submittin navigates tae a seek page. Owns an action, no a preference.
• link-picker — a hame icon that opens a menu o the page links yer app defines (Hame, Aboot Us, Contact Us, Privacy Policy, …). Owns an action, no a preference.
• share-picker — opens the native share sheet or a consumer-supplied destination list, plus copy-the-URL. Owns an action, no a preference: applies naething, persists naething.
• date-time-picker — a text field plus an APG date-picker dialog for a date, a time, or baith. Owns a form value, no a preference: the ISO string round-trips tae <input type="date">.

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

The Svelte catalog is the canonical reference; React, Vue, Angular, HTML, Nunjucks, Web Components, an Blazor ports match it contract-for-contract. See the helpers tutorial.

Accessibility

Components target WCAG 2.2 AAA. They follae thir patterns:

• Semantic HTML elements ower generic <div>s.
• <label for="id"> linkin labels tae inputs.
• aria-labelledby / aria-describedby for cross-references.
• aria-invalid + aria-errormessage for error states.
• role="alert" an aria-live for dynamic content.
• aria-pressed, aria-expanded, aria-current for state.
• Roving tabindex for grids.

Focus indicators are deliberately consumer-supplied — Lily never paints a defauld focus ring that clashes wi yer design. The example apps haud a clean axe-core baseline athort their routes.

Internationalization

Ilka label, placeholder, error message, an button text is a prop. There are nae hardcodit strings. Drap in yer translation framework o choice — Paraglide, i18next, vue-i18n, react-intl, .resx files, onything.

For dates, numbers, an currencies, the components accept pre-formattit strings: ye format wi Intl.DateTimeFormat / Intl.NumberFormat / yer preferred library an pass the result.

The locale-picker helper signals the chosen locale tae yer i18n library bi settin lang an dir on the document root.

Testin

Ilka framework subproject ships its ain tests uisin its idiomatic stack:

• HTML: WebDriverIO rinnin real browsers.
• Svelte: Vitest + @testing-library/svelte.
• React: Vitest + @testing-library/react.
• Vue: Vitest + @testing-library/vue.
• Angular: Vitest + TestBed (through the Analog Vite plugin).
• Nunjucks: Vitest wi a render helper.
• Blazor: bUnit.

Tests uise Vitest's biggit-in matchers anely — never jest-dom matchers. This keeps the test suites portable. The example apps add Playwright end-tae-end suites, axe-core accessibility baselines, an a responsive viewport sweep.

AI agents

This site publishes llms.txt an llms.json at its root — a curatit map o its maist important pages, for onie tool that follaes the llms.txt convention.

The canonical monorepo additionally ships twa Claude Skills: lily-design-system-skill, a general-purpose skill coverin Lily's concepts, terminology, an composition patterns for onybody biggin wi the system, an lily-design-system-maintainer-skill, a technical skill coverin the monorepo's required-files layoot an tooling for onybody wirkin on it. Baith live at the root o the canonical monorepo.

Troubleshootin

Contributin

Lily is young an walcomes collaboration. The maist uiseful contributions richt noo are:

• New components (especially patterns frae established design systems).
• New themes — ilkane is ae standalane stylesheet, a weel-scopit first PR.
• Better example stylin — shaw whit's possible.
• Translations o example app strings.
• Bug reports wi minimal reproduction.
• Accessibility audits wi screen readers an assistive tech.

Open issues an PRs at github.com/LilyDesignSystem/lily-design-system.

Community an support

• Questions an bug reports — open an issue at github.com/LilyDesignSystem/lily-design-system.
• Email — the maintainer reads joel@joelparkerhenderson.com an walcomes collaboration, guidance, an feedback.
• Mirrors — Lily is an aa pushed tae Codeberg an GitLab, sae ye can participate frae the forge ye prefer.
• Conduct — the project follaes a standard code o conduct; be kind, assume guid faith.

FAQ