/* ========================================================================
   vc-utilities.css — ATOMIC HELPERS
   RetirePlusPlus Investor Module ($30M Series B)

   Single-purpose utility classes so page agents can replace one-off inline
   style="" attributes (CSP §4) and bespoke pd-*/app-*/il-* helper classes
   with shared, token-driven utilities.

   All values reference vc-tokens.css semantic/scale tokens — NO raw hex here.
   LOAD ORDER: after vc-components.css, before vc-charts.css / page CSS.
   ======================================================================== */

/* ========================================================================
   1. ACCESSIBILITY HELPERS
   ======================================================================== */

/* Visually hide but keep available to assistive tech (SR-only). The
   canonical accessible text for chart/diagram alternatives & matrix glyphs. */
.visually-hidden,
.sr-only {
  position: absolute !important;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

/* Becomes visible when focused (skip-links). */
.visually-hidden-focusable:not(:focus):not(:focus-within) {
  position: absolute !important;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

/* ========================================================================
   2. PRINT / SCREEN VISIBILITY
   ======================================================================== */
@media print {
  .no-print { display: none !important; }
}
.print-only { display: none; }
@media print {
  .print-only { display: revert !important; }
}

/* ========================================================================
   3. DISPLAY
   ======================================================================== */
.d-none         { display: none !important; }
.d-block        { display: block; }
.d-inline       { display: inline; }
.d-inline-block { display: inline-block; }
.d-flex         { display: flex; }
.d-inline-flex  { display: inline-flex; }
.d-grid         { display: grid; }

/* [hidden] is the canonical CSP-clean toggle (setAttribute('hidden')). */
[hidden] { display: none !important; }

/* ========================================================================
   4. FLEXBOX
   ======================================================================== */
.flex             { display: flex; }
.inline-flex      { display: inline-flex; }
.flex-row         { flex-direction: row; }
.flex-col         { flex-direction: column; }
.flex-wrap        { flex-wrap: wrap; }
.flex-nowrap      { flex-wrap: nowrap; }
.flex-1           { flex: 1 1 0%; }
.flex-auto        { flex: 1 1 auto; }
.flex-none        { flex: none; }
.grow             { flex-grow: 1; }
.shrink-0         { flex-shrink: 0; }

.items-start      { align-items: flex-start; }
.items-center     { align-items: center; }
.items-end        { align-items: flex-end; }
.items-stretch    { align-items: stretch; }
.items-baseline   { align-items: baseline; }

.justify-start    { justify-content: flex-start; }
.justify-center   { justify-content: center; }
.justify-end      { justify-content: flex-end; }
.justify-between  { justify-content: space-between; }
.justify-around   { justify-content: space-around; }

.self-start       { align-self: flex-start; }
.self-center      { align-self: center; }
.self-end         { align-self: flex-end; }

/* ========================================================================
   5. GRID
   ======================================================================== */
.grid             { display: grid; }
.grid-cols-1      { grid-template-columns: repeat(1, minmax(0, 1fr)); }
.grid-cols-2      { grid-template-columns: repeat(2, minmax(0, 1fr)); }
.grid-cols-3      { grid-template-columns: repeat(3, minmax(0, 1fr)); }
.grid-cols-4      { grid-template-columns: repeat(4, minmax(0, 1fr)); }
.grid-cols-6      { grid-template-columns: repeat(6, minmax(0, 1fr)); }
.grid-cols-12     { grid-template-columns: repeat(12, minmax(0, 1fr)); }

/* Auto-fit responsive grids (reflow without media queries) */
.grid-auto-sm     { grid-template-columns: repeat(auto-fit, minmax(11rem, 1fr)); }
.grid-auto-md     { grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr)); }
.grid-auto-lg     { grid-template-columns: repeat(auto-fit, minmax(18.75rem, 1fr)); }

.col-span-1       { grid-column: span 1 / span 1; }
.col-span-2       { grid-column: span 2 / span 2; }
.col-span-3       { grid-column: span 3 / span 3; }
.col-span-4       { grid-column: span 4 / span 4; }
.col-span-6       { grid-column: span 6 / span 6; }
.col-span-full    { grid-column: 1 / -1; }

