/*
================================================================================
  ML Software, LLC
  Copyright 2026. All rights reserved.

  IQ Platform - _app/assets/css/utilities.css

  Platform: 0.1.2
  Version: 0.1.1
  Created: 2026-04-27
  Updated: 2026-04-27

  Description: A small, deliberately limited set of layout and
  visibility utility classes. Utilities are an escape hatch, not a
  primary styling strategy. Every utility class earns its place by
  being needed in two or more views; the platform is NOT trying to
  reinvent Tailwind.

  Naming: .iq-* prefix to namespace. Hyphenated, no double-dashes,
  no double-underscores. Read like English: .iq-row, .iq-stack,
  .iq-mt-2 (margin-top scale 2), .iq-hide-mobile.

  Load order: tokens.css -> base.css -> shell.css -> components.css
              -> forms.css -> utilities.css. Last to load so utilities
  can win specificity ties via cascade order.

  When NOT to use a utility:
    - When a component should own the rule. A button's hover state
      belongs in components.css, not via .iq-bg-raised on the markup.
    - When the rule is product-specific. Domain styling lives in
      product code.
    - When you'd reach for three or four utilities to compose
      something semantically meaningful. That's a component, not
      a utility soup.

  Version History:
    0.1.1 - 2026-04-27 - Burgundy color migration. .iq-text-error
                         changed from var(--red) to var(--red-text)
                         for legibility on dark surfaces.
    0.1.0 - 2026-04-27 - Session 3 initial. Layout helpers (.iq-row,
                         .iq-stack, .iq-spacer), visibility helpers
                         (.iq-hide-mobile, .iq-hide-desktop),
                         text utilities (.iq-text-center, .iq-text-dim,
                         .iq-text-truncate), and a small spacing
                         scale (.iq-mt-1 through .iq-mt-4 and
                         matching .iq-mb-*). Spacing scale uses
                         the platform 4px rhythm: 4, 8, 16, 24.
================================================================================
*/

/* ============================================================================
   Layout helpers
   ============================================================================ */

.iq-row {
  display: flex;
  flex-direction: row;
  align-items: center;
  gap: 12px;
}

.iq-row--between {
  justify-content: space-between;
}

.iq-row--end {
  justify-content: flex-end;
}

.iq-row--start {
  justify-content: flex-start;
  align-items: flex-start;
}

.iq-stack {
  display: flex;
  flex-direction: column;
  gap: 12px;
}

.iq-stack--tight {
  gap: 6px;
}

.iq-stack--loose {
  gap: 20px;
}

.iq-spacer {
  flex: 1;
}


/* ============================================================================
   Spacing scale (4px rhythm)
   Use sparingly. Component-owned spacing is preferred.
   ============================================================================ */

.iq-mt-1 { margin-top:  4px;  }
.iq-mt-2 { margin-top:  8px;  }
.iq-mt-3 { margin-top: 16px;  }
.iq-mt-4 { margin-top: 24px;  }

.iq-mb-1 { margin-bottom:  4px;  }
.iq-mb-2 { margin-bottom:  8px;  }
.iq-mb-3 { margin-bottom: 16px;  }
.iq-mb-4 { margin-bottom: 24px;  }


/* ============================================================================
   Visibility
   Coarse-pointer based hiding -- 'mobile' here means 'touch device',
   not 'small screen'. Use these for the hamburger toggle, mobile-only
   sidebar location switcher, etc. For pure breakpoint-based hiding
   use the existing media queries in shell.css and components.css
   rather than reaching for a utility.
   ============================================================================ */

@media (pointer: coarse) {
  .iq-hide-mobile {
    display: none !important;
  }
}

@media (pointer: fine) {
  .iq-hide-desktop {
    display: none !important;
  }
}

.iq-hidden {
  display: none !important;
}


/* ============================================================================
   Text utilities
   ============================================================================ */

.iq-text-center {
  text-align: center;
}

.iq-text-right {
  text-align: right;
}

.iq-text-dim {
  color: var(--text-dim);
}

.iq-text-secondary {
  color: var(--text-secondary);
}

.iq-text-error {
  color: var(--red-text);
}

.iq-text-success {
  color: var(--green);
}

.iq-text-truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

.iq-text-mono {
  font-family: var(--font-mono);
}


/* ============================================================================
   Surface helpers
   For one-off cases where you want a raised surface without writing
   a component. If you find yourself reaching for these often, that's
   a sign you're missing a component, not a utility.
   ============================================================================ */

.iq-surface {
  background: var(--bg-surface);
  border: 1px solid var(--border);
  border-radius: var(--radius-lg);
  padding: 16px 18px;
}

.iq-surface--raised {
  background: var(--bg-raised);
}