Agent skill

html-css-guide

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.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/html-css-guide

Metadata

Additional technical details for this skill

author
samuel
version
1.0
category
language
language
html-css
extensions
.html,.htm,.css,.scss,.less,.sass

SKILL.md

HTML/CSS Guide

Applies to: HTML5, CSS3, SCSS/LESS, Responsive Design, WCAG 2.1 AA

Core Principles

  1. Semantic First: Use HTML elements for their meaning, not their appearance; style with CSS
  2. Accessible by Default: Every page must be navigable by keyboard, screen reader, and assistive technology
  3. Progressive Enhancement: Build a solid HTML foundation, then layer on CSS and JavaScript
  4. Mobile First: Design for the smallest viewport, then enhance with min-width media queries
  5. 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>, <footer>, <nav>, <aside> for landmarks
  • 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
html
<article>
  <header>
    <h2>Deploying with Zero Downtime</h2>
    <time datetime="2025-03-15">March 15, 2025</time>
  </header>
  <section aria-labelledby="prereqs">
    <h3 id="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)
html
<a href="#main" class="skip-link">Skip to main content</a>

<form aria-labelledby="signup-heading">
  <h2 id="signup-heading">Create Account</h2>
  <label for="email">Email</label>
  <input id="email" type="email" required autocomplete="email"
         aria-describedby="email-hint" />
  <p id="email-hint" class="hint">We will never share your email.</p>
  <button type="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
css
@layer reset, base, layout, components, utilities;

@layer base {
  :root {
    --color-primary: oklch(55% 0.22 265);
    --color-surface: oklch(98% 0.005 265);
    --color-text: oklch(20% 0.02 265);
    --space-sm: 0.5rem;
    --space-md: 1rem;
    --space-lg: 2rem;
    --radius-md: 0.5rem;
    --font-body: system-ui, -apple-system, sans-serif;
  }
}

@layer components {
  .card { background: var(--color-surface); border-radius: var(--radius-md); padding: var(--space-md); }
  .card__title { font-size: 1.25rem; color: var(--color-text); }
  .card--featured { border: 2px solid var(--color-primary); }
}

Performance

  • Inline critical CSS in <head> for first contentful paint
  • Use font-display: swap for web fonts; prefer system font stacks
  • Modern image formats: AVIF > WebP > JPEG; use <picture> with fallbacks
  • Animate only transform and opacity to avoid layout reflows
  • Use content-visibility: auto for off-screen sections
  • Set width/height or aspect-ratio on media to prevent layout shift
html
<picture>
  <source srcset="hero.avif" type="image/avif" />
  <source srcset="hero.webp" type="image/webp" />
  <img src="hero.jpg" alt="Dashboard overview" width="1200" height="630"
       loading="lazy" decoding="async" />
</picture>

Responsive Design

  • Mobile-first: base styles for small screens, add complexity with min-width queries
  • Use rem/em for sizing; reserve px for borders and fine details only
  • Fluid typography with clamp(): font-size: clamp(1rem, 0.5rem + 1.5vw, 1.5rem)
  • Container queries (@container) for component-level responsiveness
  • Test at 320px, 768px, 1024px, 1440px, and with 200% browser zoom
  • Touch targets: at least 44x44px on mobile

Key Patterns

Grid (2D) vs Flexbox (1D)

Use CSS Grid for page layouts with rows and columns; use Flexbox for single-axis alignment.

css
/* Grid: 2D page layout */
.page {
  display: grid;
  grid-template: "header header" auto "sidebar main" 1fr "footer footer" auto / 16rem 1fr;
  min-height: 100dvh;
}

/* Flexbox: 1D navigation */
.nav { display: flex; align-items: center; gap: var(--space-md); }
.nav__logo { margin-right: auto; }

Container Queries

css
.card-container { container-type: inline-size; container-name: card; }

@container card (min-width: 30rem) {
  .card { flex-direction: row; align-items: center; }
}

The :has() Selector

css
.field:has(input:focus) { outline: 2px solid var(--color-primary); }
.card:has(img) { padding: 0; }
form:has(:invalid) button[type="submit"] { opacity: 0.5; pointer-events: none; }

Cascade Layers (@layer)

css
@layer reset, base, layout, components, utilities;

@layer reset { *, *::before, *::after { box-sizing: border-box; margin: 0; } }
@layer utilities {
  .visually-hidden {
    clip: rect(0 0 0 0); clip-path: inset(50%); height: 1px;
    overflow: hidden; position: absolute; white-space: nowrap; width: 1px;
  }
}

Dark Mode and User Preferences

css
:root { color-scheme: light dark; --color-bg: oklch(98% 0.005 265); }
@media (prefers-color-scheme: dark) { :root { --color-bg: oklch(15% 0.02 265); } }
[data-theme="dark"] { --color-bg: oklch(15% 0.02 265); }

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important; transition-duration: 0.01ms !important;
  }
}

Accessibility Checklist (WCAG 2.1 AA)

Perceivable

  • All images have descriptive alt (or alt="" for decorative)
  • Color contrast: 4.5:1 body text, 3:1 large text
  • Information not conveyed by color alone
  • Text resizable to 200% without content loss
  • Captions for video; transcripts for audio

Operable

  • All functionality keyboard-accessible (Tab, Enter, Escape, arrows)
  • Logical focus order; visible focus indicators
  • No keyboard traps; modals return focus on close
  • Skip navigation link as first focusable element
  • Touch targets at least 44x44px

Understandable

  • <html lang="..."> set correctly
  • Form inputs have visible labels and descriptive error messages
  • Consistent navigation across pages

Robust

  • Valid HTML (W3C validator)
  • ARIA roles, states, and properties match widget behavior
  • Tested with screen reader (VoiceOver, NVDA, or JAWS)
  • Tested with 200% browser zoom

Tooling

bash
npx stylelint "**/*.css"                      # CSS lint
npx stylelint "**/*.css" --fix                # CSS lint auto-fix
npx htmlhint "**/*.html"                      # HTML validation
npx prettier --check "**/*.{html,css,scss}"   # Format check
npx prettier --write "**/*.{html,css,scss}"   # Format fix
npx lighthouse http://localhost:3000 --output html --view  # Audit
npx @axe-core/cli http://localhost:3000       # Accessibility check
npx pa11y http://localhost:3000               # Accessibility test

Stylelint Configuration

json
{
  "extends": ["stylelint-config-standard"],
  "rules": {
    "declaration-no-important": true,
    "selector-max-specificity": "0,3,0",
    "max-nesting-depth": 3,
    "color-function-notation": "modern",
    "selector-class-pattern": "^[a-z][a-z0-9]*(__[a-z0-9-]+)?(--[a-z0-9-]+)?$"
  }
}

References

For detailed layout examples, accessibility patterns, and modern CSS features, see:

  • references/patterns.md -- Grid/Flexbox layouts, modal dialogs, fluid typography, scroll animations

External References

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results