Export formats, tokens, CSS variables, and fallbacks

Representative automated fixture coverage

Hue Codex imports versioned JSON fixtures and tests the corresponding pure production functions directly. The groups below are the representative regression evidence most relevant to this methodology.

• Export fixtures: Displayed-versus-exported values, parseable CSS and JSON, and safe allowlisted SVG output. View the JSON fixtures.
• Palette fixtures: Deterministic role output, locked-color preservation, readable-pair metadata, and export consistency. View the JSON fixtures.

What a pass means. A passing group confirms the named vectors and tested properties still match the documented implementation. It does not prove every possible input, final browser rendering, full accessibility conformance, profile-aware print output, or every downstream export consumer.

Role names are converted to lowercase token-friendly slugs by replacing non-alphanumeric separators with hyphens. HEX values are normalized before export.

Palette and tool exports favor human-readable labels plus structured data so a designer, developer, or reviewer can understand why a value exists.

Generated export keys must be deterministic and unique inside the same export group. Fixed role palettes use a predefined unique role set, while dynamic repeated outputs use stable sequence keys such as sample1, swatch-1, sample-01, or color-01.

Slugging is ASCII-oriented: Hue Codex lowercases the source label, replaces runs outside a-z and 0-9 with hyphens, trims edge hyphens, then falls back to a context key if nothing remains. JSON object keys are quoted strings, so leading numbers and reserved words are valid in JSON exports; CSS variables and framework snippets use prefixes or quoted keys when a generated name could be unsafe as a bare identifier.

Hue Codex publishes family-specific JSON Schemas for current JSON export families: plain tool reports, portable single-color records, and Hue Codex token-style JSON containers.

The umbrella export schema is a convenience wrapper over those family schemas. It is still intentionally permissive for plain reports because individual tools include different report fields, so use the token-style schema directly when validating token-style exports.

The plain-report schema excludes token-style marker fields such as top-level $schema, $extensions, dimension, or an object-valued color group. A scalar color field can still be used by a plain report.

Token-style validation requires token leaves to include both $type and $value. For example, {"color":{"primary":{"$type":"color"}}} is malformed and should fail the token-style schema rather than passing as a generic report.

The downloadable family schemas are the validation source of truth; later inline schema blocks on this page are simplified explanatory excerpts.

The generated link list for this methodology covers all 27 public Hue Codex tools. This table explains why each tool belongs here: each one exposes a copyable value, structured export, report, framework snippet, visual download, or handoff note whose naming, precision, fallback, schema, or browser behavior is governed by this methodology.

Hue Codex cites Design Tokens Format Module 2025.10, the DTCG Final Community Group Report published on October 28, 2025. The DTCG describes this version as stable and intended for implementation. It is a W3C Community Group Report, not a W3C Standard, W3C Standards Track document, or W3C Recommendation.

That publication status is separate from Hue Codex export claims. Hue Codex token-style JSON remains a practical product schema and does not claim DTCG conformance. Only the separately labeled DTCG 2025.10 JSON and Resolver companion implement the exact subsets described below.

The DTCG Format specification recommends the application/design-tokens+json media type where available. The current Color Picker download handler uses application/json, which is documented here as actual behavior rather than presented as the preferred DTCG media type.

The Color Picker Semantic CSS system emits one concrete --hc-color-source-* primitive and one usage-specific --color-* semantic alias. It adds only the interaction states that belong to the selected role and keeps light and dark selectors separate.

An sRGB fallback is emitted first. When Display P3 output is selected, a later same-color Display P3 equivalent is emitted for progressive enhancement; this does not claim new expanded-gamut authored information.

Decision status and scope remain visible in comments. Surface decisions include explicit on-surface text and icon roles instead of treating a passing surface pair as proof for every component.

Each Color Picker selector label is a separate production contract. This table summarizes what each output carries, how it is tested, and the strongest supported compatibility statement.

Token-style JSON is the existing Hue Codex recursive handoff schema. It uses CSS color strings and Hue Codex metadata, preserves its historical internal state name for saved-state compatibility, and explicitly records dtcgConformance: false. It must not be relabeled as DTCG.

DTCG 2025.10 JSON is a separate export implementing a tested Format and Color subset. It emits the official Format schema identifier, groups and $root tokens, $type: "color", structured sRGB values, normalized alpha, six-digit HEX fallbacks, curly-brace aliases, and reverse-domain Hue Codex extension metadata.

The implemented subset covers source, semantic, theme, role-relevant state, and applicable surface/content color tokens. It does not claim every DTCG value module, arbitrary user-authored documents, external token sources, importer-specific manifests, or universal importer compatibility.

