/* ============================================================================
   Alpha Branding Studio — Utilities
   assets/css/utilities.css
   ----------------------------------------------------------------------------
   Lightweight, single-purpose helper classes. Load LAST, after tokens.css,
   base.css, and layout.css.

   Contract:
   - Uses ONLY variables from tokens.css. No literal design values.
   - Single-responsibility helpers — no components, no buttons, no typography
     definitions (those live in base.css), no layout scaffolding (layout.css).
   - Mobile-first. Responsive variants are suffixed -md / -lg and only defined
     where a responsive override is genuinely useful.
   - Utilities may use limited, intentional !important to reliably override
     component styles at the call site (their purpose is to win).
   ============================================================================ */


/* ==========================================================================
   1. DISPLAY
   ========================================================================== */

.d-block        { display: block !important; }
.d-inline       { display: inline !important; }
.d-inline-block { display: inline-block !important; }
.d-flex         { display: flex !important; }
.d-inline-flex  { display: inline-flex !important; }
.d-grid         { display: grid !important; }
.d-none,
.hidden         { display: none !important; }

/* Responsive display variants (show/hide across breakpoints) */
@media (min-width: 768px) {
  .d-block-md  { display: block !important; }
  .d-flex-md   { display: flex !important; }
  .d-grid-md   { display: grid !important; }
  .d-none-md   { display: none !important; }
}

@media (min-width: 1024px) {
  .d-block-lg  { display: block !important; }
  .d-flex-lg   { display: flex !important; }
  .d-grid-lg   { display: grid !important; }
  .d-none-lg   { display: none !important; }
}


/* ==========================================================================
   2. VISIBILITY
   Visually-hidden preserves accessibility (SR-readable); .invisible only
   removes paint but keeps layout space.
   ========================================================================== */

.visually-hidden {
  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;
}

.invisible { visibility: hidden !important; }
.visible   { visibility: visible !important; }

/* Opacity helpers */
.opacity-0   { opacity: 0 !important; }
.opacity-25  { opacity: 0.25 !important; }
.opacity-50  { opacity: 0.5 !important; }
.opacity-75  { opacity: 0.75 !important; }
.opacity-100 { opacity: 1 !important; }


/* ==========================================================================
   3. TEXT
   Alignment, transform, wrapping, truncation. (Sizes/weights live in base.css.)
   ========================================================================== */

/* Alignment — logical where a keyword exists, physical for center/justify */
.text-start   { text-align: start !important; }
.text-center  { text-align: center !important; }
.text-end     { text-align: end !important; }
.text-justify { text-align: justify !important; }

/* Transform */
.text-uppercase  { text-transform: uppercase !important; }
.text-lowercase  { text-transform: lowercase !important; }
.text-capitalize { text-transform: capitalize !important; }
.text-normal-case{ text-transform: none !important; }

/* Wrapping / whitespace */
.text-nowrap  { white-space: nowrap !important; }
.text-wrap    { white-space: normal !important; }
.text-balance { text-wrap: balance !important; }
.text-pretty  { text-wrap: pretty !important; }
.text-break   {
  overflow-wrap: break-word !important;
  word-break: break-word !important;
  hyphens: auto;
}

/* Single-line truncation with ellipsis */
.text-truncate {
  overflow: hidden !important;
  text-overflow: ellipsis !important;
  white-space: nowrap !important;
}

/* Multi-line clamp (2 / 3 lines) */
.text-clamp-2,
.text-clamp-3 {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  overflow: hidden;
}
.text-clamp-2 { -webkit-line-clamp: 2; line-clamp: 2; }
.text-clamp-3 { -webkit-line-clamp: 3; line-clamp: 3; }

/* Responsive alignment */
@media (min-width: 768px) {
  .text-start-md  { text-align: start !important; }
  .text-center-md { text-align: center !important; }
  .text-end-md    { text-align: end !important; }
}


/* ==========================================================================
   4. SPACING
   Token-driven margin & padding. Scale keys map to --space-1..10.
   Naming: m/p + [t|b|s|e|x|y] + -{key}. (s = start, e = end, logical.)
   ========================================================================== */

