Skip to content

refactor: consolidate design folders under design/#16

Open
singyichen wants to merge 10 commits intomainfrom
refactor/design-folder-restructure
Open

refactor: consolidate design folders under design/#16
singyichen wants to merge 10 commits intomainfrom
refactor/design-folder-restructure

Conversation

@singyichen
Copy link
Copy Markdown
Owner

@singyichen singyichen commented Mar 27, 2026

Summary

  • Move design-system/design/system/
  • Move pencil/design/wireframes/
  • Move prototype/design/prototype/
  • Update all path references in CLAUDE.md, SKILL.md, scripts/pencil-save.sh, and design/system/MASTER.md
  • Add design/prototype/pages/profile.html and specs/002-profile-settings/spec.md

Test Plan

  • All design folders accessible under design/
  • Path references updated in CLAUDE.md, SKILL.md, scripts/pencil-save.sh, design/system/MASTER.md

🤖 Generated with Claude Code


Open with Devin

singyichen and others added 2 commits March 27, 2026 15:47
- design-system/ → design/system/
- pencil/        → design/wireframes/
- prototype/     → design/prototype/

Update all path references in CLAUDE.md, SKILL.md,
scripts/pencil-save.sh, and design/system/MASTER.md.

NOTE: Pencil app repository path must be updated to
design/wireframes/ in Windsurf settings.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Fix: translate prototype QA description to English
- Add design/prototype/pages/profile.html
- Add specs/002-profile-settings/spec.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@qodo-code-review
Copy link
Copy Markdown

Review Summary by Qodo

Consolidate design folders and add profile settings prototype with bilingual support

✨ Enhancement 📝 Documentation

Grey Divider

Walkthroughs

Description
• Consolidate design folders under design/ hierarchy for better organization
  - Move design-system/design/system/
  - Move pencil/design/wireframes/
  - Move prototype/design/prototype/
• Add profile settings page prototype with bilingual (ZH/EN) support
  - Create design/prototype/pages/profile.html with full UI implementation
  - Add specs/002-profile-settings/spec.md with user stories and acceptance criteria
• Update all path references across documentation and scripts
  - Update CLAUDE.md, SKILL.md, scripts/pencil-save.sh, design/system/MASTER.md
  - Add Pencil wireframe convention and workflow documentation
Diagram
flowchart LR
  A["design-system/<br/>pencil/<br/>prototype/"] -->|"Reorganize"| B["design/system/<br/>design/wireframes/<br/>design/prototype/"]
  B -->|"Add prototype"| C["design/prototype/<br/>pages/profile.html"]
  B -->|"Add spec"| D["specs/002-profile-settings/<br/>spec.md"]
  C -->|"Bilingual UI"| E["ZH/EN Support<br/>with i18n"]
  D -->|"User Stories"| F["P1: Profile Edit<br/>P2: Language Switch"]
Loading

Grey Divider

File Changes

1. design/prototype/pages/profile.html ✨ Enhancement +516/-0

Add bilingual profile settings page prototype

design/prototype/pages/profile.html


2. specs/002-profile-settings/spec.md 📝 Documentation +70/-0

Add profile settings feature specification

specs/002-profile-settings/spec.md


3. scripts/pencil-save.sh ⚙️ Configuration changes +3/-3

Update pencil script paths to new structure

scripts/pencil-save.sh


View more (10)
4. .claude/skills/ui-ux-pro-max/SKILL.md 📝 Documentation +5/-5

Update design system paths in skill documentation

.claude/skills/ui-ux-pro-max/SKILL.md


5. CLAUDE.md 📝 Documentation +19/-5

Update design folder paths and add workflow conventions

CLAUDE.md


6. design/system/MASTER.md 📝 Documentation +1/-1

Update design system reference path

design/system/MASTER.md


7. design/prototype/index.html Additional files +0/-0

...

design/prototype/index.html


8. design/prototype/pages/dashboard.html Additional files +0/-0

...

design/prototype/pages/dashboard.html


9. design/prototype/pages/login.html Additional files +0/-0

...

design/prototype/pages/login.html


10. design/wireframes/design-system.pen Additional files +0/-0

...

design/wireframes/design-system.pen


11. design/wireframes/index.pen Additional files +0/-0

...

design/wireframes/index.pen


12. design/wireframes/pages/dashboard.pen Additional files +0/-0

...

design/wireframes/pages/dashboard.pen


13. design/wireframes/pages/login.pen Additional files +0/-0

...

design/wireframes/pages/login.pen


Grey Divider

Qodo Logo

@qodo-code-review
Copy link
Copy Markdown

qodo-code-review bot commented Mar 27, 2026

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Grey Divider


Action required

