Contrast Ratio API: The Complete Guide to WCAG Color Accessibility

Need to ensure your color combinations meet accessibility standards? This guide covers everything you need to know about calculating WCAG contrast ratios programmatically via API, including compliance levels, use cases, and implementation examples in multiple languages.

What is Contrast Ratio?

Contrast ratio is a measure of the difference in luminance between two colors, typically text and its background. The ratio ranges from 1:1 (no contrast, same color) to 21:1 (maximum contrast, black on white).

For example, black text (#000000) on white background (#ffffff) has a contrast ratio of 21:1, while gray text (#767676) on white has approximately 4.54:1.

WCAG Standards Explained

The Web Content Accessibility Guidelines (WCAG) 2.1 define specific contrast requirements:

Level AA (Minimum)

Normal text: 4.5:1 minimum. Large text (18pt+ or 14pt+ bold): 3:1 minimum. This is the standard requirement for most websites.

Level AAA (Enhanced)

Normal text: 7:1 minimum. Large text: 4.5:1 minimum. Recommended for critical content and maximum accessibility.

Using the Contrast Ratio API

TinyFn provides a simple endpoint to calculate contrast ratios:

GET https://api.tinyfn.io/v1/color/contrast?foreground=%23000000&background=%23ffffff
Headers: X-API-Key: your-api-key

{
  "foreground": "#000000",
  "background": "#ffffff",
  "ratio": 21,
  "ratioString": "21:1",
  "compliance": {
    "aa": {
      "normalText": true,
      "largeText": true
    },
    "aaa": {
      "normalText": true,
      "largeText": true
    }
  }
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/color/contrast?foreground=%23333333&background=%23f5f5f5',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { ratio, compliance } = await response.json();
console.log(`Contrast ratio: ${ratio}:1`);
console.log(`AA compliant: ${compliance.aa.normalText}`);
// Contrast ratio: 10.69:1
// AA compliant: true

Python

import requests

response = requests.get(
    'https://api.tinyfn.io/v1/color/contrast',
    params={
        'foreground': '#333333',
        'background': '#f5f5f5'
    },
    headers={'X-API-Key': 'your-api-key'}
)
data = response.json()
print(f"Contrast ratio: {data['ratio']}:1")
print(f"AA compliant: {data['compliance']['aa']['normalText']}")
# Contrast ratio: 10.69:1
# AA compliant: True

cURL

curl "https://api.tinyfn.io/v1/color/contrast?foreground=%23333333&background=%23f5f5f5" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Design Systems: Validate color palette combinations for accessibility
• CMS Platforms: Warn users about low-contrast color choices
• Automated Testing: Include contrast checks in CI/CD pipelines
• Theme Generators: Ensure generated themes meet WCAG standards
• Accessibility Audits: Batch-check all color combinations on a site

Best Practices

1. Aim for AA minimum: 4.5:1 for normal text should be your baseline
2. Test real combinations: Check every text/background pair, not just palette colors
3. Consider hover states: Ensure interactive states also meet requirements
4. Don't rely on color alone: Use icons and patterns alongside color cues

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-color": {
      "url": "https://api.tinyfn.io/mcp/color/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all color tools available via MCP in our Color MCP Tools for AI Agents guide.