/* ---- Margin (all sides) ---- */
.m-0 { margin: 0 !important; }
.m-1 { margin: var(--space-1) !important; }
.m-2 { margin: var(--space-2) !important; }
.m-3 { margin: var(--space-3) !important; }
.m-4 { margin: var(--space-4) !important; }
.m-5 { margin: var(--space-5) !important; }
.m-6 { margin: var(--space-6) !important; }
.m-7 { margin: var(--space-7) !important; }

/* ---- Margin block (top/bottom) ---- */
.my-0 { margin-block: 0 !important; }
.my-1 { margin-block: var(--space-1) !important; }
.my-2 { margin-block: var(--space-2) !important; }
.my-3 { margin-block: var(--space-3) !important; }
.my-4 { margin-block: var(--space-4) !important; }
.my-5 { margin-block: var(--space-5) !important; }
.my-6 { margin-block: var(--space-6) !important; }
.my-7 { margin-block: var(--space-7) !important; }

/* ---- Margin inline (start/end) ---- */
.mx-0    { margin-inline: 0 !important; }
.mx-1    { margin-inline: var(--space-1) !important; }
.mx-2    { margin-inline: var(--space-2) !important; }
.mx-3    { margin-inline: var(--space-3) !important; }
.mx-4    { margin-inline: var(--space-4) !important; }
.mx-5    { margin-inline: var(--space-5) !important; }
.mx-auto { margin-inline: auto !important; }

/* ---- Margin single edge (block-start / block-end) ---- */
.mt-0 { margin-block-start: 0 !important; }
.mt-2 { margin-block-start: var(--space-2) !important; }
.mt-3 { margin-block-start: var(--space-3) !important; }
.mt-4 { margin-block-start: var(--space-4) !important; }
.mt-5 { margin-block-start: var(--space-5) !important; }
.mt-6 { margin-block-start: var(--space-6) !important; }

.mb-0 { margin-block-end: 0 !important; }
.mb-2 { margin-block-end: var(--space-2) !important; }
.mb-3 { margin-block-end: var(--space-3) !important; }
.mb-4 { margin-block-end: var(--space-4) !important; }
.mb-5 { margin-block-end: var(--space-5) !important; }
.mb-6 { margin-block-end: var(--space-6) !important; }

/* Auto edges for flex/grid alignment */
.mt-auto { margin-block-start: auto !important; }
.mb-auto { margin-block-end: auto !important; }
.ms-auto { margin-inline-start: auto !important; }
.me-auto { margin-inline-end: auto !important; }

/* ---- Padding (all sides) ---- */
.p-0 { padding: 0 !important; }
.p-1 { padding: var(--space-1) !important; }
.p-2 { padding: var(--space-2) !important; }
.p-3 { padding: var(--space-3) !important; }
.p-4 { padding: var(--space-4) !important; }
.p-5 { padding: var(--space-5) !important; }
.p-6 { padding: var(--space-6) !important; }
.p-7 { padding: var(--space-7) !important; }

/* ---- Padding block (top/bottom) ---- */
.py-0 { padding-block: 0 !important; }
.py-1 { padding-block: var(--space-1) !important; }
.py-2 { padding-block: var(--space-2) !important; }
.py-3 { padding-block: var(--space-3) !important; }
.py-4 { padding-block: var(--space-4) !important; }
.py-5 { padding-block: var(--space-5) !important; }
.py-6 { padding-block: var(--space-6) !important; }
.py-7 { padding-block: var(--space-7) !important; }

/* ---- Padding inline (start/end) ---- */
.px-0 { padding-inline: 0 !important; }
.px-1 { padding-inline: var(--space-1) !important; }
.px-2 { padding-inline: var(--space-2) !important; }
.px-3 { padding-inline: var(--space-3) !important; }
.px-4 { padding-inline: var(--space-4) !important; }
.px-5 { padding-inline: var(--space-5) !important; }
.px-6 { padding-inline: var(--space-6) !important; }

