# Cascade layer strategy

Use this reference when establishing or auditing a `@layer` order for a codebase, or resolving a specificity conflict between two legitimate rules.

## What people get wrong

The naive story is:

> Cascade layers are just a naming convention — put rules in a `@layer` block and specificity stops mattering.

Half right, and the half that's wrong is dangerous. Layers change *which layer wins*, but specificity still decides the winner *within* a layer, and — critically — the precedence order **inverts** for `!important` declarations. Per MDN's cascade-layers guidance: earlier-declared layers win over later-declared layers for normal declarations, but for `!important` declarations, earlier-declared layers win over later ones too — meaning an `!important` in an early "reset" layer can beat an `!important` in a later "overrides" layer, which is the opposite of what most engineers assume ("overrides should always win"). Unlayered styles sit in an implicit final layer for normal declarations, but unlayered `!important` styles have *lower* precedence than any layered `!important` declaration. Get this backwards and you'll "fix" a cascade bug by adding `!important` to the wrong layer and watch it silently lose anyway.

## Officially grounded shape (MDN / W3C Cascade 5)

- `@layer name1, name2, name3;` declares layer order upfront, independent of where each layer's rules are later defined in the file.
- Layer order determines precedence **regardless of selector specificity** for normal (non-important) declarations — a low-specificity selector in a later layer beats a high-specificity selector in an earlier layer.
- Unlayered styles form an implicit layer that comes **last** (highest precedence) for normal declarations.
- For `!important` declarations, the precedence order is **inverted**: earlier-declared layers' important styles win over later layers' important styles, and layered important styles always beat unlayered important styles.
- Inline `style=""` importance still beats all author-layer `!important` declarations, regardless of layer order.
- `@import url(...) layer(name);` can assign an entire imported stylesheet to a layer, which is useful for third-party CSS you don't control (framework resets, component libraries) — put it in an early layer so your own rules can override it without `!important`.

## Non-negotiable design rules

### 1. Declare the full layer order in one place, upfront

Do not let layer order emerge implicitly from file-load order. A single `@layer reset, base, tokens, components, utilities, overrides;` statement (naming may vary per codebase convention) at the top of the entry stylesheet is the source of truth. If layer order is scattered or redeclared inconsistently across files, the *effective* order becomes whatever browser resolves first-seen — audit for this as a HIGH-severity finding.

### 2. `!important` inside a layer is not a free pass — verify the inversion

Before approving `!important` anywhere, confirm which layer it lives in and whether the intended "win" actually happens under the inverted precedence rule. An `!important` added to `overrides` (a late layer) to "make sure it wins" will **lose** to an `!important` already present in an earlier layer like `reset`. This is the single most common cascade-layer mistake — check it explicitly, don't assume.

### 3. Third-party/vendor CSS goes in the earliest layer

Wrap vendor resets, component-library base styles, or any CSS the team doesn't control in its own early layer (or `@import ... layer(vendor);`). This guarantees your own component/utility layers can override it with normal specificity, with no `!important` needed at all — that's the actual payoff of adopting layers.

### 4. Utilities still need to out-rank components, by layer not specificity

If the codebase uses utility classes (e.g. Tailwind-style) alongside component styles, utilities must live in a layer declared *after* the components layer. Do not rely on utility classes having higher specificity than component selectors — that's fragile and exactly the pattern layers exist to replace.

### 5. New ID-selector or `!important` usage outside an established layer is a regression, not a quick fix

Once a codebase has adopted cascade layers, any new unlayered `!important` or ID-selector styling should be treated as bypassing the system the team already invested in. Flag it and point to the correct layer.

## Specificity primer (for the parts layers don't cover)

Within a single layer (or in a codebase with no layers), specificity still resolves conflicts using the standard weight: inline style > ID selectors > class/attribute/pseudo-class selectors > type/pseudo-element selectors, with `!important` overriding all of the above except a later `!important` of equal-or-higher-weight origin. Report specificity as a 4-part tuple (inline, IDs, classes/attrs/pseudo-classes, types/pseudo-elements) when it materially matters to a finding — do not just say "too specific" without the number.

