Product Design QA

Comparison target

Source visual truth: research/selected-visual-target.png
Normalized source: research/qa-source-normalized.jpg
Implementation screenshot: research/qa-implementation-1536-compose.png
Full-view comparison evidence: research/qa-comparison-rendered-pass2.png
Focused comparison evidence: research/qa-focus-comparison-rendered-pass2.png
Source original pixels: 1487 × 1058
Source normalized pixels: 1536 × 1024
Implementation pixels: 1536 × 1024
CSS viewport: 1536 × 1024
Density normalization: source was resampled once to the implementation viewport; implementation capture pixels equal CSS pixels, so the comparison uses a 1:1 captured density.
State: 03-2. 기준금리, exact source sentence selected, inline selection toolbar visible, contextual question panel open in compose state.

The selected ImageGen visual is the primary visual target. design.md and the user’s explicit component and interaction requirements are the product truth where the generated image omitted required top-navigation actions, approval states, edit controls, or realistic long-form content.

Findings

No actionable P0, P1, or P2 findings remain.

[P3] Learning-objective treatment is slightly more prominent in the implementation.
- Location: LearningPage header.
- Evidence: the source target uses a thin neutral outline, while the implementation uses a pale warm fill plus a rust left rule.
- Impact: the learning objective receives slightly more emphasis, but it remains subordinate to the page title and improves long-form scanning.
- Follow-up: if a stricter visual match is desired, replace the filled surface with a white background and 1px warm-gray outline.
[P3] Context input focus ring is stronger than the static source target.
- Location: ContextPanel question textarea.
- Evidence: the implementation shows a 2px rust keyboard focus ring; the generated target shows a lighter border.
- Impact: small fidelity drift, but the stronger treatment is retained for keyboard accessibility.
- Follow-up: none required unless the product later defines a dedicated focus token.

Required fidelity surfaces

Fonts and typography

Passed. The implementation uses one Korean-compatible system stack, a 34px restrained page title, 17px/1.74 long-form body text, compact 12–14px document navigation, stable weights, and Korean-aware line breaking. Compared with the generated target, the implementation intentionally uses slightly larger body type and more line height because the user explicitly required 16–18px text and long-session readability.

Spacing and layout rhythm

Passed. The 56px header, persistent hierarchical table of contents, constrained reading column, 360px context panel, sentence-margin marker, thin dividers, 6–7px radii, and low-shadow toolbar preserve the target’s three-column hierarchy. The implementation includes more vertical whitespace than the generated target, which is intentional for real 17px Korean content.

At 1440 × 1024, the reading surface remains centered and book-like. At 1280 × 800, measurements were:

table of contents: 232px
reading page: 666px with the panel open
contextual panel: 340px
header: 56px
body scroll width: 1280px

No persistent control was clipped or pushed off screen.

Colors and visual tokens

Passed after one iteration. The selected target’s restrained rust accent was applied as #A34D3B, with warm selection and question-anchor surfaces. Paper, navigation, borders, proposal, and revision surfaces remain neutral and do not use gradients, glass, decorative shadows, or purple AI styling.

Image quality and asset fidelity

Passed / not materially applicable. The app contains no illustrative or photographic assets in this first-pass reading experience. All functional icons use lucide-react; no custom SVG, CSS drawing, emoji substitute, placeholder image, or decorative raster was introduced.

Copy and content

Passed. Visible copy is natural Korean and specific to the requested economics book. The page includes a learning objective, realistic paragraphs, an example, a conceptual callout, comparison table, self-check, sources, and previous/next navigation. The question and AI answer match the requested examples, while the approved explanation reads naturally after insertion.

Icons

Passed. Header, tree, toolbar, marker, panel, proposal, editing, source, and navigation controls use a consistent Lucide outline family at 14–20px with accessible Korean labels.

States and interactions

Passed in the browser:

default reading state
chapter collapse and expand
table-of-contents page navigation
previous and next page navigation
exact source-sentence selection
floating selection toolbar
contextual panel open
contextual question submission
loading state and realistic AI answer
inline insertion preview
direct proposal editing
proposal approval
integrated explanation block
question marker reopening the correct thread
reading/editing mode switch
editable content blocks
block duplicate, transform, move, and delete
slash-menu block insertion
state preservation while navigating between mock pages
1280px narrow desktop behavior

