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.
Files changed (74) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +193 -2
  3. package/agents/AGENTS-snippet.md +10 -0
  4. package/agents/README.md +11 -0
  5. package/agents/claude-skill/fastdraw/SKILL.md +14 -0
  6. package/dist/cli.js +3694 -0
  7. package/fonts/Geist-Medium.ttf +0 -0
  8. package/fonts/Geist-Regular.ttf +0 -0
  9. package/fonts/Geist-SemiBold.ttf +0 -0
  10. package/fonts/GeistMono-Medium.ttf +0 -0
  11. package/fonts/GeistMono-Regular.ttf +0 -0
  12. package/fonts/InstrumentSerif-Italic.ttf +0 -0
  13. package/fonts/InstrumentSerif-Regular.ttf +0 -0
  14. package/fonts/LibreFranklin-Bold.ttf +0 -0
  15. package/fonts/LibreFranklin-Medium.ttf +0 -0
  16. package/fonts/LibreFranklin-Regular.ttf +0 -0
  17. package/fonts/LibreFranklin-SemiBold.ttf +0 -0
  18. package/fonts/Newsreader-Italic.ttf +0 -0
  19. package/fonts/Newsreader-Medium.ttf +0 -0
  20. package/fonts/Newsreader-Regular.ttf +0 -0
  21. package/fonts/Newsreader-SemiBold.ttf +0 -0
  22. package/fonts/OFL-Geist.txt +93 -0
  23. package/fonts/OFL-InstrumentSerif.txt +93 -0
  24. package/fonts/OFL-LibreFranklin.txt +93 -0
  25. package/fonts/OFL-Newsreader.txt +93 -0
  26. package/fonts/OFL-SketchHand.txt +49 -0
  27. package/fonts/SketchHand-Regular.ttf +0 -0
  28. package/guide/architecture-delta.md +52 -0
  29. package/guide/architecture.md +28 -0
  30. package/guide/axonometric-plan.md +54 -0
  31. package/guide/bar.md +61 -0
  32. package/guide/data-flow.md +42 -0
  33. package/guide/db-schema.md +46 -0
  34. package/guide/dependency.md +38 -0
  35. package/guide/deployment.md +46 -0
  36. package/guide/er.md +49 -0
  37. package/guide/exploded.md +53 -0
  38. package/guide/fishbone.md +44 -0
  39. package/guide/flowchart.md +22 -0
  40. package/guide/gantt.md +48 -0
  41. package/guide/guide.md +278 -0
  42. package/guide/heatmap.md +59 -0
  43. package/guide/high-level.md +38 -0
  44. package/guide/integration.md +33 -0
  45. package/guide/it-state.md +33 -0
  46. package/guide/journey.md +35 -0
  47. package/guide/kanban.md +53 -0
  48. package/guide/layers.md +49 -0
  49. package/guide/line.md +112 -0
  50. package/guide/look.md +174 -0
  51. package/guide/loop.md +45 -0
  52. package/guide/medallion.md +37 -0
  53. package/guide/nested.md +36 -0
  54. package/guide/org-chart.md +48 -0
  55. package/guide/polar.md +57 -0
  56. package/guide/process.md +41 -0
  57. package/guide/pyramid.md +46 -0
  58. package/guide/quadrant.md +44 -0
  59. package/guide/radar.md +60 -0
  60. package/guide/sankey.md +53 -0
  61. package/guide/scatter.md +73 -0
  62. package/guide/security-matrix.md +47 -0
  63. package/guide/sequence.md +39 -0
  64. package/guide/state.md +38 -0
  65. package/guide/story-map.md +29 -0
  66. package/guide/swimlane.md +40 -0
  67. package/guide/timeline.md +49 -0
  68. package/guide/tree.md +33 -0
  69. package/guide/treemap.md +67 -0
  70. package/guide/uml-class.md +59 -0
  71. package/guide/venn.md +48 -0
  72. package/guide/wardley.md +35 -0
  73. package/guide/waterfall.md +47 -0
  74. package/package.json +59 -4
