Why use it: diagram first in a new project will be blocked by a mandatory gate. The Skill silently refuses to output diagrams that carry the default colors into a project that has a brand. If you don't know about this gate, you'll think the agent is stuck.
What this file generates: a style-guide.md carrying your colors and fonts, plus (optionally) a profile library at ~/.diagram-design/profiles/ that can be shared across multiple clients.
This entire file is chat operations — except for a few
mkdir/catcommands to inspect files on disk. There is no onboarding CLI.
1. How the style-guide gate works
Excerpt from SKILL.md §0 — before drawing the first diagram, the skill:
- Looks for the marker
<project-root>/.diagram-design. A valid marker points to a real profile → select that profile directly, skip the gate.profile: defaultalso skip the gate. - No marker → open
references/style-guide.mdand compare against the shipped default tokens: paper#f5f5f5, ink#2d3142, accent#eb6c36(atomic-tangerine). - Still exactly the defaults → stop and ask you, exactly 6 options:
"This is your first diagram in this project. The style guide is still at the default (neutral white-smoke + atomic-tangerine). Do you want to customize it to match your brand first? Options: (a) pull from your website URL, (b) extract from an installed skill, (c) extract from a local folder / design-system directory, (d) paste tokens manually, (e) proceed with the default for now, (f) load a saved client profile."
Once customized (or you choose (e)), the gate won't ask again.
The "custom-unsaved" state: tokens differ from the defaults but there is no profile header at the top of the file → the skill skips the gate and invites you to save it as a profile. Don't miss that invitation, because a plugin update may overwrite the working copy.
2. The fastest path — onboard from a website
Type in chat:
onboard diagram-design to https://yoursite.com
The flow, per README.md §Onboarding and references/onboarding.md §URL:
→ tải trang chủ
→ trích palette trội + font stack
→ ánh xạ vào 5 vai trò ngữ nghĩa: paper, ink, muted, accent, link
→ hiện diff đề xuất
→ (bạn duyệt) ghi token vào references/style-guide.md
The actual mapping table (README §"What gets extracted"):
| Extracted from your site | Becomes token |
|---|---|
Background <body> |
paper |
| Main text color | ink |
| Secondary text / caption | muted |
| Card / container | paper-2 |
| Most-used brand color (CTA, link, heading) | accent |
Font of <h1> |
title |
Font of <body> |
node-name |
Font of <code> / <pre> |
sublabel |
Two things run automatically, no need to ask:
- WCAG AA contrast check for
inkonpaperbefore writing. If your colors fail at 9–12px font sizes, the skill suggests corrected values and explains why. - Fidelity receipt: sampled URLs, the role of each color, font families + weights, font source URLs, and any fallbacks. The site's public fonts are actually used and then verified after rendering, rather than being silently swapped for system fonts.
The remaining three onboarding paths
| Method | What to type | When |
|---|---|---|
| From an installed skill | "onboard diagram-design from the <tên-skill> skill" |
You already have another skill containing design tokens |
| From a local folder | "onboard diagram-design from ./design-system" | A design-system folder / token file is available |
| Paste manually | "set diagram-design tokens: paper #…, ink #…, accent #…" | You know the exact color codes |
Details for each branch are in references/onboarding.md (§URL, §Skill, §Folder).
Edit manually, not through the agent
Open skills/diagram-design/references/style-guide.md and edit the token table directly. Everything downstream reads from it — all 39 diagram types, annotation primitives, and the gallery — because they reference role names (accent), not color codes (#eb6c36).
3. Profile — working with multiple clients
This is the most valuable part and also the most easily misunderstood.
Canonical paths (from references/profiles.md §"Paths and terms")
| Item | Path |
|---|---|
| Profile library | ~/.diagram-design/profiles/ |
| A single profile | ~/.diagram-design/profiles/<slug>.md |
| Project marker | <project-root>/.diagram-design |
Marker content must be exactly one line, exactly this grammar:
profile: <slug>
The marker is treated as untrusted data (untrusted repository data). Only the exact grammar above is accepted; if malformed or pointing to a nonexistent profile, the skill reports a clear error, doesn't guess, doesn't auto-fix.
Why use a marker instead of copy-over
For a project with a marker, the skill reads directly ~/.diagram-design/profiles/<slug>.md and leaves the installed working copy untouched. That means three parallel workspaces, three different brands, none overwriting another. This is the difference from load the copy-over style.
The verbs of the /profile
In Claude Code type /diagram-design:profile; in Factory Droid / Pi type /profile.
| Type | What it does |
|---|---|
/profile (no arguments) |
list, marks the active profile according to the marker or working copy |
/profile <name> (no verb) |
equivalent to load <name> |
/profile list |
list the library |
/profile save [name] |
save the current style-guide as a profile |
/profile load [name] |
load a profile (copy-over) |
/profile switch <name> |
synonym load — real, even though it does not appear in argument-hint |
/profile show |
view the active profile |
/profile update [name] |
update an existing profile |
/profile reset |
reset to default |
/profile delete [name] |
delete a profile |
Unknown verb or extra parameters → the skill prints the valid forms and stops, writes nothing.
Four safety rules (from commands/profile.md §"Required behavior")
- Always confirm before overwriting an existing profile, changing the project marker, or deleting a profile — even when the command is invoked from a script. There is no path that skips confirmation.
- The project is chosen by marker: read the profile directly, do not overwrite the working copy.
- For
loadcopy-over mode: verify again after writing. If the destination is not writable, the skill suggests switching to the marker flow. - After
save/update: confirm exactly one metadata header and that the body is unchanged.
And one sentence worth pasting on the wall, verbatim from the command: "Never claim a write succeeded without re-reading it."
4. A formula that is enough for a 3-client agency
# một lần, tạo thư viện
mkdir -p ~/.diagram-design/profiles
Then in the chat, repeat for each client:
onboard diagram-design to https://client-a.com
/diagram-design:profile save client-a
Finally, in each project repo:
echo 'profile: client-a' > /path/to/project-a/.diagram-design
echo 'profile: client-b' > /path/to/project-b/.diagram-design
Check:
ls ~/.diagram-design/profiles/
cat /path/to/project-a/.diagram-design
From now on every diagram generated in project-a carries the brand client-a, no need to remember anything else, and the plugin installation is left untouched.
Profile survives plugin updates. Working copy style-guide.md does not.
5. This step is done when
-
references/style-guide.mdis no longer the default token set (or you have deliberately chosen (e)). - If working with multiple clients:
~/.diagram-design/profiles/has at least one.md, and the project has.diagram-designone grammatically correct line. -
/diagram-design:profilecan be listed and points to exactly the active profile.
Next: 03-authoring-in-chat.md.