css-architecture
Implement scalable CSS architecture patterns - BEM, SMACSS, ITCSS, design tokens
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.
| name | css-architecture |
|---|---|
| description | Implement scalable CSS architecture patterns - BEM, SMACSS, ITCSS, design tokens |
| sasmp_version | "1.3.0" |
| version | "2.0.0" |
| updated | "2025-12-30" |
| bonded_agent | 04-css-architecture |
| bond_type | PRIMARY_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 |
Related Skills
- css-fundamentals (prerequisite)
- css-sass (preprocessor integration)
- css-tailwind (utility-first approach)