fastdraw 0.0.0-stage → 0.1.1
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/LICENSE +21 -0
- package/README.md +193 -2
- package/agents/AGENTS-snippet.md +10 -0
- package/agents/README.md +11 -0
- package/agents/claude-skill/fastdraw/SKILL.md +14 -0
- package/dist/cli.js +3694 -0
- package/fonts/Geist-Medium.ttf +0 -0
- package/fonts/Geist-Regular.ttf +0 -0
- package/fonts/Geist-SemiBold.ttf +0 -0
- package/fonts/GeistMono-Medium.ttf +0 -0
- package/fonts/GeistMono-Regular.ttf +0 -0
- package/fonts/InstrumentSerif-Italic.ttf +0 -0
- package/fonts/InstrumentSerif-Regular.ttf +0 -0
- package/fonts/LibreFranklin-Bold.ttf +0 -0
- package/fonts/LibreFranklin-Medium.ttf +0 -0
- package/fonts/LibreFranklin-Regular.ttf +0 -0
- package/fonts/LibreFranklin-SemiBold.ttf +0 -0
- package/fonts/Newsreader-Italic.ttf +0 -0
- package/fonts/Newsreader-Medium.ttf +0 -0
- package/fonts/Newsreader-Regular.ttf +0 -0
- package/fonts/Newsreader-SemiBold.ttf +0 -0
- package/fonts/OFL-Geist.txt +93 -0
- package/fonts/OFL-InstrumentSerif.txt +93 -0
- package/fonts/OFL-LibreFranklin.txt +93 -0
- package/fonts/OFL-Newsreader.txt +93 -0
- package/fonts/OFL-SketchHand.txt +49 -0
- package/fonts/SketchHand-Regular.ttf +0 -0
- package/guide/architecture-delta.md +52 -0
- package/guide/architecture.md +28 -0
- package/guide/axonometric-plan.md +54 -0
- package/guide/bar.md +61 -0
- package/guide/data-flow.md +42 -0
- package/guide/db-schema.md +46 -0
- package/guide/dependency.md +38 -0
- package/guide/deployment.md +46 -0
- package/guide/er.md +49 -0
- package/guide/exploded.md +53 -0
- package/guide/fishbone.md +44 -0
- package/guide/flowchart.md +22 -0
- package/guide/gantt.md +48 -0
- package/guide/guide.md +278 -0
- package/guide/heatmap.md +59 -0
- package/guide/high-level.md +38 -0
- package/guide/integration.md +33 -0
- package/guide/it-state.md +33 -0
- package/guide/journey.md +35 -0
- package/guide/kanban.md +53 -0
- package/guide/layers.md +49 -0
- package/guide/line.md +112 -0
- package/guide/look.md +174 -0
- package/guide/loop.md +45 -0
- package/guide/medallion.md +37 -0
- package/guide/nested.md +36 -0
- package/guide/org-chart.md +48 -0
- package/guide/polar.md +57 -0
- package/guide/process.md +41 -0
- package/guide/pyramid.md +46 -0
- package/guide/quadrant.md +44 -0
- package/guide/radar.md +60 -0
- package/guide/sankey.md +53 -0
- package/guide/scatter.md +73 -0
- package/guide/security-matrix.md +47 -0
- package/guide/sequence.md +39 -0
- package/guide/state.md +38 -0
- package/guide/story-map.md +29 -0
- package/guide/swimlane.md +40 -0
- package/guide/timeline.md +49 -0
- package/guide/tree.md +33 -0
- package/guide/treemap.md +67 -0
- package/guide/uml-class.md +59 -0
- package/guide/venn.md +48 -0
- package/guide/wardley.md +35 -0
- package/guide/waterfall.md +47 -0
- package/package.json +59 -4
package/guide/guide.md
ADDED
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
# FastDraw guide
|
|
2
|
+
|
|
3
|
+
FastDraw draws diagrams from a small text file (`.fdraw`). You place every element yourself, at exact coordinates. A separate look file (`.look`) decides how each named style is drawn. A person may later edit the same file in a visual editor, so keep it tidy.
|
|
4
|
+
|
|
5
|
+
## How to work
|
|
6
|
+
|
|
7
|
+
1. Run `fastdraw sizes <look file>` to see the styles you can use, their default sizes, and the look's own guidance. Follow that guidance. A diagram with no `look` line uses the built-in look: run `fastdraw sizes` with no file to see it.
|
|
8
|
+
2. To create or change a look (how styles are drawn), run `fastdraw guide look` instead of the steps below.
|
|
9
|
+
3. Run `fastdraw guide list` to see which kinds of diagram have their own guide. If yours is there, run `fastdraw guide <kind>` and follow it.
|
|
10
|
+
4. Plan the composition on paper first: rows and columns, where the main thing sits.
|
|
11
|
+
5. Write the file.
|
|
12
|
+
6. Run `fastdraw check <file>`. Fix every error and warning. Read the hints and fix the ones that are real.
|
|
13
|
+
7. Run `fastdraw render <file>` and **look at the PNG**. Fix what looks wrong: cramped labels, uneven gaps, lopsided composition, a label sitting on a border. Repeat from 6 until it is clean and looks good.
|
|
14
|
+
8. To hand the diagram to a person for changes, run `fastdraw open <file>` in the background. It opens the web editor at the diagram, with its look, and saves their edits into the same file. Read the file again before you change it after that.
|
|
15
|
+
|
|
16
|
+
When you change an existing diagram: do not move, resize or restyle anything that is already there unless asked. Place only what you add, in free space.
|
|
17
|
+
|
|
18
|
+
## The file
|
|
19
|
+
|
|
20
|
+
One statement per line. An indented line continues the statement above it. `//` starts a comment; so does a line starting with `# `.
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
look "./team.look" // path relative to this file; leave the line out to use the built-in look
|
|
24
|
+
// or a look that ships with FastDraw: look headline | night | reference | sketch | whiteboard
|
|
25
|
+
canvas paper=#ffffff dots=none dotgap=24 // optional: changes the look's background for this diagram only
|
|
26
|
+
|
|
27
|
+
// shape: id: style "text" at x,y WxH key=value ...
|
|
28
|
+
api: node "Orders API" sub="REST · :8080" tag="API" at 200,120
|
|
29
|
+
db: store "Orders DB" at 440,120 160x64
|
|
30
|
+
|
|
31
|
+
// connector: [id:] from -> to "label" key=value ...
|
|
32
|
+
api -> db "writes"
|
|
33
|
+
|
|
34
|
+
// free text: [id:] text "words" at x,y style=name key=value ...
|
|
35
|
+
text "Legend" at 40,420 style=eyebrow
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Shapes
|
|
39
|
+
|
|
40
|
+
`id: style "text" at x,y WxH props`
|
|
41
|
+
|
|
42
|
+
- `id` is a short unique name followed by a colon. Give every box an id. Small decorative things (legend swatches) may omit it.
|
|
43
|
+
- `style` is a shape style from the look, or one of the plain built-ins `rect`, `ellipse`, `diamond`.
|
|
44
|
+
- `at x,y` is the **top-left corner**. No space after the comma.
|
|
45
|
+
- `WxH` is the size. Leave it out to get the style's default size.
|
|
46
|
+
- `"text"` is the main label and may be left out. Use `\n` for a line break. On a zone it is drawn as a small caption at the top.
|
|
47
|
+
- Use multiples of 4 for positions and sizes.
|
|
48
|
+
|
|
49
|
+
Text properties a shape understands (if the look's style supports them):
|
|
50
|
+
|
|
51
|
+
| Property | Meaning |
|
|
52
|
+
|---|---|
|
|
53
|
+
| `sub="..."` | a second, smaller line under the main text (`\n` for more lines) |
|
|
54
|
+
| `tag="API"` | a 3–4 letter marker in the top-left corner |
|
|
55
|
+
| `ghost="01"` | a large faint number in the bottom-right corner |
|
|
56
|
+
| `title.align=left` | text against the left edge instead of centred (`right` too). On a zone, the caption moves to that corner |
|
|
57
|
+
|
|
58
|
+
### Polygons and arcs
|
|
59
|
+
|
|
60
|
+
Two built-in shapes draw anything a box, ellipse or diamond cannot.
|
|
61
|
+
|
|
62
|
+
`polygon` takes exact corners, measured from its `at` position (so the top-left of the outline is `0,0`):
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
top: polygon "Vision" at 140,40 points=60,0;120,80;0,80 // a triangle
|
|
66
|
+
mid: polygon "Strategy" at 100,128 points=40,0;160,0;200,80;0,80 // a trapezoid
|
|
67
|
+
trend: polygon at 60,330 points=0,40;80,10;160,30;240,0 open=1 stroke=accent sw=2
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
- `open=1` leaves the outline unclosed and unfilled: a line through the points, for a trend or a series.
|
|
71
|
+
- `smooth=1` rounds the outline into a curve that passes through every point.
|
|
72
|
+
- Give `WxH` only to stretch the outline to another size.
|
|
73
|
+
- `freehand` is what the editor's Draw tool writes when a person sketches with the pointer: `freehand at x,y points=...`, a smooth open line with round ends, 2px wide, that lines and labels may cross. Leave such lines as they are when editing a file; do not write them yourself, a diagram written as text is made of boxes, lines and polygons.
|
|
74
|
+
|
|
75
|
+
`arc` is a slice of the circle (or ellipse) that fills its box. Angles are degrees, clockwise from the top:
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
won: arc "42%" at 400,40 200x200 from=0 to=151 fill=accent
|
|
79
|
+
lost: arc "58%" at 400,40 200x200 from=151 to=360 fill=ink/0.1
|
|
80
|
+
ring: arc at 660,40 200x200 from=0 to=250 inner=0.7 fill=link stroke=none
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
- Slices of one circle all use the same `at` and `WxH`.
|
|
84
|
+
- `inner=0.7` cuts out the middle, leaving a ring segment (0.7 = the hole is 70% of the radius).
|
|
85
|
+
- `open=1` draws only the curved edge.
|
|
86
|
+
- Text sits in the middle of the slice.
|
|
87
|
+
|
|
88
|
+
Shapes that are meant to overlap (circles of a Venn diagram, faces of a 3D box) need `overlap=ok`, or `check` reports them. `overlap=ok` also works on text (a faint watermark behind labels).
|
|
89
|
+
|
|
90
|
+
A filled shape first paints a patch of paper colour under itself, so that lines behind it do not show through a tint. For see-through shapes that should blend where they overlap, add `mask=0`.
|
|
91
|
+
|
|
92
|
+
Text in a polygon is centred on the outline's area, so it sits in the wide part of a triangle.
|
|
93
|
+
|
|
94
|
+
### Charts
|
|
95
|
+
|
|
96
|
+
`chart` draws axes, tick labels and grid lines, and plots your numbers, so you never work out bar heights by hand. Its box (`at x,y WxH`) is the plot area. Tick labels are drawn outside it: leave about 56px free on the left, 28px below (44px with `xtitle=`) and 40px above.
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
rev: chart "Revenue by quarter" at 80,80 360x200 x="Q1,Q2,Q3,Q4" prefix="$" unit="k" labels=1
|
|
100
|
+
| bars "2025" 42 61 75 93
|
|
101
|
+
| line "Plan" 50 60 70 80 stroke=link dots=1
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Each row is one series: `| kind "name" numbers... props`.
|
|
105
|
+
|
|
106
|
+
| Kind | Draws |
|
|
107
|
+
|---|---|
|
|
108
|
+
| `bars` | one bar per category. Several `bars` series stand side by side; `stack=1` on the chart stacks them. A pair `lo,hi` is a floating bar (a bridge step, a range) |
|
|
109
|
+
| `line` | a line through the values; `dots=1` marks each point, `dash=4,4` dashes it |
|
|
110
|
+
| `area` | a line with the space under it tinted |
|
|
111
|
+
| `dots` | points only. With a numeric x axis each point is `x,y` or `x,y,radius`; with categories a pair is `value,radius` (a bubble). `r=5` sets one radius for all, `opacity=0.6` thins them |
|
|
112
|
+
|
|
113
|
+
- `_` in place of a number leaves a gap.
|
|
114
|
+
- One bar or dot can take its own colour by its position from 1: `| bars "Sales" 72 88 110 fill=soft fill.3=accent`. `fill=` together with `stroke=` gives bars and dots an outline.
|
|
115
|
+
- A floating bar that does not start at zero is labelled as a change, with a plus sign on a rise.
|
|
116
|
+
- Colour a series with `fill=` or `stroke=` on its row. Without it the series take the accent first, then the link colour, then greys. Keep the accent for the series the chart is about.
|
|
117
|
+
|
|
118
|
+
Chart properties:
|
|
119
|
+
|
|
120
|
+
| Property | Meaning |
|
|
121
|
+
|---|---|
|
|
122
|
+
| `x="Q1,Q2,Q3"` | category names along the bottom |
|
|
123
|
+
| `x=0..100` | a numeric x axis instead (`xstep=20`, `xunit="s"`); series then give `x,y` points |
|
|
124
|
+
| `y=0..100` | the y range; left out, it runs from 0 to a round number above the largest value |
|
|
125
|
+
| `step=25` | distance between y ticks (worked out when left out) |
|
|
126
|
+
| `prefix="$"`, `unit="k"` | written around every y value |
|
|
127
|
+
| `labels=1` | write each value above its bar or point |
|
|
128
|
+
| `xtitle=`, `ytitle=` | axis titles |
|
|
129
|
+
| `grid=0`, `grid=both`, `grid=x` | no grid lines; vertical ones too; vertical ones only |
|
|
130
|
+
| `stroke=none` | no axis lines |
|
|
131
|
+
| `zero=0` | no line at zero when the y range runs from negative to positive |
|
|
132
|
+
| `key=0` | hide the series key (drawn top-right when there are two or more named series) |
|
|
133
|
+
| `yaxis=0` | hide the y tick labels (when `labels=1` already says it) |
|
|
134
|
+
| `bar.width=0.64` | share of each category's width that bars fill |
|
|
135
|
+
|
|
136
|
+
Anything the chart does not draw (a note, a threshold label, an arrow to one bar) you add as ordinary text and connectors at exact coordinates. The plot maps values linearly: value `v` is at `y + H - (v - ymin) / (ymax - ymin) * H`, and category `i` (from 0) is centred at `x + W * (i + 0.5) / n`.
|
|
137
|
+
|
|
138
|
+
### Tables
|
|
139
|
+
|
|
140
|
+
A table is a box with a header and rows, for entities, classes, database tables and grids of values. Write the box as usual, then one indented line per row, each starting with `|`:
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
users: table "users" at 40,100
|
|
144
|
+
| id "id" "uuid" "PK"
|
|
145
|
+
| email "email" "text" "UK"
|
|
146
|
+
| "created_at" "timestamptz"
|
|
147
|
+
| ---
|
|
148
|
+
| "note" "soft-deleted rows stay"
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
- A row is `| id "cell" "cell" ...`: one quoted text per column. The row id is optional; give one to every row an arrow ends on. It cannot be `top`, `bottom`, `left` or `right`.
|
|
152
|
+
- `| ---` draws a full dividing line (between the attributes and the operations of a class, say).
|
|
153
|
+
- `|= "Role" "Read" "Write"` is a heading row, drawn bold on a tint. Use it for the column headings of a grid.
|
|
154
|
+
- The size works itself out: columns are as wide as their longest cell and the height follows the rows (32px header, 24px per row with the built-in look). To make a table wider, give a width: `at 40,100 240x0`. Spare width goes to the first column.
|
|
155
|
+
- A row can have its own tint: `| late "Shipping" "3 days" fill=accent/0.1`. One cell can too, by column number from 1: `| "Analyst" "read" "none" fill.2=accent/0.15 color.3=muted`. That is how a matrix or heatmap shows levels.
|
|
156
|
+
- A row with a single cell, in a table with more columns, runs across the full width (an index name, a note).
|
|
157
|
+
- The header text may have two lines (`"«interface»\nPaymentMethod"`); `title.align=left` puts it at the left.
|
|
158
|
+
- `align=center grid=1` on the table centres every column after the first and draws column lines, for a matrix.
|
|
159
|
+
- Rows come last in the statement. Properties of the table itself go on the first line.
|
|
160
|
+
|
|
161
|
+
An arrow can end on a row: `orders.user_id -- users.id`. It attaches to the left or right edge of the table, level with that row, on the side facing the other end; `users.id.left` forces a side.
|
|
162
|
+
|
|
163
|
+
### Icons
|
|
164
|
+
|
|
165
|
+
`icon=name` puts a small outline icon in any box: `db: store "Orders DB" icon=database at 440,120`. `fastdraw sizes` lists the icons the look has (server, database, user, cloud, queue, lock, mail, function, ai and about 120 more). `fastdraw icons email` searches them by name or meaning: it finds `mail`, and `k8s` finds `pod`.
|
|
166
|
+
|
|
167
|
+
- The icon sits just left of the text and the pair is centred. `icon.pos=top` puts it above the text instead; the box then needs about 28px more height.
|
|
168
|
+
- With no text, the icon fills the box.
|
|
169
|
+
- An icon on its own, with no box, is the `icon` style: `api: icon "Orders API" at 60,220 40x40 icon=server` (24x24 unless you give `WxH`). The icon is the shape, so `fill=`, `stroke=` and `sw=` style the icon itself (`fill=accent/0.2 stroke=accent sw=2`), and its text is a caption centred underneath. Lines attach to the icon and go around other icons' captions.
|
|
170
|
+
- `icon.size=20` and `icon.color=link` change it; by default it takes the colour of the box's text.
|
|
171
|
+
- `icon.fill=accent/0.2` fills the icon's closed parts for a two-tone look (none by default), and `icon.width=2` sets its stroke width in pixels. Both take look colours, tints or hex (`icon.fill=#ffd400`), and both work in a look's `style` lines so every box of a style gets the same icon treatment. Icons from a look's folder keep their own colours.
|
|
172
|
+
- A look can bring its own colour icons (a cloud vendor's set, product logos). `fastdraw sizes <look>` lists them first; use them the same way: `icon=virtual-machine`. They keep their own colours. Run `fastdraw icons <look> word` to search a large set.
|
|
173
|
+
- Use icons where they say something the name does not (what kind of thing a box is), on every box of a row or on none. Two or three kinds of icon in one diagram is plenty.
|
|
174
|
+
|
|
175
|
+
A shape's text is styled with `title.size=`, `title.color=`, `title.weight=`, `title.font=` (and `sub.` the same for the second line).
|
|
176
|
+
|
|
177
|
+
Any appearance property can be overridden on one element: `fill=`, `stroke=`, `sw=` (stroke width), `dash=4,3`, `radius=`. Colours are `#hex`, a colour name from the look, or either followed by `/opacity` (`ink/0.3`). Prefer the look's styles; override only with a reason.
|
|
178
|
+
|
|
179
|
+
### Connectors
|
|
180
|
+
|
|
181
|
+
`from -> to "label" props`
|
|
182
|
+
|
|
183
|
+
| Operator | Draws |
|
|
184
|
+
|---|---|
|
|
185
|
+
| `->` | arrow with a head at `to` |
|
|
186
|
+
| `<->` | heads at both ends |
|
|
187
|
+
| `--` | plain line, no head |
|
|
188
|
+
|
|
189
|
+
`style=name` picks a line style from the look. Without it, `->` uses `arrow` and `--` uses `line`.
|
|
190
|
+
|
|
191
|
+
`head=` and `tail=` put a marker of your choice on the `to` end and the `from` end. They work with any operator; with `--` they are the only markers drawn.
|
|
192
|
+
|
|
193
|
+
| Marker | Looks like | Usual meaning |
|
|
194
|
+
|---|---|---|
|
|
195
|
+
| `arrow` | filled arrowhead | the default head |
|
|
196
|
+
| `open` | two strokes, not filled | a dependency, an asynchronous message |
|
|
197
|
+
| `triangle` | hollow triangle | inherits from / implements (points at the parent) |
|
|
198
|
+
| `diamond`, `diamond-solid` | hollow or filled diamond | aggregation, composition (sits on the owner) |
|
|
199
|
+
| `dot`, `circle` | filled or hollow circle | a start point, a provided interface |
|
|
200
|
+
| `one`, `only-one` | one bar, two bars | exactly one |
|
|
201
|
+
| `many`, `one-many` | crow's foot, crow's foot and bar | many, one or more |
|
|
202
|
+
| `zero-one`, `zero-many` | circle and bar, circle and crow's foot | optional one, optional many |
|
|
203
|
+
| `none` | nothing | removes a head the operator would draw |
|
|
204
|
+
|
|
205
|
+
Example: `orders.user_id -- users.id tail=many head=only-one` reads "many orders, exactly one user". A `--` that ends on a table row uses the built-in `relation` style (right-angled, no head) rather than a slanted line.
|
|
206
|
+
|
|
207
|
+
An end can be:
|
|
208
|
+
|
|
209
|
+
| Form | Meaning |
|
|
210
|
+
|---|---|
|
|
211
|
+
| `api` | the shape; FastDraw picks the side that faces the other end |
|
|
212
|
+
| `api.right` | a side: `top`, `bottom`, `left`, `right` |
|
|
213
|
+
| `api.right@0.25` | a point along that side, as a fraction (0 = top or left end) |
|
|
214
|
+
| `api.right@172` | a point along that side at absolute coordinate 172 (y for left/right, x for top/bottom) |
|
|
215
|
+
| `400,300` | a free point; either number may be negative (`-40,-20`) |
|
|
216
|
+
| `+0,260` | a point relative to the other end: one of the numbers carries a `+` (`+40,-20`, `-40,+0`); only one end may be relative |
|
|
217
|
+
| `users.email` | a row of a table: the edge of the table level with that row. `users.email.left` picks the side |
|
|
218
|
+
| `life1@176` | a point on another line: where line `life1` has coordinate 176 (y on a vertical line, x on a horizontal one); a value ≤ 1 is a fraction along it |
|
|
219
|
+
|
|
220
|
+
Routing: arrows turn at right angles with rounded corners, and go around a box that is in the way without being told. Two ends that line up give a straight line. Otherwise the arrow leaves the first shape sideways and enters the second from above or below, or uses a mid-way step. When several arrows share a side, they are spread along it automatically. Lay boxes out so the important arrows are straight; a detour is a fallback, not a design. To steer a route yourself:
|
|
221
|
+
|
|
222
|
+
- name the sides: `a.bottom -> b.left`
|
|
223
|
+
- add waypoints: `via=300,200` or `via=300,200;300,360`
|
|
224
|
+
- draw it as a smooth curve: `route=curve`. It leaves and arrives square to the sides it is attached to. `bend=40` instead bows it 40px to the left of its direction of travel (negative: to the right), which is how to draw the arcs of a cycle. `via=x,y;x,y` makes the curve pass through those points. Curves do not avoid boxes; you place them. `route=straight` gives one straight line
|
|
225
|
+
- a line that is meant to run behind boxes (a grid line, a guide) takes `layer=back`, and `check` stops reporting the boxes it crosses. `layer=front` draws a line on top of the shapes instead (an edge on a face)
|
|
226
|
+
- several lines may share one trunk, as in a tree: give them the same start point (`root.bottom@0.5 -> a.top`, `root.bottom@0.5 -> b.top`) or the same end point. Lines that overlap anywhere else are reported
|
|
227
|
+
- for a loop back to the same side (`x.right@190 -> x.right@220`), `loop=36` sets how far it sticks out
|
|
228
|
+
|
|
229
|
+
Labels are drawn in small caps on a paper-coloured patch, above a horizontal line or to the right of a vertical one, at the middle of the longest segment. Keep them to about 14 characters. To move one: `lside=below` (or `left` for vertical lines), or `lpos=x,y` (centre x, text baseline y; the default baseline is 10px above a horizontal line, or 18px below it with `lside=below`). `label.caps=0` keeps the label's own letter case, for paths and header names.
|
|
230
|
+
|
|
231
|
+
### Text
|
|
232
|
+
|
|
233
|
+
`text "words" at x,y style=name` — `at` is the left end of the text baseline. `anchor=middle` or `anchor=end` changes that. `rotate=-90` turns the text to read upwards about its `at` point (`rotate=90`: downwards), for a label along a vertical axis. Overrides: `size=`, `color=`, `weight=`, `font=sans|mono|serif`, `italic=1` (only where the font has an italic face; the bundled sans and mono do not, the serif does).
|
|
234
|
+
|
|
235
|
+
### Legend
|
|
236
|
+
|
|
237
|
+
One statement draws a whole legend: a rule line, a heading, and one entry per style, spaced and wrapped for you.
|
|
238
|
+
|
|
239
|
+
```
|
|
240
|
+
legend at 40,404 focal="The service this is about" store="Holds data" primary="Main path" return="Response"
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
- Each `style="what it means"` pair is an entry, in the order written. Use only the styles the diagram uses.
|
|
244
|
+
- It is as wide as the rest of the drawing: from its x to the right edge of everything else. Give `WxH` to set another width (the height is always worked out).
|
|
245
|
+
- `title="Key"` changes the heading; `title=none` removes it.
|
|
246
|
+
- For a mark that is not a style of the look, write `swatch.COLOUR="meaning"` (a small filled square), `dot.COLOUR="meaning"` or `line.COLOUR="meaning"`, where COLOUR is a colour name from the look or a hex colour, optionally with a tint (`swatch.muted/0.2="Flow"`, `swatch.#4a7c59="Stream"`): `legend at 40,400 dot.accent="Shipped" swatch.muted="Planned" line.link="Depends on"`.
|
|
247
|
+
- Put it 24px under the lowest element.
|
|
248
|
+
|
|
249
|
+
### Groups
|
|
250
|
+
|
|
251
|
+
`group=name` on several elements makes the editor select and move them together. It does not change how they are drawn.
|
|
252
|
+
|
|
253
|
+
### Drawing order
|
|
254
|
+
|
|
255
|
+
Shapes whose style is marked "drawn behind everything" (zones) come first, then all connectors, then connector labels, then shapes, then free text. Within each group, file order.
|
|
256
|
+
|
|
257
|
+
### Title
|
|
258
|
+
|
|
259
|
+
A diagram that has a title puts it first: `title: text "What this shows" at 40,52 style=h1`, with an optional one-line dek under it: `text "One plain sentence saying what the diagram shows" at 40,80 style=dek` (`caption` if your look has no `dek`). A title with a dek reads like a magazine graphic. Everything else then starts at y=96 or lower. When a kind's guide gives positions that start nearer the top, they are for a diagram with no title: add 56 to every y to make room for one.
|
|
260
|
+
|
|
261
|
+
### Plain lines
|
|
262
|
+
|
|
263
|
+
A separator, an axis without a head, a grid line: write these with `--` between two points (`40,380 -- 960,380 style=rule`). `->` is for arrows.
|
|
264
|
+
|
|
265
|
+
## Composition rules
|
|
266
|
+
|
|
267
|
+
These are what make a diagram look designed. `check` enforces the mechanical ones; the rest are yours.
|
|
268
|
+
|
|
269
|
+
- **Fewer elements.** Aim for nine boxes or fewer and twelve arrows or fewer. If two boxes always go together, make them one. If an arrow says nothing the layout doesn't already say, remove it.
|
|
270
|
+
- **One focus.** Use the look's accent style on one or two things only.
|
|
271
|
+
- **A grid you can name.** Pick column x-positions and row y-positions and reuse them. Boxes in a row share a top edge and height; boxes in a column share a left edge or centre.
|
|
272
|
+
- **Even gaps.** Use the same gap between neighbours along a row (48–56px between boxes that an arrow with a label connects; at least 40px otherwise).
|
|
273
|
+
- **Margins.** There is no page: the picture is everything drawn plus a 40px margin on every side, added for you. By convention start the drawing at 40,40 (the title's baseline at 40,52).
|
|
274
|
+
- **Straight arrows where possible.** Line things up so the main path is straight lines. Use elbows for branches.
|
|
275
|
+
- **No arrow through a box, no arrow on top of another, no label touching a box or another line.** `check` reports these.
|
|
276
|
+
- **Labels fit their line.** A horizontal arrow needs to be longer than its label. Make the gap wider or the label shorter.
|
|
277
|
+
- **Centre the composition.** The drawing should sit balanced, not lean to one side: centre rows, titles and branches over the width of the drawing (left edge of the leftmost element to right edge of the rightmost).
|
|
278
|
+
- **Legend.** End with a `legend` statement listing only the styles you used.
|
package/guide/heatmap.md
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Heatmaps
|
|
2
|
+
|
|
3
|
+
Shows a number for every combination of two lists (service by sprint, team by week) as a grid of cells, darker for larger. The reader scans the whole grid and one cell or cluster stands out.
|
|
4
|
+
|
|
5
|
+
FastDraw has no heatmap element. Each cell is a plain `rect` with its value as text.
|
|
6
|
+
|
|
7
|
+
## Building blocks
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
// 5 rows. Title y=52. Grid: 6 columns from x=184, 120px apart; rows from y=136, 60px apart; cells 116x56 with a 4px gap
|
|
11
|
+
// fill = ink at (value / 9 * 0.65), at least 0.07: 9 is the largest value outside the focal cell
|
|
12
|
+
title: text "CI failures peaked on payments in sprint 4" at 40,52 style=h1
|
|
13
|
+
text "SPRINT" at 542,100 style=eyebrow anchor=middle // list name, centred over the grid
|
|
14
|
+
text "SERVICE" at 74,284 style=eyebrow anchor=middle rotate=-90 // x0 - 110, level with the middle of the grid
|
|
15
|
+
text "S1" at 242,124 style=small size=10 color=muted anchor=middle // column name: cell x + 58, baseline 12px above the grid
|
|
16
|
+
text "auth" at 172,168 style=small size=10 color=ink anchor=end // row name: x0 - 12, baseline cell y + 32
|
|
17
|
+
a1: rect "4%" at 184,136 116x56 fill=ink/0.29 stroke=none radius=0 title.size=9 title.font=mono title.weight=400
|
|
18
|
+
a3: rect "6%" at 424,136 116x56 fill=ink/0.43 stroke=none radius=0 title.size=9 title.font=mono title.weight=400 title.color=#ffffff
|
|
19
|
+
p4: rect "47%" sub="REGRESSION" at 544,196 116x56 fill=accent/0.85 stroke=accent sw=1.2 radius=0 title.size=12 title.weight=700 title.font=mono title.color=#ffffff sub.color=#ffffff sub.size=8
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Composition
|
|
23
|
+
|
|
24
|
+
- Three to seven rows and three to eight columns. Fewer is a table; more makes the cells too small to read.
|
|
25
|
+
- Cells are 116x56 with a 4px gap (pitch 120 across, 60 down) for up to six columns. For seven or eight columns narrow them to 88px (pitch 92); never below 80px.
|
|
26
|
+
- Centre the grid: `x0 = 40 + (1000 - grid width) / 2`, rounded to 4 (six columns: grid width 716, x0 = 184). The 40 makes room for the row names. Column `c` is at `x0 + pitch * c`, row `r` at `136 + 60 * r`.
|
|
27
|
+
- Row names are right-aligned at `x0 - 12`, baseline 32px below the cell top. Column names are centred over each column, baseline at 124 (12px above the grid).
|
|
28
|
+
- Name both lists with `eyebrow` text, **typed in capitals** (`eyebrow` does not change case): one centred over the grid at y=100, one turned with `rotate=-90` at `x0 - 110` (clear of the longest row name), level with the middle of the grid.
|
|
29
|
+
- Grid bottom = `136 + 60 * rows - 4`. Legend rule at grid bottom + 24.
|
|
30
|
+
- Keep the order the reader expects (time left to right; rows alphabetical or by size) and show every row and column. If you leave any out, say so under the legend.
|
|
31
|
+
|
|
32
|
+
## Colour
|
|
33
|
+
|
|
34
|
+
- One scale of one colour: `fill=ink/OPACITY`, with opacity rising with the value from 0.07 (smallest; lower cannot be told from the paper) to 0.65 (largest). Work out `value / largest * 0.65` to two decimals and write the rule in a comment.
|
|
35
|
+
- No second hue and no colour per row or column. A two-colour scale is right only for values that run both sides of a meaningful zero.
|
|
36
|
+
- One cell, the one the diagram is about, is `fill=accent/0.85 stroke=accent` with white text (`title.color=#ffffff sub.color=#ffffff`: ink on that fill is hard to read). If its value is far above the rest, leave it out of the scale (take "largest" from the other cells), or every other cell turns equally pale. Then state its value in the legend.
|
|
37
|
+
|
|
38
|
+
## Text
|
|
39
|
+
|
|
40
|
+
- Every cell shows its value, in mono size 9. From opacity 0.40 up, the text is white (`title.color=#ffffff`); below, it keeps the default ink.
|
|
41
|
+
- The focal cell has a larger bold value (size 12) and may carry one word under it in `sub=`.
|
|
42
|
+
- Put the unit in the cells (`4%`) or in the note under the legend, not in both.
|
|
43
|
+
|
|
44
|
+
## Legend
|
|
45
|
+
|
|
46
|
+
By hand, because the cells are not styles of the look. With `G` the grid bottom (432 for five rows), `n` the number of ramp steps (six to eight):
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
40,456 -- 960,456 style=rule // G + 24
|
|
50
|
+
text "Legend" at 40,476 style=eyebrow // G + 44
|
|
51
|
+
text "Low" at 132,476 style=eyebrow color=soft anchor=end
|
|
52
|
+
rect at 140,466 20x12 fill=ink/0.07 stroke=none radius=0 // step k at x = 140 + 22 * k, y = G + 34
|
|
53
|
+
text "High" at 324,476 style=eyebrow color=soft // 140 + 22 * n + 4 (n = 8)
|
|
54
|
+
rect at 400,466 20x12 fill=accent/0.85 stroke=accent radius=0 // the focal swatch, 76px after High
|
|
55
|
+
text "payments · S4 · 47%: a deploy regression, since fixed" at 428,476 style=caption
|
|
56
|
+
text "CI failure rate per service and sprint. The grey scale covers 1% to 9%; the accent cell is outside it." at 40,504 style=caption // G + 72
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Step the ramp swatches through the opacities used, 0.07 up to 0.65.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# High-level diagrams
|
|
2
|
+
|
|
3
|
+
Shows a whole data stack on one page: phases across the top (sources, ingestion, storage, analysis, visualization), the components under the phase they belong to, the boundary of the cluster they run in, and the services that span all of it. It is an overview: one box per product, no internals.
|
|
4
|
+
|
|
5
|
+
## Composition
|
|
6
|
+
|
|
7
|
+
- Title at 40,52 (`style=h1`); the banner below it. Columns: four to six phases, each 224 wide, from x=40. Column n (from 0) has its centre at `152 + 224*n`. The columns end at `x = 40 + 224*phases`: 1160 for five.
|
|
8
|
+
- Phase banner at y=88: one chevron per column, drawn as a polygon 232 wide and 32 high so that each tip reaches into the notch of the next.
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
p1: polygon "DATA SOURCES" at 40,88 points=0,0;216,0;232,16;216,32;0,32 fill=accent/0.14 stroke=none title.color=accent title.font=mono title.size=8 overlap=ok
|
|
12
|
+
p2: polygon "INGESTION" at 264,88 points=0,0;216,0;232,16;216,32;0,32;16,16 fill=ink/0.06 stroke=none title.color=muted title.font=mono title.size=8 overlap=ok
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The first has a flat left end, the last a flat right end (`points=0,0;224,0;224,32;0,32;16,16`). Alternate a tint of the accent (`fill=accent/0.14 title.color=accent`) and a light grey (`fill=ink/0.06 title.color=muted`); never a solid dark fill. Never leave the banner out: it is what tells the reader what a column means.
|
|
16
|
+
- Every component is a 144x64 `node` (write the size when it differs) centred under its phase: `x = 80 + 224*n`. Boxes in one phase stack with 48px between them (pitch 112): rows at y=240 and 352 under an orchestrator, 176 and 288 without one.
|
|
17
|
+
- Sources are outside the cluster: a dashed zone under the first chevron, `zone "Sources" at 48,136 208xH dash=4,3`, holding a column of `external` boxes 160x56 at x=72 (zone x + 24), 16 apart, the first 36px below the zone's top: `y = 172 + 72*i`. Size the zone to the last box plus 36.
|
|
18
|
+
- The cluster is a zone over the other columns, `dash=none` to make it solid: `zone "Kubernetes cluster" at 272,136 888xH dash=none`, `W = 224*(phases-1) - 8`, the same height as the sources zone (the taller of the two sets).
|
|
19
|
+
- An orchestrator or scheduler is a wide `cloud` box across the top of the cluster, 24px below its top edge and 16px in from its sides, 48 high. Components start 32px below it. With no orchestrator they start 40px below the zone's top (y=176).
|
|
20
|
+
- A service that applies to everything (identity, monitoring) is a `cloud` box as wide as all the columns (`WxH` 1120x48 for five), 24px under the zones. It is outside the cluster and has no arrows. One row per service, 24px apart.
|
|
21
|
+
- Place the main row so that the busiest arrows are straight: the ingestion box level with the box it feeds, and a box fed by two others half-way between them.
|
|
22
|
+
|
|
23
|
+
## Arrows
|
|
24
|
+
|
|
25
|
+
- Data moves left to right: out of the right side, into the left side. No labels: the banner and the box names carry the meaning.
|
|
26
|
+
- One box, usually the storage hub, is `focal`. The arrows into and out of it use `style=primary` (two at most). Other data arrows are plain.
|
|
27
|
+
- From the orchestrator: a straight dashed drop onto the top of each box it triggers, `air.bottom@824 -> model.top@824 style=return`, where 824 is the centre x of the target. Give the x on both ends so the drop cannot bend.
|
|
28
|
+
- A read-back between two stacked boxes is one dashed two-way line: `trino <-> minio style=return`.
|
|
29
|
+
- Several sources into one box: they are spread along the side for you, but then bend unevenly; give every arrow its own point. Send the upper ones into the left side (`web.right -> nifi.left@256`, `ftp.right -> nifi.left@272`, 16 apart, one of them level with its source so it is straight) and the lower ones up into the bottom (`dbc.right -> nifi.bottom@352`, `legacy.right -> nifi.bottom@400`).
|
|
30
|
+
- No box sends out more than three arrows. If one seems to need more, it is the hub: make it the focal box and route through it.
|
|
31
|
+
|
|
32
|
+
## Icons
|
|
33
|
+
|
|
34
|
+
One icon per component says what kind of thing it is (`icon=queue` broker, `icon=database` store, `icon=pipeline`, `icon=monitoring`, `icon=user`), on every box of the diagram or none. The `sub=` line then carries the product. In a 144-wide box the name must stay under about 12 characters beside an icon, or the box takes `icon.pos=top` and 80 high.
|
|
35
|
+
|
|
36
|
+
## Legend
|
|
37
|
+
|
|
38
|
+
`legend at 40,Y` 24px under the last full-width box: `external=`, `focal=`, `cloud=` ("spans every phase"), `primary=`, `arrow=`, `return=`, and `node=`/`store=` if you used them as different things. The zones and the banner explain themselves.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Integration diagrams
|
|
2
|
+
|
|
3
|
+
Shows what plugs into a data platform and what it serves, and over which protocol: source systems on the left, the platform in the middle, consumers on the right, shared services underneath. There are no phases and no time axis. The claim is the number of distinct connections, so this kind may have more boxes than the usual nine (up to about 16).
|
|
4
|
+
|
|
5
|
+
## Composition
|
|
6
|
+
|
|
7
|
+
- Title at 40,52 (`style=h1`). Three columns: sources at x=40, consumers at x=1000 (`external`, 160x64), and between them one zone, `zone "Data platform" at 280,136 640xH dash=none` (`dash=none` makes it solid).
|
|
8
|
+
- Side boxes are 88 apart (24 between), centred on the surfaces' centre y, call it Y: box i of n (from 0) has its top at `Y - 32 - 44*(n-1) + 88*i`. Three boxes with Y=320: tops 200, 288, 376. The zone ends 16px below the lowest side box.
|
|
9
|
+
- Inside the zone, on one row: the two or three surfaces the outside connects to (storage, query engine), 160x72 (write the size: the default is 144x64), at least 176px apart. Exactly two of them are `focal`: the ones that make this a platform and not a pile of tools.
|
|
10
|
+
- Put that row level with the middle box of the side columns. Then the middle wire on each side is straight and the others fan out evenly above and below it.
|
|
11
|
+
- An orchestrator is a wide `cloud` box along the top of the zone (32px below its top edge, 16px in from its sides, 56 high: `296,168 608x56`), at least 56px above the row, so Y is at least 320.
|
|
12
|
+
- Every source and every consumer is its own box, even when three look alike. Merge only identical ones ("Databases", `sub="4 × MariaDB"`).
|
|
13
|
+
- Services for the whole platform (identity, logging, secrets) are `cloud` boxes 48 high in a row 48px under the zone, 32px apart, filling x=40 to 1160. Widths on the 4px grid: two 544, three 352, four 256 (`x = 40 + (w+32)*i`). They are outside the zone: identity guards the platform from outside. Each can take `icon=` (`lock`, `key`, `log`, `monitoring`); so can sources and consumers (`database`, `api`, `users`, `laptop`), on all of them or none.
|
|
14
|
+
|
|
15
|
+
## Arrows
|
|
16
|
+
|
|
17
|
+
- One arrow per wire, each labelled with its protocol (REST, CSV, JDBC). Never one bundled arrow from "the sources".
|
|
18
|
+
- Give every arrow its own point on the platform box, 16px apart, the middle one at the box's centre: `crm.right -> store.left@304`, `pos.right -> store.left@320`, `events.right -> store.left@336`.
|
|
19
|
+
- The outer wires bend inside the zone, 32px before the box, so the stretch next to the source stays clear for the label: `crm.right -> store.left@304 "REST" via=312,232;312,304` (312 = box left minus 32; 232 = centre y of the source). Mirror this on the consumer side with the box's right edge plus 32.
|
|
20
|
+
- Place every protocol label on the stretch between the side column and the zone, which is 80px wide: `lpos=240,B` on the left and `lpos=960,B` on the right, with B = that side box's centre y minus 10. Keep labels to about 9 characters; a longer one touches the zone border or the turning vertical at 312/888, so widen the gap (zone at 296, width 608) instead.
|
|
21
|
+
- Styles: source to platform is a plain arrow. Platform to consumer is `style=link`. The one hop between the two focal boxes is `style=primary`.
|
|
22
|
+
- Orchestrator to a box: a straight dashed drop without a label, `orch.bottom@424 -> store.top@424 style=return` (424 = centre x of the target).
|
|
23
|
+
- A shared service connects to the platform as a whole, never to one box inside it: `idp.top@440 -> plat.bottom@440 "auth" style=return`. The arrow ends on the zone's bottom edge. Choose an x that is under the zone and over the service box. Several service arrows need x at least 120 apart.
|
|
24
|
+
|
|
25
|
+
## Traps
|
|
26
|
+
|
|
27
|
+
- No arrow from a shared service to a single component, unless it really serves only that one.
|
|
28
|
+
- No colour per product. Only the two focal boxes carry the accent.
|
|
29
|
+
- No phase banner across the top: that belongs to a high-level diagram.
|
|
30
|
+
|
|
31
|
+
## Legend
|
|
32
|
+
|
|
33
|
+
`legend at 40,Y` 24px under the service row: `external=` (source or consumer), `focal=`, `cloud=`, `arrow=`, `primary=`, `link=`, `return=`.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# IT current-state diagrams
|
|
2
|
+
|
|
3
|
+
Shows the landscape as it is today, before a change is proposed: the systems, files and people, grouped by phase or department, the hand-offs between them, and where it hurts. It is the "before" picture that a proposal answers, so the pain points must be the first thing the reader sees.
|
|
4
|
+
|
|
5
|
+
## Composition
|
|
6
|
+
|
|
7
|
+
- Title at 40,52 (`style=h1`), optional summary at 40,88. Two to four zones side by side, one per phase or department (Collection, Processing, Dissemination), in the order the work moves, each `dash=none` for a solid outline. All start at y=136 and have the same height.
|
|
8
|
+
- Inside a zone, one column of boxes: 64 high, the first 40px below the zone's top edge, then every 112px (48px between boxes, room for a labelled arrow). Rows are shared by all zones: y=176, 288, 400. A zone with three rows is 352 high, with r rows `40 + 112*r - 48 + 16` = `112*r + 8`.
|
|
9
|
+
- A zone is its boxes plus 16px on each side. Boxes are 208 wide; a zone whose names are long may use 240.
|
|
10
|
+
- Leave 104px between zones: for a zone's right edge Z, the gap is x=Z to Z+104. Arrows that cross turn in this gap, and their labels sit in it. Zones at x=40, 384, 728 with 240 width: zone k (from 0) is at `x = 40 + 344*k`.
|
|
11
|
+
- A zone with only one or two boxes: start it at the row of its first box minus 40 (y=248 for row 2) and end it at the common bottom, so it holds no empty rows. Do not leave a free row inside a zone.
|
|
12
|
+
- At most five boxes in a zone and sixteen in all. Beyond that, draw two diagrams.
|
|
13
|
+
- Main text is the name people use for the thing. `sub=` says what makes it what it is: format, schedule, or the problem ("no version control", "manual refresh").
|
|
14
|
+
- Styles: `node` for an ordinary system or file, `store` for a system of record, `optional` (dashed) for anything outside the organisation, `focal` for a pain point. Boxes are 208x64 or 240x64: write the size on each, a `store` too (its default is 144x72). An `icon=` per box (`file`, `excel`, `database`, `server`, `laptop`, `user`, `phone`) shows what kind of thing it is; use it on every box or none.
|
|
15
|
+
- A one-line summary under the title helps: `text "..." at 40,88`.
|
|
16
|
+
|
|
17
|
+
## Focus
|
|
18
|
+
|
|
19
|
+
At most two `focal` boxes: the pain points the proposal is about. If everything that is bad is marked, nothing is. Say what is wrong in `sub=`. If you find a third, the diagram is telling two stories: split it.
|
|
20
|
+
|
|
21
|
+
## Arrows
|
|
22
|
+
|
|
23
|
+
- Every hand-off is labelled with what is passed or how: CSV, XLSX, copy, email. These labels are the evidence, so do not drop them.
|
|
24
|
+
- Inside a zone: a straight vertical arrow to the box below, `drive -> sheets "copy"`. The label is drawn to the right of the line.
|
|
25
|
+
- Into the next zone on the same row: a straight arrow. Label it over the gap: `lpos=X,Y` with X = Z+52 (the middle of the gap) and Y the line's y minus 10. Labels up to about 12 characters fit.
|
|
26
|
+
- Into the next zone on another row: give the turning points, in the gap: `online.right -> drive.left@208 "export" via=356,320;356,208 lpos=316,310`. The vertical is at x=Z+76 (356 for Z=280), and the label stays on the first stretch, centred at Z+36 (316), where it clears both the zone border (Z) and the vertical. So a label here is at most about 7 characters ("export", "XLSX"); for a longer one use Z+88 for the vertical and a 128px gap.
|
|
27
|
+
- Several arrows into one box: one point each, 16px apart (`drive.left@192`, `@208`, `@224`), and one vertical each, 16px apart (Z+76, Z+92), with the arrow from the lowest source turning nearest to the target and entering lowest. Then none of them cross. Let one be straight by starting it at the same y: `pos.right@192 -> drive.left@192`.
|
|
28
|
+
- Styles: a plain arrow for an ordinary hand-off, `style=return` (dashed) for one that crosses the organisation's edge, `style=primary` for the one or two hand-offs that cause the pain (the manual copy, the file sent around).
|
|
29
|
+
- Work moves left to right and downwards. An arrow pointing back is allowed only to or from an outside party, dashed.
|
|
30
|
+
|
|
31
|
+
## Legend
|
|
32
|
+
|
|
33
|
+
`legend at 40,Y` 24px under the zones (zones end at y=488 for three rows, so Y=512), with only the styles used: `focal="Pain point"`, `optional=`, `store=`, `arrow=`, `primary=`, `return=`.
|
package/guide/journey.md
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# User journeys
|
|
2
|
+
|
|
3
|
+
Shows how one person feels while moving through the stages of an experience, and what they do at each stage. The line of feeling is what makes it a journey; if you cannot say how the person feels at each stage, draw a process or a timeline. One person per diagram.
|
|
4
|
+
|
|
5
|
+
FastDraw has no journey elements. You build the grid from text and lines at exact coordinates, so first fix the column centres and row y-positions and reuse them everywhere.
|
|
6
|
+
|
|
7
|
+
## Composition
|
|
8
|
+
|
|
9
|
+
- Title: `text "..." at 40,52 style=h1`. The stage headers start at y=100.
|
|
10
|
+
- Columns: one per stage, six at most, centres 216px apart. Leave 128px on the left for row names: the first centre is x=228, the grid lines run from x=128 to the right edge of the last column (last centre + 108).
|
|
11
|
+
- Stage header, centred on each column: `text "Stage 1" at cx,100 style=eyebrow anchor=middle`, and 20px lower the stage name with `weight=600 anchor=middle`.
|
|
12
|
+
- Feeling band, 40px under the headers: three `style=rule` lines (written with `--`) at y=160, 240, 320 for high, neutral and low, each named at the left with `text "High" at 112,<line y + 3> style=eyebrow anchor=end`. Feelings are words on five steps (the three lines and the two half-way heights, 200 and 280), never numbers, never emoji.
|
|
13
|
+
- The curve: one dot per stage at the column centre, on the height of its level: `ellipse at cx-5,y-5 10x10 fill=muted stroke=none`. Join neighbours with straight lines given as points, `228,160 -- 444,240 sw=1.5`, so they meet in the middle of the dots. Write the lines before the dots.
|
|
14
|
+
- Rows under the band: a `style=rule` line at y=344 (24px below the low line), then up to three rows, each closed by another rule, the last row by none (the legend's own line closes it). Row name at the left like the level names, baseline 3px under the row's text baseline. The actions row is 96px high (rules at 344 and 440) so that two markers fit under the text; other rows 56px.
|
|
15
|
+
- Actions are plain `text`, `anchor=middle`, baseline 28px under the rule (y=372). Touchpoints (where it happens: a page, an email) use `style=small`, baseline 32px under their rule (y=472). Markers: first at y=384, second at y=408.
|
|
16
|
+
|
|
17
|
+
## Emphasis
|
|
18
|
+
|
|
19
|
+
The accent marks the lowest point, twice: its dot and the line falling into it (`fill=accent`, `stroke=accent`), and one or two markers under that stage's action saying what goes wrong:
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
rect "NO WARNING AT 80%" at cx-92,384 184x16 radius=2 fill=accent/0.08 stroke=accent/0.5 sw=0.8 dash=3,3
|
|
23
|
+
title.font=mono title.size=8 title.weight=400 title.color=accent title.spacing=0.1
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Mark only the low stage. A marker on every stage says nothing.
|
|
27
|
+
|
|
28
|
+
## Text
|
|
29
|
+
|
|
30
|
+
- Row and level names are horizontal, in the left margin. Keep an action under 26 characters, a marker under 30, so neighbours do not touch.
|
|
31
|
+
- No boxes around stages or cells: the grid lines and the alignment are enough.
|
|
32
|
+
|
|
33
|
+
## Legend
|
|
34
|
+
|
|
35
|
+
`legend at 40,Y line.muted="How the user feels" dot.accent="Lowest point" swatch.accent/0.15="What hurts there"`, Y = the bottom of the last row + 24 (520 for the rows above). Draw no rule of your own above it: the legend has one, and a second rule under a row that is already closed looks like an empty row.
|
package/guide/kanban.md
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Kanban boards
|
|
2
|
+
|
|
3
|
+
Shows where work stands right now: columns are states, cards are pieces of work, and each column says how many cards it holds against how many it may hold.
|
|
4
|
+
|
|
5
|
+
A board has no arrows. If you need to show how work moves, draw a flowchart or a swimlane instead.
|
|
6
|
+
|
|
7
|
+
## Building blocks
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
text "Platform team board, week 14" at 40,52 style=h1
|
|
11
|
+
|
|
12
|
+
// a column: a zone with no outline, a name, a count chip, a line under the header
|
|
13
|
+
c2: zone at 312,96 240x324 stroke=none
|
|
14
|
+
text "In progress" at 328,116 weight=600 color=ink
|
|
15
|
+
w2: rect "4/3" at 496,104 40x16 radius=2 fill=none stroke=accent sw=0.8 title.font=mono title.size=8 title.weight=400 title.color=accent
|
|
16
|
+
312,132 -- 552,132 stroke=ink/0.2 sw=1
|
|
17
|
+
|
|
18
|
+
// cards: write the size on every one (the default node is 144x64)
|
|
19
|
+
p2: node "K8s node pool migration" sub="AVA-142 · priya" at 328,212 208x56 title.align=left
|
|
20
|
+
p1: focal "Postgres 16 upgrade" sub="AVA-118 · sam" at 328,144 208x56 title.align=left dash=4,4 fill=accent/0.08 title.color=ink sub.color=muted
|
|
21
|
+
rect at 328,144 4x56 fill=accent stroke=none overlap=ok // strip on the blocked card
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Composition
|
|
25
|
+
|
|
26
|
+
- Title at 40,52; columns start at y=96. Columns are 240 wide with 32px between them, starting at x=40. Column k (from 0) is at `x = 40 + 272*k`. Five is the limit.
|
|
27
|
+
- All columns have the same height: 52 + 68 * (cards in the fullest column). The space left under a short column is its free capacity; leave it.
|
|
28
|
+
- Header: the name at column x+16, baseline 20px below the column top. The chip is 40x16, at column x+184 (its right edge 16px in), 8px below the top. The line under the header is 36px below the top and spans the column.
|
|
29
|
+
- A card is 208x56 (the column width minus 16px each side). The first card starts 12px under the header line (column top + 48); the next starts 68px lower (56 plus a 12px gap).
|
|
30
|
+
- Four cards per column and twelve on the whole board at most. If a column has more, show three and a last card that counts the rest (`optional "+14 more"`).
|
|
31
|
+
- Cards are pieces of work, not people. Put the owner in `sub=`.
|
|
32
|
+
|
|
33
|
+
## Card states
|
|
34
|
+
|
|
35
|
+
| State | Write it as |
|
|
36
|
+
|---|---|
|
|
37
|
+
| open | `node` |
|
|
38
|
+
| blocked | `focal dash=4,4 fill=accent/0.08 title.color=ink sub.color=muted` (white text would vanish on the pale fill), plus a 4px-wide accent `rect` on its left edge (`overlap=ok`) |
|
|
39
|
+
| waiting on someone outside the team | `optional` |
|
|
40
|
+
| done | `node fill=ink/0.05 stroke=ink/0.3 title.color=muted` (not `store`: that means data, and many looks draw it as a cylinder) |
|
|
41
|
+
|
|
42
|
+
Every card has `title.align=left`, a short title and a `sub=` of ticket id and owner.
|
|
43
|
+
|
|
44
|
+
## Counts and limits
|
|
45
|
+
|
|
46
|
+
- A column that work passes through shows `count/limit` in its chip. The first column (the queue) and the last (done) show the count alone.
|
|
47
|
+
- When the count is above the limit, the chip's outline and text turn accent (`stroke=accent title.color=accent`).
|
|
48
|
+
- The accent appears twice at most: one over-limit chip and one blocked card. If three cards are blocked, mark the oldest and say so in the legend.
|
|
49
|
+
- Keep the chip a rectangle with `radius=2`. Keep the done column short: show the latest two or three and say in a caption where the rest went.
|
|
50
|
+
|
|
51
|
+
## Legend
|
|
52
|
+
|
|
53
|
+
The blocked card, the done card and the chip are overrides, not styles, so mix styles and marks in one statement, 24px under the columns (column top + height + 24): `legend at 40,Y node="Open" optional="Waiting on someone outside" swatch.accent/0.15="Blocked" swatch.ink/0.08="Done" line.accent="Over its limit"`.
|
package/guide/layers.md
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Layer stacks
|
|
2
|
+
|
|
3
|
+
Shows layers that build on each other: a protocol stack, a tech stack, levels of abstraction, a cache hierarchy. Use it only when each layer really rests on the one below; otherwise draw an architecture diagram.
|
|
4
|
+
|
|
5
|
+
## Composition
|
|
6
|
+
|
|
7
|
+
- Title at `40,52` (`style=h1`). Four to six layers (n). Each is a full-width band: same x, same width, same height, touching the next one with no gap.
|
|
8
|
+
- Leave 96px free on the left for the direction marker: the stack starts at x = 136 and runs to x=960 (824 wide). Bands are 64px tall; band k from the top (from 0) is at `y = 96 + 64k`, so the stack ends at `96 + 64n`.
|
|
9
|
+
- A band is a plain `rect` with a faint outline; all ordinary bands look the same. Different colours per layer hide the order.
|
|
10
|
+
- One layer, the one the diagram is about, is a `focal` box with `radius=0`. Write it after the other bands so its outline is drawn on top of its neighbours'. Here the second band from the top is focal:
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
l1: rect at 136,96 824x64 fill=ink/0.03 stroke=ink/0.15
|
|
14
|
+
l3: rect at 136,224 824x64 fill=ink/0.03 stroke=ink/0.15
|
|
15
|
+
l4: rect at 136,288 824x64 fill=ink/0.03 stroke=ink/0.15
|
|
16
|
+
l2: focal at 136,160 824x64 radius=0
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- Order matters and is complete: highest level at the top, no layer left out, numbers without holes.
|
|
20
|
+
|
|
21
|
+
## Text
|
|
22
|
+
|
|
23
|
+
The bands carry no text of their own. Each row gets three free texts on nearly one baseline, measured from the band's top edge `Y`: index at Y+36, name at Y+38, detail at Y+37.
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
text "L4" at 156,132 style=eyebrow // index, 20px in from the left edge
|
|
27
|
+
text "Application" at 224,134 size=16 weight=600 // name, 88px in
|
|
28
|
+
text "HTTP, JSON, cookies" at 940,133 style=small size=10 anchor=end // detail, ending 20px before the right edge
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
- On the focal row all three texts are free text over the focal fill (the index and name `weight=600`). Keep the default colours on a pale fill, as in the built-in look; give each `color=#ffffff` only when the look fills `focal` with solid accent. Never the accent colour: it vanishes on a solid accent. `fastdraw check` warns when text cannot be read.
|
|
32
|
+
- Keep the detail to a few words; it must end well clear of the name.
|
|
33
|
+
|
|
34
|
+
## Direction
|
|
35
|
+
|
|
36
|
+
Say which way the stack runs, outside it on the left: one vertical arrow from the stack's foot to 8px under its top, with a word at each end. Top = `96`, bottom = `96 + 64n`:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
text "Abstraction" at 76,92 style=eyebrow anchor=middle // 12px above the arrow tip
|
|
40
|
+
76,352 -> 76,104 // foot = bottom of the stack (n=4)
|
|
41
|
+
text "Hardware" at 76,372 style=eyebrow anchor=middle // 20px under the arrow's foot
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
No other arrows. Position in the stack is the relationship. Icons add nothing here.
|
|
45
|
+
|
|
46
|
+
## Note and legend
|
|
47
|
+
|
|
48
|
+
- One sentence in `style=note` may sit 48px under the stack (baseline), starting at the stack's left edge, saying why the focal layer matters.
|
|
49
|
+
- Finish with `legend at 40,Y focal="..."`, 24px under the note (Y = 96 + 64n + 72).
|