The DTCG 2025.10 Resolver companion is deliberately separate from the Format/Color token document because its root contract describes conditional source composition rather than a standalone token group.

The companion emits the official Resolver schema identifier, version 2025.10, a named decision set, inline Format sources, one theme modifier, light and dark context arrays, a light default, and a resolution order that references the set and modifier.

A compatible consumer supplies a string selecting theme: "light" or theme: "dark" when resolving the modifier. Ordinary token importers are not assumed to consume Resolver documents.

Implemented subset. Validation covers Hue Codex generated fixtures, set/source references, aliases, contexts, defaults, and resolution order. It does not establish compatibility with every Resolver implementation.

Color Picker exposes two distinct Tailwind outputs. Tailwind v4 CSS-first theme is the current-project path; Tailwind legacy JavaScript config is retained for older JavaScript configuration workflows.

The v4 output begins with @import "tailwindcss", stores source and theme values in ordinary CSS selectors, and exposes role-specific --color-* theme variables through @theme inline. Inline is used because the theme variables reference ordinary CSS variables.

The exporter defines separate light and dark alias variables plus one current-theme variable. The [data-theme="dark"] selector points that current variable at the dark alias, and @theme inline maps the role-specific utility token to the current variable. The export does not emit @custom-variant, so a project that wants dark:* utilities tied to that selector must configure its own variant separately.

The legacy Color Picker output is CommonJS module.exports with a generated scale under theme.extend.colors[slug], including 50 through 950, DEFAULT, and foreground. It is not the CSS-first v4 output. Palette Generator has a separate historical ESM export contract.

@import "tailwindcss";

:root {
  --hc-color-source-primary: #0EA5E9;
  --hc-theme-primary-light: var(--hc-color-source-primary);
  --hc-theme-primary-dark: var(--hc-color-source-primary);
  --hc-theme-current-primary: var(--hc-theme-primary-light);
}

[data-theme="dark"] {
  --hc-theme-current-primary: var(--hc-theme-primary-dark);
}

@theme inline {
  --color-action-primary-text: var(--hc-theme-current-primary);
}

module.exports = {
  theme: {
    extend: {
      colors: {
        "primary": {
          50: "#F0F9FF",
          500: "#0EA5E9",
          950: "#082F49",
          DEFAULT: "#0EA5E9",
          foreground: "#000000"
        }
      }
    }
  }
};

Hue Codex Sass exports are SCSS module snippets intended to parse with Dart Sass. They include @use "sass:map", !default maps, lookup functions, and mixins that can emit CSS custom properties.

The maps and functions are compile-time data, so they emit no CSS until a project includes the generated mixin or reads the map in its own stylesheet code.

Hue Codex does not currently emit indented .sass syntax, @forward modules, an npm Sass package, or a Style Dictionary build pipeline. The SCSS output is still a copyable handoff artifact, but it is now structured enough to compile and consume directly in an existing Sass setup.

@use "sass:map";

$color-primary: (
  "value": "#0EA5E9",
  "hex": "#0EA5E9",
  "rgb": "14 165 233",
  "oklch": "oklch(68.56% 0.147 237.32)",
  "alpha": 1,
  "foreground": "#000000",
  "contrast-on-white": 2.77,
) !default;

@function color-primary($key) {
  @return map.get($color-primary, $key);
}

@mixin color-primary-vars($selector: ":root") {
  #{$selector} {
    --color-primary: #{map.get($color-primary, "value")};
    --color-primary-rgb: #{map.get($color-primary, "rgb")};
    --color-primary-foreground: #{map.get($color-primary, "foreground")};
  }
}

@use "sass:map";

$hue-codex-palette: (
  "primary": "#0EA5E9",
  "secondary": "#6366F1",
  "accent": "#F97316",
  "surface": "#F8FAFC",
  "text": "#0F172A",
  "border": "#CBD5E1",
  "success": "#16A34A",
  "warning": "#F59E0B",
  "danger": "#DC2626",
) !default;

$hue-codex-palette-contrast: (
  "text-on-surface": 15.82,
  "primary-on-surface": 2.44,
  "white-on-primary": 2.77,
) !default;

@function hue-codex-color($role) {
  @return map.get($hue-codex-palette, $role);
}

@mixin hue-codex-palette-vars($selector: ":root", $prefix: "color") {
  #{$selector} {
    --#{$prefix}-primary: #{map.get($hue-codex-palette, "primary")};
    --#{$prefix}-text: #{map.get($hue-codex-palette, "text")};
  }
}

