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

> Easily create sketchy hand-drawn style diagrams using cathrynlavery/diagram-design. Apply a turbulence filter to warp shapes while keeping text crisp and accessible for clear communication.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-18

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) at line 209, the skill description lists *"Hand-drawn variant → [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```svg
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md) without requiring additional configuration.

### Does the sketchy filter affect text readability?

No. According to the critical rule in [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.