@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/accessibility.md

@@ -1,171 +1,171 @@
----
-title: "Accessibility"
-description: "WCAG 2.2 AA rules for converted and built sites: alt text, media, forms, contrast, links, motion, the audit codes, and the manual check list to run before reporting done."
----
-
-# Accessibility
-
-**Outcome.** A converted or built site meets WCAG 2.2 AA where BetterCMS lets an agent control
-it, and the report says plainly what was checked and what was not.
-
-`list_seo_issues` reports the checkable items as `a11y.` codes, from the stored blocks of
-published pages: image alt missing, h1 missing, several h1, an h1 inside body text, a skipped
-heading level, generic link or button text, a video with no transcript. Each names the page and
-its block ids. It cannot see inside a `component` or `collection` block, an entry's fields, or a
-route the repo's code renders, and a clean result says nothing about contrast, focus order,
-keyboard use or form behaviour. Those stay manual: read the rendered page, then report what you
-saw. Never write "WCAG compliant"; write "checked against this list, with these exceptions".
-
-Related: [media-and-brand.md](media-and-brand.md) (assets, SVG, video, focal point),
-[forms-and-interactions.md](forms-and-interactions.md) (form fields, interactive patterns),
-[portable-text.md](portable-text.md) (heading levels, lists, tables), [seo.md](seo.md).
-
-## Contents
-
-- [Where each fact is stored](#where-each-fact-is-stored) · [Alt text](#alt-text)
-- [Video and audio](#video-and-audio) · [Forms](#forms) · [Structure and links](#structure-and-links)
-- [Colour, contrast and motion](#colour-contrast-and-motion) · [Check list before done](#check-list-before-done)
-- [What to report](#what-to-report)
-
-## Where each fact is stored
-
-| Fact | Lives in | Write with |
-|---|---|---|
-| Alt text of an image | `altText` on the image value, and on the media asset | the value in the entry or page write; `update_media` `altText` for the asset |
-| Caption | `caption` on the asset | `update_media` `caption` |
-| Transcript (video or audio) | the asset, published wherever the file is used | `update_media` `transcript` (at most 100,000 characters) |
-| Decorative image | `decorative` on the asset; an empty `altText` on one value | `update_media` `decorative: true`; the value in the entry or page write |
-| Captions track (`.vtt`) | not stored by any tool | report as missing; the owner adds it |
-| Form label, required mark, help text, consent wording | the Form's fields | `create_form` / `update_form` |
-| Icon-only link or button label | the element's `aria-label` or visually hidden text in the code, or the component prop that feeds it | code, or the component prop |
-| Page language | the page or entry `locale` | see [localization.md](localization.md) |
-| Page title | `metaTitle` | see [seo.md](seo.md) |
-
-An image value is an object, never a bare string. Alt on the asset is the default; alt on the
-value is for this placement only. Set both when the same file reads differently in two places.
-
-## Alt text
-
-An asset that is decoration wherever it is used takes `update_media` `decorative: true`: the
-audit stops asking for its alt text. An image VALUE has no such flag; an empty alt marks that one
-placement as decoration. A missing alt and a deliberately empty alt look the same to the next
-reader, so list every empty alt you left on purpose.
-
-| Image | Alt |
-|---|---|
-| Informative | What it shows that matters in this place. Never the file name, "image of", "photo" or "logo" |
-| Logo | The company name. A linked logo says where it goes ("Caldera home") |
-| Person | "Portrait of {name}" |
-| Product | The product name and what the photo shows |
-| Chart or diagram | One sentence with the trend or the point; put the numbers in real text nearby |
-| Image of text (size guide, menu) | Rebuild it as a table or list; keep the image only as a diagram |
-| Background image that carries meaning | Make it an image with alt, or mark it decorative |
-| Decorative (rule, flourish, duplicate of nearby text) | Empty alt; `decorative: true` on the asset when it is never informative |
-
-- Copy the source's real alt when it is good. Rewrite "image of ..." and file-name alt to
-  describe the image.
-- Missing or junk alt on a meaningful image: write it from the visible context and flag
-  `alt-written` for review. With no context to draw on, leave it empty and flag `alt-missing`.
-- An empty alt is right for decoration and wrong on a portfolio, product or team photo. Flag
-  every empty alt on a content image.
-- Generated images (`generate_image`, `transform_image`) always get `altText`.
-
-## Video and audio
-
-- Never invent captions or a transcript. If the source has none, leave the field empty, and
-  report it.
-- A transcript you produced from your own speech-to-text goes on the asset with `update_media`
-  `transcript`. It then publishes on the page, the Markdown twin, llms-full.txt and the delivery
-  API. BetterCMS does not generate transcripts.
-- Captions are `.vtt` files and no BetterCMS field stores them. State "captions missing" in the
-  report for any video with speech.
-- A video needs a poster image and autoplays only muted.
-- An embed needs a `title` naming the provider and what it shows. Write one when missing.
-- An animation, Lottie or 3D scene needs a poster or fallback image and a text label, and must
-  stop for reduced motion.
-
-## Forms
-
-Forms are Form records, so the rules apply to the form's fields ([forms-and-interactions.md](forms-and-interactions.md)).
-
-- Every field has a `label`, which the renderer shows as a visible label. A placeholder is not a
-  label. If the source used placeholders only, write a label from each, and flag it.
-- Mark required fields with `required: true`. The hosted renderer adds an asterisk; say in the
-  field's `helpText` or the form intro that starred fields are required, so colour or a symbol is
-  never the only signal.
-- `helpText` carries the format or constraint ("Use the number on your invoice"). A refused
-  submission returns `issues[].field` and `issues[].rule`; show the field name and the fix in the
-  form's error copy.
-- Consent: a `consent` field starts unticked and must be ticked to submit. Import a source's
-  pre-ticked box as unticked, and flag it. Import confirmshaming copy as written, then flag it
-  with a neutral rewrite.
-- `autocomplete` is not a field setting. The hosted and Next renderers set it where they know
-  it (phone). For a self-hosted form with its own markup, keep the source's values (`email`,
-  `given-name`, `tel`, `postal-code`).
-- A form result (success, error) must be announced. The Next `BcmsForm` uses a live region; check
-  that a custom form does too.
-
-## Structure and links
-
-- Heading levels follow the outline: one H1, no skipped level. How a heading level is chosen and
-  stored is in [portable-text.md](portable-text.md). Size is a style token, never a reason to
-  pick a level.
-- Lists, tables and quotes use their real Portable Text blocks, never lines of text with
-  bullets or spaces.
-- Link text says where it goes. Replace "click here", "read more" and "learn more" on their own
-  with the target ("Read the care guide"). Where the card layout forces a short visible label,
-  add the target as visually hidden text or an `aria-label` in code.
-- Icon-only links and buttons (social icons, close, menu, carousel arrows) have an `aria-label`
-  or hidden text. A dot or a map pin that links needs one too. Draft the label and flag it; never
-  leave it empty.
-- Navigation, footer and announcement bar belong in Global Layout (`update_layout`). Check the
-  skip link, the landmark roles (`header`, `nav`, `main`, `footer`) and that the mobile menu
-  opens by keyboard and returns focus.
-- Set the page `locale`. Mark a foreign phrase inside text with `lang` in code.
-- DOM order is reading order; never reorder with CSS. Targets are at least 24 by 24 CSS pixels.
-
-## Colour, contrast and motion
-
-- Contrast: 4.5:1 for body text, 3:1 for large text (24px, or 19px bold) and for borders of
-  controls and icons that carry meaning. Check each theme and each variant the editor can pick,
-  including text over photos.
-- Take colour from brand tokens and section styles, never from a copied hex
-  ([media-and-brand.md](media-and-brand.md)). A brand colour that fails contrast is reported
-  with the pair and ratio; never change the kit unasked.
-- Information is never colour alone: a status dot has a word beside it; a check mark has
-  "Included" beside it.
-- Respect reduced motion: scroll stories stack, parallax goes still, Lottie shows its fallback.
-- Carousels, marquees and auto-advancing tabs need a pause control and stop when focused.
-
-## Check list before done
-
-Run `list_seo_issues` first and fix every `a11y.` code (rows 1, 3, 4 and 5 for hosted pages).
-Then run these on the rendered pages (desktop and a 390 px mobile width), not on the stored data.
-Cover the home page, one page per template, one entry per collection, and every form page.
-
-| # | Check | How |
-|---|---|---|
-| 1 | Every informative image has alt; every empty alt is intentional | read each image's `altText` in the page output; list empties |
-| 2 | No alt is a file name, "image of" or "logo" | scan the same list |
-| 3 | Video and audio: transcript on the asset, captions reported | `get_media`, then the player |
-| 4 | One H1, no skipped heading levels | outline the headings in order |
-| 5 | Link text is meaningful out of context | list all links; fix vague ones |
-| 6 | Icon-only controls have a name | inspect each; draft and flag |
-| 7 | Every form field has a visible label, required is stated in text, consent is unticked | `get_form`, then the page |
-| 8 | A refused submission names the field and the fix | send one bad test submission |
-| 9 | Contrast meets 4.5:1 and 3:1 in every theme | measure real colour pairs |
-| 10 | Whole page works by keyboard: tab order, visible focus, menu, dialog, accordion, tabs | tab through it |
-| 12 | Motion stops or stills under reduced motion | emulate the preference |
-| 13 | Page has a title and a language | `list_seo_issues` for title; check `locale` |
-| 14 | Embeds have a title; moving content can pause | inspect each |
-
-## What to report
-
-Report accessibility as its own short block in the final report:
-
-- Checked: the pages and the rows above you ran.
-- Written: drafted alt (`alt-written`), labels and transcripts. Left empty on purpose: decorative
-  images, and each asset marked `decorative`.
-- Open: `alt-missing`, captions missing, contrast failures with the measured ratio, controls you
-  could not test (a third-party embed, a payment step).
-- Not claimed: conformance. No tool certifies it; the audit covers stored blocks only.
+---
+title: "Accessibility"
+description: "WCAG 2.2 AA rules for converted and built sites: alt text, media, forms, contrast, links, motion, the audit codes, and the manual check list to run before reporting done."
+---
+
+# Accessibility
+
+**Outcome.** A converted or built site meets WCAG 2.2 AA where BetterCMS lets an agent control
+it, and the report says plainly what was checked and what was not.
+
+`list_seo_issues` reports the checkable items as `a11y.` codes, from the stored blocks of
+published pages: image alt missing, h1 missing, several h1, an h1 inside body text, a skipped
+heading level, generic link or button text, a video with no transcript. Each names the page and
+its block ids. It cannot see inside a `component` or `collection` block, an entry's fields, or a
+route the repo's code renders, and a clean result says nothing about contrast, focus order,
+keyboard use or form behaviour. Those stay manual: read the rendered page, then report what you
+saw. Never write "WCAG compliant"; write "checked against this list, with these exceptions".
+
+Related: [media-and-brand.md](media-and-brand.md) (assets, SVG, video, focal point),
+[forms-and-interactions.md](forms-and-interactions.md) (form fields, interactive patterns),
+[portable-text.md](portable-text.md) (heading levels, lists, tables), [seo.md](seo.md).
+
+## Contents
+
+- [Where each fact is stored](#where-each-fact-is-stored) · [Alt text](#alt-text)
+- [Video and audio](#video-and-audio) · [Forms](#forms) · [Structure and links](#structure-and-links)
+- [Colour, contrast and motion](#colour-contrast-and-motion) · [Check list before done](#check-list-before-done)
+- [What to report](#what-to-report)
+
+## Where each fact is stored
+
+| Fact | Lives in | Write with |
+|---|---|---|
+| Alt text of an image | `altText` on the image value, and on the media asset | the value in the entry or page write; `update_media` `altText` for the asset |
+| Caption | `caption` on the asset | `update_media` `caption` |
+| Transcript (video or audio) | the asset, published wherever the file is used | `update_media` `transcript` (at most 100,000 characters) |
+| Decorative image | `decorative` on the asset; an empty `altText` on one value | `update_media` `decorative: true`; the value in the entry or page write |
+| Captions track (`.vtt`) | not stored by any tool | report as missing; the owner adds it |
+| Form label, required mark, help text, consent wording | the Form's fields | `create_form` / `update_form` |
+| Icon-only link or button label | the element's `aria-label` or visually hidden text in the code, or the component prop that feeds it | code, or the component prop |
+| Page language | the page or entry `locale` | see [localization.md](localization.md) |
+| Page title | `metaTitle` | see [seo.md](seo.md) |
+
+An image value is an object, never a bare string. Alt on the asset is the default; alt on the
+value is for this placement only. Set both when the same file reads differently in two places.
+
+## Alt text
+
+An asset that is decoration wherever it is used takes `update_media` `decorative: true`: the
+audit stops asking for its alt text. An image VALUE has no such flag; an empty alt marks that one
+placement as decoration. A missing alt and a deliberately empty alt look the same to the next
+reader, so list every empty alt you left on purpose.
+
+| Image | Alt |
+|---|---|
+| Informative | What it shows that matters in this place. Never the file name, "image of", "photo" or "logo" |
+| Logo | The company name. A linked logo says where it goes ("Caldera home") |
+| Person | "Portrait of {name}" |
+| Product | The product name and what the photo shows |
+| Chart or diagram | One sentence with the trend or the point; put the numbers in real text nearby |
+| Image of text (size guide, menu) | Rebuild it as a table or list; keep the image only as a diagram |
+| Background image that carries meaning | Make it an image with alt, or mark it decorative |
+| Decorative (rule, flourish, duplicate of nearby text) | Empty alt; `decorative: true` on the asset when it is never informative |
+
+- Copy the source's real alt when it is good. Rewrite "image of ..." and file-name alt to
+  describe the image.
+- Missing or junk alt on a meaningful image: write it from the visible context and flag
+  `alt-written` for review. With no context to draw on, leave it empty and flag `alt-missing`.
+- An empty alt is right for decoration and wrong on a portfolio, product or team photo. Flag
+  every empty alt on a content image.
+- Generated images (`generate_image`, `transform_image`) always get `altText`.
+
+## Video and audio
+
+- Never invent captions or a transcript. If the source has none, leave the field empty, and
+  report it.
+- A transcript you produced from your own speech-to-text goes on the asset with `update_media`
+  `transcript`. It then publishes on the page, the Markdown twin, llms-full.txt and the delivery
+  API. BetterCMS does not generate transcripts.
+- Captions are `.vtt` files and no BetterCMS field stores them. State "captions missing" in the
+  report for any video with speech.
+- A video needs a poster image and autoplays only muted.
+- An embed needs a `title` naming the provider and what it shows. Write one when missing.
+- An animation, Lottie or 3D scene needs a poster or fallback image and a text label, and must
+  stop for reduced motion.
+
+## Forms
+
+Forms are Form records, so the rules apply to the form's fields ([forms-and-interactions.md](forms-and-interactions.md)).
+
+- Every field has a `label`, which the renderer shows as a visible label. A placeholder is not a
+  label. If the source used placeholders only, write a label from each, and flag it.
+- Mark required fields with `required: true`. The hosted renderer adds an asterisk; say in the
+  field's `helpText` or the form intro that starred fields are required, so colour or a symbol is
+  never the only signal.
+- `helpText` carries the format or constraint ("Use the number on your invoice"). A refused
+  submission returns `issues[].field` and `issues[].rule`; show the field name and the fix in the
+  form's error copy.
+- Consent: a `consent` field starts unticked and must be ticked to submit. Import a source's
+  pre-ticked box as unticked, and flag it. Import confirmshaming copy as written, then flag it
+  with a neutral rewrite.
+- `autocomplete` is not a field setting. The hosted and Next renderers set it where they know
+  it (phone). For a self-hosted form with its own markup, keep the source's values (`email`,
+  `given-name`, `tel`, `postal-code`).
+- A form result (success, error) must be announced. The Next `BcmsForm` uses a live region; check
+  that a custom form does too.
+
+## Structure and links
+
+- Heading levels follow the outline: one H1, no skipped level. How a heading level is chosen and
+  stored is in [portable-text.md](portable-text.md). Size is a style token, never a reason to
+  pick a level.
+- Lists, tables and quotes use their real Portable Text blocks, never lines of text with
+  bullets or spaces.
+- Link text says where it goes. Replace "click here", "read more" and "learn more" on their own
+  with the target ("Read the care guide"). Where the card layout forces a short visible label,
+  add the target as visually hidden text or an `aria-label` in code.
+- Icon-only links and buttons (social icons, close, menu, carousel arrows) have an `aria-label`
+  or hidden text. A dot or a map pin that links needs one too. Draft the label and flag it; never
+  leave it empty.
+- Navigation, footer and announcement bar belong in Global Layout (`update_layout`). Check the
+  skip link, the landmark roles (`header`, `nav`, `main`, `footer`) and that the mobile menu
+  opens by keyboard and returns focus.
+- Set the page `locale`. Mark a foreign phrase inside text with `lang` in code.
+- DOM order is reading order; never reorder with CSS. Targets are at least 24 by 24 CSS pixels.
+
+## Colour, contrast and motion
+
+- Contrast: 4.5:1 for body text, 3:1 for large text (24px, or 19px bold) and for borders of
+  controls and icons that carry meaning. Check each theme and each variant the editor can pick,
+  including text over photos.
+- Take colour from brand tokens and section styles, never from a copied hex
+  ([media-and-brand.md](media-and-brand.md)). A brand colour that fails contrast is reported
+  with the pair and ratio; never change the kit unasked.
+- Information is never colour alone: a status dot has a word beside it; a check mark has
+  "Included" beside it.
+- Respect reduced motion: scroll stories stack, parallax goes still, Lottie shows its fallback.
+- Carousels, marquees and auto-advancing tabs need a pause control and stop when focused.
+
+## Check list before done
+
+Run `list_seo_issues` first and fix every `a11y.` code (rows 1, 3, 4 and 5 for hosted pages).
+Then run these on the rendered pages (desktop and a 390 px mobile width), not on the stored data.
+Cover the home page, one page per template, one entry per collection, and every form page.
+
+| # | Check | How |
+|---|---|---|
+| 1 | Every informative image has alt; every empty alt is intentional | read each image's `altText` in the page output; list empties |
+| 2 | No alt is a file name, "image of" or "logo" | scan the same list |
+| 3 | Video and audio: transcript on the asset, captions reported | `get_media`, then the player |
+| 4 | One H1, no skipped heading levels | outline the headings in order |
+| 5 | Link text is meaningful out of context | list all links; fix vague ones |
+| 6 | Icon-only controls have a name | inspect each; draft and flag |
+| 7 | Every form field has a visible label, required is stated in text, consent is unticked | `get_form`, then the page |
+| 8 | A refused submission names the field and the fix | send one bad test submission |
+| 9 | Contrast meets 4.5:1 and 3:1 in every theme | measure real colour pairs |
+| 10 | Whole page works by keyboard: tab order, visible focus, menu, dialog, accordion, tabs | tab through it |
+| 12 | Motion stops or stills under reduced motion | emulate the preference |
+| 13 | Page has a title and a language | `list_seo_issues` for title; check `locale` |
+| 14 | Embeds have a title; moving content can pause | inspect each |
+
+## What to report
+
+Report accessibility as its own short block in the final report:
+
+- Checked: the pages and the rows above you ran.
+- Written: drafted alt (`alt-written`), labels and transcripts. Left empty on purpose: decorative
+  images, and each asset marked `decorative`.
+- Open: `alt-missing`, captions missing, contrast failures with the measured ratio, controls you
+  could not test (a third-party embed, a payment step).
+- Not claimed: conformance. No tool certifies it; the audit covers stored blocks only.