## Minimal safe implementation flow

1. Confirm whether the codebase already declares a layer order. If yes, audit new rules against it. If no, do not retrofit an entire stylesheet into layers as a side effect of a routine review — recommend it as a separate, scoped initiative and note the current specificity-conflict risk in the meantime.
2. For any flagged `!important` or ID selector, identify the specific rule it's fighting and the minimal layer-based fix (move to correct layer, or remove the escalation entirely because the real fix is layer placement).
3. Verify inverted `!important` precedence explicitly for any layer-crossing `!important` conflict before declaring a winner — do not eyeball it.
4. Note any third-party CSS that isn't isolated into its own layer as a maintainability risk.

## Adversarial checklist

Before finalizing a cascade-layer finding, answer these:

- Is the full layer order declared in exactly one place, and does every file agree with it?
- If this conflict involves `!important` on both sides, did I apply the inverted precedence rule, or did I default to "later wins" (which is wrong for important declarations)?
- Is this `!important` compensating for a missing/incorrect layer assignment, rather than a legitimate necessity (e.g., overriding inline styles from a CMS)?
- Is the specificity claim backed by an actual computed tuple, or asserted qualitatively ("too specific")?

If any answer is "not sure," lower the finding's confidence and label it `documentation-based, needs live cascade-order verification` rather than presenting it as a confirmed defect.

# Responsive strategy decision guide

Use this reference when deciding container query vs. media query, or auditing reflow/resize-text compliance at 400%/200% zoom.

## What people get wrong

The naive story is:

> Container queries are the new best practice — replace media queries with them wherever possible.

Wrong. Container queries and media queries answer different questions and are not interchangeable. A media query answers "how big is the viewport (or does the user prefer reduced motion / dark mode / etc.)?" A container query answers "how big is *this specific containing element*, regardless of viewport?" A component meant to be reusable inside a narrow sidebar *and* a wide main-content area needs a container query — a media query cannot express that, because the viewport is the same in both placements. Conversely, a page-level layout shift (e.g. switching a top-nav to a hamburger menu) is inherently viewport-driven and belongs in a media query — wrapping the whole page in a container just to query it is unnecessary indirection.

## Officially grounded shape (MDN CSS Containment / Container Queries)

- `container-type: inline-size;` (or `size`) on an ancestor establishes a **query container**; `container-name` optionally scopes which `@container` rules target it.
- `@container (width >= 400px) { ... }` and named variants `@container excerpt (width >= 400px) { ... }` share the same comparison syntax and logical operators (`and`, `or`, `not`) as media queries.
- Container **style** queries (`@container style(--flag: value)`) also exist for querying a custom-property value on the container, distinct from size queries — verify which variant (`size` vs `style` vs both) the codebase/browser target actually needs before recommending one.
- A container query cannot query the size of the element it's applied to relative to itself (no self-referential sizing loop) — the `container-type` must be set on an **ancestor**, and the query targets descendants of that ancestor.
- Setting `container-type: size` or `inline-size` on an element applies layout/size containment to it, which affects how that element's children are sized (e.g. percentage heights) — this is a real layout side effect, not a no-op flag, and must be accounted for, not just bolted on to "enable container queries."

## Non-negotiable design rules

### 1. Ask "does this depend on its container, or on the viewport?" before choosing

If the same component needs different styling depending on *where it's placed* (sidebar vs. full-width), that's a container-size dependency → container query. If the same component always needs the same styling regardless of placement, but that styling should change based on *screen size*, that's a viewport dependency → media query. Do not default to container queries just because they are newer; recommending one when the actual dependency is viewport-based is a correctness bug, not a stylistic choice.

### 2. Verify the containment side effect before approving `container-type`

Applying `container-type: size` or `inline-size` establishes containment that can change how a container's children resolve percentage-based dimensions and can affect the container's own intrinsic sizing behavior. Flag any new `container-type` addition to an element whose children rely on percentage heights or intrinsic sizing without a check that behavior is still correct.

