# How the Client Profile System Uses .diagram-design Project Markers

> Discover how the client profile system uses .diagram-design project markers to load custom styling from isolated files, binding projects to specific brand profiles for unique visual identities.

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

---

**The client profile system uses a `.diagram-design` marker file in the project root to bind projects to specific brand profiles, loading custom styling from isolated files rather than the default style guide.**

The `cathrynlavery/diagram-design` repository implements a marker-first resolution system that enables multiple client projects to share a single plugin installation without interference. By parsing a simple marker file, the diagram skill identifies which client profile to apply, allowing project-specific branding tokens to travel with your source code.

## Understanding the .diagram-design Marker File

A **`.diagram-design`** file is a plain-text marker placed in the project root directory. This file contains a single configuration line that specifies which client profile to load:

```markdown
profile: <slug>

```

The `<slug>` value must follow strict validation rules defined in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md): lowercase ASCII letters, digits, and hyphens only, with a maximum length of 64 characters. When the skill initializes, it searches for this marker before attempting to load any styling resources.

## Profile Resolution Workflow

The resolution logic implemented in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) follows a marker-first approach to determine which style guide to apply.

When processing a diagram request, the skill executes the following steps:

1. **Check for the marker** – The skill scans the project root for a `.diagram-design` file.
2. **Validate the slug** – If found, the skill extracts and validates the profile slug against the naming constraints.
3. **Load the profile** – The system reads the profile file from `~/.diagram-design/profiles/<slug>.md`.
4. **Fallback handling** – If the marker is missing or invalid, the skill falls back to the built-in [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) or the currently active user profile.

This architecture ensures that the installed [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) remains untouched, preventing updates from overwriting customized branding.

## Creating and Managing Client Profiles

Client profiles are standalone markdown files containing brand-specific tokens, colors, and typography settings. You create these profiles using the CLI commands defined in [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md).

To create a new profile from your current style configuration:

```bash
/profile save acme

```

This command writes a complete copy of the current style guide to `~/.diagram-design/profiles/acme.md`. The profile persists across plugin updates, providing an isolated storage mechanism for client branding.

## Practical Implementation Examples

The following examples demonstrate the complete workflow for binding a project to a specific client profile using the marker system.

### Create a Profile and Add the Project Marker

First, save the current styling as a named profile:

```bash
/profile save acme-brand

```

Then, in your project root, create the marker file:

```bash
echo "profile: acme-brand" > .diagram-design

```

### Generate Diagrams with Custom Branding

Once the marker exists, all diagram requests automatically load the specified profile:

```bash
/diagram-design "Create an architecture diagram of the authentication flow"

```

The skill reads the marker, validates the slug `acme-brand`, and renders the diagram using the tokens stored in `~/.diagram-design/profiles/acme-brand.md`.

### Switch Between Client Profiles

To change branding for a different client, overwrite the marker:

```bash
echo "profile: beta-client" > .diagram-design

```

Alternatively, remove the marker entirely to revert to the default behavior:

```bash
rm .diagram-design

```

## Key Source Files and Architecture

The marker-based resolution system spans several files in the repository:

- **[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)** – Contains the core logic that checks for the `.diagram-design` marker before loading the style guide. This file implements the gate that prioritizes marker-based profiles over the default configuration.

- **[`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)** – Defines the profile storage format, slug validation rules, and the marker-first resolution specification.

- **[`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md)** – Implements the CLI interface for creating, listing, updating, and deleting profiles. This handles the `/profile save` command and manages the `~/.diagram-design/profiles/` directory structure.

- **[`skills/diagram-design/references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/onboarding.md)** – Provides the flow for extracting brand tokens from existing assets and saving them as new profiles, often followed by writing the initial marker file.

According to the source code in [`profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/profiles.md), the validation regex ensures slugs contain only lowercase alphanumeric characters and hyphens, preventing filesystem conflicts and ensuring cross-platform compatibility.

## Summary

- **The `.diagram-design` marker file** binds a project root to a specific client profile via a `profile: <slug>` declaration.
- **Profile files** are stored in `~/.diagram-design/profiles/<slug>.md` and remain isolated from the plugin's default [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).
- **Resolution follows a marker-first approach**: the skill checks for the marker in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) logic before falling back to default styles.
- **Slug validation** enforces lowercase ASCII characters with a 64-character limit to ensure filesystem safety.
- **Profiles persist across updates**, allowing multiple projects to share one installation while maintaining distinct branding through their respective markers.

## Frequently Asked Questions

### What is the exact format of the .diagram-design marker file?

The marker file must contain a single line specifying the profile slug in the format `profile: <slug>`. The file should reside in the project root directory. The slug must consist of lowercase ASCII letters, digits, and hyphens only, with a maximum length of 64 characters. Any deviation from this format causes the skill to reject the marker and fall back to default styling.

### Where are client profile files physically stored?

Client profiles are stored as individual markdown files in the `~/.diagram-design/profiles/` directory, with each file named `<slug>.md` corresponding to the profile identifier. This location is separate from the plugin installation directory, ensuring that profiles survive plugin updates and remain available across different projects on the same machine.

### How does the system handle missing or invalid markers?

If the `.diagram-design` marker is absent, the skill falls back to the built-in style guide located at [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) or uses the currently active user profile configured through the `/profile` command. Invalid slugs—those containing uppercase letters, special characters, or exceeding 64 characters—trigger the same fallback behavior, ensuring the system fails gracefully without breaking the diagram generation workflow.

### Can I switch between profiles without recreating the marker file?

Yes, you can overwrite the existing marker file to switch profiles instantly. Run `echo "profile: new-slug" > .diagram-design` from the project root to replace the current binding. The skill reads the marker fresh on each request, so subsequent diagram commands immediately use the new profile's styling tokens without requiring a restart or reinstallation of the plugin.