How Hue Codex generates palettes and scales

scheme_offsets:
  complementary:       count = 2, offsets = [0, 180]
  analogous:           count = 3, offsets = [0, -30, 30]
  triadic:             count = 3, offsets = [0, 120, 240]
  tetradic:            count = 4, offsets = [0, 90, 180, 270]
  split_complementary: count = 3, offsets = [0, 150, 210]
  monochromatic:       count = 5, offsets = [0, 0, 0, 0, 0]

monochromatic_variants:
  index 0 Base:      lightnessDelta = 0,   saturationScale = 1
  index 1 Deep tone: lightnessDelta = -28, saturationScale = 0.72
  index 2 Shade:     lightnessDelta = -14, saturationScale = 0.82
  index 3 Tint:      lightnessDelta = 16,  saturationScale = 0.62
  index 4 Pale tint: lightnessDelta = 32,  saturationScale = 0.38

tone_values(base_hsl, tone, index):
  if tone == preserve:
    return s = base.s, l = base.l
  if tone == vivid:
    return s = clamp(base.s + 16, 64, 94),
           l = clamp(base.l + (index even ? -2 : 4), 42, 62)
  if tone == muted:
    return s = clamp(base.s * 0.52, 22, 56),
           l = clamp(base.l + (index even ? 6 : 10), 46, 74)
  # balanced
  return s = clamp(base.s * 0.86, 40, 78),
         l = clamp(base.l + (index even ? -4 : 6), 40, 68)

generate_harmony(seed, scheme, tone):
  base = rgb_to_hsl(hex_to_rgb(normalize_hex(seed)))
  # Hue wrapping uses normalize_degrees(h), returning [0, 360).
  # Example: base.h + -30 becomes 330 when base.h is 0.
  for each offset at index:
    h = normalize_degrees(base.h + offset)
    if scheme == monochromatic:
      s = clamp(base.s * saturationScale[index], 18, 92)
      l = clamp(base.l + lightnessDelta[index], 10, 94)
    else:
      s, l = tone_values(base, tone, index)
    hex = index == 0 ? seed : rgb_to_hex(hsl_to_rgb(h, s, l))
    attach WCAG best-text and pair metadata

neutral_seed_policy:
  # Achromatic HSL seeds have base.s = 0 and a fallback hue of 0.
  # Preserve tone keeps generated non-base hues achromatic because s = 0.
  # Balanced, vivid, muted, and monochromatic modes can introduce saturation
  # through their minimum s clamps; that hue is a Hue Codex fallback policy,
  # not a recovered meaningful source hue.
  # Harmony generation does not adjust OKLCH chroma; OKLCH chroma changes
  # are only part of the tint/shade/tone scale formulas.

clamp(value, low, high):
  return max(low, min(high, value))