@include hue-codex-palette-vars;

.button {
  background: hue-codex-color("primary");
  color: hue-codex-color("text");
}

The downloadable Hue Codex schema family covers two product-defined JSON shapes: plain tool reports and Hue Codex token-style JSON. The separately labeled DTCG Format/Color and Resolver exports use their official 2025.10 schema identifiers and the exact-subset validation described above; they do not validate against the Hue Codex token-style schema.

When a plain JSON export needs a portable single-color record, Hue Codex uses the compact field shape shown below: name, value, type, space, contrast, source, and caveats.

All JSON exports are generated with JSON.stringify(value, null, 2), so output uses two-space indentation, quoted object keys, no comments, no trailing commas, and the current tool state at copy/download time.

Token group keys and token leaf keys are deterministic. Generated sequences use stable names such as sample1, swatch-1, or padded sample tokens when needed so repeated labels do not overwrite each other.

In the plain-report schema and umbrella schema, top-level $schema, $extensions, dimension, or an object-valued color group is a token-style discriminator. Once one of those markers is present, the object must satisfy token-style validation rather than falling through to the permissive plain-report branch.

The inline schema blocks below are simplified explanatory excerpts. Use the downloadable family-specific schemas above as the source of truth for validation.

The token-style excerpt is abbreviated, but its top-level behavior matches the downloadable Hue Codex token-style schema: $schema, $extensions, color, dimension, and any additional top-level property is interpreted as a token group. When Hue Codex emits $schema, it identifies the Hue Codex schema rather than the DTCG specification. This is not a Design Tokens Format Module conformance claim.

{
  "name": "primary",
  "value": "#0EA5E9",
  "type": "color",
  "space": "srgb",
  "contrast": {
    "againstWhite": 2.77,
    "againstWhiteRaw": 2.771412229141218,
    "againstBlack": 7.58,
    "againstBlackRaw": 7.577364269085043
  },
  "source": "palette-generator",
  "caveats": []
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Hue Codex plain JSON export",
  "description": "Tool-specific Hue Codex report payload. There is no cross-tool envelope.",
  "oneOf": [
    {
      "type": "object",
      "not": { "$ref": "#/$defs/tokenStyleDiscriminator" },
      "additionalProperties": { "$ref": "#/$defs/jsonValue" }
    },
    {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": { "$ref": "#/$defs/jsonValue" }
      }
    }
  ],
  "$defs": {
    "tokenStyleDiscriminator": {
      "type": "object",
      "anyOf": [
        { "required": ["$schema"] },
        { "required": ["$extensions"] },
        { "required": ["dimension"] },
        {
          "required": ["color"],
          "properties": {
            "color": { "type": "object" }
          }
        }
      ]
    },
    "jsonValue": {
      "oneOf": [
        { "type": "string" },
        { "type": "number" },
        { "type": "integer" },
        { "type": "boolean" },
        { "type": "null" },
        {
          "type": "array",
          "items": { "$ref": "#/$defs/jsonValue" }
        },
        {
          "type": "object",
          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
        }
      ]
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Hue Codex token-style JSON export",
  "description": "Hue Codex practical token handoff shape; not a Design Tokens conformance claim.",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Optional identifier for the Hue Codex token-style schema; not a DTCG conformance claim."
    },
    "$extensions": { "$ref": "#/$defs/extensions" },
    "color": { "$ref": "#/$defs/tokenGroup" },
    "dimension": { "$ref": "#/$defs/tokenGroup" }
  },
  "additionalProperties": { "$ref": "#/$defs/tokenGroup" },
  "anyOf": [
    { "required": ["color"] },
    { "required": ["dimension"] }
  ],
  "$defs": {
    "tokenGroup": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          { "$ref": "#/$defs/tokenGroup" },
          { "$ref": "#/$defs/tokenLeaf" }
        ]
      }
    },
    "tokenLeaf": {
      "type": "object",
      "required": ["$type", "$value"],
      "properties": {
        "$type": {
          "enum": ["color", "dimension"]
        },
        "$value": {
          "oneOf": [
            { "type": "string" },
            { "type": "number" }
          ]
        },
        "$description": { "type": "string" },
        "$extensions": { "$ref": "#/$defs/extensions" },
        "role": { "type": "string" },
        "accessibility": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "additionalProperties": true
    },
    "extensions": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "hueCodex": {
          "type": "object",
          "additionalProperties": true
        }
      }
    }
  }
}

Hue Codex orders CSS fallbacks for progressive enhancement: the broadly supported value appears first, then the modern value appears later. Browsers that do not support the later syntax ignore that declaration; browsers that do support it use the later declaration because it wins in the cascade.

