coding-styleguide-html-css

HTML & CSS

HTML

Semantic Elements

Use semantic elements like header, nav, main, article, section, aside, footer, figure, time when content has inherent meaning:

<article>
  <h1>Breaking News</h1>
  <time datetime="2025-01-15">January 15, 2025</time>
</article>

Form Labels

Every input requires an associated label. Prefer wrapping the input with label. Otherwise use for/id (when using React, call useId()):

<!-- Good -->
<label for="user-email">Email Address</label>
<input type="email" id="user-email" name="email" />

<!-- Better -->
<label>
  Email Address:
  <input type="email" name="email" />
</label>

Buttons vs. Links

Use buttons for actions, links for navigation:

<button type="button" onclick="saveData()">Save</button>
<a href="/next">Next</a>

Image Alt Text

Provide descriptive alt text for content images, empty alt for decorative images:

<img src="chart.png" alt="Sales increased 23% in Q4 2024" />
<img src="decoration.png" alt="" />

CSS

Selectors and naming

Use purpose-based named classes for styling with a maximum of 3 levels specificity.

.site-header {
}
.card {
}
.error-message {
}
.feature-highlight {
}

Check what styling solution (CSS Modules, BEM, Tailwind, ...) is used in the project and follow its conventions.

Units

Use typography units like rem, ch, ... for typography-related spacing:

font-size: 1.125rem;

Use px for everything else:

border: 1px solid #ccc;

Accessibility

Focus Indicators

Provide visible focus for all interactive elements:

button:focus {
  outline: 2px solid #007bff;
  outline-offset: 2px;
}

Color Information

Never use color alone to convey information. Use text labels or patterns to supplement color.

Motion Preferences

Respect reduced motion preferences:

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