/* ---- Padding single edge ---- */
.pt-0 { padding-block-start: 0 !important; }
.pt-4 { padding-block-start: var(--space-4) !important; }
.pt-5 { padding-block-start: var(--space-5) !important; }
.pt-6 { padding-block-start: var(--space-6) !important; }

.pb-0 { padding-block-end: 0 !important; }
.pb-4 { padding-block-end: var(--space-4) !important; }
.pb-5 { padding-block-end: var(--space-5) !important; }
.pb-6 { padding-block-end: var(--space-6) !important; }


/* ==========================================================================
   5. WIDTH & HEIGHT
   ========================================================================== */

.w-100  { inline-size: 100% !important; }
.w-auto { inline-size: auto !important; }
.w-fit  { inline-size: fit-content !important; }
.w-min  { inline-size: min-content !important; }
.w-max  { inline-size: max-content !important; }

.h-100  { block-size: 100% !important; }
.h-auto { block-size: auto !important; }
.h-screen {
  block-size: 100vh !important;
  block-size: 100svh !important;
}

.min-h-screen {
  min-block-size: 100vh !important;
  min-block-size: 100svh !important;
}

/* Max-width helpers mapped to reading measures + containers (tokens) */
.mw-100    { max-inline-size: 100% !important; }
.mw-measure{ max-inline-size: var(--measure) !important; }
.mw-narrow { max-inline-size: var(--measure-narrow) !important; }
.mw-wide   { max-inline-size: var(--measure-wide) !important; }
.mw-content{ max-inline-size: var(--container-max) !important; }


/* ==========================================================================
   6. POSITION
   ========================================================================== */

.position-relative { position: relative !important; }
.position-absolute { position: absolute !important; }
.position-fixed    { position: fixed !important; }
.position-sticky   { position: sticky !important; }
.position-static   { position: static !important; }

/* Sticky-to-top offset that clears the sticky header */
.sticky-top {
  position: sticky !important;
  inset-block-start: var(--header-height);
}

/* Inset helpers */
.inset-0 { inset: 0 !important; }
.top-0   { inset-block-start: 0 !important; }
.bottom-0{ inset-block-end: 0 !important; }


/* ==========================================================================
   7. BORDER RADIUS  (token values)
   ========================================================================== */

.rounded-none { border-radius: 0 !important; }
.rounded-sm   { border-radius: var(--radius-sm) !important; }
.rounded-md   { border-radius: var(--radius-md) !important; }
.rounded-lg   { border-radius: var(--radius-lg) !important; }
.rounded-xl   { border-radius: var(--radius-xl) !important; }
.rounded-pill { border-radius: var(--radius-pill) !important; }
.rounded-circle {
  border-radius: var(--radius-pill) !important;
  aspect-ratio: 1 / 1;
}


/* ==========================================================================
   8. SHADOWS  (token values)
   ========================================================================== */

.shadow-none { box-shadow: none !important; }
.shadow-xs   { box-shadow: var(--shadow-xs) !important; }
.shadow-sm   { box-shadow: var(--shadow-sm) !important; }
.shadow-md   { box-shadow: var(--shadow-md) !important; }
.shadow-lg   { box-shadow: var(--shadow-lg) !important; }


/* ==========================================================================
   9. BACKGROUND HELPERS
   Brand surfaces. Ink/Graphite set a legible foreground so text on dark
   fills stays readable without extra classes.
   ========================================================================== */

.bg-ink {
  background-color: var(--color-ink) !important;
  color: var(--text-on-dark) !important;
}
.bg-graphite {
  background-color: var(--color-graphite) !important;
  color: var(--text-on-dark) !important;
}
.bg-paper   { background-color: var(--color-paper) !important; }
.bg-bone    { background-color: var(--color-bone) !important; }
.bg-ash     { background-color: var(--color-ash) !important; }
.bg-flare {
  background-color: var(--color-flare) !important;
  color: var(--color-bone) !important;
}
.bg-flare-wash { background-color: var(--accent-wash) !important; }
.bg-transparent{ background-color: transparent !important; }


/* ==========================================================================
   10. COLOR HELPERS  (text color)
   ========================================================================== */

