@vibe-labs/design-responsive

Container-query-first responsive primitives for the Vibe Design System. Provides breakpoint tokens, container setup utilities, responsive visibility, layout switching, responsive grid columns, and container-relative sizing.

Usage

@import "@vibe-labs/design-responsive";

Contents

Tokens (responsive.css)

Breakpoint reference values in @layer vibe.tokens. These exist for documentation and JavaScript access via getComputedStyle() — @container queries require literal values, so the build script duplicates them.

Token	Value
--breakpoint-xs	480px
--breakpoint-sm	640px
--breakpoint-md	768px
--breakpoint-lg	1024px
--breakpoint-xl	1280px
--breakpoint-2xl	1536px

Generated Utilities (responsive.g.css)

All classes in @layer vibe.utilities.

Container Setup

Make an element a container query context:

Class	Effect
.container-inline	container-type: inline-size — the 95% use case
.container-size	container-type: size (both axes)
.container-normal	container-type: normal (named only, no sizing)

Named containers for targeted queries:

.container-name-main · .container-name-sidebar · .container-name-card · .container-name-panel

Container-Based Visibility

Hide/show elements based on their nearest container's width. Uses revert-layer on show so the element's original display type (flex, grid, etc.) is preserved.

Class	Behaviour
.hidden-below-{bp}	display: none by default, reverts at breakpoint
.hidden-above-{bp}	Visible by default, display: none at breakpoint

Breakpoints: xs · sm · md · lg · xl · 2xl

Viewport-Based Visibility

For page-level concerns where container queries aren't appropriate (e.g. top-level navigation, full-page layouts). Uses @media instead of @container.

Class	Behaviour
.viewport-hidden-below-{bp}	display: none by default, reverts at breakpoint
.viewport-hidden-above-{bp}	Visible by default, display: none at breakpoint

Breakpoints: xs · sm · md · lg · xl · 2xl

Stack-to-Row

Flex column by default, switches to row when the container reaches the breakpoint. Container-query-based.

.stack-to-row-xs · .stack-to-row-sm · .stack-to-row-md · .stack-to-row-lg · .stack-to-row-xl · .stack-to-row-2xl

<div class="container-inline">
  <div class="stack-to-row-md gap-4">
    <div>Sidebar</div>
    <div>Main content</div>
  </div>
</div>

Responsive Grid Columns

Container-query-based grid column overrides. Compose with the base .grid and .grid-cols-{n} utilities from @vibe-labs/design-display:

Class	Effect
.grid-cols-{1-12}-{bp}	Sets grid-template-columns at the given breakpoint

<div class="container-inline">
  <div class="grid grid-cols-1 grid-cols-2-md grid-cols-4-xl gap-4">
    <div>Card</div>
    <div>Card</div>
    <div>Card</div>
    <div>Card</div>
  </div>
</div>

The base .grid-cols-1 applies by default. At md, the container query activates .grid-cols-2-md. At xl, .grid-cols-4-xl takes over. Because responsive utilities are loaded after display utilities, source order ensures the correct cascade.

Container Query Units

Container-relative sizing using cqi units:

Fractional widths: Generated from all unique reduced fractions with denominators 1–12. The deduplication means you get .w-cq-1-2 (50cqi) but not .w-cq-2-4 or .w-cq-3-6.

Common examples:

Class	Value	Equivalent
.w-cq-1-1	100cqi	full
.w-cq-1-2	50cqi	half
.w-cq-1-3	33.3333cqi	third
.w-cq-2-3	66.6667cqi	two thirds
.w-cq-1-4	25cqi	quarter
.w-cq-3-4	75cqi	three quarters
.w-cq-1-6	16.6667cqi	sixth
.w-cq-5-6	83.3333cqi	five sixths
.w-cq-1-12	8.3333cqi	twelfth
.w-cq-5-12	41.6667cqi
.w-cq-7-12	58.3333cqi
.w-cq-11-12	91.6667cqi

Full list: all 46 unique fractions from denominators 1–12.

Text: Fluid typography clamped between min and max values:

Class	Size
.text-cq-sm	clamp(0.75rem, 2.5cqi, 0.875rem)
.text-cq-base	clamp(0.875rem, 3cqi, 1rem)
.text-cq-lg	clamp(1rem, 3.5cqi, 1.25rem)
.text-cq-xl	clamp(1.25rem, 4.5cqi, 1.5rem)

Dist Structure

File	Description
index.css	Barrel — imports both files below
responsive.css	Breakpoint token definitions
responsive.g.css	Generated responsive utilities

Dependencies

Runtime (CSS custom properties, not npm):

• @vibe-labs/design-display — base .grid and .grid-cols-{n} classes that responsive grid columns build upon

Build

npm run build