# How a Multi-Client Workflow Supports Different Brands for Parallel Workspaces in Diagram Design

> Learn how a multi client workflow supports different brands for parallel workspaces in diagram design. Use one installation for multiple projects with external brand profiles.

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

---

**A hidden marker file (`.diagram-design`) lets each project reference an external brand profile, so many workspaces share one installation while each uses its own visual tokens.**

Diagram Design implements a **profile-based isolation system** that separates brand identity from the core skill installation. This architecture enables agencies and freelancers to manage multiple client brands inside parallel project folders without conflicts. The mechanism centers on two components: **profiles** stored in the user's home directory and **project markers** that dynamically resolve which profile to load.

## How Brand Profiles Work

A **profile** is a standalone Markdown file containing a complete brand token table plus metadata. Profiles live in `~/.diagram-design/profiles/<slug>.md`, outside the installed skill directory. This location ensures that:

- Profile data survives skill updates
- Multiple workspaces reference the same profile without duplication
- No client tokens leak into the default [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md)

### Profile Structure

Each profile contains the same token categories as [[`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md): paper (backgrounds), ink (text), accent (highlights), and font stacks. A small YAML header tracks the profile slug and creation date.

## The Five-Step Multi-Client Workflow

The workflow defined in [[`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) connects brand extraction to project-specific rendering:

### 1. Onboard the Brand

The skill fetches a client website, extracts color palettes and typography, and writes tokens to [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md). This process is documented in [[`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md).

```bash

# Extract brand from website

onboard diagram-design to https://acme.com

```

### 2. Save as Named Profile

The `save <slug>` command copies the current style guide into `~/.diagram-design/profiles/<slug>.md`, preserving the token table and adding metadata headers.

```bash

# Save current brand under a client slug

/diagram-design:profile save acme

```

### 3. Create Project Marker

A hidden file `.diagram-design` in the project root contains one line: `profile: <slug>`. The skill reads this marker **before every generation** to determine which profile to load.

```bash

# Add marker inside client project folder

echo "profile: acme" > .diagram-design

```

### 4. Generate Client-Branded Diagrams

On each request, the skill resolves the profile from the marker, merges any missing rows from shipped defaults (schema back-filling), and renders with client-specific colors and fonts. The installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) remains untouched.

```bash

# Diagram automatically uses Acme brand

Make me an architecture diagram of my app

```

### 5. Switch or Update Brands

- **`load <slug>`** — replaces the marker (or overwrites local [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) if no marker exists)
- **`update <slug>`** — rewrites an existing profile with latest tokens

```bash

# Switch to different client in same workspace

/diagram-design:profile load beta-corp

# Update profile after style guide tweaks

/diagram-design:profile update acme

```

## How Parallel Workspaces Coexist

The marker-plus-profile design enables **true workspace parallelism**:

| Workspace | Marker Content | Profile Loaded |
|-----------|--------------|----------------|
| `/projects/acme-web/` | `profile: acme` | `~/.diagram-design/profiles/acme.md` |
| `/projects/beta-corp-api/` | `profile: beta-corp` | `~/.diagram-design/profiles/beta-corp.md` |
| `/projects/internal-tool/` | *(none)* | [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) (default) |

Both client projects share the same skill installation at `skills/diagram-design/` but render with completely independent visual identities. Because markers are **plain-text files**, they travel with the project repository—clone the repo on any machine with Diagram Design installed, and the correct brand loads automatically.

## Resolution and Validation Guarantees

The resolution logic in [[`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) provides three safety mechanisms:

- **Fallback behavior** — Missing or malformed markers are ignored; generation continues with default tokens
- **Schema validation** — Profiles are checked against the skill's current schema on every generation; new token rows added in later releases are back-filled automatically
- **Installation integrity** — The shipped [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) is only modified when `load` runs without a marker present

## Command Reference for Multi-Client Management

All commands route through [[`skills/diagram-design/commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/commands/profile.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/commands/profile.md):

```bash

# List all saved profiles

/diagram-design:profile list

# Save current style guide as new profile

/diagram-design:profile save <slug>

# Load profile into current project (creates or updates marker)

/diagram-design:profile load <slug>

# Update existing profile from current style guide

/diagram-design:profile update <slug>

# Remove a profile

/diagram-design:profile remove <slug>

```

These slash-commands function across all supported host agents (Claude Code, Codex, Factory Droid, Pi, etc.).

## Key Files in the Multi-Client Architecture

| File | Purpose |
|------|---------|
| [[`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) | Profile library format, marker resolution, verb definitions |
| [[`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md) | URL-to-tokens extraction flow |
| [[`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Default token table and schema reference |
| [[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Agent entry point for command routing |
| [[`skills/diagram-design/commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/commands/profile.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/commands/profile.md) | Concrete `/profile` command implementation |

## Summary

- **Profiles** isolate brand tokens in `~/.diagram-design/profiles/<slug>.md`, outside the skill installation
- **Project markers** (`.diagram-design` files) resolve which profile to load for each workspace
- **Parallel workspaces** share one Diagram Design installation while each renders with distinct client branding
- **Schema validation** ensures profiles stay compatible as the skill evolves
- **Fallback logic** protects against missing markers by defaulting to shipped tokens

## Frequently Asked Questions

### What happens if a project has no `.diagram-design` marker?

The skill ignores the missing file and falls back to the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) at [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md). Generation proceeds with default tokens.

### Can multiple projects use the same profile simultaneously?

Yes. Profiles are read-only during generation. Any number of project markers can point to `profile: acme`, and all will render with identical branding.

### How do I move a branded project to another machine?

Copy the project folder including the hidden `.diagram-design` marker. On the new machine, ensure the same profile slug exists in `~/.diagram-design/profiles/`. If absent, re-run `onboard` and `save` to recreate it.

### Will updating the Diagram Design skill affect my saved profiles?

No. Profiles live in your home directory, completely outside `skills/diagram-design/`. Skill updates only modify the installation directory. However, newer skill versions may introduce new token categories—these are automatically back-filled into existing profiles during the next generation.