# How to Create a Sketchy or Hand-Drawn Variant of a Diagram Using the Diagram Design Skill

> Easily create a sketchy or hand-drawn diagram variant with the Diagram Design skill. Apply a simple filter to transform clean SVGs into hand-drawn illustrations.

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

---

**The Diagram Design skill provides a built-in Sketchy filter defined in [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md) that transforms any clean SVG diagram into a hand-drawn-style illustration by wrapping graphic elements in a filtered `<g>` element.**

The `cathrynlavery/diagram-design` repository defines a complete specification for producing architectural diagrams, including an optional sketchy aesthetic. To create a sketchy or hand-drawn variant of a diagram, the skill exposes an SVG turbulence filter that adds organic jitter to shapes while preserving layout and connector logic. The top-level [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) also surfaces the hand-drawn version request and points users to the Sketchy primitive, so the effect is discoverable without external tools.

## How the Sketchy Filter Works

The Sketchy filter relies on **SVG filter primitives** declared in [`skills/diagram-design/references/primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md). It combines `<feTurbulence>` with `type="fractalNoise"` and `<feDisplacementMap>` to distort the edges of rendered geometry, producing a rough, hand-drawn appearance. Because the filter is applied inside the SVG markup, it works with any diagram variant—minimal, dark, full, or consultant—without altering underlying coordinate or connector data.

## Steps to Apply the Sketchy Filter

### Request the Sketchy Variant

According to [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) at line 509, the skill lists an optional "Hand-drawn variant" mapped to [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md). When invoking the skill, add the *sketchy* flag or explicitly request a "hand-drawn version" to enable the filter.

### Insert the Filter Definition

Place the `<defs>` block from [`skills/diagram-design/references/primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md) directly after the `<title>` element inside your `<svg>` root. Lines 9–13 define the `id="sketchy"` filter using `<feTurbulence>` and `<feDisplacementMap>` primitives.

### Wrap Shapes in a Filtered Group

Enclose all non-text shapes—such as `<rect>`, `<path>`, `<circle>`, and `<line>`—inside a single group with the attribute `filter="url(#sketchy)"` as shown in lines 15–19 of [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md). Only elements inside this group receive the displacement effect.

### Leave Text Outside the Filter

Keep all `<text>` elements outside the filtered `<g>` group so typography remains crisp. The reference file highlights this rule in lines 20–21, ensuring labels stay legible against the wobbly geometry.

### Tune Filter Parameters for Custom Jitter

You can adjust four attributes to refine the hand-drawn look. The tuning table in [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md) (lines 26–31) recommends starting values for:

- **`baseFrequency`** – controls the frequency of the fractal noise.
- **`numOctaves`** – sets the level of noise detail.
- **`scale`** – determines the intensity of displacement applied to the source graphic.
- **`seed`** – provides a reproducible randomization source for the noise pattern.

## Validating and Exporting the Sketchy Diagram

Before finishing, verify the output against the pre-output checklist in section 9 of [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md). The sketchy filter does not affect layout or connector rules, so the diagram must still satisfy all connector and label-gap taste-gate requirements.

Exporting requires no extra steps. As documented in [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md), SVG and PNG renders are derived directly from the HTML output, meaning the sketchy effect propagates automatically to every exported format.

## Runnable SVG Code Example

```html
<svg role="img" aria-labelledby="my-diagram-title my-diagram-desc">
  <title id="my-diagram-title">Feature Overview</title>
  <desc id="my-diagram-desc">Hand-drawn style diagram of the feature flow.</desc>

  <!-- Filter definition from primitive-sketchy.md -->
  <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>

  <!-- Graphic elements wrapped in the filtered group -->
  <g filter="url(#sketchy)">
    <rect x="40" y="40" width="120" height="80" fill="#fff" stroke="#2d3142"/>
    <path d="M160 80 H260" stroke="#2d3142" stroke-width="1"/>
  </g>

  <!-- Text stays outside the filtered group -->
  <text x="100" y="70" fill="#2d3142" font-family="Geist" font-size="12">
    Process step
  </text>
</svg>

```

Adjust `baseFrequency`, `numOctaves`, `scale`, and `seed` to achieve the exact jitter intensity you need.

## Summary

- The Diagram Design skill includes a built-in **Sketchy filter** defined in [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md) for creating hand-drawn diagram variants.
- Apply the filter by inserting the `<defs>` block into the SVG and wrapping shapes in `<g filter="url(#sketchy)">`.
- Keep **text elements outside** the filtered group to maintain crisp readability.
- Tune **`baseFrequency`**, **`numOctaves`**, **`scale`**, and **`seed`** to control the roughness of the effect.
- The sketchy variant passes through the standard export pipeline automatically, with no post-processing required.

## Frequently Asked Questions

### Does the sketchy filter affect diagram layout or connectors?

No. According to section 9 of [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), the sketchy filter is purely presentational. It does not alter layout calculations, connector paths, or label-gap measurements, so the diagram must still pass the standard taste-gate checklist.

### Can I use the sketchy variant with any diagram style?

Yes. The [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) specification at line 509 notes that the sketchy variant can be applied to any diagram variant, including minimal, dark, full, or consultant styles. The filter is style-agnostic because it acts on the final SVG geometry.

### Why must text remain outside the filtered group?

Text must stay outside the `<g filter="url(#sketchy)">` element to preserve legibility. As noted in lines 20–21 of [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md), applying the displacement filter to typography would distort letterforms and reduce readability, whereas keeping text crisp ensures labels remain professional.

### Do I need to manually convert the output to SVG or PNG?

No manual conversion is necessary. The [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) file states that non-HTML formats such as SVG and PNG are derived directly from the HTML output. Once the sketchy filter is present in the markup, it propagates automatically to every exported format.