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

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. These profiles contain complete brand configurations that override the default 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:

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.
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. 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 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 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, 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:

# 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:

# 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. 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:

# 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 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, 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), 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 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. According to the validation logic in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}