From 1261b3c4e3ce40f8d4af742d384ef189387b399e Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Thu, 2 Jul 2026 08:14:44 +0900 Subject: [PATCH 1/6] docs: plan product design figma workflow --- docs/ui-ux/README.md | 5 + docs/ui-ux/product-design-audit.md | 289 ++++++++++++++++++ .../product-design-figma-execution-plan.md | 189 ++++++++++++ 3 files changed, 483 insertions(+) create mode 100644 docs/ui-ux/product-design-audit.md create mode 100644 docs/ui-ux/product-design-figma-execution-plan.md diff --git a/docs/ui-ux/README.md b/docs/ui-ux/README.md index 5a5d50c0..4a936552 100644 --- a/docs/ui-ux/README.md +++ b/docs/ui-ux/README.md @@ -8,6 +8,11 @@ These reference screens define the intended product direction for Cloud ERD UI w - Modals should be centered, restrained, and form-first. - The ERD editor should prioritize canvas space, toolbars, side properties, sharing, and export workflows. +Execution planning: + +- [Product Design and Figma execution plan](product-design-figma-execution-plan.md) +- [Product Design UX audit](product-design-audit.md) + Screens: 1. `01-login-screen.png` diff --git a/docs/ui-ux/product-design-audit.md b/docs/ui-ux/product-design-audit.md new file mode 100644 index 00000000..93e80262 --- /dev/null +++ b/docs/ui-ux/product-design-audit.md @@ -0,0 +1,289 @@ +# Product Design UX Audit + +Date: 2026-07-02 + +Audit scope: `pg-erd-cloud` workspace from project entry through ERD inspection, +editing, share, and export. + +Evidence used in this pass: + +- Repository screenshots in `docs/ui-ux/01-login-screen.png` through + `docs/ui-ux/09-share-export-modal.png`. +- Current frontend source in `frontend/src/App.tsx`, + `frontend/src/styles.css`, `frontend/src/erd/TableNode.tsx`, and + `frontend/src/components/modals/*`. + +Evidence limits: + +- This is a local repository audit, not a completed Figma-board audit. A Figma + file URL/file key or plan key is still needed before screenshots and notes can + be placed in Figma. +- Screenshots show the intended product direction, while source review shows the + current implementation. Live keyboard traversal, screen-reader output, backend + latency, and real database-scale behavior still need browser verification. + +## Flow Steps + +1. Login/auth gate + - Health: usable direction, needs live validation. + - Evidence: `01-login-screen.png`, auth-gate code in `frontend/src/App.tsx`. + +2. Dashboard overview + - Health: strong information architecture direction. + - Evidence: `02-dashboard-screen.png`; current dashboard, metrics, project + cards, and recent diagram table in `frontend/src/App.tsx`. + +3. Project list + - Health: clear enough for MVP, needs density and empty-state polish. + - Evidence: `03-project-list-screen.png`; project list rows and inline create + path in `frontend/src/App.tsx`. + +4. Diagram list + - Health: clear enough for snapshot browsing, needs state clarity. + - Evidence: `04-diagram-list-screen.png`; `DiagramTable` and status pills in + `frontend/src/App.tsx` and `frontend/src/styles.css`. + +5. New diagram / connection setup + - Health: functionally present, but the workflow is split between reference + modal direction and current editor-sidebar implementation. + - Evidence: `05-new-diagram-modal.png`; project, connection, DSN, schema + filter, and snapshot controls in `frontend/src/App.tsx`. + +6. ERD editor + - Health: strongest surface in the product, with dense controls and useful + accessibility hooks; needs clearer visual grouping. + - Evidence: `06-erd-editor-main.png`; toolbar, React Flow canvas, empty/busy + state, minimap, controls, and table nodes in `frontend/src/App.tsx`, + `frontend/src/styles.css`, and `frontend/src/erd/TableNode.tsx`. + +7. Add/edit entity + - Health: covers core editing, but modal styling is less consistent than the + newer modal shell. + - Evidence: `07-add-entity-modal.png`; `EditTableModal.tsx`, + `AddTableModal.tsx`, and modal CSS. + +8. Relationship settings + - Health: usable for MVP relationship labeling, needs clearer destructive and + save/cancel hierarchy. + - Evidence: `08-relationship-settings-modal.png`; `EditEdgeModal.tsx`. + +9. Share/export + - Health: strategically important and already implemented as a combined + modal; needs clearer separation of sharing, DDL, and image/diagram exports. + - Evidence: `09-share-export-modal.png`; `ExportModal.tsx` and export toolbar + entry points in `frontend/src/App.tsx`. + +## Findings + +### P1. Setup workflow is split between the product concept and current editor sidebar + +Evidence: + +- The reference set includes a new-diagram modal, while the current implementation + exposes project selection, project creation, connection creation, DSN entry, + schema filtering, and snapshot creation inside the editor sidebar. +- In `frontend/src/App.tsx`, the editor-only sidebar controls run from project + selection through `Reverse engineer -> snapshot`. + +Impact: + +- First-time users can complete the task, but the path is operationally dense + before they understand what the ERD editor is for. +- The dashboard and list screens sell a workspace model, while the editor sidebar + carries setup, configuration, status, and navigation at once. + +Recommendation: + +- Keep the sidebar for selected-project context and advanced controls. +- Move first-run project/connection/snapshot creation into a guided "New + diagram" or "Create snapshot" modal/drawer that matches `05-new-diagram-modal`. +- In Figma, prototype both states: first-run setup and returning-user editor. + +### P1. ERD toolbar has many compact controls with mixed symbolic labels + +Evidence: + +- Toolbar labels include `↔`, `↶`, `+`, `◇`, `#`, `SQL`, `↗`, `IMG`, `UML`, and + `{}` in `frontend/src/App.tsx`. +- CSS gives each toolbar button a compact 44 x 40 minimum target. + +Impact: + +- The toolbar is dense, which is appropriate for an editor, but the visual + language mixes symbols, abbreviations, and text labels. +- Screen-reader labels are present, but sighted users must rely on hover titles + for several actions. + +Recommendation: + +- Define a Figma toolbar component with grouped regions: layout, create/edit, + analysis, share/export. +- Replace symbolic labels with consistent icon buttons plus tooltips, keeping + visible text only where the term itself is the format (`SQL`, `UML`). +- Add the grouped toolbar to the first implementation PR only after the Figma + direction is approved, because tests currently assert several visible labels. + +### P1. Share/export is strategically central but visually overloaded + +Evidence: + +- The reference screen shows share and export as two side-by-side concepts. +- `ExportModal.tsx` combines project share-link generation and DDL copy in a + single modal. Separate toolbar actions also trigger SVG, PlantUML, and Mermaid + exports directly from the toolbar. + +Impact: + +- Users may not understand which exports are project-level share links, which + are current-canvas text exports, and which are immediate file downloads. +- This matters because share links expose API-backed project resources while DDL, + SVG, PlantUML, and Mermaid are different artifact types. + +Recommendation: + +- In Figma, redesign share/export as a two-column or tabbed modal with clear + sections: Share link, SQL DDL, Diagram image, Diagram text formats. +- Add explicit disabled reasons and copy feedback to every export type. +- In code, route all export-related actions through one modal once the visual + model is approved. + +### P2. Modal system is partly consolidated and partly bespoke + +Evidence: + +- `ExportModal.tsx` uses `modalContent`, `modalHeader`, and structured sections. +- `EditTableModal.tsx` still uses a `modal` class with inline width, max-height, + overflow, row, spacing, and button styles. +- `useDialogAccessibility.ts` provides useful focus trapping, Escape handling, + and focus return behavior. + +Impact: + +- Accessibility behavior is on the right track, but visual consistency and + maintainability are uneven across modals. +- Inline styles make it harder to map modals cleanly into Figma components and + design tokens. + +Recommendation: + +- Create a Figma `Modal/Shell` component and variant rules for default, + destructive, form-heavy, and split-section modals. +- Refactor modal CSS toward shared classes before broad visual polish. +- Keep `useDialogAccessibility` as a strength and verify it with keyboard tests. + +### P2. ERD table nodes optimize density, but large schemas need progressive disclosure + +Evidence: + +- `TableNode.tsx` renders title, comment, group badge, PK/FK badges, column + comments, example values, data types, NOT NULL badges, and indexes. +- The component renders up to 25 columns and four indexes before showing a + "more" indicator. + +Impact: + +- Dense schema context is valuable, but nodes can become tall and visually noisy + as comments, examples, and indexes accumulate. +- Users auditing relationships may need a quick "keys only" or "compact" mode + before reading all metadata. + +Recommendation: + +- In Figma, define three table-node density variants: compact, standard, and + detail. +- Keep comments/examples/indexes available, but make detail expansion explicit. +- Validate with a stress case containing long schema/table names, 25+ columns, + multiple indexes, and business group badges. + +### P2. Responsive behavior exists, but mobile/narrow-width product intent is unclear + +Evidence: + +- CSS includes breakpoints at `1180px` and `767px`. +- At small widths, the sidebar becomes a top region, nav becomes four columns, + data tables scroll horizontally, and the canvas toolbar stretches across the + top of the canvas. + +Impact: + +- The product is primarily a desktop ERD editor. Narrow layouts are present, but + the expected mobile task is not defined. +- Without a target task, mobile work may become a compromised version of a + desktop editor rather than a useful review/share experience. + +Recommendation: + +- Define narrow-width scope as "review and share" unless full mobile editing is + explicitly required. +- In Figma, create a narrow review-mode screen that prioritizes project summary, + diagram preview, search, and share/export over full canvas editing. + +### P3. Design tokens are implicit in CSS rather than explicit in a system + +Evidence: + +- CSS repeats key colors such as `#034ea2`, `#e5e7eb`, `#64748b`, `#0f172a`, + `#f8fafc`, and `#fff`. +- Radius, spacing, focus ring, table density, and modal shadow values are defined + directly in component classes. + +Impact: + +- The visual direction is coherent, but Figma cannot stay linked to code without + named tokens. +- Future PRs may drift if each screen hardcodes spacing and colors independently. + +Recommendation: + +- Define Figma variables for color, spacing, radius, shadow, typography, focus, + and status. +- Mirror the naming in CSS custom properties before the first broad visual PR. + +### P3. Current screenshot references are useful but not yet an editable design system + +Evidence: + +- `docs/ui-ux` contains nine raster reference screens and a concise direction + note. +- There is no Figma file link, component inventory, token inventory, or design QA + baseline in the repository yet. + +Impact: + +- The team has product direction, but not a durable editable source for design + review, prototype links, or implementation handoff. + +Recommendation: + +- Use the execution plan in + `docs/ui-ux/product-design-figma-execution-plan.md` to create a Figma file + with pages for references, foundations, components, prototype, and QA. +- Add the Figma file link back to `docs/ui-ux/README.md` after creation. + +## Strengths To Preserve + +- The existing direction is appropriately work-focused: no marketing hero, + restrained color, compact tables, and a persistent workspace frame. +- Accessibility basics are already considered: skip link, focus-visible styles, + dialog focus trap, Escape close behavior, focus return, `aria-live`, and + `role="alert"` appear in the implementation. +- ERD-specific capabilities are real product differentiators: React Flow canvas, + table search/highlight, auto-layout, business grouping, cardinality + recommendations, generated examples, and multiple export formats. +- The reference screenshots already cover the major workspace states needed for + a first Figma design system pass. + +## Recommended First PR After Figma Review + +Start with the share/export surface because it is central to collaboration, +already has a focused component (`ExportModal.tsx`), and has clear reference +material in `09-share-export-modal.png`. + +Suggested PR scope: + +- Redesign the modal into clearer sections for share link, DDL, and diagram + exports. +- Keep existing API behavior unchanged. +- Add or update tests for disabled states, copy feedback, and error rendering. +- Verify with `cd frontend && npm run typecheck`, `cd frontend && npm test`, and + `cd frontend && npm run build`. diff --git a/docs/ui-ux/product-design-figma-execution-plan.md b/docs/ui-ux/product-design-figma-execution-plan.md new file mode 100644 index 00000000..3db5d5b0 --- /dev/null +++ b/docs/ui-ux/product-design-figma-execution-plan.md @@ -0,0 +1,189 @@ +# Product Design and Figma Execution Plan + +This plan turns the current `pg-erd-cloud` MVP into a repeatable Product Design +and Figma workflow. It is grounded in the current product surface, not a generic +design exercise. + +## Current Product Evidence + +- Product: PostgreSQL and Snowflake schema reverse engineering, ERD rendering, + snapshot export, reversing-spec generation, and share links. +- Frontend: React 19, Vite, and React Flow under `frontend/src`. +- Existing UI reference source: `docs/ui-ux/README.md` and the nine PNG screens + in `docs/ui-ux`. +- Current visual direction: quiet work-focused layout, persistent left sidebar, + light palette, blue primary actions, thin borders, subtle shadows, compact + tables, and dense ERD editor controls. +- Product font basis in code: `system-ui, -apple-system, Segoe UI, Roboto, + sans-serif`. + +## Design Brief + +Design and validate a practical Cloud ERD workspace for database engineers and +technical teammates who need to connect a database, create a schema snapshot, +inspect the ERD, adjust metadata, export DDL or diagrams, and share the result. +The interface should feel like an operational tool: dense, calm, keyboard and +screen-reader aware, and optimized for repeated use rather than marketing. + +## Work Packages + +### 1. Product Design UX Audit + +Scope: + +- Login/auth gate. +- Dashboard and recent-project/recent-diagram overview. +- Project list and diagram list. +- ERD editor canvas, toolbar, minimap, table nodes, and empty/busy states. +- Add/edit table, relationship, business group, cardinality, share/export + modals. + +Audit checks: + +- Whether the primary workflow is obvious: create project, add connection, + create snapshot, open ERD, share or export. +- Whether disabled states explain what is required next. +- Whether the editor uses canvas space efficiently on desktop and narrower + screens. +- Whether toolbar labels, icon-only controls, focus states, live regions, and + dialog focus traps are sufficient. +- Whether table nodes remain legible with many columns, comments, examples, + indexes, PK/FK badges, and business groups. +- Whether share/export choices map cleanly to current API capabilities. + +Deliverable: + +- `docs/ui-ux/product-design-audit.md` with findings ordered by severity, each + tied to the relevant screen, source component, and proposed fix. + +### 2. Figma File and Design System Setup + +Required input: + +- Existing Figma design file URL or file key, or a Figma plan key so a new file + can be created. + +Proposed Figma pages: + +- `00 Intake`: product brief, source links, open decisions. +- `01 Current References`: the nine existing `docs/ui-ux` screenshots and any + captured running-app screens. +- `02 Foundations`: color, typography, radius, spacing, shadow, focus, and + status tokens. +- `03 Components`: sidebar, nav item, button, input, select, metric card, data + table, status pill, ERD table node, toolbar button, modal shell, share/export + controls. +- `04 Core Flow Prototype`: connected screens for connection-to-share workflow. +- `05 QA and Handoff`: visual diffs, acceptance checklist, implementation notes. + +Figma tool use: + +- Use `get_libraries` and `search_design_system` before recreating components, + variables, or styles. +- Use `generate_figma_design` to capture the running web app into the target + Figma file when a local or deployed URL is available. +- Use `use_figma` to build editable screens from components, tokens, and + auto-layout frames, using the app font family confirmed from CSS. +- Validate with Figma screenshots after each major section and verify no text is + clipped or overlapping. + +Deliverable: + +- Editable Figma file containing the source references, componentized screens, + and a clickable prototype. + +### 3. Core Prototype Flow + +Prototype path: + +1. Auth gate or signed-in workspace entry. +2. Dashboard with recent projects and diagrams. +3. Project creation or project selection. +4. Connection creation with DSN validation guidance. +5. Snapshot creation and busy/empty states. +6. ERD editor with search, auto-layout, table add/edit, relationship edit, + business grouping, cardinality recommendations, and exports. +7. Share/export modal with link creation, copy feedback, and DDL export. + +Interaction level: + +- First pass: clickable screen prototype with modal open/close states and + realistic data. +- Second pass: local frontend prototype or code PR only after the first pass is + reviewed. + +Deliverables: + +- Figma prototype links for the desktop flow. +- Optional local coded prototype when a selected visual direction needs richer + interaction. + +### 4. Design QA Before Implementation + +Compare: + +- Existing screenshots in `docs/ui-ux`. +- Running local app screenshots at desktop width and a narrower viewport. +- Figma componentized output. + +QA checks: + +- Sidebar width, spacing, active states, and focus visibility. +- Dashboard card density and table scannability. +- Modal padding, title hierarchy, close button affordance, and form-first layout. +- ERD canvas framing, toolbar density, minimap placement, and empty/busy states. +- Table node readability for long names, comments, examples, badges, and indexes. +- Export/share copy, loading, error, and disabled states. +- Keyboard flow and dialog focus return. + +Deliverable: + +- `docs/ui-ux/design-qa-report.md` with screenshots or Figma node links, + mismatches, decisions, and implementation-ready fixes. + +### 5. Implementation PR Path + +Only start code changes after the audit and Figma direction identify a specific +screen or interaction to update. + +Candidate frontend targets: + +- `frontend/src/App.tsx` for workspace flow, editor toolbar, empty states, and + share/export entry points. +- `frontend/src/styles.css` for design tokens, density, focus states, responsive + layout, and visual polish. +- `frontend/src/erd/TableNode.tsx` for ERD node readability, badges, indexes, + comments, and example values. +- `frontend/src/components/modals/*` for modal structure, copy, disabled states, + and accessibility refinements. + +Verification: + +- `cd frontend && npm run typecheck` +- `cd frontend && npm test` +- `cd frontend && npm run build` +- Browser screenshot check for dashboard, editor, and share/export modal. + +Deliverable: + +- A focused PR with the design decision, Figma/screenshot evidence, and test + output in the PR body. + +## Immediate Next Actions + +1. Confirm whether to create a new Figma file or use an existing Figma design + file. +2. Run the Product Design audit against the current screenshots and source UI. +3. If a Figma target is available, import/capture the current references and + create the page structure above. +4. Build the first clickable prototype around the connection-to-share workflow. +5. Use the prototype review to choose the first implementation PR. + +## Open Inputs + +- Figma target: existing design file URL/file key or plan key for new-file + creation. +- Preferred prototype fidelity: static clickable prototype or richer local coded + prototype. +- First implementation priority: audit fixes, ERD editor, share/export, or + onboarding/dashboard. From 47b4e7dc15546162b4b10cb4be015fe7170bdb0c Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Thu, 2 Jul 2026 08:19:36 +0900 Subject: [PATCH 2/6] docs: add figjam core user flow --- docs/ui-ux/README.md | 2 + docs/ui-ux/core-user-flow.mmd | 69 +++++++++++++++++++ .../product-design-figma-execution-plan.md | 4 ++ 3 files changed, 75 insertions(+) create mode 100644 docs/ui-ux/core-user-flow.mmd diff --git a/docs/ui-ux/README.md b/docs/ui-ux/README.md index 4a936552..ed850bc6 100644 --- a/docs/ui-ux/README.md +++ b/docs/ui-ux/README.md @@ -12,6 +12,8 @@ Execution planning: - [Product Design and Figma execution plan](product-design-figma-execution-plan.md) - [Product Design UX audit](product-design-audit.md) +- [Core user flow Mermaid source](core-user-flow.mmd) +- [Core user flow FigJam board](https://www.figma.com/board/kHs1cKzwGzkNIBNaMt0xVq?utm_source=codex&utm_content=edit_in_figjam&oai_id=&request_id=b079e329-893d-4418-8909-b22a816fa588) Screens: diff --git a/docs/ui-ux/core-user-flow.mmd b/docs/ui-ux/core-user-flow.mmd new file mode 100644 index 00000000..3948c5f0 --- /dev/null +++ b/docs/ui-ux/core-user-flow.mmd @@ -0,0 +1,69 @@ +flowchart LR + start(["Signed-in workspace"]) + + subgraph intake ["Workspace setup"] + dashboard["Dashboard overview"] + project{ "Project exists?" } + createProject["Create project"] + selectProject["Select project"] + connection{ "Connection exists?" } + createConnection["Save PostgreSQL or Snowflake DSN"] + schemaFilter["Set optional schema filter"] + end + + subgraph snapshotPhase ["Reverse engineering"] + createSnapshot["Create schema snapshot"] + snapshotStatus{ "Snapshot status" } + retrySnapshot["Fix DSN or retry"] + snapshotReady["Snapshot succeeded"] + end + + subgraph editorPhase ["ERD editor"] + renderErd["Render React Flow ERD"] + searchTables["Search tables and columns"] + autoLayout["Auto-layout canvas"] + editTables["Add or edit tables"] + editRelations["Edit relationships"] + groupTables["Assign business groups"] + cardinality["Review cardinality recommendations"] + end + + subgraph handoffPhase ["Share and export"] + openExport["Open share/export modal"] + shareLink["Create share link"] + ddlExport["Copy SQL DDL"] + diagramExport["Download SVG, PlantUML, or Mermaid"] + teammate["Teammate reviews shared ERD"] + end + + start --> dashboard + dashboard --> project + project -->|"No"| createProject + project -->|"Yes"| selectProject + createProject --> selectProject + selectProject --> connection + connection -->|"No"| createConnection + connection -->|"Yes"| schemaFilter + createConnection --> schemaFilter + schemaFilter --> createSnapshot + createSnapshot --> snapshotStatus + snapshotStatus -->|"Failed"| retrySnapshot + retrySnapshot --> createConnection + snapshotStatus -->|"Succeeded"| snapshotReady + snapshotReady --> renderErd + renderErd --> searchTables + renderErd --> autoLayout + renderErd --> editTables + renderErd --> editRelations + renderErd --> groupTables + renderErd --> cardinality + searchTables & autoLayout & editTables & editRelations & groupTables & cardinality --> openExport + openExport --> shareLink + openExport --> ddlExport + openExport --> diagramExport + shareLink --> teammate + + style intake fill:#E8F2FF,stroke:#3D7DD8 + style snapshotPhase fill:#FFF2D8,stroke:#D99A20 + style editorPhase fill:#EAF7EA,stroke:#3A9B4A + style handoffPhase fill:#F1E8FF,stroke:#7B61D1 diff --git a/docs/ui-ux/product-design-figma-execution-plan.md b/docs/ui-ux/product-design-figma-execution-plan.md index 3db5d5b0..1bb10cb6 100644 --- a/docs/ui-ux/product-design-figma-execution-plan.md +++ b/docs/ui-ux/product-design-figma-execution-plan.md @@ -11,6 +11,9 @@ design exercise. - Frontend: React 19, Vite, and React Flow under `frontend/src`. - Existing UI reference source: `docs/ui-ux/README.md` and the nine PNG screens in `docs/ui-ux`. +- Core flow source: `docs/ui-ux/core-user-flow.mmd`. +- Generated FigJam flow board: + . - Current visual direction: quiet work-focused layout, persistent left sidebar, light palette, blue primary actions, thin borders, subtle shadows, compact tables, and dense ERD editor controls. @@ -115,6 +118,7 @@ Interaction level: Deliverables: - Figma prototype links for the desktop flow. +- FigJam user-flow board for the core connection-to-share journey. - Optional local coded prototype when a selected visual direction needs richer interaction. From 5cd8f24c2cbe0e53b593a71779ef739f866dc59a Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Thu, 2 Jul 2026 08:21:29 +0900 Subject: [PATCH 3/6] docs: add design qa checklist --- docs/ui-ux/README.md | 1 + docs/ui-ux/design-qa-checklist.md | 136 ++++++++++++++++++ .../product-design-figma-execution-plan.md | 2 + 3 files changed, 139 insertions(+) create mode 100644 docs/ui-ux/design-qa-checklist.md diff --git a/docs/ui-ux/README.md b/docs/ui-ux/README.md index ed850bc6..261a884e 100644 --- a/docs/ui-ux/README.md +++ b/docs/ui-ux/README.md @@ -12,6 +12,7 @@ Execution planning: - [Product Design and Figma execution plan](product-design-figma-execution-plan.md) - [Product Design UX audit](product-design-audit.md) +- [Design QA checklist](design-qa-checklist.md) - [Core user flow Mermaid source](core-user-flow.mmd) - [Core user flow FigJam board](https://www.figma.com/board/kHs1cKzwGzkNIBNaMt0xVq?utm_source=codex&utm_content=edit_in_figjam&oai_id=&request_id=b079e329-893d-4418-8909-b22a816fa588) diff --git a/docs/ui-ux/design-qa-checklist.md b/docs/ui-ux/design-qa-checklist.md new file mode 100644 index 00000000..a22e6ce5 --- /dev/null +++ b/docs/ui-ux/design-qa-checklist.md @@ -0,0 +1,136 @@ +# Design QA Checklist + +Use this checklist before implementing or merging UI changes derived from the +Product Design and Figma work. It is not a final QA report by itself; a passing +QA decision requires side-by-side evidence from both a source visual target and a +rendered implementation. + +## Required Evidence + +- Source visual target: + - Figma design node, FigJam flow board, screenshot, mockup, or `docs/ui-ux` + reference PNG. + - Record the URL or file path. +- Rendered implementation: + - Local or deployed app screenshot of the same state. + - Record the URL, viewport, browser, and screenshot file path. +- Same-state match: + - Same route or workspace view. + - Same selected project/diagram state. + - Same modal open/closed state. + - Same data density where possible. + - Same viewport class: desktop editor, narrow review layout, or modal-focused + capture. + +## Required Screens + +Run the QA pass on these screens before broad UI implementation: + +1. Auth gate or signed-in entry. +2. Dashboard with recent projects and diagrams. +3. Project list with empty and populated states. +4. Diagram list with empty, running, succeeded, and failed statuses when + available. +5. First-run setup path for project, connection, DSN, schema filter, and + snapshot creation. +6. ERD editor with at least four tables, relationships, minimap, toolbar, and + search. +7. ERD editor empty state and snapshot-running state. +8. Table node stress state with long names, comments, examples, PK/FK badges, + NOT NULL badges, indexes, and business group badge. +9. Add/edit table modal. +10. Relationship settings modal. +11. Business group modal. +12. Cardinality recommendation modal. +13. Share/export modal with no project, loading, success, copy-feedback, error, + and no-DDL states. +14. Narrow viewport review/share state. + +## Fidelity Surfaces + +### Fonts and Typography + +- Product font family follows the source target and implementation CSS. +- Heading, body, table, caption, badge, and monospace export text sizes are + visually consistent. +- Line heights do not crop Korean or English text. +- Long schema, table, column, index, and URL values wrap or truncate + intentionally. +- Button and toolbar labels fit their controls at all required viewport widths. + +### Spacing and Layout Rhythm + +- Sidebar width, padding, and section gaps match the design target. +- Dashboard cards and tables align to the same grid rhythm. +- Toolbar groups do not overlap the canvas, minimap, empty state, or React Flow + controls. +- Modals preserve header, section, form, and action spacing at desktop and narrow + widths. +- Table node density remains scannable with high metadata volume. + +### Colors and Visual Tokens + +- Primary blue, active states, focus ring, borders, neutral text, status colors, + and modal shadows map to named Figma variables or CSS custom properties. +- Disabled states remain legible and distinguishable from active controls. +- Status pills communicate succeeded, failed, running, and not-found states + without relying on color alone. +- Business group colors remain distinguishable against table-node backgrounds. + +### Image and Asset Fidelity + +- Use real source screenshots, Figma captures, product icons, or an approved icon + library. +- Do not replace product-relevant icons or screenshots with placeholder boxes, + CSS drawings, text glyphs, or handcrafted approximations. +- ERD canvas captures must show real table-node content, relationship lines, and + controls rather than blank canvas placeholders. + +### Copy and Content + +- Korean and English labels use one consistent product voice per surface. +- Toolbar, modal, and disabled-state copy explains the next action. +- Share/export copy distinguishes project share links from DDL text and diagram + file exports. +- DSN and schema-filter hints are explicit about PostgreSQL and Snowflake. +- Error states say what failed and what the user can try next. + +## Accessibility Checks + +- Keyboard can reach every visible control in a logical order. +- Skip link lands on the main workspace. +- Focus ring is visible against all backgrounds. +- Dialogs trap focus, close on Escape, and return focus to the opener. +- Destructive actions are not adjacent to primary actions without enough visual + separation. +- `aria-live` regions announce snapshot, copy, loading, and search-result + changes without excessive noise. +- Icon-only toolbar actions have accessible names and visible tooltips. +- Tables and table-like rows expose useful structure to assistive tech. + +## QA Report Format + +Save each implementation QA pass as `docs/ui-ux/design-qa-report.md` or as a +dated file under `docs/ui-ux/qa/`. + +Required fields: + +- Source visual truth path or Figma node URL. +- Implementation URL and screenshot path. +- Viewport and state. +- Full-view comparison evidence. +- Focused-region comparison evidence for toolbar, table node, and modal details, + or a reason focused regions were not needed. +- Findings ordered by severity. +- Fix checklist. +- Final result: `passed` or `blocked`. + +Use `passed` only when no actionable P0, P1, or P2 findings remain. P3 polish +can remain as follow-up. Use `blocked` when any actionable P0, P1, or P2 finding +remains. + +## First QA Target + +Start with the share/export modal because it is the recommended first +implementation surface from `product-design-audit.md` and has a clear existing +reference in `09-share-export-modal.png`. diff --git a/docs/ui-ux/product-design-figma-execution-plan.md b/docs/ui-ux/product-design-figma-execution-plan.md index 1bb10cb6..b6c1ec09 100644 --- a/docs/ui-ux/product-design-figma-execution-plan.md +++ b/docs/ui-ux/product-design-figma-execution-plan.md @@ -142,6 +142,8 @@ QA checks: Deliverable: +- `docs/ui-ux/design-qa-checklist.md` as the standing pre-implementation QA + gate. - `docs/ui-ux/design-qa-report.md` with screenshots or Figma node links, mismatches, decisions, and implementation-ready fixes. From 22228c4e4c274091f94a31b2a7104c5df228ad45 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Thu, 2 Jul 2026 08:28:41 +0900 Subject: [PATCH 4/6] docs: link figma design kit --- docs/ui-ux/README.md | 1 + docs/ui-ux/product-design-figma-execution-plan.md | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/docs/ui-ux/README.md b/docs/ui-ux/README.md index 261a884e..4c732c87 100644 --- a/docs/ui-ux/README.md +++ b/docs/ui-ux/README.md @@ -14,6 +14,7 @@ Execution planning: - [Product Design UX audit](product-design-audit.md) - [Design QA checklist](design-qa-checklist.md) - [Core user flow Mermaid source](core-user-flow.mmd) +- [Product Design Kit Figma file](https://www.figma.com/design/OTN0rBGtnVy0P7yq4Iv9Si) - [Core user flow FigJam board](https://www.figma.com/board/kHs1cKzwGzkNIBNaMt0xVq?utm_source=codex&utm_content=edit_in_figjam&oai_id=&request_id=b079e329-893d-4418-8909-b22a816fa588) Screens: diff --git a/docs/ui-ux/product-design-figma-execution-plan.md b/docs/ui-ux/product-design-figma-execution-plan.md index b6c1ec09..b37197ee 100644 --- a/docs/ui-ux/product-design-figma-execution-plan.md +++ b/docs/ui-ux/product-design-figma-execution-plan.md @@ -12,6 +12,8 @@ design exercise. - Existing UI reference source: `docs/ui-ux/README.md` and the nine PNG screens in `docs/ui-ux`. - Core flow source: `docs/ui-ux/core-user-flow.mmd`. +- Product Design Kit Figma file: + . - Generated FigJam flow board: . - Current visual direction: quiet work-focused layout, persistent left sidebar, @@ -94,6 +96,8 @@ Deliverable: - Editable Figma file containing the source references, componentized screens, and a clickable prototype. +- Initial Figma file created with pages for intake, current references, + foundations, components, core prototype flow, and QA/handoff. ### 3. Core Prototype Flow From aa49c02a254b4e8f76d44e2849de74e47b98416f Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Thu, 2 Jul 2026 08:39:42 +0900 Subject: [PATCH 5/6] docs: record figma reference placement --- docs/ui-ux/README.md | 1 + docs/ui-ux/product-design-audit.md | 9 +++++--- .../product-design-figma-execution-plan.md | 21 ++++++++++--------- 3 files changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/ui-ux/README.md b/docs/ui-ux/README.md index 4c732c87..a6e90ed0 100644 --- a/docs/ui-ux/README.md +++ b/docs/ui-ux/README.md @@ -15,6 +15,7 @@ Execution planning: - [Design QA checklist](design-qa-checklist.md) - [Core user flow Mermaid source](core-user-flow.mmd) - [Product Design Kit Figma file](https://www.figma.com/design/OTN0rBGtnVy0P7yq4Iv9Si) + with the nine screenshots placed on `01 Current References` - [Core user flow FigJam board](https://www.figma.com/board/kHs1cKzwGzkNIBNaMt0xVq?utm_source=codex&utm_content=edit_in_figjam&oai_id=&request_id=b079e329-893d-4418-8909-b22a816fa588) Screens: diff --git a/docs/ui-ux/product-design-audit.md b/docs/ui-ux/product-design-audit.md index 93e80262..0aa71415 100644 --- a/docs/ui-ux/product-design-audit.md +++ b/docs/ui-ux/product-design-audit.md @@ -9,15 +9,18 @@ Evidence used in this pass: - Repository screenshots in `docs/ui-ux/01-login-screen.png` through `docs/ui-ux/09-share-export-modal.png`. +- Figma Product Design Kit + , where the same nine + screenshots are placed on `01 Current References`. - Current frontend source in `frontend/src/App.tsx`, `frontend/src/styles.css`, `frontend/src/erd/TableNode.tsx`, and `frontend/src/components/modals/*`. Evidence limits: -- This is a local repository audit, not a completed Figma-board audit. A Figma - file URL/file key or plan key is still needed before screenshots and notes can - be placed in Figma. +- This is a repository-plus-reference audit, not a completed browser-observed + usability study. The source screenshots are now available in Figma, but live + interaction evidence still needs browser capture. - Screenshots show the intended product direction, while source review shows the current implementation. Live keyboard traversal, screen-reader output, backend latency, and real database-scale behavior still need browser verification. diff --git a/docs/ui-ux/product-design-figma-execution-plan.md b/docs/ui-ux/product-design-figma-execution-plan.md index b37197ee..911f7f7e 100644 --- a/docs/ui-ux/product-design-figma-execution-plan.md +++ b/docs/ui-ux/product-design-figma-execution-plan.md @@ -10,7 +10,7 @@ design exercise. snapshot export, reversing-spec generation, and share links. - Frontend: React 19, Vite, and React Flow under `frontend/src`. - Existing UI reference source: `docs/ui-ux/README.md` and the nine PNG screens - in `docs/ui-ux`. + in `docs/ui-ux`, now placed on the Figma `01 Current References` page. - Core flow source: `docs/ui-ux/core-user-flow.mmd`. - Product Design Kit Figma file: . @@ -98,6 +98,8 @@ Deliverable: and a clickable prototype. - Initial Figma file created with pages for intake, current references, foundations, components, core prototype flow, and QA/handoff. +- `01 Current References` populated with all nine repository screenshots as + editable image-fill cards using `FIT` scale mode. ### 3. Core Prototype Flow @@ -181,18 +183,17 @@ Deliverable: ## Immediate Next Actions -1. Confirm whether to create a new Figma file or use an existing Figma design - file. -2. Run the Product Design audit against the current screenshots and source UI. -3. If a Figma target is available, import/capture the current references and - create the page structure above. -4. Build the first clickable prototype around the connection-to-share workflow. -5. Use the prototype review to choose the first implementation PR. +1. Review the Product Design audit findings and choose the first design problem + to resolve in Figma. +2. Componentize the highest-priority screens in the Product Design Kit: + sidebar, toolbar, modal shell, table node, and share/export controls. +3. Build the first clickable prototype around the connection-to-share workflow. +4. Capture the running local app into Figma when a browser-verifiable URL is + available, then compare it against the repository screenshots. +5. Use the prototype review to choose the first focused implementation PR. ## Open Inputs -- Figma target: existing design file URL/file key or plan key for new-file - creation. - Preferred prototype fidelity: static clickable prototype or richer local coded prototype. - First implementation priority: audit fixes, ERD editor, share/export, or From e5562a8f617ebf8cc7d6ca852eaaef4bff457a58 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Thu, 2 Jul 2026 09:21:01 +0900 Subject: [PATCH 6/6] docs: update figma design system status --- docs/ui-ux/README.md | 12 +++- docs/ui-ux/design-qa-checklist.md | 22 ++++++ docs/ui-ux/product-design-audit.md | 42 ++++++++--- .../product-design-figma-execution-plan.md | 72 ++++++++++++++++--- 4 files changed, 128 insertions(+), 20 deletions(-) diff --git a/docs/ui-ux/README.md b/docs/ui-ux/README.md index a6e90ed0..5270cb52 100644 --- a/docs/ui-ux/README.md +++ b/docs/ui-ux/README.md @@ -15,9 +15,19 @@ Execution planning: - [Design QA checklist](design-qa-checklist.md) - [Core user flow Mermaid source](core-user-flow.mmd) - [Product Design Kit Figma file](https://www.figma.com/design/OTN0rBGtnVy0P7yq4Iv9Si) - with the nine screenshots placed on `01 Current References` + with the nine screenshots placed on `01 Current References`, local variables + on `02 Foundations`, component sets on `03 Components`, and a desktop core + flow prototype on `04 Core Flow Prototype` - [Core user flow FigJam board](https://www.figma.com/board/kHs1cKzwGzkNIBNaMt0xVq?utm_source=codex&utm_content=edit_in_figjam&oai_id=&request_id=b079e329-893d-4418-8909-b22a816fa588) +Current Figma implementation anchors: + +- [Foundations](https://www.figma.com/design/OTN0rBGtnVy0P7yq4Iv9Si?node-id=17-2) +- [ERD table node variants](https://www.figma.com/design/OTN0rBGtnVy0P7yq4Iv9Si?node-id=25-78) +- [Toolbar button variants](https://www.figma.com/design/OTN0rBGtnVy0P7yq4Iv9Si?node-id=28-33) +- [Share/export modal states](https://www.figma.com/design/OTN0rBGtnVy0P7yq4Iv9Si?node-id=29-143) +- [Core flow prototype](https://www.figma.com/design/OTN0rBGtnVy0P7yq4Iv9Si?node-id=32-2) + Screens: 1. `01-login-screen.png` diff --git a/docs/ui-ux/design-qa-checklist.md b/docs/ui-ux/design-qa-checklist.md index a22e6ce5..b805b953 100644 --- a/docs/ui-ux/design-qa-checklist.md +++ b/docs/ui-ux/design-qa-checklist.md @@ -22,6 +22,25 @@ rendered implementation. - Same viewport class: desktop editor, narrow review layout, or modal-focused capture. +## Current Figma Baseline + +Use these source nodes for the first implementation comparison pass: + +- Component foundations: + +- ERD table node density variants: + +- Editor toolbar button variants: + +- Share/export modal states: + +- Core flow prototype dashboard: + + +The Figma component and prototype screenshots were checked for clipped text and +overlap during the design pass. A code implementation still requires a separate +browser screenshot comparison before merge. + ## Required Screens Run the QA pass on these screens before broad UI implementation: @@ -134,3 +153,6 @@ remains. Start with the share/export modal because it is the recommended first implementation surface from `product-design-audit.md` and has a clear existing reference in `09-share-export-modal.png`. + +First source target: + diff --git a/docs/ui-ux/product-design-audit.md b/docs/ui-ux/product-design-audit.md index 0aa71415..5a560fa2 100644 --- a/docs/ui-ux/product-design-audit.md +++ b/docs/ui-ux/product-design-audit.md @@ -25,6 +25,27 @@ Evidence limits: current implementation. Live keyboard traversal, screen-reader output, backend latency, and real database-scale behavior still need browser verification. +## Figma Follow-Through Status + +The first Figma pass now covers the highest-priority audit findings: + +- Setup workflow: `04 Core Flow Prototype` includes a guided connection setup + frame between dashboard and ERD editor. +- Toolbar density: `PG ERD Toolbar Button` defines fixed-size icon and format + button variants for the editor toolbar. +- Share/export overload: `PG ERD Share Export Modal` separates share links, + SQL DDL, diagram image, and Mermaid export rows, with ready, copied, and error + states. +- Modal consistency: the share/export modal component provides the first modal + shell candidate for implementation alignment. +- Table node density: `PG ERD Table Node` defines compact, standard, and detail + variants. +- Token drift: `02 Foundations` defines local Figma variables and text/effect + styles that can be mirrored into frontend CSS custom properties. + +Implementation is still pending. Treat the Figma work as the visual source for +the next focused code PR, not as proof that the production UI already changed. + ## Flow Steps 1. Login/auth gate @@ -248,20 +269,22 @@ Evidence: - `docs/ui-ux` contains nine raster reference screens and a concise direction note. -- There is no Figma file link, component inventory, token inventory, or design QA - baseline in the repository yet. +- The Figma file now contains editable pages, component sets, variables, and a + prototype, but the repository still needs to keep this status synchronized as + the design evolves. Impact: -- The team has product direction, but not a durable editable source for design - review, prototype links, or implementation handoff. +- The team has product direction and an editable Figma source, but future PRs + can still drift if design status, token names, and implementation handoff + notes are not maintained together. Recommendation: -- Use the execution plan in - `docs/ui-ux/product-design-figma-execution-plan.md` to create a Figma file - with pages for references, foundations, components, prototype, and QA. -- Add the Figma file link back to `docs/ui-ux/README.md` after creation. +- Keep `docs/ui-ux/product-design-figma-execution-plan.md` and + `docs/ui-ux/README.md` synchronized with important Figma node links. +- Add a design QA report after the first implementation PR compares live app + screenshots against the Figma source. ## Strengths To Preserve @@ -280,7 +303,8 @@ Recommendation: Start with the share/export surface because it is central to collaboration, already has a focused component (`ExportModal.tsx`), and has clear reference -material in `09-share-export-modal.png`. +material in `09-share-export-modal.png` plus a dedicated Figma component set: +. Suggested PR scope: diff --git a/docs/ui-ux/product-design-figma-execution-plan.md b/docs/ui-ux/product-design-figma-execution-plan.md index 911f7f7e..b7400626 100644 --- a/docs/ui-ux/product-design-figma-execution-plan.md +++ b/docs/ui-ux/product-design-figma-execution-plan.md @@ -30,6 +30,51 @@ inspect the ERD, adjust metadata, export DDL or diagrams, and share the result. The interface should feel like an operational tool: dense, calm, keyboard and screen-reader aware, and optimized for repeated use rather than marketing. +## Execution Status + +Status as of 2026-07-02: + +- Figma file structure is in place with pages for intake, current references, + foundations, components, core flow prototype, and QA/handoff. +- `01 Current References` contains all nine repository screenshots as image-fill + cards using `FIT` scale mode. +- `02 Foundations` contains local Figma variables for primitives, semantic + colors, spacing, radius, text styles, modal shadow, and focus ring. The + variable WEB code syntax uses proposed CSS custom property names because the + current frontend still hardcodes the corresponding values. +- `03 Components` contains editable component sets for button, input field, + ERD table node, status pill, toolbar button, and share/export modal. +- `04 Core Flow Prototype` contains four connected desktop frames: + dashboard, connection setup, ERD editor, and share/export. The main CTAs use + Figma `ON_CLICK -> NAVIGATE` prototype reactions. + +Key Figma nodes: + +- Foundations summary: + +- Button component set: + +- Input field component set: + +- ERD table node component set: + +- Status pill component set: + +- Toolbar button component set: + +- Share/export modal component set: + +- Core flow prototype dashboard: + + +Visual checks completed: + +- Foundation summary rendered without clipped text. +- Button, input, table node, status pill, toolbar button, and share/export modal + component sets were screenshot-checked for overlap and text clipping. +- The ERD editor and share/export prototype frames were screenshot-checked after + composition. + ## Work Packages ### 1. Product Design UX Audit @@ -100,6 +145,9 @@ Deliverable: foundations, components, core prototype flow, and QA/handoff. - `01 Current References` populated with all nine repository screenshots as editable image-fill cards using `FIT` scale mode. +- Local variables and component sets now exist in the Figma file. The next code + step is to mirror the token names into CSS custom properties before broader + visual implementation. ### 3. Core Prototype Flow @@ -127,6 +175,8 @@ Deliverables: - FigJam user-flow board for the core connection-to-share journey. - Optional local coded prototype when a selected visual direction needs richer interaction. +- First Figma pass complete: dashboard -> connection setup -> ERD editor -> + share/export, with clickable navigation on the main CTAs. ### 4. Design QA Before Implementation @@ -183,18 +233,20 @@ Deliverable: ## Immediate Next Actions -1. Review the Product Design audit findings and choose the first design problem - to resolve in Figma. -2. Componentize the highest-priority screens in the Product Design Kit: - sidebar, toolbar, modal shell, table node, and share/export controls. -3. Build the first clickable prototype around the connection-to-share workflow. -4. Capture the running local app into Figma when a browser-verifiable URL is - available, then compare it against the repository screenshots. -5. Use the prototype review to choose the first focused implementation PR. +1. Review the Figma component sets and core flow prototype with product and + engineering stakeholders. +2. Choose the first implementation PR scope. The recommended first scope remains + share/export because it has a focused component and clear audit finding. +3. Capture the running local app into Figma when a browser-verifiable URL is + available, then compare it against the repository screenshots and current + Figma components. +4. Mirror the Figma token names into CSS custom properties before broad visual + implementation. +5. Use the implementation QA checklist before merging any UI code PR. ## Open Inputs -- Preferred prototype fidelity: static clickable prototype or richer local coded - prototype. - First implementation priority: audit fixes, ERD editor, share/export, or onboarding/dashboard. +- Whether narrow-width work should stay review/share-only or include full mobile + editing.