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

The Diagram Design skill provides a built-in Sketchy filter defined in 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 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. 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 at line 509, the skill lists an optional "Hand-drawn variant" mapped to 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 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. 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 (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. 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, 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

<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 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, 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 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, 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 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.

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