# HTML/CSS AI Agent Rules (Quick Reference)

## 📋 Essential Rules Summary

This file provides a quick reference for Cursor IDE. For complete details, see `AGENTS_RULES.md`.

### 🎯 Core Principles

1. **Semantic HTML First**: Use appropriate HTML5 semantic elements
2. **Accessibility**: WCAG 2.1 AA compliance minimum
3. **Responsive Design**: Mobile-first approach
4. **Modern CSS**: Use Grid, Flexbox, Custom Properties
5. **Performance**: Optimize assets, minimize reflows
6. **Cross-browser**: Test on major browsers

### 🏗️ HTML Best Practices

- Use semantic elements (`<header>`, `<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`, `<footer>`)
- Always include `lang` attribute on `<html>`
- Proper `<head>` with charset, viewport, title, meta description
- Use `alt` text for images
- Form labels with `for` attribute
- ARIA attributes when needed
- Valid HTML5 (no deprecated tags)

### 🎨 CSS Best Practices

- **Layout**: CSS Grid for 2D layouts, Flexbox for 1D layouts
- **Variables**: Use CSS Custom Properties for theming
- **Naming**: BEM methodology or semantic class names
- **Responsive**: Mobile-first media queries
- **Units**: Use `rem` for typography, `em` for spacing, `%` or `vw/vh` for layouts
- **Animations**: Use `transform` and `opacity` for performance
- **Specificity**: Keep it low, avoid `!important`

### 📱 Responsive Design

```css
/* Mobile first */
.container {
  width: 100%;
  padding: 1rem;
}

/* Tablet */
@media (min-width: 768px) {
  .container {
    max-width: 720px;
    margin: 0 auto;
  }
}

/* Desktop */
@media (min-width: 1024px) {
  .container {
    max-width: 960px;
  }
}
```

### ♿ Accessibility

- Semantic HTML structure
- Proper heading hierarchy (h1 → h2 → h3)
- ARIA labels for interactive elements
- Keyboard navigation support
- Color contrast ratios (4.5:1 for text)
- Focus indicators
- Skip links for navigation

### 🧪 Testing & Validation

- **HTML**: W3C Validator, HTMLHint
- **CSS**: W3C CSS Validator, Stylelint
- **Accessibility**: axe DevTools, WAVE
- **Cross-browser**: BrowserStack, real devices
- **Performance**: Lighthouse, PageSpeed Insights

### 🔧 Development Tools

- **Build**: Vite, Webpack, Parcel
- **Preprocessors**: Sass, PostCSS
- **Linting**: Stylelint, HTMLHint
- **Formatting**: Prettier
- **Testing**: Playwright, Cypress

### 📦 File Organization

```
project/
├── index.html
├── css/
│   ├── reset.css
│   ├── variables.css
│   ├── layout.css
│   ├── components.css
│   └── utilities.css
├── assets/
│   ├── images/
│   └── fonts/
└── js/
    └── main.js
```

### 🚫 Anti-patterns to Avoid

- ❌ Inline styles (use classes)
- ❌ Non-semantic divs everywhere
- ❌ Fixed pixel widths
- ❌ `!important` overuse
- ❌ Deep nesting (> 3 levels)
- ❌ Browser-specific prefixes without autoprefixer
- ❌ Missing alt text
- ❌ Non-responsive designs

### 📚 Full Documentation

For complete rules including:
- TDD workflow and testing strategies
- DDD principles for CSS architecture
- Git workflow and commit standards
- Code quality principles
- Detailed examples and patterns

**→ See `AGENTS_RULES.md`**

### 🤝 Contributing

See `CONTRIBUTING.md` for:
- How to propose changes
- Code review process
- Style guidelines
- Pull request template
