css-standards

CSS/SCSS Coding Standards

General Preferences

• CSS Modules or Tailwind CSS for component styling
• SCSS for complex stylesheets when needed
• CSS Custom Properties (variables) for theming
• Mobile-first responsive design
• BEM naming for traditional CSS (when not using modules)

Naming Conventions

BEM (Block Element Modifier)

/* Block: standalone component */
.card {}

/* Element: part of a block (double underscore) */
.card__header {}
.card__body {}
.card__footer {}

/* Modifier: variation of block/element (double hyphen) */
.card--featured {}
.card--compact {}
.card__header--large {}

/* Example usage */
.user-profile {}
.user-profile__avatar {}
.user-profile__name {}
.user-profile--verified {}

CSS Modules

/* UserCard.module.css */
.container {}
.header {}
.avatar {}
.name {}

/* Composes for shared styles */
.primaryButton {
  composes: button from './shared.module.css';
  background: var(--color-primary);
}

Utility Classes (Tailwind-style)

/* When creating custom utilities */
.text-center { text-align: center; }
.mt-4 { margin-top: 1rem; }
.flex { display: flex; }
.hidden { display: none; }

CSS Custom Properties

/* Define in :root for global variables */
:root {
  /* Colors */
  --color-primary: #0066cc;
  --color-primary-hover: #0052a3;
  --color-secondary: #6c757d;
  --color-success: #28a745;
  --color-error: #dc3545;
  --color-warning: #ffc107;

  /* Text colors */
  --color-text: #1a1a1a;
  --color-text-muted: #6c757d;
  --color-text-inverse: #ffffff;

  /* Backgrounds */
  --color-bg: #ffffff;
  --color-bg-secondary: #f8f9fa;
  --color-bg-tertiary: #e9ecef;

  /* Spacing scale */
  --space-xs: 0.25rem;   /* 4px */
  --space-sm: 0.5rem;    /* 8px */
  --space-md: 1rem;      /* 16px */
  --space-lg: 1.5rem;    /* 24px */
  --space-xl: 2rem;      /* 32px */
  --space-2xl: 3rem;     /* 48px */

  /* Typography */
  --font-family: system-ui, -apple-system, sans-serif;
  --font-family-mono: 'SF Mono', Consolas, monospace;

  --font-size-xs: 0.75rem;   /* 12px */
  --font-size-sm: 0.875rem;  /* 14px */
  --font-size-md: 1rem;      /* 16px */
  --font-size-lg: 1.125rem;  /* 18px */
  --font-size-xl: 1.25rem;   /* 20px */
  --font-size-2xl: 1.5rem;   /* 24px */

  --line-height-tight: 1.25;
  --line-height-normal: 1.5;
  --line-height-relaxed: 1.75;

  /* Borders */
  --border-radius-sm: 0.25rem;
  --border-radius-md: 0.5rem;
  --border-radius-lg: 1rem;
  --border-radius-full: 9999px;

  /* Shadows */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
  --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);

  /* Transitions */
  --transition-fast: 150ms ease;
  --transition-normal: 250ms ease;
  --transition-slow: 350ms ease;

  /* Z-index scale */
  --z-dropdown: 100;
  --z-sticky: 200;
  --z-modal: 300;
  --z-tooltip: 400;
}

/* Dark mode override */
@media (prefers-color-scheme: dark) {
  :root {
    --color-text: #f0f0f0;
    --color-bg: #1a1a1a;
    --color-bg-secondary: #2d2d2d;
  }
}

/* Or with class toggle */
.dark {
  --color-text: #f0f0f0;
  --color-bg: #1a1a1a;
}