fastdraw 0.1.1 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +75 -143
- package/agents/AGENTS-snippet.md +5 -0
- package/agents/README.md +8 -0
- package/agents/claude-skill/fastdraw/SKILL.md +8 -3
- package/dist/cli.js +12423 -290
- package/dist-embed/embed/draw-CFzc4XD7.js +1070 -0
- package/dist-embed/embed/iconSetAll-6ydegXby.js +1 -0
- package/dist-embed/embed.js +35 -0
- package/dist-embed/fonts/Geist-Bold.ttf +0 -0
- package/dist-embed/fonts/Geist-Medium.ttf +0 -0
- package/dist-embed/fonts/Geist-Regular.ttf +0 -0
- package/dist-embed/fonts/Geist-SemiBold.ttf +0 -0
- package/dist-embed/fonts/GeistMono-Medium.ttf +0 -0
- package/dist-embed/fonts/GeistMono-Regular.ttf +0 -0
- package/dist-embed/fonts/InstrumentSerif-Italic.ttf +0 -0
- package/dist-embed/fonts/InstrumentSerif-Regular.ttf +0 -0
- package/dist-embed/fonts/LibreFranklin-Bold.ttf +0 -0
- package/dist-embed/fonts/LibreFranklin-Medium.ttf +0 -0
- package/dist-embed/fonts/LibreFranklin-Regular.ttf +0 -0
- package/dist-embed/fonts/LibreFranklin-SemiBold.ttf +0 -0
- package/dist-embed/fonts/Newsreader-Italic.ttf +0 -0
- package/dist-embed/fonts/Newsreader-Medium.ttf +0 -0
- package/dist-embed/fonts/Newsreader-Regular.ttf +0 -0
- package/dist-embed/fonts/Newsreader-SemiBold.ttf +0 -0
- package/dist-embed/fonts/SketchHand-Regular.ttf +0 -0
- package/fonts/Geist-Bold.ttf +0 -0
- package/fonts/Geist-Variable.woff2 +0 -0
- package/guide/guide.md +41 -8
- package/guide/look.md +41 -11
- package/guide/swimlane.md +61 -5
- package/licenses/phosphor-icons.txt +21 -0
- package/package.json +20 -13
package/README.md
CHANGED
|
@@ -1,42 +1,26 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
<img src="assets/fastdraw-icon.svg" alt="FastDraw" width="
|
|
3
|
+
<img src="assets/fastdraw-icon.svg" alt="FastDraw" width="80" height="80">
|
|
4
4
|
|
|
5
5
|
# FastDraw
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
the same file in a browser editor, changes anything on a free canvas, and the change is saved
|
|
11
|
-
back as a small edit to the text. Neither side has to redo the other's work.
|
|
12
|
-
|
|
13
|
-
[A first diagram](#a-first-diagram) · [Getting started](#getting-started) · [Commands](#the-command-line-tool) · [Agents](#using-it-with-an-agent) · [Editor](#the-editor) · [Looks](#looks) · [Gallery](#gallery)
|
|
14
|
-
|
|
15
|
-
<img src="assets/how-it-works.png" alt="An AI agent writes diagram.fdraw; a person edits the same file in the browser editor; a look file sets the styles" width="860">
|
|
7
|
+
[](https://www.npmjs.com/package/fastdraw)
|
|
8
|
+
[](https://github.com/coccor/fastdraw/actions/workflows/ci.yml)
|
|
9
|
+
[](LICENSE)
|
|
16
10
|
|
|
17
11
|
</div>
|
|
18
12
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
13
|
+
FastDraw is a diagram format and set of tools for diagrams that AI coding agents write and people
|
|
14
|
+
edit. A diagram is a `.fdraw` text file with one element per line and exact coordinates. The
|
|
15
|
+
`fastdraw` command checks the file and renders it to PNG or SVG. The browser editor at
|
|
16
|
+
[fastdraw.dev/edit](https://fastdraw.dev/edit/) opens the same file and saves changes back to it as
|
|
17
|
+
small text edits, so the file stays readable in a diff.
|
|
23
18
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
cross a box, labels that collide and text that does not fit, each with a line number.
|
|
28
|
-
- **Looks.** A `.look` file holds named styles, colours, fonts and icons, so a team decides once
|
|
29
|
-
how its diagrams are drawn. The same diagram can be drawn with another look.
|
|
30
|
-
- **A visual editor.** A static site with no server. It edits the same text file and keeps the
|
|
31
|
-
changes minimal, so diffs stay readable.
|
|
32
|
-
- **Guides for over forty kinds of diagram.** Architecture, flowchart, sequence, database schema,
|
|
33
|
-
Gantt, Sankey, swimlane and more. Each guide tells an agent how to compose that kind well.
|
|
34
|
-
- **Pictures you can reopen.** Exported PNG and SVG files carry the diagram and its look inside
|
|
35
|
-
them. Drop one on the editor to keep editing. The editor's Export dialog (Ctrl+Shift+E) picks
|
|
36
|
-
PNG or SVG, a scale from 1x to 4x, a see-through background, and whether the diagram goes
|
|
37
|
-
inside; it downloads the image or copies it to the clipboard.
|
|
19
|
+
<p align="center">
|
|
20
|
+
<img src="assets/how-it-works.png" alt="An AI agent writes diagram.fdraw; a person edits the same file in the browser editor; a look file sets the styles" width="760">
|
|
21
|
+
</p>
|
|
38
22
|
|
|
39
|
-
##
|
|
23
|
+
## Example
|
|
40
24
|
|
|
41
25
|
```
|
|
42
26
|
shopper: external "Shopper" at 40,60
|
|
@@ -50,145 +34,93 @@ legend at 40,172 external="Outside what you own" focal="The service this is abou
|
|
|
50
34
|
```
|
|
51
35
|
|
|
52
36
|
<p align="center">
|
|
53
|
-
<img src="assets/example.png" alt="The diagram drawn from the text above: Shopper, Orders API and Orders DB joined by two arrows, with a legend" width="
|
|
37
|
+
<img src="assets/example.png" alt="The diagram drawn from the text above: Shopper, Orders API and Orders DB joined by two arrows, with a legend" width="680">
|
|
54
38
|
</p>
|
|
55
39
|
|
|
56
|
-
|
|
57
|
-
|
|
40
|
+
There is no automatic layout: what the file says is what is drawn. `fastdraw check` reports
|
|
41
|
+
overlapping boxes, arrows that cross a box, colliding labels and text that does not fit, each with a
|
|
42
|
+
line number, so an agent can fix its own layout before anyone looks at it.
|
|
58
43
|
|
|
59
44
|
## Getting started
|
|
60
45
|
|
|
61
|
-
FastDraw needs Node 20 or later.
|
|
62
|
-
|
|
63
|
-
```
|
|
64
|
-
npx fastdraw setup # tell this repo's coding agents about FastDraw
|
|
65
|
-
npx fastdraw check docs/example.fdraw # report problems, with line numbers
|
|
66
|
-
npx fastdraw render docs/example.fdraw # write a PNG next to the file
|
|
67
|
-
npx fastdraw open docs/example.fdraw # edit it in the browser; changes save back
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
The editor is at https://fastdraw.dev/edit/. Agents that read the web can learn the language from
|
|
71
|
-
https://fastdraw.dev/llms.txt with no setup at all.
|
|
72
|
-
|
|
73
|
-
To work on FastDraw itself (needs Node 22.18 or later, because the sources run as TypeScript directly):
|
|
46
|
+
FastDraw needs Node 20 or later.
|
|
74
47
|
|
|
75
48
|
```
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
npm run dev # the website and editor, at http://localhost:5199
|
|
49
|
+
npx fastdraw setup # add FastDraw instructions for this repo's coding agents
|
|
50
|
+
npx fastdraw check docs/example.fdraw # report problems, with line numbers
|
|
51
|
+
npx fastdraw render docs/example.fdraw # write example.png next to the file
|
|
52
|
+
npx fastdraw open docs/example.fdraw # edit in the browser; changes save to the file
|
|
81
53
|
```
|
|
82
54
|
|
|
83
|
-
|
|
55
|
+
`fastdraw setup` supports Claude Code, Codex, OpenCode and GitHub Copilot. Chat assistants without a
|
|
56
|
+
shell can read the language from https://fastdraw.dev/llms.txt.
|
|
84
57
|
|
|
85
|
-
|
|
86
|
-
|---|---|
|
|
87
|
-
| `fastdraw check <file.fdraw>` | Report problems, with line numbers |
|
|
88
|
-
| `fastdraw render <file.fdraw> [-o out.png\|.svg] [--scale 2] [--transparent] [--no-embed]` | Draw the diagram (PNG by default). `--transparent` leaves out the page colour and dots; `--no-embed` leaves the diagram out of the image |
|
|
89
|
-
| `fastdraw guide [topic]` | Print the language guide, or the guide for one kind of diagram |
|
|
90
|
-
| `fastdraw guide list` | List the kinds of diagram that have a guide |
|
|
91
|
-
| `fastdraw sizes [file]` | List a look's styles and their sizes (the built-in look when no file is given) |
|
|
92
|
-
| `fastdraw icons [file.look] [word]` | List the icons a look offers, or search them by name or meaning (`email` finds `mail`) |
|
|
93
|
-
| `fastdraw init-look [path]` | Write the built-in look to a file, to start your own |
|
|
94
|
-
| `fastdraw preview-look [file.look]` | Draw every style of a look on one sheet |
|
|
95
|
-
| `fastdraw setup [claude\|agents\|copilot] [--global]` | Tell a repo's coding agents about FastDraw: a Claude Code skill, a section in `AGENTS.md`, or in Copilot's instructions. With no name, sets up the agents the repo already uses. Running it again updates them |
|
|
96
|
-
| `fastdraw open <file.fdraw> [--editor URL]` | Open the diagram in the web editor with its look, fonts and icons; edits there save back to the file. Runs until Ctrl-C |
|
|
58
|
+
### Updating
|
|
97
59
|
|
|
98
|
-
|
|
60
|
+
The instructions `setup` writes are short: they tell the agent to run `fastdraw guide`, and the guide,
|
|
61
|
+
the kinds of diagram, the looks, `check` and `render` all come from the fastdraw that runs. Through
|
|
62
|
+
`npx fastdraw` that is the newest release, so most of an update arrives by itself.
|
|
99
63
|
|
|
100
|
-
|
|
101
|
-
|
|
64
|
+
The instruction files themselves change only when `setup` runs again. Each one carries the version that
|
|
65
|
+
wrote it, and when it is older than the fastdraw running, `fastdraw guide` starts with a note asking the
|
|
66
|
+
agent to tell you. To update them, run this in the repository; it rewrites the skill and replaces only
|
|
67
|
+
FastDraw's own section of `AGENTS.md` or Copilot's instructions:
|
|
102
68
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
| GitHub Copilot | `npx fastdraw setup copilot` (adds a section to `.github/copilot-instructions.md`) |
|
|
108
|
-
| Chat assistants | Ask it to read https://fastdraw.dev/llms.txt first, or paste that file in; then paste the reply into the editor with "Paste diagram text" |
|
|
109
|
-
|
|
110
|
-
More detail is in [`agents/README.md`](agents/README.md).
|
|
111
|
-
|
|
112
|
-
## The editor
|
|
69
|
+
```
|
|
70
|
+
npx fastdraw@latest setup # or name them: setup claude agents copilot
|
|
71
|
+
npx fastdraw@latest setup claude --global # if you put the skill in ~/.claude
|
|
72
|
+
```
|
|
113
73
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
74
|
+
If fastdraw is installed on the PATH (`npm install -g fastdraw`), agents use that copy instead of `npx`.
|
|
75
|
+
`fastdraw guide` checks npm for a newer release at most once a day and says so when there is one; update
|
|
76
|
+
with `npm install -g fastdraw@latest`. Set `FASTDRAW_NO_UPDATE_CHECK=1` to turn the check off; it is off on CI.
|
|
117
77
|
|
|
118
|
-
|
|
119
|
-
agent and a person can work on the same diagram at the same time. Other browsers keep changes in
|
|
120
|
-
memory and download the result. Nothing is uploaded; there is no server.
|
|
78
|
+
## Features
|
|
121
79
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
`.
|
|
126
|
-
|
|
80
|
+
- **Checker.** Finds layout problems by measuring the drawn picture, not just parsing the text.
|
|
81
|
+
- **Editor.** Move, resize, restyle and add elements on a canvas. In Chrome and Edge it edits the
|
|
82
|
+
file in place while an agent works on it. Nothing is uploaded.
|
|
83
|
+
- **Looks.** A `.look` file holds named styles, colours, fonts and icons. Twelve ship with
|
|
84
|
+
FastDraw, including the built-in one, and a team can write its own.
|
|
85
|
+
- **Guides for over forty kinds of diagram**, including architecture, flowchart, sequence,
|
|
86
|
+
database schema, Gantt, Sankey and swimlane. Agents read them with `fastdraw guide`.
|
|
87
|
+
- **Exports that reopen.** PNG and SVG files carry the diagram source, so dropping one on the
|
|
88
|
+
editor opens it for editing.
|
|
89
|
+
- **Embedding.** Show a diagram as a live drawing on a docs site with `<fastdraw-diagram>`, or as
|
|
90
|
+
an SVG image in a GitHub README.
|
|
127
91
|
|
|
128
|
-
|
|
129
|
-
landing page at `/`, the editor at `/edit/`, and the guide for agents at `/llms.txt` and `/guide/<kind>.md`.
|
|
92
|
+
## Gallery
|
|
130
93
|
|
|
131
|
-
|
|
94
|
+
Written by agents from the guides alone and drawn in the built-in look; sources are in
|
|
95
|
+
[`examples/kinds/`](examples/kinds).
|
|
132
96
|
|
|
133
|
-
|
|
97
|
+
| | | |
|
|
98
|
+
|:---:|:---:|:---:|
|
|
99
|
+
| <img src="assets/gallery/deployment.png" alt="Deployment diagram of a checkout service across three zones" width="260"><br>Deployment | <img src="assets/gallery/db-schema.png" alt="Database schema with four tables and their foreign keys" width="260"><br>Database schema | <img src="assets/gallery/swimlane.png" alt="Swimlane diagram of publishing an article across four roles" width="260"><br>Swimlane |
|
|
134
100
|
|
|
135
|
-
|
|
136
|
-
bin/fastdraw init-look team.look
|
|
137
|
-
bin/fastdraw preview-look team.look
|
|
138
|
-
```
|
|
101
|
+
## Documentation
|
|
139
102
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
103
|
+
- [Command-line tool](docs/cli.md): every command and option, and setup for each coding agent
|
|
104
|
+
- [Editor](docs/editor.md): editing in the browser and `fastdraw open`
|
|
105
|
+
- [Looks](docs/looks.md): the bundled looks and writing your own
|
|
106
|
+
- [Showing diagrams on other sites](docs/embedding.md): `<fastdraw-diagram>` and GitHub images
|
|
107
|
+
- The language: `npx fastdraw guide`, or https://fastdraw.dev/llms.txt
|
|
144
108
|
|
|
145
|
-
|
|
109
|
+
FastDraw is at version 0.x, and details of the language may still change.
|
|
146
110
|
|
|
147
|
-
|
|
148
|
-
[`examples/kinds/`](examples/kinds); they are drawn here with `looks/reference.look`.
|
|
111
|
+
## Contributing
|
|
149
112
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
| <img src="compare/kinds/sankey.png" alt="Sankey diagram" width="270"><br>Sankey | <img src="compare/kinds/db-schema.png" alt="Database schema" width="270"><br>Database schema | <img src="compare/kinds/swimlane.png" alt="Swimlane diagram" width="270"><br>Swimlane |
|
|
153
|
-
| <img src="compare/kinds/uml-class.png" alt="UML class diagram" width="270"><br>UML class | <img src="compare/kinds/deployment.png" alt="Deployment diagram" width="270"><br>Deployment | <img src="compare/kinds/exploded.png" alt="Exploded layer diagram" width="270"><br>Exploded layers |
|
|
154
|
-
|
|
155
|
-
## Repository layout
|
|
156
|
-
|
|
157
|
-
| Path | What it is |
|
|
158
|
-
|---|---|
|
|
159
|
-
| `src/` | Core: parser, look loader, arrow router, SVG renderer, checker, text-edit operations |
|
|
160
|
-
| `src/cli.ts`, `bin/fastdraw` | The command-line tool |
|
|
161
|
-
| `guide/` | What an agent reads to learn the language and how to compose each kind of diagram |
|
|
162
|
-
| `src/defaultLook.ts` | The built-in look, used when a diagram names none |
|
|
163
|
-
| `agents/` | Thin instruction files that point coding agents at `fastdraw guide` |
|
|
164
|
-
| `looks/reference.look` | Test look that mirrors diagram-design's default palette, for quality comparison |
|
|
165
|
-
| `looks/whiteboard.look` | Whiteboard: an online-whiteboard look with pastel sticky notes, white rounded shapes, curved connectors and one blue accent. Samples in `examples/whiteboard/` |
|
|
166
|
-
| `looks/night.look` | Night: the built-in look after dark, on a deep navy page with the same styles, so a diagram can switch with one line |
|
|
167
|
-
| `looks/headline.look` | Headline: serif headline over flat newspaper-graphics blocks, one muted crimson accent. An alternative to the built-in look |
|
|
168
|
-
| `editor/` | The browser editor (Vite + React) |
|
|
169
|
-
| `examples/` | Diagrams written by agents from the guides, and looks used in tests |
|
|
170
|
-
| `compare/` | Renders next to the diagram-design originals, plus editor screenshots |
|
|
171
|
-
| `fonts/` | Geist, Geist Mono and Newsreader (the built-in look), Libre Franklin and Instrument Serif (SIL Open Font License, texts included) |
|
|
172
|
-
| `assets/` | The icon, and the diagrams shown on this page with their sources |
|
|
173
|
-
| `test/`, `e2e/` | Core tests and editor tests |
|
|
174
|
-
|
|
175
|
-
## Development
|
|
113
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for building from source, running the tests and the
|
|
114
|
+
repository layout.
|
|
176
115
|
|
|
177
|
-
|
|
178
|
-
npm test # core tests
|
|
179
|
-
npm run typecheck
|
|
180
|
-
npm run test:e2e # editor tests (Playwright)
|
|
181
|
-
npm run build:editor # static site in dist-editor/
|
|
182
|
-
```
|
|
116
|
+
## License
|
|
183
117
|
|
|
184
|
-
|
|
118
|
+
MIT. See [LICENSE](LICENSE).
|
|
185
119
|
|
|
186
|
-
The kinds of diagram FastDraw has guides for, and many of the composition ideas in
|
|
187
|
-
(how few elements to use, one accent, legends, what makes each kind read well), follow
|
|
120
|
+
The kinds of diagram FastDraw has guides for, and many of the composition ideas in them, follow
|
|
188
121
|
[diagram-design](https://github.com/cathrynlavery/diagram-design) by Cathryn Lavery (MIT licence,
|
|
189
|
-
copyright (c) 2025 Cathryn Lavery)
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
copyright (c) 2020-2024 Paweł Kuna), the same generic set diagram-design uses.
|
|
122
|
+
copyright (c) 2025 Cathryn Lavery); the guides are written anew for FastDraw's language, and
|
|
123
|
+
`looks/reference.look` and `compare/kinds/*-ref.png` mirror it for side-by-side comparison. The
|
|
124
|
+
bundled icons are [Phosphor Icons](https://phosphoricons.com) (MIT licence, copyright (c) 2023
|
|
125
|
+
Phosphor Icons); the licence is in `licenses/phosphor-icons.txt`. The fonts are under the SIL Open
|
|
126
|
+
Font License, with texts in `fonts/`.
|
package/agents/AGENTS-snippet.md
CHANGED
|
@@ -4,7 +4,12 @@
|
|
|
4
4
|
|
|
5
5
|
Diagrams in this repo are FastDraw files (`.fdraw`), drawn with the look in `.look` files. People edit them visually afterwards.
|
|
6
6
|
|
|
7
|
+
- Save a new diagram in `docs/diagrams/` unless the person names another place or the repo already keeps its `.fdraw` files somewhere; never at the top of the repo.
|
|
7
8
|
- Before writing or changing one, run `fastdraw guide` and follow it; it is the only reference for the language.
|
|
9
|
+
- Choose the kind of diagram by what the reader has to understand, not by a word in the request ("request flow" is not a flowchart); `fastdraw guide list` says what each kind shows. Unless the request names the kind, tell the person which kind you would draw and the closest other kind, and ask before drawing.
|
|
8
10
|
- Finish with `fastdraw check <file>` clean, then run `fastdraw render <file>` and look at the PNG.
|
|
11
|
+
- `fastdraw check <folder>` and `fastdraw render <folder>` work on every `.fdraw` file under a folder. `fastdraw render <file> --dark` also writes `<file>-dark.png` with the look's dark version, for sites with a dark theme; `--look <name|file.look>` draws with another look without changing the file.
|
|
12
|
+
- When the diagram is done, always ask the person what to do next: open it in fastdraw.dev (run `fastdraw open <file>` in the background, then give them the link it prints in case no browser window appeared; edits save back to the file), preview the PNG (open it in their image viewer), or nothing. Do not open anything before they choose.
|
|
13
|
+
- On a docs site (a web page, not a GitHub README), show a diagram with `<fastdraw-diagram src="....fdraw">` from https://fastdraw.dev/embed.js and keep the rendered PNG inside it as the fallback image; see "Embedding a diagram" in FastDraw's README.
|
|
9
14
|
- When changing an existing diagram, leave the position, size and styling of existing elements alone unless asked.
|
|
10
15
|
- If `fastdraw` is not on the PATH, run it as `npx fastdraw`.
|
package/agents/README.md
CHANGED
|
@@ -9,3 +9,11 @@ All three are thin pointers to `fastdraw guide`, so there is one place to mainta
|
|
|
9
9
|
| Codex, OpenCode | `npx fastdraw setup agents` | `AGENTS-snippet.md` as a section of `AGENTS.md` |
|
|
10
10
|
| GitHub Copilot | `npx fastdraw setup copilot` | `AGENTS-snippet.md` as a section of `.github/copilot-instructions.md` |
|
|
11
11
|
| Chat assistants | none | Ask it to read https://fastdraw.dev/llms.txt first (or paste that file in), then paste the reply into the editor with "Paste diagram text" |
|
|
12
|
+
|
|
13
|
+
## Diagrams on a docs site
|
|
14
|
+
|
|
15
|
+
A README on GitHub can only show the PNG from `fastdraw render`. A docs site (Starlight, Docusaurus,
|
|
16
|
+
VitePress, plain HTML) can show the `.fdraw` file itself with the `<fastdraw-diagram>` element from
|
|
17
|
+
https://fastdraw.dev/embed.js, keeping the PNG inside it for readers without JavaScript. Both instruction
|
|
18
|
+
files above tell the agent to do that; the element is described under "Embedding a diagram" in the
|
|
19
|
+
main README.
|
|
@@ -7,8 +7,13 @@ description: Draw or change a diagram (architecture, flowchart, sequence, or any
|
|
|
7
7
|
|
|
8
8
|
FastDraw diagrams are small text files (`.fdraw`). You place every element yourself; a look file (`.look`) decides how styles are drawn. People edit the same file in a browser editor afterwards.
|
|
9
9
|
|
|
10
|
-
1.
|
|
11
|
-
2.
|
|
12
|
-
|
|
10
|
+
1. Save a new diagram in `docs/diagrams/` (create the folder), unless the person names another place or the repo already keeps its `.fdraw` files somewhere. Never at the top of the repo: `fastdraw open` lends the diagram's whole folder to the editor.
|
|
11
|
+
2. Run `fastdraw guide` and follow it. It is the single source for the language and the way of working, and it points to `fastdraw guide list` (what each kind of diagram shows), `fastdraw guide <kind>` and `fastdraw sizes`.
|
|
12
|
+
Choose the kind by what the reader has to understand, not by a word in the request ("request flow" is not a flowchart). Unless the request names the kind, tell the person which kind you would draw and the closest other kind, and ask with AskUserQuestion (your pick first) before drawing. If you cannot ask, draw your pick and say which other kind would also have worked.
|
|
13
|
+
3. Always finish with `fastdraw check <file>` clean and a look at the PNG from `fastdraw render <file>`.
|
|
14
|
+
4. When the diagram is done, always ask the person what to do next with AskUserQuestion; do not end your turn without asking. The choices: **Open in fastdraw.dev** (run `fastdraw open <file>` with `run_in_background`, then read its output and give the person the link it prints, in case no browser window appeared; it saves their edits back to the file), **Preview as PNG** (open the rendered PNG in their image viewer) or **Nothing**. Do not open anything before they choose.
|
|
15
|
+
5. For a site with light and dark themes, `fastdraw render <file or folder> --dark` writes `x.png` and `x-dark.png` (the look's dark version, Night for the built-in look). Do not copy the file to swap its look line; `--look <name|file.look>` draws with another look. A folder means every `.fdraw` file under it, for `check` too.
|
|
16
|
+
6. When changing an existing diagram, do not move, resize or restyle what is already there unless asked. A person may have arranged it by hand.
|
|
17
|
+
7. For a docs site (a web page, not a GitHub README), put the diagram on the page with `<fastdraw-diagram src="....fdraw">` from https://fastdraw.dev/embed.js, with the rendered PNG inside it as the fallback image. It draws the file live, pannable and zoomable, and follows the page's dark mode.
|
|
13
18
|
|
|
14
19
|
If the `fastdraw` command is not on the PATH, run it as `npx fastdraw` (for example `npx fastdraw guide`).
|