Docs

Kaloko

Download
Markdown with pictures (.zip)Docusaurus folder (.zip)VitePress folder (.zip)MkDocs folder (.zip)Offline HTML (.zip)PDFChangelog as JSON
Pages

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.

IdCheckWhy it mattersSeverityApplies to
HC101Exactly one H1Search engines and screen readers take the H1 as the name of the page; none or several make it unclear.warningevery step with the pack
HC102Title between 10 and 70 charactersThe title is the blue link in search results; too short says nothing, too long gets cut.warningevery step with the pack
HC103Meta description between 50 and 160 charactersThe meta description is the snippet under the link; without it search engines pick random text.warningevery step with the pack
HC104Canonical link presentWithout a canonical URL, copies of the page (parameters, filters) compete with each other in search.warningevery step with the pack
HC105hreflang for every languagehreflang tells search engines which language version to show to whom.warningscenarios with more than one locale
HC106Open Graph title and descriptionShared links on social networks and chats use Open Graph for their preview.warningevery step with the pack
HC107Not excluded from indexingA noindex robots tag keeps the page out of search results entirely.errorevery step with the pack
HC108Viewport meta for phonesWithout the viewport tag phones show a zoomed-out desktop page.errorevery step with the pack
HC109html lang attribute setScreen readers pick the voice and search engines the language from <html lang>.warningevery step with the pack
HC110No horizontal overflowContent wider than the screen makes phones scroll sideways and breaks the layout.errorevery step with the pack
HC111No console errorsConsole errors often mean a feature silently does not work.errorevery step with the pack
HC112Structured data (JSON-LD) presentStructured data tells search engines and AI assistants what the page is (a product with a price, an article, a FAQ) and earns rich results.warningevery step with the pack
HC113Every JSON-LD block is valid JSONA block that does not parse is ignored whole: the price, breadcrumbs or FAQ in it never reach search results.warningevery step with the pack
HC121Titles are unique within a languagePages with the same title look like duplicates to search engines, which then pick one and hide the others.warningstack steps, across their pages
HC122Meta descriptions are unique within a languageA description copied across pages tells searchers nothing about the one they are about to open.warningstack steps, across their pages
HC123H1 headings are unique within a languageTwo pages with one H1 compete for the same search and confuse people who land on the wrong one.warningstack steps, across their pages
HC124Every page is its own canonical, and no canonical points to an error or noindex pageA canonical that points elsewhere asks search engines to drop the page; pointing at an error or noindex page drops both.warningstack steps, across their pages
HC125hreflang alternates answer back: each language version links to the others and to itselfSearch engines ignore hreflang that is not confirmed from the other side, so the wrong language shows up in results.warningstack steps, across their pages
HC126Pages listed in the sitemap answer 200 without a redirect and are indexableA 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.warningstacks read from a sitemap
HC127Pages seen often in search are not clicked far less than the site's other pages at similar positionsSearchers see the page but pick another result: the title and description in the results do not promise what they are looking for.warningstacks 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.

IdCheckWhy it mattersSeverityApplies to
HC901Questions and answers on the page have FAQPage or QAPage structured dataAnswer engines and rich results pick up questions and answers much more reliably when the page marks them as FAQPage or QAPage.warningevery step with the pack
HC902A 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.warningevery step with the pack
HC903llms.txt is reachable at the site rootllms.txt gives language models a short map of the site: what it offers and which pages to read.warningevery step with the pack
HC904Meta description presentWithout a meta description, search engines and assistants write their own summary from random text.warningevery step with the pack
HC905Without JavaScript, GPTBot gets the title, canonical, H1, structured data and most of the textMost 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.warningevery 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.

IdCheckWhy it mattersSeverityApplies to
HC301Images have alternative textWithout alt text, blind visitors and search engines do not know what an image shows.errorevery step with the pack
HC302Links and buttons have an accessible nameAn icon button without a name is read as just "button".errorevery step with the pack
HC303Form fields have labelsScreen reader users hear only "edit text" for a field without a label.errorevery step with the pack
HC304Heading levels are not skippedPeople navigate by headings; a jump from H2 to H4 hides the structure.warningevery step with the pack
HC305Text meets WCAG AA contrastLow contrast text is hard to read in sunlight and for people with weaker sight.errorevery step with the pack
HC306The page has a main landmarkScreen reader users jump straight to <main> to skip the navigation.warningevery step with the pack
HC307Element ids are uniqueDuplicate ids break labels, anchors and scripts that look elements up by id.warningevery step with the pack
HC308Tab order follows the page and reaches every controlPeople who use a keyboard move with Tab; focus that jumps around or skips a button leaves them lost or stuck.warningevery step with the pack
HC309Keyboard 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.warningevery step with the pack
HC310No keyboard trapA widget that keeps Tab inside (an embed, a custom menu) traps keyboard users for good.errorevery step with the pack
HC311A skip link or an early way into the main contentWithout a skip link, keyboard and screen reader users tab through the whole menu on every page.warningevery step with the pack
HC312Controls have a name in the accessibility treeThe accessibility tree is what screen readers read; a control without a name there is announced as just "button".errorevery step with the pack
HC313Landmarks are complete and labelledScreen reader users jump between header, navigation, main and footer; duplicates without names all sound the same.warningevery step with the pack
HC314ARIA roles and attributes are validWrong ARIA is worse than none: screen readers trust it and announce things that are not there.warningevery 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.

