/* ============================================================================
 * Manifold utility-class CSS layer — Phase 16, Plan 02 (CSS-01 + CSS-02)
 * ----------------------------------------------------------------------------
 * HAND-AUTHORED — codegen does not own this file. tools/build_tokens.py only
 * touches the @manifold-tokens:start/end sentinel blocks inside each
 * theme.css. This file is hand-edited; bump the ?v= cache-buster in
 * core/dashboard/index.html whenever you change anything below.
 *
 * Contract — reads vars, never declares them.
 *   Every aesthetic value in this file routes through `var(--mt-*)`
 *   (the theme-owned token surface from Phase 15) or `var(--m-radius-*)`
 *   (legacy-but-canonical per PROJECT.md 2026-05-15 naming lock).
 *   This file MUST NOT declare any `--mt-*` / `--m-*` variable itself —
 *   that would shadow the theme.css definition and silently break the
 *   theme-switch contract. Grep gate (Plan 16-03 / 16-02 pytest):
 *     grep -E '^\s*--' core/dashboard/lib/utilities.css   # must be empty
 *     grep -E '#[0-9a-fA-F]{3,8}' core/dashboard/lib/utilities.css  # empty
 *
 * Cascade — loaded BEFORE every theme.css.
 *   core/dashboard/index.html links this file IMMEDIATELY ABOVE the
 *   default theme.css <link>. Non-default themes inject via
 *   themes.js::_loadCss() at runtime; those always land after this file
 *   in document order. The theme.css `:root[data-theme="..."]` blocks
 *   redefine `--mt-*` vars; cascade carries those values down to every
 *   element carrying a `mt-*` class.
 *
 * Adding a new utility class:
 *   1. Confirm the corresponding --mt-* var exists in design-tokens/_base.json
 *      AND emits into every theme.css sentinel block via tools/build_tokens.py.
 *      If it does not, add the token first (a separate plan).
 *   2. Add the class here, grouped under its category banner below.
 *   3. Add a row to docs/css-utility-classes.md (Plan 16-05).
 *   4. Bump the ?v= cache-buster on the index.html <link> tag.
 *
 * Radius classes — deliberate naming deviation.
 *   The 8 LOCKED categories include radius. Per PROJECT.md 2026-05-15,
 *   `--m-radius-{sm,md,lg,full}` is the canonical name for corner-radius
 *   tokens; Phase 16 TOKEN-BACKFILL (Plan 16-01) explicitly does NOT
 *   rename them to `--mt-radius-*`. So `mt-radius-*` classes read
 *   `var(--m-radius-*)` — this is intentional. Plan 16-05's
 *   docs/css-utility-classes.md calls this out.
 *
 * Layout helpers — no var refs.
 *   mt-flex / mt-flex-col / mt-items-center / etc. carry no aesthetic
 *   meaning (display/flex-direction/alignment is structural, not
 *   theme-skinnable). They keep the `mt-` prefix so the namespace stays
 *   uniform but consume no CSS vars.
 *
 * Categories (LOCKED in SPEC R1):
 *   1. background      — bg, bg-deep, bg-elev
 *   2. text color      — text, text-muted, text-dim, text-accent,
 *                        text-live, text-warn, text-error
 *   3. text size       — text-{xs,sm,md,lg,xl,2xl,3xl}
 *   4. text weight     — weight-{regular,medium,semibold,bold}
 *   5. border          — border, border-strong, border-none
 *   6. radius          — radius-{none,sm,md,lg,full}
 *   7. space           — pad-{xs,sm,md,lg,xl}, m-{xs,sm,md,lg}, gap-{xs,sm,md,lg}
 *   8. layout helpers  — flex, flex-{col,row}, items-{center,baseline},
 *                        justify-{center,between}
 *
 * Omitted from RESEARCH.md catalog:
 *   - `mt-bg-surface` — SPEC R1 lists it but `--mt-bg-surface` does not
 *     exist in any theme.css sentinel block today (verified by grep).
 *     A class that resolves to nothing is worse than no class at all
 *     (silent layout collapse on any element carrying it). Omitted until
 *     a future plan adds the token to design-tokens/_base.json.
 * ============================================================================
 */

