# Where Are Named Client Profiles Stored in diagram-design? Complete Guide to Profile Location and Management

> Discover where named client profiles are stored in diagram-design. Learn to manage these Markdown files located in ~/.diagram-design/profiles/ for your style guides.

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

---

**Named client profiles in diagram-design are stored as individual Markdown files in `~/.diagram-design/profiles/`, with each profile named as `<slug>.md` containing a metadata header and complete style guide.**

The diagram-design repository by cathrynlavery manages visual consistency across projects through **client profiles** — reusable style configurations that define colors, fonts, and design rules. Understanding where these profiles live on your filesystem is essential for backup, version control, and team collaboration workflows.

## Profile Storage Location and File Structure

### Primary Directory: `~/.diagram-design/profiles/`

Diagram-design maintains a **profile library** in your home directory under a hidden folder. This location ensures profiles persist across project directories and remain isolated from the installed plugin code.

| Aspect | Specification |
|--------|---------------|
| **Base directory** | `~/.diagram-design/profiles/` |
| **File format** | Markdown (`.md` extension) |
| **Naming convention** | `<slug>.md` (kebab-case identifier) |
| **Example path** | `~/.diagram-design/profiles/acme-corp.md` |

### Profile File Contents

Each `.md` file combines **YAML frontmatter metadata** with free-form Markdown content:

- **Required metadata header**: `profile`, `created`, `source-url`
- **Body**: Complete style guide documentation for that client

The built-in **default profile** exists at `~/.diagram-design/profiles/default.md` but is **read-only** — the system prevents overwriting this file to preserve baseline functionality during updates.

## Profile Resolution Mechanism

When diagram-design encounters a `.diagram-design` marker file specifying `profile: <slug>`, it resolves the profile through a direct filesystem lookup:

1. Parse the `profile` value from the project marker
2. Construct path: `~/.diagram-design/profiles/<slug>.md`
3. Load and validate the file contents

This **library-first resolution** means multiple projects can reference the same client profile without duplicating files, while升级s to diagram-design itself never touch your custom profiles.

## Working with Stored Profiles: Code Examples

### Load a Client Profile Programmatically

```python

# Locate and read an existing client profile

import os
from pathlib import Path

home = Path.home()
profile_path = home / ".diagram-design" / "profiles" / "acme-corp.md"

if profile_path.is_file():
    with profile_path.open(encoding="utf-8") as f:
        profile_contents = f.read()
    print("Profile loaded:", profile_path)
else:
    print("Profile not found:", profile_path)

```

### Create a New Profile via Command Line

```bash

# Initialize the profiles directory if needed

mkdir -p ~/.diagram-design/profiles

# Create a profile with required metadata header

cat > ~/.diagram-design/profiles/my-client.md <<'EOF'
profile: my-client
created: 2026-09-06
source-url: none

# My-Client Style Guide

## Colors

- Primary: #2E5BFF
- Secondary: #FF6B2E

## Typography

- Headings: Inter Bold
- Body: Inter Regular
EOF

# Optional: associate with current project

echo "profile: my-client" > .diagram-design

```

### List All Available Profiles

```bash

# View all stored client profiles

ls ~/.diagram-design/profiles/*.md

```

## Core Source Files Defining Profile Storage

According to the diagram-design source code, these files govern how profiles are stored, formatted, and accessed:

| File | Purpose |
|------|---------|
| [`references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/profiles.md) | **Specification document** defining library location, file format, and resolution rules |
| [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md) | CLI implementation for `list`, `save`, `load`, `update`, `reset`, `delete` operations |
| [`prompts/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/profile.md) | Interactive prompt definitions guiding profile management workflows |
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Entry point explaining profile resolution and `.diagram-design` marker interaction |

The [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md) reference specification is the authoritative source for storage conventions, while [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md) provides the user-facing interface for manipulating files in `~/.diagram-design/profiles/`.

## Migration and Backup Considerations

Since profiles live in your home directory rather than project repositories:

- **Back up** `~/.diagram-design/profiles/` to preserve client configurations
- **Sync across machines** using dotfiles repositories or cloud storage
- **Version control** individual profiles by tracking the `.md` files externally

The read-only [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) ensures you always have a fallback, but custom profiles depend entirely on this directory's integrity.

## Summary

- **Named client profiles are stored in `~/.diagram-design/profiles/`** as `<slug>.md` Markdown files
- Each profile contains a **required metadata header** (`profile`, `created`, `source-url`) plus style guide content
- The **default profile** at [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) is read-only and protected from overwrites
- Profile resolution bypasses the installed working copy, enabling **shared installations across multiple clients**
- Core specifications live in [`references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/profiles.md) with CLI operations defined in [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md)

## Frequently Asked Questions

### Can I change the default profile storage location?

No. The `~/.diagram-design/profiles/` path is hardcoded in the resolution logic defined in [`references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/profiles.md). The system relies on this consistent location to locate profiles regardless of where diagram-design is installed or invoked.

### What happens if I delete a profile referenced by a project?

The project marker still specifies `profile: <slug>`, but profile resolution will fail at runtime. The [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md) CLI does not validate cross-references when deleting — maintain your own tracking or use the `list` command to audit usage before removal.

### How do I share client profiles with my team?

Since profiles exist outside version control, share the `.md` files directly. Copy files into `~/.diagram-design/profiles/` on each teammate's machine, or symlink the directory to a shared cloud storage location. The specification in [`references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/profiles.md) does not currently support remote profile fetching.