palette_style_settings(base_hsl, style):
  balanced = {
    s: base.s, l: base.l,
    secondary: 34, accent: 180, surface: 24, text: 205,
    semanticS: 1, semanticL: 0, semanticShift: 1
  }

  settings = {
    balanced: balanced,
    vivid: {
      s: min(94, base.s + 18), l: min(62, base.l + 3),
      secondary: 42, accent: 174, surface: 28, text: 212,
      semanticS: 1.12, semanticL: -2, semanticShift: 1.2
    },
    calm: {
      s: max(34, base.s - 22), l: min(68, base.l + 8),
      secondary: 24, accent: 156, surface: 18, text: 200,
      semanticS: 0.84, semanticL: 4, semanticShift: 0.75
    },
    neutral: {
      s: max(18, base.s - 38), l: min(64, base.l + 4),
      secondary: 18, accent: 144, surface: 12, text: 196,
      semanticS: 0.64, semanticL: 8, semanticShift: 0.55,
      surfaceS: 12, borderS: 10
    },
    warm: {
      s: max(46, min(86, base.s * 0.82 + 14)), l: clamp(base.l + 2, 38, 62),
      secondaryHue: 28, accentHue: 54, surfaceHue: 36, textHue: 24,
      roleShift: 0.18, roleMaxShift: 34,
      semanticS: 0.96, semanticL: 2, semanticShift: 0.85
    },
    cool: {
      s: max(38, min(82, base.s * 0.82 + 8)), l: clamp(base.l + 1, 38, 62),
      secondaryHue: 205, accentHue: 268, surfaceHue: 206, textHue: 220,
      roleShift: 0.2, roleMaxShift: 38,
      semanticS: 0.86, semanticL: 2, semanticShift: 0.7
    },
    muted: {
      s: max(20, base.s - 38), l: clamp(base.l + 2, 34, 62),
      secondary: 28, accent: 160, surface: 20, text: 205,
      semanticS: 0.58, semanticL: 6, semanticShift: 0.5
    },
    pastel: {
      s: max(30, min(58, base.s * 0.48 + 18)), l: clamp(base.l + 22, 68, 82),
      secondary: 26, accent: 156, surface: 18, text: 205,
      semanticS: 0.48, semanticL: 14, semanticShift: 0.42,
      surfaceL: 97, borderL: 86
    },
    earthy: {
      s: max(26, min(58, base.s * 0.55 + 12)), l: clamp(base.l - 3, 34, 54),
      secondaryHue: 36, accentHue: 96, surfaceHue: 42, textHue: 30,
      roleShift: 0.16, roleMaxShift: 30,
      semanticS: 0.62, semanticL: 4, semanticShift: 0.45,
      surfaceS: 24, borderS: 18
    },
    monochrome: {
      s: max(18, base.s * 0.68), l: clamp(base.l, 34, 62),
      secondary: 0, accent: 0, surface: 0, text: 0,
      semanticS: 0.5, semanticL: 8, semanticShift: 0,
      semanticMode: seed,
      surfaceS: max(8, base.s * 0.16),
      textS: max(12, base.s * 0.32),
      borderS: max(8, base.s * 0.2)
    },
    high-contrast: {
      s: min(96, max(58, base.s + 12)), l: base.l >= 56 ? 44 : 58,
      secondary: 180, accent: 60, surface: 0, text: 205,
      semanticS: 1.16, semanticL: -6, semanticShift: 1.15,
      surfaceL: 98, textL: 7, borderL: 18
    },
    dark: {
      s: max(36, min(72, base.s * 0.72 + 10)), l: clamp(base.l - 22, 18, 38),
      secondary: 28, accent: 180, surface: 210, text: 42,
      semanticS: 0.92, semanticL: 4, semanticShift: 0.8,
      surfaceL: 10, textL: 92, borderL: 30,
      surfaceS: 18, textS: 18, borderS: 22
    },
    light: {
      s: max(24, min(58, base.s * 0.52 + 12)), l: clamp(base.l + 24, 68, 84),
      secondary: 22, accent: 150, surface: 18, text: 205,
      semanticS: 0.62, semanticL: 12, semanticShift: 0.55,
      surfaceL: 98, textL: 16, borderL: 88
    },
    playful: {
      s: min(96, max(62, base.s + 16)), l: clamp(base.l + 9, 54, 72),
      secondary: 54, accent: 205, surface: 42, text: 224,
      semanticS: 1.05, semanticL: 5, semanticShift: 1.05
    },
    elegant: {
      s: max(18, min(48, base.s * 0.42 + 10)), l: clamp(base.l - 8, 28, 50),
      secondary: 28, accent: 132, surface: 18, text: 210,
      semanticS: 0.5, semanticL: 1, semanticShift: 0.38,
      surfaceS: 10, textS: 20, borderS: 12, borderL: 70
    },
    retro: {
      s: max(42, min(78, base.s * 0.6 + 22)), l: clamp(base.l + 1, 42, 62),
      secondaryHue: 32, accentHue: 176, surfaceHue: 46, textHue: 24,
      roleShift: 0.12, roleMaxShift: 28,
      semanticS: 0.82, semanticL: 5, semanticShift: 0.62,
      surfaceS: 28, borderS: 22, borderL: 72
    },
    futuristic: {
      s: min(98, max(54, base.s + 20)), l: clamp(base.l + 2, 42, 64),
      secondaryHue: 210, accentHue: 292, surfaceHue: 222, textHue: 188,
      roleShift: 0.24, roleMaxShift: 44,
      semanticS: 1.08, semanticL: -1, semanticShift: 0.92,
      surfaceL: 8, textL: 90, borderL: 34,
      surfaceS: 22, borderS: 34
    }
  }

  return settings[style] or balanced

harmonized_hue(seed_hue, anchor_hue, strength, max_shift):
  shortest = ((seed_hue - anchor_hue + 540) % 360) - 180
  shift = clamp(shortest * strength, -max_shift, max_shift)
  return normalize_degrees(anchor_hue + shift)