/* 12-col content grid collapses to 1-col under 48rem */
@media (max-width: 48rem) {
  .grid-cols-2,
  .grid-cols-3,
  .grid-cols-4,
  .grid-cols-6,
  .grid-cols-12 { grid-template-columns: minmax(0, 1fr); }
  .col-span-1,
  .col-span-2,
  .col-span-3,
  .col-span-4,
  .col-span-6 { grid-column: 1 / -1; }
}

/* ========================================================================
   6. GAP (8-pt scale)
   ======================================================================== */
.gap-0   { gap: var(--space-0); }
.gap-1   { gap: var(--space-1); }
.gap-2   { gap: var(--space-2); }
.gap-3   { gap: var(--space-3); }
.gap-4   { gap: var(--space-4); }
.gap-5   { gap: var(--space-5); }
.gap-6   { gap: var(--space-6); }
.gap-8   { gap: var(--space-8); }
.gap-10  { gap: var(--space-10); }
.gap-12  { gap: var(--space-12); }
.gap-x-2 { column-gap: var(--space-2); }
.gap-x-4 { column-gap: var(--space-4); }
.gap-x-6 { column-gap: var(--space-6); }
.gap-y-2 { row-gap: var(--space-2); }
.gap-y-4 { row-gap: var(--space-4); }
.gap-y-6 { row-gap: var(--space-6); }

/* ========================================================================
   7. MARGIN (8-pt scale)
   ======================================================================== */
.m-0    { margin: var(--space-0); }
.m-auto { margin: auto; }
.mx-auto { margin-left: auto; margin-right: auto; }

.mt-0  { margin-top: var(--space-0); }
.mt-1  { margin-top: var(--space-1); }
.mt-2  { margin-top: var(--space-2); }
.mt-3  { margin-top: var(--space-3); }
.mt-4  { margin-top: var(--space-4); }
.mt-5  { margin-top: var(--space-5); }
.mt-6  { margin-top: var(--space-6); }
.mt-8  { margin-top: var(--space-8); }
.mt-10 { margin-top: var(--space-10); }
.mt-12 { margin-top: var(--space-12); }
.mt-16 { margin-top: var(--space-16); }

.mb-0  { margin-bottom: var(--space-0); }
.mb-1  { margin-bottom: var(--space-1); }
.mb-2  { margin-bottom: var(--space-2); }
.mb-3  { margin-bottom: var(--space-3); }
.mb-4  { margin-bottom: var(--space-4); }
.mb-5  { margin-bottom: var(--space-5); }
.mb-6  { margin-bottom: var(--space-6); }
.mb-8  { margin-bottom: var(--space-8); }
.mb-10 { margin-bottom: var(--space-10); }
.mb-12 { margin-bottom: var(--space-12); }
.mb-16 { margin-bottom: var(--space-16); }

.ml-1  { margin-left: var(--space-1); }
.ml-2  { margin-left: var(--space-2); }
.ml-3  { margin-left: var(--space-3); }
.ml-4  { margin-left: var(--space-4); }
.ml-auto { margin-left: auto; }

.mr-1  { margin-right: var(--space-1); }
.mr-2  { margin-right: var(--space-2); }
.mr-3  { margin-right: var(--space-3); }
.mr-4  { margin-right: var(--space-4); }
.mr-auto { margin-right: auto; }

.my-0  { margin-top: var(--space-0); margin-bottom: var(--space-0); }
.my-2  { margin-top: var(--space-2); margin-bottom: var(--space-2); }
.my-4  { margin-top: var(--space-4); margin-bottom: var(--space-4); }
.my-6  { margin-top: var(--space-6); margin-bottom: var(--space-6); }
.my-8  { margin-top: var(--space-8); margin-bottom: var(--space-8); }
.my-12 { margin-top: var(--space-12); margin-bottom: var(--space-12); }

/* ========================================================================
   8. PADDING (8-pt scale)
   ======================================================================== */
.p-0  { padding: var(--space-0); }
.p-1  { padding: var(--space-1); }
.p-2  { padding: var(--space-2); }
.p-3  { padding: var(--space-3); }
.p-4  { padding: var(--space-4); }
.p-5  { padding: var(--space-5); }
.p-6  { padding: var(--space-6); }
.p-8  { padding: var(--space-8); }
.p-10 { padding: var(--space-10); }
.p-12 { padding: var(--space-12); }

