Legibility

Each color may include a legibility object to describe its perceptual properties.
This helps consumers choose appropriate foreground text colors and assess contrast.

Properties

luminance (optional)

• Type: number
• Range: 0 ≤ value ≤ 1
• Purpose: relative luminance of the color, following WCAG definitions.

contrastVsWhite (optional)

• Type: number
• Minimum: 1
• Maximum: 21
• Purpose: contrast ratio of the color against pure white.

contrastVsBlack (optional)

• Type: number
• Minimum: 1
• Maximum: 21
• Purpose: contrast ratio of the color against pure black.

preferredText (optional)

• Type: string
• Allowed values: light, dark
• Purpose: guidance for whether light or dark text is more legible over this color.

WCAG Contrast Ratios

Contrast ratios follow the WCAG 2.x standard, which defines ratios on a scale from 1:1 (no contrast) to 21:1 (maximum contrast between pure white and pure black in sRGB).

These values are computed for the sRGB color space. HDR displays or other contrast metrics (e.g., APCA) would require different fields and are not currently supported.

Examples

{
  "id": "brand-blue",
  "hex": "#1269F2",
  "legibility": {
    "luminance": 0.28,
    "contrastVsWhite": 3.2,
    "contrastVsBlack": 12.5,
    "preferredText": "light"
  }
}

Usage guidance

• luminance and contrast ratios are numeric hints; different consumers may calculate them differently.
• preferredText is a high-level recommendation that can be applied directly in UIs.
• These fields are optional — if absent, consumers should calculate or infer legibility as needed.

Next steps

You’ve reached the end of the Specification section.
Check out Examples to see PaletteJSON used in practice.