HTML and CSS guardrails, patterns, and best practices for AI-assisted development.
Use when working with HTML/CSS files (.html, .css, .scss, .less), or when the user mentions HTML/CSS.
Provides semantic HTML guidelines, accessibility standards, modern CSS patterns,
and responsive design conventions specific to this project's coding standards.
HTML and CSS guardrails, patterns, and best practices for AI-assisted development.
Use when working with HTML/CSS files (.html, .css, .scss, .less), or when the user mentions HTML/CSS.
Provides semantic HTML guidelines, accessibility standards, modern CSS patterns,
and responsive design conventions specific to this project's coding standards.
Applies to: HTML5, CSS3, SCSS/LESS, Responsive Design, WCAG 2.1 AA
Core Principles
Semantic First: Use HTML elements for their meaning, not their appearance; style with CSS
Accessible by Default: Every page must be navigable by keyboard, screen reader, and assistive technology
Progressive Enhancement: Build a solid HTML foundation, then layer on CSS and JavaScript
Mobile First: Design for the smallest viewport, then enhance with min-width media queries
Performance Budget: Minimize render-blocking resources; prefer system fonts, modern image formats, and critical CSS inlining
Guardrails
Semantic HTML
Use <main> once per page; <header>, , , for landmarks
<footer>
<nav>
<aside>
Use <article> for self-contained content; <section> for thematic groups with a heading
Use <figure>/<figcaption> for captioned media; <time datetime="..."> for dates
Headings (<h1>-<h6>) must follow a logical outline; never skip levels for styling
Use <button> for actions and <a> for navigation; never <div onclick>
Lists (<ul>, <ol>, <dl>) for groups of related items; not <div> sequences
<article><header><h2>Deploying with Zero Downtime</h2><timedatetime="2025-03-15">March 15, 2025</time></header><sectionaria-labelledby="prereqs"><h3id="prereqs">Prerequisites</h3><ul><li>Container runtime (Docker or Podman)</li><li>Load balancer with health checks</li></ul></section></article>
Accessibility (WCAG 2.1 AA)
Every <img> must have alt; decorative images use alt=""
All form inputs must have associated <label> elements (use for/id)
Color contrast: 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+)
Focus indicators must be visible; never outline: none without a replacement
Skip-to-content link as the first focusable element on every page
All interactive elements must be keyboard-operable
Use aria-live="polite" for dynamic updates; role="alert" for immediate announcements
Use aria-expanded, aria-controls, aria-haspopup for disclosure widgets
Do not rely on color alone to convey information (add icons, text, or patterns)
<ahref="#main"class="skip-link">Skip to main content</a><formaria-labelledby="signup-heading"><h2id="signup-heading">Create Account</h2><labelfor="email">Email</label><inputid="email"type="email"requiredautocomplete="email"aria-describedby="email-hint" /><pid="email-hint"class="hint">We will never share your email.</p><buttontype="submit">Create Account</button></form>
CSS Architecture
One component per file; file name matches component (card.css, nav.css)
Use @layer for specificity control: reset, base, layout, components, utilities
Prefer BEM (.block__element--modifier) or utility-first -- pick one, stay consistent
Never use !important outside utility overrides; fix specificity instead
Max 3 levels of nesting (native or preprocessor)
Custom properties for all theme values (colors, spacing, typography, radii)
No inline styles unless dynamically computed by JavaScript
