Skip to main content

​
Sequence Status Workflow - Design Specification

​
Executive Summary

This document specifies a redesigned workflow diagram for sequence statuses. The goal is to create a compact, scannable visualization that can be understood in under 5 seconds.

​
Current Problems (Analysis)

ProblemRoot Cause
Too tall (720px)Vertical stacking of every state; wastes horizontal space
Arrows pointing wrongRejected arrow goes to completed (line 99-100) instead of rework_required
Complex branching4D/2D split shown as equal-weight paths; cognitive overload
Rework loop unclearLoop-back arrow is tiny text on rotated label; hard to parse

​
Why This Approach?

  1. Horizontal flow matches reading direction - Left-to-right progression is intuitive
  2. Parallel tracks show branching clearly - 4D track above, 2D track below, visually distinct
  3. Compact width - Fits in typical doc/readme viewport (800px)
  4. Rework as annotation - Not a full path; shown as a simple return arrow with clear label
Other approaches considered:
ApproachRejected Because
Compact GridHard to show flow direction; looks like a table
Simplified LinearLoses important 4D/2D branch information
SwimlaneAdds visual complexity for minimal benefit

​
Dimensions

viewBox: "0 0 800 280"
  • Width: 800px - Fits in most markdown viewers, GitHub, docs
  • Height: 280px - Compact; no scrolling required
  • Padding: 20px on all sides

​
Layout Grid

The diagram uses a 5-column horizontal grid:
ColumnX PositionContentWidth
120-140Initial states (stacked)120px
2180-300Labeling states (stacked)120px
3340-460Review states (stacked)120px
4500-620Final states (stacked)120px
5660-780End state120px
Row positions:
  • Track labels: y=20 (small text)
  • 4D track: y=60 (center of state boxes)
  • 2D track: y=140 (center of state boxes)
  • Shared path: y=100 (center, for converged flow)
  • Legend: y=250

​
State Positions (Exact Coordinates)

​
Column 1: Initial (Stacked Vertically, Centered)

All three initial states share one column, shown as a compact vertical stack:
StatexyNotes
unattempted80 (center)60Top of stack
pending80 (center)100Middle
ready_for_annotation80 (center)140Bottom; branch point
Box dimensions: 130x28 each (compact)

​
Column 2: Labeling (Two Tracks)

StatexyTrack
labeling_4d240 (center)604D track
labeling_2d240 (center)1402D track
Box dimensions: 110x28 each

​
Column 3: Review (Two Tracks + Transition)

StatexyTrack
review_4d400 (center)604D track
ready_for_2d400 (center)100Transition (between tracks)
review_2d400 (center)1402D track
Box dimensions: 100x28 (review_4d, review_2d), 95x24 (ready_for_2d - smaller, transitional)

​
Column 4: Final Review

StatexyNotes
final_review560 (center)100Centered vertically
rework_required560 (center)180Below, connected by rejection arrow
Box dimensions: 110x28 (final_review), 120x24 (rework_required - red accent)

​
Column 5: Completion

StatexyNotes
completed720 (center)80Upper
customer_approved720 (center)120Lower; final state
Box dimensions: 100x28 each

​
Arrow Paths (Connections)

​
Happy Path (Main Flow)

