# CSS Architecture

> Organize stylesheets with scoping, co-location, and layer order so CSS stays deletable as the codebase grows. Use when structuring styles for a growing app or auditing a stylesheet nobody dares touch.

- Skill: `amey-thakur/css-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add amey-thakur/css-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/amey-thakur/css-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Amey-Thakur (https://skillmd.com/u/amey-thakur)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/amey-thakur/css-architecture

---


# CSS architecture

The health metric for CSS is deletability: when a component dies, its
styles must die with it, provably. Every practice here serves that.

## Method

1. **Co-locate styles with components.** One style unit per component,
   living next to it (CSS Modules, scoped SFC styles, utility classes in
   markup, or a `.css` imported by the component). Global stylesheets
   accumulate; co-located ones get deleted with their component.
2. **Pick one scoping mechanism and hold it.** CSS Modules or scoped
   styles for build-time isolation; utility classes for token-constrained
   markup styling; Shadow DOM only for embeddable widgets. Mixing idioms
   per-feature multiplies the knowledge needed to touch anything.
3. **Define the global layer order once.**
   `@layer reset, tokens, base, components, utilities;` in the entry
   stylesheet. Globals are exactly: reset, token definitions, element
   defaults (`base`), and shared utilities. Anything else claiming global
   status needs an argument.
4. **Style through stable interfaces.** Components expose modifiers
   (`data-variant`, props) and semantic tokens; parents size and position
   children (`grid-area`, width on the slot), never reach inside them
   (`.parent .child-internal` is the coupling that makes CSS undeletable).
5. **Keep specificity flat inside a scope.** One class or attribute
   selector deep (see css-cascade); state via `data-*` or aria attributes
   (`[aria-expanded="true"]`), which doubles as an accessibility
   contract.
6. **Delete with tooling, not archaeology.** Scoped styles make unused
   CSS visible (unimported file, unreferenced local class); CI can run
   coverage or lint for orphaned modules. A quarterly "grep the class
   name, delete the rule" pass keeps the base honest even without
   tooling.

## Boundaries

- Naming conventions (BEM) solved scoping before build tools did; adopt
  them only where no build-time scoping exists (CMS themes, legacy
  server-rendered apps).
- Print styles, email HTML, and rendered user content are separate
  stylesheets with their own rules; do not fold them into the app system.
- Architecture cannot fix an undesigned system; without tokens and
  components, organizing files is rearranging the pile.