> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/coleam00/excalidraw-diagram-skill/llms.txt
> Use this file to discover all available pages before exploring further.

# Customization

> How to customize colors and brand styles for your diagrams

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.

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

## Locating the Color Palette

The color palette is at:

```bash theme={null}
~/.claude/skills/excalidraw-diagram/references/color-palette.md
```

This file defines four categories of colors:

1. **Shape Colors** (semantic purpose-based)
2. **Text Colors** (hierarchy-based)
3. **Evidence Artifact Colors** (for code/data examples)
4. **Default Stroke & Line Colors**

## Editing the Color Palette

<Steps>
  ### Step 1: Read the Current Palette

  First, view the current color definitions:

  ```bash theme={null}
  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)

  <Warning>
    Use hex color codes (e.g., `#3b82f6`) for consistency with Excalidraw's JSON format.
  </Warning>

  ### 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:

  ```markdown theme={null}
  | 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](/guides/render-validate))

  ### Step 4: Update Text Colors

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

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

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

  ### Step 5: Customize Evidence Artifacts (Optional)

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

  ```markdown theme={null}
  | 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:

  ```bash theme={null}
  # 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.
</Steps>

## 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:

<CodeGroup>
  ```markdown Before (Default) theme={null}
  ## Shape Colors (Semantic)

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

  ```markdown After (TechFlow Brand) theme={null}
  ## Shape Colors (Semantic)

  | Semantic Purpose | Fill | Stroke |
  |------------------|------|--------|
  | Primary/Neutral | `#9333ea` | `#4a1d7a` |
  | Secondary | `#c084fc` | `#4a1d7a` |
  | Start/Trigger | `#fde68a` | `#ca8a04` |
  | End/Success | `#86efac` | `#15803d` |
  ```
</CodeGroup>

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:

<Tabs>
  <Tab title="Good Contrast">
    ```json theme={null}
    {
      "backgroundColor": "#9333ea",  // Light-ish purple fill
      "strokeColor": "#4a1d7a"       // Dark purple stroke
    }
    ```

    **Result:** Clear, readable outline.
  </Tab>

  <Tab title="Poor Contrast">
    ```json theme={null}
    {
      "backgroundColor": "#9333ea",  // Purple fill
      "strokeColor": "#a855f7"       // Similar purple stroke
    }
    ```

    **Result:** Stroke blends into fill, looks muddy.
  </Tab>
</Tabs>

### 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:

```markdown theme={null}
| 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                     |

<Warning>
  **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.
</Warning>

## Testing Your Customizations

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

<Steps>
  ### Create a simple test diagram

  ```json test-colors.excalidraw theme={null}
  {
    "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

  ```bash theme={null}
  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.
</Steps>

## Advanced: Color Accessibility

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

<AccordionGroup>
  <Accordion title="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"`)
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="My custom colors aren't being used">
    Ensure you:

    1. Saved the `color-palette.md` file after editing
    2. Used valid hex color codes (e.g., `#3b82f6`, not `blue` or `rgb(59, 130, 246)`)
    3. Kept the same semantic purpose names (don't rename "Primary/Neutral" to "Main Color")
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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`)
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Creating Diagrams" icon="pencil" href="/guides/creating-diagrams">
    Start creating diagrams with your new brand colors
  </Card>

  <Card title="Color Palette Reference" icon="palette" href="/reference/color-palette">
    See the full default color palette reference
  </Card>

  <Card title="Element Templates" icon="code" href="/reference/element-templates">
    Use templates that reference your custom colors
  </Card>
</CardGroup>