🗺️ CSS & Styling Architecture — MOC

Map of Content. How styling decisions are encoded: tokens, the cascade, and the component styling contract. Sibling to Software Architecture.

Canonical source: the css-conventions skill (~/resources/scripts/dotfiles/skills/css-conventions/). These notes capture the transferable why; the skill holds the full rules and token inventory.

Design tokens

• Three-Tier Design Tokens — primitive → semantic → component; each tier consumes only the one above
• The Semantic Token Layer Makes Theming Free — components read semantics only, so a theme is one [data-theme] override block
• Unit Choice Tracks Whether a Value Should Scale With Text — rem for text/spacing, px for visual detail, em for tracking, unitless line-height
• Deprecation-Alias Pattern for Renaming Public Names — alias old→new with removal date; migrate usages first (generalizes beyond CSS)

Cascade & layers

• Unlayered CSS Beats Layered CSS — the footgun: @layer overrides loses to unlayered third-party styles regardless of order
• Scoped Styles Skip the Layer Wrapper; Global Styles Need It — auto-scoped styles need no @layer components; opting out of scoping does
• Isolate Third-Party Overrides in an Overrides Partial — _overrides.scss, @layer overrides, wrapper-scoped, tokens only

Component styling contract

• CSS Custom Properties Are a Component's Styling API — expose --vars on the root; parents override those, never pierce internals (replaces ::ng-deep)

All linked notes

LIST
FROM [[CSS & Styling Architecture]]
WHERE type = "zettel" OR type = "source"
SORT file.name ASC

Open questions

• Does the three-tier token model generalize to any design-decision store (config systems, not just CSS)?
• Should the deprecation-alias pattern be promoted to a standalone, domain-general "API evolution" note?