How to Create Sketchy or Hand-Drawn Style Diagrams with Diagram-Design

Request a "hand-drawn" or "sketchy" variant when generating any of the 28 supported diagram types to automatically apply the SVG turbulence filter defined in primitive-sketchy.md, which warps shapes while keeping text crisp and accessible.

The cathrynlavery/diagram-design repository generates clean, editorial-style diagrams as SVG/HTML. When you need to create sketchy or hand-drawn style diagrams for essays, newsletters, or narrative content, the skill offers a lightweight variant that applies a reusable SVG filter without sacrificing text legibility or accessibility.

How the Sketchy Filter Works Under the Hood

Triggering the Variant via SKILL.md

In skills/diagram-design/SKILL.md at line 209, the skill description lists "Hand-drawn variant → primitive-sketchy.md". When the LLM detects phrases like "hand-drawn," "sketchy," or "make it look like a doodle," it dynamically loads the additional reference file rather than applying the filter to every diagram by default.

The SVG Filter Implementation

The skills/diagram-design/references/primitive-sketchy.md file defines a reusable SVG <filter> called sketchy that uses feTurbulence and feDisplacementMap to create the wobbly effect (lines 7-14). The filter applies fractal noise with a base frequency of 0.02 and two octaves, then displaces the source graphic by 1.5 units. Because the filter is script-free and self-contained, it adds negligible overhead to the rendering pipeline.

Application Rules and Critical Constraints

According to primitive-sketchy.md lines 33-35, the skill enforces a critical architectural rule: the filter is applied to shape elements (rectangles, paths, circles) wrapped in <g filter="url(#sketchy)">, but text elements must remain outside this group. This ensures typography stays crisp and screen-reader accessible while the graphics receive the hand-drawn treatment. The documentation also warns against using the sketchy style for dense technical documentation or dark-theme variants (lines 36-44).

Step-by-Step Guide to Creating Sketchy Diagrams

1. Generate a base diagram – Request any of the 28 supported types (flowcharts, sequence diagrams, etc.) through your AI coding agent.

2. Request the sketchy style – Append phrases like "in a sketchy style," "hand-drawn version," or "make it look like a doodle" to your prompt.

3. Automatic filter injection – The skill loads primitive-sketchy.md and wraps the SVG shapes in the filtered group before returning the HTML/SVG file.

4. Export the result – Use the standard export commands to obtain the final asset in your desired format.

Customizing the Hand-Drawn Effect Manually

If you need to fine-tune the sketchiness, you can edit the SVG directly. Insert the filter definition in the <defs> section and wrap your shapes accordingly:

<defs>
  <filter id="sketchy" x="-2%" y="-2%" width="104%" height="104%">
    <feTurbulence type="fractalNoise" baseFrequency="0.02" numOctaves="2" seed="4"/>
    <feDisplacementMap in="SourceGraphic" scale="1.5"/>
  </filter>
</defs>

<!-- Apply to shapes only -->
<g filter="url(#sketchy)">
  <rect x="10" y="10" width="180" height="80" fill="#fff" stroke="#000"/>
  <path d="M20,20 L180,20" stroke="#000"/>
</g>

<!-- Keep text outside for legibility -->
<text x="30" y="45" font-family="sans-serif" font-size="14">Start</text>

As documented in primitive-sketchy.md lines 24-31, adjust baseFrequency (0.01–0.05), numOctaves (1–3), or scale (0.5–3.0) to achieve lighter or more exaggerated sketchiness. Higher baseFrequency values create tighter noise patterns, while increasing scale amplifies the wobble displacement.

Exporting Sketchy Diagrams

After generation, export your hand-drawn diagram using the standard CLI commands. The sketchy filter remains embedded in the SVG, ensuring PNG rasterization preserves the effect:

# Export as SVG (filter embedded)

/export-diagram path/to/diagram.html --svg-only

# Export high-resolution PNG

export-diagram path/to/diagram.html --png-only --scale=3

The exported SVG contains the filter definition inline, so the wobbly appearance persists when viewed in browsers or converted to raster formats via Playwright.

Summary

• cathrynlavery/diagram-design supports sketchy variants for all 28 diagram types via primitive-sketchy.md.
• The SVG filter uses feTurbulence and feDisplacementMap to warp shapes without affecting text legibility.
• Trigger the style by requesting "hand-drawn" or "sketchy" in your prompt; the skill loads the filter dynamically from SKILL.md line 209.
• Always keep text elements outside the filtered group to maintain accessibility.
• Avoid sketchy styles for dense technical documentation or dark themes.

Frequently Asked Questions

What diagram types support the sketchy style?

All 28 visual diagram types available in the cathrynlavery/diagram-design repository support the hand-drawn variant. When you request a sketchy version of any flowchart, sequence diagram, or architecture diagram, the skill automatically applies the filter defined in primitive-sketchy.md without requiring additional configuration.

Does the sketchy filter affect text readability?

No. According to the critical rule in primitive-sketchy.md lines 33-35, the filter is applied only to graphical elements wrapped in <g filter="url(#sketchy)">. Text elements remain outside this group, ensuring typography stays crisp and accessible while shapes receive the wobbly hand-drawn effect.

Can I adjust the intensity of the hand-drawn effect?

Yes. The primitive-sketchy.md file documents tunable parameters including baseFrequency (controls noise granularity), numOctaves (complexity), and scale (displacement intensity). Adjust these values in the SVG filter definition to create anything from subtle sketchiness to exaggerated doodle effects.

When should I avoid using the sketchy style?

Avoid the sketchy variant for dense technical documentation or dark-theme diagrams, as noted in primitive-sketchy.md lines 36-44. The filter is optimized for narrative contexts like essays, blog posts, and newsletters where an informal, hand-drawn aesthetic enhances readability rather than detracting from it.

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