package/guide/line.md ADDED
@@ -0,0 +1,112 @@
1
+ # Line charts
2
+
3
+ Shows how a number changes over time or along an ordered scale: signups per week, latency per release. The reader looks at direction and steepness. Four variants at the end cover two-state comparisons (slopegraph), rank changes (bump), distributions (ridgeline) and a total with its parts (streamgraph).
4
+
5
+ ## Building blocks
6
+
7
+ ```
8
+ // Title at y=52, plot 96,96 to 960,412. The series the chart is about is written last, so it is drawn on top
9
+ title: text "Signups grew every week" at 40,52 style=h1
10
+ sig: chart at 96,96 864x316 x="W1,W2,W3,W4" y=0..240 step=40 key=0 ytitle="Signups per week"
11
+ | line "Referral" 45 52 48 60 stroke=soft sw=1.5
12
+ | line "Direct" 80 82 88 90 stroke=muted sw=1.5
13
+ | area "Organic" 120 135 148 162 stroke=accent fill=accent/0.08 dots=1
14
+ text "Organic · 162" at 852,188 size=11 weight=600 color=accent anchor=end
15
+ text "Direct" at 852,283 size=10 color=muted anchor=end
16
+ text "Referral" at 852,323 size=10 color=soft anchor=end
17
+ legend at 40,464 line.accent="Organic" line.muted="Direct" line.soft="Referral"
18
+ ```
19
+
20
+ ## Composition
21
+
22
+ - Title at y=52, plot `at 96,96 864x316` (tick labels end near y=440), legend at y=464. Move the legend 20px lower if there is an `xtitle=`.
23
+ - Four to twelve points per line. With more, sum them into longer periods.
24
+ - Five lines at most. One is the subject: `stroke=accent`, default width, `dots=1`. The others are `stroke=muted`, `soft` or `ink/0.5` with `sw=1.5` and no dots.
25
+ - Use `area` instead of `line` for the subject only when the amount under the line means something (a volume, a count). Give it `fill=accent/0.08`; the default tint is heavy and dulls the lines under it.
26
+ - `y=0..N` when the size of the number matters. A range that starts above 0 is allowed only for a quantity with no natural zero, and then say so in `ytitle=`.
27
+ - A missing value is `_`, which breaks the line. Do not bridge it.
28
+ - The chart joins points with straight segments. Keep it so: a smoothed curve shows highs and lows between samples that nobody measured.
29
+
30
+ ## Text
31
+
32
+ - Name each line at its right end, right-aligned to the last point: `anchor=end`, size 10 or 11, in the line's colour. The last point of n categories is at `x = 96 + 864 * (n - 0.5) / n` (852 for four, 906 for eight); its height is `y = 412 - value / ymax * 316`. Put the baseline 10px above that.
33
+ - Two lines that end closer than 14px (a few units, `14 / 316 * ymax`) would put their labels on top of each other. Keep the upper label 10px above its point and put the lower one below its point (baseline 16px under it). Do not move the lines. If three end together, name the third in the legend only.
34
+ - Write the latest value of the subject line in its label. Do not use `labels=1` with several lines; the numbers pile up.
35
+
36
+ ## Slopegraph
37
+
38
+ Two states (before and after), four to ten things, one straight line each. The reader compares slopes. Use a chart with two categories and hide its own axes:
39
+
40
+ ```
41
+ // y 100..550 over 320px: value v is at y = 416 - (v - 100) * 320 / 450. The two states are at x=350 and x=650
42
+ 350,96 -- 350,416 stroke=ink/0.25 layer=back // the two state rules, behind the lines
43
+ 650,96 -- 650,416 stroke=ink/0.25 layer=back
44
+ sl: chart at 200,96 600x320 x="Before,After" y=100..550 yaxis=0 grid=0 key=0 stroke=none tick.size=10
45
+ | line 512 208 stroke=ink/0.7 sw=1.2 dots=1
46
+ | line 238 431 stroke=accent sw=2.5 dots=1 // the subject last
47
+ text "Search" at 290,127 anchor=end size=11 color=ink // name, then value, left of the left rule
48
+ text "512" at 338,127 anchor=end style=small color=muted
49
+ text "431" at 662,185 style=small color=muted // value, then name, right of the right rule
50
+ text "Recommender" at 694,185 size=11 weight=600 color=ink
51
+ ```
52
+
53
+ - With two categories the points are a quarter and three quarters of the way across the chart box.
54
+ - Label both ends of every line with name and value, baseline 4px below the point. Where two labels on one side are closer than 14px, shift them apart evenly and leave the dots where they are.
55
+ - Both sides share one scale; that is why it is one chart. State the range in the legend heading when it does not start at 0 (`title="p95 in ms · scale 100 to 550"`).
56
+ - Keep each label wholly outside or wholly inside the chart box. A text that crosses its edge is reported as an overlap.
57
+
58
+ ## Bump chart
59
+
60
+ Ranks at three to six moments. The same construction with more categories. The y range must run upwards, so plot `ranks + 1 - rank` to put rank 1 on top:
61
+
62
+ ```
63
+ bp: chart at 320,96 480x336 x="Q1,Q2,Q3,Q4" y=0.5..6.5 step=10 yaxis=0 grid=0 key=0 stroke=none tick.size=10
64
+ | line 5 4 4 5 stroke=ink/0.6 sw=1.2 dots=1 // ranks 2, 3, 3, 2
65
+ | line 6 5 3 1 stroke=accent sw=2.5 dots=1 // ranks 1, 2, 4, 6
66
+ ```
67
+
68
+ - With `y=0.5..N+0.5`, rank r is at `plot y + plot height * (r - 0.5) / N`: 56px rows here.
69
+ - Left of the first column: the name (`anchor=end`, outside the chart box) and `#1`, `#2` ... in `small`. Right of the last column: the same in final order. Every rank at every moment is taken by exactly one line.
70
+ - Never bend a line off its row to make room for a label.
71
+
72
+ ## Ridgeline
73
+
74
+ One distribution per row, rows overlapping, to compare shapes. Each row is its own small chart with one `area`; all share width, height and `y=` range, so heights compare:
75
+
76
+ ```
77
+ // rows 56px apart, each 120px high, so a peak may reach into the row above but not two rows up
78
+ r1: chart at 320,96 384x120 y=0..50 yaxis=0 grid=0 key=0 stroke=none overlap=ok
79
+ | area 0 22 30 18 9 5 2 1 0 0 0 0 0 stroke=ink/0.7 sw=1 fill=ink/0.1
80
+ r2: chart at 320,152 384x120 y=0..50 yaxis=0 grid=0 key=0 stroke=none overlap=ok
81
+ | area 0 5 24 31 16 7 3 1 1 0 0 0 0 stroke=ink/0.7 sw=1 fill=ink/0.1
82
+ 320,216 -- 704,216 stroke=ink/0.6 sw=1 // the baseline of r1: its y + height
83
+ text "static-cdn" at 304,220 anchor=end size=11 color=ink
84
+ ```
85
+
86
+ - Three to eight rows. The subject row takes `stroke=accent sw=2 fill=accent/0.15`.
87
+ - The rows end at the last row's y + 120 + 64 (its tick labels and the scale name); the legend goes 24px lower.
88
+ - Only the last chart has `x="0,,,120,,,240"`: one entry per bin, empty where no tick label is wanted. Name the scale in a `small` text under it.
89
+ - Order the rows by something you can state (median, peak position) and say it in the legend heading.
90
+
91
+ ## Streamgraph
92
+
93
+ A total and its parts over many periods, drawn as bands around a centre line. Three to five layers. The chart does not stack areas, so give it the boundaries: for each period, add the layers up from the bottom, and shift each period so the stack is centred on the same level.
94
+
95
+ ```
96
+ // boundaries from the top one down; each area paints over the ones before it; the last, in paper colour, clears below the stream
97
+ st: chart at 60,96 880x320 x="W01,W02,W03,W04" y=0..200 yaxis=0 grid=0 key=0 stroke=none
98
+ | area 140 142 146 152 fill=soft stroke=paper sw=1 // top of the top layer
99
+ | area 130 133 138 143 fill=accent stroke=paper sw=1
100
+ | area 120 120 118 116 fill=ink stroke=paper sw=1
101
+ | area 80 78 75 72 fill=muted stroke=paper sw=1
102
+ | area 60 58 54 48 fill=paper stroke=paper sw=1 // bottom of the stream
103
+ ```
104
+
105
+ - Bottom boundary of a period = `centre - total / 2`; each boundary above adds one layer's value. Keep `y=` starting at 0 and all boundaries above 0.
106
+ - Fills must be solid colours (`ink`, `muted`, `soft`, `accent`, a `#hex` grey). A see-through fill would mix with the layers painted under it.
107
+ - The largest layers go in the middle, the layer order never changes, and one layer takes the accent. A layer that is zero for a while pinches shut; leave it.
108
+ - There is no y axis: thickness is read, not position. Put totals in the legend entries (`swatch.accent="End-to-end · 688 min"`).
109
+
110
+ ## Legend
111
+
112
+ `legend at 40,464` (24px under the lowest element) with one `line.COLOUR=` entry per line (`swatch.COLOUR=` for ridgeline and streamgraph). The subject comes first and its entry says why it matters.
package/guide/look.md ADDED
@@ -0,0 +1,174 @@
1
+ # Writing a look
2
+
3
+ A look is one text file (`.look`) that decides how every style is drawn: colours, fonts, shapes, lines and text. Diagrams point to it with `look "./team.look"`. Change the look and every diagram that uses it changes.
4
+
5
+ Five looks ship with FastDraw and need no file: `look headline`, `look night`, `look reference`, `look sketch` and `look whiteboard` (a bare name, no quotes or `.look`). In the editor, the **Look** button shows the diagram in each of them and the built-in look, to try one before keeping it.
6
+
7
+ ## How to work
8
+
9
+ 1. Start from the built-in look: `fastdraw init-look team.look`. It has every style the guides rely on, so you change values instead of inventing structure.
10
+ 2. Edit the file.
11
+ 3. Run `fastdraw preview-look team.look` and **look at the PNG**. It draws every style on one sheet. `fastdraw sizes team.look` lists the styles and reports mistakes.
12
+ 4. Render a real diagram with it (`fastdraw render some.fdraw`) before calling it done. A look that is fine on the sheet can still be too heavy or too faint in a real composition.
13
+
14
+ Keep the style names from the built-in look (`node`, `focal`, `store`, `cloud`, `external`, `optional`, `step`, `terminal`, `terminal-focal`, `decision`, `zone`, `bar`, `arrow`, `primary`, `link`, `return`, `lifeline`, `rule`, `h1`, `eyebrow`, `caption`, `note`, `small`). The diagram guides and existing diagrams use those names. You may add more styles of your own.
15
+
16
+ The looks that ship with FastDraw all define the same styles (the ones above plus `kicker`, `dek`, `legend`, `table`, `matrix`, `chart`, `relation`, `sticky`, `sticky-orange` and `sticky-violet`), so a diagram can move between them without a style going plain. A test holds them to that: after editing one in `looks/`, run `node tools/bundle-looks.mjs`.
17
+
18
+ ## The file
19
+
20
+ One statement per line; an indented line continues the one above; `//` starts a comment.
21
+
22
+ ```
23
+ canvas paper=paper dots=ink/0.06 dotgap=22 // paper= background colour; dots= dot colour and dotgap= spacing are optional; a diagram's own canvas line can override any of the three
24
+ // sketch=1 draws every outline and line by hand (2 is rougher); see looks/sketch.look
25
+
26
+ color paper #ffffff // a named colour
27
+ color ink #1c1f2a
28
+ color accent #0e7c66
29
+
30
+ font sans "Geist" // the three font roles
31
+ font mono "Geist Mono"
32
+ font serif "Newsreader"
33
+
34
+ style node shape=rect radius=4 size=144x64 fill=#ffffff stroke=ink sw=1.2
35
+ use="default box: a service, component or step"
36
+ style focal extends node fill=accent/0.08 stroke=accent
37
+
38
+ style arrow line stroke=ink sw=1.3 route=ortho radius=6
39
+ style h1 text font=serif size=28 weight=400 color=ink
40
+
41
+ guidance "Use focal on at most two things in one diagram."
42
+ ```
43
+
44
+ ### Colours
45
+
46
+ A colour value is `#hex`, a name defined with `color`, or either followed by `/opacity`: `ink/0.3`, `#ffffff/0.85`. `none` means no fill or no stroke. Define `paper`, `ink` and `muted` at least; built-in parts fall back to those names. `card` is the fill of a plain box (white unless a look sets it; a dark look sets it to its box colour), so a diagram that writes `fill=card` stays right in every look.
47
+
48
+ ### Fonts
49
+
50
+ `font sans|mono|serif "Family"` sets the family for each role; styles then say `font=sans`.
51
+
52
+ Five families are bundled and always available: **Geist**, **Geist Mono** and **Newsreader** (the built-in look), **Libre Franklin** and **Instrument Serif**. To use any other font, put its files in a folder next to the look and name the folder:
53
+
54
+ ```
55
+ fontdir "./fonts" // relative to the look file
56
+ font sans "Fira Sans"
57
+ ```
58
+
59
+ - Files must be **TTF or OTF**, one file per weight and style you use (for example Regular and SemiBold; add Italic if a style sets `italic=1`). Box titles use weight 600 by default. Use static files, not a single variable font.
60
+ - The family name is read from inside the files, so `font sans "..."` must match it exactly. `fastdraw sizes team.look` lists the fonts and flags any family it found no file for; `fastdraw check` warns about it too.
61
+ - Commit the font folder with the look, and keep the font's licence file beside it. Use fonts whose licence allows redistribution (for example the SIL Open Font License).
62
+ - In the browser editor the look's fonts load when a folder is open. A diagram opened as a single file, pasted, or restored from an exported image is drawn with fallback fonts until its folder is opened.
63
+
64
+ ### Styles
65
+
66
+ `style name [extends other] [line|text] key=value ...`
67
+
68
+ - A style is a shape style unless you write `line` or `text` after the name.
69
+ - `extends other` starts from another style's values. Define the base first.
70
+ - `use="..."` is a short description shown to agents and in the editor's gallery. Write one for every style.
71
+
72
+ **Shape styles**
73
+
74
+ | Key | Meaning |
75
+ |---|---|
76
+ | `shape=` | `rect`, `ellipse`, `diamond`, `path`, or `table` (a header and rows, see below) |
77
+ | `path="..."` | with `shape=path`: an outline written in a box that runs from 0,0 to 1,1 and is stretched to the element. Commands `M`, `L`, `C`, `Q`, `Z` only, absolute. Example cylinder: `"M0,0.1 C0,-0.035 1,-0.035 1,0.1 L1,0.9 C1,1.035 0,1.035 0,0.9 Z M0,0.1 C0,0.235 1,0.235 1,0.1 C1,0.235 0,0.235 0,0.1"`. Every part of a path is filled, so a detail line such as the rim is traced there and back to enclose no area |
78
+ | `radius=` | corner radius of a `rect`; half the height or more makes a pill |
79
+ | `size=WxH` | default size when a diagram gives none |
80
+ | `fill=`, `stroke=`, `sw=`, `dash=5,4` | fill colour, stroke colour, stroke width, dash pattern |
81
+ | `hatch=colour` | fill with diagonal pencil lines on top of `fill=`; `hatch.gap=` spaces them, `hatch.sw=` weighs them |
82
+ | `sketch=0` | with `canvas sketch=` on: draw this style with clean lines (works on line styles too) |
83
+ | `layer=back` | draw behind everything (for regions like `zone`) |
84
+ | `title.*` | the main text: `title.font`, `title.size`, `title.weight`, `title.color`, `title.italic=1`, `title.spacing` (in em), `title.caps=1`; `title.pos=top` puts it as a small caption at the top edge |
85
+ | `sub.*` | the second line (`sub=` on an element): `sub.font`, `sub.size`, `sub.color` |
86
+ | `tag.*` | the corner marker (`tag=`): `tag.color`, `tag.border`, `tag.font`, `tag.size` |
87
+ | `ghost.*` | the big faint number (`ghost=`): `ghost.color`, `ghost.size` |
88
+
89
+ On a dark or saturated fill, set `title.color`, `sub.color`, `tag.color` and `tag.border` to something that contrasts, or the text disappears. Set these explicitly on every style; do not rely on defaults.
90
+
91
+ The tag sits 8px in from the top-left corner and is 12px tall, so keep a path's details (a cylinder rim) out of the top 20px or flatten them. A `title.pos=top` caption is centred on the top edge with a paper-coloured patch behind it.
92
+
93
+ **Table styles** (`shape=table`) use `fill`, `stroke`, `sw`, `radius`, `dash` and `title.*` like any box, plus:
94
+
95
+ | Key | Meaning |
96
+ |---|---|
97
+ | `head.fill=`, `head.h=` | the header band's colour and height (default 32) |
98
+ | `row.h=` | row height (default 24) |
99
+ | `cell.font=`, `cell.size=`, `cell.color=` | cell text; `cell.color` is the first column |
100
+ | `detail.color=` | text colour of every column after the first |
101
+ | `rule=` | colour of the thin lines between rows; `rules=0` removes them |
102
+ | `cell.pad=`, `cell.gap=` | space at the left and right edges (default 12) and between columns (default 16) |
103
+ | `align=center`, `grid=1` | centre the columns after the first; draw lines between columns |
104
+
105
+ **Chart styles** (`style name extends chart ...`): `stroke=` and `sw=` are the axis lines, `fill=` the plot background, and:
106
+
107
+ | Key | Meaning |
108
+ |---|---|
109
+ | `tick.font=`, `tick.size=`, `tick.color=` | tick labels |
110
+ | `value.font=`, `value.size=`, `value.color=` | the numbers written by `labels=1` |
111
+ | `axis.font=`, `axis.size=`, `axis.color=` | axis titles and the series key |
112
+ | `grid.color=` | grid lines |
113
+ | `bar.radius=`, `bar.width=` | bar corner radius; share of the category width the bars fill |
114
+ | `title.*` | the chart's title |
115
+
116
+ **Line styles** (`style name line ...`)
117
+
118
+ | Key | Meaning |
119
+ |---|---|
120
+ | `stroke=`, `sw=`, `dash=` | colour, width, dash pattern |
121
+ | `route=` | `ortho` (right-angle turns), `straight`, or `curve` (a smooth line) |
122
+ | `radius=` | corner radius of the turns |
123
+ | `head=` | the marker `->` draws: `arrow` (default), `open`, `triangle`, `diamond`, `diamond-solid`, `dot`, `circle`, or one of the relationship ends (`one`, `only-one`, `many`, `one-many`, `zero-one`, `zero-many`). `head=none` marks a style meant for plain lines, never arrows |
124
+ | `tail=` | a marker for the start of the line, if the style always has one |
125
+ | `label.*` | the text on the line: `label.font`, `label.size`, `label.color`, `label.spacing`, `label.caps=0` to keep the label's own case (default is capitals) |
126
+
127
+ **Text styles** (`style name text ...`): `font=`, `size=`, `weight=`, `color=`, `italic=1`, `spacing=`, `caps=1`.
128
+
129
+ ### Built-in styles you can restyle
130
+
131
+ `rect`, `ellipse`, `diamond`, `polygon`, `freehand`, `arc`, `table`, `chart`, `text`, `arrow`, `line`, `relation` and `legend` exist in every look. A style can also be built on `polygon` or `arc` (`style slice extends arc stroke=paper sw=2`); the corners and angles are still given on each element. Redefine one to change it. For the legend: `style legend extends legend rule=ink/0.2 title="Key" title.font=sans item.size=10`. Its keys are `rule` (the line's colour), `title` (heading text, or `none`), `title.font`, `title.size`, `title.color`, `title.spacing`, `title.caps`, and `item.font`, `item.size`, `item.color` for the entries.
132
+
133
+ ### Icons
134
+
135
+ Every look starts with a set of outline icons (see `fastdraw sizes`). Add your own, or replace one, with
136
+
137
+ ```
138
+ icon queue "M4 6h16" "M4 12h16" "M4 18h16"
139
+ ```
140
+
141
+ The quoted parts are SVG path data drawn in a 24x24 box; they are stroked, not filled, in the colour of the box's text. Keep to simple outlines with a 1.5 stroke in mind, so they match the bundled ones. A style can carry an icon (`style store extends node icon=database`), and `icon.size=`, `icon.color=`, `icon.pos=top` work in a style too.
142
+
143
+ **Colour icons and vendor sets** go in a folder of SVG files next to the look:
144
+
145
+ ```
146
+ icondir "./icons"
147
+ ```
148
+
149
+ Every `.svg` file directly in that folder becomes an icon, drawn exactly as the file looks, in its own colours. The icon's name is the file name in small letters with everything that is not a letter or digit turned into `-`, and a leading number-and-`icon-service-` prefix dropped: `10021-icon-service-Virtual-Machine.svg` is `icon=virtual-machine`, `Load Balancer.svg` is `icon=load-balancer`. `fastdraw icons team.look` lists them and `fastdraw icons team.look storage` searches. This is how a team adds, say, the Azure or AWS architecture icons: download the set from the vendor, copy the files you use into the folder, and commit them with the look (check the vendor's terms first; FastDraw ships none of them).
150
+
151
+ - A file icon keeps its colours; `icon.color=` does not apply to it.
152
+ - Files over 300 KB are skipped. Only the icons a diagram uses are carried inside its exported image.
153
+ - A file with the same name as a built-in icon replaces it.
154
+
155
+ ### Guidance
156
+
157
+ `guidance "..."` lines are shown to agents by `fastdraw sizes`. Use them for rules a drawing tool cannot enforce: how many accent elements are allowed, when to use `tag=`, what `sub=` is for.
158
+
159
+ ## What makes a look good
160
+
161
+ - **On dark paper, use solid fills for the accent.** A translucent tint (`accent/0.15`) over a dark background turns muddy; a solid accent with dark text on it stays clean.
162
+ - **Decide the accent first.** One colour carries the focus (`focal`, `terminal-focal`, `primary`). Everything else is ink, greys and paper. A look with three bright colours has no focus.
163
+ - **Separate by more than colour.** `external`, `optional`, `cloud` and `store` should differ in shape, fill or dash, so they read in greyscale and for colour-blind readers.
164
+ - **Two or three stroke weights at most**, and the accent arrow slightly heavier than the default arrow.
165
+ - **Check contrast** of text on every fill, and of faint things (`zone`, `lifeline`, `rule`) against the paper: visible, but quieter than the boxes.
166
+ - **Keep default sizes on a 4px grid** and the same height for the box styles that share a row.
167
+ - **Mono type is for technical detail** (paths, ports, commands), not for names.
168
+
169
+ ## Limits today
170
+
171
+ - Shapes cannot contain extra drawn details beyond the outline, one icon, the tag and the ghost number. The tag's position is fixed. Icons are outlines in one colour.
172
+ - The background can have dots but not grid lines.
173
+ - `path` outlines have no arcs (`A`); use curves (`C`, `Q`). Arrows attach to the outline's bounding box.
174
+ - Exported images carry the diagram and look but not the font files, so someone reopening an image without the repo sees fallback fonts for any font that is not bundled.
package/guide/loop.md ADDED
@@ -0,0 +1,45 @@
1
+ # Loop diagrams
2
+
3
+ Shows a cycle that feeds itself: steps around a ring, each handing over to the next, and one hub in the middle that every step writes to. Use it only when the last step really leads back to the first and the centre holds something that accumulates (a memory, a record, a standard). A path that ends is a flowchart.
4
+
5
+ ## Building blocks
6
+
7
+ ```
8
+ // title at y=52. Ring: centre 520,372 · radius 240 · six stations 60 degrees apart, the first at the top
9
+ title: text "Every release teaches the next one" at 40,52 style=h1
10
+ capture: node "Capture" sub="signals in / intake" at 440,100 160x64
11
+ research: node "Research" sub="evidence pulled" at 648,220 160x64
12
+ hub: rect "Shared memory" sub="one record, every loop" at 420,320 200x104 radius=8 fill=accent/0.12 stroke=accent sw=1.5 title.color=ink sub.color=muted
13
+
14
+ capture.right@146 -> research.top@705 route=curve bend=9 // a piece of the ring
15
+ research.bottom@743 -> decide.top@743 route=curve bend=16
16
+ capture.bottom -> hub.top "signals" style=return stroke=soft // a write-back
17
+ research.bottom@672 -> hub.top@616 style=return stroke=soft route=straight
18
+ ```
19
+
20
+ ## Composition
21
+
22
+ - Five to eight stations and exactly one hub. With more than eight, the write-backs crowd the hub: split the subject. Two hubs are two diagrams.
23
+ - Pick the centre `cx,cy` and the radius R. Station n of N (from 0, clockwise from the top) has its centre at `cx + R*sin(a), cy - R*cos(a)` with `a = n*360/N`. Its `at` is that point minus half its size, rounded to 4. Equal angles; uneven spacing stops the ring reading as one cycle.
24
+ - Numbers that work for five or six stations: stations 160x64, hub 200x104, R=240, centre 520,372 (top station's top edge at y=100, under the title). Six stations are then at 440,100 · 648,220 · 648,460 · 440,580 · 232,460 · 232,220. For seven or eight stations the neighbours would touch: take R=280, centre 520,408. In general `cy = R + 132`.
25
+ - The hub is the strongest element: a `rect` with `fill=accent/0.12 stroke=accent sw=1.5 title.color=ink sub.color=muted`, a little larger than a station, centred on `cx,cy`. One name and one short line (its `sub=` is small type, so keep it under about 24 characters); it is a state, not a step.
26
+ - At most one station is `focal`: the gate or decision the loop turns on. All others are `node`.
27
+
28
+ ## Arrows
29
+
30
+ - The ring is one arrow per neighbouring pair, clockwise, the last one back to the first. Each is `route=curve bend=N` with a positive N, which bows it outward. Never mix in elbows or straight pieces: the gaps must read as parts of one circle.
31
+ - Each arrow starts and ends where the circle crosses a box edge, so give both ends exactly. Which edge: at angle `a` the circle runs in direction `(cos a, sin a)`. A station is left through its right edge (left edge if `cos a` is negative) when `80*|sin a| < 32*|cos a|`, otherwise through its bottom edge (top edge if `sin a` is negative). It is entered through the same test on the reversed direction: top edge where it leaves through the bottom, bottom where it leaves through the top, right edge where it leaves through the left, and so on. Six stations: leave right, bottom, bottom, left, top, top; enter top, top, right, bottom, bottom, left.
32
+ - On a left or right edge at x=e the crossing is at `y = cy ± sqrt(R² - (e - cx)²)`; on a top or bottom edge at y=e it is at `x = cx ± sqrt(R² - (e - cy)²)`. Take the minus on a left or right edge above the centre, the plus below it; on a top or bottom edge the plus on the right of the centre, the minus on the left. Write them as `box.right@146` or `box.top@705` (absolute coordinates).
33
+ - `bend` is how far the circle rises above the straight line between the two ends: `R - sqrt(R² - (d/2)²)`, where d is the distance between the two attach points. For six stations: 9 for the four slanted gaps, 16 for the two vertical ones on the sides.
34
+ - The six attach points, clockwise: `capture.right@146 → research.top@705`, `research.bottom@743 → decide.top@743`, `decide.bottom@705 → act.right@598`, `act.left@598 → measure.bottom@335`, `measure.top@297 → learn.bottom@297`, `learn.top@335 → capture.left@146`.
35
+ - Write-backs run from each station straight towards the hub: `style=return stroke=soft` (dashed and lighter than the ring). A solid write-back looks like part of the flow. A station directly above or below the hub: `a.bottom -> hub.top` (or `a.top -> hub.bottom`). A station level with the hub (four or eight stations): `a.left -> hub.right`. The others need `route=straight` and both ends named: start 24px in from the station's corner nearest the hub (on its bottom edge for stations above the hub, top edge for stations below), end 4px in from the hub's nearest corner on the facing edge. Above: `research.bottom@672 -> hub.top@616`; below: `decide.top@672 -> hub.bottom@616`, `measure.top@368 -> hub.bottom@424`; upper left: `learn.bottom@368 -> hub.top@424`.
36
+ - Label two write-backs at most, one word each. The station's `sub=` usually says what is written.
37
+ - Nothing crosses the hub and no two lines cross. If a ring arrow would touch the hub, make R larger.
38
+
39
+ ## Text
40
+
41
+ Station name as the main text, what happens there as `sub=`. The title sits above the ring at y=52.
42
+
43
+ ## Legend
44
+
45
+ Usually none: one ring, one hub, one kind of dashed line. If you add one, `legend at 40,Y node="Step" focal="The gate" arrow="Work moves on" return="Writes to the hub"` with Y 24px under the lowest station.
@@ -0,0 +1,37 @@
1
+ # Medallion diagrams
2
+
3
+ Shows the tiers a dataset is stored in, from raw landing to curated marts to cold archive: what each tier holds, who writes it with what tool and format, and how data is promoted from one tier to the next. For the systems around the storage, draw a high-level diagram instead.
4
+
5
+ ## Composition
6
+
7
+ - Each tier is a `table`: the tier name is its header, and its rows are the same facts in the same order for every tier, so the reader can compare across.
8
+
9
+ ```
10
+ agg: table "Aggregated" at 736,176 208x0 stroke=accent fill=accent/0.08
11
+ | "Bucket" "analytics-marts"
12
+ | "Tool" "Trino INSERT"
13
+ | "Format" "Iceberg · metrics"
14
+ | "Writer" "Data Scientist"
15
+ | ---
16
+ | "Holds" "daily conversion rate"
17
+ | "" "revenue by channel"
18
+ ```
19
+
20
+ - Title at 40,52 (`style=h1`). Three to five tiers in one row, left to right in the order data is promoted. All tops at y=176, all 208 wide, 24 apart: `x = 40 + 232*n` for tier n from 0. The tiers end at `x = 16 + 232*tiers`: 712 for three, 944 for four, 1176 for five.
21
+ - Keep every value to 21 characters or fewer. A longer cell makes that table wider than the 208 you gave and it runs into its neighbour (`check` reports the overlap).
22
+ - Always end with a "Holds" block under a `| ---` line: two concrete examples of what is in the tier. Without it the diagram is abstract.
23
+ - One tier, the one consumers query, is the focus: `stroke=accent fill=accent/0.08` on its table. An archive or retention tier is dashed and greyed: `dash=4,3 fill=ink/0.05`. No other tier is styled.
24
+ - A table is 32 high for its header plus 24 per row (the `| ---` line adds none): four facts and two "Holds" rows make 32 + 6*24 = 176, so the tiers end at y=352. Tiers with the same row count end together.
25
+ - Optional row of one or two wide boxes under the tiers, 48px below their bottom edge (y=400 for the table above), 64 high, for the ways data is written between tiers: `cloud "Trino INSERT INTO … SELECT" sub="filter · join · aggregate" tag="SQL" at 40,400 WxH`. For m boxes the width is `(T - 24*(m-1)) / m`, where T = `232*tiers - 24` is the width of the tier row: 440 each for two under four tiers. They describe methods, not tiers.
26
+
27
+ ## Arrows
28
+
29
+ - A promotion is an arc over the top, from the top of one tier to the top of the next: `raw.top@0.65 -> anon.top@0.35 "mask ids" route=curve`. Give every arc its own points: leave at `@0.65` of the tier it starts from and arrive at `@0.35` of the next A middle tier then has its arriving arc left of centre and its leaving arc right of it, and they do not pinch together. The first tier may leave and the last arrive at `@0.5`.
30
+ - The arcs rise about 70px and the label sits above the arc, so the tiers start at y=176 with the title at y=52 above them.
31
+ - Labels are one verb or two short words, 14 characters at most: "aggregate", not "calculate and summarize".
32
+ - The promotion into the focal tier uses `style=primary`. A move done by a retention or lifecycle rule uses `style=return`. The rest are plain arrows.
33
+ - Promotions only go left to right, to the next tier. If data flows back, this is the wrong kind of diagram.
34
+
35
+ ## Legend
36
+
37
+ `legend at 40,Y` 24px under the lowest element (y=488 under the method boxes, 376 under the tiers): `swatch.accent/0.1=` for the focal tier (its tint matches the table; `focal=` would show a solid swatch), `optional=` for the archive tier, `arrow=`, `primary=`, `return=`, and `cloud=` if you drew method boxes.
@@ -0,0 +1,36 @@
1
+ # Nested diagrams
2
+
3
+ Shows hierarchy by containment: each ring sits inside a broader one. Use it for scopes, trust boundaries, folders inside folders, how far a failure spreads.
4
+
5
+ ## Composition
6
+
7
+ - Title at `40,52` (`style=h1`). The outermost ring starts at y=96.
8
+ - Three to five levels: n outer rings (`zone`) and one innermost box. With more, the inner ones become too small to read.
9
+ - The outermost ring is `W` wide: 920 for four rings, 760 for three, 600 for two, so the innermost box does not turn into a wide empty bar. Its height is `H = 72n + 92`: 308 for three rings, 380 for four.
10
+ - Ring i (from 0) is inset from the one around it by 32px left and right and 36px top and bottom: `at 40+32i, 96+36i` and size `(W-64i) x (H-72i)`. The innermost box is the same step again: `at 40+32n, 96+36n`, size `(W-64n) x 92`. Uneven insets look like a mistake.
11
+ - Rings are `zone` shapes without text, written outermost first. Write `dash=none` on each ring so every outline is solid, whatever the look does with zones. The innermost level is a `focal` box with `radius=8`: it is the subject and holds the only centred text (main text and `sub=`).
12
+ - The outline gets stronger and the fill a little darker with each step inward, so the eye is drawn to the middle. Override the zone's colours ring by ring (four rings, n=4, W=920):
13
+
14
+ ```
15
+ l1: zone at 40,96 920x380 dash=none stroke=ink/0.30 sw=1 fill=ink/0.015
16
+ l2: zone at 72,132 856x308 dash=none stroke=ink/0.35 sw=1 fill=ink/0.02
17
+ l3: zone at 104,168 792x236 dash=none stroke=ink/0.45 sw=1 fill=ink/0.025
18
+ l4: zone at 136,204 728x164 dash=none stroke=muted sw=1 fill=ink/0.03
19
+ core: focal "Project guidance" sub="inherits every level above" at 168,240 664x92 radius=8
20
+ ```
21
+
22
+ - The accent appears on the innermost box only.
23
+
24
+ ## Text
25
+
26
+ - Name every ring at its top-left corner with free text, not with the zone's own caption (that one is centred, and centred names stack up in a column): `text "/business" at 120,190 style=eyebrow`. x is the ring's left edge plus 16; the baseline is the ring's top edge plus 22, which puts the name in the strip between this ring and the next. Ring names stay in `muted` (the default); the innermost level is named by its own box.
27
+ - For names that must keep their case (paths, identifiers) add `caps=0`.
28
+ - Never put free text over the focal box. If you must, give it a colour that reads on the focal fill; `fastdraw check` warns when it does not.
29
+ - Rings hold nothing but their name and the next ring. Items that are not levels of the hierarchy belong in another diagram.
30
+
31
+ ## Callouts and lines
32
+
33
+ - A nested diagram has no arrows. Containment is the relationship.
34
+ - At most two short remarks in `style=note`, outside the rings: one above the top-right corner (baseline y=84, `anchor=end` at the ring's right edge), one under the bottom-left (baseline 32px under the outer ring).
35
+ - A remark may point at the level it is about with one faint curved line ending in a dot: `820,88 -- core.top@560 style=lifeline route=curve head=dot`.
36
+ - A legend is not needed when every ring is named. Leave it out.
@@ -0,0 +1,48 @@
1
+ # Org charts
2
+
3
+ Shows who owns what: people, teams or agents, whom they report to, and how to reach them. For a hierarchy of things rather than owners, use the tree guide.
4
+
5
+ ## Composition
6
+
7
+ - Build it like a tree (see `fastdraw guide tree`): leaves placed first, each parent centred over its own reports. Title at `40,52` (`style=h1`). Rows are 148px apart: top row y=104, middle row y=252, bottom row y=400. Write `WxH` on every box.
8
+ - Top row: the one owner or front door that takes work nobody else claims. It is the only `focal` box. Make it wide enough for its `sub=` (200 to 224 wide, 48 tall).
9
+ - Middle row: teams, pods or queues, as `node` boxes 160x48.
10
+ - Bottom row: the people or agents who do the work, as `cloud` boxes 136x56, 24px apart.
11
+ - An owner that is planned, vacant or not reachable yet is drawn with `optional` (dashed), in its place in the chart. Do not leave it out and do not draw it as if it were live: the gaps are what readers look for.
12
+ - Limits: 12 boxes, four rows, five reports under one parent. Count boxes, not heads: when the people are not the point, the bottom row holds squads or teams (one `cloud` box each, head count in `sub=`: "4 engineers"). If a parent has more reports, add a grouping row or split the chart.
13
+
14
+ ## Text
15
+
16
+ - Main text is the name of the person, role or team.
17
+ - `sub=` (small sans) is how to reach them or what they cover: a handle, a queue, or two to four words of scope. Not a job description.
18
+ - Name each row at the left margin with an eyebrow text, and separate the rows with rule lines 28px under each row of boxes (`--`):
19
+
20
+ ```
21
+ text "Command center" at 40,96 style=eyebrow // 8px above the first row's top edge
22
+ 40,180 -- 1000,180 style=rule // 28px under the row's boxes
23
+ text "Workstreams" at 40,204 style=eyebrow // 24px under the rule
24
+ 40,328 -- 1000,328 style=rule
25
+ text "Specialists" at 40,352 style=eyebrow
26
+ ```
27
+
28
+ The row name sits above the left end of its row. Keep every bus and drop line at least 8px away from it.
29
+
30
+ ## Reporting lines
31
+
32
+ - Same construction as a tree: plain lines with square corners, no labels, no arrowheads. Write `--` with `style=relation`, and give every report the same start point on the parent: `athena.bottom@0.5 -- growth.top style=relation`. The bus draws itself half-way between the rows.
33
+ - A parent with one report gets a single straight line: `content.bottom -- rory.top style=relation`. Centre them on each other.
34
+ - Centre every parent over its reports (the mean of its first and last report's centre x), or its line jogs.
35
+
36
+ ## Rules that are not reporting lines
37
+
38
+ Escalation paths, approval rules and known gaps are not boxes in the hierarchy. Put them in one strip under the chart, as wide as the bottom row, 32px below it:
39
+
40
+ ```
41
+ gaps: optional "Setup gaps stay visible" sub="approval gates · name mismatches" at 52,488 936x48
42
+ ```
43
+
44
+ Two such strips at most.
45
+
46
+ ## Legend
47
+
48
+ One `legend at 40,Y` statement 32px under the last strip (Y=568), with an entry for each box style used. Say what dashed means.
package/guide/polar.md ADDED
@@ -0,0 +1,57 @@
1
+ # Polar charts
2
+
3
+ Shows one number for each of four to twelve categories whose order runs in a circle: hours of the day, days of the week, months, compass directions. Each category is a ray from the centre; its length is the value.
4
+
5
+ FastDraw has no polar element. Rings are `ellipse`s, rays are plain lines with a small ring on the end.
6
+
7
+ ## Building blocks
8
+
9
+ ```
10
+ // title at y=52. Centre 500,300, radius 160 = 100, so 1.6px per point. Eight categories, the first straight up, then clockwise.
11
+ title: text "Request demand by UTC window" at 40,52 style=h1
12
+ text "% of daily peak · 0 to 100" at 40,74 style=caption
13
+ ellipse at 436,236 128x128 fill=none stroke=ink/0.1 sw=1 overlap=ok mask=0 // ring at 40: at = centre - r, size = 2r
14
+ ellipse at 340,140 320x320 fill=none stroke=ink/0.25 sw=1 overlap=ok mask=0 // outer ring, 100
15
+
16
+ 500,300 -- 613,187 stroke=ink/0.14 sw=1 // spoke of the second category, to the outer ring
17
+ 500,300 -- 520,280 stroke=muted sw=1.5 // its ray: value 18
18
+ ellipse at 516,276 8x8 fill=paper stroke=muted sw=1.5 overlap=ok // the end of the ray, minus 4
19
+ text "03–06" at 627,175 size=11 weight=600 color=ink // 20px beyond the outer ring
20
+ text "18" at 627,188 style=small color=muted // the value, 13px below the name
21
+ legend at 40,520 dot.accent="12–15 UTC · the daily peak" dot.muted="Other windows" title="Distance from the centre = demand"
22
+ ```
23
+
24
+ ## Working out the points
25
+
26
+ A value `v` in category `i` ends at `centre + v * px per point * direction of i`. For N categories the direction of `i` (first up, clockwise) is `sin(360° * i / N), -cos(360° * i / N)`; round to whole px. Common ones:
27
+
28
+ | Categories | Directions |
29
+ |---|---|
30
+ | 4 | 0,-1 · 1,0 · 0,1 · -1,0 |
31
+ | 6 | 0,-1 · 0.866,-0.5 · 0.866,0.5 · 0,1 · -0.866,0.5 · -0.866,-0.5 |
32
+ | 8 | 0,-1 · 0.707,-0.707 · 1,0 · 0.707,0.707 · 0,1 · -0.707,0.707 · -1,0 · -0.707,-0.707 |
33
+ | 12 | every 30°: 0,-1 · 0.5,-0.866 · 0.866,-0.5 · 1,0 · 0.866,0.5 · 0.5,0.866 · 0,1, then the same mirrored to the left |
34
+
35
+ ## Composition
36
+
37
+ - Centre 500,300, radius 160, legend at y=520. The top label (name baseline 110) clears the title; the bottom one ends near y=502, so the legend cannot go higher.
38
+ - Four to twelve categories, in their natural order. Twelve still reads (the spokes are 30° apart); with more, group them. Do not sort by value: the circle is the order. If the order does not wrap around, use a bar chart; it is easier to read.
39
+ - One number per category. The scale starts at 0 in the centre and every ray uses it.
40
+ - Five rings at equal steps of the scale: the inner four `stroke=ink/0.1`, the outer `ink/0.25`. They need `overlap=ok mask=0`.
41
+ - Each category has a faint spoke to the outer ring and, on top of it, its ray to the value. Both start at the centre; write the spoke first. Spokes and rays are written with `--`.
42
+ - A missing value is not zero. Leave the ray out and write "no data" in place of the value.
43
+
44
+ ## Colour
45
+
46
+ - All rays `stroke=muted sw=1.5` with an 8x8 end ring (`fill=paper stroke=muted`).
47
+ - One category may be the subject: `stroke=accent sw=2`, a 10x10 end ring, name and value in `color=accent`.
48
+
49
+ ## Text
50
+
51
+ - Name and value sit outside the outer ring. Take `P = spoke end + 20 * direction`. If the direction's x is above 0.3, the text starts at `P.x`; below -0.3, `anchor=end` at `P.x`; otherwise `anchor=middle` at `P.x`. Baselines: on the sides (and diagonals) name at `P.y + 2`, value 13px below it; at the top name at `P.y - 10`, value at `P.y + 3`; at the bottom name at `P.y + 8`, value at `P.y + 22`.
52
+ - Scale numbers (`20`, `40` ...) go beside the first spoke: `small` text, size 8, `color=soft`, right-aligned 6px left of it, level with each ring. Leave out the outermost one; the first category's name sits there. Write them after the rays. The last category's ray runs just left of the first spoke and crosses a number when it is long and close (twelve categories, a high last value): then move the numbers to the spoke of a category whose neighbours are short, or leave them out and say the rings in the unit line ("rings every 20").
53
+ - Title and unit: the `h1` title, then the unit under it in `caption` (`text ... at 40,74 style=caption`): there is no axis to hang them on.
54
+
55
+ ## Legend
56
+
57
+ `legend at 40,520 dot.accent="12–15 UTC · the daily peak" dot.muted="Other windows" title="Distance from the centre = demand"`. The heading says what length means.
@@ -0,0 +1,41 @@
1
+ # Process diagrams
2
+
3
+ Shows a business process that passes between several teams: who does each step, what goes into the step and what comes out, and with which tool. Rows are the actors, columns are the steps in order. If what goes in and out and the tools do not matter, a plain swimlane is enough; if there is one actor, draw a flowchart.
4
+
5
+ ## Composition
6
+
7
+ - Columns: one per step, 152px apart. The first column centre is x=248; the left 128px (x=40 to 168) holds the lane names. The lanes run from x=40 to 64px past the last column centre: lane width W = 272 + (steps − 1) × 152.
8
+ - Title: `text "..." at 40,52 style=h1`. Step header above each column: a numbered chip, `ellipse "1" at cx-12,96 24x24 fill=ink/0.08 stroke=none title.size=9`, and under it `text "Order" at cx,136 style=eyebrow anchor=middle`. One word per step.
9
+ - Lanes: one per actor, 96px high, across the full width, the first starting at y=148 (lane i at 148 + 96 * i). Tint every second lane (the first, third, ...) with `zone at 40,y WxH radius=0 stroke=none` (no text), W as above. Draw a `style=rule` line (written with `--`) on every lane border and one vertical line at x=168 (`168,148 -- 168,<bottom> stroke=ink/0.2 sw=1`) to close off the names. Lane name: `text "Customer" at 104,<lane top + 51> style=eyebrow anchor=middle`.
10
+ - A box goes where an actor does a step: 128x72, centred on the column, 12px below the top of the lane. A cell where nothing happens stays empty: no box, no dash.
11
+ - Order the lanes so that the process moves down the page as it moves right, and neighbours in the process are neighbours on the page where possible.
12
+ - Six lanes and twelve steps at most. More: an overview diagram and a detail diagram.
13
+
14
+ ## A box
15
+
16
+ `sub=` holds one line only, and this kind needs three, so leave the box's own text empty and write the lines as text, centred on the column:
17
+
18
+ ```
19
+ alloc: focal tag="WHS" at 488,352 128x72
20
+ text "Allocate stock" at 552,388 weight=600 anchor=middle // what is done: box top + 36
21
+ text "order → pick list" at 552,403 style=caption anchor=middle // in → out: box top + 51
22
+ text "inventory system" at 552,415 style=caption anchor=middle color=soft // tool: box top + 63
23
+ ```
24
+
25
+ `tag=` is a three or four letter code for the actor (CUS, SUP, WHS): its first letters, or the usual short name; a lane called "Platform team" is PLAT. It lets a box say whose it is when quoted alone. The second and third lines are `style=caption`, the same sans as a box's own `sub=`, with the tool line in `color=soft`. Text on a `focal` box keeps the default ink on a pale fill, as above; only on a solid accent fill (a look that draws `focal` that way) does it need `color=#ffffff`. `fastdraw check` warns when text cannot be read. Keep the name under 17 characters and the other lines under 20.
26
+
27
+ ## Arrows
28
+
29
+ - To a box in another lane: out of the right side, one bend, into the top (target below) or the bottom (target above): `place.right -> verify.top`. Never into the left side of a box in another lane, never diagonal.
30
+ - To the next box in the same lane: `pick -> pack`, a short straight arrow.
31
+ - No labels. The step number and the lane already say what happens. Label an arrow only when it is not a step (a retry, an escalation).
32
+ - An arrow may run through empty cells, never through a box. If two arrows would cross, reorder the lanes.
33
+ - Something that only triggers a step (a schedule, a manual override) uses `style=return`.
34
+
35
+ ## Emphasis
36
+
37
+ One step is the one the process turns on. Its box is `focal`, its header chip and name are accent (`fill=accent/0.16 title.color=accent` on the chip, `color=accent` on the name), and the arrows into and out of it use `style=primary`. Nothing else.
38
+
39
+ ## Legend
40
+
41
+ `legend at 40,Y node="A step, in the lane of who does it" focal="..." primary="Critical handoff" arrow="Handoff"`, 24px under the last lane (Y = 148 + 96 * lanes + 24).
@@ -0,0 +1,46 @@
1
+ # Pyramids and funnels
2
+
3
+ Shows a ranking as stacked layers that narrow. A pyramid points up: a broad base carries a small, rare top. A funnel points down: a wide intake shrinks to the few that come out. Use one or the other, never both in one diagram.
4
+
5
+ Each layer is a `polygon`: a trapezoid with four corners, measured from its `at` position. Title at `40,52` (`style=h1`) with an optional `caption` at `40,74`; the apex's top is y=96.
6
+
7
+ ## Building blocks
8
+
9
+ ```
10
+ // pyramid, centre x=500: each layer is 64 high and 64 narrower on each side than the one below
11
+ l3: polygon "Essays" sub="weekly · 800–1,500 words" at 244,288 points=64,0;448,0;512,64;0,64 fill=ink/0.05 stroke=ink/0.12 sw=1
12
+ l4: polygon "Short posts" sub="daily · ~200 words" at 180,352 points=64,0;576,0;640,64;0,64 fill=ink/0.05 stroke=ink/0.12 sw=1
13
+ apex: polygon at 372,96 points=128,0;256,128;0,128 fill=accent/0.08 stroke=accent sw=1
14
+ text "Flagship book" at 500,192 anchor=middle weight=600 color=ink
15
+
16
+ // funnel: the top edge of a layer is as wide as its count, the bottom edge as wide as the next count
17
+ f1: polygon "Visitors" sub="10,000" at 200,96 points=0,0;600,0;480,64;120,64 fill=ink/0.05 stroke=ink/0.12 sw=1
18
+ ```
19
+
20
+ ## Composition
21
+
22
+ - Four to six layers. With seven or more, merge neighbours or split the diagram.
23
+ - All layers have the same height, 56 to 72px, and share one centre x. Each sits exactly on the one below: its bottom edge equals the top edge of the next.
24
+ - Pyramid: the sides are two straight lines from the base corners to the tip, so every layer loses the same width on each side (its height, for 45° sides). With n layers in all (apex included) the base is `128(n+1)` wide: 640 for four, giving three trapezoids and a triangle 128 high on top. The apex's top is y=96, layer k (from the apex, k=1..n-1) has its top edge at `y = 224 + 64(k-1)`, and the base is at `96 + 128 + 64(n-1)` = 416 for four.
25
+ - Funnel with real numbers: pick a scale (say 600px for the largest count) and make every edge that wide. Uneven drops then show as uneven steps. Do not smooth them into a straight side. The last layer is a plain rectangle of its own width, at least 48px so its name fits.
26
+ - Leave 180px free on each side of the widest layer for side notes and an axis.
27
+ - Fill every plain layer the same (`fill=ink/0.05 stroke=ink/0.12`). One layer takes the accent (`fill=accent/0.08 stroke=accent`): the tip of a pyramid, the outcome of a funnel, or the step where most is lost. Never the base.
28
+ - Write the accent layer last in the file. Shapes are drawn in file order, and a neighbour written after it would cover the shared edge.
29
+
30
+ ## Text
31
+
32
+ - The layer's name is its main text and a short detail is `sub=`. Both are centred in the layer.
33
+ - A triangle is the exception: text is centred in the triangle's box, which puts it up in the narrow part. Leave the triangle without text and place the name and detail yourself, with baselines 32px and 16px above its bottom edge.
34
+ - A name must be narrower than the top edge of its layer (the bottom edge in a funnel). If it is not, widen the whole figure.
35
+ - Side notes (a count, a drop such as "−40%") are `small` text level with the middle of the layer, starting 24px right of that layer's widest corner. Keep them outside the layer's bounding box or `check` reports an overlap.
36
+ - An arrow up the left side shows what the order means: `100,416 -> 100,104 stroke=ink/0.3 sw=1` (foot at the base's y, tip 8px under the apex's top). Label its two ends along the line with rotated `eyebrow` text, which reads upwards and may be two words; keep each under about 150px:
37
+ `text "Common, high volume" at 84,416 style=eyebrow rotate=-90` (starts at the foot) and `text "Rare, high leverage" at 84,104 style=eyebrow rotate=-90 anchor=end` (ends at the tip). The 180px margin is never crossed.
38
+
39
+ ## Legend
40
+
41
+ The layers are not styles of the look, but `legend` takes swatches: `legend at 40,464 swatch.accent/0.1="Apex: rarest" swatch.ink/0.1="Supporting layer"` (24px under the note that sits 32px under the base). If the widths follow real numbers, say so in the title's `caption` line.
42
+
43
+ ## Traps
44
+
45
+ - A pyramid claims that each layer rests on the one below. If the items are only a list or a set of sizes, use a bar chart.
46
+ - Equal steps for unequal numbers mislead. Either use the real widths or say nowhere that width means quantity.