@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.
- package/README.md +81 -862
- package/bin/install.js +4 -3
- package/package.json +2 -3
- package/src/claude/agents/code-auditor.md +25 -1
- package/src/claude/agents/spec-maker.md +17 -2
- package/src/claude/agents/test-runner.md +22 -3
- package/src/claude/hooks/spec-state.cjs +4 -4
- package/src/claude/migration-manifest.json +1 -1
- package/src/claude/rules/state-sync.md +7 -5
- package/src/claude/skills/code-review/references/spec-compliance-review.md +8 -1
- package/src/claude/skills/develop/SKILL.md +25 -4
- package/src/claude/skills/develop/references/quality-gate.md +23 -13
- package/src/claude/skills/generate-graph/LICENSE +21 -0
- package/src/claude/skills/generate-graph/README.md +523 -0
- package/src/claude/skills/generate-graph/SKILL.md +427 -0
- package/src/claude/skills/generate-graph/agentloop-core.svg +101 -0
- package/src/claude/skills/generate-graph/agents/openai.yaml +4 -0
- package/src/claude/skills/generate-graph/assets/samples/sample-style1-flat.png +0 -0
- package/src/claude/skills/generate-graph/assets/samples/sample-style2-dark.png +0 -0
- package/src/claude/skills/generate-graph/assets/samples/sample-style3-blueprint.png +0 -0
- package/src/claude/skills/generate-graph/assets/samples/sample-style4-notion.png +0 -0
- package/src/claude/skills/generate-graph/assets/samples/sample-style5-glass.png +0 -0
- package/src/claude/skills/generate-graph/assets/samples/sample-style6-claude.png +0 -0
- package/src/claude/skills/generate-graph/assets/samples/sample-style7-openai.png +0 -0
- package/src/claude/skills/generate-graph/fixtures/agent-memory-types-style4.json +181 -0
- package/src/claude/skills/generate-graph/fixtures/api-flow-style7.json +40 -0
- package/src/claude/skills/generate-graph/fixtures/mem0-style1.json +297 -0
- package/src/claude/skills/generate-graph/fixtures/microservices-style3.json +64 -0
- package/src/claude/skills/generate-graph/fixtures/multi-agent-style5.json +45 -0
- package/src/claude/skills/generate-graph/fixtures/system-architecture-style6.json +48 -0
- package/src/claude/skills/generate-graph/fixtures/tool-call-style2.json +182 -0
- package/src/claude/skills/generate-graph/package.json +42 -0
- package/src/claude/skills/generate-graph/references/icons.md +281 -0
- package/src/claude/skills/generate-graph/references/style-1-flat-icon.md +108 -0
- package/src/claude/skills/generate-graph/references/style-2-dark-terminal.md +107 -0
- package/src/claude/skills/generate-graph/references/style-3-blueprint.md +113 -0
- package/src/claude/skills/generate-graph/references/style-4-notion-clean.md +94 -0
- package/src/claude/skills/generate-graph/references/style-5-glassmorphism.md +125 -0
- package/src/claude/skills/generate-graph/references/style-6-claude-official.md +209 -0
- package/src/claude/skills/generate-graph/references/style-7-openai.md +215 -0
- package/src/claude/skills/generate-graph/references/style-diagram-matrix.md +135 -0
- package/src/claude/skills/generate-graph/references/svg-layout-best-practices.md +100 -0
- package/src/claude/skills/generate-graph/scripts/generate-diagram.sh +157 -0
- package/src/claude/skills/generate-graph/scripts/generate-from-template.py +1556 -0
- package/src/claude/skills/generate-graph/scripts/test-all-styles.sh +135 -0
- package/src/claude/skills/generate-graph/scripts/validate-svg.sh +292 -0
- package/src/claude/skills/generate-graph/templates/agent-architecture.svg +28 -0
- package/src/claude/skills/generate-graph/templates/architecture.svg +23 -0
- package/src/claude/skills/generate-graph/templates/comparison-matrix.svg +14 -0
- package/src/claude/skills/generate-graph/templates/data-flow.svg +28 -0
- package/src/claude/skills/generate-graph/templates/er-diagram.svg +21 -0
- package/src/claude/skills/generate-graph/templates/flowchart.svg +21 -0
- package/src/claude/skills/generate-graph/templates/sequence.svg +20 -0
- package/src/claude/skills/generate-graph/templates/state-machine.svg +20 -0
- package/src/claude/skills/generate-graph/templates/timeline.svg +19 -0
- package/src/claude/skills/generate-graph/templates/use-case.svg +21 -0
- package/src/claude/skills/specs/SKILL.md +35 -5
- package/src/claude/skills/specs/references/review.md +1 -1
- package/src/claude/skills/specs/rules/tasks-generation.md +17 -0
- package/src/claude/skills/specs/templates/design.md +13 -0
- package/src/claude/skills/specs/templates/init.json +4 -1
- package/src/claude/skills/specs/templates/requirements.md +21 -8
- 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}"
|