@layer utilities {
  /* ========================================================================
     SPACING UTILITIES: Relative to token scale
     ======================================================================== */

  .m-0 {
    margin: 0;
  }

  .mb-1 {
    margin-block-end: var(--space-md);
  }

  .mb-1-5 {
    margin-block-end: var(--space-lg);
  }

  .mb-2 {
    margin-block-end: var(--space-xl);
  }

  .mb-3 {
    margin-block-end: var(--space-2xl);
  }

  .mb-4 {
    margin-block-end: var(--space-3xl);
  }

  .mt-1 {
    margin-block-start: var(--space-md);
  }

  .mt-1-0 {
    margin-block-start: var(--base-space);
  }

  .mt-1-5 {
    margin-block-start: var(--space-lg);
  }

  .mt-2 {
    margin-block-start: var(--space-xl);
  }

  .mt-4 {
    margin-block-start: var(--space-3xl);
  }

  .my-1-5 {
    margin-block: var(--space-lg);
  }

  .m-top-small {
    margin: var(--space-sm) 0 0 0;
  }

  .ml-1 {
    margin-inline-start: var(--space-md);
  }

  .mt-0-5 {
    margin-block-start: var(--space-sm);
  }

  .py-1 {
    padding-block: var(--space-md);
  }

  .py-2 {
    padding-block: var(--space-xl);
  }

  /* ========================================================================
     TEXT UTILITIES: Typography & emphasis
     ======================================================================== */

  .text-sm {
    font-size: var(--text-small);
  }

  .text-xs {
    font-size: var(--text-x-small);
  }

  .text-left {
    text-align: start;
  }

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

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

  .muted-text {
    color: var(--color-text-muted);
  }

  /* Alias: text-muted maps to the same semantic token */
  .text-muted {
    color: var(--color-text-muted);
  }

  .muted-light {
    color: var(--color-text-lighter);
  }

  .text-danger {
    color: var(--color-negative);
  }

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

  .text-warning {
    color: var(--color-warning);
  }

  .font-semibold {
    font-weight: var(--font-weight-semibold);
  }

  .sub-title {
    font-size: var(--text-medium);
    font-weight: var(--font-weight-semibold);
    color: var(--color-text-muted);
    margin-block-end: var(--space-md);
  }

  /* ========================================================================
     LINK UTILITIES
     ======================================================================== */

  .link-muted {
    text-decoration: none;
    color: inherit;
  }

  /* Nav background (#e8e4da) needs L<38% for WCAG AA 4.5:1 contrast */
  .site-nav .link-muted {
    /* Use the semantic text colour to ensure sufficient contrast
       against the site nav background. */
    color: var(--color-text);
  }

  /* Standard link utility: uses design token colours for links */
  .link {
    color: var(--color-link);
    text-decoration: underline;
  }

  .link:visited {
    color: var(--color-link-visited);
  }

  .link:hover {
    color: var(--color-link-hover);
  }

  .link-primary {
    color: var(--color-primary);
    text-decoration: none;
    font-weight: var(--font-weight-semibold);
  }

  .link-primary:hover {
    text-decoration: underline;
    color: var(--color-link-hover);
  }

  /* ========================================================================
     CODE & INLINE ELEMENTS
     ======================================================================== */

  .code-inline {
    background-color: var(--color-background-default);
    padding: var(--space-xs) var(--space-sm);
    border-radius: var(--radius-sm);
  }

  /* ========================================================================
     FORM UTILITIES
     ======================================================================== */

  .block-label {
    display: block;
  }

  /* ========================================================================
     FLEXBOX UTILITIES
     ======================================================================== */

  .flex-between-center {
    display: flex;
    justify-content: space-between;
    align-items: center;
  }

  /* Bootstrap-compatible display/flex aliases */
  .d-flex {
    display: flex;
  }

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

  .align-items-center {
    align-items: center;
  }

  .align-items-start {
    align-items: flex-start;
  }

  .flex-wrap {
    flex-wrap: wrap;
  }

  .flex-gap-md {
    display: flex;
    gap: var(--space-md);
  }

  /* Grid utilities */
  .grid-2 {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: var(--space-md);
  }

  .grid-full {
    grid-column: 1 / -1;
  }

  /* Form row: label and value aligned left in two-column layout */
  .form-row {
    display: flex;
    align-items: center;
    gap: var(--space-md);
  }

  .form-row--start {
    display: flex;
    align-items: flex-start;
    gap: var(--space-md);
  }

  .form-row .form-label {
    width: 30%;
    flex: 0 0 30%;
    margin: 0;
  }

  .form-row--start .form-label {
    width: 30%;
    flex: 0 0 30%;
  }

  .form-row .form-value {
    margin: 0;
    text-align: left;
    flex: 1 1 auto;
  }

  .form-row .form-value--multiline {
    text-align: left;
    max-width: 70%;
  }

  /* ========================================================================
     BACKGROUND COLOUR UTILITIES
     ======================================================================== */

  .bg-danger {
    background-color: var(--color-negative);
    color: var(--color-text-inverse);
  }

  .bg-warning {
    background-color: var(--color-warning);
    color: var(--color-text-inverse);
  }

  .bg-success {
    background-color: var(--color-positive);
    color: var(--color-text-inverse);
  }

  .bg-muted {
    background-color: var(--color-background-default);
  }

  /* ========================================================================
     TABLE UTILITIES
     ======================================================================== */

  /* Compact table variant */
  .table-sm th,
  .table-sm td {
    padding: var(--space-xs) var(--space-sm);
  }

  .admin-table {
    width: 100%;
    border-collapse: collapse;
  }

  .admin-table--spaced {
    margin-block-start: var(--space-lg);
  }

  .admin-table th,
  .admin-table td {
    padding: var(--space-md);
  }

  .admin-table th {
    font-weight: var(--font-weight-semibold);
  }

  .admin-table thead tr {
    border-block-end: 2px solid var(--color-border);
  }

  .admin-table tbody tr {
    border-block-end: 1px solid var(--color-border);
  }

  .row-clickable {
    cursor: pointer;
  }

  /* ========================================================================
     BADGE UTILITIES
     ======================================================================== */

  .badge {
    padding: var(--space-xs) var(--space-md);
    border-radius: var(--radius-sm);
    /* Default badge: subtle light background + dark text for white canvases */
    background-color: var(--color-background-secondary);
    color: var(--color-text);
    border: 1px solid var(--color-border-subtle);
    font-size: var(--text-small);
    display: inline-block;
    text-transform: capitalize;
    font-weight: var(--font-weight-semibold);
  }

  .badge--status-balanced {
    color: var(--color-text-subtle);
    background-color: var(--color-positive);
  }

  .badge--status-overload {
    color: var(--color-text-subtle);
    background-color: var(--color-negative);
  }

  /* Light warning badge used for small inline markers like `auth` */
  .badge--status-warning {
    background-color: oklch(var(--lch-warning-lightest));
    /* use the regular text colour (dark) for better legibility */
    color: var(--color-text);
    border: 1px solid oklch(var(--lch-warning-light));
    /* make the badge a touch smaller for inline placement */
    font-size: var(--text-x-small);
    padding: 2px 6px;
    line-height: 1;
  }

  /* Small badge variant for inline markers (e.g. `auth`) */
  .badge--small {
    font-size: var(--text-x-small);
    padding: 2px 6px;
    line-height: 1;
    vertical-align: middle;
  }

  /* Keep compact inline code+badge from wrapping */
  .pbs-code {
    display: inline-flex;
    align-items: center;
    gap: 4px;
    white-space: nowrap;
  }

  .badge--muted {
    background-color: var(--color-background-secondary);
    color: var(--color-text);
  }

  /* ========================================================================
     PROGRESS INDICATORS
     Simple indeterminate progress bar used in import tables while a job is running
     ======================================================================== */

  .progress {
    inline-size: 160px;
    block-size: 12px;
    background-color: var(--color-background-secondary);
    border-radius: var(--radius-sm);
    overflow: hidden;
    position: relative;
  }

  .progress__bar {
    inline-size: 25%;
    block-size: 100%;
    background: linear-gradient(90deg, var(--color-primary), color-mix(in srgb, var(--color-primary) 60%, white));
    animation: progress-slide 1.5s ease-in-out infinite;
  }

  @keyframes progress-slide {
    0% { transform: translateX(-25%); }
    100% { transform: translateX(425%); }
  }

  /* ========================================================================
     PAGY PAGINATION
     Targets pagy v43 plain series_nav output:
       <nav class="pagy series-nav" aria-label="...">
         <a href="?page=N">N</a>                            page link
         <a aria-current="page" aria-disabled="true">N</a>  current page
         <a role="separator" aria-disabled="true">…</a>     gap
         <a aria-disabled="true" aria-label="prev/next">‹›</a> disabled nav
       </nav>
     ======================================================================== */

  .pagy-nav-wrapper {
    margin-block-start: var(--space-md);
    display: flex;
    justify-content: flex-end;
  }

  nav.pagy {
    display: flex;
    align-items: center;
    gap: var(--space-xs);
    flex-wrap: wrap;
    list-style: none;
    margin: 0;
    padding: 0;
  }

  nav.pagy a {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    min-inline-size: 2rem;
    min-block-size: 2rem;
    padding-inline: var(--space-sm);
    border-radius: var(--radius-md);
    font-size: var(--text-small);
    font-weight: var(--font-weight-semibold);
    text-decoration: none;
    color: var(--color-text);
    border: var(--border);
    background-color: var(--color-canvas);
    transition: background-color var(--duration-fast) var(--ease-out),
                border-color var(--duration-fast) var(--ease-out),
                color var(--duration-fast) var(--ease-out);
    line-height: 1;
  }

  /* Clickable page links */
  nav.pagy a[href]:hover {
    background-color: var(--color-background-default);
    border-color: var(--color-primary);
    color: var(--color-primary);
  }

  /* Current page */
  nav.pagy a[aria-current="page"] {
    background-color: var(--color-primary);
    border-color: var(--color-primary);
    color: var(--color-text-inverse);
    cursor: default;
    pointer-events: none;
  }

  /* Disabled prev/next and gap */
  nav.pagy a[aria-disabled="true"] {
    color: var(--color-text-subtle);
    background-color: var(--color-background-default);
    border-color: var(--color-border);
    cursor: not-allowed;
    pointer-events: none;
  }

  /* Gap ellipsis: minimal border */
  nav.pagy a[role="separator"] {
    border-color: transparent;
    background-color: transparent;
  }

  /* ========================================================================
     DIVIDER UTILITIES
     ======================================================================== */

  .hr-divider {
    margin-block: var(--space-lg);
    border: none;
    border-block-start: 1px solid var(--color-border);
  }

  /* ========================================================================
     HEADING UTILITIES
     ======================================================================== */

  .h-sub {
    font-size: 1.125rem;
    font-weight: var(--font-weight-semibold);
    margin-block-end: var(--space-md);
  }

  /* ========================================================================
     CARD UTILITIES
     ======================================================================== */

  .card-muted {
    background-color: var(--color-background-default);
    padding: var(--space-lg);
    border-radius: var(--radius-md);
  }

  /* ========================================================================
     NAVIGATION UTILITIES
     ======================================================================== */

  .org-name {
    margin-inline-start: var(--space-sm);
    color: var(--color-text-muted);
    font-weight: var(--font-weight-semibold);
    font-size: 0.95rem;
  }

  /* Ensure organisation name links meet contrast requirements */
  .org-name .link-muted {
    color: var(--color-text);
  }

  /* ========================================================================
     ACCESSIBILITY UTILITIES
     ======================================================================== */

  .visually-hidden,
  .for-screen-reader {
    position: absolute;
    clip-path: inset(50%);
    inline-size: 1px;
    block-size: 1px;
    overflow: hidden;
    white-space: nowrap;
  }

  [hidden] {
    display: none !important;
  }

  .display-contents {
    display: contents;
  }

  /* ========================================================================
     FOCUS RING UTILITIES: For keyboard navigation
     ======================================================================== */

  button:focus-visible,
  a:focus-visible,
  input:focus-visible,
  select:focus-visible,
  textarea:focus-visible {
    outline: var(--focus-ring);
    outline-offset: var(--focus-ring-offset);
  }

  .hide-focus-ring {
    --focus-ring-width: 0;
  }

  /* Enhanced focus states for interactive elements */
  button:focus-visible,
  .btn:focus-visible,
  a[href]:focus-visible {
    outline-width: var(--focus-ring-width, 2px);
    outline-style: solid;
    outline-color: var(--color-focus, var(--color-primary));
    outline-offset: 2px;
  }

  /* Disabled state contrast */
  button:disabled,
  input:disabled,
  select:disabled,
  textarea:disabled {
    cursor: not-allowed;
    opacity: 0.6;
    background-color: var(--color-background-secondary);
  }

  /* Active/current navigation state */
  a.active,
  button.active,
  [aria-current="page"] {
    font-weight: var(--font-weight-semibold);
  }

  /* Motion preferences: Reduce animations for users who prefer it */
  @media (prefers-reduced-motion: reduce) {
    *,
    *::before,
    *::after {
      animation-duration: 0.01ms !important;
      animation-iteration-count: 1 !important;
      transition-duration: 0.01ms !important;
    }
  }

  /* Contrast preferences: Enhance for high contrast mode */
  @media (prefers-contrast: more) {
    button:focus-visible,
    a[href]:focus-visible,
    input:focus-visible {
      outline-width: 3px;
    }

    .visually-hidden:focus {
      position: relative;
      clip-path: auto;
      inline-size: auto;
      block-size: auto;
      overflow: visible;
      white-space: normal;
      background-color: var(--color-focus);
      color: var(--color-text-inverse);
      padding: var(--space-xs) var(--space-sm);
    }
  }

  /* Skip to main content link */
  .skip-link {
    position: absolute;
    inset-block-start: -40px;
    inset-inline-start: 0;
    background-color: var(--color-primary);
    color: white;
    padding: var(--space-sm);
    text-decoration: none;
    z-index: var(--z-above-all);
  }

  .skip-link:focus {
    inset-block-start: 0;
  }

  /* Keyboard-only utilities */
  .js-focus-visible :focus:not(.focus-visible) {
    outline: none;
  }

  /* Ensure all interactive elements have adequate touch targets.
     Checkboxes/radios using .form-check-input are explicitly sized by the
     components layer and must be excluded here so they don't get forced to
     44px (utilities layer wins over components in the declared layer order). */
  a,
  button,
  input[type="checkbox"]:not(.form-check-input),
  input[type="radio"]:not(.form-check-input),
  input[type="button"],
  input[type="submit"],
  select {
    min-height: 44px;
    min-width: 44px;
  }

  /* Screen reader text for icon-only buttons */
  .icon-button .icon-label {
    position: absolute;
    clip-path: inset(50%);
    inline-size: 1px;
    block-size: 1px;
    overflow: hidden;
    white-space: nowrap;
  }

  /* ========================================================================
     SKIP LINK UTILITIES: Keyboard navigation shortcut
     ======================================================================== */

  .skip-to-content {
    position: absolute;
    inset-block-start: -40px;
    inset-inline-start: 0;
    background-color: var(--color-primary);
    color: white;
    padding: var(--space-sm) var(--space-md);
    text-decoration: none;
    z-index: var(--z-above-all);
    border-radius: 0 0 var(--radius-md) 0;
    font-weight: var(--font-weight-semibold);
  }

  .skip-to-content:focus {
    inset-block-start: 0;
  }

  /* ========================================================================
     DARK MODE UTILITIES: Testing and development
     ======================================================================== */

  /* Force light mode for component testing */
  .theme-light {
    color-scheme: light;
    --lch-white: 100% 0 0;
    --lch-neutral-lightest: 96% 0.012 100;
    --lch-neutral-lighter: 92% 0.014 90;
    --lch-ink-darkest: 26% 0.05 264;
  }

  /* Force dark mode for component testing */
  .theme-dark {
    color-scheme: dark;
    --lch-white: 20% 0.0195 232.58;
    --lch-neutral-lightest: 25% 0.0017 40;
    --lch-neutral-lighter: 30% 0.012 50;
    --lch-ink-darkest: 96.02% 0.0034 260;
  }

  /* High contrast testing for accessibility */
  .theme-high-contrast {
    --focus-ring-width: 3px;
    --color-text: oklch(0% 0 0);
    --color-background-default: oklch(100% 0 0);
  }

  /* Reduced motion for accessibility testing */
  .test-reduced-motion * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }

  /* Component contrast checker overlay */
  .contrast-checker {
    position: relative;
  }

  .contrast-checker::before {
    content: attr(data-contrast-ratio);
    position: absolute;
    top: 0;
    right: 0;
    background: rgba(0, 0, 0, 0.7);
    color: white;
    padding: 2px 6px;
    font-size: 10px;
    border-radius: 2px;
    pointer-events: none;
    z-index: var(--z-top);
  }

  /* ========================================================================
     COMPONENT INTEGRATION PATTERNS
     ======================================================================== */

  /* Button focus ring integration */
  .btn:focus-visible {
    outline: var(--focus-ring);
    outline-offset: var(--focus-ring-offset);
  }

  .btn:disabled {
    opacity: 0.6;
    cursor: not-allowed;
  }

  /* Form input focus integration */
  input:focus-visible,
  textarea:focus-visible,
  select:focus-visible {
    outline: var(--focus-ring);
    outline-offset: var(--focus-ring-offset);
  }

  input:disabled,
  textarea:disabled,
  select:disabled {
    opacity: 0.6;
    cursor: not-allowed;
    background-color: var(--color-background-secondary);
  }

  /* Navigation active state integration */
  nav a[aria-current="page"],
  nav a.active {
    font-weight: var(--font-weight-semibold);
    color: var(--color-primary);
  }

  nav a[aria-current="page"]::before,
  nav a.active::before {
    content: '';
    position: absolute;
    inset-block-end: -2px;
    inset-inline: 0;
    height: 2px;
    background-color: var(--color-primary);
  }

  /* Badge status integration */
  .badge.badge--positive {
    background-color: var(--color-positive);
    color: white;
  }

  .badge.badge--warning {
    background-color: var(--color-warning);
    color: white;
  }

  .badge.badge--negative {
    background-color: var(--color-negative);
    color: white;
  }

  /* Alert integration */
  .alert.alert--success {
    background-color: oklch(var(--lch-success-lightest));
    border: 1px solid var(--color-positive);
    border-radius: var(--radius-md);
    padding: var(--space-md);
  }

  .alert.alert--warning {
    background-color: oklch(var(--lch-warning-lightest));
    border: 1px solid var(--color-warning);
    border-radius: var(--radius-md);
    padding: var(--space-md);
  }

  .alert.alert--error {
    background-color: oklch(var(--lch-error-lightest));
    border: 1px solid var(--color-negative);
    border-radius: var(--radius-md);
    padding: var(--space-md);
  }

  /* Table integration */
  table {
    width: 100%;
    border-collapse: collapse;
  }

  table th {
    background-color: var(--color-background-default);
    padding: var(--space-md);
    text-align: start;
    font-weight: var(--font-weight-semibold);
    border-block-end: 2px solid var(--color-border);
  }

  table td {
    padding: var(--space-md);
    border-block-end: 1px solid var(--color-border);
  }

  table tbody tr:hover {
    background-color: var(--color-background-default);
  }

  /* ========================================================================
     UTILITY OVERRIDES (Legacy support)
     ======================================================================== */

  .is-hidden {
    display: none;
  }

  .is-visible {
    display: block;
  }
}