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

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 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 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, 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 documentation defines the command-line interface for managing active profiles. You can query the current configuration using:

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

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:

# 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 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 — Documents the architectural decision and consequences for the marker-first resolution system.
• commands/profile.md — Defines the CLI interface for displaying and setting active profiles.
• prompts/profile.md — Contains prompt templates used by AI agents to assist users in profile creation and editing.
• 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 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.

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 file, as documented in 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 to help AI assistants guide users through creating and transferring these brand skin definitions between environments.

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