.pt-0  { padding-top: var(--space-0); }
.pt-2  { padding-top: var(--space-2); }
.pt-4  { padding-top: var(--space-4); }
.pt-6  { padding-top: var(--space-6); }
.pt-8  { padding-top: var(--space-8); }
.pt-12 { padding-top: var(--space-12); }

.pb-0  { padding-bottom: var(--space-0); }
.pb-2  { padding-bottom: var(--space-2); }
.pb-4  { padding-bottom: var(--space-4); }
.pb-6  { padding-bottom: var(--space-6); }
.pb-8  { padding-bottom: var(--space-8); }
.pb-12 { padding-bottom: var(--space-12); }

.pl-2  { padding-left: var(--space-2); }
.pl-4  { padding-left: var(--space-4); }
.pl-6  { padding-left: var(--space-6); }

.pr-2  { padding-right: var(--space-2); }
.pr-4  { padding-right: var(--space-4); }
.pr-6  { padding-right: var(--space-6); }

.px-2  { padding-left: var(--space-2); padding-right: var(--space-2); }
.px-4  { padding-left: var(--space-4); padding-right: var(--space-4); }
.px-6  { padding-left: var(--space-6); padding-right: var(--space-6); }
.px-8  { padding-left: var(--space-8); padding-right: var(--space-8); }

.py-2  { padding-top: var(--space-2); padding-bottom: var(--space-2); }
.py-4  { padding-top: var(--space-4); padding-bottom: var(--space-4); }
.py-6  { padding-top: var(--space-6); padding-bottom: var(--space-6); }
.py-8  { padding-top: var(--space-8); padding-bottom: var(--space-8); }
.py-12 { padding-top: var(--space-12); padding-bottom: var(--space-12); }

/* Section vertical rhythm helper (uses responsive --section-y token) */
.section-y { padding-top: var(--section-y); padding-bottom: var(--section-y); }

/* ========================================================================
   9. WIDTH / LAYOUT CONTAINERS
   ======================================================================== */
.w-full       { width: 100%; }
.w-auto       { width: auto; }
.max-w-prose  { max-width: var(--max-width-prose); }
.max-w        { max-width: var(--max-width); }
.max-w-wide   { max-width: var(--max-width-wide); }
.h-full       { height: 100%; }

/* ========================================================================
   10. TEXT
   ======================================================================== */
.text-left    { text-align: left; }
.text-center  { text-align: center; }
.text-right   { text-align: right; }

.text-2xs  { font-size: var(--fs-2xs); }
.text-xs   { font-size: var(--fs-xs); }
.text-sm   { font-size: var(--fs-sm); }
.text-base { font-size: var(--fs-base); }
.text-lg   { font-size: var(--fs-lg); }
.text-xl   { font-size: var(--fs-xl); }
.text-2xl  { font-size: var(--fs-2xl); }
.text-3xl  { font-size: var(--fs-3xl); }
.text-4xl  { font-size: var(--fs-4xl); }

.font-light    { font-weight: var(--fw-light); }
.font-regular  { font-weight: var(--fw-regular); }
.font-medium   { font-weight: var(--fw-medium); }
.font-semibold { font-weight: var(--fw-semibold); }
.font-bold     { font-weight: var(--fw-bold); }
.font-extrabold { font-weight: var(--fw-extrabold); }

.font-display { font-family: var(--font-display); }
.font-ui      { font-family: var(--font-ui); }
.font-data    { font-family: var(--font-data); }
.font-mono    { font-family: var(--font-mono); }

.uppercase    { text-transform: uppercase; }
.capitalize   { text-transform: capitalize; }
.italic       { font-style: italic; }
.leading-tight  { line-height: var(--lh-heading); }
.leading-normal { line-height: var(--lh-body); }
.tracking-eyebrow { letter-spacing: var(--ls-eyebrow); }
.truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

/* All numeric figures: tabular-nums for stable column alignment (spec §4). */
.tabular-nums,
.figure { font-variant-numeric: tabular-nums; }

/* ========================================================================
   11. TEXT COLOR HELPERS (semantic roles only — theme-aware)
   ======================================================================== */
