# How to Configure Brand Onboarding to Extract Colors from a Website URL in Diagram-Design

> Learn to configure brand onboarding in diagram-design. Extract website colors via URL using the agent-browser navigate command and map them to semantic roles in style-guide.md.

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

---

**Configure brand onboarding by running the `agent-browser navigate` command against your target URL, then approve the generated token diff to automatically map extracted colors to the [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) semantic roles.**

The **cathrynlavery/diagram-design** repository provides a complete brand onboarding pipeline that scrapes live websites to extract color palettes and typography. This process analyzes CSS custom properties, computed styles, and screenshot histograms to populate the [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) token table with brand-accurate values.

## The Five-Step Onboarding Pipeline

The URL-based onboarding flow is defined in [`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) and executes atomically across five stages:

### 1. Fetch the Page with Agent-Browser

The pipeline begins by treating the target URL as untrusted input. The system executes:

```bash
agent-browser navigate https://mybrand.com --screenshot /tmp/out.png --html /tmp/out.html

```

This command captures both the rendered page screenshot and raw HTML without executing remote directives. The trust-boundary validation in [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) ensures no remote code execution occurs during this step.

### 2. Extract Colors and Fonts

The system analyzes the fetched assets through three hierarchical methods:

- **Primary**: CSS custom properties from `:root { --accent: #hex; }`
- **Secondary**: `getComputedStyle` samples from semantic elements (`body`, `h1`, `<code>`)
- **Tertiary**: Color histogram analysis of the screenshot PNG

Font detection follows the same priority order, scanning for `font-family` declarations in computed styles.

### 3. Map to Semantic Roles

Extracted values are assigned to the diagram-design token architecture:

- `paper` (backgrounds)
- `ink` (primary text)
- `muted` (secondary text)
- `accent` (interactive elements)
- `paper-2` (elevated surfaces)
- `rule` (borders and dividers)

Low-confidence mappings are flagged for manual confirmation before proceeding to the diff stage.

### 4. Preview the Diff

A `git-style` diff of [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) displays proposed token changes. This view includes a **brand fidelity receipt** summarizing the extracted hex codes and font stacks. Users must explicitly approve this diff before the system writes any changes.

### 5. Apply and Save Profiles

Upon approval, the new tokens commit to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). Optionally, persist the configuration as a reusable client profile:

```bash
diagram-design profile save mybrand

```

This creates `~/.diagram-design/profiles/mybrand.md` and writes a `.diagram-design` marker file in the project root.

## Security and Trust Boundaries

The onboarding flow implements strict isolation between untrusted web content and the execution environment. The validation logic in [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) enforces that fetched HTML is parsed for token extraction only—no scripts execute, no external resources load, and no network requests originate from the analysis phase.

## CLI Commands and Automation

### Invoke Full Onboarding from Chat

```text
Onboard diagram-design to https://mybrand.com

```

The skill parses this command, launches the URL flow, and guides you through interactive diff approval.

### Debug with Manual Extraction

For troubleshooting brand detection:

```bash
agent-browser navigate https://mybrand.com --screenshot /tmp/out.png --html /tmp/out.html
python -m diagram_design.onboard --preview /tmp/tokens.json

```

The preview command prints the proposed changes to `paper`, `ink`, and `accent` values without writing to disk.

### Regenerate Examples

After applying new brand tokens, refresh all diagram examples:

```bash
/regenerate-examples

```

## Key Configuration Files

Understanding these source files ensures accurate customization:

- **[`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)**: Canonical specification of URL, Skill, and Folder onboarding flows
- **[`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md)**: Single source of truth for the token table (modified during Step 5)
- **[`references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/profiles.md)**: Mechanics for persisting customized skins as named client profiles
- **[`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py)**: Enforces trust boundaries and documentation synchronization

## Summary

- **Brand onboarding** scrapes live URLs to extract visual tokens automatically
- The **five-step pipeline** fetches, extracts, maps, previews, and commits color/font data to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)
- **Semantic roles** (`paper`, `ink`, `accent`, `muted`) structure the extracted values consistently
- **Trust boundaries** in [`verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-docs-sync.py) prevent remote code execution during fetching
- **Named profiles** persist brand configurations for reuse across projects via `diagram-design profile save`

## Frequently Asked Questions

### How does diagram-design handle websites without CSS custom properties?

When `:root` CSS variables are absent, the system falls back to `getComputedStyle` sampling from semantic HTML elements. If computed styles prove insufficient, it derives a histogram from the screenshot PNG to infer dominant and accent colors.

### Can I preview brand changes before they overwrite my style guide?

Yes. Step 4 generates a `git-style` diff showing exact changes to [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) token values. The system waits for explicit user approval before writing the new skin, preventing accidental overwrites.

### What is the brand fidelity receipt?

The **brand fidelity receipt** is a summary document generated during the preview stage. It lists every extracted hex code, font family, and confidence score, providing transparency into how the algorithm mapped raw website data to semantic roles like `paper` and `accent`.

### Where are saved brand profiles stored?

Saved profiles reside in `~/.diagram-design/profiles/[profilename].md`. The system creates a `.diagram-design` marker in your project root pointing to the active profile, allowing instant brand context switching between client projects.