Skip to content
TheChatArchiveThe Chat Archive
Grok 4.1 Fast· xaiHugging Face Frontier Reasoning Traces

Design a CSS architecture that scales for a large project using ITCSS methodology.

  1. User

    Design a CSS architecture that scales for a large project using ITCSS methodology.

  2. Assistant
    /* Example scalable ITCSS folder structure for a large project */
    

    Overview of ITCSS Architecture

    ITCSS (Inverted Triangle CSS) is a scalable methodology by Harry Roberts that organizes CSS into 7 distinct layers, ordered from most specific (top) to least specific (bottom). This creates a predictable cascade where later layers naturally override earlier ones, minimizing specificity wars, improving maintainability, and enabling easy scaling for large projects (e.g., enterprise apps with 100+ components).

    Key benefits for large projects:

    • Predictability: Fixed import order ensures overrides work as expected.
    • Modularity: Components are isolated; changes don't ripple unexpectedly.
    • Performance: Layers can be tree-shaken or lazy-loaded in modern bundlers (e.g., Vite, Webpack).
    • Collaboration: Teams can own layers (e.g., design system team owns Objects/Components).
    • Tooling: Pairs perfectly with Sass/SCSS, PostCSS, PurgeCSS for unused CSS removal.

    Assumptions:

    • Using Sass/SCSS as preprocessor (native to ITCSS).
    • Naming conventions: BEM-inspired with ITCSS prefixes (e.g., .o-grid, .c-button, .u-hidden).
    • Build tools: Webpack/Vite + Autoprefixer + cssnano + PurgeCSS.
    • Large project scale: 100k+ LOC CSS, modularized with namespaces (e.g., admin/, checkout/).

    Recommended Folder Structure

    Organize in src/scss/ (or styles/). Use subfolders for layers, with further namespacing for scale.

    src/
    ├── scss/
    │   ├── abstracts/          # Non-outputting (Settings + Tools)
    │   │   ├── _settings.scss          # Global variables
    │   │   │   ├── _colors.scss
    │   │   │   ├── _typography.scss
    │   │   │   ├── _spacing.scss
    │   │   │   └── _breakpoints.scss
    │   │   ├── _tools.scss            # Mixins/functions
    │   │   │   ├── _functions.scss
    │   │   │   └── _mixins.scss
    │   │   └── abstracts.scss         # Imports all abstracts
    │   ├── base/                     # Generic + Elements
    │   │   ├── _reset.scss            # Normalize/reset
    │   │   ├── _typography.scss       # Base elements (h1, p, etc.)
    │   │   └── base.scss              # Imports base
    │   ├── components/                # Components (namespaced for scale)
    │   │   ├── _buttons.scss
    │   │   ├── _cards.scss
    │   │   ├── admin/                 # Feature-namespace
    │   │   │   └── _dashboard.scss
    │   │   └── checkout/              # Feature-namespace
    │   │       └── _progress-bar.scss
    │   │   └── components.scss        # Imports all (use @use/@forward in Sass modules)
    │   ├── layout/                    # Objects (layout patterns)
    │   │   ├── _grid.scss
    │   │   ├── _media.scss
    │   │   └── layout.scss
    │   ├── utilities/                 # Atomic utilities
    │   │   ├── _spacing.scss
    │   │   ├── _text.scss
    │   │   └── utilities.scss
    │   └── main.scss                  # Entry point: imports in ITCSS order
    └── js/  # JS imports CSS via imports/CSS-in-JS if needed
    

    Notes on structure:

    • Abstracts: No CSS output (underscores prevent compilation).
    • Namespacing: For 100+ components, use feature/component.scss (e.g., auth/_login-form.scss).
    • Sass Modules: Use @use with @forward for better scoping/namespace (Sass 1.23+).

    Layer-by-Layer Breakdown

    1. Settings (abstracts/_settings.scss)

    Global configuration variables. No nesting/output. Define once, use everywhere.

    // Colors (semantic, not atomic)
    $color-primary: #007bff;
    $color-error: #dc3545;
    
    // Typography scale
    $font-scale: (
      'h1': 2rem,
      'body': 1rem
    );
    
    // Spacing system (8pt grid)
    $space: (
      'xs': 0.25rem,
      's':  0.5rem,
      'm':  1rem
    );
    
    // Breakpoints (mobile-first)
    $breakpoints: (
      'tablet': 768px,
      'desktop': 1024px
    );
    

    2. Tools (abstracts/_tools.scss)

    Reusable Sass utilities (mixins, functions, maps). No output.

    // Function: Spacing from map
    @function space($key) {
      @return map.get($space, $key);
    }
    
    // Mixin: Media queries
    @mixin mq($breakpoint) {
      @if map-has-key($breakpoints, $breakpoint) {
        @media (min-width: map.get($breakpoints, $breakpoint)) {
          @content;
        }
      }
    }
    
    // Mixin: Visual spacing
    @mixin visually-hidden {
      position: absolute !important;
      width: 1px !important;
      height: 1px !important;
      padding: 0 !important;
      margin: -1px !important;
      overflow: hidden !important;
      clip: rect(0, 0, 0, 0) !important;
      white-space: nowrap !important;
      border: 0 !important;
    }
    

    3. Generic (base/_reset.scss)

    Low-specificity resets/normalization. Applies to everything.

    /* Normalize.css or custom reset */
    *,
    *::before,
    *::after {
      box-sizing: border-box;
    }
    
    html {
      font-size: 16px; // Modular scale base
      line-height: 1.5;
      -webkit-text-size-adjust: 100%;
    }
    
    body {
      margin: 0;
      font-family: system-ui, sans-serif;
    }
    

    4. Elements (base/_typography.scss)

    Unclassed HTML elements. Base styles only (no IDs/classes).

    h1, h2, h3 {
      margin-bottom: space('m');
      font-weight: 600;
    }
    
    h1 { font-size: map.get($font-scale, 'h1'); }
    
    p {
      margin-bottom: space('s');
    }
    

    5. Objects (layout/_grid.scss, layout/_media.scss)

    Reusable, composable layout patterns. No semantic meaning; pure structure (0.1 specificity).

    // .o-grid: Flexible grid object
    .o-grid {
      display: flex;
      flex-wrap: wrap;
    }
    
    .o-grid__item {
      flex: 1;
    }
    
    // .o-media: Figure/media layout
    .o-media {
      display: flex;
      align-items: flex-start;
    }
    
    .o-media__img {
      flex-shrink: 0;
      margin-right: space('m');
    }
    
    .o-media__body {
      flex: 1;
    }
    

    6. Components (components/_button.scss, etc.)

    Specific, styled UI components. Higher specificity (1.0+). Scoped to context.

    // .c-button: Full component
    .c-button {
      display: inline-flex;
      align-items: center;
      justify-content: center;
      padding: space('s') space('m');
      border: 1px solid $color-primary;
      background: $color-primary;
      color: white;
      text-decoration: none;
      border-radius: 0.25rem;
      transition: background 0.2s;
    
      &:hover { background: darken($color-primary, 10%); }
      &--primary { background: $color-primary; }
      &--secondary { background: transparent; color: $color-primary; }
    }
    
    // Namespaced: .c-checkout__progress-bar
    .c-checkout__progress-bar {
      // Specific to checkout feature
    }
    

    7. Utilities (utilities/_spacing.scss)

    High-specificity (often !important), atomic classes for overrides. Last resort.

    .u-margin-bottom--none { margin-bottom: 0 !important; }
    .u-text--center { text-align: center !important; }
    .u-visually-hidden { @include visually-hidden; }
    .u-full-bleed {
      width: 100vw;
      margin-left: calc(50% - 50vw);
    }
    

    Main Entry Point (scss/main.scss)

    Import strictly in ITCSS order. Use @import (legacy) or @use (modern).

    // 1. Abstracts (Settings/Tools)
    @import 'abstracts/abstracts';
    
    // 2. Base (Generic/Elements)
    @import 'base/base';
    
    // 3. Layout (Objects)
    @import 'layout/layout';
    
    // 4. Components
    @import 'components/components';
    
    // 5. Utilities (highest specificity)
    @import 'utilities/utilities';
    

    Scaling for Large Projects: Best Practices

    1. Modularity & Namespacing:

      • Feature folders: components/blog/_post-card.scss.
      • @use with namespaces: @use 'components/blog/post-card' as blog;.
    2. Performance:

      • PurgeCSS: Scan JS/HTML templates to remove unused CSS.
      • Critical CSS: Inline above-fold styles; load rest async.
      • CSS Modules/Shadow DOM: For component isolation in React/Vue.
    3. Documentation:

      • Styleguidist/Storybook for Components/Objects.
      • Add comments: /* 6. Components: Button variations */.
    4. Linting & Tooling:

      • Stylelint with ITCSS config: Enforce layer order, prefixes.
      • Prettier for Sass.
      • Git hooks for auto-linting.
    5. Testing & Maintenance:

      • Unit test variables/functions with Sass-test/Jest.
      • Audit specificity with StyleStats.
      • Design tokens: Export settings to JSON for Figma/Storybook sync.
    6. Evolution:

      • Migrate to CSS Custom Properties for runtime theming (e.g., --color-primary).
      • Tailwind/CSS-in-JS hybrid: Use ITCSS for global, Tailwind for components.

    This architecture has powered sites like Financial Times. Start small, refactor incrementally—it's forgiving and scales infinitely! 🚀

Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.