From c5805a0c7f3c873fab173085da0b8b9080bee7d3 Mon Sep 17 00:00:00 2001 From: ActArtech <123718991+ActArtech@users.noreply.github.com> Date: Tue, 11 Aug 2026 08:24:51 +0400 Subject: [PATCH] fix(sequence): dash OAuth returns and align type-sequence docs (#14) 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. --- README.md | 6 +++--- scripts/verify-sequence-oauth.py | 20 ++++++++++++++++++- .../assets/example-sequence-oauth-dark.html | 9 ++++++--- .../assets/example-sequence-oauth-full.html | 9 ++++++--- .../assets/example-sequence-oauth.html | 11 +++++----- .../references/type-sequence.md | 8 ++++---- 6 files changed, 44 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 7079949..3cc29a5 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/scripts/verify-sequence-oauth.py b/scripts/verify-sequence-oauth.py index e70a093..d8ad046 100644 --- a/scripts/verify-sequence-oauth.py +++ b/scripts/verify-sequence-oauth.py @@ -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']*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'=100)") + ok("oauth trio has ALT two-region structure + async open + dashed returns") # Drive real skin linter entry point on new files cmd = [ diff --git a/skills/diagram-design/assets/example-sequence-oauth-dark.html b/skills/diagram-design/assets/example-sequence-oauth-dark.html index e8de6b9..bc0a132 100644 --- a/skills/diagram-design/assets/example-sequence-oauth-dark.html +++ b/skills/diagram-design/assets/example-sequence-oauth-dark.html @@ -87,7 +87,8 @@ - + + @@ -113,7 +114,8 @@ [else · 401] - + + 401 @@ -129,7 +131,8 @@ GET /RESOURCE · RETRY - + + 200 · BODY diff --git a/skills/diagram-design/assets/example-sequence-oauth-full.html b/skills/diagram-design/assets/example-sequence-oauth-full.html index 7e4163a..4b5822a 100644 --- a/skills/diagram-design/assets/example-sequence-oauth-full.html +++ b/skills/diagram-design/assets/example-sequence-oauth-full.html @@ -210,7 +210,8 @@ - + + @@ -236,7 +237,8 @@ [else · 401] - + + 401 @@ -252,7 +254,8 @@ GET /RESOURCE · RETRY - + + 200 · BODY diff --git a/skills/diagram-design/assets/example-sequence-oauth.html b/skills/diagram-design/assets/example-sequence-oauth.html index db741f6..062eda3 100644 --- a/skills/diagram-design/assets/example-sequence-oauth.html +++ b/skills/diagram-design/assets/example-sequence-oauth.html @@ -96,7 +96,8 @@ ACTIVATION BARS ================================================================= --> - + + @@ -137,8 +138,8 @@ [else · 401] - - + + 401 @@ -157,8 +158,8 @@ GET /RESOURCE · RETRY - - + + 200 · BODY diff --git a/skills/diagram-design/references/type-sequence.md b/skills/diagram-design/references/type-sequence.md index 441b1c3..7821605 100644 --- a/skills/diagram-design/references/type-sequence.md +++ b/skills/diagram-design/references/type-sequence.md @@ -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)