How to Manually Edit style-guide.md Tokens Without Running Onboarding

You can manually edit visual tokens in style-guide.md by modifying the markdown tables for semantic colors, typography, and layout metrics without triggering the automated onboarding flow.

The Diagram Design system centralizes all visual design tokens in a single reference file within the cathrynlavery/diagram-design repository. While the onboarding flow generates skins automatically, direct manipulation of style-guide.md provides immediate control over colors, spacing, and typographic hierarchies.

Locating the Token Definition File

Navigate to skills/diagram-design/references/style-guide.md in your local clone of the repository. This file serves as the single source of truth for all visual tokens including semantic colors, typography families, stroke weights, border radius, and spacing values.

The companion file skills/diagram-design/references/onboarding.md describes the automated skin generation flow, but you can bypass this entirely by editing the markdown tables directly.

Understanding the Token Table Structure

The style-guide.md file organizes design tokens into four distinct markdown table types. Each table controls specific aspects of the visual system with strict column ordering.

Semantic Color Roles

The semantic roles table defines core palette tokens using four columns: token name, description, light mode value, and dark mode value. To change the page background from default white to a warm gray, edit the paper row:

| `paper` | Page background, default node fill | `#f2f0e9` | `#2d3142` |

Replace the hex or rgba values in the appropriate column while preserving the light-mode-first, dark-mode-second column order.

Series Palette Extensions

For multi-series charts, locate the optional chart series colors table. These tokens follow the series-N naming convention and extend the palette beyond core semantic roles:

| `series-6` | `#c08a5b` (olive) | Non-focal series |

Terminal Skin Overrides

The terminal skin table provides an alternate palette specifically for terminal primitives. Edit these values independently from the main semantic roles when customizing CLI or code-block visualizations.

Layout Metrics

Numeric tokens for physical dimensions occupy separate tables without light/dark variants. To adjust the border width for tag boxes from 0.8 to 1 pixel, modify the stroke table:

| `stroke-thin` | `1` | Tag-box outlines, leaf nodes |

Critical Constraints for Manual Edits

Direct editing requires adherence to design constraints documented in the Constraints section of the same file. Violations break visual consistency across generated diagrams.

WCAG AA Contrast Requirements

The ink token must achieve WCAG AA contrast ratios against the paper token in both color modes. The muted token must also maintain AA contrast against paper when used for body text. Verify contrast calculations whenever modifying these core semantic colors.

Single Accent Discipline

Only one hue should occupy the accent role. Adding secondary accent colors breaks the focal visual cue that guides user attention through diagrams. The accent token should appear a maximum of 1–2 times per composition.

Typography Family Restrictions

The system enforces a three-family rule using Instrument Serif, Geist Sans, and Geist Mono. Do not introduce additional font families into the token definitions, as the rendering engine expects these specific typeface associations.

Rainbow Palette Prevention

Limit the overall palette to the core semantic roles defined in the tables. Extra colors belong in the series palette, not as new semantic tokens. Adding arbitrary colors outside the established roles creates visual noise inconsistent with the Diagram Design aesthetic.

Post-Edit Validation Workflow

After saving changes to style-guide.md, run the skill's taste-gate validation if available. This verifies that the new accent value maintains focal prominence and reads correctly against the current paper background.

Inspect generated example diagrams by opening assets/index.html after rebuilding. Confirm that stroke weights render at the correct pixel values, color balances appear harmonious in both modes, and typographic hierarchies remain legible.

Committing Your Changes

Once validation succeeds, stage and commit the modified style-guide.md file. The Diagram Design system automatically applies these token values to all future diagram generations without requiring additional onboarding steps or configuration updates.

Summary

• Direct file editing: Modify skills/diagram-design/references/style-guide.md to change tokens immediately without running onboarding
• Table structure: Edit markdown tables for semantic colors, series palettes, terminal skins, and numeric metrics
• Column ordering: Maintain light-mode-first values for all color tokens to preserve dark mode compatibility
• Design constraints: Respect WCAG AA contrast ratios, single-accent focal rules, three-typography-family limitations, and anti-rainbow palette discipline
• Validation: Use taste-gate checks and visual inspection of assets/index.html before committing changes

Frequently Asked Questions

What happens if I violate the WCAG contrast constraints in style-guide.md?

Violating contrast requirements produces diagrams that fail accessibility standards and render text illegible in certain viewing conditions. While the build process will not block compilation, generated outputs will exhibit poor readability when ink lacks sufficient contrast against paper.

Can I add new semantic tokens beyond the defined roles?

Avoid adding new semantic tokens to the core roles table. The Diagram Design engine expects specific token names like paper, ink, accent, and muted. Instead, add auxiliary colors to the series palette or extend existing semantic values while maintaining the constrained palette approach to prevent visual noise.

Do I need to restart the onboarding flow after manual edits?

No. Manual edits to style-guide.md take effect immediately for subsequent diagram generations. The onboarding flow described in onboarding.md serves as an alternative entry point for automated skin generation, but direct file editing bypasses this requirement entirely.

How do I modify tokens for dark mode specifically?

Locate the second value column in the semantic color tables. The first column represents light mode values, while the second column contains dark mode variants. Edit the second column to adjust dark mode appearances independently of light mode values.

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