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

Diagram-Design applies a sketchy, hand-drawn appearance by injecting an SVG turbulence filter from 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). 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:

# 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:

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: Contains the actual SVG filter definition (<filter id="sketchy">) using <feTurbulence> and <feDisplacementMap> primitives.
• SKILL.md: Documents the hand-drawn variant as an optional styling parameter applicable across all diagram types.
• 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 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). 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, 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 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.

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