CSS Architecture Skill Skill

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)

Agent Skills: CSS Architecture Skill

Skill Files