/* === Background ============================================================ */

.mt-bg              { background-color: var(--mt-bg); }
.mt-bg-deep         { background-color: var(--mt-bg-deep); }
.mt-bg-elev         { background-color: var(--mt-bg-elev); }
.mt-bg-transparent  { background: transparent; }

/* === Text color ============================================================ */

.mt-text         { color: var(--mt-fg); }
.mt-text-muted   { color: var(--mt-muted); }
.mt-text-dim     { color: var(--mt-dim); }
.mt-text-accent  { color: var(--mt-accent); }
.mt-text-live    { color: var(--mt-live); }
.mt-text-warn    { color: var(--mt-warn); }
.mt-text-error   { color: var(--mt-error); }

/* === Text size — font-size + line-height paired per Phase 15 scale ========= */

.mt-text-xs  { font-size: var(--mt-text-xs-size);  line-height: var(--mt-text-xs-lh); }
.mt-text-sm  { font-size: var(--mt-text-sm-size);  line-height: var(--mt-text-sm-lh); }
.mt-text-md  { font-size: var(--mt-text-md-size);  line-height: var(--mt-text-md-lh); }
.mt-text-lg  { font-size: var(--mt-text-lg-size);  line-height: var(--mt-text-lg-lh); }
.mt-text-xl  { font-size: var(--mt-text-xl-size);  line-height: var(--mt-text-xl-lh); }
.mt-text-2xl { font-size: var(--mt-text-2xl-size); line-height: var(--mt-text-2xl-lh); }
.mt-text-3xl { font-size: var(--mt-text-3xl-size); line-height: var(--mt-text-3xl-lh); }

/* === Text weight — vars land via Plan 16-01 (same wave) =================== */

.mt-weight-regular   { font-weight: var(--mt-weight-regular); }
.mt-weight-medium    { font-weight: var(--mt-weight-medium); }
.mt-weight-semibold  { font-weight: var(--mt-weight-semibold); }
.mt-weight-bold      { font-weight: var(--mt-weight-bold); }

/* === Border =============================================================== */

.mt-border         { border: 1px solid var(--mt-border); }
.mt-border-strong  { border: 1px solid var(--mt-border-strong); }
.mt-border-none    { border: none; }

/* === Radius — deliberate var(--m-radius-*) deviation (see header) ========= */

.mt-radius-none  { border-radius: 0; }
.mt-radius-sm    { border-radius: var(--m-radius-sm); }
.mt-radius-md    { border-radius: var(--m-radius-md); }
.mt-radius-lg    { border-radius: var(--m-radius-lg); }
.mt-radius-full  { border-radius: var(--m-radius-full); }

/* === Space — padding (vars land via Plan 16-01) ========================== */

.mt-pad-0   { padding: 0; }
.mt-pad-xs  { padding: var(--mt-space-xs); }
.mt-pad-sm  { padding: var(--mt-space-sm); }
.mt-pad-md  { padding: var(--mt-space-md); }
.mt-pad-lg  { padding: var(--mt-space-lg); }
.mt-pad-xl  { padding: var(--mt-space-xl); }

/* === Space — margin ======================================================= */

.mt-m-xs  { margin: var(--mt-space-xs); }
.mt-m-sm  { margin: var(--mt-space-sm); }
.mt-m-md  { margin: var(--mt-space-md); }
.mt-m-lg  { margin: var(--mt-space-lg); }

/* === Space — gap (applies to flex / grid containers) ===================== */

.mt-gap-xs  { gap: var(--mt-space-xs); }
.mt-gap-sm  { gap: var(--mt-space-sm); }
.mt-gap-md  { gap: var(--mt-space-md); }
.mt-gap-lg  { gap: var(--mt-space-lg); }

/* === Space — axis-specific margin (Phase 16-04 / W3.1 expansion) =========
 * Added during Plan 16-04 to support sites with single-axis margins. The
 * proof-slice expansion across confirm-modal/branding-modal/section-editor
 * surfaced 33 single-axis margin/padding violations that all-axis utilities
 * cannot represent without visual creep. Each class reads --mt-space-* so
 * theme-skin cascade still routes through the locked token surface.
 * ========================================================================= */

