HTML/CSS

General Principles

Write clean, semantic, and maintainable HTML and CSS that works across modern browsers and devices.

HTML Guidelines

Document Structure

Always use HTML5 doctype and proper document structure:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Page Title</title>
</head>
<body>
  <!-- Content -->
</body>
</html>

Semantic HTML

Use semantic elements to convey meaning and improve accessibility:

<!-- Good -->
<header>
  <nav>
    <ul>
      <li><a href="/">Home</a></li>
    </ul>
  </nav>
</header>

<main>
  <article>
    <h1>Article Title</h1>
    <p>Content...</p>
  </article>
</main>

<footer>
  <p>&copy; 2025 Company Name</p>
</footer>

<!-- Avoid -->
<div class="header">
  <div class="nav">
    <div class="item">Home</div>
  </div>
</div>

Accessibility

Always include alt attributes on images
Use proper heading hierarchy (h1 → h2 → h3)
Ensure sufficient color contrast
Make interactive elements keyboard accessible
Use ARIA attributes when semantic HTML isn’t sufficient

<!-- Good -->
<img src="profile.jpg" alt="User profile photo">
<button type="button" aria-label="Close dialog">×</button>

<!-- Bad -->
<img src="profile.jpg">
<div onclick="closeDialog()">×</div>

Formatting

Use 2 spaces for indentation
Use lowercase for element names and attributes
Always quote attribute values
Keep line length under 100 characters
Close all tags properly

<!-- Good -->
<div class="container" data-user-id="123">
  <p>Content here</p>
</div>

<!-- Bad -->
<DIV class=container data-user-id=123>
  <p>Content here
</DIV>

CSS Guidelines

Modern Syntax

Use modern CSS features and avoid outdated practices:

/* Good - Use custom properties */
:root {
  --color-primary: hsl(220 90% 56%);
  --spacing-base: 1rem;
}

.button {
  background: var(--color-primary);
  padding: var(--spacing-base);
}

/* Good - Use modern color functions */
.card {
  background: hsl(0 0% 100%);
  border: 1px solid hsl(0 0% 90%);
}

/* Avoid - Old hex notation without variables */
.button {
  background: #3b82f6;
  padding: 16px;
}

Selector Specificity

Keep specificity low and predictable:

/* Good - Low specificity */
.button { }
.button-primary { }

/* Avoid - High specificity */
div.container > ul li.active a.link { }
#header .nav .item { }

Property Organization

Group related properties logically:

.element {
  /* Positioning */
  position: relative;
  top: 0;
  left: 0;

  /* Display & Box Model */
  display: flex;
  width: 100%;
  padding: 1rem;
  margin: 0;

  /* Visual */
  background: white;
  border: 1px solid gray;
  color: black;

  /* Typography */
  font-size: 1rem;
  line-height: 1.5;

  /* Misc */
  cursor: pointer;
  transition: all 0.2s;
}

Modern Layout

Use Flexbox and Grid for layouts:

/* Flexbox for one-dimensional layouts */
.nav {
  display: flex;
  gap: 1rem;
  align-items: center;
}

/* Grid for two-dimensional layouts */
.grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 2rem;
}

Responsive Design

Use mobile-first approach with media queries:

/* Mobile first - base styles */
.container {
  padding: 1rem;
}

/* Tablet and up */
@media (min-width: 768px) {
  .container {
    padding: 2rem;
  }
}

/* Desktop and up */
@media (min-width: 1024px) {
  .container {
    max-width: 1280px;
    margin: 0 auto;
  }
}

Performance

Optimize for performance:

Minimize reflows and repaints
Use transform and opacity for animations
Avoid expensive properties like box-shadow in animations
Load critical CSS inline, defer non-critical CSS

/* Good - GPU accelerated */
.element {
  transform: translateX(100px);
  opacity: 0.5;
}

/* Avoid - Expensive during animation */
.element {
  left: 100px; /* Triggers reflow */
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2); /* Expensive */
}

Naming Conventions

BEM (Block Element Modifier)

Use BEM for component-based naming:

/* Block */
.card { }

/* Element */
.card__title { }
.card__content { }

/* Modifier */
.card--featured { }
.card__title--large { }

Utility Classes

Use descriptive utility class names:

.text-center { text-align: center; }
.mt-4 { margin-top: 1rem; }
.flex { display: flex; }
.hidden { display: none; }

Tooling

Recommended Tools

Prettier - Automatic code formatting
Stylelint - CSS linting
PostCSS - CSS transformations and autoprefixer
CSS Modules - Scoped CSS for components
Tailwind CSS - Utility-first CSS framework

Configuration Example

.prettierrc:

{
  "printWidth": 100,
  "tabWidth": 2,
  "semi": true,
  "singleQuote": true,
  "htmlWhitespaceSensitivity": "css"
}

Best Practices

Do’s

✅ Use semantic HTML elements ✅ Write accessible markup ✅ Use CSS custom properties for theming ✅ Keep specificity low ✅ Use modern layout techniques (Flexbox, Grid) ✅ Optimize for performance ✅ Test across devices and browsers ✅ Use consistent naming conventions

Don’ts

❌ Use inline styles ❌ Use !important unless absolutely necessary ❌ Use deprecated HTML elements (<center>, <font>) ❌ Nest selectors too deeply ❌ Forget about accessibility ❌ Ignore browser compatibility ❌ Mix different naming conventions