For direct CSS properties, the fallback and modern declaration can sit next to each other. For CSS custom properties, Hue Codex documents the safer pattern: keep the HEX custom property outside @supports, then override it inside an @supports block that tests the modern color syntax. That avoids older browsers storing an unsupported modern color token inside a custom property and failing later when the variable is used.

Fallback order should not be reversed. A HEX declaration placed after an OKLCH, color-mix(), light-dark(), or modern gradient declaration will override the modern value in browsers that support both.

.button {
  background-color: #0EA5E9;
  background-color: oklch(68.56% 0.147 237.32);
}

:root {
  --hc-primary: #0EA5E9;
}

@supports (color: oklch(0% 0 0)) {
  :root {
    --hc-primary: oklch(68.56% 0.147 237.32);
  }
}

.button {
  background-color: var(--hc-primary);
}

.hero {
  background-image: linear-gradient(135deg, #0EA5E9, #6366F1);
  background-image: linear-gradient(
    135deg in oklab,
    oklch(68.56% 0.147 237.32),
    oklch(58.52% 0.201 275.23)
  );
}

.badge {
  border-color: #7DD3FC;
}

@supports (color: color-mix(in oklab, #0EA5E9 70%, white)) {
  .badge {
    border-color: color-mix(in oklab, #0EA5E9 70%, white);
  }
}

Modern CSS exports can include fallback declarations before newer syntax. Gradient exports include fallback CSS when the selected interpolation syntax may not be broadly supported.

Duotone CSS is labeled as an approximation because the source-size PNG is generated from actual canvas pixels, while CSS filters and blend modes depend on browser rendering and context.

HEX and RGB exports are not decimal precision modes: Hue Codex normalizes HEX to uppercase six-digit #RRGGBB and serializes RGB as integer sRGB channels from 0 to 255.

Contrast pass/fail decisions use raw WCAG ratios. Displayed ratios and compact summary fields round to two decimals; JSON exports that include a full WCAG score object include both ratio and rawRatio. Portable single-color records should include displayed and raw contrast fields when the raw value is available.

• Readable exports may round values more aggressively than detailed or token exports.
• Browser support for modern CSS color functions should be checked before relying on those declarations alone.
• CSS Color 5 features such as color-mix(), light-dark(), and device-cmyk() are draft-standard context; exports should keep fallbacks or review notes when those features are used.
• Hue Codex token-style JSON is intended as a practical handoff format, not a Design Tokens conformance claim or a promise that every consuming tool will import it without mapping.
• DTCG 2025.10 JSON implements and validates the documented Format/Color subset; the Resolver companion implements its documented Resolver subset. Neither claim guarantees universal importer compatibility.
• Tailwind v4 CSS-first output must be processed by a Tailwind CSS v4 build. The separate legacy JavaScript fragment targets older configuration workflows.
• Downloaded files are generated in the browser and use the current tool state at the time of export.

Export naming is deterministic. Fixed role palettes use unique role names; generated sequences add stable numeric suffixes or padded sample tokens so repeated labels do not overwrite each other.

reserved_target_words = [
  "__proto__", "prototype", "constructor", "toString", "valueOf",
  "default", "class", "function", "var", "let", "const", "import", "export"
]

slugify(value, fallback):
  slug = String(value)
    .trim()
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-+|-+$/g, "")
  return slug or fallback

unique_generated_key(value, fallback, used, options):
  base = slugify(value, fallback)

  if options.prefixLeadingNumber and base matches /^[0-9]/:
    base = options.leadingNumberPrefix + "-" + base

  if options.avoidReservedWords and base is in reserved_target_words:
    base = options.reservedWordPrefix + "-" + base

  candidate = base
  suffix = 2
  while used contains candidate:
    candidate = base + "-" + suffix
    suffix = suffix + 1

  add candidate to used
  return candidate

fixed_role_export_key(role):
  # Palettes use a fixed unique role set:
  # primary, secondary, accent, surface, text, border, success, warning, danger.
  return slugify(role, "color")

image_palette_export_key(label, index):
  # Dynamic image roles can repeat, so append the 1-based index.
  return slugify(label, "swatch-" + (index + 1)) + "-" + (index + 1)

gradient_palette_export_key(index):
  return "sample-" + pad_left(index + 1, 2, "0")

cvd_export_key(index):
  return "color-" + pad_left(index + 1, 2, "0")

json_token_key(label, fallback, used):
  # JSON keys are quoted strings, so leading numbers and language reserved
  # words are preserved unless they collide in the same token group.
  return unique_generated_key(label, fallback, used, {
    prefixLeadingNumber: false,
    avoidReservedWords: false
  })

bare_identifier_key(label, fallback, used):
  # Use for any target that cannot quote keys safely.
  return unique_generated_key(label, fallback, used, {
    prefixLeadingNumber: true,
    leadingNumberPrefix: "token",
    avoidReservedWords: true,
    reservedWordPrefix: "token"
  })

round(value, places):
  multiplier = 10 ^ places
  return Math.round((Number(value) + Number.EPSILON) * multiplier) / multiplier

stage1_precision(mode):
  quick/rounded: basic 2, lab 4, ok 6, xyz 6
  css:           basic 2, lab 3, ok 5, xyz 5
  precise:       basic 4, lab 6, ok 8, xyz 8
  token/tokens:  basic 3, lab 5, ok 7, xyz 7

stage2_model_precision(mode):
  quick:   hue 0, percent 0, lab 1, ok 3, xyz 4, cmyk 0
  css:     hue 2, percent 2, lab 3, ok 5, xyz 5, cmyk 2
  precise: hue 3, percent 3, lab 5, ok 6, xyz 6, cmyk 3
  token:   hue 3, percent 3, lab 3, ok 5, xyz 6, cmyk 2

stage1_oklch_precision(mode):
  # Color Picker and Color Converter formatColorSetForPrecision()
  L_percent_places = stage1_precision(mode).lab
  chroma_places = stage1_precision(mode).ok
  hue_places = stage1_precision(mode).lab

stage2_oklch_precision(mode):
  # Color Model Comparison formatModelValues()
  L_percent_places = stage2_model_precision(mode).ok
  chroma_places = stage2_model_precision(mode).ok
  hue_places = stage2_model_precision(mode).hue

alpha_precision:
  picker_alpha_decimal = round(percent_input / 100, 3)
  picker_alpha_css_percent = round(alpha * 100, 1) + "%"
  css_generator_alpha_decimal = round(clamp(alpha_input, 0, 1), 2)
  opacity_css_alpha_number = round(alpha, 3)
  alpha_hex_byte = uppercase_hex(round(alpha * 255), 2 digits)

contrast_precision:
  rawRatio = wcag_ratio(foreground, background)
  ratio = round(rawRatio, 2)
  display ratio
  include rawRatio when exporting a full wcagScore object in JSON

tailwind_export_shape(tool):
  if tool is Color Picker or Color Converter:
    return CommonJS config fragment:
      module.exports.theme.extend.colors[slug] = scale
  if tool is Palette Generator:
    return ESM config fragment:
      export default.theme.extend.colors.palette = role_map

sass_export_shape(tool):
  if tool is Color Picker or Color Converter:
    return SCSS module:
      @use "sass:map"
      $color-[slug]: ("hex": ..., "foreground": ..., ...)
      @function color-[slug]($key)
      @mixin color-[slug]-vars($selector: ":root")
  if tool is Palette Generator:
    return SCSS module:
      @use "sass:map"
      $hue-codex-palette: ("primary": ..., "secondary": ..., ...)
      $hue-codex-palette-contrast: ("text-on-surface": ..., ...)
      @function hue-codex-color($role)
      @function hue-codex-contrast($pair)
      @mixin hue-codex-palette-vars($selector: ":root", $prefix: "color")
  compile behavior:
    snippet parses as SCSS
    maps and functions emit no CSS until consumed by project code
    included mixins emit CSS custom properties

css_fallback_order(property, fallbackValue, modernValue):
  emit property: fallbackValue first
  emit property: modernValue second
  # If modernValue is unsupported, the browser ignores that declaration.
  # If modernValue is supported, the later declaration wins by cascade order.

css_custom_property_fallback_order(name, fallbackValue, modernValue, supportsProbe):
  emit :root { name: fallbackValue }
  emit @supports (color: supportsProbe) { :root { name: modernValue } }
  # This avoids relying on unsupported modern color syntax stored inside a
  # custom property in older browsers.

format rule:
  normalize HEX first
  calculate with raw values
  round only at display/export boundaries

Export pages are not primarily mathematical, but these deterministic vectors make naming, normalization, and token-shape behavior testable.

Tools using this methodology

These Hue Codex tools link to this methodology because they depend on the formulas, assumptions, limits, or data policy described here.

Report a calculation issue

If a result does not match the documented formula or fixture, send the exact input, tool settings, displayed result, expected result, precision mode, and browser details. Please do not include private images, personal information, or secrets.