No browser console errors were present during the full question and answer flow.

Accessibility

Passed for the scoped prototype:

semantic buttons, headings, navigation, labels, table headers, and source list
Korean accessible names for icon-only controls
2px visible keyboard focus ring
Escape closes the contextual panel and returns focus to #source-paragraph
selection uses highlight, underline, and an icon marker rather than color alone
reduced-motion media query disables nonessential animation
question submission communicates disabled and loading states
source return, close, apply, cancel, and edit actions are keyboard reachable

Comparison history

Pass 1

Finding: [P1] the implementation used a deep-teal accent while the selected visual target used a muted rust accent.
Evidence: research/qa-comparison-rendered.png and research/qa-focus-comparison-rendered.png.
Fix: changed the accent, active navigation, selected sentence, focus, marker, and contextual surfaces to the rust family; updated the product color rules in design.md.

Pass 2

Post-fix evidence: research/qa-comparison-rendered-pass2.png and research/qa-focus-comparison-rendered-pass2.png.
Result: the primary accent, selection, panel, and inline toolbar now match the selected visual direction. No actionable P0/P1/P2 mismatch remains. The denser source text, shorter source top bar, and simpler source navigation are accepted generated-mock limitations because the implementation follows the user’s explicit content, typography, and navigation requirements.

Pass 3: full interaction and narrow-desktop audit

Evidence: audit/01-default-reading-1440.png through audit/10-narrow-panel-1280-fixed.png.
Completed the exact anchored-question flow, including selection, contextual question, answer, insertion preview, approval, marker reopening, and navigation away from and back to the source page.
Completed the edit-mode flow and verified block handles, direct text editing, AI block action, and the ten-item slash menu.
Verified chapter collapse/expand, table-of-contents navigation, previous/next navigation, and state preservation.
Verified a visible 2px keyboard focus outline and an empty browser warning/error log.
Finding fixed: at 1280 × 800 the context panel grid item could grow beyond the workspace instead of giving its body an internal scroll area.
Fix: added min-height: 0 to .context-panel and .context-scroll. The panel is now 744px tall below the 56px header, while .context-scroll independently scrolls its 902px content inside a 678px viewport.
Final result: no horizontal overflow at 1280px (body.scrollWidth === 1280) and all contextual actions remain reachable.

Pass 4: Figma and live-prototype alignment

Evidence: audit-alignment/07-prototype-expanded-final.png, audit-alignment/05-figma-default-after.png, audit-alignment/08-prototype-collapsed-final.png, and audit-alignment/06-figma-toc-collapsed-after.png.
Replaced the former card-like Figma reading screen with the live prototype’s plain documentation hierarchy, 260px table of contents, centered 780px reading column, 56px header, and matching long-form vertical rhythm.
Added a 56px collapsed table-of-contents rail with an expand control, book identity, chapter shortcuts, and a non-color-only current-chapter indicator.
Wired the Figma collapse/expand controls between the expanded screen (70:2) and collapsed screen (89:532).
Added the same collapse/expand behavior to the React prototype; the current page and learning state are preserved during the transition.
The comparison at 1440 × 1024 shows matching header placement, reading-column width, source paragraph line breaks, example block, section rhythm, and collapsed-rail behavior.
Figma uses Noto Sans KR for the rebuilt text nodes because Pretendard Variable is not available in the connected Figma font environment; visual hierarchy and measurements were matched against the live Pretendard-rendered prototype.

Pass 5: shared components and page-outline alignment

