css-architecture

Implement scalable CSS architecture patterns - BEM, SMACSS, ITCSS, design tokens

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill empowers developers to build scalable, maintainable, and professional-grade CSS codebases by implementing industry-standard architecture patterns. It provides expert guidance on methodologies like BEM, SMACSS, and ITCSS, alongside design token integration, ensuring that front-end styles remain organized and conflict-free as projects grow from small sites to enterprise-level applications.

Use Cases

  • Refactoring monolithic legacy CSS files into modular, BEM-compliant components to eliminate style leakage and improve reusability.
  • Setting up an ITCSS (Inverted Triangle CSS) hierarchy for large-scale projects to manage CSS specificity and prevent 'important' tag abuse.
  • Implementing a multi-tier design token system (primitive, semantic, and component tokens) using CSS custom properties for consistent branding.
  • Generating optimized folder structures and naming conventions tailored to specific project scales, such as SMACSS for multi-page websites.
  • Migrating existing styles to a utility-first or atomic CSS approach while maintaining a structured architectural foundation.
namecss-architecture
descriptionImplement scalable CSS architecture patterns - BEM, SMACSS, ITCSS, design tokens
sasmp_version"1.3.0"
version"2.0.0"
updated"2025-12-30"
bonded_agent04-css-architecture
bond_typePRIMARY_BOND

CSS Architecture Skill

Implement scalable CSS architecture patterns for maintainable, organized codebases.

Overview

This skill provides atomic, focused guidance on CSS architecture methodologies with practical implementation patterns and migration strategies.

Skill Metadata

Property Value
Category Organization
Complexity Intermediate to Expert
Dependencies css-fundamentals
Bonded Agent 04-css-architecture

Usage

Skill("css-architecture")

Parameter Schema

parameters:
  methodology:
    type: string
    required: true
    enum: [bem, smacss, oocss, itcss, atomic, css-modules]
    description: CSS architecture methodology

  project_size:
    type: string
    required: false
    default: medium
    enum: [small, medium, large, enterprise]
    description: Project scale for appropriate recommendations

  include_tokens:
    type: boolean
    required: false
    default: true
    description: Include design token patterns

validation:
  - rule: methodology_required
    message: "methodology parameter is required"
  - rule: valid_methodology
    message: "methodology must be one of: bem, smacss, oocss, itcss, atomic, css-modules"

Topics Covered

BEM (Block Element Modifier)

  • Block: Standalone component
  • Element: Part of block (__)
  • Modifier: Variant/state (--)

SMACSS

  • Base, Layout, Module, State, Theme

ITCSS (Inverted Triangle CSS)

  • Settings, Tools, Generic, Elements, Objects, Components, Utilities

Design Tokens

  • Primitive, semantic, component tokens
  • CSS custom properties organization

Retry Logic

retry_config:
  max_attempts: 3
  backoff_type: exponential
  initial_delay_ms: 1000
  max_delay_ms: 10000

Logging & Observability

logging:
  entry_point: skill_invoked
  exit_point: skill_completed
  metrics:
    - invocation_count
    - methodology_distribution
    - project_size_distribution

Quick Reference

BEM Naming

/* Block */
.card { }

/* Element */
.card__header { }
.card__body { }
.card__footer { }

/* Modifier */
.card--featured { }
.card--compact { }
.card__header--large { }

ITCSS Layers

/styles
├── 1-settings/     → $variables, tokens
├── 2-tools/        → @mixins, functions
├── 3-generic/      → reset, normalize
├── 4-elements/     → h1, p, a (bare HTML)
├── 5-objects/      → .o-grid, .o-container
├── 6-components/   → .c-card, .c-button
└── 7-utilities/    → .u-hidden, .u-text-center

Design Token Hierarchy

/* 1. Primitive Tokens */
:root {
  --color-blue-500: #3b82f6;
  --color-gray-900: #111827;
  --space-4: 1rem;
  --font-size-lg: 1.125rem;
}

/* 2. Semantic Tokens */
:root {
  --color-primary: var(--color-blue-500);
  --color-text: var(--color-gray-900);
  --spacing-md: var(--space-4);
}

/* 3. Component Tokens */
.button {
  --button-bg: var(--color-primary);
  --button-padding: var(--spacing-md);
}

File Structure Templates

Small Project

styles/
├── base.css
├── components.css
├── utilities.css
└── main.css

Medium Project

styles/
├── base/
│   ├── reset.css
│   └── typography.css
├── components/
│   ├── button.css
│   └── card.css
├── layouts/
│   └── grid.css
├── utilities/
│   └── helpers.css
└── main.css

Large/Enterprise Project

styles/
├── settings/
│   ├── _tokens.scss
│   └── _breakpoints.scss
├── tools/
│   ├── _mixins.scss
│   └── _functions.scss
├── generic/
│   └── _reset.scss
├── elements/
│   └── _typography.scss
├── objects/
│   └── _grid.scss
├── components/
│   ├── _button.scss
│   └── _card.scss
├── utilities/
│   └── _helpers.scss
└── main.scss

Naming Convention Comparison

Methodology Example Best For
BEM .block__element--modifier Component systems
SMACSS .l-grid, .is-active Multi-page sites
OOCSS .media, .media-body Reusable patterns
Atomic .flex, .p-4, .text-center Utility-first

Test Template

describe('CSS Architecture Skill', () => {
  test('validates methodology parameter', () => {
    expect(() => skill({ methodology: 'invalid' }))
      .toThrow('methodology must be one of: bem, smacss...');
  });

  test('returns BEM examples for bem methodology', () => {
    const result = skill({ methodology: 'bem' });
    expect(result).toContain('__');
    expect(result).toContain('--');
  });

  test('scales recommendations based on project_size', () => {
    const smallResult = skill({ methodology: 'itcss', project_size: 'small' });
    const largeResult = skill({ methodology: 'itcss', project_size: 'large' });
    expect(largeResult.layers).toBeGreaterThan(smallResult.layers);
  });
});

Error Handling

Error Code Cause Recovery
INVALID_METHODOLOGY Unknown methodology Show valid options
SIZE_MISMATCH Methodology too complex for project size Suggest simpler alternative
TOKEN_CONFLICT Conflicting token names Show naming resolution
  • css-fundamentals (prerequisite)
  • css-sass (preprocessor integration)
  • css-tailwind (utility-first approach)