Responsive helpers

[minimaldesign]

Assessment

Worth doing at a deliberately small scope. Decided at review (2026-07-17): ship responsive variants for a small, high-value helper set only — full Tailwind-style coverage would balloon the CSS while PurgeCSS is disabled (see the companion PurgeCSS re-evaluation issue). Naming: plain suffix style (.display-none-md), matching the framework's existing kebab/property-prefixed helper names (.of-auto, .position-sticky). Notable: the framework currently has no display helpers at all (help.layout.css covers overflow/position/visibility/z-index only), so those get added as part of this. Effort: M.

Implementation plan

1. Base display helpers (new)

In src/styles/framework/help.layout.css (already imported layer(helpers) in mcss.css — no import changes needed), add a DISPLAY section following the existing long-form naming:

.display-none, .display-block, .display-inline, .display-inline-block, .display-flex, .display-grid (+ short aliases .d-none etc., mirroring the .of-*/.overflow-* alias pattern). Property-prefixed names dodge the .grid class collision with the grid system.

2. Responsive variants

• Semantics: mobile-first. A -{bp} suffix applies at that breakpoint and above, using the existing @custom-media tokens from settings.media-queries.css (--sm ≥480px, --md ≥768px, --lg ≥1024px).
• Breakpoints: sm, md, lg only (not all 7) to keep output small.
• Covered helpers:
  • all display helpers above → .display-none-md, .display-flex-lg, … (18 rules)
  • text-align helpers in help.typography.css → .text-center-md, .text-start-lg, … (~15 rules)
• Down-direction needs no extra classes: class="display-none display-block-md" hides below md. Document this idiom.
• Order matters within the file: emit @media blocks in ascending breakpoint order after the base classes so larger breakpoints win at equal specificity.

3. Explicitly out of scope

Responsive spacing/color/opacity helpers. If real needs emerge, revisit after PurgeCSS is re-enabled (companion issue) — that changes the size calculus entirely. The grid system already has its own responsive story (col/span attributes + #10).

4. Docs & verification

• src/content/docs/helpers.mdx: new "Responsive helpers" section — naming rule, mobile-first semantics, the hide/show idiom, and a note on how consumers can generate more variants themselves in their own layer.
• agents/css.md: record the -{bp} suffix convention.
• Future-proofing: suffix names are plain strings (no escaping), and a single safelist regex /-(sm|md|lg)$/ covers them when PurgeCSS returns.
• Verify: dev server, resize across 480/768/1024 — variants flip at the right widths; confirm helpers still beat component styles (helpers is the last layer).