Evidence: audit-alignment/10-prototype-default-current.jpg, audit-alignment/11-prototype-collapsed-current.jpg, audit-alignment/figma-01.png through audit-alignment/figma-08.png, and audit-alignment/figma-screen-comparison.html.
Changed the page label from 이 페이지에서 배울 내용 to 목차.
Matched all three page-outline labels exactly to their body H2 headings: 기준금리란 무엇인가, 기준금리는 어떻게 결정될까, 기준금리 변화가 전달되는 길.
Added Figma component sets for App Header (Read/Edit × 1440/1280) and Book TOC (Expanded/Collapsed), plus a Page Outline component.
Replaced the header and book TOC on screens 1–8 with instances of those masters. Screen 6 uses the Edit variant, screen 7 uses the 1280 variant, and screen 8 uses the Collapsed TOC variant.
Synced screens 2–5 and 7 to the same long-form reading layout used by the live prototype and screen 8 while preserving their toolbar, contextual panel, proposal, approved block, marker, and edit-state overlays.
Added interactive variant changes for read/edit and TOC expanded/collapsed controls in the component masters.
Structural verification found no visible stale outline labels and confirmed every screen has the three exact matching headings.
Browser verification completed the anchored-question flow, answer insertion preview, approval, question-marker reopening, edit-mode transition, expanded/collapsed TOC, page-outline anchor movement, and a visible 2px keyboard focus outline.
Current visual result: no actionable P0/P1/P2 mismatch. The Figma font remains Noto Sans KR because Pretendard is unavailable in the connected Figma environment.

Pass 6: Figma learning-mode extension

Figma file: HdxjSbLGMouLWHXKd5K50G
Visual comparison evidence: audit/learning-mode/handoff-qa.png
Desktop evidence: audit/learning-mode/desktop-default.png and audit/learning-mode/desktop-failure.png
Responsive evidence: audit/learning-mode/responsive-1280-fixed.png and audit/learning-mode/responsive-1024-fixed.png
The existing Wiki Mode and the new Learning Mode were placed side by side in 10. Handoff at the same rendered width. The 56px header, warm paper surface, rust accent, thin borders, restrained radii, Korean type hierarchy, and document-first density remain visibly consistent.
The 1440px default layout preserves a 380px learning guide and a 592px usable editor. When the contextual Agent opens, the guide yields its space and the editor grows to 656px instead of becoming a narrow IDE column.
At 1280px the book navigation becomes a 64px rail. At 1024px the file tree is hidden and the editor remains 564px wide.
Fixed during this pass:
- the responsive header instance covering the Workspace Mode switch;
- 1024px secondary tools clipping beyond the viewport;
- the Agent opening automatically on failure instead of waiting for the user action;
- missing Terminal close and Agent close paths.
Prototype verification:
- two named start points exist on 09. Prototype;
- the primary flow contains 15 frames from Wiki Mode through a saved Wiki note;
- environment setup, initial test execution, and retest use timed transitions;
- command execution, file mutation, and Wiki insertion require explicit click approval;
- the 1280px flow connects balanced, code-focus, guide-focus, and Agent-open states.
Accessibility checks:
- status surfaces include text labels in addition to color;
- Diff rows include 삭제/추가 labels and -/+ line prefixes;
- code and terminal typography use 14/22px and 13/20px respectively;
- the handoff specifies a 2px accent focus ring and keyboard order.
Final result: no actionable P0, P1, or P2 finding remains for the scoped Figma prototype.

Pass 7: local Home and Learning Mode prototype

