Training
A self-paced course for a team adopting Lily: eight modules, each with a goal, something to read, an exercise you do in a real browser, and a self-check with answers. About a day in all; one module a sitting works well.
Before you start
Pick one framework tutorial and finish it first. Run one of the example apps locally, or use the component pages here, for the exercises. You need a keyboard, and for module 8 a screen reader: VoiceOver on macOS and iOS, NVDA on Windows or TalkBack on Android, all free.
Module 1 — What headless means
Goal: know what Lily decides and what you decide.
Read: the about page, and one component page, such as Button, end to end.
Do: render a Button and a TextInput with no stylesheet. Then link one theme, then another. Note what changed and
what did not.
Self-check: what does a Lily component never ship? What does it always ship?
Never: CSS, fonts, icons or images (the pickers' icons excepted), English text, data fetching, a default locale or currency. Always: the most specific HTML element, its kebab-case class hook first, ARIA where HTML falls short, keyboard behaviour, and your other attributes passed through.
Self-check: you want a red border on one button. Where does it go?
In your CSS, on the class hook (.button) or a class you add. Never in the component.
Module 2 — Keyboard and focus
Goal: use and test every component without a mouse.
Read: the Keyboard Interactions table on TabBar, Listbox and Dialog.
Do: unplug the mouse. On each of those three pages, reach the demo with Tab and do everything the table lists. Open the dialog, press Escape, and note where focus lands.
Self-check: why does a tab bar take one Tab stop, not one per tab?
The APG composite pattern: Tab moves between widgets, and the arrow keys move inside one (a roving tab index). A tab bar with ten tab stops makes a keyboard user press Tab ten times to get past it.
Self-check: after a modal dialog closes, where should focus be?
On the control that opened it. Lily's modal dialogs use showModal(), which also keeps Tab inside the dialog while it is open.
Module 3 — Names, roles and states
Goal: give every control a name a screen reader can say, in your words.
Read: the ARIA section of IconButton and SwitchButton.
Do: in your own app, running its development server,
render an IconButton without its label. Open the
browser console: Lily warns that the control has no accessible name. Add
the label and check the warning is gone. (The warnings exist only in a
development build, so a production page, such as this site, stays silent.)
Self-check: when do you use aria-label, and when visible text?
Visible text whenever you can: everyone sees it, and speech-input users
can say it. aria-label only where there is no visible text,
such as an icon. If both exist, the name must contain the visible words
(WCAG 2.5.3).
Self-check: a status shown only in red. What is missing?
Text. Colour can repeat a meaning but never carry it alone (WCAG 1.4.1); the status needs words.
Module 4 — Forms
Goal: build a form whose errors anyone can find and fix.
Read and do: the accessible forms tutorial, all five steps.
Self-check: the form fails validation. Where does focus go, and what is read?
To the error summary, which is announced with its heading and its list of links, one per error, each leading to its field.
Self-check: why not disable the submit button until the form is valid?
A disabled button cannot say what is wrong, and many people cannot tell why it does nothing.
Module 5 — Themes and contrast
Goal: restyle Lily without breaking contrast or focus.
Read: the theming tutorial and the theme contrast table.
Do: override --color-primary with your own brand
colour. Check its pair, --color-primary-content, reaches 4.5:1,
and that the focus ring still shows against the page.
Self-check: your brand colour is too pale for white text. Can you still use it?
Yes, as decoration (--lily-brand: a header band, a rule, a logo
background), never for text or a control's boundary. Text and borders use
the theme's content pairs.
Module 6 — Worldwide
Goal: make no country the default.
Read and do: a form that works worldwide.
Self-check: why does CurrencyInput have no default currency?
Any default would be one country's money, silently wrong everywhere else. A missing currencyCode is a defect in the caller.
Self-check: a page in Arabic. What do you set, and what must your CSS do?
lang="ar" and dir="rtl" (the locale picker sets both); your CSS uses logical properties so the layout mirrors on its own.
Module 7 — Motion
Goal: animate without harming anyone.
Read: the motion recipes.
Do: turn on "reduce motion" in your operating system and reload a page with the marquee recipe. It should stand still and wrap. Then reach its pause button by keyboard.
Self-check: something moves on its own for more than five seconds. What must it have?
A way to pause, stop or hide it (WCAG 2.2.2), reachable by keyboard, not only by hovering.
Module 8 — Check your work
Goal: test a page the way Lily tests its own.
Do: take one page you built in this course and run four checks:
- axe (the browser extension, or
@axe-core/playwrightin a test): no violations. - Keyboard only: every task done, focus always visible, never trapped.
- Zoom to 400% and narrow the window to 320 pixels: no sideways scrolling, nothing cut off.
- A screen reader: every control has a name, a role and its state, and errors are announced.
Self-check: axe reports no violations. Is the page accessible?
Not yet proven. Automated checks find perhaps a third of the problems; the keyboard, zoom and screen-reader checks find much of the rest. See the quality page for what Lily itself has and has not verified.
After the course
- The healthcare guide, for clinical software.
- The helpers: pickers, the data grid, the calendar.
- Help, and the project for questions.