# How to Create and Manage Client Brand Profiles with the Marker System in Diagram Design

> Learn to create and manage client brand profiles using the marker system in Diagram Design. Apply specific branding to workspaces automatically with this efficient workflow.

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

---

**Diagram Design stores branding configurations in reusable named profiles within `~/.diagram-design/profiles/` and uses a project marker file (`.diagram-design`) containing `profile: <slug>` to automatically apply the correct brand to each workspace without modifying the core style guide.**

The cathrynlavery/diagram-design repository provides a robust system for managing client brand identities through persistent profiles and project-specific markers. Instead of repeatedly editing the base [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) file for different clients, you can create and manage client brand profiles with the marker system to maintain immutable skill installations while delivering fully branded diagrams across multiple projects.

## Understanding the Profile Architecture

### The Profile Library

Profiles are stored as individual Markdown files in the user configuration directory. According to [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md), each profile resides at `~/.diagram-design/profiles/<slug>.md` and contains a metadata header followed by the complete style guide body. The system automatically generates a [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) profile that mirrors the pristine shipped style guide upon first use.

### The Project Marker File

The marker system relies on a file named `.diagram-design` placed at the project root. This file adheres to a strict grammar: a single line reading `profile: <slug>` where the slug matches the filename (lower-case, alphanumeric-hyphen, maximum 64 characters). The skill treats this file as untrusted data and ignores malformed markers with explanatory warnings.

## Creating and Saving Brand Profiles

To capture the current effective style guide as a reusable profile, use the `/profile` command with the `save` verb. This creates a new file in the profile library with the required metadata header (`<!-- diagram-design-profile … -->`) and the full body of [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).

```bash

# Save current brand configuration as "acme-corp" profile

/diagram-design:profile save acme-corp

```

The CLI prompts for a display name and optional source URL during creation. The resulting file schema is validated against the current semantic role table and typography table, with missing rows automatically backfilled from shipped defaults.

## Selecting Profiles with Project Markers

After creating a profile, apply it to a specific project by creating the marker file. This enables **marker-first resolution**, where the skill reads the profile directly instead of the installed style guide before every generation.

```bash

# Create marker file for the "acme-corp" profile

echo "profile: acme-corp" > /path/to/project/.diagram-design

```

This approach guarantees that parallel workspaces can use different brand skins without overwriting each other, as the marker is processed prior to any style guide copy-over operations.

## Profile Resolution and Validation

The resolution logic, as implemented in the skill entry point ([`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)), follows a strict hierarchy:

```python
def resolve_style_guide(project_root):
    marker_path = os.path.join(project_root, ".diagram-design")
    if os.path.exists(marker_path):
        slug = read_marker(marker_path)  # validates "profile: <slug>"

        profile_path = os.path.expanduser(f"~/.diagram-design/profiles/{slug}.md")
        if os.path.isfile(profile_path):
            return read_file(profile_path)  # marker-first direct read

    # Fallback to installed style-guide.md

    return read_file(installed_dir / "references/style-guide.md")

```

Every profile undergoes schema-aware validation against the current skill version. If structural changes are detected, the user is offered an `update` command to persist repairs while maintaining backward compatibility.

## Managing Profiles via CLI Commands

The `/profile` command interface (defined in [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md)) implements seven verbs for comprehensive profile management:

- **list**: Display all available profiles in the library
- **save**: Persist current style guide as a new named profile  
- **load|switch**: Change the active profile for the current project by updating the marker
- **show**: Display the currently active profile (checks marker first, then style guide)
- **update**: Repair profile structure against current schema
- **reset**: Restore profile to default state
- **delete**: Remove a profile from the library

All write, delete, and marker change operations require explicit confirmation. The command re-reads after every write to guarantee success.

```bash

# List all saved profiles

/diagram-design:profile list

# Switch current project to "beta-client" profile

/diagram-design:profile load beta-client

# Verify active profile

/diagram-design:profile show

```

## Summary

- **Profile Storage**: Save reusable brand configurations to `~/.diagram-design/profiles/<slug>.md` with metadata headers
- **Marker Files**: Create `.diagram-design` files containing `profile: <slug>` at project roots to enable automatic brand selection
- **Resolution Order**: The system checks markers before every generation, falling back to the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) only when markers are missing or invalid
- **CLI Management**: Use the `/profile` command with verbs like `save`, `load`, and `show` to manipulate profiles safely
- **Schema Safety**: All profiles validate against semantic and typography tables, with automatic backfilling of missing values

## Frequently Asked Questions

### What happens if the marker file points to a non-existent profile?

If the `.diagram-design` marker specifies a slug that does not exist in `~/.diagram-design/profiles/`, the skill ignores the marker and falls back to the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). The system may prompt you to `save` a new profile or correct the marker spelling.

### Can I use different brand profiles for different projects simultaneously?

Yes. Because each project maintains its own `.diagram-design` marker file and resolution occurs before every generation, parallel workspaces can reference different profiles without interference. The marker-first architecture ensures complete isolation between client projects.

### How does Diagram Design handle profile updates when the skill schema changes?

When the skill schema evolves (modifications to semantic role tables or typography tables), existing profiles are validated against the current version. Missing rows are backfilled from shipped defaults, and the user is offered an `update` command via `/profile update` to persist these structural repairs permanently.

### Is the marker file syntax flexible or does it require exact formatting?

The marker file requires exact grammar: a single line reading `profile: <slug>` where the slug is lower-case, alphanumeric-hyphen, and 64 characters or fewer. The skill treats the marker as untrusted data and rejects malformed entries with explanatory warnings, then proceeds with the default style guide.