CSS architecture (BEM, etc.)

Style extension flow (skill-flow-block)

  [ Read SKILL: naming, forbidden selectors, entry files ]
        │
        ▼
  ┌─────────────┐     Choose BEM or equivalent (SUIT, rscss)
  │ Scope & names │── no bare tags, deep descendants; one root block per component
  └─────────────┘
        │
        ▼
  ┌─────────────┐     @layer order / ITCSS tiers / import graph
  │ Right layer   │── new rules do not jump above utilities unless SKILL allows
  └─────────────┘
        │
        ▼
  ┌─────────────┐     Modules: local by default; :global needs rationale
  │ Framework chk │── third party: API → variables → wrapper → hard override last
  └─────────────┘
        │
        ▼
  ┌─────────────┐     Stylelint + review checklist; exceptions in SKILL
  │ Validate/docs │── !important and deep selectors must be traceable
  └─────────────┘

BEM: block, element, modifier

/* BEM naming: block__element--modifier */
.card { padding: var(--space-4); }               /* Block */
.card__title { font-size: var(--font-size-lg); } /* Element: expresses role, not tag name */
.card__body  { color: var(--color-text-muted); }
.card--compact { padding: var(--space-2); }      /* Modifier: variant of block */
.card--featured .card__title { color: var(--color-brand); }

/* Multiple modifiers: stack classes, not chained */
<div class="card card--compact card--dark">   <!-- ✅ correct -->
<div class="card card--compact--dark">        <!-- ❌ anti-pattern: chained modifier -->

/* ❌ anti-pattern: structural coupling (high specificity + fragile) */
/* .card .title { } — not BEM, relies on DOM hierarchy */

/* Mixing with utility classes (team must agree) */
<div class="card mt-4 mb-2">  <!-- mt/mb from utilities; card is the BEM block -->

• Element names should express responsibility (__title) not DOM tag names (__h2).
• With multiple modifiers, stack classes side by side (.card .card--compact .card--dark) instead of chaining (--compact--dark).

@layer cascade layer usage examples

/* @layer: declare layer order — later layers have higher priority */
@layer reset, tokens, base, components, utilities;

/* reset layer: lowest priority */
@layer reset {
  *, *::before, *::after { box-sizing: border-box; }
  body { margin: 0; }
}

/* tokens layer: CSS variables — no specificity issues */
@layer tokens {
  :root { --color-brand: #3b82f6; --space-4: 1rem; }
}

/* components layer: BEM component styles */
@layer components {
  .card { padding: var(--space-4); border-radius: 0.5rem; }
  .card--elevated { box-shadow: var(--shadow-md); }
}

/* utilities layer: highest priority — single class overrides */
@layer utilities {
  .mt-4  { margin-top: var(--space-4) !important; }  /* utility may use !important */
  .sr-only { position: absolute; clip: rect(0,0,0,0); }
}

/* Unlayered styles (no @layer) have higher priority than all layers */
.third-party-override { color: var(--color-brand); }

• Before editing, check the SKILL layer list: which @layer a new file belongs in, or which partial it follows.
• Specificity strategy: prefer single-class selectors; to raise weight, adjust layer order instead of adding deeply nested descendants.

CSS Modules vs CSS-in-JS

/* CSS Modules: local by default; build generates unique class names */
/* Card.module.css */
.card { padding: var(--space-4); }       /* → .Card_card__xyz unique class */
.title { font-size: var(--font-size-lg); }

/* Global leakage: must document the reason */
:global(.third-party-class) { color: red; } /* reason: third-party hook class */

// Card.tsx (React)
import styles from './Card.module.css';
const Card = () => <div className={styles.card}><h2 className={styles.title}>...</h2></div>;

// CSS-in-JS (styled-components): inject theme tokens from a single source
import styled, { ThemeProvider } from 'styled-components';

const StyledCard = styled.div`
  padding: ${({ theme }) => theme.space[4]};
  border-radius: ${({ theme }) => theme.radii.md};
`;

// CSS Modules: zero runtime overhead, build-time extraction — preferred for SSR
// CSS-in-JS: dynamic theme/props-driven styles, runtime cost — suited for design systems

• CSS-in-JS: inject theme tokens from a single source to avoid drift between runtime and static CSS variables.
• Overriding libraries: check classNames / slots / CSS variables first; a BEM wrapper block beats editing internal library classes across upgrades.

Stylelint, tokens, and critical CSS

• Stylelint: max-nesting-depth, selector-max-id, custom property naming, and BEM regex should match the SKILL.
• Critical CSS: if the build inlines critical path rules, do not put footer-only rules in the critical entry.
• Design tokens: spacing and color via var(--space-*) etc.; no magic numbers unless the SKILL allows an exception directory.

BEM class builder lab

Build a single BEM class string (one class, no spaces) for pasting into SKILL examples or templates; block is required, element and modifier optional.