### 3. Do not recommend "just add both" as a hedge

Applying both a media query and a container query to the same rule for the "same" breakpoint without a distinct rationale for each is a maintainability trap — two systems now need to be kept in sync for one visual outcome. If both are genuinely needed (e.g., viewport-level layout change *and* the component independently needs to adapt to a narrower container within that layout), state the distinct rationale for each explicitly.

### 4. Media queries remain correct — and required — for preference-based and non-size media features

`prefers-reduced-motion`, `prefers-color-scheme`, `prefers-contrast`, `forced-colors`, and print media all have no container-query equivalent; container queries only address size/style-of-container, not user/device preference signals. Never suggest replacing a preference-based media query with a container query.

## WCAG 2.2 reflow and resize-text audit

- **1.4.10 Reflow**: content must be usable without horizontal scrolling (except content requiring 2D layout, like data tables or images) at a 320 CSS-px equivalent viewport width (i.e., 400% zoom on a 1280px-wide viewport). Flag any fixed-width container, fixed `min-width` wider than ~320px on primary content, or `overflow-x` forced on the body/main content region as a reflow-failure risk.
- **1.4.4 Resize text**: text must remain readable and functional when resized up to 200% without loss of content or functionality, without requiring assistive technology. Flag any font-size defined in `px` on root/body text without a corresponding relative-unit (`rem`/`em`/`%`) sizing strategy, and flag any fixed-height text container that would clip text at 200% zoom.
- Fixed viewport units (`vh`/`vw`) used for text container height, combined with fixed-size text, is a common reflow+resize-text double failure — flag it as one finding with both WCAG criteria cited, not two separate notes.
- These are static-review flags based on markup/CSS inspection, not a substitute for live zoom/reflow testing in a real browser — always label the finding `documentation-based risk, requires live verification at 400%/200% zoom`.

## Minimal safe implementation flow

1. For each new/changed responsive rule, identify what the styling actually depends on: container size, viewport size, or a user/device preference.
2. Match the dependency to the correct query type per the rules above.
3. If `container-type` is newly applied, check descendant elements for percentage-based sizing that containment could affect.
4. Scan for fixed-width primary-content containers, fixed-px text sizing, and fixed-height text containers as reflow/resize-text risk flags.
5. Report all size-based container-query/media-query findings and all WCAG 1.4.10/1.4.4 flags as `documentation-based risk` pending live-browser verification — never assert a WCAG pass/fail from static review alone.

## Adversarial checklist

Before finalizing a responsive-strategy finding, answer these:

- Is the actual styling dependency container-size, viewport-size, or a user/device preference — confirmed, not assumed?
- If recommending `container-type`, did I check whether it changes containment behavior for existing percentage-sized children?
- Am I recommending both a media query and a container query for the same visual outcome without a distinct rationale for each?
- Have I mislabeled a static-review flag as a confirmed WCAG pass/fail instead of a risk pending live verification?

If any answer is "not sure," lower the finding's confidence and label it `documentation-based, requires live verification` rather than presenting it as a confirmed defect.

# Design token conformance patterns

Use this reference when auditing hardcoded-value drift against an existing custom-property token system, including token-tier (primitive vs. semantic vs. component) conventions.

## What people get wrong

The naive story is:

> If a codebase has CSS custom properties, any hex code or `px` value found in a stylesheet is a violation — just swap in the nearest-looking token.

Wrong on two counts. First, not every hardcoded value is drift — a one-off value with no semantic meaning (e.g. a decorative `box-shadow` blur radius unique to one component) may legitimately not belong in the token system. Second, "nearest-looking" is the wrong selection criterion: swapping a hardcoded `#3B82F6` for whatever token happens to render the closest shade of blue, without checking whether that token is semantically named for a *different* purpose (e.g. `--color-danger` vs `--color-brand-primary` happening to be visually similar), silently couples unrelated UI concerns and will drift the moment either token's value changes for its actual intended purpose.

