Skip to content
Back to search

design-flow

MarketplaceWorks with Claude CodeGitHub

Draw every screen of a feature as a UX flow canvas before coding; the user comments and approves in the browser, and comments come back to the session.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 20 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/stvlynn/design-flow with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/stvlynn/design-flow'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/stvlynn--design-flow/badge.svg)](/listings/stvlynn--design-flow)

HTML

<a href="/listings/stvlynn--design-flow"><img src="/api/listings/stvlynn--design-flow/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need Node.js 20 or newer. The skill ships with everything it runs — the CLI, the server and the canvas — so there is nothing else to install.

Install it with the [skills CLI](https://github.com/vercel-labs/skills):

npx skills add stvlynn/design-flow

The CLI asks which agents to install it for (Claude Code, Codex, Cursor and others) and whether to install it for this project or for your user. To skip the questions:

npx skills add stvlynn/design-flow --skill design-flow --agent claude-code --yes

Add `-g` to install it for every project:

npx skills add stvlynn/design-flow --skill design-flow --agent claude-code -g --yes

The skill lands in `.claude/skills/design-flow/` (or `~/.claude/skills/design-flow/` with `-g`).

Optional: the Claude Code plugin

The skill works on its own: it tells the agent to run `design-flow watch` in the background, so your comments reach it while you work. If you use Claude Code and want comments attached to your next message even when no watcher is running, install the repository as a plugin as well:

claude plugin marketplace add stvlynn/design-flow
claude plugin install design-flow@design-flow

The plugin adds a prompt hook (unread comments and approvals are attached to your next message) and a monitor that streams them into the session. It loads in the next session, or after `/reload-plugins`. Plugin monitors need a recent Claude Code; on older versions the prompt hook still delivers comments.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "design-flow",
  3. "description": "Draw every screen of a feature as a UX flow canvas before coding; the user comments and approves in the browser, and comments come back to the session.",
  4. "owner": { "name": "Steven Lynn", "email": "i@stv.pm" },
  5. "plugins": [
  6. {
  7. "name": "design-flow",
  8. "description": "UX flow canvas before coding: screens as HTML, comments back to the agent, approve to start.",
  9. "version": "0.1.0",
  10. "source": "./",
  11. "author": { "name": "Steven Lynn", "email": "i@stv.pm" }
  12. }
  13. ]
  14. }