IdCheckWhy it mattersSeverityApplies to
HC201The purpose of the page is clear within the first screenVisitors decide within seconds whether they are in the right place.warningpage types landing, doc
HC202One clear primary actionSeveral equally loud buttons make people hesitate; none leaves them without a next step.warningpage type landing
HC203Form fields have visible labelsA placeholder disappears as people type; they forget what the field was.warningevery step with the pack
HC204Links 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.warningevery step with the pack
HC205The heading says what the screen is forPeople switch between screens all day; a vague heading makes them check where they are.warningpage types work, list, settings, form
HC207Each item in the list says what it is and how to open itA row with only an id or a date makes people open items one by one to find the right one.warningpage type list
HC208Each setting says what it changes and how it is savedPeople leave settings unsure whether the change took effect.warningpage type settings
HC206It is clear how to send the form and what happens nextWhen the send button or the next step is unclear, people submit twice or give up.warningpage type form
HC209The text can be scanned: headings and short paragraphsReaders of documentation scan for their question; a wall of text hides the answer.warningpage 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.

IdCheckWhy it mattersSeverityApplies to
HC401Largest contentful paint within 2.5 sLCP is how long people wait before the page looks ready; Google uses it for ranking.warningevery step with the pack
HC402Cumulative layout shift below 0.1Content that jumps while loading makes people tap the wrong thing.warningevery step with the pack
HC403Time to first byte within 800 msA slow first byte delays everything else on the page.warningevery step with the pack
HC404Page weight within 3 MBHeavy pages are slow and expensive on mobile data.warningevery 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.

IdCheckWhy it mattersSeverityApplies to
HC501Console errors do not touch what the step acceptsSeparates real failures from third-party noise (analytics, extensions).errorevery 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.

IdCheckWhy it mattersSeverityApplies to
HC601Answers with an error status (4xx/5xx), not a soft 200A missing page that answers 200 gets indexed as real content and hides broken links from monitoring.errorerror pages only (expect_status, or a page answering 4xx/5xx)
HC602Links back to the home pageA dead end loses the visitor.warningevery step with the pack
HC603Navigation or search stays availablePeople on an error page want to find what they came for.warningevery step with the pack
HC604No stack trace, SQL error or framework debug pageStack traces leak paths, versions and queries that help attackers.errorevery step with the pack
HC605Explains the error in plain language and offers a way forwardA calm explanation keeps people on the site instead of leaving.warningerror pages only (expect_status, or a page answering 4xx/5xx)
HC606No console errorsScripts failing on the error page often break its navigation too.errorevery 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.

IdCheckWhy it mattersSeverityApplies to
HC1001html lang matches the walked localeScreen readers pick the voice and search engines the language from html lang; a German page marked as English is read with an English accent.warningevery step with the pack
HC1002The page's own hreflang names it with the walked locale, codes are valid and agree with the addressesA wrong own hreflang or a code such as en_UK makes search engines skip the whole set of language versions.warningevery step with the pack
HC1003The text is in the language of the walked localeAn untranslated page in a language version loses its visitors and looks like duplicate content of the source language.warningevery step with the pack
HC1004Prices use the decimal separator of the walked locale12.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.warningevery step with the pack
HC1005Every page has its own language version (hreflang) in each walked localeA 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.warningstacks 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.

IdCheckWhy it mattersSeverityApplies to
HC701Every control has an accessible labelVoiceOver and TalkBack read unlabeled controls as "button".errorevery step with the pack
HC702Touch targets at least 48 dp (Android) / 44 pt (iOS)Small targets are missed, especially by thumbs and older people.warningevery step with the pack
HC703No truncated texts (…)Cut text hides prices, names or instructions, often only in longer languages.warningevery step with the pack
HC704The app did not crash or stop respondingA crash or an "app not responding" dialog ends the session.errorevery step with the pack
HC705The purpose of the screen and the next action are clearOn a small screen, people need to see at once what to do next.warningevery 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.

IdCheckWhy it mattersSeverityApplies to
AC801Looks like the design reference (under 3 % of pixels differ)Visible differences from the accepted design mean it was built differently than agreed.acceptance criterionevery step with the pack
AC802Same structure as the design reference: headings, landmarks, actions and form fieldsMissing headings, actions or fields change what people can do, even if it looks close.acceptance criterionevery step with the pack
AC803Colors, fonts, sizes, spacing and radii come from the token setRaw values drift from the design system and make later changes expensive.acceptance criterionevery 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.

IdCheckWhy it mattersSeverityApplies to
HC1101robots.txt answers 200 and every line parsesCrawlers 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.warningonce per site
HC1102robots.txt does not block the walked start pages for search enginesA 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 elsewhereonce per site
HC1103robots.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.warningonce per site, on production only
HC1104Every sitemap answers, is valid XML, and lists absolute same-host addresses with sane lastmod datesA 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.warningonce per site
HC1105llms.txt is reachable at the site rootllms.txt gives language models a short map of the site: what it offers and which pages to read.warningonce per site
HC1106http:// redirects to https:// in one hopEach extra redirect costs time on every first visit, and a page served over http:// splits links and rankings between two addresses.warningonce per site
HC1107The other host name (with or without www) redirects in one hopWhen 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.warningonce per site
On this pageOn this page