Cursor Rules for HTML: Semantics, Forms, and Accessibility

Cursor rules for HTML tell the assistant to use semantic elements correctly, write accessible form markup, and run through a review checklist before finishing a template. Without them, an assistant defaults to <div> for everything, omits <label> elements on form inputs, and skips the checks that catch missing alt text and broken heading hierarchy.

fenbs stores the content and design requirements that shape the HTML: which headings are approved for a section, which form fields were confirmed with the client, and which accessibility standard applies to the product. The rule sets the technical floor; fenbs keeps the agreed decisions.

What HTML rules should cover

HTML has a small set of recurring mistakes that rules can prevent. Using <div> and <span> when a semantic element like <nav>, <main>, <article>, or <button> is correct. Omitting <label> on form inputs. Missing alt attributes on images. Breaking the heading hierarchy. Each is easy to catch with a rule; each is harder to find after the fact.

• Semantic structure: which elements to use for landmarks, headings, and interactive controls.
• Forms: every input must have an associated label, and form validation messages must be programmatically linked.
• Images: every <img> needs an alt attribute; decorative images get an empty one.
• Heading hierarchy: start with one <h1>, do not skip levels, and do not use headings for visual size alone.
• Interactive elements: use <button> for actions and <a> for navigation; do not use <div> with an onclick handler.

Semantic structure

Semantic HTML communicates meaning to browsers, assistive technology, and search engines. A <nav> landmark tells screen reader users there is a navigation region; a <div> does not. A <button> is focusable and activatable by keyboard by default; a <div> with an event listener is neither without additional ARIA.

The HTML Living Standard at html.spec.whatwg.org↗ (opens in a new tab) defines the semantic content model for each element. For assistants, a rule that names the correct element for common patterns, such as "use <article> for self-contained content that would make sense on its own", is more useful than a reference to the full specification.

---
description: HTML structure and accessibility rules
globs: "**/*.html,**/*.htm,**/*.njk,**/*.jinja,templates/**"
alwaysApply: false
---

## Semantic structure
- Use landmark elements: `<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>`.
- Use `<article>` for self-contained content, `<section>` only with a heading.
- Never use a `<div>` or `<span>` when a semantic element fits.

## Headings
- One `<h1>` per page, describing the page topic.
- Do not skip heading levels; nest `<h2>` under `<h1>`, `<h3>` under `<h2>`.
- Do not use a heading element for visual size; use CSS.

## Forms
- Every input needs an associated `<label>` with a matching `for` attribute.
- Error messages must be linked to their input with `aria-describedby`.
- Use `type="submit"` on the submit button, not `type="button"`.

## Images
- Every `<img>` needs an `alt` attribute.
- Decorative images: `alt=""`. Informative images: a description of the content.

## Interactive elements
- Use `<button>` for actions that stay on the page; use `<a>` for navigation.
- Never add an onclick handler to a non-interactive element without role and keyboard support.

## Completion check
- Validate heading hierarchy before finishing.
- Check every form input for a visible label.

Accessible form markup

Forms are the most common source of accessibility failures. An input without a label is unusable for screen reader users. An error message that appears visually but is not linked to the input does not reach assistive technology. A submit button with type="button" does not submit on Enter.

The rule covers these patterns with specific markup requirements. When the assistant writes a form, it includes a label for every input, links error messages with aria-describedby, and uses the correct button type. Those requirements are easy to state and check, which makes them well-suited to a rule file.

ARIA and custom interactive components

Standard HTML elements carry built-in ARIA semantics. A <button> is already a button to assistive technology; a <nav> is already a navigation landmark. When your project builds a custom dropdown, modal, or date picker using <div> and <span> elements, those semantics disappear unless you add them explicitly.

The rule can name the custom components your project uses and the ARIA pattern each follows. Telling the assistant that your dropdown uses role="listbox" with aria-activedescendant is more precise than a general reminder to use ARIA. When the pattern is named, the assistant applies it consistently. When it is not, each new implementation may differ. The ARIA Authoring Practices Guide↗ (opens in a new tab) at W3C documents the keyboard and ARIA patterns for every common component type and is a useful reference to point to in the rule for any component your project has not yet covered.

Completion checks as a review tool

The completion check in the rule is also a quality gate. When the assistant finishes a template, working through the list catches the mistakes that are easy to introduce in a first pass: a label that was added to one input but not a second one added later, a heading level that skipped from <h2> to <h4>, an image that got descriptive text replaced with an empty string. Each check is fast to run and specific enough that the assistant can confirm it without a separate review pass.

For projects with an accessibility standard requirement, the completion check is also where compliance obligations land. Stating "verify contrast at WCAG AA before finishing" turns a vague commitment into a specific step the assistant performs on every task. That is easier to maintain than a periodic audit that finds a backlog of accumulated issues.

How to set up HTML rules with fenbs

1. Create a free account and add your project.
2. Record the content decisions in fenbs: approved heading structure, confirmed form fields, the accessibility standard that applies.
3. Place the .cursor/rules/html.mdc file at the project root and adjust the globs to match your template file extensions.
4. Connect Cursor via Integrations and ask it to read the project context before working on any template.
5. After each template task, record the heading structure and any form field decisions that came up.

For rules that apply to the styles alongside the HTML, see cursor rules tailwind. For more rule patterns, see cursor rules examples. For organizing multiple rule files, see cursor rules hierarchy and cursor rules library. For the WCAG accessibility standard, see WCAG 2.2↗ (opens in a new tab).