# Understanding Brand Profile Resolution Order in Diagram Design: Project Markers vs. Shared Library

> Learn how Diagram Design resolves brand profiles prioritizing project markers over shared libraries for workspace isolation. Understand the four-layer hierarchy.

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

---

**Diagram Design resolves brand profiles through a deterministic four-layer hierarchy that prioritizes project-level `.diagram-design` markers over shared library files, ensuring complete workspace isolation without cross-project contamination.**

Diagram Design determines the effective style guide for every diagram generation through a strict brand profile resolution order. This system balances project-specific customization with shared organizational standards by checking local markers before falling back to global libraries. Understanding this resolution hierarchy—documented in [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)—is essential for maintaining consistent branding across multiple client environments without configuration conflicts.

## The Four-Layer Brand Profile Resolution Hierarchy

Diagram Design implements a deterministic resolution process that guarantees independent workspaces coexist safely. The system evaluates potential style guide sources in the following strict sequence:

1. **Project-level marker file** (`.diagram-design`)
2. **Installed working copy** ([`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md))
3. **Default profile creation** ([`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md))
4. **Structural schema validation**

### Step 1: Project-Level Marker Inspection (`.diagram-design`)

The resolver first checks for a file named `.diagram-design` in the project root. If present, this marker takes absolute precedence.

The marker must contain exactly one line matching the grammar `profile: <slug>`. The slug must validate against the regex `[a-z0-9][a-z0-9-]{0,63}`. When valid, the system reads `~/.diagram-design/profiles/<slug>.md` directly from the profile library, bypassing any installed working copy. The special slug `default` loads the built-in [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) profile.

If the marker is missing, malformed, or references a non-existent profile, resolution proceeds to the next layer.

### Step 2: Fallback to Installed Working Copy

When no valid marker exists, Diagram Design falls back to the repository's installed [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md).

If this file begins with a `<!-- diagram-design-profile … -->` header, the header's `slug` attribute identifies which saved profile the working copy represents. If the header is absent but the file's token values match shipped defaults, the system triggers the **first-time-setup gate** documented in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md). Any deviation from defaults (such as a custom `accent` token) marks the working copy as **custom-unsaved**, enabling the `save` verb.

### Step 3: Default Profile Initialization

Upon first save or load operation, the system ensures a pristine copy of the shipped style guide exists as [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) in the library (`~/.diagram-design/profiles/`). This snapshot serves the `reset` verb and supports marker-only projects requesting `profile: default`.

### Step 4: Structural Schema Validation

After loading any profile—whether marker-selected or copied—the system performs a current-schema structural check. Missing rows are back-filled from shipped defaults before diagram generation proceeds, ensuring forward compatibility with new schema versions.

## Visualizing the Resolution Flow

The complete resolution order can be visualized as:

```text
.project/.diagram-design  →  ~/.diagram-design/profiles/<slug>.md
                 else →  references/style-guide.md (+ header → linked profile)
                 else →  built-in defaults (default.md)

```

Because the marker processes **before** any file-system write, parallel projects maintain distinct profiles without touching the shared install directory. This "marker-first" flow provides the core safety guarantee for multi-client environments.

## Managing Brand Profiles: Practical Commands

The `diagram-design profile` command suite implements the resolution logic defined in [`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md) and [`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md).

### Creating a Project Marker

Create a `.diagram-design` file at your repository root:

```text

# .diagram-design

profile: acme-corp

```

The file must contain nothing else—no comments, no extra keys.

### Listing Available Profiles

```bash
diagram-design profile list

```

Sample output:

```text
default            – Built-in default (read-only)
acme-corp          – Acme Corporation (source-url: https://example.com)

```

### Saving and Loading Profiles

Save the current effective style guide as a named profile:

```bash
diagram-design profile save my-client

```

This command:

1. Validates `my-client` against the slug regex `[a-z0-9][a-z0-9-]{0,63}`.
2. Strips existing `<!-- diagram-design-profile … -->` blocks.
3. Prepends a fresh header with `created`/`updated` dates.
4. Writes to `~/.diagram-design/profiles/my-client.md`.
5. Offers to write a project marker with explicit consent.

Load a profile into the working copy:

```bash
diagram-design profile load acme-corp

```

If the install directory is unwritable, the command falls back to writing a project marker instead.

### Resetting to Defaults

```bash
diagram-design profile reset

```

Ensures [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) exists, then writes a marker or copies the default profile based on permissions.

## Key Implementation Files

Understanding the brand profile resolution order requires familiarity with these specific source files:

- **[`skills/diagram-design/references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/profiles.md)** – Canonical specification for profile resolution, slug validation rules, marker handling, and structural back-filling (see § Resolution before every generation, § Built-in default, § Current-schema structural check).

- **[`commands/profile.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/profile.md)** – User-facing command definition delegating to the resolution procedures.

- **[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)** – Entry point triggering the style-guide gate and explaining marker-first flow (see § 0. First-time setup — style guide gate).

- **[`scripts/verify-doctor.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-doctor.py)** – Verification mapping command files to reference specifications.

- **[`scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/self_check.py)** – Runtime validation of the effective style guide before generation.

## Summary

- Diagram Design uses a **four-layer deterministic hierarchy** to resolve brand profiles, starting with project markers and falling back through working copies to built-in defaults.
- The **`.diagram-design` marker** provides absolute precedence, enabling complete project isolation without shared state contamination.
- **Slug validation** enforces the regex `[a-z0-9][a-z0-9-]{0,63}` for all profile names.
- The **`profile save`** and **`profile load`** commands manage the shared library at `~/.diagram-design/profiles/` while respecting the marker-first resolution order.
- **Structural schema checks** ensure loaded profiles remain compatible with current skill definitions by back-filling missing tokens from shipped defaults.

## Frequently Asked Questions

### What happens if the `.diagram-design` marker points to a non-existent profile?

If the marker references a profile slug not present in `~/.diagram-design/profiles/`, the resolver treats this as a resolution failure and falls back to the installed [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md). If that file is also unavailable or invalid, the system ultimately loads the built-in [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) profile after ensuring it exists in the library.

### How does Diagram Design prevent cross-project contamination?

The **marker-first** architecture processes `.diagram-design` files before any file-system writes occur. Because projects read profiles directly from the shared library without copying to the install directory, multiple projects can simultaneously use different `profile: <slug>` values without overwriting each other's configurations. Each project maintains its own isolated effective style guide.

### What is the difference between `profile save` and `profile load`?

The **`profile save`** command captures the current effective style guide—including any custom tokens—into a new shared library file with a validated slug header. The **`profile load`** command copies a saved profile from the library into the working [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md) (unless a marker is present, in which case it suggests creating one). Save creates shared assets; load activates them in the working copy.

### Where does Diagram Design store saved brand profiles?

Saved profiles reside in **`~/.diagram-design/profiles/<slug>.md`** within the user's home directory. This location serves as the shared library accessible across all projects, while the [`default.md`](https://github.com/cathrynlavery/diagram-design/blob/main/default.md) file in this directory maintains the pristine shipped defaults used for reset operations and marker-based default requests.