Lily Design System React

Three real, independent React subprojects exist in this monorepo. This skill is the umbrella: it maps the three, tells you which one you need, and points at the two sibling skills that go deep on the first two. It does not restate their content.

| Subproject | What it is | Reach for it when | | --- | --- | --- | | lily-design-system-react-headless | An npm package: the 490-component headless catalog as React 19 function components. Zero CSS. | You're building your own app and want the library you actually pnpm install and depend on. | | lily-design-system-react-helpers | Six small npm packages (theme-picker, locale-picker, text-size-picker, motion-picker, share-picker, date-time-picker) that each own one whole page-header interaction — selection, DOM application, optional persistence. | You need a ready-made preference control or share action rather than building one from catalog primitives. | | lily-design-system-react-next-examples | A React 19 + Next.js 15 App Router application: every headless component fully styled and wired up, plus 12 composed-page demos. Not a package you install. | You want to see a component working end-to-end, copy its CSS, or run a live reference before wiring the headless library into your own app. |

Deep-dive skills for the first two

• lily-design-system-react-headless — install command, import shape, the className + rest-props convention, controlled-prop patterns (value/onChange, open/onChange), and documented component-level gotchas (BreadcrumbListItem, Alert, Dialog, ErrorSummary, TabBarButton, RadioInput, FileUpload). Use it, not this skill, for anything about consuming the headless library itself.
• lily-design-system-react-helpers — the six helper packages' names and shapes, the render-prop children convention, "use client" SSR boundaries, and why the idempotent-apply guard matters specifically in React (a controlled value applies once when set and again when your own onChange writes it back). Use it, not this skill, for anything about consuming the helper packages.

This skill's job is the map and the routing decision above — it does not restate either sibling's install commands, prop conventions, or gotchas.

The example app: lily-design-system-react-next-examples

Neither sibling skill covers this subproject — it's the one place this skill gives real, not just pointer-level, coverage.

• Stack: React 19 + Next.js 15, App Router. Every example page carries the "use client" directive, because the demos are interactive and the headless components manage their own state. typescript.ignoreBuildErrors: true is set in next.config.ts because the headless library's [key: string]: unknown rest-props typing conflicts with Next's strict ReactNode typing — a known, deliberate accommodation, not a defect to fix.
• Component wiring: components are imported from the headless library through a @pgds/ path alias (../lily-design-system-react-headless/components/); each of the 490 wrapper components under components/ is a thin re-export (export { default } from "@pgds/Button") so example pages can also import locally via @/components/*.
• Styling: NHS UK design system colours, typography, spacing, and focus states — the same default visual reference every Lily example app uses — served as a runtime theme stylesheet (a managed <link data-lily-theme-picker> the theme-picker helper swaps among /themes/*.css, defaulting to NHS England for patients). assets/css/app-shell.css holds only the fixed app-shell chrome (skip-link, page-wrapper, site-header) that no theme should style.
• Required routes, per the general example-app contract every Lily example app follows (AGENTS/examples.md): / (home, links to the catalog and composed demos), /components (the full searchable catalog index), and /components/{slug} (one live demo per component with its metadata). On top of those, this app ships 12 composed-page demos exercising multiple components together: /contact-form, /dashboard, /dialog-flow, /file-upload-form, /navigation-and-menus, /page-layout, /rating-and-feedback, /search-and-filter, /settings-page, /tabbed-interface, /task-management, /timeline-and-cards.
• Running it: pnpm install && pnpm run dev, then http://localhost:4140. pnpm run build / pnpm start for a production build; pnpm test runs the vitest + @testing-library/react suite (jsdom, vitest's own matchers only — no jest-dom).
• This is not a package you install. It's a running reference app. If a request is about how a component looks or how a full page is assembled, point here and at its CSS; if it's about the API you code against, point at the headless skill instead.

React-wide conventions verified across all three

• React 19 function components only, TypeScript, hooks only (useState, useEffect, useRef) — no class components, no legacy lifecycle methods, in the headless library, the helpers, or the example app.
• className, not class, everywhere; every root element combines the kebab-case slug with the consumer's className.
• Rest-props spread onto the root in both the headless library and the helpers, so id, data-*, event handlers, and ARIA overrides pass straight through.
• "use client" is the SSR boundary for anything that touches the DOM — the helpers carry it in their own packages, and every example page in the Next.js app carries it too, for the same reason (interactive components need client rendering).
• No hardcoded user-facing strings — every label, heading, and placeholder is a prop, consistent with the rest of Lily's internationalisation rule.

Framework-agnostic Lily concepts

For what "headless" means in general, what a class hook or slug is, the 491-component catalog at a glance, naming conventions, and composition patterns that aren't React-specific, use lily-design-system instead — this skill assumes that grounding and only adds the React layer on top.