---name: cssdescription: Best practices for CSS development including modern layout techniques, naming conventions, theming, and maintainable stylesheet architecture---

CSS Development Guidelines

Core Principles

• Write semantic HTML to improve accessibility and SEO
• Use CSS for styling, avoiding inline styles
• Ensure responsive design using media queries and flexible layouts
• Prioritize external stylesheets over inline or embedded styles

Layout Techniques

Flexbox

• Use Flexbox for one-dimensional layouts (rows or columns)
• Leverage justify-content and align-items for alignment
• Use flex-wrap for responsive wrapping behavior
• Prefer gap property over margins for consistent spacing

Grid

• Use CSS Grid for two-dimensional layouts
• Define grid templates with grid-template-columns and grid-template-rows
• Use grid-area for named template areas
• Leverage auto-fit and auto-fill for responsive grids

Units and Typography

• Use rem units for typography to respect user preferences
• Use em units for component-relative sizing
• Avoid px for font sizes; reserve for borders and fixed elements
• Implement fluid typography with clamp() when appropriate
• Use viewport units (vw, vh) thoughtfully for full-screen layouts

CSS Variables (Custom Properties)

• Define design tokens as CSS variables on :root
• Use variables for colors, spacing, typography, and shadows
• Implement theming by overriding variables in different contexts
• Name variables semantically (e.g., --color-primary, --spacing-md)

Naming Conventions

BEM Methodology

• Block: Standalone component (e.g., .card)
• Element: Part of a block (e.g., .card__title)
• Modifier: Variation of block or element (e.g., .card--featured)

Best Practices

• Use lowercase with hyphens for class names
• Avoid IDs for styling; reserve for JavaScript hooks
• Keep specificity low by using single class selectors
• Scope styles to components to prevent conflicts

Specificity Management

• Maintain specificity at 0-1-0 (single class) when possible
• Avoid !important declarations
• Use cascading intentionally, not accidentally
• Consider CSS Layers (@layer) for specificity control

Responsive Design

• Implement mobile-first media queries
• Use relative units for flexible layouts
• Test across multiple viewport sizes
• Consider container queries for component-level responsiveness

Performance

• Minimize selector complexity
• Avoid deeply nested selectors
• Use efficient selectors (class over element)
• Leverage CSS containment for isolated components
• Consider critical CSS for above-the-fold content

Modern CSS Features

• Use aspect-ratio for maintaining proportions
• Leverage gap in Flexbox and Grid
• Use logical properties (margin-inline, padding-block)
• Implement smooth transitions with transition property
• Use @supports for feature detection

Organization

• Structure stylesheets logically (base, layout, components, utilities)
• Keep files modular and focused
• Document complex styles with comments
• Use a consistent property order within declarations

Browser Compatibility

• Use vendor prefixes when necessary (consider Autoprefixer)
• Test across target browsers
• Provide fallbacks for newer features
• Use progressive enhancement approach

Accessibility

• Ensure sufficient color contrast (WCAG AA minimum)
• Provide visible focus styles for keyboard navigation
• Avoid hiding content in ways that affect screen readers
• Use prefers-reduced-motion media query for animations