.text-primary    { color: var(--text-primary); }
.text-secondary  { color: var(--text-secondary); }
.text-muted      { color: var(--text-muted); }
.text-on-brand   { color: var(--text-on-brand); }
.text-accent     { color: var(--accent-primary); }
.text-accent-secondary { color: var(--accent-secondary); }
.text-accent-tertiary  { color: var(--accent-tertiary); }
.text-partner    { color: var(--accent-partner); }
/* Status-as-text helpers use the theme-aware --status-*-text variants (not the
   saturated --status-* FILLS), so they clear WCAG 1.4.3 (4.5:1) wherever applied
   as body/label text in either theme. Raw fills stay for borders/bg/icons. */
.text-success    { color: var(--status-success-text); }
.text-warning    { color: var(--status-warning-text); }
.text-error      { color: var(--status-error-text); }
.text-info       { color: var(--status-info-text); }

/* ========================================================================
   12. SURFACE / BACKGROUND HELPERS (theme-aware)
   On dark, elevated surfaces also get a hairline border (shadow alone is
   invisible on near-black) — see .elevated below.
   ======================================================================== */
.bg-canvas    { background-color: var(--bg-canvas); }
.bg-surface   { background-color: var(--bg-surface); }
.bg-surface-2 { background-color: var(--bg-surface-2); }
.bg-inset     { background-color: var(--bg-inset); }
.bg-elevated  { background-color: var(--bg-elevated); }
.bg-brand     { background-color: var(--bg-brand); color: var(--text-on-brand); }

.grad-brand   { background-image: var(--grad-brand); }
.grad-growth  { background-image: var(--grad-growth); }
.grad-ai      { background-image: var(--grad-ai); }
.grad-partner { background-image: var(--grad-partner); }
.grad-hero    { background-image: var(--grad-hero); }
.grad-accent-line { background-image: var(--grad-accent-line); }

/* ========================================================================
   13. BORDERS / RADII / SHADOWS / ELEVATION
   ======================================================================== */
.border        { border: 1px solid var(--border-subtle); }
.border-strong { border: 1px solid var(--border-strong); }
.border-brand  { border: 1px solid var(--border-brand); }
.border-top    { border-top: 1px solid var(--border-subtle); }
.border-0      { border: 0; }

.rounded-sm  { border-radius: var(--radius-sm); }
.rounded-md  { border-radius: var(--radius-md); }
.rounded-lg  { border-radius: var(--radius-lg); }
.rounded-xl  { border-radius: var(--radius-xl); }
.rounded-2xl { border-radius: var(--radius-2xl); }
.rounded-pill { border-radius: var(--radius-pill); }

.shadow-sm { box-shadow: var(--shadow-sm); }
.shadow-md { box-shadow: var(--shadow-md); }
.shadow-lg { box-shadow: var(--shadow-lg); }
.shadow-xl { box-shadow: var(--shadow-xl); }

/* Elevated card: on dark, add the hairline border that reads as elevation. */
.elevated {
  background-color: var(--bg-surface);
  box-shadow: var(--shadow-md);
}
[data-theme="dark"] .elevated {
  border: 1px solid var(--border-subtle);
}

/* ========================================================================
   14. CHART HEIGHT HELPERS (reserve canvas height — no inline style="height:")
   Prevents layout shift (design §10); page agents pick a height class.
   ======================================================================== */
.chart-h-xs { height: 12rem; }
.chart-h-sm { height: 16rem; }
.chart-h-md { height: 20rem; }
.chart-h-lg { height: 24rem; }
.chart-h-xl { height: 30rem; }

/* ========================================================================
   15. POSITION / OVERFLOW
   ======================================================================== */
.relative   { position: relative; }
.absolute   { position: absolute; }
.fixed      { position: fixed; }
.sticky     { position: sticky; }
.inset-0    { top: 0; right: 0; bottom: 0; left: 0; }
.overflow-hidden { overflow: hidden; }
.overflow-x-auto { overflow-x: auto; }
.overflow-auto   { overflow: auto; }

/* ========================================================================
   16. REDUCED MOTION (global guard; component-level pauses live in
       component CSS). Pages inherit this regardless of which page CSS loads.
   ======================================================================== */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}