utopia-container-queries

matthewharwood's avatarfrom matthewharwood

Container query setup required for this project's cqi-based fluid scales. The type and space tokens use cqi units which need container-type declarations to function.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 9, 2025
[Code Generation]

When & Why to Use This Skill

This Claude skill facilitates the implementation of CSS Container Queries specifically for Utopia-based fluid scaling systems. It automates the setup of container contexts (inline-size) required for cqi units to function, ensuring that typography and spacing scales respond accurately to container dimensions rather than just the viewport, preventing static layout issues.

Use Cases

  • Global Fluid Scale Activation: Automatically configuring the root HTML or body elements with the correct container-type to enable project-wide fluid typography and spacing.
  • Component-Based Responsive Design: Establishing local container contexts for specific UI components, allowing them to adapt their internal layout and scaling based on their own width rather than the screen size.
  • CSS Infrastructure Auditing and Repair: Identifying and fixing instances where fluid tokens (cqi units) are defined but inactive due to missing container-type declarations in existing stylesheets.
nameutopia-container-queries
descriptionContainer query setup required for this project's cqi-based fluid scales. The type and space tokens use cqi units which need container-type declarations to function.
allowed-toolsRead, Write, Edit

Utopia Container Queries

Container setup required for this project's fluid scales

Critical: cqi Units Require Container Context

This project's type and space scales use cqi (container query inline) units:

/* From typography.css */
--step-0: clamp(1.125rem, 1.0739rem + 0.2273cqi, 1.25rem);

/* From space.css */
--space-m: clamp(1.6875rem, 1.6108rem + 0.3409cqi, 1.875rem);

Without a container context, the cqi portion evaluates to 0, meaning values stay at their minimum.

Required Setup

For fluid scaling to work, you must establish a container context:

Apply to html or body for global container context:

html {
  container-type: inline-size;
}

Or in your component:

body {
  container-type: inline-size;
}

Option 2: Component-Level Containers

For component-specific containers:

.card-container {
  container-type: inline-size;
}

/* Optional: name the container */
.card-container {
  container: card / inline-size;
}

Current State

No container-type declarations exist in the CSS files. The fluid scales are defined but will not scale fluidly until container context is added.

Files That Need Container Context

File Has cqi Units Has container-type
typography.css Yes No
space.css Yes No
grid.css No (uses vw fallback) No

Adding Container Support

Minimal Setup

Add to css/styles/index.css:

html {
  container-type: inline-size;
}

Per-Component Setup

For isolated components:

.my-component {
  container-type: inline-size;
}

Container Query Syntax

Once containers are established, you can use container queries:

@container (inline-size > 400px) {
  .card {
    display: grid;
    grid-template-columns: 150px 1fr;
  }
}

/* Named container query */
@container card (inline-size > 600px) {
  .card__title {
    font-size: var(--step-3);
  }
}

Container Units Available

Unit Description
cqi 1% of container inline size (width in LTR)
cqb 1% of container block size (height in LTR)
cqw 1% of container width
cqh 1% of container height
cqmin Smaller of cqi/cqb
cqmax Larger of cqi/cqb

What's NOT Defined

The following are not currently in the CSS:

  • Any container-type declarations
  • Any @container queries
  • Named containers

The infrastructure (cqi-based tokens) exists, but the container context to make it functional does not.

Next Steps

  1. Add container-type: inline-size to html or body
  2. Verify fluid scaling works by resizing viewport
  3. Add component-level containers as needed
  4. Add @container queries for component-level responsiveness

Files

  • css/styles/index.css - Recommended location for root container setup
  • css/styles/layouts.css - Empty, available for container utilities