Css Architecture

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

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

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

Related Skills

• css-fundamentals (prerequisite)
• css-sass (preprocessor integration)
• css-tailwind (utility-first approach)

Css Architecture Guide

Overview

This guide provides comprehensive documentation for the css-architecture skill in the custom-plugin-css plugin.

Category: General

Quick Start

Prerequisites

• Familiarity with general concepts
• Development environment set up
• Plugin installed and configured

Basic Usage

# Invoke the skill
claude "css-architecture - [your task description]"

# Example
claude "css-architecture - analyze the current implementation"

Core Concepts

Key Principles

1. Consistency - Follow established patterns 2. Clarity - Write readable, maintainable code 3. Quality - Validate before deployment

Best Practices

• Always validate input data
• Handle edge cases explicitly
• Document your decisions
• Write tests for critical paths

Common Tasks

Task 1: Basic Implementation

# Example implementation pattern
def implement_css_architecture(input_data):
    """
    Implement css-architecture functionality.

    Args:
        input_data: Input to process

    Returns:
        Processed result
    """
    # Validate input
    if not input_data:
        raise ValueError("Input required")

    # Process
    result = process(input_data)

    # Return
    return result

Task 2: Advanced Usage

For advanced scenarios, consider:

• Configuration customization via assets/config.yaml
• Validation using scripts/validate.py
• Integration with other skills

Troubleshooting

Common Issues

Related Resources

• SKILL.md - Skill specification
• config.yaml - Configuration options
• validate.py - Validation script

---

Last updated: 2025-12-30

Css Architecture Patterns

Design Patterns

Pattern 1: Input Validation

Always validate input before processing:

def validate_input(data):
    if data is None:
        raise ValueError("Data cannot be None")
    if not isinstance(data, dict):
        raise TypeError("Data must be a dictionary")
    return True

Pattern 2: Error Handling

Use consistent error handling:

try:
    result = risky_operation()
except SpecificError as e:
    logger.error(f"Operation failed: {e}")
    handle_error(e)
except Exception as e:
    logger.exception("Unexpected error")
    raise

Pattern 3: Configuration Loading

Load and validate configuration:

import yaml

def load_config(config_path):
    with open(config_path) as f:
        config = yaml.safe_load(f)
    validate_config(config)
    return config

Anti-Patterns to Avoid

❌ Don't: Swallow Exceptions

# BAD
try:
    do_something()
except:
    pass

✅ Do: Handle Explicitly

# GOOD
try:
    do_something()
except SpecificError as e:
    logger.warning(f"Expected error: {e}")
    return default_value

Category-Specific Patterns: General

Recommended Approach

1. Start with the simplest implementation 2. Add complexity only when needed 3. Test each addition 4. Document decisions

Common Integration Points

• Configuration: assets/config.yaml
• Validation: scripts/validate.py
• Documentation: references/GUIDE.md

---

Pattern library for css-architecture skill