# How to Add the Sketchy/Hand-Drawn Filter Primitive to a Diagram in Diagram-Design

> Learn how to add the sketchy hand-drawn filter primitive to your diagrams in Diagram-Design. Apply a wobbly stroke effect easily to enhance your graphics.

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

---

**Diagram-Design provides a reusable SVG filter defined in [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md) that applies a hand-drawn, wobbly stroke effect to graphical elements using turbulence and displacement maps while keeping text crisp and readable.**

The **sketchy filter primitive** in the `cathrynlavery/diagram-design` repository allows you to transform precise vector diagrams into casual, hand-drawn style sketches without modifying layout geometry. This optional styling primitive is ideal for essays, blog posts, or wireframes where a "working sketch" aesthetic is desired. According to the source code, the filter combines fractal noise generation with geometric displacement to simulate irregular, organic strokes.

## How the Sketchy Filter Works

The filter implementation relies on a classic SVG technique for wobbly strokes. In [`skills/diagram-design/references/primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md), the filter definition uses `<feTurbulence>` to generate fractal noise and `<feDisplacementMap>` to distort the source graphic based on that noise pattern. This creates the appearance of hand-drawn lines without altering the underlying path data.

Unlike Excalidraw’s native "rough" style, this filter is implemented as a post-processing SVG effect applied to standard vector elements, as documented in [`skills/diagram-design/references/import-excalidraw.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-excalidraw.md).

## Step-by-Step Implementation

### Insert the Filter Definition

Add the filter definition to the `<defs>` section of your SVG output once per diagram. This registers the `id="sketchy"` filter for use throughout the document.

```svg
<svg xmlns="http://www.w3.org/2000/svg" width="800" height="600">
  <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>
  <!-- Diagram content follows -->
</svg>

```

### Apply the Filter to Graphical Elements

Wrap the shapes you want to appear hand-drawn in a `<g>` element that references the filter via the `filter` attribute. This applies the displacement effect to rectangles, circles, paths, and lines.

```svg
<g filter="url(#sketchy)">
  <rect x="50" y="50" width="200" height="100" fill="#4a90e2"/>
  <circle cx="400" cy="100" r="50" fill="#e94a4a"/>
  <line x1="600" y1="30" x2="750" y2="150"
        stroke="#7b5cb0" stroke-width="4"/>
</g>

```

### Exclude Text from the Filtered Group

Keep all text elements—labels, annotations, and titles—outside the filtered group. The displacement map distorts text and renders it unreadable, so maintain text crispness by placing it after the closing `</g>` tag.

```svg
<!-- Labels remain sharp -->
<text x="60" y="45" font-family="sans-serif" font-size="14">
  Sketchy Rectangle
</text>

```

## Customizing the Hand-Drawn Effect

The sketchy filter exposes three tunable parameters in [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md) that control the intensity and character of the wobble:

- **`baseFrequency`** — Controls the coarseness of the fractal noise; higher values create finer, more frequent irregularities
- **`numOctaves`** — Determines the complexity of the turbulence by layering multiple noise octaves
- **`scale`** (in `feDisplacementMap`) — Sets the magnitude of pixel displacement; larger values produce more exaggerated, cartoonish strokes

Adjust these values in the filter definition to shift between subtle pencil sketch effects and bold, marker-style lines.

## Key Source Files

The sketchy filter primitive is documented and implemented across these repository locations:

- **[`skills/diagram-design/references/primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md)** — Contains the complete SVG `<filter>` definition, parameter descriptions, and tuning recommendations
- **[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)** — Advertises the Sketchy variant as an optional primitive available for any diagram type
- **[`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md)** — Lists the filter among available styling options and links to the reference implementation
- **[`skills/diagram-design/references/import-excalidraw.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-excalidraw.md)** — Explains the distinction between this SVG filter and Excalidraw’s native rough rendering

## Summary

- The sketchy filter primitive uses `feTurbulence` and `feDisplacementMap` defined in [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md) to create wobbly strokes
- Apply the effect by wrapping target shapes in `<g filter="url(#sketchy)">` elements
- Always place text labels outside filtered groups to preserve legibility
- Tune `baseFrequency`, `numOctaves`, and `scale` to achieve the desired hand-drawn intensity
- The filter is optional and documented in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) as a variant for all diagram types

## Frequently Asked Questions

### Can I apply the sketchy filter to text elements?

No. The displacement map distorts text and makes it unreadable. According to the source documentation, you must keep all labels, annotations, and text elements outside the filtered `<g>` group to ensure they render crisply while the shapes appear hand-drawn.

### Where is the sketchy filter defined in the repository?

The filter definition lives in [`skills/diagram-design/references/primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md). This file contains the complete SVG filter markup with `feTurbulence` and `feDisplacementMap` primitives, along with a table documenting how to adjust the three key parameters.

### How do I make the sketchy effect more or less intense?

Modify the `baseFrequency`, `numOctaves`, and `scale` attributes within the filter definition. Increasing `baseFrequency` and `scale` values creates more aggressive distortion and larger wobbles, while decreasing them produces subtler, more delicate hand-drawn lines.

### Is the sketchy filter available for all diagram types?

Yes. As implemented in the repository, the Sketchy filter is advertised in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) as an optional primitive that can be enabled for any diagram type generated by Diagram-Design, making it a universal styling option across the toolset.