.mt-mt-0   { margin-top: 0; }
.mt-mt-xs  { margin-top: var(--mt-space-xs); }
.mt-mt-sm  { margin-top: var(--mt-space-sm); }
.mt-mt-md  { margin-top: var(--mt-space-md); }
.mt-mt-lg  { margin-top: var(--mt-space-lg); }
.mt-mt-xl  { margin-top: var(--mt-space-xl); }

.mt-mb-0   { margin-bottom: 0; }
.mt-mb-xs  { margin-bottom: var(--mt-space-xs); }
.mt-mb-sm  { margin-bottom: var(--mt-space-sm); }
.mt-mb-md  { margin-bottom: var(--mt-space-md); }
.mt-mb-lg  { margin-bottom: var(--mt-space-lg); }
.mt-mb-xl  { margin-bottom: var(--mt-space-xl); }

.mt-ml-xs  { margin-left: var(--mt-space-xs); }
.mt-ml-sm  { margin-left: var(--mt-space-sm); }
.mt-ml-md  { margin-left: var(--mt-space-md); }
.mt-ml-lg  { margin-left: var(--mt-space-lg); }
.mt-ml-xl  { margin-left: var(--mt-space-xl); }

.mt-mr-xs  { margin-right: var(--mt-space-xs); }
.mt-mr-sm  { margin-right: var(--mt-space-sm); }
.mt-mr-md  { margin-right: var(--mt-space-md); }
.mt-mr-lg  { margin-right: var(--mt-space-lg); }
.mt-mr-xl  { margin-right: var(--mt-space-xl); }

/* === Space — axis-specific padding (Phase 16-04 / W3.1 expansion) ========= */

.mt-pt-xs  { padding-top: var(--mt-space-xs); }
.mt-pt-sm  { padding-top: var(--mt-space-sm); }
.mt-pt-md  { padding-top: var(--mt-space-md); }
.mt-pt-lg  { padding-top: var(--mt-space-lg); }
.mt-pt-xl  { padding-top: var(--mt-space-xl); }

.mt-pb-xs  { padding-bottom: var(--mt-space-xs); }
.mt-pb-sm  { padding-bottom: var(--mt-space-sm); }
.mt-pb-md  { padding-bottom: var(--mt-space-md); }
.mt-pb-lg  { padding-bottom: var(--mt-space-lg); }
.mt-pb-xl  { padding-bottom: var(--mt-space-xl); }

.mt-pl-xs  { padding-left: var(--mt-space-xs); }
.mt-pl-sm  { padding-left: var(--mt-space-sm); }
.mt-pl-md  { padding-left: var(--mt-space-md); }
.mt-pl-lg  { padding-left: var(--mt-space-lg); }
.mt-pl-xl  { padding-left: var(--mt-space-xl); }

.mt-pr-xs  { padding-right: var(--mt-space-xs); }
.mt-pr-sm  { padding-right: var(--mt-space-sm); }
.mt-pr-md  { padding-right: var(--mt-space-md); }
.mt-pr-lg  { padding-right: var(--mt-space-lg); }
.mt-pr-xl  { padding-right: var(--mt-space-xl); }

/* === Layout helpers — pure layout, no aesthetic meaning =================== */

.mt-flex             { display: flex; }
.mt-flex-col         { flex-direction: column; }
.mt-flex-row         { flex-direction: row; }
.mt-items-center     { align-items: center; }
.mt-items-baseline   { align-items: baseline; }
.mt-justify-center   { justify-content: center; }
.mt-justify-between  { justify-content: space-between; }

/* === Text alignment — structural, no token consumption (Phase 19-02) =====
 * Added Phase 19 Plan 02 to give the 93 inline `textAlign` sites a utility
 * home. text-align is structural (not theme-skinnable), so no --mt-text-align-*
 * token is needed — these read no CSS variables, matching the layout-helper
 * pattern (.mt-flex, .mt-items-center). Adding a token + redefining it across
 * 4 themes would expand Phase 15's surface for no design benefit.
 * ========================================================================= */

.mt-text-left    { text-align: left; }
.mt-text-center  { text-align: center; }
.mt-text-right   { text-align: right; }