.text-ink       { color: var(--color-ink) !important; }
.text-graphite  { color: var(--color-graphite) !important; }
.text-stone     { color: var(--color-stone) !important; }
.text-paper     { color: var(--color-paper) !important; }
.text-flare     { color: var(--color-flare) !important; }
.text-ember     { color: var(--color-ember) !important; }

/* Semantic text (functional messaging) */
.text-primary   { color: var(--text-primary) !important; }
.text-secondary { color: var(--text-secondary) !important; }
.text-muted     { color: var(--text-muted) !important; }
.text-accent    { color: var(--text-accent) !important; }
.text-success   { color: var(--color-success) !important; }
.text-warning   { color: var(--color-warning) !important; }
.text-error     { color: var(--color-error) !important; }

/* Inherit from a colored ancestor (e.g. inside .bg-ink) */
.text-inherit   { color: inherit !important; }


/* ==========================================================================
   11. BORDER UTILITIES
   ========================================================================== */

.border {
  border: var(--border-hairline) solid var(--border-default) !important;
}
.border-top    { border-block-start: var(--border-hairline) solid var(--border-default) !important; }
.border-bottom { border-block-end: var(--border-hairline) solid var(--border-default) !important; }
.border-start  { border-inline-start: var(--border-hairline) solid var(--border-default) !important; }
.border-end    { border-inline-end: var(--border-hairline) solid var(--border-default) !important; }
.border-none   { border: 0 !important; }

/* Border color / emphasis modifiers */
.border-strong { border-color: var(--border-strong) !important; }
.border-accent { border-color: var(--accent) !important; }
.border-medium { border-width: var(--border-medium) !important; }
.border-thick  { border-width: var(--border-thick) !important; }


/* ==========================================================================
   12. CURSOR
   ========================================================================== */

.cursor-pointer    { cursor: pointer !important; }
.cursor-default    { cursor: default !important; }
.cursor-not-allowed{ cursor: not-allowed !important; }
.cursor-help       { cursor: help !important; }
.cursor-grab       { cursor: grab !important; }


/* ==========================================================================
   13. OVERFLOW
   ========================================================================== */

.overflow-hidden  { overflow: hidden !important; }
.overflow-auto    { overflow: auto !important; }
.overflow-visible { overflow: visible !important; }
.overflow-clip    { overflow: clip !important; }
.overflow-x-auto  { overflow-x: auto !important; overflow-y: hidden !important; }
.overflow-y-auto  { overflow-y: auto !important; overflow-x: hidden !important; }
.overflow-x-hidden{ overflow-x: hidden !important; }

/* Momentum scroll for touch scroll regions */
.scroll-touch {
  -webkit-overflow-scrolling: touch;
  overscroll-behavior: contain;
}


/* ==========================================================================
   14. Z-INDEX  (token scale)
   ========================================================================== */

.z-base     { z-index: var(--z-base) !important; }
.z-raised   { z-index: var(--z-raised) !important; }
.z-dropdown { z-index: var(--z-dropdown) !important; }
.z-sticky   { z-index: var(--z-sticky) !important; }
.z-overlay  { z-index: var(--z-overlay) !important; }
.z-modal    { z-index: var(--z-modal) !important; }
.z-toast    { z-index: var(--z-toast) !important; }


/* ==========================================================================
   15. RESPONSIVE VARIANTS (assorted, high-value only)
   Alignment / auto-margins that commonly need a breakpoint override.
   ========================================================================== */

@media (min-width: 768px) {
  .mx-auto-md { margin-inline: auto !important; }
  .w-auto-md  { inline-size: auto !important; }
  .w-100-md   { inline-size: 100% !important; }
}

@media (min-width: 1024px) {
  .text-start-lg  { text-align: start !important; }
  .text-center-lg { text-align: center !important; }
  .ms-auto-lg     { margin-inline-start: auto !important; }
  .w-auto-lg      { inline-size: auto !important; }
}


/* ==========================================================================
   16. MOTION-SAFE HELPERS
   Pair with component transitions; respect the user's reduced-motion pref.
   ========================================================================== */

@media (prefers-reduced-motion: reduce) {
  .motion-safe {
    transition: none !important;
    animation: none !important;
  }
}