@haposoft/cafekit 0.7.23 → 0.7.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +81 -862
  2. package/bin/install.js +4 -3
  3. package/package.json +2 -3
  4. package/src/claude/agents/code-auditor.md +25 -1
  5. package/src/claude/agents/spec-maker.md +17 -2
  6. package/src/claude/agents/test-runner.md +22 -3
  7. package/src/claude/hooks/spec-state.cjs +4 -4
  8. package/src/claude/migration-manifest.json +1 -1
  9. package/src/claude/rules/state-sync.md +7 -5
  10. package/src/claude/skills/code-review/references/spec-compliance-review.md +8 -1
  11. package/src/claude/skills/develop/SKILL.md +25 -4
  12. package/src/claude/skills/develop/references/quality-gate.md +23 -13
  13. package/src/claude/skills/generate-graph/LICENSE +21 -0
  14. package/src/claude/skills/generate-graph/README.md +523 -0
  15. package/src/claude/skills/generate-graph/SKILL.md +427 -0
  16. package/src/claude/skills/generate-graph/agentloop-core.svg +101 -0
  17. package/src/claude/skills/generate-graph/agents/openai.yaml +4 -0
  18. package/src/claude/skills/generate-graph/assets/samples/sample-style1-flat.png +0 -0
  19. package/src/claude/skills/generate-graph/assets/samples/sample-style2-dark.png +0 -0
  20. package/src/claude/skills/generate-graph/assets/samples/sample-style3-blueprint.png +0 -0
  21. package/src/claude/skills/generate-graph/assets/samples/sample-style4-notion.png +0 -0
  22. package/src/claude/skills/generate-graph/assets/samples/sample-style5-glass.png +0 -0
  23. package/src/claude/skills/generate-graph/assets/samples/sample-style6-claude.png +0 -0
  24. package/src/claude/skills/generate-graph/assets/samples/sample-style7-openai.png +0 -0
  25. package/src/claude/skills/generate-graph/fixtures/agent-memory-types-style4.json +181 -0
  26. package/src/claude/skills/generate-graph/fixtures/api-flow-style7.json +40 -0
  27. package/src/claude/skills/generate-graph/fixtures/mem0-style1.json +297 -0
  28. package/src/claude/skills/generate-graph/fixtures/microservices-style3.json +64 -0
  29. package/src/claude/skills/generate-graph/fixtures/multi-agent-style5.json +45 -0
  30. package/src/claude/skills/generate-graph/fixtures/system-architecture-style6.json +48 -0
  31. package/src/claude/skills/generate-graph/fixtures/tool-call-style2.json +182 -0
  32. package/src/claude/skills/generate-graph/package.json +42 -0
  33. package/src/claude/skills/generate-graph/references/icons.md +281 -0
  34. package/src/claude/skills/generate-graph/references/style-1-flat-icon.md +108 -0
  35. package/src/claude/skills/generate-graph/references/style-2-dark-terminal.md +107 -0
  36. package/src/claude/skills/generate-graph/references/style-3-blueprint.md +113 -0
  37. package/src/claude/skills/generate-graph/references/style-4-notion-clean.md +94 -0
  38. package/src/claude/skills/generate-graph/references/style-5-glassmorphism.md +125 -0
  39. package/src/claude/skills/generate-graph/references/style-6-claude-official.md +209 -0
  40. package/src/claude/skills/generate-graph/references/style-7-openai.md +215 -0
  41. package/src/claude/skills/generate-graph/references/style-diagram-matrix.md +135 -0
  42. package/src/claude/skills/generate-graph/references/svg-layout-best-practices.md +100 -0
  43. package/src/claude/skills/generate-graph/scripts/generate-diagram.sh +157 -0
  44. package/src/claude/skills/generate-graph/scripts/generate-from-template.py +1556 -0
  45. package/src/claude/skills/generate-graph/scripts/test-all-styles.sh +135 -0
  46. package/src/claude/skills/generate-graph/scripts/validate-svg.sh +292 -0
  47. package/src/claude/skills/generate-graph/templates/agent-architecture.svg +28 -0
  48. package/src/claude/skills/generate-graph/templates/architecture.svg +23 -0
  49. package/src/claude/skills/generate-graph/templates/comparison-matrix.svg +14 -0
  50. package/src/claude/skills/generate-graph/templates/data-flow.svg +28 -0
  51. package/src/claude/skills/generate-graph/templates/er-diagram.svg +21 -0
  52. package/src/claude/skills/generate-graph/templates/flowchart.svg +21 -0
  53. package/src/claude/skills/generate-graph/templates/sequence.svg +20 -0
  54. package/src/claude/skills/generate-graph/templates/state-machine.svg +20 -0
  55. package/src/claude/skills/generate-graph/templates/timeline.svg +19 -0
  56. package/src/claude/skills/generate-graph/templates/use-case.svg +21 -0
  57. package/src/claude/skills/specs/SKILL.md +35 -5
  58. package/src/claude/skills/specs/references/review.md +1 -1
  59. package/src/claude/skills/specs/rules/tasks-generation.md +17 -0
  60. package/src/claude/skills/specs/templates/design.md +13 -0
  61. package/src/claude/skills/specs/templates/init.json +4 -1
  62. package/src/claude/skills/specs/templates/requirements.md +21 -8
  63. package/src/claude/skills/specs/templates/task.md +16 -3
