Load mahou:program-design first, then mahou:canvas. Then read .mahou/program-design-with-canvas.md if present.
Program design with canvas
program-design and the skills it loads keep their opening, tree, branch order, parts, standards, record and ending.
When the user asks for a fast track, or fast track is already on in the session, load mahou:fast-track after mahou:canvas and before starting, unless it is already in context. It changes some of this skill's engagement rules.
The document is canvas/<name>.tldr.json in the change's scratch folder, named after what the program design covers, such as settings-screen.tldr.json. The record stays program-design/<root>.md. Each time a part settles on the canvas, write it into the record in the text representation from program-design's references.
The canvas
- The tree goes at the top, in monospace text, with
design-tree's marks. Update it whenever you propose a part or the user settles one.
- Each part gets its own
area, labelled <root> · <branch> · <n> <part> · <status>, with the status proposed or settled. A new part goes under the previous part of its branch. A settled part stays on the canvas.
- Give each branch its own column. Start a new branch to the right of the previous one. Put the new branch's first part at the same height as the first part of the root's first branch.
- Draw each part as its reference under
references/representations/ describes. Work out a part with no canvas reference with the user before drawing it.
- Draw the contents of a file, such as a route file or a config, as a
code-snippet mock in its code view, with highlighting rules for the file's language. Never draw a file's contents as a monospace text card.
- Draw the code the user asks for as
code-snippet mocks inside an area in the column of the branch it details, under the branch's parts, labelled as a sketch that does not enter the record. Draw a change as a diff in the unified view, one snippet per file, with a note beside each changed line on the behaviour the line adds or changes.
- A spike's result goes in the area of the part that asked for it, under the part's representation, as
canvas describes.
- An arrow runs from the part that acts to the part it acts on, labelled with the action and what it carries:
renders · <props> from a component to what it renders, calls · <arguments> from a caller to the hook or function it calls, reads context · <values> from a component to the provider whose context it reads. The canvas references name only the labels each one uses.
Each canvas reference describes how to draw one of program-design's representations, and has the same file name as that representation's reference under program-design/references/representations/:
| The part |
program-design reference |
Canvas reference |
| Screen layout |
screen-layout.md |
references/representations/screen-layout.md |
| Component tree |
component-tree.md |
references/representations/component-tree.md |
| State, as a derivation ledger |
derivation-ledger.md |
references/representations/derivation-ledger.md |
| Package layout |
package-layout.md |
references/representations/package-layout.md |
| Interfaces |
interfaces.md |
references/representations/interfaces.md |
| Callstack |
callstack.md |
references/representations/callstack.md |
| Module list |
module-list.md |
references/representations/module-list.md |
| Standards |
standards.md |
references/representations/standards.md |
Marking the change
On every part, mark what the change adds, alters and removes, and what exists today and takes part in the change, with the same marks in every representation.
- A card carries a badge in its top right corner for the change to the whole component, hook or function:
+ NEW in green when the change adds it, ~ CHANGED in amber when it exists today and the change alters it, and = UNCHANGED in grey when it exists today, stays as it is and takes part in the change. The border repeats the mark: solid and thicker for new, dashed for changed, dotted grey for unchanged. The card's colour names the kind of component or hook.
- A line, an interface member or a file carries a mark in its left margin:
+ added, ~ changed, − removed, and no mark when it exists today and stays. On state, hook and interface cards the line's name and expression take the mark's colour: green for added, amber for changed, red and struck through for removed. A line carries no background colour.
- Draw what takes part in the change even when the change leaves it as it is, such as the host that renders a new component or the component that calls a changed hook, marked
= UNCHANGED, with the lines that connect it to the change.
- Draw a part that another branch defines as a reference in the branch that uses it: the same kind of card, with its name and kind, the line
definition in <branch>.<part> and no lines inside, joined only to the cards of this branch. Never draw an arrow to a card in another column. In the module list, the file of that part carries the mark it has in the branch that defines the part, followed by shared, defined in <branch>.<part>.
- Every part ends with the same legend, a
change-legend mock that draws the three badges with their borders and the three line marks. The component tree draws the badges inside its own legend row instead.
Questions
A question goes inside the part it is about, on the right side of the part's area, next to the items it discusses. The part's Agent note goes under the questions.
- A question is a violet card: a rectangle with violet border and fill, titled
❓ Q<n> · <title>, then the body, which gives the situation and ends with the question. Add a diagram, drawn with tldraw shapes, when the question is about where something runs, in what order or across which boundary.
- Follow-ups stay inside the base question's card, one at a time, until the question closes. The card holds, top to bottom: the base question and its diagram, a summary box, one Agent note, and the current follow-up as a violet card of its own.
- The summary box, a solid grey rectangle labelled
Summary · Q<n> so far, holds what the question has settled and the findings that bear on it. Rewrite it each round; never add a line per answer.
- When the question closes, delete the card, redraw the part with what it settled, and update the record.
Messages from the agent
Everything you would say in the chat goes on the canvas: how you read an answer, research results, status, and requests to approve a part. Write it as an Agent note: a grey dashed rectangle labelled Agent, in the part or the question it is about. Keep one Agent note per place and replace its text each round. When a part settles, delete its note.
Mockups
The canvas references use the mockups in this skill's mockups/ folder: component-cards, state-card, hook-card, interface-card, file-tree and change-legend. Before drawing a part, copy the mockups it uses into the canvas folder's mockups/, unless they are already there. Each file's props are its data.
1---2name: program-design-with-canvas3description: Runs the program-design skill on a canvas. Each part of a branch (screen layout, component tree, state) is drawn on the canvas for the user to correct, while the record file keeps the text representation. Use when the user wants to work a program design on a canvas.4argument-hint: <the scope or change to program-design>5metadata:6 source: https://skillmd.com/skills/asermax/program-design-with-canvas7---89Load mahou:program-design first, then mahou:canvas. Then read `.mahou/program-design-with-canvas.md` if present.1011# Program design with canvas1213`program-design` and the skills it loads keep their opening, tree, branch order, parts, standards, record and ending.1415When the user asks for a fast track, or fast track is already on in the session, load mahou:fast-track after mahou:canvas and before starting, unless it is already in context. It changes some of this skill's engagement rules.1617The document is `canvas/<name>.tldr.json` in the change's scratch folder, named after what the program design covers, such as `settings-screen.tldr.json`. The record stays `program-design/<root>.md`. Each time a part settles on the canvas, write it into the record in the text representation from `program-design`'s references.1819## The canvas2021- **The tree goes at the top**, in monospace text, with `design-tree`'s marks. Update it whenever you propose a part or the user settles one.22- **Each part gets its own `area`**, labelled `<root> · <branch> · <n> <part> · <status>`, with the status `proposed` or `settled`. A new part goes under the previous part of its branch. A settled part stays on the canvas.23- **Give each branch its own column.** Start a new branch to the right of the previous one. Put the new branch's first part at the same height as the first part of the root's first branch.24- **Draw each part as its reference under `references/representations/` describes.** Work out a part with no canvas reference with the user before drawing it.25- **Draw the contents of a file, such as a route file or a config, as a `code-snippet` mock** in its `code` view, with highlighting rules for the file's language. Never draw a file's contents as a monospace text card.26- **Draw the code the user asks for as `code-snippet` mocks** inside an `area` in the column of the branch it details, under the branch's parts, labelled as a sketch that does not enter the record. Draw a change as a diff in the `unified` view, one snippet per file, with a note beside each changed line on the behaviour the line adds or changes.27- **A spike's result goes in the area of the part that asked for it**, under the part's representation, as `canvas` describes.28- **An arrow runs from the part that acts to the part it acts on**, labelled with the action and what it carries: `renders · <props>` from a component to what it renders, `calls · <arguments>` from a caller to the hook or function it calls, `reads context · <values>` from a component to the provider whose context it reads. The canvas references name only the labels each one uses.2930Each canvas reference describes how to draw one of `program-design`'s representations, and has the same file name as that representation's reference under `program-design/references/representations/`:3132| The part | `program-design` reference | Canvas reference |33|---|---|---|34| Screen layout | `screen-layout.md` | `references/representations/screen-layout.md` |35| Component tree | `component-tree.md` | `references/representations/component-tree.md` |36| State, as a derivation ledger | `derivation-ledger.md` | `references/representations/derivation-ledger.md` |37| Package layout | `package-layout.md` | `references/representations/package-layout.md` |38| Interfaces | `interfaces.md` | `references/representations/interfaces.md` |39| Callstack | `callstack.md` | `references/representations/callstack.md` |40| Module list | `module-list.md` | `references/representations/module-list.md` |41| Standards | `standards.md` | `references/representations/standards.md` |4243## Marking the change4445On every part, mark what the change adds, alters and removes, and what exists today and takes part in the change, with the same marks in every representation.4647- **A card carries a badge in its top right corner** for the change to the whole component, hook or function: `+ NEW` in green when the change adds it, `~ CHANGED` in amber when it exists today and the change alters it, and `= UNCHANGED` in grey when it exists today, stays as it is and takes part in the change. The border repeats the mark: solid and thicker for new, dashed for changed, dotted grey for unchanged. The card's colour names the kind of component or hook.48- **A line, an interface member or a file carries a mark in its left margin**: `+` added, `~` changed, `−` removed, and no mark when it exists today and stays. On state, hook and interface cards the line's name and expression take the mark's colour: green for added, amber for changed, red and struck through for removed. A line carries no background colour.49- **Draw what takes part in the change even when the change leaves it as it is**, such as the host that renders a new component or the component that calls a changed hook, marked `= UNCHANGED`, with the lines that connect it to the change.50- **Draw a part that another branch defines as a reference** in the branch that uses it: the same kind of card, with its name and kind, the line `definition in <branch>.<part>` and no lines inside, joined only to the cards of this branch. Never draw an arrow to a card in another column. In the module list, the file of that part carries the mark it has in the branch that defines the part, followed by `shared, defined in <branch>.<part>`.51- **Every part ends with the same legend**, a `change-legend` mock that draws the three badges with their borders and the three line marks. The component tree draws the badges inside its own legend row instead.5253## Questions5455A question goes inside the part it is about, on the right side of the part's area, next to the items it discusses. The part's Agent note goes under the questions.5657- **A question is a violet card**: a rectangle with violet border and fill, titled `❓ Q<n> · <title>`, then the body, which gives the situation and ends with the question. Add a diagram, drawn with tldraw shapes, when the question is about where something runs, in what order or across which boundary.58- **Follow-ups stay inside the base question's card**, one at a time, until the question closes. The card holds, top to bottom: the base question and its diagram, a summary box, one Agent note, and the current follow-up as a violet card of its own.59- **The summary box**, a solid grey rectangle labelled `Summary · Q<n> so far`, holds what the question has settled and the findings that bear on it. Rewrite it each round; never add a line per answer.60- **When the question closes**, delete the card, redraw the part with what it settled, and update the record.6162## Messages from the agent6364Everything you would say in the chat goes on the canvas: how you read an answer, research results, status, and requests to approve a part. Write it as an Agent note: a grey dashed rectangle labelled `Agent`, in the part or the question it is about. Keep one Agent note per place and replace its text each round. When a part settles, delete its note.6566## Mockups6768The canvas references use the mockups in this skill's `mockups/` folder: `component-cards`, `state-card`, `hook-card`, `interface-card`, `file-tree` and `change-legend`. Before drawing a part, copy the mockups it uses into the canvas folder's `mockups/`, unless they are already there. Each file's props are its `data`.