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

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—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)
3. Default profile creation (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 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.

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

.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 and skills/diagram-design/references/profiles.md.

Creating a Project Marker

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

# .diagram-design

profile: acme-corp

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

Listing Available Profiles

diagram-design profile list

Sample output:

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:

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:

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

diagram-design profile reset

Ensures 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 – 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 – User-facing command definition delegating to the resolution procedures.

• 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 – Verification mapping command files to reference specifications.

• 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. If that file is also unavailable or invalid, the system ultimately loads the built-in 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 (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 file in this directory maintains the pristine shipped defaults used for reset operations and marker-based default requests.

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