@@ -0,0 +1,215 @@
1
+ # Style 7: OpenAI Official
2
+
3
+ Clean, modern aesthetic matching OpenAI's documentation and research diagrams — minimal but precise.
4
+
5
+ ## Color Palette
6
+
7
+ ```
8
+ Background: #ffffff (pure white)
9
+ Primary text: #0d0d0d (near black)
10
+ Secondary text: #6e6e80 (muted gray)
11
+ Border: #e5e5e5 (light gray)
12
+
13
+ Accent colors (reserved):
14
+ Green accent: #10a37f (OpenAI brand green)
15
+ Blue accent: #1d4ed8 (links, actions)
16
+ Orange accent: #f97316 (highlights, warnings)
17
+ Gray accent: #71717a (secondary elements)
18
+ ```
19
+
20
+ ## Typography
21
+
22
+ ```
23
+ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica Neue, sans-serif
24
+ font-size: 16px node labels, 13px descriptions, 12px arrow labels
25
+ font-weight: 600 for titles, 500 for labels, 400 for descriptions
26
+ letter-spacing: -0.01em (tight)
27
+ ```
28
+
29
+ No custom fonts. System font stack only for maximum compatibility.
30
+
31
+ ## Node Boxes
32
+
33
+ Clean, minimal boxes with subtle borders:
34
+
35
+ ```xml
36
+ <!-- Standard node -->
37
+ <rect x="100" y="100" width="180" height="80" rx="8" ry="8"
38
+ fill="#ffffff" stroke="#e5e5e5" stroke-width="1.5"/>
39
+
40
+ <!-- Accent node (with green left border) -->
41
+ <rect x="100" y="100" width="180" height="80" rx="8" ry="8"
42
+ fill="#ffffff" stroke="#e5e5e5" stroke-width="1.5"/>
43
+ <rect x="100" y="100" width="4" height="80" rx="2" ry="2"
44
+ fill="#10a37f"/>
45
+ ```
46
+
47
+ **Key techniques:**
48
+ 1. White fill with light gray border (no shadows)
49
+ 2. Optional colored left-border accent strip (4px wide)
50
+ 3. `rx="8"` for subtle rounding
51
+ 4. `stroke-width: 1.5` — thin, precise borders
52
+ 5. No gradients, no shadows, no decorative elements
53
+
54
+ ## Arrows
55
+
56
+ Thin, precise arrows with subtle colors:
57
+
58
+ ```xml
59
+ <defs>
60
+ <!-- Default arrow (gray) -->
61
+ <marker id="arrow-oai" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
62
+ <polygon points="0 0, 10 3.5, 0 7" fill="#71717a"/>
63
+ </marker>
64
+
65
+ <!-- Accent arrow (green) -->
66
+ <marker id="arrow-oai-green" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
67
+ <polygon points="0 0, 10 3.5, 0 7" fill="#10a37f"/>
68
+ </marker>
69
+ </defs>
70
+
71
+ <!-- Default connection -->
72
+ <line x1="280" y1="140" x2="400" y2="140"
73
+ stroke="#71717a" stroke-width="1.5" marker-end="url(#arrow-oai)"/>
74
+
75
+ <!-- Accent connection -->
76
+ <line x1="280" y1="140" x2="400" y2="140"
77
+ stroke="#10a37f" stroke-width="1.5" marker-end="url(#arrow-oai-green)"/>
78
+ ```
79
+
80
+ **Arrow guidelines:**
81
+ - Prefer straight lines (orthogonal routing with right angles)
82
+ - `stroke-width: 1.5` — thin and precise
83
+ - Filled polygon arrowheads (not stroke-based)
84
+ - Gray for default, green for primary/accent flows
85
+ - Dashed (`stroke-dasharray="4,3"`) for optional/async flows
86
+
87
+ ## Arrow Labels
88
+
89
+ Minimal, small labels:
90
+
91
+ ```xml
92
+ <text x="340" y="133" text-anchor="middle" fill="#6e6e80" font-size="12">
93
+ label
94
+ </text>
95
+ ```
96
+
97
+ Labels should be:
98
+ - 12px, gray color (`#6e6e80`)
99
+ - No background rect (white background is default)
100
+ - Short, technical language
101
+ - Midpoint of arrow
102
+
103
+ ## Database Shapes
104
+
105
+ Clean cylinders with thin borders:
106
+
107
+ ```xml
108
+ <ellipse cx="200" cy="100" rx="50" ry="12" fill="#ffffff" stroke="#e5e5e5" stroke-width="1.5"/>
109
+ <path d="M 150,100 L 150,140 Q 200,155 250,140 L 250,100"
110
+ fill="#ffffff" stroke="#e5e5e5" stroke-width="1.5"/>
111
+ <ellipse cx="200" cy="140" rx="50" ry="12" fill="none" stroke="#e5e5e5" stroke-width="1.5"/>
112
+ ```
113
+
114
+ ## Grouping Containers
115
+
116
+ Dashed rect containers for logical grouping:
117
+
118
+ ```xml
119
+ <rect x="80" y="80" width="400" height="200" rx="8" ry="8"
120
+ fill="none" stroke="#e5e5e5" stroke-width="1" stroke-dasharray="4,3"/>
121
+ <text x="90" y="97" fill="#6e6e80" font-size="12" font-weight="500">
122
+ Group Label
123
+ </text>
124
+ ```
125
+
126
+ ## Node Content
127
+
128
+ Clean, minimal text layout:
129
+
130
+ ```xml
131
+ <rect x="100" y="100" width="180" height="80" rx="8" ry="8"
132
+ fill="#ffffff" stroke="#e5e5e5" stroke-width="1.5"/>
133
+ <text x="190" y="130" text-anchor="middle" fill="#0d0d0d"
134
+ font-size="16" font-weight="600">
135
+ Component Name
136
+ </text>
137
+ <text x="190" y="150" text-anchor="middle" fill="#6e6e80"
138
+ font-size="13">
139
+ Brief description
140
+ </text>
141
+ ```
142
+
143
+ **Content guidelines:**
144
+ - 1-2 lines per box
145
+ - Main label: 16px, font-weight: 600, near-black
146
+ - Description: 13px, font-weight: 400, gray
147
+ - Center-aligned text within boxes
148
+
149
+ ## Layout Principles
150
+
151
+ **Precise, grid-aligned layout:**
152
+ - Snap all coordinates to 8px grid
153
+ - Consistent 100px horizontal spacing
154
+ - Consistent 120px vertical spacing
155
+ - Generous whitespace (40px+ margins)
156
+ - No decorative elements
157
+
158
+ **OpenAI minimalism:**
159
+ - Only use color when semantically meaningful (brand green for primary flow)
160
+ - White boxes on white background — differentiation through border and label only
161
+ - Avoid: shadows, gradients, patterns, icons, decorative elements
162
+ - Prefer: straight lines, orthogonal routing, thin strokes
163
+
164
+ ## SVG Template
165
+
166
+ ```xml
167
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 600" width="960" height="600">
168
+ <style>
169
+ text { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
170
+ </style>
171
+ <defs>
172
+ <marker id="arrow-oai" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
173
+ <polygon points="0 0, 10 3.5, 0 7" fill="#71717a"/>
174
+ </marker>
175
+ <marker id="arrow-oai-green" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
176
+ <polygon points="0 0, 10 3.5, 0 7" fill="#10a37f"/>
177
+ </marker>
178
+ </defs>
179
+
180
+ <!-- White background -->
181
+ <rect width="960" height="600" fill="#ffffff"/>
182
+
183
+ <!-- Title -->
184
+ <text x="480" y="30" text-anchor="middle" fill="#0d0d0d"
185
+ font-size="20" font-weight="600">Diagram Title</text>
186
+
187
+ <!-- Standard node -->
188
+ <rect x="100" y="70" width="180" height="80" rx="8" ry="8"
189
+ fill="#ffffff" stroke="#e5e5e5" stroke-width="1.5"/>
190
+ <text x="190" y="100" text-anchor="middle" fill="#0d0d0d"
191
+ font-size="16" font-weight="600">Component</text>
192
+ <text x="190" y="120" text-anchor="middle" fill="#6e6e80"
193
+ font-size="13">Description</text>
194
+
195
+ <!-- Connection -->
196
+ <line x1="280" y1="110" x2="400" y2="110"
197
+ stroke="#71717a" stroke-width="1.5" marker-end="url(#arrow-oai)"/>
198
+ <text x="340" y="103" text-anchor="middle" fill="#6e6e80" font-size="12">label</text>
199
+ </svg>
200
+ ```
201
+
202
+ ## Design Philosophy
203
+
204
+ OpenAI Official style emphasizes:
205
+ - **Minimalism**: White on white, only essential visual elements
206
+ - **Precision**: Thin strokes, sharp corners (rx=8), grid-aligned
207
+ - **Clarity**: Content-first, no visual noise
208
+ - **Brand consistency**: `#10a37f` green used sparingly for primary flows
209
+
210
+ Avoid:
211
+ - Shadows and gradients
212
+ - Colorful fills (white fill only)
213
+ - Thick borders (>2px)
214
+ - Decorative elements (icons, patterns, textures)
215
+ - Custom fonts (system stack only)
@@ -0,0 +1,135 @@
1
+ # Style-to-Diagram-Type Adaptation Guide
2
+
3
+ Not all styles work equally well for every diagram type. Use this guide to pick the best style.
4
+
5
+ ## Architecture Diagram
6
+ | Style | Suitability | Notes |
7
+ |-------|----------|
8
+ | 1 Flat Icon | Excellent | Default choice; colorful node fills, clear layering |
9
+ | 2 Dark Terminal | Excellent | Popular for dev blogs; use colored borders on dark bg |
10
+ | 3 Blueprint | Excellent | Perfect for formal architecture docs |
11
+ | 4 Notion Clean | Good | Minimal, works for inline docs |
12
+ | 5 Glassmorphism | Good | Striking for presentations and product pages |
13
+ | 6 Claude Official | Good | Warm aesthetic, Anthropic-style presentations |
14
+ | 7 OpenAI Official | Good | Clean, precise; minimal borders, brand green accents |
15
+
16
+ ## Class Diagram / ER Diagram
17
+ | Style | Suitability | Notes |
18
+ |-------|------------|-------|
19
+ | 1 Flat Icon | Good | Colored headers per class category |
20
+ | 2 Dark Terminal | Good | High contrast for code-like diagrams |
21
+ | 3 Blueprint | Excellent | Best for formal UML documentation |
22
+ | 4 Notion Clean | Excellent | Clean, minimal; ideal for Notion-embedded diagrams |
23
+ | 5 Glassmorphism | Poor | Glass effects distract from structural content |
24
+ | 6 Claude Official | Excellent | Warm, readable; good for documentation |
25
+ | 7 OpenAI Official | Excellent | Minimal aesthetic matches UML precision |
26
+
27
+ ## Sequence Diagram
28
+ | Style | Suitability | Notes |
29
+ |-------|------------|-------|
30
+ | 1 Flat Icon | Good | Clear lifelines; activation boxes visible |
31
+ | 2 Dark Terminal | Good | Good for dev articles; dashed lifelines visible |
32
+ | 3 Blueprint | Excellent | Formal, technical documentation |
33
+ | 4 Notion Clean | Excellent | Best for Notion-embedded sequence diagrams |
34
+ | 5 Glassmorphism | Poor | Glass effects make lifelines hard to read |
35
+ | 6 Claude Official | Excellent | Ward contrast |
36
+ | 7 OpenAI Official | Excellent | Minimal, precise; ideal for API docs |
37
+
38
+ ## Flowchart / Process Flow
39
+ | Style | Suitability | Notes |
40
+ |-------|------------|-------|
41
+ | 1 Flat Icon | Excellent | Default; colorful decision diamonds |
42
+ | 2 Dark Terminal | Good | Works well for dev workflow diagrams |
43
+ | 3 Blueprint | Good | Formal process documentation |
44
+ | 4 Notion Clean | Good | Clean for SOPs and inline docs |
45
+ | 5 Glassmorphism | Good | Striking for product demos |
46
+ | 6 Claude Official | Good | Warm aesthetic for presentations |
47
+ | 7 OpenAI Official | Good | Clean and minimal |
48
+
49
+ ## Mind Map / Concept Map
50
+ | Style | Suitability | Notes |
51
+ |-------|------------|-------|
52
+ | 1 Flat Icon | Excellent branches, engaging |
53
+ | 2 Dark Terminal | Good | Neon-like branches on dark bg |
54
+ | 3 Blueprint | Poor | Blueprint grid conflicts with radial layout |
55
+ | 4 Notion Clean | Excellent | Ideal for n brainstorming |
56
+ | 5 Glassmorphism | Excellent | Stunning visual for presentations |
57
+ | 6 Claude Official | Good | Warm, readable |
58
+ | 7 OpenAI Official | Good | Clean and minimal |
59
+
60
+ ## Data Flow Diagram
61
+ | Style | Suitability | Notes |
62
+ |-------|------------|-------|
63
+ | 1 Flat Icon | Excellent | Color-coded arrows by data type |
64
+ | 2 Dark Terminal | Excellent | Glowing data paths on dark bg |
65
+ | 3 Blueprint | Excellent | Formal data flow documentation |
66
+ | 4 Notion Clean | Good | Minimal, clean |
67
+ | 5 Glassmorphism | Poor | Distracts from flow semantics |
68
+ | 6 Claude Official | Good | Readable |
69
+ | 7 OpenAI Official | Good | Precise, minimal |
70
+
71
+ ## Use Case Diagram
72
+ | Style | Suitability | Notes |
73
+ |-------|------------|-------|
74
+ | 1 Flat Icon | Good | Colorful use case ellipses |
75
+ | 2 Dark Terminal | Poor | Stick figures less visible on dark bg |
76
+ | 3 rint | Excellent | Classic UML aesthetic |
77
+ | 4 Notion Clean | Excellent | Perfect for product requirement docs |
78
+ | 5 Glassmorphism | Poor | Unnecessary visual noise |
79
+ | 6 Claude Official | Excellent | Warm, professional |
80
+ | 7 OpenAI Official | Excellent | Clean, precise UML |
81
+
82
+ ## State Machine Diagram
83
+ | Style | Suitability | Notes |
84
+ |-------|------------|-------|
85
+ Flat Icon | Good | Colorful states |
86
+ | 2 Dark Terminal | Good | Glowing states and transitions |
87
+ | 3 Blueprint | Excellent | Best for formal UML state machines |
88
+ | 4 Notion Clean | Excellent | Clean for documentation |
89
+ | 5 Glassmorphism | Poor | Distracts from state transitions |
90
+ | 6 Claude Official | Excellent | Readable |
91
+ | 7 OpenAI Official | Excellent | Minimal, precise |
92
+
93
+ ## Network Topology
94
+ | Style | Suitabili |
95
+ |-------|------------|-------|
96
+ | 1 Flat Icon | Excellent | Colorful device icons |
97
+ | 2 Dark Terminal | Excellent | Cyberpunk-style network maps |
98
+ | 3 Blueprint | Excellent | Ideal for infrastructure docs |
99
+ | 4 Notion Clean | Good | Clean for IT documentation |
100
+ | 5 Glassmorphism | Good | Striking for presentations |
101
+ | 6 Claude Official | Good | Professional network diagrams |
102
+ | 7 OpenAI Official | Good | Clean infrastructure diagrams |
103
+
104
+ ## Comparison / Feature Matrix
105
+ | Style | Suitability | Notes |
106
+ |-------|------------|-------|
107
+ | 1 Flat Icon | Excellent | Color-coded checkmarks |
108
+ | 2 Dark Terminal | Good | Works for dev tool comparisons |
109
+ | 3 Blor | Grid conflicts with table layout |
110
+ | 4 Notion Clean | Excellent | Perfect for Notion-embedded tables |
111
+ | 5 Glassmorphism | Poor | Distabular data |
112
+ | 6 Claude Official | Excellent | Clean, warm |
113
+ | 7 OpenAI Official | Excellent | Minimal, precise |
114
+
115
+ ## Timeline / Gantt
116
+ | Style | Suitability | Notes |
117
+ |-------|------------|-------|
118
+ | 1 Flat Icon | Excellent | Colorful bars by category |
119
+ | 2 Dark Terminal | Good | Works for dev roadmaps |
120
+ | 3 Blueprint | Good | Formal project plans |
121
+ | 4 Notion Clean | Excellent | Ideal for Notion project docs |
122
+ | 5 Glassmorphism | Good | Striking for keynote presentations |
123
+ | 6 Claude Official | Good | Warm, professional |
124
+ | 7 OpenAI Official | Good | Clean timeline |
125
+
126
+ ## Agent / Memory Architecture
127
+ | Style | Suitability | Notes |
128
+ |-------|------------|-------|
129
+ | 1 Flat Icon | Excellent | Colorful layers, engaging |
130
+ | 2 Dark Terminal | Excellent | Popular for AI/ML blog posts |
131
+ | 3 Blueprint | Good | Formal AI system documentation |
132
+ | 4 Notion Clean | Good | Clean for AI research notes |
133
+ | 5 Glassmorphism | Excellent | Stunning for AI product presentations |
134
+ | 6 Claude Official | Excellent | Anthropic AI aesthetic |
135
+ | 7 OpenAI Official | Excellent | OpenAI AI aesthetic |
@@ -0,0 +1,100 @@
1
+ # SVG Technical Diagram Layout Best Practices
2
+
3
+ ## Universal Layout Rules (Apply to All Styles)
4
+
5
+ ### 1. Component Spacing
6
+ - **Minimum clearance between components**: 80px (edge to edge)
7
+ - **Minimum clearance for arrow paths**: 60px from component edges
8
+ - **Layer vertical spacing**: 120px between horizontal layers
9
+ - **Same-layer horizontal spacing**: 100-120px between components
10
+
11
+ ### 2. Arrow Routing & Connection Points
12
+
13
+ #### Connection Point Rules
14
+ - **Never connect arrows to component corners** - use midpoints of edges
15
+ - **Entry/exit points**:
16
+ - Top edge: `cx ± offset` where offset = 0 for single arrow, ±30px for multiple
17
+ - Bottom edge: same rule
18
+ - Left/right edges: `cy ± offset`
19
+ - **Clearance from corners**: minimum 20px
20
+
21
+ #### Arrow Path Routing
22
+ - **Avoid diagonal lines crossing components** - use orthogonal routing (L-shaped paths)
23
+ - **For curved arrows**:
24
+ - Control point should be at least 40px away from any component edge
25
+ - Use intermediate waypoints for complex routing: `M x1,y1 L x2,y2 Q cx,cy x3,y3`
26
+ - **Multiple arrows between same layers**: stagger Y-coordinates by 15-20px to avoid overlap
27
+
28
+ #### Arrow Overlap Prevention
29
+ ```svg
30
+ <!-- Bad: diagonal arrow crosses component -->
31
+ <path d="M 200,100 L 600,400"/>
32
+
33
+ <!-- Good: orthogonal routing around component -->
34
+ <path d="M 200,100 L 200,250 L 600,250 L 600,400"/>
35
+
36
+ <!-- Good: curved with safe control point -->
37
+ <path d="M 200,100 Q 400,200 600,400"/>
38
+ <!-- Control point (400,200) is 50px+ away from any component -->
39
+ ```
40
+
41
+ ### 3. Arrow Label Placement
42
+ - **Position**: midpoint of arrow path, offset by 5-10px perpendicular to arrow direction
43
+ - **Background rect**: ALWAYS include, with:
44
+ - Padding: 4px horizontal, 2px vertical
45
+ - Fill: match ckground color
46
+ - Opacity: 0.9-0.95
47
+ - **Safety distance**: 15px minimum from any component edge
48
+ - **Multiple converging arrows**: stagger label positions vertically by 20px
49
+
50
+ ### 4. Component Overlap Detection
51
+ Before finalizing SVG, check:
52
+ - No component bounding boxes overlap px safety margin)
53
+ - No arrow paths pass through component interiors (except intentional tunneling with dashed style)
54
+ - No text labels overlap with components or other labels
55
+
56
+ ### 5. Z-Index Layering (SVG render order)
57
+ ```svg
58
+ <!-- Render order (top to bot back to front): -->
59
+ 1. Background rect
60
+ 2. Grouping coners (dashed rects)
61
+ 3. Arrow paths
62
+ 4. Arrow label background rects
63
+ 5. Components (boxes, cylinders, etc.)
64
+ 6. Component text
65
+ 7. Arrow label text
66
+ 8. Legend
67
+ ```
68
+
69
+ ## Style-Specific Enhancements
70
+
71
+ ### Style-1: Flat Icon Clean- **Perfect alignment**: snap all coordinates to 8px grid
72
+ - **Sharp corners**: rx="8" ry="8" for rounded rects (consistent)
73
+ - **Arrows**: thin (1.5-2px), filled polygon markers
74
+ - **No shadows**: flat design principle
75
+
76
+ ### Style-6: Claude Official Warm
77
+ - **Soft shadows**: `<feDropShadow dx="0" dy="2" stdDeviation="6" flood-color="#00000008"/>`
78
+ - **Rounded corners**: rx="12" ry="12" (more rounded than Style-1)
79
+ - **Arrows**: medium weight (2px), subtle markers
80
+
81
+ ## Validation Checklist
82
+
83
+ Before exporting PNG, verify:
84
+ - [ ] No arrow-component overlaps (visual inspection)
85
+ - [ ] All arrow labels have background rects
86
+ - [ ] Minimum 60px clearance for all arrow paths
87
+ - [ ] Component spacing ≥ 80px
88
+ - [ ] Arrow connection points avoid corners (≥20px from corner)
89
+ - [ ] Multiple arrows between layers are staggered
90
+ - [ ] Legend is readable and doesn't overlap content
91
+ - [ ] SVG validates with `rsvg-convert`
92
+
93
+ ## Common Anti-Patterns to Avoid
94
+
95
+ | Anti-Pattern | Fix |
96
+ |--------------|-----|
97
+ | Arrow crosses component | Use orthogonal routingase control point distancelabel overlaps component | Add background rect + increase offset |
98
+ | Components too close | Increase spacing to 80px minimum |
99
+ | Arrow connects to corner | Move connection point to edge midpoint offset |
100
+ | No z-index planning | Follow render order: arrows -> components -> text |
@@ -0,0 +1,157 @@
1
+ #!/bin/bash
2
+ # SVG Diagram Generation - Validates and exports SVG diagrams with PNG export
3
+
4
+ set -euo pipefail
5
+
6
+ # Colors
7
+ RED='\033[0;31m'
8
+ GREEN='\033[0;32m'
9
+ YELLOW='\033[1;33m'
10
+ BLUE='\033[0;34m'
11
+ NC='\033[0m'
12
+
13
+ # Default values
14
+ STYLE="1"
15
+ WIDTH="1920"
16
+ OUTPUT_DIR="."
17
+ VALIDATE=true
18
+
19
+ # Valid diagram types
20
+ VALID_TYPES="architecture|data-flow|flowchart|sequence|comparison|timeline|mind-map|agent|memory|use-case|class|state-machine|er-diagram|network-topology"
21
+
22
+ usage() {
23
+ cat << USAGE
24
+ Usage: $0 [OPTIONS]
25
+
26
+ Options:
27
+ -t, --type TYPE Diagram type ($VALID_TYPES)
28
+ -s, --style STYLE Style number (1-7, default: 1)
29
+ -o, --output PATH Output path (default: current directory)
30
+ -w, --width WIDTH PNG width in pixels (default: 1920)
31
+ --no-validate Skip validation
32
+ -h, --help Show this help
33
+
34
+ Examples:
35
+ $0 -t architecture -s 1 -o ./output/arch.svg
36
+ $0 -t class -s 2 -w 2400
37
+ $0 -t sequence -s 6
38
+ USAGE
39
+ exit 0
40
+ }
41
+
42
+ # Parse arguments
43
+ while [[ $# -gt 0 ]]; do
44
+ case $1 in
45
+ -t|--type)
46
+ TYPE="$2"
47
+ shift 2
48
+ ;;
49
+ -s|--style)
50
+ STYLE="$2"
51
+ shift 2
52
+ ;;
53
+ -o|--output)
54
+ OUTPUT_PATH="$2"
55
+ shift 2
56
+ ;;
57
+ -w|--width)
58
+ WIDTH="$2"
59
+ shift 2
60
+ ;;
61
+ --no-validate)
62
+ VALIDATE=false
63
+ shift
64
+ ;;
65
+ -h|--help)
66
+ usage
67
+ ;;
68
+ *)
69
+ echo -e "${RED}Unknown option: $1${NC}"
70
+ usage
71
+ ;;
72
+ esac
73
+ done
74
+
75
+ # Check required parameters
76
+ if [ -z "${TYPE:-}" ]; then
77
+ echo -e "${RED}Error: Diagram type is required${NC}"
78
+ usage
79
+ fi
80
+
81
+ # Validate type
82
+ VALID_TYPE=false
83
+ for t in architecture data-flow flowchart sequence comparison timeline mind-map agent memory use-case class state-machine er-diagram network-topology; do
84
+ if [ "$TYPE" = "$t" ]; then
85
+ VALID_TYPE=true
86
+ break
87
+ fi
88
+ done
89
+
90
+ if [ "$VALID_TYPE" = false ]; then
91
+ echo -e "${RED}Error: Invalid diagram type '$TYPE'${NC}"
92
+ echo "Valid types: $VALID_TYPES"
93
+ exit 1
94
+ fi
95
+
96
+ # Determine output path
97
+ if [ -z "${OUTPUT_PATH:-}" ]; then
98
+ BASENAME="${TYPE}-style${STYLE}"
99
+ SVG_FILE="${OUTPUT_DIR}/${BASENAME}.svg"
100
+ PNG_FILE="${OUTPUT_DIR}/${BASENAME}.png"
101
+ else
102
+ SVG_FILE="$OUTPUT_PATH"
103
+ PNG_FILE="${OUTPUT_PATH%.svg}.png"
104
+ fi
105
+
106
+ echo -e "${BLUE}Generating ${TYPE} diagram (style ${STYLE})...${NC}"
107
+ echo "Output: $SVG_FILE"
108
+
109
+ # Load style reference
110
+ SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
111
+ STYLE_FILE=$(find "${SKILL_DIR}/references" -maxdepth 1 -type f -name "style-${STYLE}-*.md" | head -n 1)
112
+
113
+ if [ -z "${STYLE_FILE:-}" ] || [ ! -f "$STYLE_FILE" ]; then
114
+ echo -e "${RED}Error: Style file not found: ${STYLE_FILE}${NC}"
115
+ echo "Available styles: 1-7"
116
+ exit 1
117
+ fi
118
+
119
+ # Note: Actual SVG generation is done by Claude Code
120
+ # This script provides validation and export only
121
+
122
+ echo -e "${YELLOW}Note: SVG content generation requires Claude Code${NC}"
123
+ echo -e "${YELLOW}This script provides validation and export only${NC}"
124
+
125
+ # Validate if SVG exists
126
+ if [ -f "$SVG_FILE" ]; then
127
+ if [ "$VALIDATE" = true ]; then
128
+ echo -e "\n${BLUE}Validating SVG...${NC}"
129
+ if "${SKILL_DIR}/scripts/validate-svg.sh" "$SVG_FILE"; then
130
+ echo -e "${GREEN}Validation passed${NC}"
131
+ else
132
+ echo -e "${RED}Validation failed${NC}"
133
+ exit 1
134
+ fi
135
+ fi
136
+
137
+ # Export PNG
138
+ echo -e "\n${BLUE}Exporting PNG (width: ${WIDTH}px)...${NC}"
139
+ if command -v rsvg-convert &> /dev/null; then
140
+ if rsvg-convert -w "$WIDTH" "$SVG_FILE" -o "$PNG_FILE" 2>/dev/null; then
141
+ PNG_SIZE=$(du -h "$PNG_FILE" | cut -f1)
142
+ echo -e "${GREEN}PNG exported: $PNG_FILE (${PNG_SIZE})${NC}"
143
+ else
144
+ echo -e "${RED}PNG export failed${NC}"
145
+ exit 1
146
+ fi
147
+ else
148
+ echo -e "${RED}Error: rsvg-convert not found${NC}"
149
+ echo "Install with: brew install librsvg"
150
+ exit 1
151
+ fi
152
+ else
153
+ echo -e "${YELLOW}SVG file not found. Generate it first with Claude Code.${NC}"
154
+ exit 1
155
+ fi
156
+
157
+ echo -e "\n${GREEN}Done${NC}"