Design a CSS architecture that scales for a large project using ITCSS methodology.
- User
Design a CSS architecture that scales for a large project using ITCSS methodology.
- 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/(orstyles/). 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 neededNotes 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
@usewith@forwardfor 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
-
Modularity & Namespacing:
- Feature folders:
components/blog/_post-card.scss. @usewith namespaces:@use 'components/blog/post-card' as blog;.
- Feature folders:
-
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.
-
Documentation:
- Styleguidist/Storybook for Components/Objects.
- Add comments:
/* 6. Components: Button variations */.
-
Linting & Tooling:
- Stylelint with ITCSS config: Enforce layer order, prefixes.
- Prettier for Sass.
- Git hooks for auto-linting.
-
Testing & Maintenance:
- Unit test variables/functions with Sass-test/Jest.
- Audit specificity with StyleStats.
- Design tokens: Export settings to JSON for Figma/Storybook sync.
-
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.
- Migrate to CSS Custom Properties for runtime theming (e.g.,
This architecture has powered sites like Financial Times. Start small, refactor incrementally—it's forgiving and scales infinitely! 🚀
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.