Skip to content

About

Lily Design System: a free open-source headless design system — 491 accessible components implemented across 7 frameworks, with themes, helpers, and example apps

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,240 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Lily Design System™

Lily Design System is a free open source design system that anyone can use and improve.

This is brand new work and we welcome collaboration, guidance, and feedback.

Contact joel@joelparkerhenderson.com

Lily is headless: the components ship semantic HTML, ARIA, and keyboard behaviour, and you ship every visual decision. The same markup, styled by an example app's stylesheet and bare:

A component-detail page from the SvelteKit example app, styled with the NHS UK visual reference

The same breadcrumb markup with no stylesheet: a browser-default ordered list

Lily targets WCAG 2.2 AAA — and says precisely what that does and does not mean in the accessibility statement.

Packages publish with npm provenance today; long-lived registry tokens are slated for replacement by Trusted Publishing once it covers every forge and registry this project treats as a peer.

The living specification is spec/index.md. The modular reference docs are in AGENTS.md and AGENTS/. For a topic-by-topic walkthrough, see the modular specification docs under spec/.

How the pieces fit

Lily is a stack of layers, each owning one job: the catalog (607 named components, components.tsv), headless libraries (the catalog as unstyled, accessible components in nine frameworks), helpers (packages that own a whole interaction: pickers, data grid, kanban board, calendar, Gantt chart, filter), themes (63 stylesheets), examples (styled apps, one per framework) and skills (instructions for AI agents). Which one to reach for: the site page How the pieces fit.

AI agent support

Twenty-seven Claude Skills give an AI coding agent a curated entry point, in three tiers: lily-design-system-skill for people building with Lily (concepts, naming, composition patterns), lily-design-system-maintainer-skill for people working on this monorepo (required files, bin/ tooling, the spec-driven workflow), eight framework-umbrella skills ({framework}-skill) that map a framework's headless/helpers/example-app subprojects and point down into the more specific skills, and sixteen framework-specific skills — one {framework}-headless-skill and one {framework}-helpers-skill per framework family (angular, blazor, html, nunjucks, react, svelte, vue, web-components) — each scoped to exactly the one real subproject it covers, plus lily-design-system-alpine-headless-skill for the Alpine.js catalog. All 27 live at this monorepo's root (their standalone mirror repositories were retired on 2026-10-10). See spec/agent-skills/ for the full list, or the docs site's Lily + Claude Code page for a guided tour. llms.txt and llms.json give any LLM tool a curated map of the project's most important content, following the llms.txt convention; the docs site publishes its own pair at its own root with site-appropriate links. See spec/agent-skills/ and spec/llms-json-and-llms-txt/.

How AI tools are actually used to build this project — disclosure, human oversight, quality controls, and the standing authorization for an agentic Claude Code session to decide a specific release is ready and publish it for real — is AI_STATEMENT.md and GOVERNANCE.md § AI agent publish authority, not this section.

Examples

Batteries-included web examples that demonstrate components in real apps:

Headless versions if you want to use components with all your own styles:

Helpers

Small, opinionated helper packages for every framework, one top-level subproject each. Each of the eight frameworks ships eleven *-picker helpers — 88 packages in all — plus picker-bar, the grid-like data-grid, kanban-board, gantt-chart, calendar and filter, the markdown-editor and org-editor, and locale-translations (20 per framework; with nunjucks-listbox-behavior and the six Alpine.js packages, 167 helper packages in all), and each owns one complete interaction end to end:

Themes

The themes/ directory ships 63 standalone reference theme stylesheets that target the Lily™ class hooks — NHS England, NHS Scotland, and NHS Wales (patient and practitioner variants), GOV.UK GDS, USWDS, Adobe Spectrum, Mozilla Protocol, Ant Design, Atlassian, Excel, Fluent, GitHub Primer, IBM Carbon, Linear, Notion, Salesforce, SAP Fiori, Vercel, and general-purpose light/dark themes. The theme-picker helper loads them at runtime.

Components

The canonical catalog is components.tsv — 607 components. Each slug below links to the per-component documentation.

About

Lily Design System: a free open-source headless design system — 491 accessible components implemented across 7 frameworks, with themes, helpers, and example apps

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages