# How to Apply Sketchy Hand-Drawn Styling to Diagrams in Diagram-Design

> Easily apply sketchy hand-drawn styling to your diagrams in Diagram-Design using the --style sketchy flag or API option. Transform your visuals with a unique artistic touch.

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

---

**Diagram-Design applies a sketchy, hand-drawn appearance by injecting an SVG turbulence filter from [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md), activated via the `--style sketchy` CLI flag or `style: "sketchy"` API option.**

The **diagram-design** library by cathrynlavery includes a built-in **sketchy styling** feature that transforms precise vector diagrams into informal, hand-drawn visuals. This implementation leverages SVG filter primitives to mathematically perturb stroke paths, creating a natural pencil-sketch aesthetic ideal for presentations and essays.

## Understanding the SVG Filter Implementation

The hand-drawn effect originates in [[`skills/diagram-design/references/primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md). This file defines an SVG `<filter>` element with the ID `sketchy` that applies to the entire diagram canvas.

The filter configuration extends beyond the viewport boundaries (`x="-2%" y="-2%" width="104%" height="104%"`) to ensure edge elements remain fully affected. It combines `<feTurbulence>` with `<feDisplacementMap>` to offset vector paths procedurally, producing the characteristic wobble of hand-drawn lines. When rendering, Diagram-Design wraps the diagram elements in a group tag with `filter="url(#sketchy)"`, instantiating the displacement effect.

## Enabling Sketchy Styling

You can activate the sketchy variant through either the command-line interface or the JavaScript API.

### Command Line Usage

Pass the `--style sketchy` flag to any diagram generation command. The following example converts a Mermaid flowchart to a sketch-styled SVG:

```bash

# Generate a flowchart with the sketchy (hand-drawn) look

diagram-design import-mermaid sample-flowchart.mmd \
  --style sketchy \
  --output diagram.svg

```

### Programmatic API Usage

For Node.js applications, import the `DiagramDesign` class and specify `style: "sketchy"` in the render options:

```javascript
import { DiagramDesign } from "diagram-design";

// Load a Mermaid source
const mermaidSource = await fetch("sample-flowchart.mmd").then(r => r.text());

// Create a diagram with the sketchy skin
const diagram = await DiagramDesign.render({
  source: mermaidSource,
  format: "svg",
  style: "sketchy",   // activates the SVG turbulence filter
});

await diagram.save("diagram.svg");

```

## Key Source Files and Configuration

According to the repository documentation, the sketchy style is an optional variant available for all supported diagram types, including flowcharts and Gantt charts.

- **[`skills/diagram-design/references/primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md)**: Contains the actual SVG filter definition (`<filter id="sketchy">`) using `<feTurbulence>` and `<feDisplacementMap>` primitives.
- **[`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)**: Documents the hand-drawn variant as an optional styling parameter applicable across all diagram types.
- **[`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md)**: Describes the "Sketchy filter" as utilizing "SVG turbulence + displacement map for a hand-drawn variant," recommending it for essays while cautioning against use in technical documentation requiring precision.

## Summary

- The sketchy effect is implemented via an SVG filter defined in [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md) that mathematically displaces vector paths using turbulence noise.
- Activate the style using `--style sketchy` in CLI commands or `style: "sketchy"` in the `DiagramDesign.render()` API.
- The filter applies 2% overflow coverage (`width="104%"`) to ensure consistent rendering at canvas edges.
- This styling is recommended for informal contexts like essays and presentations, not for technical documentation where geometric precision is required.

## Frequently Asked Questions

### What file contains the sketchy filter definition?

The SVG filter definition resides in [[`skills/diagram-design/references/primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md). This file specifies the `<filter>` element with ID `sketchy` that implements the turbulence and displacement effects used to create the hand-drawn appearance.

### Can I apply sketchy styling to any diagram type?

Yes. According to [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), the sketchy variant is an optional style that can be applied to any diagram type supported by Diagram-Design, including flowcharts, Gantt charts, and sequence diagrams, by including the style reference in command options.

### Is the sketchy style suitable for technical documentation?

No. The repository's [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) explicitly states that while the sketchy filter is "good for essays," it is not appropriate for technical documentation where exact precision and clarity of line work are essential.

### How does the SVG filter create the hand-drawn effect?

The filter uses `<feTurbulence>` to generate random noise and `<feDisplacementMap>` to apply that noise as geometric displacement to the diagram's vector paths. This mathematical perturbation mimics the natural irregularities and wobble characteristic of hand-drawn pencil strokes.