Visual targets:
- Home: /Users/wars/.codex/generated_images/019fac18-fbca-7a40-aed2-10185f220efd/call_VeH4i3ayFrPhuB32MwDhmOhZ.png
- Learning Mode: audit/learning-mode/desktop-default.png
Normalized and rendered evidence:
- audit/local-prototype/home-reference-1440.png
- audit/local-prototype/home-1440.png
- audit/local-prototype/practice-default-1440.png
- audit/local-prototype/home-comparison.png
- audit/local-prototype/practice-comparison.png
Responsive evidence:
- audit/local-prototype/home-1280.png
- audit/local-prototype/home-1024.png
- audit/local-prototype/practice-default-1280.png
- audit/local-prototype/practice-default-1024.png
State evidence:
- audit/local-prototype/command-approval-1440.png
- audit/local-prototype/test-failed-1440.png
- audit/local-prototype/agent-error-1440.png
- audit/local-prototype/diff-review-1440.png
- audit/local-prototype/change-applied-1440.png
- audit/local-prototype/test-passed-1440.png
- audit/local-prototype/save-note-preview-1440.png
- audit/local-prototype/wiki-saved-note-1440.png
- audit/local-prototype/home-search-1440.png
- audit/local-prototype/home-keyboard-focus-1440.png
Capture settings: 1440 × 900, 1280 × 800, and 1024 × 768 CSS pixels at 1:1 screenshot density. The Home source was resampled once from 1586 × 992 to 1440 × 900 for structural comparison.
The generated Home reference and implementation share the same shell, left navigation, continue-learning hierarchy, two-column book library, and recent-learning rail. Minor text rasterization and content-fit differences are accepted because the generated target is an art-direction mock rather than a production bitmap contract.
The Learning Mode implementation preserves the selected Figma composition and adds the user's latest requirement: a permanently visible project file tree. At 1024px, the practice navigation becomes a 56px rail while the 168px file tree remains visible.
Manual interaction pass:
- Home search filters the local book library.
- Home opens the Spring Wiki and Learning Mode while retaining the current book and page.
- Test execution requires explicit approval.
- A failing test exposes the exact 404 output and an error-owned Agent panel.
- Agent help escalates from explanation to a reviewable /post → /posts Diff.
- File mutation occurs only after 적용.
- Retesting reaches PostControllerTest PASSED.
- Saving the lesson opens a preview before integrating the practice note into the Wiki page.
Keyboard and browser audit:
- A visible 2px rust focus outline is present on the primary Home action.
- Production preview produced no browser console errors or uncaught page errors.
- React Doctor reported zero errors and no diagnostics in the newly added Home, Learning Mode, Wiki bridge, or primitive files. The remaining 23 warnings are confined to the pre-existing src/App.jsx.
Objective image-diff evidence:
- Home: dimensions match, alpha intact. The raw score is intentionally not used as a pass/fail metric because the generated reference contains different raster antialiasing across nearly every neutral pixel; the side-by-side comparison is the primary visual evidence.
- Learning Mode: dimensions match, alpha intact, 52/100 pixel similarity. The largest hotspots correspond to the intentionally added file-tree column and the reference's wider blank editor region; structure, typography, color, and panel hierarchy match visibly.
No actionable P0, P1, or P2 visual issue remains in the scoped local prototype.

Pass 8: learning-book types and mouse workspace composition

Evidence:
- audit/local-prototype/book-types/home-types-1440.png
- audit/local-prototype/book-types/economics-wiki-only-1440.png
- audit/local-prototype/book-types/economics-edit-draggable-1440.png
- audit/local-prototype/book-types/economics-block-reordered-1440.png
- audit/local-prototype/book-types/practice-resizers-default-1440.png
- audit/local-prototype/book-types/practice-panels-resized-1440.png
- audit/local-prototype/book-types/practice-terminal-resized-1440.png
- audit/local-prototype/book-types/practice-resizers-1024.png
Book typing:
- Home book covers now identify 위키형 학습서 and 실습형 학습서.
- The economics and interest-rate Wiki exposes document Read/Edit only; it contains no Wiki/Learning workspace switch or Learning Mode CTA.
- The Spring Boot Wiki retains its Learning Mode switch because it owns a connected practice folder and executable steps.
Mouse interaction:
- In Wiki Edit mode, dragging the second paragraph block handle above the first changed the rendered block order while preserving both editable texts.
- In Learning Mode, dragging the guide separator changed the guide from 380px to 428px.
- Dragging the file-tree separator changed the tree from 184px to its 144px minimum without hiding it.
- Dragging the terminal separator upward changed the terminal from 240px to 320px.
- 패널 구성 초기화 restored the terminal to 240px and cleared custom layout variables.
Responsive and accessibility:
- At 1024 × 768 the navigation remains 56px, guide 260px, file tree 168px, and code workspace 478px with no horizontal overflow.
- Every panel boundary is a keyboard-focusable separator with orientation and min/current/max values; direction keys resize in 8px steps.
Final result: no actionable P0, P1, or P2 finding remains for the scoped interaction change.

Implementation checklist

Follow-up polish

Consider a slightly quieter learning-objective surface if later screens make the top of the page feel too dense.
Define a formal focus-ring token when the broader design system is created.
Replace the static code surface with Monaco only when the technical prototype starts exercising real filesystem edits.

final result: passed

FilesExpand file tree

design-qa.md

Latest commit

History