responsive

Responsive Rules (responsive)

The responsive category contains static analysis rules for code quality, architectural constraints, and design system governance.

---

Category Rule Index

Rule ID	Severity	Summary	Full Specification	Status
responsive.aspect-ratio-overflow	WARN	Warns against fixed aspect-ratio combined with rigid static heights without fluid width boundaries on mobile viewports	responsive.aspect-ratio-overflow	enabled
responsive.container-overconstraint	WARN	Warns against excessive mobile horizontal padding or overconstrained widths that pinch usable content width below 280px on smartphone viewports	responsive.container-overconstraint	enabled
responsive.desktop-only-content	WARN	Warns when primary action buttons or form submit controls are hidden on mobile viewports without mobile alternatives	responsive.desktop-only-content	enabled
responsive.dynamic-viewport-inconsistency	WARN	Warns when static viewport units (100vh, h-screen) and modern dynamic units (dvh, svh) are mixed inconsistently across layout hierarchies	responsive.dynamic-viewport-inconsistency	enabled
responsive.fixed-width-overflow	ERROR	Detects static fixed container widths exceeding 320px that cause horizontal overflow on mobile viewports	responsive.fixed-width-overflow	enabled
responsive.flex-child-overflow	WARN	Warns when a flex child containing text or dynamic content lacks min-w-0, causing min-width: auto container blowout	responsive.flex-child-overflow	enabled
responsive.grid-min-column	WARN	Warns against CSS grid minmax column definitions with rigid minimum sizes (> 320px) that cause horizontal overflow on mobile viewports	responsive.grid-min-column	enabled
responsive.horizontal-overflow	WARN	Warns when unconstrained overflow-x-scroll is declared without fluid width boundary or dynamic auto-scrolling	responsive.horizontal-overflow	enabled
responsive.image-overflow	WARN	Warns when media elements with large fixed dimensions lack responsive max-w-full scaling	responsive.image-overflow	enabled
responsive.keyboard-obstruction	WARN	Warns against fixed bottom action bars in forms lacking vertical scroll containers, which can be obstructed by the mobile virtual keyboard	responsive.keyboard-obstruction	enabled
responsive.missing-breakpoint	WARN	Warns when multi-column grids or giant font sizes are declared on mobile baseline without responsive breakpoint modifiers	responsive.missing-breakpoint	enabled
responsive.mobile-density-overload	WARN	Warns when toolbars or action rows cram more than 4 interactive buttons in a single unscrollable row on mobile viewports	responsive.mobile-density-overload	enabled
responsive.mobile-text-overflow	WARN	Warns when whitespace-nowrap text or code blocks lack truncation, word breaking, or horizontal scroll wrappers	responsive.mobile-text-overflow	enabled
responsive.safe-area-missing	WARN	Warns when bottom-docked fixed or sticky elements lack safe-area-inset-bottom padding for modern mobile home indicators	responsive.safe-area-missing	enabled
responsive.unwrapped-table-overflow	WARN	Warns when an HTML table element lacks a responsive horizontal scroll wrapper (overflow-x-auto) or responsive display transformation	responsive.unwrapped-table-overflow	enabled
responsive.viewport-meta-missing	WARN	Warns when is missing width=device-width or viewport-fit=cover	responsive.viewport-meta-missing	enabled
responsive.viewport-unit-leak	WARN	Warns when viewport height relies on static 100vh instead of modern dynamic dvh or svh units	responsive.viewport-unit-leak	enabled

---

How the Responsive Layout Analysis Pipeline Works

The responsive engine analyzes layout structures, touch target ergonomics, and modern CSS container queries:

flowchart LR
    subgraph Inputs ["1. Workspace Inputs"]
        Components["Component Files (*.astro, *.tsx)"]
    end

    subgraph Inspection ["2. Layout & Touch Traversal"]
        Components --> AST["Leaf IR Traversal"]
        AST --> TouchNodes["Interactive Controls (button, a, tap targets)"]
        AST --> LayoutNodes["Container & Grid Layouts"]
    end

    subgraph Evaluation ["3. Responsive Rule Evaluation"]
        TouchNodes --> Fitts["Fitts's Law Evaluator (min 44x44px bounding area)"]
        LayoutNodes --> Containers["Container Query Enforcer (@container vs rigid viewport)"]
        LayoutNodes --> Overflow["Mobile Overflow & Scroll-Jank Detector"]
    end

    subgraph Output ["4. Results"]
        Fitts --> Decision{"Touch & Layout Ergonomics Check"}
        Containers --> Decision
        Overflow --> Decision
        Decision -- "Compliant" --> Safe["Pass"]
        Decision -- "Violation" --> Diag["Diagnostic: responsive.*"]
    end

Loading

Pipeline Flow:

1. Touch Target Sizing: Evaluates interactive controls against Fitts's Law, verifying minimum tap target dimensions of 44x44px (min-h-11 min-w-11 / size-11).
2. Container Query Governance: Enforces modular @container queries over fragile page-level viewport media queries (sm:, md:, lg:).
3. Viewport & Overflow Analysis: Identifies fixed-width containers that cause mobile horizontal scrollbars or layout breakage.

---

How Responsive Tests Work (Verification Harness)

Responsive rules are verified against:

1. 1-SSOT Golden Tri-Corpus (tests/correctness/responsive.*/):
   • Positive: Flags undersized interactive buttons, hardcoded viewport constraints, and overflowing data tables.
   • Negative: Confirms passes for fluid container query layouts and 44x44px compliant controls.
   • Adversarial: Tests nested grid layouts with responsive variant overrides.