jb/diagram-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(sequence): dash OAuth returns and align type-sequence docs (#14)

Browse Source 
Polish after #13: 401 and retry 200 use dashed return strokes on all
three OAuth examples; first API activation bar covers the happy-path
return; type-sequence return rules no longer contradict the message table;
README quickstart names bearer+refresh rather than a full OAuth handshake.
verify-sequence-oauth.py now checks dashed returns and activation height.
This commit is contained in:
ActArtech
2026-08-10 23:24:51 -05:00
committed by GitHub
parent 8827b27739
commit c5805a0c7f
6 changed files with 44 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+3 -3
View File
@@ -179,9 +179,9 @@ open ~/.claude/skills/diagram-design/assets/index.html
# In Claude Code, just ask:
# "Make me an architecture diagram of my app: frontend, backend, database, Redis cache."
# "I need a quadrant showing Q2 projects by impact vs effort."
# "Give me a sequence diagram of the OAuth handshake."
# (branching token refresh uses the ALT combined-fragment grammar in type-sequence.md;
# see assets/example-sequence-oauth.html)
# "Give me a sequence of a bearer call with token refresh on 401."
# (branching refresh uses the ALT combined-fragment grammar in type-sequence.md;
# see assets/example-sequence-oauth.html — not a full authorize-code handshake)
```
Claude will pick the right type, build the HTML, and save it. You can also start from a template directly:
scripts/verify-sequence-oauth.py
+19 -1
View File
@@ -89,7 +89,25 @@ def main() -> int:
fail(f"{path.name} missing arrow-open async marker")
if "Bearer" not in body and "BEARER" not in body:
fail(f"{path.name} missing bearer call")
ok("oauth trio has ALT two-region structure + async open")
# Return grammar: 401 and retry 200 body must be dashed (not solid calls)
for y, label in (("368", "401"), ("544", "retry 200")):
# line at y1=y must include stroke-dasharray when present
m = re.search(
rf'<line[^>]*y1="{y}"[^>]*/?>',
body,
)
if not m:
fail(f"{path.name} missing return line at y1={y} ({label})")
if "stroke-dasharray" not in m.group(0):
fail(f"{path.name} {label} return at y1={y} must be dashed")
# First API activation must span past M2 (y=272)
act = re.search(
r'<rect x="476" y="180" width="8" height="(\d+)"',
body,
)
if not act or int(act.group(1)) < 100:
fail(f"{path.name} first API activation height must cover M2 (height>=100)")
ok("oauth trio has ALT two-region structure + async open + dashed returns")
# Drive real skin linter entry point on new files
cmd = [
skills/diagram-design/assets/example-sequence-oauth-dark.html
+6 -3
View File
@@ -87,7 +87,8 @@
<line x1="480" y1="128" x2="480" y2="624" stroke="rgba(245,245,245,0.22)" stroke-width="1" stroke-dasharray="3,3"/>
<line x1="800" y1="128" x2="800" y2="624" stroke="rgba(245,245,245,0.22)" stroke-width="1" stroke-dasharray="3,3"/>
<rect x="476" y="180" width="8" height="88" fill="rgba(245,245,245,0.06)" stroke="#bfc0c0" stroke-width="0.8"/>
<!-- First API activation brackets M1 call through M2 success return -->
<rect x="476" y="180" width="8" height="104" fill="rgba(245,245,245,0.06)" stroke="#bfc0c0" stroke-width="0.8"/>
<rect x="156" y="360" width="8" height="200" fill="rgba(245,245,245,0.06)" stroke="#bfc0c0" stroke-width="0.8"/>
<rect x="796" y="400" width="8" height="64" fill="rgba(245,245,245,0.06)" stroke="#bfc0c0" stroke-width="0.8"/>
<rect x="476" y="496" width="8" height="64" fill="rgba(245,245,245,0.06)" stroke="#bfc0c0" stroke-width="0.8"/>
@@ -113,7 +114,8 @@
<text x="100" y="336" fill="#bfc0c0" font-size="8" font-family="'Geist Mono', monospace" letter-spacing="0.04em">[else · 401]</text>
<line x1="476" y1="368" x2="168" y2="368" stroke="#bfc0c0" stroke-width="1.2" marker-end="url(#arrow)"/>
<!-- M3: 401 return dashed -->
<line x1="476" y1="368" x2="168" y2="368" stroke="#bfc0c0" stroke-width="1.2" stroke-dasharray="5,4" marker-end="url(#arrow)"/>
<rect x="272" y="352" width="56" height="12" rx="2" fill="#2d3142"/>
<text x="300" y="362" fill="#bfc0c0" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">401</text>
@@ -129,7 +131,8 @@
<rect x="248" y="488" width="112" height="12" rx="2" fill="#2d3142"/>
<text x="304" y="498" fill="#6a95d8" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">GET /RESOURCE · RETRY</text>
<line x1="476" y1="544" x2="168" y2="544" stroke="#bfc0c0" stroke-width="1.2" marker-end="url(#arrow)"/>
<!-- M7: retry 200 return dashed -->
<line x1="476" y1="544" x2="168" y2="544" stroke="#bfc0c0" stroke-width="1.2" stroke-dasharray="5,4" marker-end="url(#arrow)"/>
<rect x="256" y="528" width="88" height="12" rx="2" fill="#2d3142"/>
<text x="300" y="538" fill="#bfc0c0" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">200 · BODY</text>
skills/diagram-design/assets/example-sequence-oauth-full.html
+6 -3
View File
@@ -210,7 +210,8 @@
<line x1="480" y1="128" x2="480" y2="624" stroke="rgba(45,49,66,0.22)" stroke-width="1" stroke-dasharray="3,3"/>
<line x1="800" y1="128" x2="800" y2="624" stroke="rgba(45,49,66,0.22)" stroke-width="1" stroke-dasharray="3,3"/>
<rect x="476" y="180" width="8" height="88" fill="rgba(45,49,66,0.06)" stroke="#4f5d75" stroke-width="0.8"/>
<!-- First API activation brackets M1 call through M2 success return -->
<rect x="476" y="180" width="8" height="104" fill="rgba(45,49,66,0.06)" stroke="#4f5d75" stroke-width="0.8"/>
<rect x="156" y="360" width="8" height="200" fill="rgba(45,49,66,0.06)" stroke="#4f5d75" stroke-width="0.8"/>
<rect x="796" y="400" width="8" height="64" fill="rgba(45,49,66,0.06)" stroke="#4f5d75" stroke-width="0.8"/>
<rect x="476" y="496" width="8" height="64" fill="rgba(45,49,66,0.06)" stroke="#4f5d75" stroke-width="0.8"/>
@@ -236,7 +237,8 @@
<text x="100" y="336" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" letter-spacing="0.04em">[else · 401]</text>
<line x1="476" y1="368" x2="168" y2="368" stroke="#4f5d75" stroke-width="1.2" marker-end="url(#arrow)"/>
<!-- M3: 401 return dashed -->
<line x1="476" y1="368" x2="168" y2="368" stroke="#4f5d75" stroke-width="1.2" stroke-dasharray="5,4" marker-end="url(#arrow)"/>
<rect x="272" y="352" width="56" height="12" rx="2" fill="#f5f5f5"/>
<text x="300" y="362" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">401</text>
@@ -252,7 +254,8 @@
<rect x="248" y="488" width="112" height="12" rx="2" fill="#f5f5f5"/>
<text x="304" y="498" fill="#2e5aa8" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">GET /RESOURCE · RETRY</text>
<line x1="476" y1="544" x2="168" y2="544" stroke="#4f5d75" stroke-width="1.2" marker-end="url(#arrow)"/>
<!-- M7: retry 200 return dashed -->
<line x1="476" y1="544" x2="168" y2="544" stroke="#4f5d75" stroke-width="1.2" stroke-dasharray="5,4" marker-end="url(#arrow)"/>
<rect x="256" y="528" width="88" height="12" rx="2" fill="#f5f5f5"/>
<text x="300" y="538" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">200 · BODY</text>
skills/diagram-design/assets/example-sequence-oauth.html
+6 -5
View File
@@ -96,7 +96,8 @@
ACTIVATION BARS
================================================================= -->
<!-- API holds control for the initial call -->
<rect x="476" y="180" width="8" height="88" fill="rgba(45,49,66,0.06)" stroke="#4f5d75" stroke-width="0.8"/>
<!-- First API activation brackets M1 call through M2 success return -->
<rect x="476" y="180" width="8" height="104" fill="rgba(45,49,66,0.06)" stroke="#4f5d75" stroke-width="0.8"/>
<!-- Client activation during refresh region -->
<rect x="156" y="360" width="8" height="200" fill="rgba(45,49,66,0.06)" stroke="#4f5d75" stroke-width="0.8"/>
<!-- Auth activation for refresh -->
@@ -137,8 +138,8 @@
<!-- Region 2 guard -->
<text x="100" y="336" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" letter-spacing="0.04em">[else · 401]</text>
<!-- M3: API → Client 401 -->
<line x1="476" y1="368" x2="168" y2="368" stroke="#4f5d75" stroke-width="1.2" marker-end="url(#arrow)"/>
<!-- M3: API → Client 401 (return: dashed + filled) -->
<line x1="476" y1="368" x2="168" y2="368" stroke="#4f5d75" stroke-width="1.2" stroke-dasharray="5,4" marker-end="url(#arrow)"/>
<rect x="272" y="352" width="56" height="12" rx="2" fill="#f5f5f5"/>
<text x="300" y="362" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">401</text>
@@ -157,8 +158,8 @@
<rect x="248" y="488" width="112" height="12" rx="2" fill="#f5f5f5"/>
<text x="304" y="498" fill="#2e5aa8" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">GET /RESOURCE · RETRY</text>
<!-- M7: API → Client 200 retry success (muted — coral already used) -->
<line x1="476" y1="544" x2="168" y2="544" stroke="#4f5d75" stroke-width="1.2" marker-end="url(#arrow)"/>
<!-- M7: API → Client 200 retry success (return dashed; coral already used on M2) -->
<line x1="476" y1="544" x2="168" y2="544" stroke="#4f5d75" stroke-width="1.2" stroke-dasharray="5,4" marker-end="url(#arrow)"/>
<rect x="256" y="528" width="88" height="12" rx="2" fill="#f5f5f5"/>
<text x="300" y="538" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">200 · BODY</text>
skills/diagram-design/references/type-sequence.md
+4 -4
View File
@@ -8,8 +8,8 @@
- Messages: horizontal arrows between lifelines; time flows top→down.
- **Activation bar**: narrow rectangle (`w=8`, muted fill, 0.8 hairline stroke) on a lifeline spanning the interval that actor holds control. Stack for nested calls.
- Self-messages: short U-shaped loop returning to the same lifeline; label right of the loop.
- Return messages: dashed line in the same color as the originating call.
- Coral on the primary success response or headline message — one, maybe two.
- Return messages: **dashed** stroke + **filled** marker (never open). Prefer muted; optionally match the originating call color when pairing multi-hop stacks. Headline success may use solid coral (see Message kinds).
- Coral on the primary success response or headline message — one, maybe two. Actor focal strokes do not count toward the coral message budget.
- When the flow **branches** (valid vs invalid token, retry, optional step), draw a **combined fragment** frame — do not invent free-floating if/else arrow clusters.
## Message kinds
@@ -17,9 +17,9 @@
| Kind | Stroke | Marker | When |
|---|---|---|---|
| Call (sync) | solid muted or link-blue | filled | Request that expects a reply |
| Return | dashed, same color as the call | filled | Reply to a sync call |
| Return | **dashed** muted (or match call color) | filled | Reply to a sync call — never solid |
| Async / fire-and-forget | dashed muted | **open** arrowhead | Beacons, events, one-way notify |
| Headline success | solid accent (≤1–2) | accent filled | Primary happy-path response |
| Headline success | solid accent (≤1–2 messages) | accent filled | Primary happy-path response only |
### Open arrowhead (async)