# How diagram-design Supports Multi-Client Workflows with Named Profiles

> Diagram-design uses named profiles to manage multi-client workflows. Isolate client branding colors fonts and diagram settings in separate style-guide files for seamless project management.

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

---

**Diagram-design enables a single installation to serve multiple clients through named profiles—independent style-guide files stored in `~/.diagram-design/profiles/` that isolate each client's branding, colors, fonts, and diagram settings.**

Multi-client creative work demands strict separation between brand identities. Diagram-design solves this with a **profile-based architecture** that keeps each client's style guide independent from the core plugin files. According to the `cathrynlavery/diagram-design` source code, profiles are plain Markdown files with hidden headers containing metadata, allowing teams to switch between client configurations instantly without risking cross-contamination or data loss during updates.

## Understanding Named Profiles in diagram-design

A **named profile** is a self-contained style guide stored outside the plugin installation. Each profile exists as `<slug>.md` in `~/.diagram-design/profiles/` and contains:

- A hidden **profile header** with `name`, `slug`, `source-url`, creation dates, and notes
- The complete **style-guide body** with semantic roles and typography rules

This separation guarantees that plugin updates never touch client profiles. The installed [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) remains the working copy, while the profile library persists safely in the user's home directory.

## Profile Resolution: How diagram-design Selects the Active Style Guide

The system determines which profile to apply through a strict three-tier resolution order, as implemented in the core resolution logic:

### 1. Project Marker (Highest Priority)

Diagram-design checks for a `.diagram-design` file in the project root. If found, it reads the `profile: <slug>` line and loads that profile directly from the home library.

```bash

# Example marker file at <project-root>/.diagram-design

profile: acme-corp

```

This **marker-based approach** makes profile selection portable—the configuration travels with the project, enabling parallel workspaces for different clients without file conflicts.

### 2. Working Copy Header (Fallback)

If no marker exists, the system inspects [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) for a profile header. The header's `slug` field identifies the active profile.

### 3. Default Comparison (Final Fallback)

When neither marker nor header is present, diagram-design compares the installed style guide against shipped defaults. Semantic or typographic differences indicate a **custom-unsaved style**, which the user can persist as a new profile.

## Profile Isolation and Safety Mechanisms

The architecture enforces strict boundaries between clients. These safety checks operate at every stage:

| Step | Action | Safety Guard |
|------|--------|------------|
| **Resolve marker** | Parse `profile: <slug>` from `.diagram-design` | Validates against regex `[a-z0-9][a-z0-9-]{0,63}`; rejects malformed or unknown slugs |
| **Load profile** | Open `~/.diagram-design/profiles/<slug>.md` | Verifies structural integrity; back-fills missing rows from defaults |
| **Copy-over** | Write profile to installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) | Re-reads to confirm exact match; offers marker-only flow if unwritable |
| **Save** | Create new profile from effective guide | Blocks `default` overwrite; requires confirmation for existing profiles |
| **Update** | Refresh existing profile header | Preserves original `created` date; refuses `default` modification |
| **Delete** | Remove profile file | Warns if markers or headers still reference the profile; never glob-deletes |

## CLI Commands for Multi-Client Workflows

The [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md) implementation provides direct control over profile operations:

```bash

# List all saved profiles

diagram-design profile list

# Save current style guide as new client profile

diagram-design profile save acme

# Create project marker for "acme" profile (recommended)

diagram-design profile load acme

# Display active profile in current project

diagram-design profile show

# Update profile after style guide edits

diagram-design profile update acme

# Remove obsolete client profile

diagram-design profile delete acme

```

### Direct Installation Switching (No Marker)

For workflows that don't use project markers:

```bash

# Overwrite installed style guide with "acme" profile

diagram-design profile switch acme

```

The `switch` command bypasses marker creation entirely, useful for single-client environments or quick previews.

## Key Implementation Files

Two source files define the complete multi-client system:

- **[`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)** — Profile specification covering file format, slug validation rules, and structural checks
  https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md

- **[`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md)** — CLI verb documentation for `save`, `load`, `list`, `show`, `update`, `reset`, and `delete` operations
  https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md

## Summary

- **Named profiles** in diagram-design are isolated Markdown files stored in `~/.diagram-design/profiles/`
- **Project markers** (`.diagram-design` files with `profile: <slug>`) enable portable, client-specific configurations
- **Three-tier resolution** checks markers first, then headers, then defaults to determine the effective style guide
- **Safety mechanisms** prevent `default` profile deletion, enforce slug validation, and warn against orphaned profile references
- **Plugin updates remain safe** because profiles live outside the installation directory

## Frequently Asked Questions

### How do I set up a new client workspace in diagram-design?

Run `diagram-design profile save <client-slug>` to capture your current style guide as a profile. Then run `diagram-design profile load <client-slug>` within the client's project directory to create a `.diagram-design` marker file. This binds the project to that profile permanently.

### What happens to my profiles when I update the diagram-design plugin?

Nothing. Profiles reside in `~/.diagram-design/profiles/`, completely outside the plugin installation. Updates only modify shipped files, leaving your client library untouched.

### Can two projects use different profiles simultaneously?

Yes. Each project with its own `.diagram-design` marker file resolves its profile independently. The installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) is only modified when you explicitly run `load` or `switch` commands without markers.

### Why does diagram-design block overwriting the "default" profile?

The `default` profile serves as the immutable reference point. Blocking modifications ensures every custom profile derives from a known baseline and prevents accidental corruption of the system's fallback configuration.