Working with AI

Give your agent LUZ

LUZ is plain HTML and CSS, so an AI coding agent can write it when it knows which class names exist. Paste this prompt into your agent.

It points the agent at the files below and asks it to run the checker on what it wrote. What the checker does not do is in What this does not do.

Use LUZ for the markup. Read https://nandovejer.github.io/luz/llms.txt first and use only the classes in each package's classes.json. After you write HTML or CSS, run `npx @luz-ds/check@0.3.0` on the files and fix every finding before you answer.

Start a site

For a new site, or to move one to LUZ, give an LLM the longer prompt. It asks you about the project in short rounds, shows you the plan, and writes nothing until you say "go".

Open the prompt

For one kind of site, its page has a prompt made for it and the recipes of its parts: a landing page, a blog or a newspaper, a web application or a documentation site.

What an agent can read

Every file below is written by the build of this site from the pages you are reading, so an agent and a person get the same facts. Give an agent the URL of llms.txt: it lists the rest.

Check what an agent wrote

npx @luz-ds/check@0.3.0 reads the HTML and CSS of a project, offline, and says which LUZ classes, elements, load order and color tokens are wrong. It reads files and writes nothing.

It needs Node 20 or later.

npx @luz-ds/check@0.3.0
npx @luz-ds/check@0.3.0 index.html css/site.css
npx @luz-ds/check@0.3.0 src --json

Say npx @luz-ds/check@0.3.0, with the scope. A path is a file, a folder (read recursively: .html, .htm and .css) or a quoted glob such as "src/**/*.html".

With no path it reads the current folder.

A luz-check.json in the folder you run it from sets ignore, rules, themes and strict. A rule that warns can be switched off there; a rule that blocks is silenced only with ignore, and the summary says how many findings were ignored and how many rules are off.

Exit codes

What it prints

One line for each finding, in the order of the files and lines: a mark (✗ blocks, ! warns), the place, the rule and one sentence that says what is wrong and what to do. A color token finding is followed by the lines where the colors were set.

The last line counts what it found in the files it read.

✗ index.html:14:8 class/unknown  .luz-btn-primary is not a LUZ class; the closest is .luz-btn--primary
✗ index.html:22:5 load/package-missing  <luz-announcement> is in @luz-ds/catalog/components/announcement.css; add it after core
! site.css:8:3 css/literal-colour  color is set to #1a5fb4; use a token, such as var(--luz-brand-fill)
✗ theme.css:3:3 theme/contrast  light: --luz-text-secondary on surface-page is 2.8:1, needs 4.5:1 (text); change one of the two
    --luz-text-secondary: #999999 is set in theme.css:3
✗ 3 blocking and 1 warning in 3 files (manifests: @luz-ds/core 0.1.0 from node_modules)

The (manifests: …) part says which LUZ version the names were checked against, and from where: your node_modules or the copy that ships with the command.

The JSON report

--json prints one object with these fields. A field that is not in this table is not part of the report.

The same two things hold for the text and for the JSON: a path or a name that is not made of ordinary characters is written escaped, and the command never quotes the text of your files.

What check blocks and what it warns about

Each rule has an id such as class/unknown, shown in every finding. A rule that blocks makes the exit code 1.

A rule that warns does not, unless you pass --strict. The two tables are written from the list of rules the command has.

Catalog 0.3 renamed its classes, elements, files and chunks, and the old names do nothing. names/renamed finds an old class, an old tag, a link to an old component file or an old chunk, and gives the new name. It says nothing on a page that links catalog 0.0 to 0.2, where the old names are the right ones.

The accessibility reviewer

The same package prints an agent definition for an AI coding assistant: a reviewer that reads the source of a page and gives advice on accessibility. Copy it into your project.

npx @luz-ds/check@0.3.0 agent > .claude/agents/luz-accessibility-reviewer.md

• It overwrites. The > replaces a file that is already there. Use another path, or put your copy under version control first, if you edited it.
• It is read-only. It has three tools, Read, Grep and Glob: it reads, searches and lists files, and writes nothing. Read-only does not mean harmless, because Read has no path limit. Read the file before you use it, and review any change to it as you would code.
• It gives advice. It reviews source against WCAG 2.2 level AA and EN 301 549, and labels each finding as confirmed in the source or as one that needs a browser or assistive technology. Its findings are suggestions from reading code, not test results.
• It does not use assistive technology. It does not open a page or run a script, and it does not look at how a page renders, so it does not replace a test with a keyboard and a screen reader.

The file is also in the package as @luz-ds/check/agents/accessibility.md, for a build step that copies it.

What this does not do

A run with no findings says what the checker did not find in the files it read. It is not a test of the page.

• It does not run a browser. It reads files, so anything that depends on how a page renders, such as layout, focus order or the colors a browser works out, is not seen.
• Contrast is measured for your tokens only. It measures the --luz-* colors you set in your own color tokens file. A color written straight into a rule is not measured against anything. How the pairs are read is on Contrast check.
• A class built at run time is not seen. A name put together in a script, such as "luz-" + name, or written by a template, is not in the file, so it is not checked.
• It does not check names, labels, alt text, headings and language. Whether a button has a name, an image a useful alternative, the headings an order and the page a language is not read, and a run with no findings says nothing about them.
• It does not replace testing with a screen reader. No assistive technology is used, by the command or by the reviewer. What has not been tested is listed in the accessibility statement.
• It does not call a network. It runs offline, with the data in your node_modules or in its own package.
• Discovery by llms.txt is by link. This site is not at the root of a host, so an agent does not find the file by itself: give it the URL, as the prompt above does.
• Exit code 0 is not an accessibility result. It says that no rule above blocks in the files that were read.
• The messages are in English. They are not translated, whatever the language of the page.