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:

  1. axe (the browser extension, or @axe-core/playwright in a test): no violations.
  2. Keyboard only: every task done, focus always visible, never trapped.
  3. Zoom to 400% and narrow the window to 320 pixels: no sideways scrolling, nothing cut off.
  4. 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