WCAG Contrast Checking During Website Brand Extraction in Diagram-Design

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, 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. 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, 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, 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.

# 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 script provides command-line validation for all diagram types:

# 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 and 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 — Defines the brand extraction workflow and token heuristics
• 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 — Enforces contrast ratios for fills and strokes across diagram types
• skills/diagram-design/references/type-bar.md and type-line.md — Detail redundancy strategies for specific chart types
• 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 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. 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 under the "Contrast" section, while the implementation logic resides in scripts/verify-dumbbell.py. The 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 script validates contrast ratios across all diagram types, checking both fills and strokes. Additionally, type-specific reference files like type-bar.md and type-line.md document how each chart type implements redundant encodings to supplement contrast requirements.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}