# URL-Based Brand Onboarding Validation Checks in Diagram-Design

> Discover URL-based brand onboarding validation checks: AA contrast, accent saturation, and paper color purity ensure accessible and coherent palettes for your style guide.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-16

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) and serves as the final gate before tokens are committed to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```python
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:

```diff
- | `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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) | Full URL onboarding specification with validation constraints |
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Target file for validated brand tokens |
| [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) for rapid reapplication across diagram projects.