# WCAG Contrast Checking During Website Brand Extraction in Diagram-Design

> Automate WCAG contrast checking for website brand colors. Diagram-Design ensures your diagrams meet accessibility standards automatically during brand extraction.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: tutorial
- Published: 2026-09-09

---

**Diagram-Design automatically validates extracted brand colors against WCAG AA contrast standards during the onboarding workflow, ensuring all autogenerated diagrams meet accessibility requirements before rendering.**

The `cathrynlavery/diagram-design` repository implements an integrated accessibility pipeline that performs WCAG contrast checking during website brand extraction. When users request to match a target site's visual identity, the system scrapes CSS for brand tokens and immediately verifies contrast ratios before persisting any values. This ensures that diagrams rendered with extracted palettes maintain AA compliance for text and UI elements without requiring manual accessibility audits.

## Brand Onboarding and Contrast Verification Pipeline

The extraction process begins when a user requests to match a specific website. The skill fetches the target URL and scans the page's CSS to identify the most frequently used brand colors, including semantic tokens such as `accent`, `primary`, `cta`, `ink`, and `paper`. This logic is documented in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md), which defines the heuristic rules for token generation.

Before persisting these tokens, the system runs a mandatory contrast check defined in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). The `ink` token representing text must achieve a contrast ratio of at least **4.5 : 1** against the `paper` background to satisfy WCAG AA standards. For non-text UI elements larger than 11px, the `muted` token must meet the same threshold.

## Automated Contrast Correction

When a color fails the contrast verification, the system does not reject the brand extraction. Instead, it programmatically proposes an adjusted value that satisfies the required ratio and documents the change. This behavior is exercised by [`scripts/verify-dumbbell.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-dumbbell.py), which asserts correct contrast ratios for both fills and strokes across all diagram types.

The correction logic ensures that the final `ink` value contrasts adequately with `paper` before the tokens are written to the project's style guide. As noted in [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md), the skill records a "brand fidelity receipt" listing the final token values and the specific contrast ratios they satisfy, providing an audit trail for accessibility compliance.

## Implementation in the Codebase

The contrast verification is implemented through specific Python functions and verification scripts. The `diagram_design.brand` module provides `extract_brand()` for scraping and `verify_contrast()` for validation, including an `adjust()` method for automatic correction.

```python

# Example: Extract brand colors and enforce WCAG AA contrast

from diagram_design.brand import extract_brand, verify_contrast

brand_tokens = extract_brand(url="https://example.com")

# Verify that `ink` vs `paper` meets 4.5:1 contrast

if not verify_contrast(brand_tokens['ink'], brand_tokens['paper']):
    # Propose a compliant alternative

    brand_tokens['ink'] = verify_contrast.adjust(
        brand_tokens['ink'], brand_tokens['paper'], target=4.5
    )

# Write the verified tokens to style‑guide.md

with open("skills/diagram-design/references/style-guide.md", "a") as f:
    f.write(f"\nink: {brand_tokens['ink']}\npaper: {brand_tokens['paper']}\n")

```

The [`scripts/verify-dumbbell.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-dumbbell.py) script provides command-line validation for all diagram types:

```bash

# Run the built‑in verification script after onboarding

python scripts/verify-dumbbell.py --all

# Sample output

✔︎ ink vs paper contrast = 5.2:1 (AA compliant)
✘ accent vs paper contrast = 2.9:1 – adjusted to #e66c30

```

## Redundancy Guarantees for Accessibility

Beyond contrast checking, the system employs redundant encodings to ensure accessibility even when contrast ratios approach minimum thresholds. According to the type-specific reference files such as [`skills/diagram-design/references/type-bar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-bar.md) and [`skills/diagram-design/references/type-line.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-line.md), diagrams use labels, legend entries, and positional cues so that visual marks do not rely solely on color differentiation.

This multi-layered approach ensures that meaning is never conveyed by color contrast alone, providing additional safeguards for users with color vision deficiencies.

## Key Source Files for Contrast Verification

The following files govern the WCAG contrast checking implementation:

- **[`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)** — Defines the brand extraction workflow and token heuristics
- **[`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)** — Contains the semantic token definitions and the "Contrast" section specifying the 4.5:1 ratio requirement
- **[`scripts/verify-dumbbell.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-dumbbell.py)** — Enforces contrast ratios for fills and strokes across diagram types
- **[`skills/diagram-design/references/type-bar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-bar.md)** and **[`type-line.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-line.md)** — Detail redundancy strategies for specific chart types
- **[`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md)** — Documents the brand fidelity receipt and WCAG AA verification requirements (lines 144 and 226)

## Summary

- **Immediate Validation**: The `diagram-design` skill checks WCAG AA contrast ratios immediately after extracting brand colors from a target website, preventing non-compliant palettes from entering the rendering pipeline.
- **Strict Ratios**: Text tokens (`ink`) must achieve a 4.5:1 contrast ratio against background tokens (`paper`), while non-text UI elements using the `muted` token must meet the same threshold.
- **Automatic Correction**: When extraction yields insufficient contrast, the `verify_contrast.adjust()` method proposes compliant alternatives rather than failing silently.
- **Comprehensive Testing**: The [`verify-dumbbell.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-dumbbell.py) script validates contrast for fills and strokes across all diagram types, ensuring consistent accessibility.
- **Redundant Encoding**: Type-specific documentation mandates redundant visual cues (labels, legends) to prevent reliance on color alone.

## Frequently Asked Questions

### What contrast ratio does Diagram-Design enforce for text elements?

Diagram-Design enforces a **4.5 : 1** contrast ratio for text elements, as defined in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). This applies specifically to the `ink` token (text) against the `paper` token (background) to meet WCAG AA standards.

### How does the tool handle colors that fail WCAG contrast checks?

When extracted colors fail verification, the system invokes the `verify_contrast.adjust()` method to propose a modified color value that satisfies the required ratio. This adjustment is documented in the output and stored in the brand fidelity receipt, ensuring the final palette is compliant without manual intervention.

### Where is the contrast verification logic documented?

The contrast rules are documented in **[`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)** under the "Contrast" section, while the implementation logic resides in **[`scripts/verify-dumbbell.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-dumbbell.py)**. The [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) (lines 144 and 226) also references the brand fidelity receipt and verification requirements.

### Does Diagram-Design verify contrast for all diagram types?

Yes. The [`scripts/verify-dumbbell.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-dumbbell.py) script validates contrast ratios across all diagram types, checking both fills and strokes. Additionally, type-specific reference files like [`type-bar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-bar.md) and [`type-line.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-line.md) document how each chart type implements redundant encodings to supplement contrast requirements.