build_role_palette(seed, style, locks, previous_palette):
  base = rgb_to_hsl(hex_to_rgb(seed))
  settings = palette_style_settings(base, style)

  role_hue(key, fallback_offset):
    if settings has key + "Hue":
      return harmonized_hue(base.h, settings[key + "Hue"],
                            settings.roleShift or 0.2,
                            settings.roleMaxShift or 36)
    return normalize_degrees(base.h + fallback_offset)

  semantic_hue(anchor, strength, max_shift):
    if settings.semanticMode == seed:
      return base.h
    return harmonized_hue(base.h, anchor,
                          strength * settings.semanticShift,
                          max_shift)

  semantic_targets:
    success: anchor = 145deg, strength = 0.20, max_shift = 18deg, range = 127..163deg
    warning: anchor = 44deg,  strength = 0.16, max_shift = 14deg, range = 30..58deg
    danger:  anchor = 350deg, strength = 0.14, max_shift = 12deg, range = 338..360deg or 0..2deg

  semantic_s(base_amount, min_s, max_s):
    return clamp((base_amount + base.s * 0.18) * settings.semanticS, min_s, max_s)

  semantic_l(base_amount, min_l, max_l):
    return clamp(base_amount + settings.semanticL, min_l, max_l)

  roles = [
    primary:   style == balanced ? seed : hsl(base.h, clamp(settings.s), clamp(settings.l, 4, 97)),
    secondary: hsl(role_hue(secondary, settings.secondary), settings.s * 0.86, settings.l - 7),
    accent:    hsl(role_hue(accent, settings.accent), min(94, settings.s + 10), settings.l + 5),
    surface:   hsl(role_hue(surface, settings.surface), settings.surfaceS ?? max(12, settings.s * 0.28), settings.surfaceL ?? 96),
    text:      hsl(role_hue(text, settings.text), settings.textS ?? max(24, settings.s * 0.42), settings.textL ?? 12),
    border:    hsl(role_hue(surface, settings.surface), settings.borderS ?? max(10, settings.s * 0.24), settings.borderL ?? 78),
    success:   hsl(semantic_hue(145, 0.2, 18), semantic_s(48,34,88), semantic_l(36,28,52)),
    warning:   hsl(semantic_hue(44, 0.16, 14), semantic_s(68,44,94), semantic_l(62,48,74)),
    danger:    hsl(semantic_hue(350, 0.14, 12), semantic_s(64,42,92), semantic_l(56,42,68))
  ]

  for each role at index:
    if locks[index] and previous_palette has color at index:
      keep previous hex
    else:
      convert HSL role to HEX with h normalized, s clamped 0..100, l clamped 4..97

  role_contracts:
    text on surface: minimum 7.0
    primary, secondary, accent, border, success, warning, danger on surface: minimum 3.0

  if surface is unlocked and a locked role misses its contract:
    search the surface OKLCH lightness range for the nearest surface that fits every locked role

  for each unlocked contracted role:
    if raw WCAG contrast is below target + 0.05:
      keep OKLCH hue, move lightness toward the higher-contrast black/white endpoint,
      binary-search the smallest passing move, and reduce chroma only when needed for sRGB

  locked roles never move; if locked colors make the system unsatisfiable, report the exact failed pair

random_seed():
  # This is not a seedable Hue Codex PRNG.
  # It uses the browser JavaScript Math.random() source.
  h = floor(Math.random() * 360)
  s = 62 + floor(Math.random() * 24)  # 62..85 percent
  l = 42 + floor(Math.random() * 20)  # 42..61 percent
  return rgb_to_hex(hsl_to_rgb(h, s, l))