## Officially grounded shape (W3C CSS Custom Properties / MDN)

- CSS custom properties (`--token-name: value;`) are just inherited, cascade-participating properties — they carry no built-in type, tier, or namespace semantics. Any tiering convention (primitive/semantic/component) is a *codebase convention*, not a CSS-spec-enforced structure. Verify the codebase's actual convention before applying a generic three-tier assumption.
- `var(--token-name, fallback)` resolves to `fallback` only if the custom property is unset or invalid at computed-value time — an empty-string or whitespace-only fallback is valid and will not error, which can silently produce unstyled output. Flag fallback values used to paper over a token that should exist but doesn't.
- Custom properties are visible to and overridable at any DOM node via the cascade — a component-scoped token override (e.g. `.card { --spacing-gap: 8px; }`) is a normal and often correct pattern, not automatically drift.

## Non-negotiable design rules

### 1. Establish which token tiers actually exist in this codebase before auditing

Common conventions: **primitive** (raw values: `--blue-500: #3B82F6`), **semantic** (purpose-bound: `--color-brand-primary: var(--blue-500)`), **component** (scoped: `--button-bg: var(--color-brand-primary)`). Not every codebase has all three tiers. Read the existing token file(s) first — do not assume a tier structure the codebase hasn't adopted.

### 2. Flag hardcoded values only when a token exists for that exact purpose

If a semantic token like `--spacing-md` exists and a new rule hardcodes `16px` where `--spacing-md` resolves to the same value, that's drift — flag it and name the token. If no token covers that specific purpose (e.g. a genuinely one-off decorative value), do not force a token substitution; note it as "no matching token — token-system gap or legitimately one-off" and let a human decide whether to add a token.

### 3. Recommend the correct tier, not just the nearest value

When a hardcoded value should become a token, point to the most specific applicable tier — component tier if a component-scoped token already exists for that role, semantic tier if not, primitive tier only as a last resort (raw primitives should rarely be referenced directly from component styles; that's what semantic tokens are for). Recommending a raw primitive when a semantic token already covers the case reintroduces exactly the coupling problem tokens exist to prevent.

### 4. Treat `var()` fallback values as a signal, not noise

A `var(--token, <hardcoded-fallback>)` pattern used defensively across many call sites for the *same* token is a sign the token itself may be missing from some build/theme context — flag it as a build/theming risk, not a per-call-site style nitpick.

### 5. Do not flag legitimate component-scoped overrides as drift

`.card--compact { --card-padding: var(--spacing-sm); }` is normal token-system usage (a component redefining a token it owns, still referencing the token system). Only flag when the override value is hardcoded raw instead of referencing another token, or when it silently diverges from the token's documented purpose.

## Minimal safe implementation flow

1. Locate and read the codebase's token definition file(s) (commonly `:root { --... }` blocks, a `tokens.css`, or a design-tokens JSON/YAML source feeding generated CSS).
2. Determine the tier convention in use, if any.
3. Grep the diff/file under review for raw color (`#`, `rgb(`, `hsl(`), spacing (`px`, `rem` outside of token definitions), and typography (font-family, font-size literals) values.
4. For each hit, check whether an existing token resolves to the same or functionally equivalent value and purpose. Report a match, a "gap" (no token exists), or confirm it's an intentional one-off.
5. Never invent a token name that doesn't exist in the codebase and present it as if it does — only recommend using tokens that are confirmed present via Read/Grep.

## Adversarial checklist

Before finalizing a token-conformance finding, answer these:

- Does a token actually exist for this exact purpose, confirmed via Read/Grep — not assumed from naming convention alone?
- Am I recommending the most specific applicable tier (component > semantic > primitive), or just the first token that visually matches?
- Could this hardcoded value be a legitimate one-off rather than drift?
- Is this `var()` fallback masking a real token-availability gap in some theme/build context?

If any answer is "not sure," report it as "no matching token found — confirm with design-system owner" rather than asserting a specific token substitution as fact.