How-to guidesAdd an HTML check

Add an HTML check

  1. Open apps/frontend/src/Utils/HTML/htmlValidation.ts.
  2. Decide the scope:
    • Per element — add to validateElement, using add(level, rule, message). Use ctx.index for parents/ancestors (ancestors(eid, ctx)), descendants(node) for children.
    • Per page — add to validatePage with page(level, rule, message).
    • Data-driven — for “tag X needs attribute Y” or “tag X must be inside Y”, extend REQUIRED_ATTRS or ALLOWED_PARENTS instead of writing code. ID-reference attributes go in IDREF_ATTRS.
  3. If the rule needs a page-wide lookup, compute it once in buildPageContext and add the field to PageContext.
  4. Pick the level: error for invalid HTML or broken behavior, warning for accessibility/reference problems, info for suggestions (not counted in badges).
  5. Write the message for designers: what’s wrong and, briefly, what to do. No rule ids or code in the text.
  6. Add a test to Utils/HTML/__tests__/htmlValidation.test.ts covering a failing and a passing case, then run npx jest src/Utils/HTML.
  7. Add the rule to the designer HTML checks reference and the internal HTML validation reference.

Troubleshooting

  • The “well-formed page” test fails. The new rule fires on the minimal valid page in that test; tighten the condition.
  • Crash before the page loads. Guard against tagless nodes; the tree is {} until the page loads.