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/bar.md ADDED
@@ -0,0 +1,61 @@
1
+ # Bar charts
2
+
3
+ Compares one number per category: velocity per sprint, revenue per month. The dumbbell variant compares two numbers per category and shows the gap between them.
4
+
5
+ ## Building blocks
6
+
7
+ ```
8
+ // title at 40,52; plot area 96,112 to 960,404
9
+ text "Velocity per sprint" at 40,52 style=h1
10
+ vel: chart at 96,112 864x292 x="S1,S2,S3,S4,S5" y=0..120 step=20 labels=1 key=0 ytitle="Story points per sprint"
11
+ | bars "Velocity" 72 88 95 78 110 fill=soft fill.5=accent
12
+ legend at 40,456 swatch.accent="Sprint 5 · record high" swatch.soft="Other sprints"
13
+ ```
14
+
15
+ - The `chart` element draws axes, grid, tick labels, bars and values. Never work out bar heights yourself.
16
+ - A series has one colour; one bar of it takes its own with its position from 1: `fill=soft fill.5=accent` (the fifth bar). Do not make a second series for it: that needs `stack=1` and `_` gaps to keep the bars centred.
17
+
18
+ ## Composition
19
+
20
+ - Title at 40,52 (`style=h1`). Plot area `at 96,112 864x292`: that leaves room for the axis title above the plot (it sits about 28px over the top edge), tick labels on the left, category names below (to y=432) and the legend at y=456.
21
+ - Four to eight bars. With more, group them into longer periods or draw two charts.
22
+ - The y axis starts at 0. Always write `y=0..N` with N a round number just above the largest value; a cut axis makes small differences look large.
23
+ - `step=` gives four to six grid lines.
24
+ - `labels=1` writes each value over its bar. Name the unit once with `ytitle=` (it is drawn above the top-left corner of the plot); do not repeat it in every label.
25
+ - Category names are short (`S1`, `Q3`, `Mar`). Names longer than about 12 characters collide: shorten them, or use the dumbbell layout below, which has room for names on the left.
26
+ - Keep the default bar width (`bar.width=0.64`). The gap must stay narrower than the bar.
27
+
28
+ ## Focus
29
+
30
+ - One bar takes `fill=accent`: the one the chart is about. Every other bar is `fill=soft`.
31
+ - Two series compared across categories: two `bars` rows without `stack=1`, the main one `fill=accent`, the other `fill=soft`. No more than two.
32
+ - Stacked parts of a total: `stack=1`, the part that matters in accent and the rest in `soft`, `muted`, `ink`. `labels=1` then labels every segment; three segments per bar at most.
33
+
34
+ ## Dumbbell
35
+
36
+ Two dots per row on one horizontal scale, joined by a line: before and after, target and actual. The chart element has no horizontal bars, so use it with a numeric x axis and put each row at a height of your choosing:
37
+
38
+ ```
39
+ // 5 rows: y runs 0..n for n rows, and row i (from the top, from 0) sits at y = n - 0.5 - i
40
+ // plot top 104, 320 high: row i is centred at 104 + 320 * (i + 0.5) / n
41
+ db: chart at 200,104 760x320 x=0..100 xstep=20 xunit="%" y=0..5 step=10 yaxis=0 grid=both key=0 xtitle="Builds passing first time"
42
+ | line 34,4.5 71,4.5 stroke=ink/0.55 sw=1 // one connector per row, written before the dots
43
+ | line 52,3.5 80,3.5 stroke=ink/0.55 sw=1
44
+ | dots "2024" 34,4.5 52,3.5 fill=muted r=5
45
+ | dots "2025" 71,4.5 80,3.5 fill=accent r=6
46
+ text "Platform" at 188,140 anchor=end size=11 weight=600 color=ink // baseline = row centre (136) + 4
47
+ text "34" at 446,139 anchor=end style=small color=muted // x of value v = 200 + 760 * v / 100, then 12px outside the dot; baseline = centre + 3
48
+ text "71" at 752,139 style=small color=muted
49
+ legend at 40,484 dot.muted="2024" dot.accent="2025" title="Rows ordered by 2025 value"
50
+ ```
51
+
52
+ - `step=10` (larger than the y range) and `yaxis=0` remove the horizontal grid and the row axis numbers; `grid=both` draws the vertical lines.
53
+ - Title at 40,52. Leave 200px on the left for row names, right-aligned 12px before the plot, baseline 4px below the row centre. The legend goes 24px under the axis title (y=484 here). With fewer than five rows keep `y=0..n` and shrink the plot height (64px per row) so it does not end in empty space.
54
+ - Four to eight rows, 48 to 88px apart. Sort them and say by what in the legend heading.
55
+ - The scale starts at 0, as for bars. Write both values beside each pair, outside it: the smaller one right-aligned 12px left of the left dot, the larger 12px right of the right dot. A value at 0 would land on the row name; write it above its dot instead.
56
+ - The accent marks the same end on every row (the newer or the actual value). Do not also highlight one row.
57
+ - Two dots only. With three per row the line means nothing.
58
+
59
+ ## Legend
60
+
61
+ One `legend` statement with `swatch.COLOUR=` entries (bars) or `dot.COLOUR=` entries (dumbbell), 24px under the category names (y=456 for the bar layout above). Use plain colour names in bar fills (`soft`, not `soft/0.4`) so the legend swatch matches the bars.
@@ -0,0 +1,42 @@
1
+ # Data flow diagrams
2
+
3
+ Shows a data pipeline as a grid: steps run left to right, roles are bands from top to bottom, and each box says who does what at which step and what kind of data goes in and comes out. For a business process with no typed data, draw a swimlane instead.
4
+
5
+ FastDraw has no lane or chip elements. Build them from `zone`, `rect` and `text` as below.
6
+
7
+ ## Composition
8
+
9
+ - Limits: 4 roles and 6 steps. More than that is two diagrams.
10
+ - Title: `text "..." at 40,52 style=h1`. Columns: the first 168px (x 40 to 208) hold the role names. Step n (from 0) has its box at `x = 224 + 172*n`, 144 wide, so boxes in one lane are 28px apart and the column centre is `296 + 172*n`. For s steps the lanes are `172*(s+1)` wide (five steps: 1032; six: 1204).
11
+ - Step headers sit above the lanes, centred on the column: a pill `rect "01" at cx-20,88 40x20 radius=10 fill=ink/0.08 stroke=none`, and the step name under it as `text "Ingest" at cx,124 style=eyebrow anchor=middle`.
12
+ - Lanes: one `zone at 40,Y 1032x120 radius=0 stroke=none` per role (the built-in zone is dashed), with no text, touching each other, the first at y=136 (lane i at 136 + 120*i). Alternate `fill=ink/0.03` and `fill=ink/0.015` so the bands can be told apart. Use `zone`, not `rect`: a rect counts as a box and every arrow and label on it is reported.
13
+ - Role name: `text "Data\nengineer" at 124,Y+58 style=eyebrow anchor=middle` (two lines), and one `208,136 -- 208,BOTTOM style=rule` to close the name column.
14
+ - Boxes: 144x88 at lane top + 16. Main text is the action ("Clean & Model"), `sub=` the tool, `tag=` a three-letter code for the role.
15
+ - A role that does nothing at a step gets nothing in that cell. No placeholder box.
16
+ - Read left to right and downwards: each hand-off goes to the next column, in the same lane or a lower one.
17
+
18
+ ## Data-type chips
19
+
20
+ Each box carries two chips: bottom-left is what comes in, bottom-right is what goes out. A source has no left chip and a sink no right one.
21
+
22
+ ```
23
+ rect "DB" at X+8,Y+68 28x12 radius=3 fill=#5e7a9b stroke=none title.color=#ffffff title.size=7 overlap=ok
24
+ rect "TB" at X+108,Y+68 28x12 radius=3 fill=#b8915a stroke=none title.color=#ffffff title.size=7 overlap=ok
25
+ ```
26
+
27
+ (X,Y is the box's `at`; the chips do not clash with `sub=` on one line.) Use one two-letter code and one quiet colour per kind of data, four kinds at most, and never the accent. `overlap=ok` is needed because the chip sits on its box.
28
+
29
+ ## Arrows
30
+
31
+ - Same lane: `a -> b`, a short straight arrow with no label.
32
+ - Into a lower lane: `a.right -> b.top`. It runs along the lane and drops into the next column with one bend.
33
+ - Exactly one arrow is the hand-off the diagram is about, usually where the data changes role. It gets `style=primary` and the only arrow label, the payload ("raw table").
34
+ - An arrow that leaves the pipeline for its consumers uses `style=link`.
35
+
36
+ ## Focus
37
+
38
+ One box (the one that receives the primary arrow) uses `focal`. Its step header takes the accent too: `fill=accent/0.18` on the pill and `color=accent` on the name. Nothing else is accented, and no lane is tinted in a colour.
39
+
40
+ ## Legend
41
+
42
+ `legend at 40,Y` 24px under the last lane (Y = 136 + 120 * roles + 24), for the box and arrow styles. The chips need their own row, built by hand because the legend cannot draw hex colours: `text "Data type" at 40,Y+78 style=eyebrow`, then for each kind the same chip rect (without `overlap=ok`) at y = Y+68, starting x=120 and about 130px apart, and its name as `text ... style=caption` at chip x+36, baseline Y+78; at the end the caption "left chip = what comes in · right chip = what goes out".
@@ -0,0 +1,46 @@
1
+ # Database schema diagrams
2
+
3
+ Shows real tables: column names, SQL types, constraints, the indexes that matter, and foreign keys drawn from the referencing column to the column it references. Use it to review a migration or what a delete does. For what the entities mean, draw an ER diagram instead.
4
+
5
+ ## Building blocks
6
+
7
+ ```
8
+ billing: zone "billing" at 40,96 256x148 title.align=left // a schema other than the default
9
+
10
+ orders: table "public.orders" at 392,152 296x0
11
+ | id "id" "PK" "uuid"
12
+ | customer_id "customer_id" "FK NN" "uuid"
13
+ | "total" "NN" "numeric(12,2)"
14
+ |= "Indexes"
15
+ | "idx_orders_status"
16
+
17
+ items.order_id.right -> orders.id.right "cascade" style=primary
18
+ inv.order_id -> orders.id "restrict"
19
+ ```
20
+
21
+ - Title at 40,52 (`style=h1`); the first table or zone at y=96 or lower. A table is a `table` named `schema.table`. Each row has three quoted cells: column name, constraints (`PK`, `FK`, `UQ`, `NN`, separated by a space), SQL type. Never leave the type out. A column with no constraint takes an empty cell `""`: `| "published_at" "" "timestamptz"`. Leaving it out slides the type into the constraints column.
22
+ - The row id is the unquoted first word of the line, before the cells (`| customer_id "customer_id" "FK NN" "uuid"`), and it is optional: a row without one starts straight with its first quoted cell. Give an id to every column a foreign key starts or ends on, and to no other.
23
+ - Indexes go under a `|= "Indexes"` row, one name per row. List only the ones the diagram is about.
24
+ - Eight columns per table at most. If you leave columns out, say so in a last row: `| "+ 3 more columns"`.
25
+ - The look has no table or key style: the built-in `table` is the plain table, `arrow` a foreign key.
26
+
27
+ ## Composition
28
+
29
+ - Five tables and six foreign keys at most. Beyond that, show one subsystem and say so in the title.
30
+ - The table most keys point at goes in the middle column. Tables that reference it or that it references go left and right, 112px or more away.
31
+ - A row's centre is at `table y + 44 + 24 * n`. Set each neighbour's y so that the foreign-key row and the row it references are level; the key is then a straight line. Do this for as many keys as you can.
32
+ - Widths: the three columns need about 224px for short names. A one-cell row (an index name, the "more columns" line) widens the first column for the whole table, so a table with a 22-character index name needs 296. `check` tells you when a width is too small; fix the width, then re-place the neighbours.
33
+ - A key between two tables in the same column loops out on one side: name the side on both ends, `items.order_id.right -> orders.id.right`. Send it to the side with fewer lines, and leave 64px between the two tables.
34
+ - Plan the sides so no two keys cross. A key that leaves a row lower in its table should go to a table lower in the drawing.
35
+ - Tables of another schema sit inside a `zone` named after the schema: 16px of padding, 32px at the top. Height = the table's height + 44; the table is at zone x + 16, zone y + 32.
36
+
37
+ ## Arrows
38
+
39
+ - The arrow points from the foreign-key column to the referenced column.
40
+ - The label is the ON DELETE action in one word: "restrict", "cascade", "set null". Every key has one.
41
+ - One key, the delete that destroys rows (cascade), takes `style=primary`, and the table whose rows are destroyed takes `stroke=accent fill=accent/0.08`. If no key cascades, nothing is accented.
42
+ - You may say what that key means in one `note` in free space ("Deleting an order deletes its items."), one `text` statement per line, 20px apart.
43
+
44
+ ## Legend
45
+
46
+ `legend at 40,Y node="Table" focal="Rows deleted with their parent" zone="Schema other than public" arrow="Foreign key · label = ON DELETE" primary="Destructive delete"`, 24px under the lowest table. Keep each entry short or the last one wraps.
@@ -0,0 +1,38 @@
1
+ # Dependency graphs
2
+
3
+ Shows what depends on what among packages, modules or services. Draw it when the data has something a tree cannot show: a box that several others depend on, or a cycle. If every box has one parent and nothing points back, draw a tree.
4
+
5
+ ## Composition
6
+
7
+ - Rank the boxes first. Rank 0 is what nothing depends on (the apps); a box sits one rank below the lowest thing that depends on it. Four ranks at most, nine boxes at most, fourteen arrows at most. Over that, fold a group of leaves into one box named "+6 leaves".
8
+ - Ranks are rows, rank 0 on top (first row at y=96, under the title `text "..." at 40,52 style=h1`): boxes `160x64` (write the size on every box; the default is 144x64), rows 144px apart (80px of free space between rows, for bends). Name each row at the left margin: `text "Rank 0" at 40,<row y + 36> style=eyebrow`.
9
+ - Columns: three, 240px apart (x = 180, 420, 660). A box goes in the column of the thing it mostly depends on or is depended on by, so that as many arrows as possible are straight vertical lines. Leave a cell empty rather than force a bend; a straight arrow may pass through an empty cell.
10
+ - The box that most others depend on goes in the middle column, with the boxes that use it on both sides above it. That box is `focal`.
11
+ - One box per package or service, never per file. `sub=` is its path (`packages/ui-kit`) or, for a third-party one, version and registry (`v3.23 · npm`). `tag=` is its kind (APP, SVC, PKG, EXT).
12
+ - Styles: `node` for your own, `cloud` for third party, `focal` for the most used. Nothing else: a box that depends on nothing is shown by sitting on the lowest rank, not by a style (`store` means data, and many looks draw it as a cylinder).
13
+ - Icons are optional here; `icon=` on the kind (`pod` or `service` for SVC, `bucket` for PKG, `cloud` for EXT) only if every box gets one.
14
+ - Every box shows how many depend on it, in its top-right corner, including "0 in" on the apps: `rect "4 in" at <box right − 36>,<box top + 8> 28x12 radius=2 fill=none stroke=ink/0.4 sw=0.8 title.font=mono title.size=8 title.weight=400 overlap=ok`. These counts are why the diagram exists; do not leave them out. `overlap=ok` is needed because the chip sits on its box. On the `focal` box keep the same chip with `stroke=accent/0.5`; only in a look that fills `focal` with solid accent is an outlined chip unreadable, and there write the count as plain text instead: `text "4 in" at <box right − 22>,<box top + 17> style=small size=8 color=#ffffff anchor=middle`.
15
+
16
+ ## Arrows
17
+
18
+ An arrow points from the dependent to what it depends on: downward, or sideways within a rank. Never upward, except the one cycle.
19
+
20
+ Do not let FastDraw choose the sides here. With several arrows on one side it spreads them, and a straight arrow gets a kink. Name the side and the x of every end:
21
+
22
+ ```
23
+ web.bottom@260 -> api.top@260 // straight: same x at both ends
24
+ web.bottom@300 -> uikit.top@680 via=300,188;680,188 // bend at y=188
25
+ admin.bottom@700 -> api.top@300 via=700,212;300,212 // crosses it; bends at y=212, 24px lower
26
+ ```
27
+
28
+ - The straight arrow uses the centre of the box. A bent one leaves 40px to the side of the centre, on the side it is heading for, and arrives 40 to 60px from the centre of its target.
29
+ - Two bent arrows in the same gap between rows bend at different heights, at least 24px apart, unless their horizontal parts do not share any x. Two arrows may cross once at a right angle; they may never run along each other. No two ends within 20px of each other on one side.
30
+ - No labels on ordinary arrows. The direction is the meaning.
31
+
32
+ ## The cycle
33
+
34
+ Show one cycle at most, the one that matters. Draw its back arrow with `style=primary` and label it: `utils.top@540 -> shared.bottom@540 "cycle" style=primary`. When the two boxes are stacked, run it beside the forward arrow, 40px to its right. Otherwise take it round the outside of the graph with `via=`, never between other boxes. With `focal` on the most-used box, that is both uses of the accent.
35
+
36
+ ## Legend
37
+
38
+ One `legend at 40,Y` 24px under the last row (the box bottom + 24 = 616): each box style used, `arrow="Depends on"`, `primary="Closes a cycle"`.
@@ -0,0 +1,46 @@
1
+ # Deployment diagrams
2
+
3
+ Shows where software runs: which host or managed service, in which environment or network, in how many copies and at which version. An architecture diagram says what talks to what; this one says what is installed where. If you have no boundary, no copy count and no version to show, draw an architecture diagram.
4
+
5
+ ## Three levels
6
+
7
+ ```
8
+ text "Checkout service, production" at 40,52 style=h1
9
+
10
+ // 1. zone: a real boundary (an environment, a network, a region), never just a visual group
11
+ prod: zone "Prod / eu-west-1" at 40,96 232x304 dash=4,4 stroke=ink/0.2
12
+
13
+ // 2. host: a box with a type tag and no text of its own; icon and name sit as separate items
14
+ app: node tag="POD" at 56,268 200x116
15
+ icon at 68,296 20x20 icon=container // what kind of thing it is
16
+ text "app" at 96,311 weight=600 // name: host top + 43
17
+ rect "x3" at 220,276 28x12 radius=2 fill=none stroke=ink/0.4 sw=0.8 title.font=mono title.size=8 title.weight=400 overlap=ok
18
+
19
+ // 3. chip: one per thing installed on the host, with its version
20
+ rect at 64,320 184x24 radius=4 fill=paper stroke=ink/0.25 overlap=ok
21
+ text "checkout-api" at 72,336
22
+ text "v2.4.1" at 240,336 style=small anchor=end
23
+ ```
24
+
25
+ - Host: 200 wide. Height 84 with one chip, plus 32 for each further chip. `tag=` is the kind of host (POD, VM, CDN, MANAGED). Leave the host's own text empty, or it is centred on top of the chips.
26
+ - Icon: `icon=` names from `fastdraw sizes` (container, server, vm, database, bucket, gateway, cdn), a 20x20 `icon` shape at host x+12, top+28, one per host or none. The name starts at host x+40, baseline top+43. On a `focal` host the name keeps the default ink on a pale fill (the built-in look); give it `color=#ffffff` only when the look fills `focal` with solid accent. `fastdraw check` warns when text cannot be read.
27
+ - Chip: a `rect`, never `store` (that means data, and many looks draw it as a cylinder). 8px in from the host's sides, 24 high; the first starts 52px below the host's top, the next 32px lower. Name at chip x+8, version right-aligned at chip right−8, both with baseline 16px below the chip's top. Every chip has a version: the version is why it is drawn. `fill=paper` also reads on a `focal` host.
28
+ - Copies: one host with a badge in its top-right corner, not one box per copy: the `rect "x3"` above, at hostright−36,hosttop+8. It needs `overlap=ok`.
29
+ - Host styles: `node` for your own hosts, `cloud` for a hosted platform (managed databases and buckets too), `focal` for the one that matters (the single point of failure, or the new piece). Do not use `store` for a host: it means data, and in looks that draw it as a cylinder its tag is half hidden by the top.
30
+
31
+ ## Composition
32
+
33
+ - Title at 40,52; zones start at y=96. Zones stand side by side in the order traffic passes through them, 80px apart (x = 40, 352, 664: 312 each), tops level. A zone is 16px larger than its hosts on the sides and bottom and 32px at the top for its name (hosts start at y=128). A zone with one host is shorter than its neighbours; that is fine.
34
+ - Hosts in a zone stack vertically, at least 56px apart. Choose which goes on top so that each path between zones is a straight horizontal line: the two hosts it joins sit level (same centre y).
35
+ - Three zones, six hosts, nine chips, eight paths at most. More: one diagram per environment. Never two environments in one diagram without a zone between them.
36
+
37
+ ## Paths
38
+
39
+ - Every path carries protocol and port as its label: `"HTTPS:443"`, `"TLS:5432"`.
40
+ - A path that crosses a zone border uses `style=link`; a path inside a zone is the default arrow; replication or anything asynchronous uses `style=return`.
41
+ - A path between neighbouring zones: put its label in the gap between the two zones with `lpos=<middle of the gap>,<line y − 10>`, so it does not sit on a zone border.
42
+ - A path that must pass a zone it does not touch (zone 1 to zone 3) goes under the zones: leave the bottom of the hosts, run it 24px below the lowest zone and come up into the bottom of the target: `app.bottom@120 -> bucket.bottom@780 "S3:443" style=return via=120,424;780,424 lpos=450,440`. `@` is an absolute x here, and must lie within the host's width. The label goes under the line.
43
+
44
+ ## Legend
45
+
46
+ One `legend at 40,Y` 24px under the lowest path (or zone), with each host style and each path style used. Say what the focal host is ("Single point of failure").
package/guide/er.md ADDED
@@ -0,0 +1,49 @@
1
+ # ER diagrams
2
+
3
+ Shows the things a domain is made of (entities), the fields that matter, and how many of one belong to how many of another. Use it for a conceptual or logical model. For real tables with SQL types, constraints and ON DELETE rules, draw a db-schema diagram instead.
4
+
5
+ ## Building blocks
6
+
7
+ ```
8
+ author: table "Author" at 40,152 216x0
9
+ | id "# id" "uuid"
10
+ | "handle" "text"
11
+
12
+ article: table "Article" at 376,128 248x0 stroke=accent fill=accent/0.08
13
+ | id "# id" "uuid"
14
+ | author "→ author_id" "uuid"
15
+ | "title" "text"
16
+
17
+ author.id -- article.author "writes" style=arrow tail=only-one head=many
18
+ ```
19
+
20
+ - An entity is a `table`: the entity name is the header, each row is a field name and its type. Start a primary key with `# ` and a foreign key with `→ `.
21
+ - Give a row id only to rows a relationship ends on.
22
+ - The look has no entity or relationship style. The built-in `table` is the plain entity. The one entity the model is built around takes `stroke=accent fill=accent/0.08`. A join entity (it exists only to link two others) takes `dash=4,3 stroke=muted fill=ink/0.05`.
23
+
24
+ ## Composition
25
+
26
+ - Title at 40,52 (`style=h1`); tables start at y=112 or lower. Three to six entities in columns 200 to 248 wide with 104 to 120px between columns, so a relationship has room for both end marks and a label. If one entity joins the rest (a hub), put it in the middle with the others around it. If the model is a chain (A to B to C to D), lay it out left to right in one row, the accent on the entity the model is about wherever it falls; six in a chain go in two rows of three, the second row running back under the first.
27
+ - Give every table a width (`216x0`); the height follows the rows. Do not pad entities to the same height.
28
+ - A row's centre is at `table y + 44 + 24 * n` (n = 0 for the first row). Place the tables so the two rows of every relationship are at the same y: that line is then straight. Going along a chain, each next table's y is the previous one's plus 24 times (its key row number minus the previous table's foreign-key row number): a 4-entity chain steps down 24 or 48 each time, as a staircase. Putting a foreign key right under the primary key makes this easy.
29
+ - Six to eight fields per entity at most. Leave out fields that say nothing about the model (timestamps, flags).
30
+ - Two relationships must not leave the same row on the same side (their lines jog onto each other): move one to another row or end it on the top or bottom edge (`a.bottom -- b.top`).
31
+ - With more than about six relationships, do not draw them all: group related entities close together and draw only the ones the diagram is about.
32
+
33
+ ## Relationships
34
+
35
+ - Always write `style=arrow` on a relationship. A bare `--` is a straight line and comes out diagonal between rows at different heights; with `style=arrow` it turns at right angles.
36
+ - Cardinality is drawn by the end marks, not written as text: `tail=` is the mark at the first end, `head=` at the second. `only-one` (exactly one), `zero-one`, `many`, `one-many`, `zero-many`. Mark both ends of every relationship, in the same notation throughout.
37
+ - Between entities side by side, end on the key rows: `author.id -- article.author`. Between entities stacked in one column, join the boxes: `tag.bottom -- atag.top`, with at least 56px between them for the two marks.
38
+ - A label is one verb ("writes", "tagged"). Leave it out when the field names already say it.
39
+
40
+ ## Legend
41
+
42
+ `legend at 40,Y 360x0 focal="Aggregate root" node="Entity" optional="Join entity"`, 24px under the lowest table. The `node` swatch stands for the plain table. Give the legend a width (360 holds three entries; add 120 for each more) so the entries stay on the left. The statement cannot show key prefixes or end marks, so add them by hand to its right, from `x = 40 + legend width + 40`, on the entries' line (text baseline Y+40, the line sample at Y+37); each next x is the last text's x plus `6 * its characters + 24`:
43
+
44
+ ```
45
+ text "#" at 440,452 style=small color=ink
46
+ text "Primary key" at 452,452 style=caption
47
+ 560,449 -- 608,449 style=arrow tail=only-one head=many
48
+ text "Exactly one to many" at 620,452 style=caption
49
+ ```
@@ -0,0 +1,53 @@
1
+ # Exploded views
2
+
3
+ Shows the parts of one object pulled apart along one axis, drawn as solid plates seen from above at an angle, each named at the side. Use it when the parts are physical or stack like physical things (a device, a package, the tiers of a product). No arrows: position along the axis is the only relation. For rows of text about abstract levels use `layers`.
4
+
5
+ FastDraw has no 3D. A plate is four `rect`s with the same `at` and size, each with its own outline (`shape=path`): the silhouette, the two side faces, and the rim line.
6
+
7
+ ## Building blocks
8
+
9
+ ```
10
+ // title at y=52. One plate: a square slab with rounded corners, 384 wide and 208 high on screen (16 of that is its thickness).
11
+ // This is the bottom one of three: y = 96 + 116 * 2
12
+ title: text "What the thermostat is made of" at 40,52 style=h1
13
+ data: rect at 208,328 384x208 fill=card stroke=ink sw=1.2 overlap=ok shape=path
14
+ path="M0,0.462 Q0.003,0.442 0.013,0.433 L0.469,0.029 Q0.5,0 0.531,0.029 L0.987,0.433 Q0.997,0.442 1,0.462 L1,0.538 Q0.997,0.558 0.987,0.567 L0.531,0.971 Q0.5,1 0.469,0.971 L0.013,0.567 Q0.003,0.558 0,0.538 Z"
15
+ rect at 208,328 384x208 fill=ink/0.07 stroke=none overlap=ok mask=0 shape=path // left face, lit
16
+ path="M0,0.462 Q0.003,0.481 0.013,0.49 L0.469,0.894 Q0.484,0.909 0.5,0.909 L0.5,0.986 Q0.484,0.986 0.469,0.971 L0.013,0.567 Q0.003,0.558 0,0.538 Z"
17
+ rect at 208,328 384x208 fill=ink/0.15 stroke=none overlap=ok mask=0 shape=path // right face, in shade
18
+ path="M1,0.462 Q0.997,0.481 0.987,0.49 L0.531,0.894 Q0.516,0.909 0.5,0.909 L0.5,0.986 Q0.516,0.986 0.531,0.971 L0.987,0.567 Q0.997,0.558 1,0.538 Z"
19
+ rect at 208,328 384x208 fill=none stroke=ink/0.55 sw=0.8 overlap=ok mask=0 shape=path // rim of the top face
20
+ path="M0,0.462 Q0.003,0.481 0.013,0.49 L0.469,0.894 Q0.5,0.923 0.531,0.894 L0.987,0.49 Q0.997,0.481 1,0.462"
21
+
22
+ ellipse at 590,430 4x4 fill=ink stroke=none overlap=ok // dot on the right corner, mid-thickness: y + 102
23
+ 598,432 -- 644,432 stroke=ink/0.4 sw=0.8 // leader: y + 104
24
+ text "Data" at 656,431 size=16 weight=600 color=ink // y + 103
25
+ text "postgres, object store" at 656,447 style=small size=10 // y + 119
26
+ ```
27
+
28
+ Copy the four paths as they are. They are fractions of the box, so the same four serve every plate; only `at` changes.
29
+
30
+ ## Composition
31
+
32
+ - Two to five parts. Write them bottom part first: shapes are drawn in file order and each plate must cover the one below it.
33
+ - All plates share one x and one size, and sit one above the other with the same step of 116px (with 384x208 plates the gap shows about half of each lower plate's top). Never shrink one gap to fit; let the stack grow taller or drop a part. The top plate is at y=96 (under the title); the plate `k` from the top (0 is the top) is at `y = 96 + 116 * k`. Three parts: 96, 212, 328; four: 96, 212, 328, 444.
34
+ - Plates at x=208 so that plates plus labels (which end near x=800) sit centred on x=500.
35
+ - For a smaller or larger plate give another size with the same proportions (288x156) and scale the 116 step and the offsets below with it. A size with other proportions distorts the angle and the thickness.
36
+ - Always keep the two face tints. A plate with only an outline can be read two ways.
37
+ - One part at most is the focus: `stroke=accent` on its silhouette, a second silhouette rect over it with `fill=accent/0.1 stroke=none mask=0`, faces `accent/0.1` and `accent/0.22`, rim `stroke=accent/0.7`. Do not fade the other parts.
38
+ - Two dashed lines tie the stack together, from the bottom plate's left and right corners up to the top plate: `208,424 -- 208,208 stroke=ink/0.3 sw=0.8 dash=4,3 layer=back` and the same at x=592 (x = plate left and plate right; y from the bottom plate's `y + 96` to the top plate's `y + 112`; here three parts, 424 and 208). Plain lines are written with `--`.
39
+
40
+ ## Text
41
+
42
+ - One label per part, all in one column 64px right of the plates (x=656). With `y` the plate's top: the name (`size=16 weight=600`, one or two words) with its baseline at `y + 103`, and a detail line at `y + 119` in `small size=10`.
43
+ - The leader is level with the middle of the plate's side (`y + 104`): a 4x4 dot at `590,y+102` (centred on the right corner), then a line from `598,y+104` to `644,y+104`. Leaders are level, never bent, and never cross a plate.
44
+ - The focal part's dot, leader and detail line take the accent; its name stays ink.
45
+ - No text on the plates, no numbers with a key.
46
+
47
+ ## Legend
48
+
49
+ None. A one-line `caption` at the bottom, at `y = bottom plate y + 256` (with a short `eyebrow` lead such as "Focal layer" at x=208, the caption from x=312), may say why the accent part matters.
50
+
51
+ ## Limits
52
+
53
+ Only this one plate shape is given here. A part with another footprint (a long board, a cylinder) or details on its top face needs its own paths, worked out point by point with the projection in `axonometric-plan`; keep to plain plates unless the subject demands more.
@@ -0,0 +1,44 @@
1
+ # Fishbone diagrams
2
+
3
+ Shows the causes that were looked into for one observed effect, grouped by category, with the confirmed root cause marked. It is the picture of an investigation, not of a sequence: if the causes happened one after another, draw a timeline.
4
+
5
+ FastDraw has no fishbone elements. You draw the spine, the slanted bones and the ticks as lines at exact coordinates. All of them follow from two numbers: the spine's height `CY` and the x where each bone joins it.
6
+
7
+ ## Composition
8
+
9
+ - Title: `text "..." at 40,52 style=h1`. The spine is at CY=300 (the bones' category boxes then start at y=104).
10
+ - With n bones (five at most), the effect box's x is `EX = 160*n + 240` (four bones: EX=880). This keeps the leftmost cause text clear of the left margin and the left side from standing empty.
11
+ - The effect is a `focal` box at the right end, 200x88, vertically centred on the spine (`at EX,256`), with `tag="EFFECT"` and the observation on two lines. It says what was seen ("Checkout p99 latency\n4x for 90 minutes"), never the fix.
12
+ - Bones join the spine every 160px, the first 80px left of the effect box: join k (from 0) is at x = EX − 80 − 160k. They alternate: first above, second below, and so on.
13
+ - The spine starts 80px left of the leftmost join and runs into the effect: `SX,CY -> effect.left stroke=ink`, with SX = EX − 160n (240 for four bones).
14
+ - Every bone leans the same way, 96px left for 168px up or down. Its outer end is a category box 120x28, centred on that end:
15
+
16
+ ```
17
+ deploy: rect "DEPLOY" at 644,104 120x28 radius=4 fill=paper stroke=ink sw=0.8 // above: x = join − 156, y = CY − 196
18
+ deploy.bottom -- 800,300 sw=1.2 stroke=ink
19
+ data: focal "DATA" at 484,468 120x28 radius=4 // below: y = CY + 168
20
+ data.top -- 640,300 sw=1.2 stroke=accent
21
+ ```
22
+
23
+ - Causes hang off the bone as 32px ticks pointing left, with the words left of the tick. For step `m` along the bone (m=2 and m=4 for two causes, m=3 for one, m=1, 3, 5 for three), the tick starts on the bone at `x = join − 16·m`, `y = CY ∓ 28·m` (minus above, plus below):
24
+
25
+ ```
26
+ 768,244 -- 736,244 sw=1 // m=2 on the bone that joins at 800, above
27
+ text "canary skipped" at 732,247 style=small anchor=end // 4px left of the tick, 3px below its y
28
+ ```
29
+
30
+ - A cause may be up to 32 characters. On the leftmost bone it must still start right of x=40: shorten it if it does not.
31
+
32
+ ## Limits
33
+
34
+ - Three causes per bone at most. A bone with none is a placeholder: delete it.
35
+ - Name categories from the investigation. Do not paste a standard list and leave parts empty.
36
+ - A cause must say more than its category ("config drift", not "deploy problem").
37
+
38
+ ## Emphasis
39
+
40
+ The accent is used on two things: the effect box, and the one bone that is the confirmed root cause (its line `stroke=accent`, its category box `focal`). Two confirmed causes means two diagrams.
41
+
42
+ ## Legend
43
+
44
+ One `legend` statement at y=524 (24px under the lower category boxes), because the lines here are not styles of the look: `legend at 40,524 line.ink="Category of cause" line.accent="Confirmed root cause" line.muted="Cause looked into" focal="What was observed"`.
@@ -0,0 +1,22 @@
1
+ # Flowcharts
2
+
3
+ Shows a decision process: steps, yes/no questions, outcomes.
4
+
5
+ ## Composition
6
+
7
+ - The main path runs straight down the centre of the drawing. Every shape on it shares the same centre x.
8
+ - Shape carries meaning: a rounded terminal for start and end, a rectangle for an action, a diamond for a question. Use the look's styles for these.
9
+ - Each question has one answer that continues down the spine and one that branches sideways to an outcome placed level with the diamond (same centre y). Put all side outcomes in one column, on the same side.
10
+ - Vertical gaps: 24–32px between a step and the next shape; 40px below a diamond, so the answer label has room.
11
+ - Horizontal gap from a diamond's tip to a side outcome: about 120px, so the answer label sits on a clear stretch of line.
12
+ - Question text goes on two short lines (`"Reusable across\nprojects?"`). Keep it under 16 characters per line so it fits the diamond.
13
+ - The outcome the chart is really about gets the accent style, and the arrow into it gets the primary arrow style. Nothing else does.
14
+
15
+ ## Arrows
16
+
17
+ - Label only the answers leaving a diamond (YES, NO). Do not label plain step-to-step arrows.
18
+ - Arrows on the spine are straight vertical lines; branches are straight horizontal lines. If one isn't straight, the shapes aren't lined up: fix the positions, not the route.
19
+
20
+ ## Legend
21
+
22
+ One `legend at 40,Y` statement under the chart, explaining the shape meanings (start/end, step, decision) and the arrow kinds used.
package/guide/gantt.md ADDED
@@ -0,0 +1,48 @@
1
+ # Gantt charts
2
+
3
+ Shows a plan: tasks as bars against a time axis, grouped into phases, so the reader sees what overlaps and what comes after what.
4
+
5
+ FastDraw has no Gantt element. You build one from zones, plain rects, lines and text.
6
+
7
+ ## Building blocks
8
+
9
+ ```
10
+ text "Product launch plan" at 40,52 style=h1
11
+ // time: week 1 starts at x=232, 64px per week, 12 weeks (ends at 1000)
12
+ p1: zone "Discovery" at 40,136 1000x96 title.align=left dash=none stroke=ink/0.1 // a phase, behind its rows
13
+
14
+ zone at 296,124 1x356 fill=ink/0.06 stroke=none radius=0 // a week line
15
+ zone at 488,92 1x388 fill=ink/0.16 stroke=none radius=0 // a month boundary
16
+
17
+ text "April" at 360,108 size=9 weight=600 color=ink anchor=middle
18
+ text "W1" at 264,120 style=small size=8 color=soft anchor=middle
19
+ 232,124 -- 1000,124 stroke=ink/0.2 sw=0.8 // under the header
20
+ 232,92 -- 232,480 stroke=ink/0.2 sw=0.8 // after the name column
21
+
22
+ text "Market research" at 56,176 size=10 weight=600 color=ink
23
+ t1: rect at 232,160 128x24 radius=4 fill=muted/0.15 stroke=muted // weeks 1 and 2
24
+ ```
25
+
26
+ ## Composition
27
+
28
+ - Fix the scale first and write it in a comment: the x where time starts and the px per unit. A bar starts at `start + (first unit - 1) * pitch` and is `units * pitch` wide. Pick a pitch that is a multiple of 4 (64px per week). The phase zones are at x=40 with width = start + n * pitch - 40, so they end where the scale ends.
29
+ - Names are in a column on the left, x=56 to 232, on the zones' inner side. Time runs from x=232 to the right.
30
+ - Rows are 40px apart. A bar is 24px high. The task name's baseline is 16px below the top of its bar.
31
+ - A phase is a `zone` across the full width with `title.align=left`; write `dash=none stroke=ink/0.1` (the built-in zone is dashed). Its first bar starts 24px below the zone's top and the zone ends 8px below its last bar: height = 40 * rows + 16. The first zone starts at y=136; each next one 8px below the previous.
32
+ - Header, under the title: the larger unit (months) as names centred over their span at y=108, the smaller unit (weeks) as tiny labels centred in each column at y=120, then a line at y=124. Without the unit named, the chart cannot be read.
33
+ - Draw the vertical grid as zones 1px wide, not as lines (or as lines with `layer=back`). A plain line that runs behind a bar makes `check` report "passes through"; a zone is drawn behind everything and is not reported. Write them after the phase zones. Week lines run from y=124 to the bottom of the last phase; boundaries of the larger unit are darker and start at y=92.
34
+ - A "today" marker is one more 1px zone with `fill=accent/0.6` starting at y=92, with a small label above it at y=86.
35
+ - Twelve tasks at most, and no more than five running at once in one phase. For a bigger plan, draw one bar per phase and put the detail in a second diagram.
36
+
37
+ ## Focus
38
+
39
+ - One bar is the task everything depends on: `fill=accent/0.12 stroke=accent`, with its name in `color=accent`. All other bars look alike.
40
+ - A word on a bar (`GATE`) is `small` text centred on it, `anchor=middle`, baseline 16px below the bar top. Do not write dates on bars; the axis carries them.
41
+
42
+ ## Arrows
43
+
44
+ None, as a rule. Bar positions already show order. Add a dependency arrow only where one task cannot start before another ends and the reader would not guess it, and no more than three. Leave the bottom of the earlier bar 16px before its end and enter the left side of the later bar: `t4.bottom@632 -> t5.left`. Do not write `t4.right -> t5.left`: when one bar ends where the next begins, the two points have the same x and nothing is drawn.
45
+
46
+ ## Legend
47
+
48
+ The bars are not styles of the look, so use tinted swatches, 24px under the last phase: `legend at 40,Y swatch.accent/0.2="The gate" swatch.muted/0.2="Task" swatch.ink/0.06="Phase"` (add `line.accent="Today"` if there is a marker).