1. previewAvatar() uses innerHTML📘 Rule violation ⛨ Security
Description
The avatar preview injects user-controlled data (FileReader result) into the DOM using
innerHTML, which can enable XSS if content-type checks are bypassed or misreported. This violates
the requirement to validate/sanitize user input before rendering or echoing it.
Code

design/prototype/pages/profile.html[R435-440]

+      const reader = new FileReader();
+      reader.onload = e => {
+        const preview = document.getElementById('avatar-preview');
+        preview.innerHTML = `<img src="${e.target.result}" alt="${STRINGS[currentLang]['avatar-preview-alt']}" class="w-full h-full object-cover" />`;
+      };
+      reader.readAsDataURL(file);
Evidence
PR Compliance ID 10 requires sanitizing/validating user-controlled input before rendering; the new
code assigns a user-derived string (e.target.result) into the DOM via innerHTML when previewing
an uploaded file.

CLAUDE.md
design/prototype/pages/profile.html[435-440]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The avatar preview uses `innerHTML` to render user-controlled data from `FileReader`, which can create an XSS sink.
## Issue Context
Even with MIME checks, relying on `innerHTML` for untrusted content is unsafe. Prefer creating an `img` element and setting `src`/`alt` via DOM APIs (or using `URL.createObjectURL(file)`), and avoid HTML string injection.
## Fix Focus Areas
- design/prototype/pages/profile.html[415-441]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


2. Prototype deploy path outdated🐞 Bug ⛯ Reliability
Description
.github/workflows/deploy-prototype.yml still triggers on and uploads prototype/, but the
prototype content now lives under design/prototype/, so deployments won’t run (and would upload a
non-existent directory).
Code

CLAUDE.md[208]

