css-modern

name	css-modern
description	Enforce modern CSS authoring with DTCG-aligned design tokens, native nesting, container queries, cascade layers, and progressive enhancement. Use when creating, reviewing, or refactoring `.css` files or style blocks in web codebases including Vue/Nuxt/Quasar and Tailwind-powered apps.

CSS Modern

Overview

Apply modern CSS platform features with predictable cascade control, token-driven styling, and progressive enhancement. Treat design tokens as a system contract, keep selectors and specificity maintainable, and prefer native CSS features over legacy Sass-era workarounds.

Load References On Demand

• Read references/modern-css-source.md for copy-ready patterns and framework bridges (Vue/Nuxt/Quasar/Tailwind).
• Read references/support-snapshot-2026-02.md when deciding fallback policy or feature gating.

Core Workflow

1. Confirm token source of truth (DTCG JSON or existing token registry).
2. Map tokens to runtime CSS custom properties and semantic aliases.
3. Define cascade order with @layer and isolate vendor CSS in a vendor layer.
4. Implement component styles with native nesting, modern selectors, and container queries.
5. Add fluid sizing, logical properties, and modern color/theming primitives.
6. Gate partial-support features with @supports and explicit fallback behavior.
7. Review accessibility, motion preferences, and performance-oriented CSS features.

Modern CSS Rules

1. Use Design Tokens As The Source Of Truth (DTCG-First)

• Prefer DTCG token format for canonical token data ($value, $type, $description, alias references).
• Map canonical tokens to CSS custom properties in global and semantic scopes.
• Keep semantic token names stable; allow value churn behind them.
• Avoid hard-coded values in components unless a one-off value is intentional and documented.

{
  "color": {
    "brand": {
      "primary": { "$type": "color", "$value": "oklch(62% 0.2 256)" }
    },
    "surface": {
      "default": { "$type": "color", "$value": "#ffffff" }
    }
  }
}

:root {
    --color-brand-primary   : oklch(62% 0.2 256);
    --color-surface-default : #ffffff;
    --space-4               : 1rem;
    --radius-md             : 0.5rem;
}

2. Bridge Tokens Into Framework CSS Pipelines

• Vue/Nuxt/Quasar: consume CSS vars directly in SFC style blocks; use v-bind() only for component-reactive values.
• Tailwind v4: keep tokens in @theme and align naming with CSS vars so utilities and raw CSS share the same source values.
• Keep token mapping deterministic so design, app CSS, and utility classes stay synchronized.

@theme {
    --color-brand-primary : oklch(62% 0.2 256);
    --spacing-4           : 1rem;
    --radius-md           : 0.5rem;
}

3. Control Cascade Predictably With @layer

• Declare global layer order once.
• Import third-party CSS into a dedicated vendor layer.
• Use layers to avoid specificity escalation.

@layer reset, vendor, tokens, base, components, utilities, overrides;
@import url("vendor.css") layer(vendor);

4. Use Native Nesting, But Keep It Shallow

• Use native nesting for state selectors, local descendants, and colocated queries.
• Keep depth at <= 3 levels.
• Avoid deep DOM-coupled selectors.

5. Use Container Queries For Component Responsiveness

• Set container: <name> / inline-size (or container-type + container-name) at component boundaries.
• Prefer container queries for component internals; keep viewport media queries for page shell layout.
• Use container query units (cqw, cqh, cqi, cqmin, cqmax) when sizing should track container width/height.

6. Use Modern Selectors Deliberately

• Use :has() for parent/state-driven styling where it simplifies markup/JS.
• Use :is() to group selector variants with normal specificity.
• Use :where() for zero-specificity defaults.
• Always include accessible keyboard focus states with :focus-visible.

7. Prefer Modern Layout, Sizing, and Internationalization Primitives

• Use Grid/Flex with gap instead of margin-based spacing hacks.
• Use clamp(), min(), max(), and calc() for fluid sizing.
• Prefer logical properties (padding-inline, border-inline-start, inset-block) over physical left/right properties.
• Use aspect-ratio instead of padding-box ratio hacks.

8. Use Modern Color and Theming Primitives

• Prefer perceptual color spaces (oklch) for token values.
• Derive variants with color-mix() instead of manually duplicating palettes.
• Use color-scheme and light-dark() when dual-theme behavior is needed.
• Treat accent-color as enhancement, not correctness-critical styling.

9. Handle Motion, Interaction, and Performance Intentionally

• Respect user preferences (prefers-reduced-motion, contrast and forced-color modes where relevant).
• Use @starting-style, transition-behavior: allow-discrete, and popover hooks as enhancement patterns.
• Use content-visibility and containment for long lists and heavy offscreen content.
• Use scrollbar-gutter: stable to reduce layout shift during scrollbar appearance.

Progressive Enhancement Policy (Tiered Modern-First)

• Safe default: use broadly supported modern features by default.
• Enhancement tier: require @supports guard plus acceptable fallback behavior.
• Limited/experimental tier: use only with explicit justification and easy rollback.

Documentation, Organization, And Formatting

Organization

• Split styles by role when codebase size justifies it:
  • styles/tokens.css
  • styles/base.css
  • styles/components/*.css
  • styles/utilities.css
• Keep component styles close to components when practical.
• Centralize global token definitions to reduce drift.

Documentation

• Add short comments for non-obvious intent, fallback rationale, or compatibility constraints.
• Document why partial-support features are used.
• Keep comments focused on why, not what.

Formatting

• Keep property ordering logical:
  1. Layout (display, position, grid/flex, z-index)
  2. Box model (inline-size/block-size, margin, padding, border)
  3. Typography (font-*, line-height, text-*)
  4. Visual (background, color, box-shadow, opacity, filter)
  5. Motion (transform, transition, animation)
• Use consistent spacing and alignment.
• Prefer small, single-purpose selector blocks.

Completion Checklist

• Token model is defined and mapped cleanly into CSS custom properties.
• Hard-coded values are minimized and justified when present.
• Layer order is explicit and vendor CSS is isolated.
• Nesting is shallow and readable.
• Container queries and modern selectors are used where they simplify code.
• Accessibility states include :focus-visible and motion preferences are respected.
• Enhancement and limited features are gated with fallbacks.
• Comments are concise and intent-focused.