What Is the Role of references/style-guide.md in Diagram Design?

The references/style-guide.md file serves as the single source of truth for all visual tokens in the Diagram Design skill, centralizing colors, typography, spacing, and node treatments to ensure visual consistency and theme-ability across every diagram type.

In the cathrynlavery/diagram-design repository, the references/style-guide.md file functions as the authoritative stylesheet that drives every visual aspect of the system. Instead of hard-coding hex values throughout diagram specifications, all components reference semantic tokens defined in this central document. This architecture guarantees that diagrams maintain a coherent visual language while remaining fully customizable for different brands or accessibility needs.

Centralized Visual Token System

The style guide establishes a semantic token architecture that abstracts raw color values into meaningful roles. According to the source code in references/style-guide.md (lines 17-27), these roles include paper (background), ink (primary text), accent (highlighting), and muted (secondary elements), each with defined light-mode and dark-mode values.

All diagram specifications reference these semantic names rather than raw hex codes like #EB6C36. For example, a diagram type definition might specify "use accent for the focal element," ensuring that the actual color value remains decoupled from the structural logic.

Light and Dark Mode Support

The file implements an automatic inversion rule (lines 34-36) that converts light-mode rgba values to their dark-mode equivalents. This ensures color consistency across different skins without requiring manual maintenance of separate dark palettes for every token.

Typography Standards

The style guide defines three font families and their specific use cases (lines 72-81). These mappings include title for headings, node-name for element labels, and sublabel for secondary text. A critical constraint specifies that mono fonts are reserved exclusively for technical content (lines 89-90), preventing their overuse in general diagram elements.

Structural Design Constants

Beyond colors and fonts, references/style-guide.md centralizes all geometric constants that govern SVG rendering.

Spacing, Stroke, and Radius Values

The document standardizes values such as stroke-thin, radius-md, and establishes a base grid size of 4 (lines 93-103). These constants ensure that all diagram elements—from containers to connectors—share identical proportions and visual weight.

Node-Type Treatments

Specific node classifications like focal, backend, and store map directly to fill and stroke token combinations (lines 107-119). This mapping allows any type specification to reference a node role name rather than defining visual properties repeatedly, ensuring that a "focal" node always renders with accent-tint fill and accent stroke regardless of the specific diagram type.

Theming and Customization Workflows

The style guide supports four distinct methods for altering the visual skin (lines 23-31). Users can run the onboarding.md workflow to generate a custom guide from a brand URL, edit the file manually, import a design-token JSON file, or switch between named profiles defined in profiles.md.

The Terminal Skin Exception

For specialized use cases, the guide offers an optional terminal skin (lines 52-66) designed specifically for the terminal-window primitive. Importantly, this skin exists as a self-contained alternative that does not replace the default palette, allowing terminal diagrams to coexist with standard diagrams without theme conflicts.

Accessibility and Design Constraints

The file enforces strict WCAG contrast requirements and the "one-accent" rule (lines 32-41). These constraints prevent visual overload by limiting the series palette to five desaturated tokens (series-1 through series-5) for multi-series charts, ensuring that diagrams remain accessible and visually focused.

Integration with Diagram Specifications

Diagram type definitions, such as type-wardley.md, consume these tokens directly. The following examples demonstrate how specifications reference the style guide without hard-coding values.

# Example: a node definition in a type spec (type-wardley.md)

nodes:
  - id: componentA
    type: focal               # ← pulls accent-tint fill & accent stroke

    label: "Core Service"

<!-- Example: using a token in an SVG style definition -->
<ellipse cx="100" cy="50" rx="40" ry="20"
         fill="var(--accent-tint)" stroke="var(--accent)" stroke-width="1"/>

Both snippets rely on token names defined in references/style-guide.md, with actual color values injected at runtime from the tables in that file.

Summary

• references/style-guide.md acts as the single source of truth for all visual tokens in the Diagram Design system.
• Semantic roles like paper, ink, and accent abstract color values, enabling theme-ability and dark-mode support via automatic inversion rules.
• Structural constants for stroke widths, radii, and spacing ensure geometric consistency across all SVG outputs.
• Node-type treatments map logical roles (e.g., focal, backend) to specific color combinations, eliminating repetitive styling code.
• Four customization workflows allow users to retheme diagrams via onboarding scripts, manual edits, JSON imports, or profile switching.
• Accessibility constraints enforce WCAG compliance and the "one-accent" visual rule to prevent design clutter.

Frequently Asked Questions

What happens if I edit references/style-guide.md directly?

Editing the file directly immediately affects all diagram types that reference its tokens, as the file serves as the runtime source for color values, typography, and spacing constants. This approach is one of four supported customization methods, alongside using the onboarding workflow, importing a design-token JSON, or switching named profiles.

How does the style guide enforce the "one-accent" rule?

The guide limits the series palette to five desaturated tokens (series-1 through series-5) and constrains the use of the primary accent color to focal elements only. These limitations are documented as unbreakable constraints (lines 32-41) that prevent visual clutter and maintain accessibility standards.

Can I use the Diagram Design system without the default style guide?

While the system requires a style guide to resolve token references, you can replace the default references/style-guide.md content entirely by importing a custom design-token JSON or switching to a different named profile. The terminal skin option (lines 52-66) demonstrates how alternative palettes can coexist without modifying the default file.

How do semantic tokens like paper and ink work in practice?

Instead of specifying hex codes in diagram definitions, authors reference semantic roles defined in lines 17-27 of the style guide. For example, paper always represents the background color and automatically adjusts between light and dark modes via the inversion rule (lines 34-36), ensuring consistent contrast without manual theme management.

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