# How to Use Client Profiles to Save and Apply Brand Skins in Diagram-Design

> Learn how Diagram Design client profiles save and apply brand skins, storing style-guide snapshots to ensure consistent visual identity across all your projects.

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

---

**Diagram-Design uses client profiles as self-contained style-guide snapshots stored in `~/.diagram-design/profiles/` to persist and automatically apply brand-specific visual identities across projects.**

The `cathrynlavery/diagram-design` repository implements a robust client profile system that enables users to save and apply brand skins through marker-first resolution. These profiles capture complete style-guide definitions—including color palettes, typography, and spacing rules—as portable plain-text files. Understanding how client profiles save and apply brand skins allows teams to maintain consistent visual identity across diagrams while ensuring configurations survive software updates.

## What Are Client Profiles?

**Client profiles** are self-contained snapshots that represent a brand’s complete visual identity within Diagram-Design. Each profile encapsulates semantic roles, color definitions, font families, and spacing configurations as a single reusable unit. Rather than modifying the default [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) directly, users create named profiles that can be instantly activated per project or shared across installations.

## Storing Brand Skins in Client Profiles

### Profile Storage Location

When you create a profile, Diagram-Design writes it to your home directory under `~/.diagram-design/profiles/`. Each profile exists as a plain-text Markdown file containing a **metadata header** that names the profile and a body section that defines the full style-guide rules. This location remains outside the installed plugin directory, ensuring your brand configurations persist independently of the core software installation.

### File Structure and Schema Validation

Every profile file follows a structured format with YAML front-matter defining the profile slug and display name, followed by the style-guide definition. Upon loading, Diagram-Design validates the profile against the current **semantic-role and typography schema**. Missing entries are automatically back-filled from shipped defaults, guaranteeing that older profiles remain functional even as the core schema evolves in future versions.

## Applying Brand Skins with Marker-First Resolution

### Project Marker Files

Diagram-Design implements **marker-first resolution** to determine which brand skin to apply. A project can include an optional marker file named `.diagram-design` at its root directory. This marker contains a simple slug that directly selects one of the saved profiles from your `~/.diagram-design/profiles/` directory.

### Resolution Logic

When Diagram-Design starts, it checks for the presence of this marker file:

- **If the marker exists**, the corresponding profile loads **immediately**, guaranteeing that diagram rendering uses the brand-specific skin without modifying any working files.
- **If the marker is absent**, Diagram-Design falls back to a **marker-less load**, which copies the chosen profile into the installed working [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) file. This fallback path respects the profile’s definitions while adding a safety copy-step.

According to [`docs/adr/0006-client-profiles-and-marker-first-resolution.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0006-client-profiles-and-marker-first-resolution.md), this design decision ensures deterministic brand application while maintaining flexibility for projects that do not use version-controlled markers.

### CLI Profile Management

The [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md) documentation defines the command-line interface for managing active profiles. You can query the current configuration using:

```bash

# Display the currently active profile

$ diagram-design profile
Active profile: my-brand

```

This command reads the metadata from your `~/.diagram-design/profiles/` directory and reports which brand skin is currently loaded.

## Persistence and Sharing

### Survival Across Updates

Because profiles live in your user home directory rather than the plugin installation folder, they **survive plugin upgrades completely intact**. The software never overwrites the `~/.diagram-design/profiles/` directory during updates, ensuring your brand skins remain available regardless of core software version changes.

### Sharing Between Installations

Profile files are simple, inspectable text files, making them ideal for sharing between team members or AI agents. You can distribute a brand skin by copying the profile file from `~/.diagram-design/profiles/` and transferring it to another installation. The [`prompts/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/profile.md) file contains templates used by AI assistants like Claude or Codex to guide users through creating and editing these shareable profile files.

## Implementation Examples

### Loading a Profile Programmatically

The following Python example illustrates how Diagram-Design loads profile files from the storage location:

```python
from pathlib import Path
import yaml

HOME = Path.home()
PROFILES_DIR = HOME / ".diagram-design" / "profiles"

def load_profile(slug: str):
    profile_path = PROFILES_DIR / f"{slug}.md"
    if not profile_path.exists():
        raise FileNotFoundError(f"Profile {slug} not found")
    
    # Read the markdown file, extract the YAML front-matter header

    raw = profile_path.read_text(encoding="utf-8")
    header, _, body = raw.partition("---\n")
    metadata = yaml.safe_load(header)
    
    # Validate against current schema (validation logic omitted for brevity)

    return {"metadata": metadata, "style_guide": body}

```

### Creating a Project Marker

To automatically apply a specific brand skin to a project, create the marker file:

```bash

# Add a marker to select the 'my-brand' profile automatically

echo "my-brand" > .diagram-design

```

### Synchronization Testing

The repository includes [`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py) as a test harness to ensure that profile reference files remain synchronized with the documentation. This validation guarantees that the client profile system behaves consistently across different installation environments.

## Key Implementation Files

Several critical files define how client profiles save and apply brand skins:

- **[`docs/adr/0006-client-profiles-and-marker-first-resolution.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0006-client-profiles-and-marker-first-resolution.md)** — Documents the architectural decision and consequences for the marker-first resolution system.
- **[`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md)** — Defines the CLI interface for displaying and setting active profiles.
- **[`prompts/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/profile.md)** — Contains prompt templates used by AI agents to assist users in profile creation and editing.
- **[`scripts/verify-docs-sync.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-docs-sync.py)** — Test harness ensuring profile documentation and implementation remain synchronized.

## Summary

- **Client profiles** are stored as plain-text Markdown files in `~/.diagram-design/profiles/` with YAML metadata headers defining the brand identity.
- **Marker-first resolution** uses a `.diagram-design` file at the project root to immediately load specific brand skins, falling back to copying profiles into [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) when markers are absent.
- **Schema validation** automatically back-fills missing entries from defaults, ensuring backward compatibility as the core software evolves.
- **Persistence across updates** is guaranteed because profiles reside outside the plugin directory, surviving version upgrades without modification.
- **Sharing capabilities** allow brand skins to move between installations as simple text files, supported by AI agent prompts in [`prompts/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/profile.md).

## Frequently Asked Questions

### Where are client profiles stored in Diagram-Design?

Client profiles are stored in the `~/.diagram-design/profiles/` directory within your home folder. Each profile is a plain-text Markdown file containing a YAML front-matter header with metadata and a body section defining the style-guide rules. This location ensures profiles persist across plugin updates since it resides outside the installation directory.

### How does Diagram-Design know which brand skin to apply to a project?

Diagram-Design uses **marker-first resolution** to select brand skins. If a project contains a `.diagram-design` marker file at its root with a profile slug inside, the system loads that specific profile immediately. Without a marker, the software falls back to a marker-less load that copies the active profile into the working [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) file, as documented in [`docs/adr/0006-client-profiles-and-marker-first-resolution.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0006-client-profiles-and-marker-first-resolution.md).

### What happens to my brand skins when I update the Diagram-Design plugin?

Your brand skins remain completely intact during updates. Because profiles live in your user home directory (`~/.diagram-design/profiles/`) rather than the plugin installation folder, the software never overwrites them during upgrades. This design ensures long-term persistence of your visual identity configurations regardless of core schema changes.

### Can I share client profiles between different machines or team members?

Yes, client profiles are designed for easy sharing. Since they are simple, inspectable text files, you can copy them directly from `~/.diagram-design/profiles/` and distribute them to other installations. The repository includes [`prompts/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/profile.md) to help AI assistants guide users through creating and transferring these brand skin definitions between environments.