Customization

All colors and brand-specific styles live in one file: color-palette.md. This is the single source of truth for all color choices in your diagrams—shape fills, strokes, text colors, evidence artifact backgrounds, everything.

The Customization Philosophy

Everything else in this skill is universal design methodology and Excalidraw best practices. To make this skill produce diagrams in your own brand style, you only need to edit one file.

The skill reads color-palette.md before generating any diagram and uses it as the authoritative source for all color decisions.

Locating the Color Palette

The color palette is at:

~/.claude/skills/excalidraw-diagram/references/color-palette.md

This file defines four categories of colors:

Shape Colors (semantic purpose-based)
Text Colors (hierarchy-based)
Evidence Artifact Colors (for code/data examples)
Default Stroke & Line Colors

Editing the Color Palette

Step 1: Read the Current Palette

First, view the current color definitions:

cat ~/.claude/skills/excalidraw-diagram/references/color-palette.md

You’ll see tables defining colors for each semantic purpose.

Step 2: Choose Your Brand Colors

Identify your brand’s color palette. You’ll need:

Primary brand color

Secondary/accent colors

Neutral/gray tones

Colors for semantic states (success, warning, error)

Use hex color codes (e.g., #3b82f6) for consistency with Excalidraw’s JSON format.

Step 3: Update Shape Colors

Edit the Shape Colors (Semantic) section. Each row defines a semantic purpose with a fill and stroke color.

Example: Changing the Primary/Neutral color to your brand blue:

| Semantic Purpose | Fill | Stroke |
|------------------|------|--------|
| Primary/Neutral | `#0066cc` | `#003366` |

Key principles:

Always pair a darker stroke with a lighter fill for contrast

The stroke should be readable against both the fill and white background

Test colors by rendering a diagram (see Render & Validate)

Step 4: Update Text Colors

Edit the Text Colors (Hierarchy) section to match your brand’s typography colors:

| Level | Color | Use For |
|-------|-------|---------|  
| Title | `#003366` | Section headings, major labels |
| Subtitle | `#0066cc` | Subheadings, secondary labels |
| Body/Detail | `#64748b` | Descriptions, annotations, metadata |

Maintain clear hierarchy: titles should be the darkest, subtitles medium, body/detail the lightest. This ensures readability.

Step 5: Customize Evidence Artifacts (Optional)

If you want to change the styling of code snippets and data examples:

| Artifact | Background | Text Color |
|----------|-----------|------------|
| Code snippet | `#1e293b` | Syntax-colored (language-appropriate) |
| JSON/data example | `#1e293b` | `#22c55e` (green) |

Most users keep the dark background (#1e293b) since it’s conventional for code blocks. You can change the text color to match your brand’s accent color.

Step 6: Save and Test

After editing, save the file:

# If editing with vim/nano/etc:
:wq

# Or if using Edit tool:
Edit ~/.claude/skills/excalidraw-diagram/references/color-palette.md ...

Then generate a test diagram and render it to verify your colors look good together.

Complete Example: Custom Brand Palette

Here’s a full example of customizing the palette for a fictional brand “TechFlow” with purple as the primary color:

## Shape Colors (Semantic)

| Semantic Purpose | Fill | Stroke |
|------------------|------|--------|
| Primary/Neutral | `#3b82f6` | `#1e3a5f` |
| Secondary | `#60a5fa` | `#1e3a5f` |
| Start/Trigger | `#fed7aa` | `#c2410c` |
| End/Success | `#a7f3d0` | `#047857` |

Notice:

Primary changed from blue (#3b82f6) to purple (#9333ea)
Stroke darkened to maintain contrast (#4a1d7a)
Secondary adjusted to lighter purple (#c084fc)
Start/End colors remain distinct but harmonize with the new palette

Color Pairing Guidelines

Fill + Stroke Contrast

Ensure sufficient contrast between fill and stroke:

Good Contrast
Poor Contrast

{
  "backgroundColor": "#9333ea",  // Light-ish purple fill
  "strokeColor": "#4a1d7a"       // Dark purple stroke
}

Result: Clear, readable outline.

{
  "backgroundColor": "#9333ea",  // Purple fill
  "strokeColor": "#a855f7"       // Similar purple stroke
}

Result: Stroke blends into fill, looks muddy.

Text on Colored Backgrounds

When text sits inside a colored shape, ensure readability: Rule of thumb:

Light fills → dark text (#374151 or darker)
Dark fills → white text (#ffffff)

From the palette:

| Level | Color | Use For |
|-------|-------|---------|  
| On light fills | `#374151` | Text inside light-colored shapes |
| On dark fills | `#ffffff` | Text inside dark-colored shapes |

Semantic Color Meanings

When customizing, maintain the semantic meanings:

Purpose	What It Represents	Recommended Colors
Primary/Neutral	Default shapes, main content	Brand primary color
Secondary	Supporting elements	Brand secondary/accent
Tertiary	Least important shapes	Lighter/muted variant
Start/Trigger	Beginning of flow, inputs	Warm colors (orange, yellow)
End/Success	Completion, outputs, success states	Green tones
Warning/Reset	Caution, resets, destructive actions	Red/pink tones
Decision	Branching points, choices	Yellow/gold tones
AI/LLM	AI-powered components	Purple tones
Inactive/Disabled	Not currently active	Muted blue with dashed stroke
Error	Error states, failures	Red tones

Don’t invent new semantic categories. If a concept doesn’t fit an existing category, use Primary/Neutral or Secondary. Adding custom categories won’t be recognized by the skill.

Testing Your Customizations

After editing color-palette.md, create a test diagram:

Create a simple test diagram

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    {
      "id": "primary_test",
      "type": "rectangle",
      "x": 100,
      "y": 100,
      "width": 180,
      "height": 90,
      "strokeColor": "#4a1d7a",
      "backgroundColor": "#9333ea",
      "text": "Primary",
      "fontSize": 20,
      "fontFamily": 3,
      "textAlign": "center",
      "verticalAlign": "middle",
      "roughness": 0,
      "opacity": 100,
      "seed": 1
    }
  ],
  "appState": {"viewBackgroundColor": "#ffffff", "gridSize": 20},
  "files": {}
}

Render it

cd ~/.claude/skills/excalidraw-diagram/references
uv run python render_excalidraw.py test-colors.excalidraw

Review the PNG

View test-colors.png to verify:

Colors render as expected

Fill/stroke contrast is sufficient

Text is readable on colored backgrounds

Iterate if needed

If colors don’t look right, edit color-palette.md again and re-test.

Advanced: Color Accessibility

For diagrams that will be viewed by colorblind users or in print/grayscale:

Use patterns in addition to color

Differentiate elements with:

Different shapes (rectangle vs ellipse vs diamond)
Different stroke widths (strokeWidth: 1 vs strokeWidth: 3)
Dashed vs solid strokes (strokeStyle: "dashed" vs "solid")

Test in grayscale

Convert your rendered PNG to grayscale to verify that:

Different elements are still distinguishable
Text remains readable
Flow is still clear without color cues

Ensure sufficient contrast ratios

Use a contrast checker (e.g., WebAIM) to verify:

Text vs background: minimum 4.5:1 for normal text
Stroke vs fill: minimum 3:1 for visual clarity

Troubleshooting

My custom colors aren't being used

Ensure you:

Saved the color-palette.md file after editing
Used valid hex color codes (e.g., #3b82f6, not blue or rgb(59, 130, 246))
Kept the same semantic purpose names (don’t rename “Primary/Neutral” to “Main Color”)

Colors look good individually but clash together

Check color harmony:

Use a tool like Adobe Color or Coolors to validate your palette
Ensure all colors are from the same “family” (similar saturation/brightness)
Test with a full diagram, not just individual shapes

Text is unreadable on my custom backgrounds

Adjust the “On light fills” / “On dark fills” text colors:

Light fills need darker text (try #1f2937 or darker)
Dark fills need white or very light text (#ffffff or #f9fafb)

Next Steps

Creating Diagrams

Start creating diagrams with your new brand colors

Color Palette Reference

See the full default color palette reference

Element Templates

Use templates that reference your custom colors

Get Started

Core Concepts

Design Methodology

Guides

The Customization Philosophy

Locating the Color Palette

Editing the Color Palette

Complete Example: Custom Brand Palette

Color Pairing Guidelines

Fill + Stroke Contrast

Text on Colored Backgrounds

Semantic Color Meanings

Testing Your Customizations

Advanced: Color Accessibility

Troubleshooting

Next Steps

Creating Diagrams

Color Palette Reference

Element Templates

Build docs developers (and LLMs) love

Get Started

Core Concepts

Design Methodology

Guides

​The Customization Philosophy

​Locating the Color Palette

​Editing the Color Palette

​Complete Example: Custom Brand Palette

​Color Pairing Guidelines

​Fill + Stroke Contrast

​Text on Colored Backgrounds

​Semantic Color Meanings

​Testing Your Customizations

​Advanced: Color Accessibility

​Troubleshooting

​Next Steps

Creating Diagrams

Color Palette Reference

Element Templates

Build docs developers (and LLMs) love

The Customization Philosophy

Locating the Color Palette

Editing the Color Palette

Complete Example: Custom Brand Palette

Color Pairing Guidelines

Fill + Stroke Contrast

Text on Colored Backgrounds

Semantic Color Meanings

Testing Your Customizations

Advanced: Color Accessibility

Troubleshooting

Next Steps