# How to Set Up Client Profiles for Multiple Brands in Diagram Design

> Learn how to set up client profiles for multiple brands in Diagram Design. Keep your style guides separate and organized in the `~/.diagram-design/profiles/` directory.

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

---

**Diagram Design uses isolated client profiles stored in `~/.diagram-design/profiles/` to support multiple brand style-guides without modifying the core installation files.**

When managing design systems for multiple clients, you need to set up client profiles for multiple brands without risking your customizations during plugin updates. The Diagram Design system, as implemented in `cathrynlavery/diagram-design`, solves this by storing independent, full-copy style-guides outside the plugin directory according to the specifications in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md). These profiles contain complete brand configurations that override the default [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) only when explicitly requested via project markers.

## Understanding the Profile Architecture

The Diagram Design engine implements a resolution system that determines which style-guide to apply before every generation. This architecture ensures that plugin updates never erase client-specific customizations while allowing seamless switching between brand identities.

### The Resolution Mechanism

When generating diagrams, the engine performs a two-step resolution process defined in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md):

1. **Project Marker Check** – If the project root contains a hidden file named `.diagram-design` containing `profile: <slug>`, the engine reads the matching profile directly from `~/.diagram-design/profiles/<slug>.md` and completely bypasses the installed [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md).
2. **Marker-less Fallback** – Without a marker file, the engine checks the working copy of the installed style-guide. If this copy contains a leading profile header, that header identifies the active profile; otherwise, the engine compares the working copy against shipped defaults and treats any divergence as a custom-unsaved style-guide.

### Profile Storage and the Default Profile

All user-created profiles live in the `~/.diagram-design/profiles/` directory, separate from the plugin installation. The system reserves the slug `default` for the built-in snapshot of the pristine style-guide located at [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md). You cannot overwrite or delete the `default` profile, ensuring you always have a clean fallback. When the plugin updates, only this `default` snapshot regenerates, leaving your client profiles untouched.

## Profile File Format and Metadata Requirements

Each profile file is a complete copy of [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) plus a mandatory metadata comment at the top. The metadata is display-only and never interpreted as commands, containing:

- **Display name** – Human-readable brand identifier
- **Slug** – Unique identifier matching the regular expression `[a-z0-9][a-z0-9-]{0,63}`
- **Source URL** – Reference to brand assets
- **Creation and update dates** – Timestamps for version tracking
- **Optional notes** – Additional context for the design team

The slug validation logic in [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md) strictly enforces the regex pattern `[a-z0-9][a-z0-9-]{0,63}` to ensure filesystem compatibility and URL safety.

## Managing Brand Profiles via CLI

The `profile` command implements all profile-related verbs in [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md), enforcing strict validation and confirming destructive actions. These commands always re-read target files after writing to guarantee integrity.

### Creating and Saving Profiles

To set up a new brand profile, use the `save` verb with required metadata:

```bash

# Create a new profile for the "Acme" brand

diagram-design profile save acme \
  --name "Acme Corporation" \
  --source-url "https://acme.example.com" \
  --notes "Primary web brand"

```

This creates `~/.diagram-design/profiles/acme.md` and optionally writes a project marker in the current directory.

### Switching Between Brand Profiles

Switching profiles updates the `.diagram-design` marker in your project root:

```bash

# Switch the current project to the "acme" profile

diagram-design profile load acme

```

The `load` command (aliased as `switch`) writes the marker file or replaces an existing one after confirmation, as specified in the prompt metadata at [`prompts/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/profile.md). This ensures each project points to its specific brand configuration without affecting others.

### Listing, Updating, and Deleting Profiles

Maintain your brand library with these operations:

```bash

# List all saved profiles (shows active status)

diagram-design profile list

# Verify which profile is active for the current project

diagram-design profile show

# Update metadata after modifying style-guide tokens

diagram-design profile update acme \
  --notes "Added new accent colour"

# Remove obsolete brand configurations

diagram-design profile delete acme

```

The `update` command refreshes the profile metadata after you modify style-guide tokens, while `delete` permanently removes the profile file from `~/.diagram-design/profiles/` after confirmation.

## Project-Level Profile Assignment

The `.diagram-design` marker file establishes the link between a project directory and its brand profile. When this file contains `profile: <slug>`, the resolution engine in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md) resolves to that specific profile exclusively, ignoring the installed working copy entirely. This marker-based approach allows multiple projects to coexist on the same machine, each referencing different brand style-guides without configuration conflicts or path collisions.

## How Plugin Updates Protect Your Customizations

Because profiles reside in `~/.diagram-design/profiles/` rather than the plugin directory, **updates to the Diagram Design plugin never erase client-specific customizations**. The update process only regenerates the `default` snapshot based on the shipped [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md), leaving all named profiles intact. This design safely supports parallel brand configurations across multiple projects, with each project simply pointing to its own profile via the `.diagram-design` marker.

## Summary

- **Diagram Design stores client profiles** in `~/.diagram-design/profiles/` as complete, independent style-guide copies outside the plugin directory.
- **The resolution engine** checks for a `.diagram-design` marker file first, falling back to the working copy only when no marker exists.
- **Profile slugs** must match `[a-z0-9][a-z0-9-]{0,63}`, with `default` reserved for the immutable system snapshot.
- **CLI commands** (`save`, `load`, `list`, `show`, `update`, `delete`) enforce validation and confirm destructive actions before modifying files.
- **Plugin updates** only regenerate the `default` profile, ensuring your multi-brand configurations persist across versions.

## Frequently Asked Questions

### Where are client profiles stored on the filesystem?

Diagram Design saves all client profiles in the `~/.diagram-design/profiles/` directory within your home folder. Each profile is a separate Markdown file named after its slug (e.g., [`acme.md`](https://github.com/cathrynlavery/diagram-design/blob/main/acme.md)), containing the full style-guide body plus metadata headers. This location ensures your brand configurations survive plugin updates and reinstalls.

### What happens if a project doesn't have a `.diagram-design` marker file?

Without a marker file, the engine enters marker-less fallback mode. It examines the installed working copy of [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) for a leading profile header indicating the active profile. If no header exists, the engine compares the working copy against shipped defaults; any token differences cause it to treat the file as a custom-unsaved style-guide rather than a named profile.

### Can I delete or modify the default profile?

No. The slug `default` is reserved for the built-in snapshot of the pristine style-guide located at [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md). According to the validation logic in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md), the system prevents overwriting or deleting this profile to ensure you always have a clean, unmodified reference. When the plugin updates, only this default snapshot regenerates.

### How do I verify which brand profile is active in my current project?

Run `diagram-design profile show` from within your project directory. This command reads either the `.diagram-design` marker file in the project root or checks the profile header in the working style-guide copy, displaying the active profile's display name, slug, source URL, and last update timestamp without modifying any configuration.