Getting started with Lily

Install

Lily is published as separate Git repos per framework. The fastest way to try it is to clone the headless repo for your stack:

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

The same pattern works for the other frameworks:

• lily-design-system-html-headless — no install needed; copy .html files
• lily-design-system-svelte-headless — pnpm install
• lily-design-system-react-headless — pnpm install
• lily-design-system-vue-headless — pnpm install
• lily-design-system-angular-headless — pnpm install
• lily-design-system-nunjucks-headless — pnpm install
• lily-design-system-blazor-headless — dotnet build

The headless libraries are designed to be cloned or vendored — treat the source as the source of truth and copy what you need. The preference helpers additionally ship as installable packages with a build and publish pipeline (npm for the JS frameworks, NuGet for Blazor).

Use a headless component

Headless components ship semantic HTML, ARIA, and props — but no CSS. Here's a Button in each 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 "lily-design-system-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" }) }}

Use a styled example

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

Then open http://localhost:5173 and browse /components.

Styling and design tokens

Each component renders with a single kebab-case class on its root element. For example, <Button> renders <button class="button">. Style it however you 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 default Lily color palette (used in the example apps) is:

• Primary: #2563eb
• Danger: #dc2626
• Warning: #f59e0b
• Success: #16a34a
• Page background: #f9fafb
• Card background: #ffffff

These are suggestions, not requirements. Replace them with your own brand palette and Lily comes along happily.

Ready-made themes

Don't want to write CSS from scratch? Lily ships 45 standalone reference themes in the themes/ directory. Each is one stylesheet targeting the Lily class hooks — link it and you're styled:

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

The set covers:

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

Theme selectors use :where(...), so your own CSS always wins on specificity. Pair them with the theme-select helper below for runtime switching, or follow the theming tutorial.

Preference helpers

Each framework has a companion *-helpers catalog with three small packages that each own one user preference end to end — selection, DOM application, and optional localStorage persistence. Each renders a native <select>, is SSR-safe, and ships no CSS:

• theme-select — loads theme stylesheets at runtime by swapping a managed <link>, and sets data-theme on the document.
• locale-select — sets lang and dir (with automatic RTL detection) so your i18n library can follow; performs no translation itself.
• text-size-select — sets data-text-size on the document; your CSS maps each value to font sizing.

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

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

Accessibility

Components target WCAG 2.2 AAA. They follow these patterns:

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

Focus indicators are intentionally consumer-supplied — Lily never paints a default focus ring that conflicts with your design. The example apps hold a clean axe-core baseline across their routes.

Internationalization

Every label, placeholder, error message, and button text is a prop. There are no hardcoded strings. Drop in your translation framework of choice — Paraglide, i18next, vue-i18n, react-intl, .resx files, anything.

For dates, numbers, and currencies, the components accept pre-formatted strings: you format with Intl.DateTimeFormat / Intl.NumberFormat / your preferred library and pass the result.

The locale-select helper signals the chosen locale to your i18n library by setting lang and dir on the document root.

Testing

Each framework subproject ships its own tests using its idiomatic stack:

• HTML: WebDriverIO running real browsers.
• 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.

Tests use Vitest's built-in matchers only — never jest-dom matchers. This keeps the test suites portable. The example apps add Playwright end-to-end suites, axe-core accessibility baselines, and a responsive viewport sweep.

Troubleshooting

Contributing

Lily is young and welcomes collaboration. The most useful contributions right now are:

• New components (especially patterns from established design systems).
• New themes — each is one standalone stylesheet, a well-scoped first PR.
• Better example styling — show off what's possible.
• Translations of example app strings.
• Bug reports with a minimal reproduction.
• Accessibility audits with screen readers and assistive tech.

Open issues and PRs against the relevant repo at github.com/LilyDesignSystem.

Community and support

• Questions and bug reports — open an issue on the relevant repo at github.com/LilyDesignSystem.
• Email — the maintainer reads joel@joelparkerhenderson.com and welcomes collaboration, guidance, and feedback.
• Mirrors — Lily is also pushed to Codeberg and GitLab, so you can participate from the forge you prefer.
• Conduct — the project follows a standard code of conduct; be kind, assume good faith.

FAQ