docs: add frontend process, wireframe kit, and SVG generation pipeline#28
Conversation
📝 WalkthroughWalkthroughThis PR establishes a formal wireframe workflow by introducing process documentation, generation tooling, and a concrete login wireframe example. It adds ChangesWireframe Workflow & Documentation
🎯 2 (Simple) | ⏱️ ~12 minutes
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
- Add docs/PROCESS.md with step-by-step checklists for both backend (new module setup + per-US TDD workflow) and frontend (Phase 1 foundation + Phase 2 per-feature workflow) - Add docs/wireframes/login.excalidraw — login screen wireframe - Add docs/wireframes/_template.excalidraw — full UI component kit (12 sections: color palette, typography, buttons, form controls, badges, navigation, sidebar, table, cards, feedback, modal, app shell) - Add docs/wireframes/generate-template.mjs — script to regenerate _template.excalidraw from source - Add docs/scripts/generate-wireframes.ps1 — regenerates .svg previews from .excalidraw via Kroki.io (mirrors generate-diagrams.ps1 pattern) - Switch wireframe preview format from .png to .svg (Kroki only supports SVG for Excalidraw; SVG renders inline on GitHub and scales better) - Update CLAUDE.md, PATTERNS.md, PROCESS.md, README.md to reflect SVG convention and new generate-wireframes.ps1 workflow Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
phuongnse
force-pushed
the
docs/frontend-process-and-wireframe-kit
branch
from
bce486d to
00e0751
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Line 350: Update the acceptance criteria text that currently reads "PNG
exported alongside" to require an SVG preview instead (e.g., ".svg exported
alongside" or "SVG exported alongside") and align the wireframe convention
sentence to state the source is docs/wireframes/{screen-slug}.excalidraw with
{screen-slug}.svg as the rendered preview; update the nearby "Wireframe" callout
wording if necessary so the feature file guidance matches the new .svg
requirement.
In `@docs/epics/E02-identity-access/features/F01-authentication.md`:
- Around line 3-6: Move the existing '> **Wireframe**:
[docs/wireframes/login.excalidraw] · [preview]' callout so it appears
immediately after the feature title line '# F01 — Authentication' instead of
after the back-link; locate the '> **Wireframe**' callout in this file and
cut/paste it directly beneath the '# F01 — Authentication' header ensuring the
backlink '[← Back to E02](../README.md)' remains at the top or below as per
convention.
In `@docs/PATTERNS.md`:
- Around line 1443-1447: The fenced code block showing the wireframes directory
is missing a language tag (causing MD040); update the markdown fenced block (the
triple-backtick block containing "docs/wireframes/ ├── {screen-slug}.excalidraw
…") to include a language identifier such as "text" (i.e., change ``` to
```text) so the linter recognizes the block language.
In `@docs/README.md`:
- Line 16: Update the wireframes table row text to reflect the actual preview
format: replace the phrase "PNG preview" with "SVG preview" in the markdown row
that currently reads "| [Wireframes](./wireframes/) | Screen wireframes —
Excalidraw source + PNG preview |" so the README matches the project convention
that rendered previews are .svg files (docs/wireframes/{screen-slug}.svg).
In `@docs/scripts/generate-wireframes.ps1`:
- Around line 16-29: The catch blocks in generate-wireframes.ps1 currently only
log failures (using $svgPath and $excalidrawPath) and swallow errors so the
script exits successfully; update the catch blocks (both the shown one and the
similar block around lines 47-54) to propagate failure by either re-throwing the
caught error (throw $_) or explicitly exiting with a non-zero status (exit 1)
after logging, ensuring callers/CI detect partial/failed generation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 6e085d07-e679-4485-bd77-e34d07c5efdc
⛔ Files ignored due to path filters (2)
docs/wireframes/_template.svgis excluded by!**/*.svgdocs/wireframes/login.svgis excluded by!**/*.svg
📒 Files selected for processing (9)
CLAUDE.mddocs/PATTERNS.mddocs/PROCESS.mddocs/README.mddocs/epics/E02-identity-access/features/F01-authentication.mddocs/scripts/generate-wireframes.ps1docs/wireframes/_template.excalidrawdocs/wireframes/generate-template.mjsdocs/wireframes/login.excalidraw
| [← Back to E02](../README.md) | ||
|
|
||
| > **Wireframe**: [docs/wireframes/login.excalidraw](../../../wireframes/login.excalidraw) · [preview](../../../wireframes/login.svg) | ||
|
|
There was a problem hiding this comment.
Move the > **Wireframe** callout directly under the feature title.
The callout is currently placed after the back-link. Per the convention, it should be immediately after # F01 — Authentication.
As per coding guidelines "Link from feature file with > **Wireframe** callout directly after feature title".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/epics/E02-identity-access/features/F01-authentication.md` around lines 3
- 6, Move the existing '> **Wireframe**: [docs/wireframes/login.excalidraw] ·
[preview]' callout so it appears immediately after the feature title line '# F01
— Authentication' instead of after the back-link; locate the '> **Wireframe**'
callout in this file and cut/paste it directly beneath the '# F01 —
Authentication' header ensuring the backlink '[← Back to E02](../README.md)'
remains at the top or below as per convention.
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/PATTERNS.md (1)
1443-1447:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd language identifier to the fenced code block.
The fence is missing a language tag, which triggers MD040. Add
textafter the opening fence.Proposed fix
-``` +```text docs/wireframes/ ├── {screen-slug}.excalidraw ← source (JSON, diffable on GitHub) └── {screen-slug}.svg ← rendered preview (vector, renders inline on GitHub)</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/PATTERNS.mdaround lines 1443 - 1447, The fenced code block showing the
docs/wireframes tree is missing a language tag and triggers MD040; update the
opening triple-backtick for that block to include the language identifiertext
(i.e., changetotext) so the snippet is properly annotated in
docs/PATTERNS.md; locate the block containing the directory listing (the lines
starting with "docs/wireframes/") and addtextimmediately after the opening
fence.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.Duplicate comments:
In@docs/PATTERNS.md:
- Around line 1443-1447: The fenced code block showing the docs/wireframes tree
is missing a language tag and triggers MD040; update the opening triple-backtick
for that block to include the language identifiertext(i.e., change ``` toblock containing the directory listing (the lines starting with "docs/wireframes/") and add `text` immediately after the opening fence.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
fcd4bd7c-67a2-42e5-8f90-ab3fd0ef4e3a⛔ Files ignored due to path filters (2)
docs/wireframes/_template.svgis excluded by!**/*.svgdocs/wireframes/login.svgis excluded by!**/*.svg📒 Files selected for processing (9)
CLAUDE.mddocs/PATTERNS.mddocs/PROCESS.mddocs/README.mddocs/epics/E02-identity-access/features/F01-authentication.mddocs/scripts/generate-wireframes.ps1docs/wireframes/_template.excalidrawdocs/wireframes/generate-template.mjsdocs/wireframes/login.excalidraw✅ Files skipped from review due to trivial changes (4)
- docs/epics/E02-identity-access/features/F01-authentication.md
- docs/wireframes/login.excalidraw
- docs/README.md
- docs/PROCESS.md
🚧 Files skipped from review as they are similar to previous changes (3)
- CLAUDE.md
- docs/scripts/generate-wireframes.ps1
- docs/wireframes/generate-template.mjs
Mirror docs/epics/ structure: each module gets its own subfolder under docs/wireframes/. Shared screens go in _shared/. Update generate-wireframes.ps1 to recurse subfolders. Update all path references in docs and feature files. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/PATTERNS.md (1)
1443-1451:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd a language tag to the fenced block at Line 1443.
The wireframe tree block is missing a fence language, which can trip MD040 in linted docs pipelines.
Suggested fix
-``` +```text docs/wireframes/ ├── E02-identity-access/ │ ├── login.excalidraw ← source (JSON, diffable on GitHub) │ └── login.svg ← rendered preview (vector, renders inline on GitHub) ├── E03-data-modeling/ │ └── ... └── _shared/ ← screens not belonging to a single module</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/PATTERNS.mdaround lines 1443 - 1451, The fenced code block showing the
wireframe tree in docs/PATTERNS.md is missing a language tag (tripping MD040);
update the opening fence fromtotext so the block is explicitly marked
as plain text. Locate the block that begins with the tree lines (the block
containing "docs/wireframes/" and the E02/E03/_shared entries) and change the
delimiter to ```text to satisfy the linter.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.Duplicate comments:
In@docs/PATTERNS.md:
- Around line 1443-1451: The fenced code block showing the wireframe tree in
docs/PATTERNS.md is missing a language tag (tripping MD040); update the opening
fence fromtotext so the block is explicitly marked as plain text.
Locate the block that begins with the tree lines (the block containing
"docs/wireframes/" and the E02/E03/_shared entries) and change the delimiter to
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
0af07627-d856-4708-b9fc-00bd892c734b⛔ Files ignored due to path filters (1)
docs/wireframes/E02-identity-access/login.svgis excluded by!**/*.svg📒 Files selected for processing (6)
CLAUDE.mddocs/PATTERNS.mddocs/README.mddocs/epics/E02-identity-access/features/F01-authentication.mddocs/scripts/generate-wireframes.ps1docs/wireframes/E02-identity-access/login.excalidraw✅ Files skipped from review due to trivial changes (4)
- docs/epics/E02-identity-access/features/F01-authentication.md
- docs/README.md
- docs/wireframes/E02-identity-access/login.excalidraw
- CLAUDE.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/scripts/generate-wireframes.ps1
- Move Wireframe callout to immediately after feature title in F01 - Fix README navigation table: PNG → SVG - generate-wireframes.ps1 now returns exit code 1 on any failure Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/scripts/generate-wireframes.ps1`:
- Around line 35-43: The pipeline building $wireframes and the conditional
assigning $filtered can collapse to a single scalar hashtable when only one
match is found; wrap the pipeline outputs in array subexpression to force arrays
so .Count and foreach work correctly—specifically, change creation of
$wireframes to use an array wrapper (e.g. @(...Get-ChildItem... | ForEach-Object
{ ... })) and ensure the $filtered assignment also wraps the result of the
Where-Object branch (and the else branch) with @(...) so $filtered is always an
array even for a single match.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 211c3ce8-dd5f-4c47-a9d7-cdb5efd5aea0
📒 Files selected for processing (3)
docs/README.mddocs/epics/E02-identity-access/features/F01-authentication.mddocs/scripts/generate-wireframes.ps1
✅ Files skipped from review due to trivial changes (2)
- docs/epics/E02-identity-access/features/F01-authentication.md
- docs/README.md
| $wireframes = Get-ChildItem -Path $wireframesRoot -Filter "*.excalidraw" -Recurse | | ||
| ForEach-Object { | ||
| @{ | ||
| src = $_.FullName | ||
| svg = [System.IO.Path]::ChangeExtension($_.FullName, ".svg") | ||
| } | ||
| } | ||
|
|
||
| $filtered = if ($Filter) { $wireframes | Where-Object { $_.src -like "*$Filter*" } } else { $wireframes } |
There was a problem hiding this comment.
Single-match filtering can break iteration and count.
On Line 35 and Line 43, single-result pipeline output can collapse to a scalar hashtable. That makes $filtered.Count incorrect and can break foreach ($w in $filtered) (iterating keys/entries instead of wireframe objects), which impacts the documented -Filter "login" path.
Suggested fix
-$wireframes = Get-ChildItem -Path $wireframesRoot -Filter "*.excalidraw" -Recurse |
- ForEach-Object {
- @{
- src = $_.FullName
- svg = [System.IO.Path]::ChangeExtension($_.FullName, ".svg")
- }
- }
+$wireframes = @(
+ Get-ChildItem -Path $wireframesRoot -Filter "*.excalidraw" -Recurse |
+ ForEach-Object {
+ [pscustomobject]@{
+ src = $_.FullName
+ svg = [System.IO.Path]::ChangeExtension($_.FullName, ".svg")
+ }
+ }
+)
-$filtered = if ($Filter) { $wireframes | Where-Object { $_.src -like "*$Filter*" } } else { $wireframes }
+$filtered = @(
+ if ($Filter) { $wireframes | Where-Object { $_.src -like "*$Filter*" } } else { $wireframes }
+)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| $wireframes = Get-ChildItem -Path $wireframesRoot -Filter "*.excalidraw" -Recurse | | |
| ForEach-Object { | |
| @{ | |
| src = $_.FullName | |
| svg = [System.IO.Path]::ChangeExtension($_.FullName, ".svg") | |
| } | |
| } | |
| $filtered = if ($Filter) { $wireframes | Where-Object { $_.src -like "*$Filter*" } } else { $wireframes } | |
| $wireframes = @( | |
| Get-ChildItem -Path $wireframesRoot -Filter "*.excalidraw" -Recurse | | |
| ForEach-Object { | |
| [pscustomobject]@{ | |
| src = $_.FullName | |
| svg = [System.IO.Path]::ChangeExtension($_.FullName, ".svg") | |
| } | |
| } | |
| ) | |
| $filtered = @( | |
| if ($Filter) { $wireframes | Where-Object { $_.src -like "*$Filter*" } } else { $wireframes } | |
| ) |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/scripts/generate-wireframes.ps1` around lines 35 - 43, The pipeline
building $wireframes and the conditional assigning $filtered can collapse to a
single scalar hashtable when only one match is found; wrap the pipeline outputs
in array subexpression to force arrays so .Count and foreach work
correctly—specifically, change creation of $wireframes to use an array wrapper
(e.g. @(...Get-ChildItem... | ForEach-Object { ... })) and ensure the $filtered
assignment also wraps the result of the Where-Object branch (and the else
branch) with @(...) so $filtered is always an array even for a single match.
1 participant
Summary
docs/PROCESS.md(new) — step-by-step checklists for backend (module setup + per-US TDD workflow) and frontend (Phase 1 foundation + Phase 2 per-feature workflow); extracted from CLAUDE.md to keep it conciselogin.excalidraw(login screen) +_template.excalidraw(full UI component kit with 12 sections: color palette, typography, buttons, form controls, badges, navigation, sidebar, table, cards, feedback, modal, app shell); generated bygenerate-template.mjsdocs/scripts/generate-wireframes.ps1mirrorsgenerate-diagrams.ps1; POSTs.excalidrawto Kroki.io/excalidraw/svgand saves the result; Kroki only supports SVG (not PNG) for Excalidraw, and SVG renders inline on GitHub and scales better as a vector formatDocs updated
CLAUDE.md— wireframe convention updated to.svg, generation script referenceddocs/PATTERNS.md— wireframe pattern updated with SVG workflow and pitfall notedocs/PROCESS.md— step 2 updated to includegenerate-wireframes.ps1docs/README.md— wireframes section added with navigation tabledocs/epics/E02-identity-access/features/F01-authentication.md— wireframe callout updated to.svgTest plan
docs/wireframes/login.svg— renders the login screen wireframedocs/wireframes/_template.svg— renders all 12 UI component sections.\docs\scripts\generate-wireframes.ps1— regenerates both SVGs successfullynode docs/wireframes/generate-template.mjs— regenerates_template.excalidraw🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores