Universal Anti-Patterns: Distinguishing AI Slop from Editorial Diagrams in diagram-design

"AI slop" is formally defined as any diagram that violates the strict visual language encoded in cathrynlavery/diagram-design—specifically generic rounded boxes, drop shadows, unlimited color palettes, mixed typography, and autoplay animations—while editorial-quality artifacts enforce 39 predefined visual types, a 4-pixel grid, WCAG AA contrast, and a maximum 4/10 node density.

The cathrynlavery/diagram-design repository treats editorial diagramming as a constrained design system where deviation from established tokens and layout rules constitutes "slop." By codifying eleven universal anti-patterns into automated linting scripts and CI pipelines, the project ensures deterministic, brand-consistent rendering that large-language-model generators typically fail to produce.

What Constitutes "AI Slop" vs. Editorial Quality

According to the source code analysis, diagrams are classified as "AI slop" when they rely on generic widget libraries, arbitrary styling, or unconstrained layouts. The repository enforces a " behaviour matters" philosophy: diagrams must first select a semantic pattern (e.g., fan-in queue, policy trace) before applying a visual type, ensuring structural integrity overrides purely aesthetic composition.

The Eleven Universal Anti-Patterns

The following categories define the boundary between noise and editorial precision as implemented in the repository's validation suite.

Visual Style Violations

Shapes and Effects
The most visible marker of AI slop is the use of generic rounded-box widgets with varied corner radii and drop-shadows. The README.md at line 19 explicitly forbids "generic rounded boxes," mandating instead the use of 39 predefined visual types. Similarly, line 20 establishes the "no shadows" rule, requiring 1 px hairline borders and flat, crisp SVG outlines without gradients or blur filters.

Colour Palette Constraints
Unlimited "rainbow" schemes and gradients are flagged as anti-patterns. Editorial diagrams must use one accent colour plus semantic roles defined in skills/diagram-design/references/style-guide.md: paper (background), ink (primary text), muted (secondary text), accent (CTA/focal), and link. All values must be drawn from the central token table; any fallback to default generic palettes triggers an error in self_check.py.

Typography Lockdown
Mixed fonts, script faces, or decorative typefaces indicate AI slop. The design system at README.md lines 996–1005 mandates three fixed families exclusively: Instrument Serif for titles, Geist Sans for node names, and Geist Mono for sublabels. No arbitrary font imports are permitted.

Structural and Layout Standards

The 4-Pixel Grid
Irregular spacing and arbitrary coordinates are prohibited. All coordinates, gaps, and dimensions must be divisible by 4, with the layout engine snapping to a strict 4-pixel grid (README.md, lines 996–1005).

Node Density (The 4/10 Rule)
Diagrams containing dozens of unordered nodes violate the density constraint. The system targets 4 focal nodes with ≤10 total elements; excess complexity triggers the "simplify" anti-pattern. As noted at line 29 of README.md, "the highest-quality move is usually deletion."

Layout Semantics
Purely visual layouts without underlying behavioral patterns are rejected. When "behaviour matters," diagrams must select a semantic pattern first (e.g., fan-in queue, policy trace) before applying a visual type. Skipping this step is an explicit anti-pattern (README.md, line 294).

Accessibility and Motion Constraints

Contrast and ARIA
Low-contrast text and missing accessibility attributes define AI slop. The system enforces automatic WCAG AA contrast checks for ink over paper, and every SVG must include <title>, <desc>, and role="img" attributes (README.md, line 39).

Motion Contract
Autoplay and looping animations are anti-patterns per docs/adr/0003-reveal-is-the-only-sanctioned-autoplay.md line 7. Motion is optional and never autoplaying; allowed modes are none, reveal, step, or loop only after explicit user interaction.

Asset Integrity and Import Rules

Iconography Standards
Random icon styles are forbidden. Icons must be monochrome and currentColor-based, sourced exclusively from the 87 curated icons in Tabler Icons and Simple Icons sets (README.md, line 606).

Import Fidelity
Directly reusing source layouts (e.g., draw.io coordinates or Mermaid auto-layout) constitutes AI slop. Import pipelines must redraw the source, discarding original coordinates, palettes, and layout quirks while preserving only structural information—components, relationships, and direction (README.md, line 423).

Automated Enforcement with lint-skin.py and self_check.py

The repository enforces these anti-patterns automatically during CI via .github/workflows/ci.yml. The scripts/lint-skin.py validator checks for shadow usage, grid alignment, and font compliance, while skills/diagram-design/scripts/self_check.py performs runtime validation of generated diagrams.

# Validate motion compliance (prevents autoplay anti-pattern)

python3 scripts/lint-skin.py example-motion-bad.html

# → fails (autoplay detected)

python3 scripts/lint-skin.py example-motion-good.html

# → passes

# Check semantic token adherence

python3 skills/diagram-design/scripts/self_check.py diagram.html

# → ERR: missing semantic tokens; falls back to default "generic" palette (AI slop)

Editorial Workflow Examples

Converting AI Slop to Editorial Quality

The following demonstrates the import pipeline removing generic Mermaid styling and enforcing the design system:

# AI-slop input: raw Mermaid with generic styling and excessive nodes

cat <<'EOF' > sample.mmd
graph TD
    A[User] --> B[Auth Service]
    B --> C[Order Service]
    C --> D[Database]
    D --> E[Cache]
    B --> F[Payments]
    F --> G[Gateway]
    G --> H[Third-Party API]
EOF

# Editorial conversion: redraws with 4px grid, token palette, and 4/10 density

/diagram-design:import-mermaid sample.mmd --detail=simplified --size=slide-16x9

The resulting HTML uses the canonical grid, single accent colour, three-font system, and prunes connectors to respect density limits.

Enforcing Motion Contracts

Non-compliant autoplay implementations are rejected:

<!-- Anti-pattern: autoplaying animation -->
<svg ...>
  <script>/* autoplay code – violates ADR 0003 */</script>
</svg>

Compliant implementations require explicit triggers:

<!-- Editorial standard: user-triggered reveal -->
<svg data-motion="reveal" data-trigger="click">…</svg>

Style Guide Token Reference

Valid diagrams must reference the central token table:

# skills/diagram-design/references/style-guide.md

| Token  | Role         | Value   |
|--------|--------------|---------|
| paper  | background   | #ffffff |
| ink    | primary text | #111111 |
| accent | CTA / focal  | #eb6c36 |
| muted  | secondary    | #666666 |

Summary

• Generic elements are prohibited: Rounded boxes, shadows, and unlimited colours are automatically flagged as AI slop by lint-skin.py.
• Strict token system: Editorial diagrams use one accent colour, three fixed fonts, and 87 curated monochrome icons from style-guide.md.
• Layout discipline: All coordinates snap to a 4-pixel grid, and diagrams must obey the 4/10 node density rule (≤10 elements, ~4 focal).
• Semantic requirement: Layouts must map to predefined behavioral patterns before visual styling is applied.
• Accessibility is mandatory: WCAG AA contrast checks and ARIA attributes are enforced automatically in CI.
• Import pipelines sanitize input: Original coordinates from Mermaid or draw.io are discarded; only structural relationships are preserved.

Frequently Asked Questions

What is the 4/10 density rule in diagram-design?

The 4/10 density rule dictates that high-quality diagrams should target approximately 4 focal nodes with a maximum of 10 total elements. This constraint prevents the visual noise typical of AI-generated diagrams and enforces the principle that "the highest-quality move is usually deletion" (README.md, line 29). Exceeding this density triggers the "simplify" anti-pattern in validation scripts.

How does the repository enforce the "no shadows" rule?

The scripts/lint-skin.py linter scans SVG output for drop-shadows, gradients, and blur filters. According to README.md (line 20), editorial diagrams must use 1 px hairline borders with flat, crisp SVG outlines. Any detected shadow effects cause the CI pipeline to fail, ensuring all assets maintain the flat design language required for brand consistency.

What motion triggers are permitted under the animation contract?

Per docs/adr/0003-reveal-is-the-only-sanctioned-autoplay.md, motion is strictly optional and never autoplaying. Permitted modes are none, reveal, step, or loop, but loop and reveal only activate after explicit user interaction. Autoplay is explicitly listed as an anti-pattern to prevent distracting, unmotivated animation typical of AI slop.

How does the import pipeline handle Mermaid files without preserving AI slop?

The import-mermaid command (documented in commands/import-mermaid.md) redraws the source diagram rather than preserving its layout. It discards original coordinates, colour schemes, and typography, retaining only structural information—components, relationships, and direction. The output is then regenerated using the 4-pixel grid, semantic colour tokens from style-guide.md, and the three-font system, effectively sterilizing the input of generic styling.

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