URL-Based Brand Onboarding Validation Checks in Diagram-Design

URL-based brand onboarding enforces three mandatory validation checks—AA contrast ratios, accent saturation dominance, and paper-color purity—to ensure only accessible, visually coherent palettes are written to the style guide.

The cathrynlavery/diagram-design repository implements a structured URL onboarding pipeline that extracts brand colors from live websites and validates them before persisting any changes. According to the source code, the validation stage is explicitly defined in skills/diagram-design/references/onboarding.md and serves as the final gate before tokens are committed to style-guide.md.

AA Contrast Requirement

The first validation check enforces WCAG 2.1 Level AA accessibility standards for text legibility.

• Ink-on-paper contrast: The ratio between body text (ink) and background (paper) must be ≥ 4.5 : 1.
• Muted-on-paper contrast: The ratio between secondary text (muted) and background must also be ≥ 4.5 : 1.

If either ratio falls below this threshold, the onboarding flow raises a ValidationError and proposes an adjusted value with an explanation. This prevents committing inaccessible color combinations that would fail accessibility audits.

Accent Saturation Check

The second check ensures the accent color carries sufficient visual weight to function as a primary call-to-action or highlight.

The validation logic requires that:

• The accent token must be the most saturated color in the extracted palette.
• It cannot be a muted, near-grey, or low-saturation hue.

This constraint prevents weak accent colors that would fail to draw user attention in diagram layouts. The is_most_saturated() comparison runs against all extracted tokens to verify dominance.

Paper-Color Purity Guard

The third check addresses a specific usability concern with pure white backgrounds.

If the detected paper color equals #ffffff, the system automatically falls back to a warm-neutral default (#fafaf7) unless the user explicitly confirms pure white was intentional. This guard prevents:

• Harsh screen glare in dark environment usage
• Loss of subtle shadow depth in diagram components
• Unintentional "unfinished" aesthetic in exported assets

The fallback is logged and presented in the diff preview for user awareness.

Validation Implementation Example

The following Python pseudo-code distills the validation logic from the onboarding specification:

def validate_tokens(tokens):
    # 1️⃣ AA contrast checks

    if contrast(tokens['ink'], tokens['paper']) < 4.5:
        raise ValidationError("Ink-on-paper contrast too low")
    if contrast(tokens['muted'], tokens['paper']) < 4.5:
        raise ValidationError("Muted-on-paper contrast too low")

    # 2️⃣ Accent saturation check

    if not is_most_saturated(tokens['accent'], tokens.values()):
        raise ValidationError("Accent is not the most saturated color")

    # 3️⃣ Paper-pure-white guard

    if tokens['paper'].lower() == "#ffffff":
        tokens['paper'] = "#fafaf7"   # fallback to warm-neutral

        log("Paper was pure white; replaced with #fafaf7")
    return tokens

User Confirmation Flow

When validation proposes adjustments, the system presents a diff preview before applying changes:

- | `paper`  | #f5f4ed | #1c1a17 |
- | `ink`    | #0b0d0b | #f1efe7 |
- | `accent` | #f7591f | #ff6a30 |
+ | `paper`  | #f8f6f0 | #1a1815 |
+ | `ink`    | #111111 | #efeee7 |
+ | `accent` | #c73a2b | #e05440 |

Users may accept the suggested corrections or abort the operation. No changes are written to style-guide.md without explicit confirmation.

Key Source Files

The validation behavior is documented across these repository files:

File	Purpose
skills/diagram-design/references/onboarding.md	Full URL onboarding specification with validation constraints
skills/diagram-design/references/style-guide.md	Target file for validated brand tokens
skills/diagram-design/references/profiles.md	Reusable profile definitions for successful onboarding results

Summary

• AA contrast checks enforce 4.5:1 ratios for ink and muted against paper
• Accent saturation validation guarantees the accent is the palette's most saturated color
• Paper-color purity guard replaces #ffffff with #fafaf7 unless explicitly overridden
• All failures trigger proposed adjustments with explanations, not silent corrections
• Final authority rests with the user via diff preview confirmation

Frequently Asked Questions

What happens if the extracted colors fail the AA contrast check?

The onboarding flow raises a ValidationError with a specific message identifying which contrast pair failed. The system presents an adjusted color value that meets the 4.5:1 threshold and waits for user confirmation before proceeding.

Can I force pure white (#ffffff) as my paper color?

Yes, but only through explicit user confirmation. The paper-color purity guard defaults to #fafaf7 when pure white is detected, logging the replacement. To retain #ffffff, you must actively confirm this choice in the confirmation dialog.

How is "most saturated color" determined for the accent check?

The is_most_saturated() function compares the HSL saturation value of the accent token against all other extracted color tokens in the palette. If any other token has higher saturation, the validation fails and the system suggests the most saturated alternative.

Where are validated onboarding results stored?

Successful URL-based brand onboarding writes tokens to skills/diagram-design/references/style-guide.md. Additionally, the completed configuration can be saved as a reusable profile in skills/diagram-design/references/profiles.md for rapid reapplication across diagram projects.

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