/* ============================================================================
 * Layer 2 — Utility Classes
 * ----------------------------------------------------------------------------
 * ui/static/css/utilities.css
 *
 * Single-purpose, atomic helper classes for layout, spacing, and typography.
 * Every primitive value MUST be a var(--token-name) reference from tokens.css.
 * No raw hex codes, rems, or magic numbers are permitted in this file.
 *
 * Usage: append one or more of these classes to a semantic element. The
 * semantic class names in components.css describe WHAT the element is; the
 * utility classes here describe HOW it is positioned or styled in the
 * surrounding layout.
 *
 * Anti-pattern: do NOT construct bespoke one-off utility classes. If a layout
 * need is shared across two or more components, promote it to components.css.
 * ========================================================================== */

/* ------------------------------------------------------------------------
 * Display
 * ---------------------------------------------------------------------- */
.flex { display: flex; }
.grid { display: grid; }
.hidden { display: none; }
.block { display: block; }
.inline-block { display: inline-block; }

/* ------------------------------------------------------------------------
 * Flex helpers
 * ---------------------------------------------------------------------- */
.flex-wrap { flex-wrap: wrap; }
.items-center { align-items: center; }
.justify-between { justify-content: space-between; }
.justify-center { justify-content: center; }

/* ------------------------------------------------------------------------
 * Gap (for flex and grid containers)
 * ---------------------------------------------------------------------- */
.gap-1 { gap: var(--spacing-1); }
.gap-2 { gap: var(--spacing-2); }
.gap-3 { gap: var(--spacing-3); }
.gap-4 { gap: var(--spacing-4); }

/* ------------------------------------------------------------------------
 * Spacing — margin-top
 * ---------------------------------------------------------------------- */
.mt-1 { margin-top: var(--spacing-1); }
.mt-2 { margin-top: var(--spacing-2); }
.mt-3 { margin-top: var(--spacing-3); }
.mt-4 { margin-top: var(--spacing-4); }

/* ------------------------------------------------------------------------
 * Spacing — margin-bottom
 * ---------------------------------------------------------------------- */
.mb-1 { margin-bottom: var(--spacing-1); }
.mb-2 { margin-bottom: var(--spacing-2); }
.mb-3 { margin-bottom: var(--spacing-3); }
.mb-4 { margin-bottom: var(--spacing-4); }

/* ------------------------------------------------------------------------
 * Spacing — uniform padding
 * ---------------------------------------------------------------------- */
.p-1 { padding: var(--spacing-1); }
.p-2 { padding: var(--spacing-2); }
.p-3 { padding: var(--spacing-3); }
.p-4 { padding: var(--spacing-4); }

/* ------------------------------------------------------------------------
 * Typography
 * ---------------------------------------------------------------------- */
.text-xs { font-size: var(--font-xs); }
.text-sm { font-size: var(--font-sm); }
.text-lg { font-size: var(--font-lg); }
.text-xl { font-size: var(--font-xl); }
.text-center { text-align: center; }
.text-right { text-align: right; }
.font-medium { font-weight: var(--font-weight-medium); }
.font-semibold { font-weight: var(--font-weight-semibold); }
.font-bold { font-weight: var(--font-weight-bold); }

/* ------------------------------------------------------------------------
 * Color utilities
 * ---------------------------------------------------------------------- */
.text-muted { color: var(--color-gray-500); }
.text-danger { color: var(--color-danger); }
.text-success { color: var(--color-success); }
.bg-white { background-color: var(--color-white); }
.bg-gray-50 { background-color: var(--color-gray-50); }

/* ------------------------------------------------------------------------
 * Width
 * ---------------------------------------------------------------------- */
.w-full { width: 100%; }

/* ------------------------------------------------------------------------
 * Container
 * ---------------------------------------------------------------------- */
.container { max-width: var(--container-max-width); margin: 0 auto; padding: 0 var(--spacing-4); }
.container-narrow { max-width: var(--container-narrow); margin: 0 auto; padding: 0 var(--spacing-4); }

/* ------------------------------------------------------------------------
 * Border radius
 * ---------------------------------------------------------------------- */
.rounded { border-radius: var(--radius-md); }
.rounded-lg { border-radius: var(--radius-lg); }

/* ------------------------------------------------------------------------
 * Shadows
 * ---------------------------------------------------------------------- */
.shadow-sm { box-shadow: var(--shadow-sm); }
.shadow-md { box-shadow: var(--shadow-md); }

/* ------------------------------------------------------------------------
 * Screen reader only — visually hidden, still announced by AT
 * ---------------------------------------------------------------------- */
.sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border: 0;
}