All arrows use gray (#71717a) with arrowhead marker.
FromToPath TypeNotes
unattemptedpendingShort vertical
pendingready_for_annotationShort vertical
ready_for_annotationlabeling_4dDiagonal up-rightBranch to 4D
ready_for_annotationlabeling_2dHorizontal rightBranch to 2D (or straight if 2D-only)
labeling_4dreview_4dHorizontal right
review_4dready_for_2dDiagonal down-right
ready_for_2dlabeling_2dDiagonal down-rightDotted/dashed (joining 2D track)
labeling_2dreview_2dHorizontal right
review_2dfinal_reviewDiagonal up-rightConverge to center
final_reviewcompletedHorizontal right
completedcustomer_approvedShort vertical

​
Rejection Path (Rework Loop)

Uses red (#ef4444) stroke and arrow.
FromToPath TypeLabel
final_reviewrework_requiredShort vertical down”rejected” label
rework_requiredlabeling_2dCurved return arrow (goes left, under the diagram, back to column 2)“rework” small label
Rework arrow implementation:
  • Start: right side of rework_required
  • Curve: down and left, passing beneath the main flow
  • End: bottom of labeling_2d or labeling_4d (depending on what type of rework)
  • Use a simple curved path or rounded corner path, not complex bezier
Simplified rework alternative: Instead of a complex return arrow, show a simple annotation:
  • Small red text below rework_required: “returns to labeling”
  • This avoids arrow chaos while communicating the concept

​
Color Scheme (Minimal)

Use the existing color scheme but simplified:
CategoryFillStrokeText
Queue (unattempted, pending, ready_for_annotation)#27272a#3f3f46#e4e4e7
Labeling (labeling_4d, labeling_2d)#1e1b4b#6366f1#e4e4e7
Review (review_4d, review_2d, final_review)#422006#f59e0b#e4e4e7
Transition (ready_for_2d)#27272a#3f3f46 (dashed)#a1a1aa
Complete (completed, customer_approved)#052e16#22c55e#e4e4e7
Rework (rework_required)#450a0a#ef4444#e4e4e7
Arrows (normal)-#71717a-
Arrows (rejection)-#ef4444-

​
Typography

ElementFontSizeColor
State labelssystem-ui, sans-serif11px#e4e4e7
Track labels (4D, 2D)system-ui, sans-serif10px#71717a
Arrow labels (rejected, rework)system-ui, sans-serif9px#ef4444
Legend textsystem-ui, sans-serif9px#a1a1aa

​
Visual Hierarchy

  1. Primary: State boxes and their labels (most prominent)
  2. Secondary: Main flow arrows (gray, moderate weight)
  3. Tertiary: Track labels “4D path” / “2D path” (faded)
  4. Accent: Rejection/rework path (red, draws attention to exception flow)
  5. Reference: Legend (bottom, small)

​
Rework Loop Design Decision

Recommendation: Use annotation, not complex arrow Instead of drawing a complex curved arrow that loops back: 
<!-- Below rework_required box -->
<text x="560" y="210" text-anchor="middle" fill="#ef4444" font-size="9">
  returns to labeling
</text>
This is cleaner and avoids:
  • Arrow crossing other arrows
  • Visual clutter
  • Ambiguity about which labeling state it returns to
If the implementer wants the arrow version:
  • Draw a red dashed path from rework_required going DOWN, then LEFT under the diagram, then UP to labeling_2d
  • Keep stroke thin (1px) and dashed to differentiate from main flow

​
Legend (Compact, Horizontal)

Position: Bottom of diagram (y=250), centered horizontally 
[Queue] [Labeling] [Review] [Complete] [Rework]
Each legend item: 12x12 square + label text, spaced 60px apart.

​
Implementation Notes for the Implementing Agent

  1. Start with the grid - Lay out columns first, then place boxes
  2. Draw happy path first - All the gray arrows for normal flow
  3. Add rejection/rework last - So it overlays correctly
  4. Test readability - View at 100% zoom in browser; all text must be legible
  5. Keep stroke widths consistent - 1.5px for arrows, 1.5-2px for box borders
  6. Rounded corners - rx=“5” for all state boxes (friendly, modern look)

​
Expected Result

A compact horizontal workflow that:
  • Shows the complete sequence status flow at a glance
  • Clearly distinguishes 4D and 2D tracks
  • Makes the happy path obvious (left-to-right)
  • Shows rework as an exception path without cluttering the main flow
  • Fits in 800x280 pixels

​
Comparison: Before vs After

MetricCurrentNew Design
Dimensions400x720800x280
Aspect ratioPortrait (0.56)Landscape (2.86)
Scannable in 5 secNoYes
Branch logic clearNoYes (stacked tracks)
Rework arrow correctNo (points to wrong state)Yes (or uses text annotation)
Legend includedYesYes (compact)

​
File Output

The implementing agent should save the new SVG to: 
/Users/graceguo/avala/docs/images/workflows/sequence-statuses.svg
(Overwrites the existing file)