Health checks
Every pack and every check it runs, listed from the same code the CLI runs, so the list matches the version you install. Health checks are advisory: the canvas shows them on the Health tab, and they never change the verdict of a step or a run. When a check matters to your team, adopt it as a criterion (kaloko health adopt <step>:<check>); from then on it counts for acceptance.
A step turns packs on with packs: [seo, a11y] in the scenario file (Add criteria and packs). The kinds of check, their options and the ids are in Criteria, checks and packs.
Severity of a failed check: an error when people or search engines are shut out, a warning otherwise. An answer the evaluator was unsure about shows as unsure.
SEO basics (seo)
What search engines read from a page: the title, description, canonical, hreflang, Open Graph, robots, viewport and structured data. On a stack step it also compares the pages with each other.
Off on design environments, where the steps are your own HTML served from a folder. To keep it on there, list it in health: { design_packs: [...] } in the scenario.
| Id | Check | Why it matters | Severity | Applies to |
|---|---|---|---|---|
| HC101 | Exactly one H1 | Search engines and screen readers take the H1 as the name of the page; none or several make it unclear. | warning | every step with the pack |
| HC102 | Title between 10 and 70 characters | The title is the blue link in search results; too short says nothing, too long gets cut. | warning | every step with the pack |
| HC103 | Meta description between 50 and 160 characters | The meta description is the snippet under the link; without it search engines pick random text. | warning | every step with the pack |
| HC104 | Canonical link present | Without a canonical URL, copies of the page (parameters, filters) compete with each other in search. | warning | every step with the pack |
| HC105 | hreflang for every language | hreflang tells search engines which language version to show to whom. | warning | scenarios with more than one locale |
| HC106 | Open Graph title and description | Shared links on social networks and chats use Open Graph for their preview. | warning | every step with the pack |
| HC107 | Not excluded from indexing | A noindex robots tag keeps the page out of search results entirely. | error | every step with the pack |
| HC108 | Viewport meta for phones | Without the viewport tag phones show a zoomed-out desktop page. | error | every step with the pack |
| HC109 | html lang attribute set | Screen readers pick the voice and search engines the language from <html lang>. | warning | every step with the pack |
| HC110 | No horizontal overflow | Content wider than the screen makes phones scroll sideways and breaks the layout. | error | every step with the pack |
| HC111 | No console errors | Console errors often mean a feature silently does not work. | error | every step with the pack |
| HC112 | Structured data (JSON-LD) present | Structured data tells search engines and AI assistants what the page is (a product with a price, an article, a FAQ) and earns rich results. | warning | every step with the pack |
| HC113 | Every JSON-LD block is valid JSON | A block that does not parse is ignored whole: the price, breadcrumbs or FAQ in it never reach search results. | warning | every step with the pack |
| HC121 | Titles are unique within a language | Pages with the same title look like duplicates to search engines, which then pick one and hide the others. | warning | stack steps, across their pages |
| HC122 | Meta descriptions are unique within a language | A description copied across pages tells searchers nothing about the one they are about to open. | warning | stack steps, across their pages |
| HC123 | H1 headings are unique within a language | Two pages with one H1 compete for the same search and confuse people who land on the wrong one. | warning | stack steps, across their pages |
| HC124 | Every page is its own canonical, and no canonical points to an error or noindex page | A canonical that points elsewhere asks search engines to drop the page; pointing at an error or noindex page drops both. | warning | stack steps, across their pages |
| HC125 | hreflang alternates answer back: each language version links to the others and to itself | Search engines ignore hreflang that is not confirmed from the other side, so the wrong language shows up in results. | warning | stack steps, across their pages |
| HC126 | Pages listed in the sitemap answer 200 without a redirect and are indexable | A sitemap is the list of pages you want found; redirects, errors and noindex in it waste the crawl and erode trust in the whole list. | warning | stacks read from a sitemap |
| HC127 | Pages seen often in search are not clicked far less than the site's other pages at similar positions | Searchers see the page but pick another result: the title and description in the results do not promise what they are looking for. | warning | stacks with traffic data |
Answer engines (aeo)
What AI search and assistants pick up: FAQ structured data, a short answer under the H1, llms.txt, a meta description, and the page as GPTBot gets it without JavaScript. Cheap signals from the page, not a ranking in any assistant.
Off on design environments, where the steps are your own HTML served from a folder. To keep it on there, list it in health: { design_packs: [...] } in the scenario.
| Id | Check | Why it matters | Severity | Applies to |
|---|---|---|---|---|
| HC901 | Questions and answers on the page have FAQPage or QAPage structured data | Answer engines and rich results pick up questions and answers much more reliably when the page marks them as FAQPage or QAPage. | warning | every step with the pack |
| HC902 | A short answer-first paragraph follows the H1 (40 to 320 characters) | AI assistants quote the first clear answer they find; a short paragraph right under the heading is the one they take. | warning | every step with the pack |
| HC903 | llms.txt is reachable at the site root | llms.txt gives language models a short map of the site: what it offers and which pages to read. | warning | every step with the pack |
| HC904 | Meta description present | Without a meta description, search engines and assistants write their own summary from random text. | warning | every step with the pack |
| HC905 | Without JavaScript, GPTBot gets the title, canonical, H1, structured data and most of the text | Most AI crawlers do not run JavaScript. What appears only after scripts run does not exist for them, even if the page looks complete in a browser. | warning | every step with the pack |
Accessibility (a11y)
The part of WCAG 2.2 AA that can be measured on the page, a walk with the Tab key (without clicking or typing) and the accessibility tree. It does not replace an audit with a screen reader.
Runs on design environments too.
| Id | Check | Why it matters | Severity | Applies to |
|---|---|---|---|---|
| HC301 | Images have alternative text | Without alt text, blind visitors and search engines do not know what an image shows. | error | every step with the pack |
| HC302 | Links and buttons have an accessible name | An icon button without a name is read as just "button". | error | every step with the pack |
| HC303 | Form fields have labels | Screen reader users hear only "edit text" for a field without a label. | error | every step with the pack |
| HC304 | Heading levels are not skipped | People navigate by headings; a jump from H2 to H4 hides the structure. | warning | every step with the pack |
| HC305 | Text meets WCAG AA contrast | Low contrast text is hard to read in sunlight and for people with weaker sight. | error | every step with the pack |
| HC306 | The page has a main landmark | Screen reader users jump straight to <main> to skip the navigation. | warning | every step with the pack |
| HC307 | Element ids are unique | Duplicate ids break labels, anchors and scripts that look elements up by id. | warning | every step with the pack |
| HC308 | Tab order follows the page and reaches every control | People who use a keyboard move with Tab; focus that jumps around or skips a button leaves them lost or stuck. | warning | every step with the pack |
| HC309 | Keyboard focus is clearly visible (at least 3:1 contrast) | Without a visible focus ring, keyboard users do not know where they are on the page. | warning | every step with the pack |
| HC310 | No keyboard trap | A widget that keeps Tab inside (an embed, a custom menu) traps keyboard users for good. | error | every step with the pack |
| HC311 | A skip link or an early way into the main content | Without a skip link, keyboard and screen reader users tab through the whole menu on every page. | warning | every step with the pack |
| HC312 | Controls have a name in the accessibility tree | The accessibility tree is what screen readers read; a control without a name there is announced as just "button". | error | every step with the pack |
| HC313 | Landmarks are complete and labelled | Screen reader users jump between header, navigation, main and footer; duplicates without names all sound the same. | warning | every step with the pack |
| HC314 | ARIA roles and attributes are valid | Wrong ARIA is worse than none: screen readers trust it and announce things that are not there. | warning | every step with the pack |
Usability (usability)
Questions for the evaluator, picked by the page type of the step (page: landing, work, list, settings, form, doc), and labelled form fields.
Runs on design environments too.
| Id | Check | Why it matters | Severity | Applies to |
|---|---|---|---|---|
| HC201 | The purpose of the page is clear within the first screen | Visitors decide within seconds whether they are in the right place. | warning | page types landing, doc |
| HC202 | One clear primary action | Several equally loud buttons make people hesitate; none leaves them without a next step. | warning | page type landing |
| HC203 | Form fields have visible labels | A placeholder disappears as people type; they forget what the field was. | warning | every step with the pack |
| HC204 | Links and buttons say what they do | "Click here" or "More" does not say where it leads, especially out of context or to a screen reader. | warning | every step with the pack |
| HC205 | The heading says what the screen is for | People switch between screens all day; a vague heading makes them check where they are. | warning | page types work, list, settings, form |
| HC207 | Each item in the list says what it is and how to open it | A row with only an id or a date makes people open items one by one to find the right one. | warning | page type list |
| HC208 | Each setting says what it changes and how it is saved | People leave settings unsure whether the change took effect. | warning | page type settings |
| HC206 | It is clear how to send the form and what happens next | When the send button or the next step is unclear, people submit twice or give up. | warning | page type form |
| HC209 | The text can be scanned: headings and short paragraphs | Readers of documentation scan for their question; a wall of text hides the answer. | warning | page type doc |
Performance (perf)
Lab values measured in the walk's browser: LCP, CLS, TTFB and page weight. Real visitors on slower phones may see other numbers.
Off on design environments, where the steps are your own HTML served from a folder. To keep it on there, list it in health: { design_packs: [...] } in the scenario.
| Id | Check | Why it matters | Severity | Applies to |
|---|---|---|---|---|
| HC401 | Largest contentful paint within 2.5 s | LCP is how long people wait before the page looks ready; Google uses it for ranking. | warning | every step with the pack |
| HC402 | Cumulative layout shift below 0.1 | Content that jumps while loading makes people tap the wrong thing. | warning | every step with the pack |
| HC403 | Time to first byte within 800 ms | A slow first byte delays everything else on the page. | warning | every step with the pack |
| HC404 | Page weight within 3 MB | Heavy pages are slow and expensive on mobile data. | warning | every step with the pack |
Console (console)
The evaluator reads the console errors of the step and says whether they touch what the step accepts or are noise from third-party scripts.
Off on design environments, where the steps are your own HTML served from a folder. To keep it on there, list it in health: { design_packs: [...] } in the scenario.
| Id | Check | Why it matters | Severity | Applies to |
|---|---|---|---|---|
| HC501 | Console errors do not touch what the step accepts | Separates real failures from third-party noise (analytics, extensions). | error | every step with the pack |
Error pages (errors)
For 404, 410, 500 and maintenance pages: a real error status, a way back, and no technical detail leaking out. Meant for steps that are error pages.
Off on design environments, where the steps are your own HTML served from a folder. To keep it on there, list it in health: { design_packs: [...] } in the scenario.
| Id | Check | Why it matters | Severity | Applies to |
|---|---|---|---|---|
| HC601 | Answers with an error status (4xx/5xx), not a soft 200 | A missing page that answers 200 gets indexed as real content and hides broken links from monitoring. | error | error pages only (expect_status, or a page answering 4xx/5xx) |
| HC602 | Links back to the home page | A dead end loses the visitor. | warning | every step with the pack |
| HC603 | Navigation or search stays available | People on an error page want to find what they came for. | warning | every step with the pack |
| HC604 | No stack trace, SQL error or framework debug page | Stack traces leak paths, versions and queries that help attackers. | error | every step with the pack |
| HC605 | Explains the error in plain language and offers a way forward | A calm explanation keeps people on the site instead of leaving. | warning | error pages only (expect_status, or a page answering 4xx/5xx) |
| HC606 | No console errors | Scripts failing on the error page often break its navigation too. | error | every step with the pack |
Language versions (locale)
For multilingual sites: html lang, the page's own hreflang, the language of the text and the decimal separator of prices match the walked locale. Only in scenarios that list their locales.
Runs on design environments too.
| Id | Check | Why it matters | Severity | Applies to |
|---|---|---|---|---|
| HC1001 | html lang matches the walked locale | Screen readers pick the voice and search engines the language from html lang; a German page marked as English is read with an English accent. | warning | every step with the pack |
| HC1002 | The page's own hreflang names it with the walked locale, codes are valid and agree with the addresses | A wrong own hreflang or a code such as en_UK makes search engines skip the whole set of language versions. | warning | every step with the pack |
| HC1003 | The text is in the language of the walked locale | An untranslated page in a language version loses its visitors and looks like duplicate content of the source language. | warning | every step with the pack |
| HC1004 | Prices use the decimal separator of the walked locale | 12.50 € reads oddly to a German or Czech customer and 12,50 $ to an American; it looks like the shop was not made for them. | warning | every step with the pack |
| HC1005 | Every page has its own language version (hreflang) in each walked locale | A page without its translation sends visitors of that language to the wrong one, and search shows them whatever is left; several pages pointing to one version usually mean a fallback to a listing or the home page. | warning | stacks with items.variants: hreflang |
App screens (app)
Native apps on Android, iOS and desktop: labelled controls, touch targets, cut-off text, crashes and a clear next step.
| Id | Check | Why it matters | Severity | Applies to |
|---|---|---|---|---|
| HC701 | Every control has an accessible label | VoiceOver and TalkBack read unlabeled controls as "button". | error | every step with the pack |
| HC702 | Touch targets at least 48 dp (Android) / 44 pt (iOS) | Small targets are missed, especially by thumbs and older people. | warning | every step with the pack |
| HC703 | No truncated texts (…) | Cut text hides prices, names or instructions, often only in longer languages. | warning | every step with the pack |
| HC704 | The app did not crash or stop responding | A crash or an "app not responding" dialog ends the session. | error | every step with the pack |
| HC705 | The purpose of the screen and the next action are clear | On a small screen, people need to see at once what to do next. | warning | every step with the pack |
Design reference (design)
The implementation against the accepted design version: pixels, structure and tokens. The only pack that always counts for acceptance, so its ids are AC.
| Id | Check | Why it matters | Severity | Applies to |
|---|---|---|---|---|
| AC801 | Looks like the design reference (under 3 % of pixels differ) | Visible differences from the accepted design mean it was built differently than agreed. | acceptance criterion | every step with the pack |
| AC802 | Same structure as the design reference: headings, landmarks, actions and form fields | Missing headings, actions or fields change what people can do, even if it looks close. | acceptance criterion | every step with the pack |
| AC803 | Colors, fonts, sizes, spacing and radii come from the token set | Raw values drift from the design system and make later changes expensive. | acceptance criterion | every step with the pack |
Site checks (site)
Once per site and run, not per step: robots.txt, the sitemaps it lists, llms.txt and the redirects to https and to one host name. Off unless the scenario sets health: { site: true }, because they make requests of their own. They cannot be adopted as criteria.
| Id | Check | Why it matters | Severity | Applies to |
|---|---|---|---|---|
| HC1101 | robots.txt answers 200 and every line parses | Crawlers skip lines they do not understand, so a typo such as "Disalow" silently opens or closes part of the site; a server error stops crawling altogether. | warning | once per site |
| HC1102 | robots.txt does not block the walked start pages for search engines | A Disallow that covers the home page or a language root removes the site from search, often after a staging setting reached production. | error on production, warning elsewhere | once per site |
| HC1103 | robots.txt does not block AI crawlers (GPTBot, OAI-SearchBot, ChatGPT-User, PerplexityBot, ClaudeBot, Google-Extended, CCBot) | GPTBot, ClaudeBot, PerplexityBot and others read robots.txt; blocked, the site does not appear in AI answers and assistants cannot open its pages for users. | warning | once per site, on production only |
| HC1104 | Every sitemap answers, is valid XML, and lists absolute same-host addresses with sane lastmod dates | A broken or cut-off sitemap, relative addresses or another host make search engines ignore it, and made-up lastmod dates teach them to ignore those too. | warning | once per site |
| HC1105 | llms.txt is reachable at the site root | llms.txt gives language models a short map of the site: what it offers and which pages to read. | warning | once per site |
| HC1106 | http:// redirects to https:// in one hop | Each extra redirect costs time on every first visit, and a page served over http:// splits links and rankings between two addresses. | warning | once per site |
| HC1107 | The other host name (with or without www) redirects in one hop | When both example.com and www.example.com answer, search engines see two copies of the site; a chain of redirects slows every visit that comes the other way. | warning | once per site |