README.md · README · 200 lines
  1. <h1 align="center">Design Flow</h1>
  2. <p align="center">
  3. <b>A UX flow canvas your coding agent draws before it writes code.</b><br />
  4. Every screen, branch, error and way back, on one infinite canvas. You comment, the agent fixes it, you approve, then it codes.
  5. </p>
  6. <p align="center">
  7. <img src="docs/images/canvas.png" alt="The Design Flow canvas for a sign-up and sign-in flow: three lanes (Sign up, Sign in, Errors and interruptions), thirteen phone-sized screens drawn in the app's own style, and labelled arrows between them" width="960" />
  8. </p>
  9. Ask an agent to build a sign-up flow and it starts writing components. The branches it forgot (email already taken, code expired, five wrong passwords, offline) turn up in review, after the code exists.
  10. With Design Flow, the agent first writes the flow as `.design-flow/<feature>/flow.yaml`: every screen as HTML in your product's own style, the lanes they belong to and the arrows between them. A local server lays it out as a canvas and opens it in your browser. You click any button, field or arrow and leave a comment; the comment arrives in the agent's session; the agent changes the flow, replies, and the canvas updates while you watch. When it is right you press **Approve**, and only then does the agent start coding.
  11. ## Install
  12. You need Node.js 20 or newer. The skill ships with everything it runs — the CLI, the server and the canvas — so there is nothing else to install.
  13. Install it with the [skills CLI](https://github.com/vercel-labs/skills):
  14. ```bash
  15. npx skills add stvlynn/design-flow
  16. ```
  17. The CLI asks which agents to install it for (Claude Code, Codex, Cursor and others) and whether to install it for this project or for your user. To skip the questions:
  18. ```bash
  19. npx skills add stvlynn/design-flow --skill design-flow --agent claude-code --yes
  20. ```
  21. Add `-g` to install it for every project:
  22. ```bash
  23. npx skills add stvlynn/design-flow --skill design-flow --agent claude-code -g --yes
  24. ```
  25. The skill lands in `.claude/skills/design-flow/` (or `~/.claude/skills/design-flow/` with `-g`).
  26. ### Optional: the Claude Code plugin
  27. The skill works on its own: it tells the agent to run `design-flow watch` in the background, so your comments reach it while you work. If you use Claude Code and want comments attached to your next message even when no watcher is running, install the repository as a plugin as well:
  28. ```bash
  29. claude plugin marketplace add stvlynn/design-flow
  30. ```
  31. ```bash
  32. claude plugin install design-flow@design-flow
  33. ```
  34. The plugin adds a prompt hook (unread comments and approvals are attached to your next message) and a monitor that streams them into the session. It loads in the next session, or after `/reload-plugins`. Plugin monitors need a recent Claude Code; on older versions the prompt hook still delivers comments.
  35. ## Use it
  36. ### 1. Ask for a feature with screens
  37. The skill triggers on its own when you ask for something with screens or steps, or when you ask for a UX flow:
  38. ```text
  39. Build sign-up and sign-in for the app. Draw the UX flow first.
  40. ```
  41. In Claude Code you can also call it by name, at the start of your message:
  42. ```text
  43. /design-flow sign-up and sign-in, including every error path
  44. ```
  45. Installed as a plugin, the same skill is also available as `/design-flow:design-flow`.
  46. The agent picks a feature name, runs `design-flow open sign-up`, and writes `.design-flow/sign-up/flow.yaml`. Your browser opens the canvas at `http://127.0.0.1:27420/…`.
  47. ### 2. Read the canvas
  48. <p align="center">
  49. <img src="docs/images/frames.png" alt="Close-up of the Sign in lane: Welcome, Sign in, Wrong password, Reset password and Link sent screens, each a real interface, connected by labelled arrows such as Forgot password and Sent link" width="960" />
  50. </p>
  51. - **Lanes** group the flow (sign up, sign in, errors). An error lane marked "reachable from any step" holds interruptions that can happen anywhere.
  52. - **Frames** are the agent's HTML for each screen, rendered at the device's viewport in a sandbox with no network. Each has an id (`S02`) and a title.
  53. - **Arrows** are labelled with the action or trigger. Red arrows are errors; dashed arrows go back.
  54. - **Badges** mark screens that return home, animate or count down; the **legend** and **notes** sit above and below.
  55. Scroll to pan, ⌘-scroll to zoom. Drag a frame to move it; Design Flow remembers it, and **Re-layout** puts everything back.
  56. ### 3. Comment on anything
  57. Press <kbd>C</kbd> and click: a button inside a screen, a screen's title, an arrow, a lane or empty canvas.
  58. <p align="center">
  59. <img src="docs/images/comment.png" alt="A comment pinned to the resend line inside screen S02 Enter code. The comment panel shows the user asking what happens after five wrong codes, and the agent's reply saying the arrow to X02 now reads Expired or 5 wrong" width="960" />
  60. </p>
  61. The agent receives it where it is anchored:
  62. ```text
  63. [design-flow] sign-up · new comment #4a95ec3d on Screen S02 Enter code · p "Resend code in 0:24" ([data-id="resend"]): What happens after 5 wrong codes? I only see the expiry path.
  64. ```
  65. It changes `flow.yaml`, replies with `design-flow reply`, and resolves the thread when it is settled. Its reply appears under your comment; the canvas redraws as soon as the file changes.
  66. ### 4. Approve
  67. <p align="center">
  68. <img src="docs/images/approve.png" alt="The Approve dialog: one comment thread is still open; the agent will be told it can start coding; changing flow.yaml later withdraws the approval" width="960" />
  69. </p>
  70. **Approve** records the exact version of `flow.yaml` you were looking at and tells the agent it may start coding. If the file changes afterwards, the approval is withdrawn and the canvas asks again. The agent does not code the feature until `design-flow status` says `approved`.
  71. ### Export
  72. The download button exports the whole canvas as a PNG at 2×, with or without comment pins — for a PR description or a design review.
  73. <p align="center">
  74. <img src="docs/images/export-lane.png" alt="Part of an exported PNG: the Sign up lane with the Email, Enter code, Create password and Account ready screens" width="960" />
  75. </p>
  76. The canvas follows your system's light or dark mode; screens keep their own colors.
  77. <p align="center">
  78. <img src="docs/images/dark.png" alt="The same canvas in dark mode" width="960" />
  79. </p>
  80. ## Commands
  81. The agent runs these; you can too. `design-flow` is the skill's launcher:
  82. ```bash
  83. node .claude/skills/design-flow/scripts/design-flow.mjs <command>
  84. ```
  85. | Command | Does |
  86. | --- | --- |
  87. | `open <feature> [--no-open]` | Start the server, write a commented template if `flow.yaml` is missing, open the canvas |
  88. | `check <feature>` | Validate; prints `file:line:col`, the problem and a fix; exit 0 clean, 3 with issues |
  89. | `comments <feature> [--unread] [--json]` | Threads, where each is anchored, and who said what |
  90. | `reply <feature> <thread> --text "…"` | Reply as the agent |
  91. | `resolve <feature> <thread>` | Resolve a thread |
  92. | `status <feature>` | `draft`, `approved` or `stale`, and open threads |
  93. | `watch` | One line per new comment or approval |
  94. | `list` / `stop` | Features in this project / stop the server |
  95. Every command takes `--project-dir <path>`; the default is the current directory. Add `?lang=en` or `?lang=zh` to a canvas URL to pick the interface language.
  96. ## flow.yaml
  97. ```yaml
  98. version: 1
  99. title: Sign up and sign in
  100. viewport: { width: 390, height: 844 } # one screen in CSS px; a screen can override it
  101. style: | # your styles, in every screen's <head>
  102. <style> .btn { padding: 14px; border-radius: 14px } .btn.main { background: #5b4bff; color: #fff } </style>
  103. lanes:
  104. - { id: signup, title: Sign up, tone: success } # success | info | danger | neutral
  105. - { id: errors, title: Errors and interruptions, tone: danger, enter: any }
  106. screens:
  107. - id: W00 # no lane: the entry column
  108. title: Welcome
  109. html: <h1>Notes that keep up with you</h1><button class="btn main" data-id="create">Create account</button>
  110. - id: S01
  111. lane: signup
  112. title: Email
  113. file: screens/s01.html # or keep the HTML in a file
  114. - id: X04
  115. lane: errors
  116. title: Offline
  117. badges: [home] # home | video | timer
  118. note: Any step; keeps what was typed
  119. html: <p>You're offline. We'll try again when you're back.</p>
  120. edges:
  121. - { from: W00, to: S01, label: Create account }
  122. - { from: S01, to: X04, label: No network, kind: error } # normal | error | back
  123. notes:
  124. - Every field keeps its value when the user goes back.
  125. ```
  126. The full reference the agent follows is [`skills/design-flow/SKILL.md`](skills/design-flow/SKILL.md); the schema is [`skills/design-flow/schema/flow.v1.json`](skills/design-flow/schema/flow.v1.json). [`examples/notely`](examples/notely/.design-flow/sign-up/flow.yaml) is the flow in the screenshots.
  127. ## How it works
  128. - One local server for the machine (port 27420, state in `~/.design-flow/`) serves every project; the CLI starts it on demand.
  129. - `flow.yaml` belongs to the agent. `layout.json` (dragged frames), `comments.json`, `approval.json` and `.last-valid.yaml` belong to the tool, next to it. While `flow.yaml` is broken the canvas keeps showing the last valid version and lists the problems.
  130. - Screens run in sandboxed iframes with a content security policy that blocks network access; they can't reach your machine or the server.
  131. - The server only answers requests from its own origin, so other websites cannot post comments into your agent's session or approve a flow.
  132. ## Develop
  133. ```bash
  134. pnpm install
  135. pnpm test # vitest
  136. pnpm typecheck
  137. pnpm build # tsc + vite, then bundles skills/design-flow/scripts/
  138. ```
  139. `src/` is the CLI, server and core; `web/` is the canvas (React, React Flow, ELK); `scripts/bundle-skill.mjs` builds the self-contained skill.
  140. ## License
  141. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.