@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.

Installation

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

Tokens

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

Utilities / Generated Classes

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. 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

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

Responsive Grid Columns

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

.grid-cols-{1-12}-{bp} — sets grid-template-columns at the given breakpoint

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: All 46 unique reduced fractions with denominators 1–12.

Class	Value
.w-cq-1-1	100cqi
.w-cq-1-2	50cqi
.w-cq-1-3	33.3333cqi
.w-cq-2-3	66.6667cqi
.w-cq-1-4	25cqi
.w-cq-3-4	75cqi
.w-cq-1-6	16.6667cqi
.w-cq-5-6	83.3333cqi
.w-cq-1-12	8.3333cqi

Fluid text:

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

---

Usage Guide

Provides container-query-first responsive utilities — visibility, layout switching, responsive grids, and container-relative sizing — for the Vibe Design System.

Import

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

Common Patterns

1. Set up a container query context

Any responsive utility that uses @container requires a container ancestor:

<div class="container-inline">
  <!-- responsive children go here -->
</div>

2. Responsive card grid (1 → 2 → 4 columns)

<div class="container-inline">
  <div class="grid grid-cols-1 grid-cols-2-md grid-cols-4-xl gap-4">
    <div class="bg-elevated rounded-lg p-4">Card</div>
    <div class="bg-elevated rounded-lg p-4">Card</div>
    <div class="bg-elevated rounded-lg p-4">Card</div>
    <div class="bg-elevated rounded-lg p-4">Card</div>
  </div>
</div>

3. Stack-to-row layout at a breakpoint

<div class="container-inline">
  <div class="stack-to-row-md gap-6">
    <aside class="w-full">Sidebar content</aside>
    <main class="flex-1">Main content</main>
  </div>
</div>

4. Show/hide elements based on container width

<div class="container-inline">
  <!-- Only visible when container >= md -->
  <nav class="hidden-below-md flex gap-4">
    <a href="#">Full nav</a>
  </nav>

  <!-- Only visible when container < md (mobile nav) -->
  <button class="hidden-above-md">Menu</button>
</div>

5. Container-relative widths inside a sidebar

<div class="container-inline">
  <div class="w-cq-1-2 bg-elevated p-4 rounded">Half container width</div>
  <div class="w-cq-1-3 bg-elevated p-4 rounded">Third of container</div>
</div>

6. Fluid typography that scales with container

<div class="container-inline">
  <h2 class="text-cq-xl font-bold">
    Scales fluidly with container width, not viewport
  </h2>
  <p class="text-cq-base leading-relaxed">
    Body text that also responds to its container.
  </p>
</div>

Token Reference

Token	Value	Access via JS
--breakpoint-xs	480px	getComputedStyle(el).getPropertyValue('--breakpoint-xs')
--breakpoint-sm	640px
--breakpoint-md	768px
--breakpoint-lg	1024px
--breakpoint-xl	1280px
--breakpoint-2xl	1536px

Note: Breakpoint tokens are for JS access and documentation. Container queries in the CSS use hardcoded literal values (duplicated by the build script) because @container does not support CSS custom properties in query conditions.