+/ui-ux-pro-max                          → design/prototype/ + design/system/  (optional, UI-heavy features)
Evidence
The repo documentation now points prototypes to design/prototype/, but the GitHub Pages workflow
is still wired to prototype/** and prototype/, which no longer exists in the repo after this
refactor.

.github/workflows/deploy-prototype.yml[1-35]
CLAUDE.md[112-117]
design/prototype/index.html[1-11]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The GitHub Pages workflow still deploys from `prototype/`, but prototypes were moved to `design/prototype/`. This prevents the workflow from triggering on prototype changes and makes the upload step point at a missing directory.
### Issue Context
Prototype files are now under `design/prototype/`.
### Fix Focus Areas
- .github/workflows/deploy-prototype.yml[1-35]
- Update `on.push.paths` from `prototype/**` to `design/prototype/**`
- Update `actions/upload-pages-artifact` `path:` from `prototype/` to `design/prototype/`

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


3. Design system path hardcoded🐞 Bug ✓ Correctness
Description
UI/UX Pro Max persistence code still writes and documents design-system/..., so generated design
system files will be created in the wrong location relative to the new design/system/...
structure.
Code

.claude/skills/ui-ux-pro-max/SKILL.md[R161-162]

+- `design/system/MASTER.md` — Global Source of Truth with all design rules
+- `design/system/pages/` — Folder for page-specific overrides
Evidence
Docs and the checked-in master design system file use design/system/..., but the generator/CLI
scripts still hardcode design-system/... for directory creation, help text, and printed guidance.
This will recreate the old folder and break the intended consolidated layout.

.claude/skills/ui-ux-pro-max/SKILL.md[152-176]
design/system/MASTER.md[1-6]
.claude/skills/ui-ux-pro-max/scripts/design_system.py[461-539]
.claude/skills/ui-ux-pro-max/scripts/search.py[1-99]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
After consolidating design folders under `design/`, the UI/UX Pro Max scripts still persist outputs to `design-system/...` and instruct users to read from `design-system/...`. This diverges from `design/system/...` used elsewhere in the repo.
### Issue Context
- Docs now say persisted files live under `design/system/`.
- Scripts still create and reference `design-system/`.
### Fix Focus Areas
- .claude/skills/ui-ux-pro-max/scripts/design_system.py[490-535]
- Change persisted base directory from `design-system` to `design/system`
- Update any embedded markdown strings referencing `design-system/...`
- .claude/skills/ui-ux-pro-max/scripts/design_system.py[542-563]
- Update `format_master_md` logic header paths
- .claude/skills/ui-ux-pro-max/scripts/search.py[12-15]
- Update usage docs in module docstring
- .claude/skills/ui-ux-pro-max/scripts/search.py[64-99]
- Update argparse help text and printed persistence confirmation paths

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


View more (1)
4. Wireframe docs still pencil🐞 Bug ⚙ Maintainability
Description
CLAUDE.md still instructs storing wireframes under pencil/... even though wireframes were moved
to design/wireframes/, which will send users/agents to non-existent paths.
Code

CLAUDE.md[R266-267]

+- Each page wireframe is stored as a separate file under `pencil/pages/[page-name].pen` (e.g. `login.pen`, `profile.pen`)
+- `pencil/index.pen` is for overview purposes only — **do not** place page wireframe frames inside it
Evidence
The Communication section was updated to allow Traditional Chinese under design/wireframes/, and
the Pencil save script examples were updated to design/wireframes/..., but multiple later CLAUDE
workflow sections still reference pencil/pages/... and pencil/index.pen.

CLAUDE.md[112-117]
CLAUDE.md[206-217]
CLAUDE.md[249-270]
scripts/pencil-save.sh[1-26]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`CLAUDE.md` contains conflicting wireframe storage instructions: it acknowledges `design/wireframes/` but still tells users/agents to use `pencil/pages/...` and `pencil/index.pen`.
### Issue Context
Wireframes now live under `design/wireframes/`.
### Fix Focus Areas
- CLAUDE.md[206-217]
- Update `/pencil wireframe` output path from `pencil/pages/[page].pen` to `design/wireframes/pages/[page].pen`
- CLAUDE.md[249-270]
- Update the wireframe command table row and “Pencil Wireframe Convention” section to use `design/wireframes/...` consistently

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

ⓘ The new review experience is currently in Beta. Learn more

Grey Divider

Qodo Logo

qodo-code-review[bot]

This comment was marked as resolved.

singyichen and others added 5 commits March 30, 2026 09:43
- fix: replace innerHTML with DOM API in previewAvatar() to prevent XSS
- fix: update deploy-prototype.yml paths from prototype/ to design/prototype/
- fix: update design_system.py persist path from design-system/ to design/system/
- fix: update search.py help text and output paths to design/system/
- fix: update CLAUDE.md wireframe paths from pencil/ to design/wireframes/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add ui-ux-pro-max pre-generation reminder in CLAUDE.md
- Update design/system/MASTER.md with revised design system rules
- Update design/wireframes/design-system.pen wireframe
- Update SKILL.md with design system path adjustments

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
devin-ai-integration[bot]

This comment was marked as resolved.

- fix: update stale pencil/pages/ path to design/wireframes/pages/ in CLAUDE.md workflow section
- fix: add Pattern C (Header + Sidebar + Content) to MASTER.md for Profile pages,
  resolving inconsistency between profile.html sidebar layout and Pattern A spec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
devin-ai-integration[bot]

This comment was marked as resolved.

singyichen and others added 2 commits March 31, 2026 09:26
- Update docstrings at lines 471 and 493
- Update format_page_override_md output at line 822
All changed from design-system/ to design/system/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…profile wireframe

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Copy link
Copy Markdown

@devin-ai-integration devin-ai-integration bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 2 new potential issues.

View 12 additional findings in Devin Review.

Open in Devin Review

Comment on lines +1 to +5
{
"version": "2.9",
"children": [
{
"type": "frame",
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 profile.pen has only 2 frames instead of required 6, violating Pencil Wireframe Convention

The newly added design/wireframes/pages/profile.pen contains only 2 top-level frames ("Profile Desktop (ZH)" at x:0 and "Profile Desktop (EN)" at x:1520), but CLAUDE.md's Pencil Wireframe Convention (CLAUDE.md:284) mandates that each .pen file under pages/ must contain 6 side-by-side frames: Desktop ZH, Desktop EN, Mobile ZH (x:3000), Mobile EN (x:4500), Component ZH (x:6000), and Component EN (x:7500). The 4 missing frames (Mobile ZH, Mobile EN, Component ZH, Component EN) are required by the convention established in this same PR.

Prompt for agents
Add 4 missing frames to design/wireframes/pages/profile.pen to comply with the Pencil Wireframe Convention in CLAUDE.md:284-293. The file currently has only Desktop ZH (x:0) and Desktop EN (x:1520). Add:
1. Mobile ZH frame at x:3000 (mobile-width version of the profile page in Traditional Chinese)
2. Mobile EN frame at x:4500 (mobile-width version in English)
3. Component ZH frame at x:6000 (reusable UI component set — avatar upload, form fields, language toggle, toast — in ZH)
4. Component EN frame at x:7500 (same component set in EN)
Also fix the Desktop EN x-offset from 1520 to 1500 per the convention table. Use Pencil MCP tools to make these changes — do not edit the .pen file directly.
Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

{
"type": "frame",
"id": "uXyra",
"x": 1520,
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 profile.pen Desktop EN frame at x:1520 instead of convention-mandated x:1500

The "Profile Desktop (EN)" frame in design/wireframes/pages/profile.pen is positioned at x: 1520, but the Pencil Wireframe Convention in CLAUDE.md:289 specifies Desktop EN must be at x:1500. This is inconsistent with the convention established in this PR. Note: the existing dashboard.pen and login.pen also use x:1520, suggesting this may be a systemic mismatch between the convention as written and the actual files.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant