Diagram Design: evidence-driven visual explanations
Adopting Diagram Design in a team: package revision, profiles and artifact delivery
Separate installing the authoring package from publishing its output, and avoid shared style files becoming a cross-project configuration race.
What you will learn
- There are two deployment problems
- Keep client style selection out of shared mutable state
- Qualify the publishing destination
Before you start
- Basic HTML and SVG concepts
- Ability to distinguish a system relationship from its visual layout
Choose a useful representation, account for simplification and interpret checker findings within their real scope.
Key takeaways
- Installing an authoring package and publishing an artifact are distinct operations.
- Project-selected profile snapshots avoid shared style-file races.
- Verify fonts, URLs and cache behavior at the real destination.
There are two deployment problems
The authoring package runs in a compatible agent host, while its generated HTML or exported image is delivered through a documentation site, slide deck or another destination. Installing the skill does not publish an article, and uploading a diagram does not install the authoring tools for teammates. Assign responsibility to both workflows.
Record the package revision rather than relying only on a human-readable version string. The repository contains host manifests pointing at a shared skill directory. That organization reduces duplicated instructions, but each host still has its own installation, discovery and update behavior. This review inspected packaging metadata without performing a marketplace installation.
Keep client style selection out of shared mutable state
Managed package updates can replace edits inside the installed style guide. The documented profile design stores named snapshots outside the installation and lets a project marker select a validated profile slug. Marker-based resolution reads that profile directly, so two workspaces need not overwrite the same installed working file to use different brands.
Treat the project marker and the profile snapshot as configuration with owners. A missing profile, outdated schema or unreviewed brand change should be resolved deliberately rather than silently substituting an unrelated client’s colors. The marker example below is documentation of the format, not an instruction we executed against a user profile directory.
Qualify the publishing destination
For article delivery, inspect the actual asset URL, cache behavior and font availability in the deployed site. For raster output, the documented workflow adds browser automation and Chromium setup; that is a different dependency surface from viewing static markup. Decide which artifacts and dependencies the delivery environment really needs.
A rollout acceptance check should include a fresh host session, two differently branded projects, a rendered diagram at destination width and a rollback path for package updates. None of those integration outcomes follows from our geometry fixture results. No host installation, profile change, production publish or complete export run was performed here.
Implementation steps
- 1
Record the source revision and intended host.
- 2
Assign owners to profile snapshots and project markers.
- 3
Test authoring and delivery as separate workflows.
- 4
Keep the previous approved package and artifacts for rollback.
Copy-ready example
# Example contents of a project .diagram-design marker
# Requires an existing approved profile; not written by this review
profile: acme-docsFrequently asked questions
Does installing the plugin publish the generated diagram?
No. It enables authoring in a host. Your site or document delivery process still needs to publish the resulting artifact.
Why avoid editing a shared installed style guide for every client?
Updates can replace it, and parallel projects can overwrite one another’s settings. The documented marker/profile model separates project selection from that shared file.
Sources
- .codex-plugin/plugin.jsonSource checked 2026-09-08
- docs/adr/0006-client-profiles-and-marker-first-resolution.mdSource checked 2026-09-08
- README.mdSource checked 2026-09-08