@misoto22/design 0.7.0 → 0.9.0

package/dist/agent/WaterfallChart.md

@@ -4,7 +4,7 @@ How a total got from one figure to another.
 
 - Group: Charts
 - Import: `import { WaterfallChart } from '@misoto22/design/charts'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/waterfall-chart/
 - Related: bar-chart, funnel-chart
 
@@ -12,6 +12,29 @@ How a total got from one figure to another.
 
 “Why did this change”, where the contributions can be negative. A pie cannot hold a negative slice; a BarChart is right when the parts need not add up to the gap between two totals.
 
+## Anatomy
+
+- **Figure frame** (required) — ChartFigure’s <figure>, with an empty state at zero steps. description is where the ordering caveat goes, and it is sr-only until showTitle is set.
+- **Steps** (required) — <WaterfallChart.Bars>: one floating range bar per step, running from the previous total to the new one, with a custom shape over it. Increases and totals take the solid series fill, decreases the 45 degree hatch, so direction survives greyscale and forced colours.
+- **Connectors** — connectors, on by default, joining each bar’s closing edge to where the next one starts. Without them a waterfall is a row of bars floating at unrelated heights and the reader has to reconstruct the cascade.
+- **Zero baseline** (required) — A reference line at zero that <WaterfallChart.Bars> draws itself. It is what the total bars stand on, and a waterfall with no visible zero asks the reader to take every floating bar on trust.
+- **Step labels** — showValues, and it is OFF by default. It prints each step’s signed change beside its bar — worth more here than anywhere else, because an intermediate bar has no baseline under it and its length is the one thing the axis cannot give back.
+- **Hidden data table** — The sr-only table carries the CHANGE and the RUNNING TOTAL per step, which is exactly the pair the picture encodes as a length and a position.
+
+## Best practices
+
+### Do
+
+- Turn showValues on. It is off by default and it is the relief for this form’s central weakness: an intermediate bar floats, so a reader can see that a step was small and cannot see how small.
+- Leave value off the closing total step. Omitted, it is computed from the deltas above it; typed by hand it can disagree with them, and the chart will draw the disagreement without saying a word.
+- Say in description when the step order is editorial, and pass showTitle so the sentence is actually printed. The connectors draw the steps as a sequence and most breakdowns are not one — churn and expansion in the same month are simultaneous — and a reader takes the leftmost bar as the first cause.
+
+### Don’t
+
+- Do not net two opposing movements into one step. A bar reading minus twenty that is really plus one hundred and eighty against minus two hundred is drawn exactly like a quiet month, and showing what moved is the entire purpose of the form.
+- Do not compare an intermediate bar with a total bar by eye. Only the totals sit on the zero line; everything between them is a length at an arbitrary height, so a small step high in the cascade and a large one near zero are not on comparable ground.
+- Do not reach for a pie when the contributions are signed. This is the form that exists because a pie cannot hold a negative slice — and a BarChart is the right one instead when the parts need not add up to the gap between two totals.
+
 ## Accessibility
 
 - The connectors draw the steps as a sequence, and most breakdowns are not sequential — churn and expansion in the same month are simultaneous, and a reader takes the leftmost bar as the first cause. Where the order is arbitrary, say so in description.

package/dist/agent/WorkflowFigure.md

@@ -4,7 +4,7 @@ A process in lanes and phases, with the main path drawn heavier than its branche
 
 - Group: Diagrams
 - Import: `import { WorkflowFigure } from '@misoto22/design/diagrams'`
-- Version: 0.7.0
+- Version: 0.9.0
 - Docs: https://ui.misoto22.com/components/workflow-figure/
 - Related: lifecycle-figure, sequence-figure, steps
 
@@ -12,6 +12,28 @@ A process in lanes and phases, with the main path drawn heavier than its branche
 
 A runbook, an approval chain, a CI pipeline — anything with an owner per step. mainPath is what turns fourteen boxes into a diagram with a subject.
 
+## Anatomy
+
+- **Figure shell** (required) — The same frame every figure sits in. What a process hands it is a key of LINE variants rather than of node kinds — Call, Primary path, Crosses a trust boundary, Asynchronous — because a runbook is read for its arrows and not for its boxes.
+- **Lane** (required) — A 92-unit band per lane with its name set in the 118-unit gutter to its left. The band spans only what the lane actually holds, and a lane marked exception is washed rather than ruled — the one wash in the package’s diagrams, because nothing routes across it.
+- **Column** (required) — What col indexes: a 168-unit column with a 58-unit gutter, the same across every lane. A node sits centred in its lane’s depth, moved off that centre line only by yOffset.
+- **Phase header** — A mono caption at the x of its fromCol, over a rule drawn across the columns from fromCol to toCol — so a phase’s extent is something a reader can see rather than a field only its author knows. variant dashes that rule for security and thickens it for emphasis. A phase is an axis label, so it is set like one rather than framed.
+- **Group frame** — A labelled rule around a run of columns inside ONE lane — a planning loop, an evidence path — dashed when its variant is security.
+- **Main path** — mainPath, drawn as weight rather than as a mark of its own: every edge between two consecutive ids on it goes heavier whatever its own variant says.
+
+## Best practices
+
+### Do
+
+- Give every node a lane that spec.lanes declares. An unknown lane id still resolves to the first lane — there is nowhere else to put the box — so a step written for the exception band is drawn in the right column, at the right size, in the wrong row, and development prints DIAGRAM_LANE_UNKNOWN naming the node.
+- Write mainPath as the path in order. The heavier weight is applied to CONSECUTIVE pairs, so [intake, review, ship] emphasises intake→review and review→ship and nothing else; an id whose neighbour on the list is not the far end of a real edge changes nothing at all.
+- Say what an edge MEANS with role and let the drawing follow it. async and error take the quiet dashed line, return takes an open arrowhead, and main and branch add no stroke of their own because mainPath already draws that distinction as weight. An explicit variant overrides all of it, which is what it is for.
+
+### Don’t
+
+- Phases partition the columns; they do not stack. Each is drawn as a rule across its own span, so two phases claiming the same columns put two rules on one line and one caption over the other — and a reader cannot tell that from one phase drawn twice.
+- An empty lane is not a spacer. The band is sized from what the lane holds, so a lane with no nodes collapses to about one column beside the gutter with its name still set — and an exception lane in that state washes a strip of ground next to the figure rather than under the failure path.
+
 ## Accessibility
 
 - Same contract as every figure: a named picture, with its nodes and relationships published as text beside it.
@@ -19,7 +41,7 @@ A runbook, an approval chain, a CI pipeline — anything with an owner per step.
 
 ## WorkflowFigure
 
-A process: who does what, in what order, and where it can go wrong. Three structures stacked on one grid, and they are three because they answer three different questions a reader brings to a runbook. **Lanes** are rows and answer WHO. A lane marked `exception` is the one band that gets a wash rather than a rule, and it earns the exception to the frames-are-rules law because nothing routes across it — it IS the ground for the failure path, not a frame drawn over the happy one. **Phases** are columns across every lane and answer WHEN. Printed as captions on one header rule, because a phase is an axis label. **Groups** are frames inside a single lane and answer WHAT BELONGS TOGETHER — a planning loop, an evidence path. THE MAIN PATH IS HEAVIER, and that is the whole hierarchy. `mainPath` lists the node ids a reader should be able to follow without thinking. Every edge between two consecutive ids on it is drawn at the emphasis weight whatever its own variant says, which is the one thing that turns fourteen boxes and nineteen arrows into a diagram with a subject. An `error` role goes the other way — dashed and soft — so the exception path recedes without disappearing.
+A process: who does what, in what order, and where it can go wrong. Three structures stacked on one grid, and they are three because they answer three different questions a reader brings to a runbook. **Lanes** are rows and answer WHO. A lane marked `exception` is the one band that gets a wash rather than a rule, and it earns the exception to the frames-are-rules law because nothing routes across it — it IS the ground for the failure path, not a frame drawn over the happy one. **Phases** are columns across every lane and answer WHEN. Printed as captions on one header rule, because a phase is an axis label. **Groups** are frames inside a single lane and answer WHAT BELONGS TOGETHER — a planning loop, an evidence path. THE MAIN PATH IS HEAVIER, and that is the whole hierarchy. `mainPath` lists the node ids a reader should be able to follow without thinking. Every edge between two consecutive ids on it is drawn at the emphasis weight whatever its own variant says, which is the one thing that turns fourteen boxes and nineteen arrows into a diagram with a subject. An `error` role goes the other way — dashed and soft — so the exception path recedes without disappearing, and so does `async`. `branch` adds no stroke of its own: a branch is an edge the main path does not list, and that is already the difference on the page.
 
 ### Props