initial_palette(location):
  state = decode_versioned_fragment_state(location.hash)
  seed = normalize_hex(state.seed or #4169E1)
  style = state.style or balanced
  locks = state.locks or [false, false, false, false, false, false, false, false, false]

  if state contains resolved role colors:
    palette = create_palette_from_role_colors(state.palette)
    return palette, seed, style, locks

  return build_role_palette(seed, style, locks, previous = null)

regenerate(seed, style, locks, previous_palette):
  # Deterministic after seed, style, locks, and previous locked values are known.
  seed = normalize_hex(seed)
  return build_role_palette(seed, style, locks, previous_palette)

share_palette(seed, style, locks, palette, export_mode):
  state = canonical_versioned_state(seed, style, locks, palette, export_mode)
  return "/palette-generator#s=" + base64url_encode(state)

shared_palette_fragment_behavior:
  # The fragment stores the supported current settings and resolved role colors.
  # It does not store an internal PRNG state or the original Math.random() draws.
  validate version, tool, fields, locks, roles, names, colors, and size bounds

wcag_score(foreground, background):
  raw = wcag_contrast_ratio(foreground, background)
  return {
    ratio: round(raw, 2),
    rawRatio: raw,
    normalAA: raw >= 4.5,
    normalAAA: raw >= 7,
    largeAA: raw >= 3,
    largeAAA: raw >= 4.5,
    uiAA: raw >= 3
  }

with_accessibility_metadata(color, palette):
  surface = palette.role(surface) or #FFFFFF
  text = palette.role(text) or #10212B
  return {
    contrastOnSurface: round(wcag_contrast_ratio(color.hex, surface), 2),
    contrastWithText: round(wcag_contrast_ratio(color.hex, text), 2),
    bestText: highest_raw_contrast(color.hex, [text, #FFFFFF, #000000]),
    wcagOnSurface: wcag_score(color.hex, surface)
  }

palette_primary_checks(palette):
  primary = palette.role(primary)
  surface = palette.role(surface)
  text = palette.role(text)
  border = palette.role(border)
  success = palette.role(success)
  warning = palette.role(warning)
  danger = palette.role(danger)
  secondary = palette.role(secondary)
  accent = palette.role(accent)
  bestOnPrimary = highest_raw_contrast(primary.hex, [#FFFFFF, #000000])

  return {
    textOnSurface: wcag_score(text.hex, surface.hex),
    primaryOnSurface: wcag_score(primary.hex, surface.hex),
    secondaryOnSurface: wcag_score(secondary.hex, surface.hex),
    accentOnSurface: wcag_score(accent.hex, surface.hex),
    whiteOnPrimary: wcag_score(#FFFFFF, primary.hex),
    blackOnPrimary: wcag_score(#000000, primary.hex),
    bestOnPrimaryScore: wcag_score(bestOnPrimary.hex, primary.hex),
    borderOnSurface: wcag_score(border.hex, surface.hex),
    successOnSurface: wcag_score(success.hex, surface.hex),
    warningOnSurface: wcag_score(warning.hex, surface.hex),
    dangerOnSurface: wcag_score(danger.hex, surface.hex)
  }

readable_pair_count(palette):
  count = 0
  for each foreground in palette.colors:
    for each background in palette.colors:
      if foreground.hex != background.hex:
        raw = wcag_contrast_ratio(foreground.hex, background.hex)
        if raw >= 4.5:
          count += 1
  return count

build_scales(seed, requested_steps, mode):
  count = clamp(requested_steps, 3, 11)
  weights = [(index + 1) / (count + 1) for index in 0..count-1]

  if mode == simple:
    Tints  = [mix_srgb(seed, #FFFFFF, weight) for weight in weights]
    Shades = [mix_srgb(seed, #000000, weight) for weight in weights]
    Tones  = [mix_srgb(seed, #808080, weight * 0.82) for weight in weights]
    return Tints, Shades, Tones

  if mode == hsl:
    base = rgb_to_hsl(hex_to_rgb(seed))
    Tints = [
      hsl(base.h, max(0, base.s - weight * 10),
          base.l + (98 - base.l) * weight)
      for weight in weights
    ]
    Shades = [
      hsl(base.h, base.s,
          max(4, base.l * (1 - weight * 0.82)))
      for weight in weights
    ]
    Tones = [
      hsl(base.h, max(0, base.s * (1 - weight * 0.75)),
          base.l + (50 - base.l) * weight * 0.45)
      for weight in weights
    ]
    return Tints, Shades, Tones

  # default mode: OKLCH perceptual
  base = rgb_to_oklch(hex_to_rgb(seed))
  oklch_hex(l, c, h = base.h):
    return rgb_to_hex(oklch_to_rgb(
      l = clamp(l, 0, 1),
      c = max(0, c),
      h = h
    ))

  Tints = [
    oklch_hex(base.l + (0.98 - base.l) * weight,
              base.c * (1 - weight * 0.18))
    for weight in weights
  ]
  Shades = [
    oklch_hex(base.l * (1 - weight * 0.82),
              base.c * (1 - weight * 0.08))
    for weight in weights
  ]
  Tones = [
    oklch_hex(base.l + (0.62 - base.l) * weight * 0.32,
              base.c * (1 - weight * 0.78))
    for weight in weights
  ]
  return Tints, Shades, Tones