/* =============================================================================
   UTILITIES — the LAST resort, highest layer (wins over components).
   Keep this set TINY and generic. If you reach for a utility three times for
   the same intent, that intent belongs in a component or a layout primitive.
   No Tailwind-style sprawl. No color utilities (color = status = component).
   ========================================================================== */

@layer utilities {
  /* The `hidden` attribute is authoritative. A component's `display` (e.g.
     .btn{display:inline-flex}, .push-banner{display:flex}) lives in the lower
     `components` layer, so without this an element JS hides via `hidden` would
     stay visible. Declaring it in the top layer wins by cascade order — no
     !important, no per-component guard. Stimulus controllers across the app
     toggle `el.hidden` and rely on this. */
  [hidden] { display: none; }

  /* Accessibility: visually hide but keep for screen readers. */
  .visually-hidden:not(:focus):not(:focus-within) {
    position: absolute !important;
    inline-size: 1px; block-size: 1px;
    padding: 0; margin: -1px;
    overflow: hidden; clip: rect(0 0 0 0); clip-path: inset(50%);
    white-space: nowrap; border: 0;
  }

  .skip-link {
    position: absolute; inset-block-start: var(--space-xs); inset-inline-start: var(--space-xs);
    z-index: var(--z-overlay); padding: var(--space-xs) var(--space-md);
    background: var(--surface-raised); border-radius: var(--radius-md); box-shadow: var(--shadow-md);
    transform: translateY(-150%);
  }
  .skip-link:focus { transform: none; }

  .text-muted  { color: var(--color-text-muted); }
  .text-center { text-align: center; }
  .text-end    { text-align: end; }
  .truncate    { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }

  .hidden { display: none !important; }

  /* Spacing escape hatches — sparingly. */
  .mt-0 { margin-block-start: 0 !important; }
  .flow-tight { --stack-gap: var(--space-xs); }
  .flow-loose { --stack-gap: var(--space-xl); }
}