@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/external-ui-ux-quality-benchmarks.md

@@ -0,0 +1,79 @@
+# External UI/UX Quality Benchmarks
+
+Use this reference when internal Figma/code evidence is not enough to judge UI/UX quality, launch readiness, accessibility, performance, or iteration metrics.
+
+These are external quality benchmarks, not visual style sources. Do not copy another product's brand, layout, or component appearance.
+
+## Source Anchors
+
+- Nielsen Norman Group: usability heuristics such as system status visibility, user control, consistency, error prevention, recognition over recall, and recovery.
+- W3C WCAG 2.2: accessibility criteria for keyboard, focus, contrast, labels, target size, error identification, and consistent navigation.
+- web.dev Core Web Vitals: Largest Contentful Paint, Cumulative Layout Shift, Interaction to Next Paint, and field/lab measurement.
+- Google HEART framework: product-experience metrics across happiness, engagement, adoption, retention, and task success.
+- Platform/design-system guidance such as Material Design and Atlassian Design System: touch targets, empty/error states, progressive disclosure, feedback, and content clarity.
+
+## Heuristic Review Layer
+
+For every important screen, check:
+
+- **Status visibility**: users can see whether the product is loading, generating, saving, uploading, reviewing, failed, complete, or stale.
+- **User control**: users can cancel, undo, retry, close, go back, clear, edit, regenerate, or recover when the action has consequence.
+- **Consistency**: repeated surfaces use the same action hierarchy, navigation, selected states, empty states, and feedback strength.
+- **Error prevention**: destructive, public, irreversible, expensive, or trust-sensitive actions require clear consequence copy and confirmation.
+- **Recognition over recall**: current object, active mode, applied filters, selected source/context, and next action stay visible.
+- **Recovery**: every recoverable error gives a path forward; unrecoverable errors explain what still works.
+
+## Accessibility Baseline
+
+Before launch or review, verify:
+
+- Every interactive element has an accessible name or visible label.
+- Keyboard/focus behavior works on web for controls, dialogs, menus, popovers, tabs, and drawers.
+- Mobile tap targets are large enough for common platform expectations and not crowded near screen edges.
+- Text and essential icon states have sufficient contrast in normal, disabled, selected, hover, focus, error, and loading states.
+- Error messages identify the field or action and explain the correction.
+- Motion, streaming, progress, and loading indicators do not block comprehension or task completion.
+- Layout works with longer localized strings, larger text settings, and long generated content.
+- **WCAG 2.2 (W3C Recommendation 5 October 2023) added 9 new success criteria; the 6 most product UI surfaces will hit are**: pointer-target ≥24×24 CSS px (AA, SC 2.5.8 — five exceptions per W3C: Spacing where a 24px circle centered on each undersized target does not intersect siblings, Equivalent control elsewhere on the page, Inline-in-text targets, User-agent default controls, Essential when the *presentation* of the target is essential to the information being conveyed and cannot be programmatically determined — narrow scope, e.g. map pins on geographic-density maps or fine-grained selection in a data-viz cluster; this exception is NOT a blanket pass for dense data-table row actions, inline icon buttons in toolbars, or close buttons on cards, which still need 24px geometry or the Spacing/Equivalent exception); focus ring not obscured by sticky bars / cookie banners (AA, SC 2.4.11 Focus Not Obscured Minimum); single-pointer alternative for any *authored* dragging interaction (AA, SC 2.5.7 Dragging Movements — drag-to-reorder, drag-to-resize, draggable map markers, custom-canvas pan; does NOT apply to native browser scroll, OS-level pinch-to-zoom, or assistive-tech gestures, and multipoint gestures like pinch fall under SC 2.5.1 Pointer Gestures, not 2.5.7); accessible authentication without a cognitive-function test like solving puzzles or remembering generated codes (AA, SC 3.3.8 — supporting `autocomplete="username"` and `autocomplete="current-password"` plus allowing paste counts; SMS OTP, email magic link, OAuth, passkeys all satisfy; image-CAPTCHA and "type the code we just showed you" do not); consistent help placement across pages (A, SC 3.2.6); redundant entry — re-using previously entered data unless re-entry is essential (A, SC 3.3.7). The remaining 3 SC (2.4.12 Focus Not Obscured Enhanced AAA, 2.4.13 Focus Appearance AAA, 3.3.9 Accessible Authentication Enhanced AAA) are AAA-only and rarely a launch gate. Treat WCAG 2.2 (not 2.1) as the current acceptance line; 2.1-only audit checklists silently miss the above.
+- **Reduced-motion / color-scheme / contrast / transparency design intent must be declared, not auto-derived from `@media` query alone**. For each non-decorative animation, name whether it is *essential* (progress indicator, drag preview, view transition that conveys a state change) or *decorative* (parallax, autoplay carousel, hover bounce); `prefers-reduced-motion: reduce` should remove or replace decorative motion by default and may shorten essential motion but cannot omit feedback. An explicit in-product opt-in (e.g. user setting "Show celebration animation even when system asks for reduced motion") MAY override the default for brand-splash / completion-celebration moments when policy permits, but the override must be opt-in not opt-out and the default behavior must respect the system preference. `prefers-color-scheme` requires the design system to ship Light + Dark token pairs (no missing pair = no dark-mode claim). `prefers-contrast: more` and `prefers-reduced-transparency` are useful supplements where browser support permits but are NOT Baseline yet — do not gate accessibility compliance on them; route them through a separate "increased contrast" theme variant when product needs require it.
+- **APCA (Accessible Perceptual Contrast Algorithm) is the WCAG 3 / Silver candidate contrast method, not a WCAG 2.2 replacement**. WCAG 2.2 SC 1.4.3 / 1.4.11 (4.5:1 body / 3:1 large text + UI components) remains the legal/audit baseline. APCA can be used as a *supplementary* perceptual check (per APCA Bronze Simple Mode, Lc 75 minimum / Lc 90 preferred for body text) when WCAG 2.x mathematical contrast passes but the result looks washed-out, or when designing dark mode where WCAG 2.x ratios systematically over-permit low-readability combinations. Decision matrix: WCAG 2.x fail blocks accessibility/legal compliance claims regardless of APCA result; WCAG 2.x pass + APCA fail is NOT a WCAG failure but should be treated as a readability / product-quality defect — either adjust the color tokens to also pass APCA Bronze, or document the acceptance with a rationale (brand constraint, dark-mode literal preserved). Do not ship a design that passes only APCA but fails WCAG 2.2.
+
+## Performance And Perceived Speed
+
+Use these checks for AI, feed, media, upload, and document-heavy surfaces:
+
+- LCP-critical content should appear quickly or use a meaningful skeleton that matches final layout.
+- Avoid layout shifts when cards, media, citations, ads/promotions, AI output, or toolbars load.
+- User input should remain responsive during streaming, upload, PDF/document rendering, long tables, and chart rendering.
+- Heavy panels should lazy-load without hiding the primary task.
+- Progress should be visible for long-running operations; if duration is uncertain, show staged progress and recovery options.
+- Repeated rerenders, oversized bundles, unbounded lists, and hidden but mounted expensive viewers should be treated as launch risks.
+
+## Product Metrics For Iteration
+
+Use HEART-style metrics as a product-iteration lens:
+
+- **Happiness**: satisfaction feedback, qualitative complaints, rating/reaction reasons, AI answer helpfulness.
+- **Engagement**: feed depth, comments/replies, reactions, follows, topic joins, creation attempts, AI draft usage.
+- **Adoption**: first successful action, first follow, first post/comment, first AI-assisted contribution, onboarding completion.
+- **Retention**: return from notification, repeat visits, recurring creation, saved topics, creator return.
+- **Task success**: completion rate, time to complete, error rate, retry rate, abandon step, moderation appeal success.
+
+Do not optimize a visual change without a corresponding behavior or quality hypothesis.
+
+## Launch Review Additions
+
+Add these to product launch acceptance:
+
+- Accessibility smoke test: keyboard, focus, contrast, labels, target size, long text.
+- Web performance smoke test: key page load, no major layout shift, responsive input during interaction.
+- Error-prevention smoke test: destructive/public/trust-sensitive actions have confirmation and recovery.
+- Metrics smoke test: primary action, failure, retry, drop-off, and satisfaction events are observable.
+- Content clarity smoke test: empty/error/success states say what happened and what to do next.
+
+## What Not To Absorb
+
+- Do not turn external benchmark articles into a generic checklist dump.
+- Do not force enterprise dashboard density onto consumer discovery surfaces.
+- Do not import another design system's exact visual language when local tokens/components exist.
+- Do not cite performance or accessibility as "done" without running a product-specific check when implementation exists.

package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/frontend-code-evidence-map.md

@@ -0,0 +1,63 @@
+# Frontend Code Evidence Map
+
+Use this reference when a task needs implementation evidence from frontend code. The rules below describe *how* to classify and use code evidence; specific local repository paths are kept in the private provenance archive outside this skill tree.
+
+Users without code access can still use the distilled patterns in this file and in the platform-specific references. Do not require access to specific local paths unless the task explicitly asks to audit, update, or re-extract implementation evidence.
+
+## Evidence Rules
+
+- Absorb implementation mechanics only: state ownership, async handling, navigation, permissions, upload/progress, preview, review, charts, tables, tooltips, layout recovery, and build scripts.
+- Do not copy source product names, business workflows, legacy information architecture, or visual taste into a generic product skill.
+- Prefer newer React + design-system + typed-build subprojects over older Vue 2 / Element UI projects or server-rendered legacy folders.
+- When auditing, updating, or re-extracting from source, treat package scripts and source structure as evidence only after confirming the subproject exists locally. For normal use, rely on the distilled patterns below.
+
+## Source Strength Classification
+
+For each frontend subproject in scope, classify the code evidence before extracting rules. The shape below is the classification frame; specific paths live in the private archive.
+
+| Strength | Typical stack signature | Useful extraction |
+| --- | --- | --- |
+| **Strong** | Modern React + Ant Design (Pro Components) workbench, or React + antd-mobile H5, with typed build (TS + Vite/Umi), generated API client, and Less/CSS-module token files | State ownership, route/permission metadata, sidebar/process tabs, upload/preview/review drawers, long-task polling, dense tables, measured overflow, AI/assistant surfaces |
+| **Medium** | React + design-system but smaller scope: admin/workbench, structured creator, content-center, consumer-mobile, H5 device/resource | Sidebar tabs, permission separation, structured DnD, canvas mechanics, list/detail flows, QR/device states |
+| **Weak / excluded** | Legacy Vue 2 + Element UI, rich-text-only packages, render/export pipelines, deploy-only servers, third-party utility apps that happen to share a stack | Use only for legacy stack reference (print/QR/canvas behavior) or matching-stack implementation evidence; never as visual or interaction benchmark |
+| **Backend (out of scope)** | Service-side code | Out of scope for this skill except for product-visible lifecycle consequences; route to the backend skill |
+
+A subproject's strength can be confirmed from its `package.json` deps (e.g. `antd@5 + @ant-design/pro-components` indicates Pro workbench; `antd-mobile@5` indicates H5; absence of either with `vue@2` indicates legacy) plus a quick read of one entry component. Stack guesses based on directory name alone are not evidence.
+
+## Extracted Implementation Patterns
+
+These are the source-neutral patterns confirmed across the strong/medium subprojects:
+
+- Build scripts: most modern web/H5 subprojects separate `build`, `dev`, `prod`, `preview`, `format`, `setup`, and sometimes `gen:api`. Non-framework packages may add independent test/build/lint gates. Preserve environment-mode and generated-API separation in new projects.
+- Mobile primitives: responsive shell, route guard, bottom navigation, safe-area/keyboard behavior using viewport-aware fallbacks, WebView bridge initialization, development-only debug tooling, touch gestures, portrait/landscape review modes, left/right-handed toolbar adaptation, toast/notice provider with queue/dedupe behavior, consent/update dialogs, image/media preview, document viewer, async loading/error/retry, no-data states, report/chart containers, and mobile feature modularization. These cross-check the mobile design-system primitives for NoticeBar, Dialog, Modal, ErrorBlock, Toast, SafeArea, TabBar, Popup, ImageUploader, and ResultPage.
+- Web primitives: central API request wrapper, design-system shell, route-selected sidebar, collapsible navigation, route metadata for layout/menu/permission, process tabs for active jobs, permission-gated menus/actions, drawer/modal/detail inspection, upload and document preview, scan/review progress drawers, rich media viewers, chart/report sections, data tables, event bridge for active workflow tabs, download task entries, and long-label truncation with measured overflow tooltips. These cross-check the web design-system patterns for Sidebar, Content Card, Chat Bot, Empty, Alert, Message, Dialog, Steps, responsive widths, and card min/max height.
+- Complex interaction primitives: dnd/drag selection, canvas/image/PDF preview, zoom/pan/crop, source upload, parse/process progress, manual correction, structured editing, split/merge/reorder, preview before commit, and export/download.
+- Review and ops primitives: workbench/task queues, content/audit/check pages, search forms, pagination, persisted filters, multi-select, batch operation, operation-after-reload/reset, distribution/download, filters/search, segmented controls, no-data/empty states, direct row actions, and affected-scope summaries.
+- Visual/runtime primitives: chart components normalize values and clean up instances; canvas/image flows account for device pixel ratio, zoom/pan, drag, reset, and preview state; long-running export/download flows should be visible as jobs rather than hidden behind one toast.
+- Structured editor primitives: engine initialization, initialization-failure retry, side settings panel, validation-driven disabled save, preview/render callback, zoom/pan canvas controls, object grouping, and editable vs preview object distinction.
+- Native/device task primitives: host bridge initialization, old/new bridge fallback, callback id lifecycle and cleanup, device status taxonomy, preflight configuration, wait state, success continuation, retry/reselect/report recovery, and automatic support reporting for classified failures.
+- Design-system reference primitives (from refreshed published-system files): application navigation, modals, table header/cell/row actions, empty states, chart axes/legends/markers, metrics, progress steps, alerts/notifications, icon best practices, flowchart nodes, decision branches, hot zones, annotations, measurement labels, cursor/gesture cues, and UAT/workflow templates. Use these as capability and review coverage, not as product IA or brand direction.
+
+## Cross-Skill Routing
+
+- Visual/state acceptance → stays in this skill (`product-ui-ux-design`).
+- React/browser implementation ownership → `web-react-dev`.
+- Flutter/Android/iOS/RN implementation ownership → `app-cross-platform-dev`.
+- Mini-program implementation ownership → `miniapp-product-dev`.
+- Test-layer planning → `testing-strategy`.
+- Backend service implementation → the relevant backend skill (e.g. Python service, Go microservice).
+
+## Product Translation
+
+When mapping these implementation patterns to a new product domain:
+
+- Mobile app implementation → community mobile shell, onboarding, profile/settings, AI creation, notification, feed/detail, and insight surfaces.
+- Web shell implementation → creator center, moderation/trust workspace, AI workspace, asset/resource governance, analytics, and settings.
+- Creation/editing implementation → AI draft creation, media/content import, structured post/event/content-pack setup, and review-before-publish.
+- Scan/print/canvas implementation → media ingestion, document preview, QR/device flows, evidence capture, and export/share flows.
+
+Discard the source product's nouns, role labels, and workflow copy from any extracted rule.
+
+## Where The Specific Provenance Lives
+
+Specific subproject paths, real branch names, package.json signatures, and dated implementation cross-check logs live in the maintainer's private archive. They are not included in this file, so any cross-organization use of this skill stays clean.

package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/interaction-design-patterns.md

@@ -0,0 +1,146 @@
+# Interaction Design Patterns
+
+Use this reference when designing, implementing, or reviewing interaction flows, micro-feedback, mobile gestures, AI-assisted flows, state transitions, or trust-sensitive product behavior. It combines Figma evidence with reusable frontend implementation patterns from mobile and web sources.
+
+Do not inherit old source-domain semantics. Translate only the interaction mechanics into the new product's domain.
+
+## Source Evidence
+
+- Mobile app source: login, agreement consent, keyboard open/closed states, tab navigation, task cards, empty states, AI photo/upload, multi-item review, Toast, Modal, profile/settings, and explicit interaction-note sections.
+- Desktop shell/workbench capability class: desktop login states, Sidebar full/collapsed states, selected/hover menu states, process/task entries, responsive workbench, Steps, Alert, Message, Dialog, Chat Bot, AI open/closed states, empty cards, upload/import workflow, and drawer/transfer patterns.
+- Implementation primitives: see the catalog in `ui-ux-design-development.md`.
+
+## Core Interaction Model
+
+Every primary surface should state one dominant user job and support a complete loop:
+
+1. **Discover**: scan feed/list/dashboard, understand current context, identify available actions.
+2. **Inspect**: open detail, preview media/source, expand context, compare or filter when needed.
+3. **Act**: create, reply, upload, analyze, follow, save, report, configure, or submit.
+4. **Confirm**: show lightweight success, visible in-progress state, or explicit decision dialog.
+5. **Return**: preserve context and selection when returning; make next action visible.
+
+Do not add interaction states as decoration. Each state must answer: where am I, what changed, what can I do next, and can I undo or retry?
+
+## Feedback Strength
+
+Use the lightest feedback that still preserves user confidence. This is the canonical feedback-strength ladder for this skill:
+
+- **Inline state**: validation, field errors, disabled reasons, upload progress, selected filter, current tab, active task.
+- **Toast**: lightweight success or non-blocking failure after an action, such as saved, copied, sent, retried, or uploaded.
+- **Notice bar / alert**: scoped persistent condition that affects a page or module, such as service migration, partial data, permission limits, stale data, or AI confidence caveat.
+- **Dialog / modal**: decisions with consequence, consent, destructive actions, permission explanations, or workflow transitions that cannot be silently reversed.
+- **Bottom sheet / drawer**: focused secondary workflow such as filters, selection, source settings, detail inspection, or batch setup while preserving the parent context.
+- **Full-page error / empty state**: when the whole surface cannot proceed. Include a concrete recovery action whenever possible.
+
+Avoid modal overuse. If the action can be retried or undone without major consequence, prefer inline feedback, toast, or an undo affordance.
+
+## State Contract
+
+Use the canonical state taxonomy in `product-surface-patterns.md`. This file adds interaction-level detail for state transitions:
+
+- Entry states should distinguish first-use, returning-user, and empty-context entry.
+- Progress states should distinguish short loading, streaming, upload/parse, long-running background task, and pagination/loading-more.
+- Result states should distinguish success, partial success, no result, stale result, and generated-but-unreviewed result.
+- Error states should distinguish retryable, non-retryable, permission denied, unsupported input, offline/network, and backend rejection.
+- Control states should include selected, active, hover, pressed, focused, disabled, expanded/collapsed, and long-content behavior. **每态视觉必明显可辨**（不只是 5% opacity 差）：hover / focus / active 用**不同维度**的视觉变化（如 hover 改 bg、focus 加 outline、active 加 inner shadow）；disabled 视觉去活力 + 必含可见原因（参 [[design-execution-checklist.md]] §7 B）。默认 framework state（如未样式化的 `:focus`）不可见 = 等于无 state。
+- Reversal states should include undo, cancel, remove, retake, replace, exit, clear, reset, and return.
+- Trust states should include source visible, AI caveat, moderation/review label, reported/blocked/muted state, and risk-sensitive confirmation.
+
+For AI or generated output, do not treat "generated" as final. Provide review, edit, regenerate, cite/source, copy/share, and failure paths as appropriate.
+
+For embedded workspace assistants, treat the assistant as a secondary workflow surface rather than a separate chat island:
+
+- Entry: docked panel, collapsed/floating launcher, fullscreen, hidden-by-permission, and route-local entry states.
+- Compose: prompt text, attachments, preset suggestions, mode toggles, disabled submit, IME-safe send, and clear dependency rules between search, reasoning, upload, and model choices.
+- Generate: waiting, streaming, cancel, interrupted, timeout, network failure, retry/regenerate, copy, and generated-content caution.
+- Continue: session history, new conversation, switch conversation, delete confirmation, load older turns while preserving scroll, and return-to-bottom only when the user is not already near the latest output.
+- Commit: if AI output becomes a post, resource, task, saved item, or workflow artifact, require preview/review, already-saved state, failure recovery, and a return path to the originating work.
+
+For assistant geometry, responsive collapse, and workbench placement rules, use `platform-web-desktop-patterns.md#ai-assistant-in-workbench`.
+
+## Mobile Interaction Rules
+
+- Keep the main loop one-handed and screen-local. Primary actions should be reachable near the bottom or within the active card.
+- Use bottom tabs for durable product areas, not transient workflow steps. Map tabs to core loops such as feed, create/AI, notifications, profile, or community spaces.
+- Use a NavBar for screen identity and return behavior. Avoid hiding back/close behind browser controls.
+- Use bottom sheets for filters, selector lists, advanced settings, and focused confirmation workflows.
+- Keyboard-sensitive screens must handle visual viewport changes, Android overlay/resize differences, and safe bottom padding.
+- Edge-swipe back is useful only when it does not conflict with horizontal content scrolling, carousels, drawing, annotation, or drag selection.
+- Multi-item review or upload flows need current position, previous/next, retake/remove/replace, confirm, and done states.
+- Empty mobile states should distinguish first-use guidance, no current items, no permission, and temporary loading/no-update conditions.
+
+## Desktop / Web Interaction Rules
+
+- Use a stable shell: account/context area, primary navigation, selected state, collapsed state, and discoverable hover labels.
+- Put process/task entries near navigation only when they represent active user work, uploads, reviews, imports, generation jobs, or downloads.
+- Keep dense workflow pages anchored by a title/context area, a toolbar, visible filters, and a persistent next action.
+- Use drawers for detail or setup when the parent list/table should remain mentally available.
+- Use explicit stepper phases for upload/import/configure/review/publish flows. Users should always know which phase they are in.
+- For large workspaces, define min/max widths and collapse secondary panels before compressing primary content below usable size.
+- Opening external systems or new windows should have clear feedback for failure and should not silently break the user's current task.
+
+## Presentation Mode vs Workbench Mode
+
+A product surface that exists in both an authoring/editing context (workbench mode) AND a "show this to a room" or "annotate live" context (presentation mode) is two distinct UIs sharing data, not one responsive UI. Treat them as different surfaces with explicit rules:
+
+- **Fixed viewport vs responsive**: presentation mode targets a known display (typically projector / shared screen at one resolution like 1920×1080); design and test against that fixed viewport. Workbench mode is responsive across the user's window sizes. A single responsive surface trying to serve both will either fail the presentation case (controls too small at projector distance, text wraps unpredictably) or fail the workbench case (excess whitespace at normal window sizes).
+- **Curated subset, not full data**: presentation mode shows only the artifacts the presenter chose to display (a selected item + curated supporting artifacts + the slide they navigated to), not the full table / list / search space. Workbench mode shows full data with filters; presentation mode shows the post-filter selection. Switching between modes must preserve the selection, not reset it.
+- **Simplified control surface**: presentation mode strips workbench controls that don't apply to a live audience — sort, multi-select, batch actions, deep filters, account/settings entry, secondary nav. Keep navigation between items (next / previous / jump), the annotation/highlight toolset, fullscreen, and exit. Anything else is noise on a projector.
+- **Annotation state is context-scoped, not global**: when the surface supports live drawing / highlighting / pen markup, the annotation state belongs to the current context (current item × current source pane), and each context owns its own annotation layer. Switching item or source pane must **switch to the new context's annotation layer** — show that scope's existing annotations if any, or start empty if none — and **preserve** every other scope's annotation layer until explicit discard or mode exit. A common wrong implementation uses one global canvas that wipes on every navigation; the presenter then loses every annotation the moment they navigate to compare items. Never wipe other scopes; only the current scope's layer is the one being drawn into.
+- **Privacy mode is a live toggle**: when the presented content includes identifiable individuals (participant names, customer ids, employee photos, any personal identifier), provide a `hide / show real identifier` toggle that flips in real time without losing position or annotation. Default state is policy-driven (some venues default-show, others default-hide); do not bake the default into the workbench-mode user setting.
+- **Mode entry and exit are first-class actions**: getting into presentation mode is an explicit affordance (a "Present" button), not a coincidental fullscreen press; exiting returns to the workbench in the same state (same selection, same scroll, same filter). Exit must be reachable from the keyboard (Esc) AND from the toolbar — projector audiences sometimes need the presenter to exit without alt-tabbing.
+- **Persistence and replay**: any annotations the presenter wants to keep (for later review with audience members who were absent, for follow-up tasks) need a save path that survives mode exit. Annotations the presenter doesn't save are discarded on exit; do not silently persist every stroke.
+
+## Community Product Translation
+
+Translate old source mechanics into C-end community equivalents:
+
+- Login/consent -> onboarding, account security, privacy agreement, notification permissions.
+- Sidebar/process tabs -> creator workspace, moderation queue, upload/generation jobs, saved drafts.
+- Workbench cards -> feed shortcuts, creation prompts, topic onboarding, community health, recent activity.
+- Upload/parse/review -> media upload, AI draft extraction, source citation, content moderation, attachment processing.
+- Analysis dashboards -> creator insights, topic health, retention, trust/safety, AI answer quality.
+- Task review flows -> moderation decisions, report handling, creator payout review, campaign setup, AI classification correction.
+
+Discard old source-domain scoring, hierarchy, workflow, and role vocabulary. Keep source-specific terms only in provenance notes.
+
+## Serious / Financial Product Adaptation
+
+When this skill is used for finance, health, legal, enterprise admin, or other trust-sensitive products, add an extra interaction layer:
+
+- Show source, timestamp, data scope, and known gaps for AI or analytics outputs.
+- Separate "informational insight" from "actionable decision" through copy, controls, and confirmation.
+- Use stronger confirmation for irreversible, externally visible, account, money, permission, or compliance-sensitive actions.
+- Avoid optimistic UI for actions that change money, permissions, identity, compliance status, or official records.
+- Make partial data and delayed data explicit; do not let empty charts or `--` values masquerade as normal results.
+- Prefer audit-friendly labels over cute microcopy for critical states.
+
+This adaptation does not turn the skill into a finance compliance skill. It only prevents generic consumer interaction patterns from becoming unsafe in serious domains.
+
+## Form & Defensive UI Patterns
+
+- **"Labels are a last resort" — 仅适用于展示型数据，不是表单输入**：(a) **展示数据**（profile 字段、商品规格、详情页 attribute 列表）能用 layout / 值文本本身 / icon / 分组让意思自明，就**不重复贴 label**（"$42" 不必 "Price: $42"；"alice@example.com" 不必前缀 "Email:"）。(b) **表单输入则相反 — accessible label 是默认必须**（screen reader、autofill、低视力都依赖；WCAG 1.3.1 / 2.4.6 / 3.3.2 要求 — 见 [[external-ui-ux-quality-benchmarks.md]]）。可视觉隐藏（visually-hidden）label 仅当 placeholder/icon 等已提供持久可见 name；浮动 label、icon 内嵌等都是 label 仍存在的形式，不是"省略 label"。
+- **User-supplied / 外部资源必有 fallback，按内容类型分对应模式**：avatar → initials / 默认头像；通用 media (cover/banner) → placeholder / blurhash；语义关键媒体（chart / map / PDF preview / 法律凭据）→ **不可用"看起来正常"的默认替代**（会误导用户认为渲染成功），必给明确"unavailable"或"无法渲染"状态；远程加载 → skeleton + retry control；生成型 preview → 明确"生成失败"状态 + retry。设计时显式给 fallback 视觉，不让 dev "实现时再说"。
+
+## UI Copy Patterns（quick reference）
+
+Operational microcopy patterns; 完整规则见 `design-execution-checklist.md` §7 B 段。
+
+- **Button label**：verb + 具体对象（`Save changes` / `Send message`），avoid generic when action 不明（`Submit` 弱、`OK` 遮蔽结果）；platform dialog 标准位 `Cancel`/`OK` 仍可用。Destructive 更显式（`Delete forever`）
+- **Error**：happened / why（安全可披露时给）/ what to do；不出 stack trace 或纯 error code 作主文案
+- **Disabled**：默认给原因 + 启用条件；policy/permission/security 暴露条件不安全时改隐藏 control 或通用解释
+- **Success / confirmation**：说清成功了什么 + 下一步（不只 `Done`）
+- **Empty state**：见上文 "Full-page error / empty state" — 必含 recovery / next action
+- **Voice consistency**：(a) 无内部代号 (b) 同动作/对象不混术语 (c) 无未解释 jargon (d) 无翻译腔 (e) 时态/人称/大小写统一
+
+## Review Checklist
+
+- The primary loop is visible without reading documentation.
+- The next action is clear in happy, empty, loading, error, and partial states.
+- Feedback strength matches the canonical ladder in this file.
+- Mobile screens handle keyboard, safe area, return navigation, long labels, and one-handed action placement.
+- Web screens handle collapsed navigation, selected state, filters, task/process entries, detail drawers, and responsive secondary panels.
+- AI flows include generating, failed, reviewed, editable, source/citation, and regenerate paths.
+- Trust-sensitive actions include source, timestamp, confirmation, retry, and audit-friendly state labels.
+- Domain terms from source Figma/code have been translated or discarded.

package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/layout-recipes-and-screenshot-acceptance.md

@@ -0,0 +1,250 @@
+# Layout Recipes And Screenshot Acceptance
+
+Use this reference when a design task risks becoming "rule-compliant but plain". It turns the generic design rules into concrete layout recipes, density targets, state templates, and screenshot acceptance checks.
+
+This file is distilled from current Figma rules and frontend implementation evidence. Source product terms are provenance only; do not copy them into new-product UI.
+
+## Non-Negotiable Adaptation Defaults
+
+Do this before drawing or coding any nontrivial page:
+
+1. Pick the screen family: desktop workbench, consumer web, mobile app/H5, dense table/list, structured editor, scan/upload/review, analytics/tracking, or resource/library.
+2. Pick the primary viewport and two stress viewports:
+   - Desktop workbench: 1440x810 first, then wider desktop and a narrow desktop/tablet width.
+   - Consumer web: content column and optional rail at desktop, then one tablet/narrow width and one mobile width.
+   - Mobile app/H5: 393x852 first, then 375x812 and 428x926; if the task supports landscape or review, also check about 874x402.
+3. Assign fixed or bounded regions before spacing polish: shell/header, context/filter row, primary region, secondary panel, feedback region, and action area.
+4. Decide the collapse rule: secondary panel, side rail, preview, filters, and metadata collapse before the primary content becomes unreadable. Do not just shrink everything.
+5. Decide the density mode and spacing scale. Productive compact and consumer relaxed use different page padding, control height, row height, and card breathing room.
+6. Map long text, no data, partial data, permission blocked, loading, error, and keyboard/safe-area states into the same geometry as the happy path.
+
+If a design or implementation skips these decisions, it is not ready for UI review even if the component choices are correct.
+
+## Four-Layer Quality Pass
+
+Use the canonical four-layer order from `design-execution-checklist.md` after choosing a recipe and before coding, screenshot review, or acceptance. In this reference, translate that order into layout proof:
+
+- Aesthetic proof: visible layer model, rhythm, density, alignment, color weight, and one primary focus.
+- Interaction proof: visible entry point, current task, next action, progressive disclosure, and return path.
+- Behavioral proof: visible protection or recovery for repeat, mistake, wait, cancel, retry, interruption, and undo risks.
+- Psychology proof: reduced uncertainty, immediate feedback, perceived control, and deliberate confirmation for high-impact actions.
+
+If one layer is missing, the screen is incomplete even when it passes component and token checks.
+
+## Universal Layout Recipe
+
+Every nontrivial screen needs a visible composition before component styling:
+
+1. Shell: global nav, account/context, route title, and persistent feedback providers.
+2. Context row: current scope, mode, filters, selected object, permission or trust state.
+3. Primary region: the main content, review object, feed, editor, table, or output.
+4. Control region: input, filters, toolbar, settings, or action panel.
+5. Feedback region: empty/loading/error/progress/success/partial state in the same geometry as the final content.
+6. Return loop: back/close, save draft, retry, undo, next item, or route-preserved selection.
+7. Annotation and flow support: for complex tasks, expose the user's current step, decision point, hot zone, affected object, and measurement/status cue through concise labels, markers, progress steps, or tooltips rather than forcing users to infer the workflow from raw layout.
+
+If a screen cannot be described by this recipe, it is probably a marketing page, a raw component dump, or an unfinished placeholder. Data-driven empty workbenches are valid when they still expose module structure and next action.
+
+## Productive Web Workbench
+
+Use for creator tools, moderation, analytics, AI review, asset management, and other repeated-use web surfaces.
+
+- Page: light neutral background, 16-24px outer padding, 8-12px panel radius, one primary surface row above the fold.
+- Aesthetic logic: use the background as a quiet canvas and let white/elevated work surfaces carry the task. Borders, shadows, and radius should express grouping and depth, not decoration. Repeated work areas need a stable spacing rhythm so the screen feels deliberate at dense information load.
+- Interaction logic: keep context, controls, output/review, and final action visible as a connected task path. Complex flows should move into side panels, drawers, setup dialogs, or step regions while preserving the parent workbench context.
+- Behavioral psychology: repeated-use users need certainty, recovery, and speed. Show pending jobs, disabled reasons, progress, retry, last-known status, and safe return paths instead of relying on transient toasts.
+- Header: compact title/context/action row, usually 48-64px high. Avoid a second oversized title inside the page.
+- Control bar: filters, segmented mode, search, upload/generate action, and selected scope in one compact band. Prefer 32-40px controls.
+- Status strip: small facts such as scope, source, permission, job state, model/cost, data freshness, or selected count. Keep it one line when possible.
+- Desktop baseline: many source workspaces use 1440x810 frames with 64px navigation/header bars. Use this as a practical first screenshot target, then check wider desktop and narrow responsive behavior.
+- Workbench body: use one of these structures:
+  - Library/resource workspace: left tree/source rail around 240px, top filter/search band, sticky filter state, content cards/table in the main region, preview/download/share/edit actions near the object.
+  - Split review: left list/source/input 280-360px, center preview/result flexible, right settings/metadata 320-420px.
+  - Editor with fixed side panel: primary editor min 900-960px, side panel 360-420px, page min width around 1280-1400px.
+  - Table workspace: toolbar above, sticky header, compact rows, fixed action column, detail drawer for inspection.
+  - AI workspace: input/source panel, generated output panel, review/metadata panel; output geometry exists in empty and loading states.
+- Dialog/setup panels: 560-640px is a useful default for focused settings/download/import dialogs; expand only when comparison, preview, or multi-step validation needs it.
+- Collapse rule: hide or dock secondary metadata first, turn right-side settings into a drawer or step panel second, and only then simplify the primary content. If the center work area would fall below about 720px for reading/review or about 900px for structured editing, switch layout rather than squeezing controls.
+- Spacing rhythm: outer padding 16/20/24px by density, panel inner padding 12/16px, row/card gaps 8/12/16px. Avoid mixing 10 unrelated spacing values in one page.
+- Control alignment: top filters and actions share one baseline, 32-40px height, and consistent label widths. Primary action stays on the far edge or sticky header; destructive actions move into menu/confirm flows.
+- Empty/loading/error states stay inside the workbench geometry. Do not replace the whole first viewport with a large illustration unless the whole product area is empty.
+- Data-driven workbenches are valid: modules may appear, disappear, reorder, or change status based on permissions, jobs, saved drafts, metrics, or configured workflows. The requirement is that the empty/loading/no-permission shape still exposes the intended module grid, next action, and future data slots instead of collapsing into an unstructured placeholder.
+- Table, modal, empty, alert, progress, metric, and chart components must be selected by task role. A table needs stable row/header/action behavior; a modal needs decision and return context; an empty state needs next action; a chart needs drill-down or explanation; an alert needs scope and consequence.
+
+Good workbench screens make the next operator action obvious within five seconds.
+
+## Consumer Web Recipe
+
+Use for feed, detail, profile, community/topic, notification, and creator-facing consumer web pages.
+
+- Keep the first viewport content-led: feed/detail/creator identity should appear immediately, not below a decorative hero.
+- Use a constrained content column plus optional secondary rail. Keep paragraphs and post bodies readable; do not stretch text full width.
+- For desktop, keep the main reading/action column visually dominant. Secondary rails are supporting context and should collapse, stack, or move below content before they force the primary column into cramped line lengths.
+- Cards may be expressive, but repeated cards need stable rhythm: avatar/title/body/media/metadata/actions should align across the list.
+- Put creation entry, follow/subscribe, reaction, reply, share, save, and moderation/report affordances close to the content they affect.
+- Empty states invite a first community action: follow topics, create a post, invite people, upload media, or tune AI suggestions.
+
+## Mobile App Recipe
+
+Use for app/H5 consumer surfaces and focused mobile task flows.
+
+- Mobile baseline: check 393x852 portrait as a primary app/H5 target. For media/review tasks that support landscape, also check a landscape frame around 874x402.
+- Aesthetic logic: mobile screens should have one clear focus per viewport. Use compact rhythm for repeated tasks and warmer spacing for discovery or creation, but keep tap targets reliable.
+- Interaction logic: design around thumb reach, back/close clarity, bottom-sheet focus, keyboard appearance, and foreground/background recovery. Landscape modes need a new toolbar and preview arrangement, not a rotated portrait layout.
+- Behavioral psychology: mobile users are interruption-prone. Preserve draft/input/progress when the app backgrounds, explain disabled actions, and keep the active input/action visible when the keyboard or safe area changes the viewport.
+- Shell: safe-area aware app shell, screen NavBar for identity/back/close, durable bottom tabs only for top-level areas.
+- Container: full-width by default, optional max width only for desktop preview; avoid ad hoc wrappers that fight scrolling.
+- Main loop: one primary action per screen, reachable by thumb or in the active card.
+- Lists/cards: compact metadata, clear action row, stable skeleton matching final card shape.
+- Bottom sheets: filters, selectors, source settings, and focused confirmation. They must handle keyboard and visual viewport changes.
+- Safe-area and keyboard: bottom actions, tabs, floating panels, and text inputs must remain visible with safe-area inset and keyboard open. When the keyboard appears, the active input and submit/retry action must stay reachable without manual page gymnastics.
+- Touch sizing: icon-only or compact controls still need reliable tap targets and accessible labels. Use icon-first only for familiar repeated tools; otherwise pair icon with label or tooltip/sheet title.
+- Orientation: if landscape is supported for media, review, or editing, toolbar density and preview geometry must be redesigned for landscape, not merely rotated.
+- Empty states: illustration max around 120x100 unless onboarding needs more; title + one useful next action beats a large blank decorative panel.
+- Errors: section-level retry for local failures; full-page result only when the whole screen cannot proceed.
+
+## Dense Table/List Recipe
+
+Use for analytics, moderation queues, asset libraries, admin settings, and review backlogs.
+
+- Top row: search/filter/segmented mode left, primary action right, selected count/status visible.
+- Management baseline: use a 1440x810 working frame with a 64px-class page header when designing table/list management pages; long configuration pages may extend vertically to 1254px-wide content sections.
+- Filter stack: cascade selector, tabs, keyword search, status/date/source filters, and bulk action entry should be grouped before the table/list. Avoid scattering filters across unrelated cards.
+- Table/list: zebra or subtle row separation is acceptable; hover should preserve row identity and may highlight the hovered column for comparison-heavy data.
+- Table header/cell system: define header label, sortable/selected state, row lead action, row secondary actions, cell truncation, status badges, and responsive hidden/wrapped columns before implementation.
+- Width handling: choose which columns are fixed, which truncate, which wrap, and which hide at narrow widths. Long names need measured tooltip/title behavior; numeric/status columns stay aligned.
+- Row height: compact rows should stay visually stable across loading, hover, selection, error, and disabled states. Do not let badges, tags, or action menus change row height unpredictably.
+- Sorting: visible sort state, compact icon, no ambiguous default order.
+- Pagination: show total, page controls, page size, and quick jump only when useful; controls should align and use the same radius as other compact controls.
+- Row actions: keep primary row action visible; move secondary/destructive actions into menu/popconfirm/drawer.
+- Empty: show what filter/scope produced no result and offer reset/create/import where relevant.
+- Detail inspection: drawer or side panel keeps the parent table/list available.
+- Import/repair: show upload/import, validation, preview, confirm, export/download, and error-repair as a connected sequence. Preview the changed object list before commit.
+
+## Creation And Structured Editor Recipe
+
+Use for upload/import, structured creation, AI draft setup, media editing, rule/configuration, and review-before-publish.
+
+- Phase model: configure -> import/generate -> review/edit -> validate -> publish/export.
+- Preview before commit: show the produced object shape before final save/download/publish.
+- Validation: put blocking issues near the affected item and summarize them in the side/status panel.
+- Long tasks: progress, retry, cancel, background task entry, and terminal success/failure.
+- Side settings panel: 320-500px, scrollable, grouped sections, compact labels, validation states, and disabled reasons.
+- Header action: save/publish/download button stays visible; disabled state explains what blocks it.
+- Editor engine state: initialization, failed initialization with retry, render-complete, validation-blocked, disabled editing, and save-in-progress are first-class screen states.
+- Canvas or document preview: include zoom in/out, drag/pan, reset or fit behavior where useful, device-pixel-ratio/image quality checks, and clear distinction between preview, selectable object, and editable object.
+- Validation psychology: users should know why save/publish is blocked, which object caused it, and what minimum correction unlocks progress.
+- Flow and annotation support: complex creation should show the current phase, decision branch, active hot zone, affected object, measurement or quality cue, and next possible action without turning the page into a tutorial.
+
+## Device Or Native-Capability Task Recipe
+
+Use for printing, scanning, camera/file capture, native bridge operations, device pairing, QR flows, and other flows that depend on hardware or a host app.
+
+- Phase model: configure -> confirm -> wait/processing -> success/continue -> error/retry/report.
+- Preflight: expose missing host app, unsupported device, missing permission, unavailable service, no media/paper/resource, or insufficient balance/capacity before the user commits.
+- Waiting: keep the modal/screen stable, disable unsafe duplicate actions, show that work is still ongoing, and prevent background interaction when interruption would be confusing.
+- Error classification: map raw device/native codes to user-meaningful categories such as missing input, connection failure, host bridge missing, processing failure, unsupported state, or retryable network issue.
+- Recovery: offer retry, reselect/reconfigure, report/support, return home, or continue with another item depending on the failure class. Do not collapse all failures into a generic error toast.
+- Instrumentation: for support-traceable failures, capture device/status/action context in the workflow and make the user-visible next step clear.
+
+## Scan, Upload, And Review Pipeline Recipe
+
+Use for media ingestion, file parsing, AI extraction, moderation/review queues, and evidence review.
+
+- State sequence: disconnected/not ready -> empty/no item -> upload/scan/import in progress -> preview on/off -> processing -> partial/unsupported -> ready -> large preview/detail -> completed.
+- Interaction logic: split preflight/check, active processing, review/repair, and completion into visible stages. Keep the user in the same task context while moving detailed controls into drawers, toolbars, or side panels.
+- Behavioral psychology: users fear losing work during long tasks. Provide a visible count or progress indicator, upload/processing speed or freshness when useful, pause/continue/cancel when supported, before-unload/offline protection, and explicit recovery from partial failure.
+- Header: 64px-class factual page header with current object, progress, and next action.
+- Preview: keep preview geometry stable when switching between no preview, small preview, large preview, and detail drawer.
+- Progress: use inline progress ring/bar plus status text for active processing; do not hide progress behind a generic spinner.
+- Review toolbar: show task type/mode, current item, previous/next, mark/confirm, issue/report, and completion progress. Toolbars may be compact icon-first controls, but every unfamiliar icon needs a discoverable label or tooltip.
+- Adaptation: support one item vs multiple items, single focus vs side-by-side comparison, and portrait/landscape review where relevant.
+- Unsupported input: explain what is unsupported and what the user can still upload, retry, replace, or skip.
+- High-throughput evaluation screenshot set: capture at least single-item, multi-item, long-content, empty/delayed artifact, completed item, unsupported automation, and active automation-config states.
+- Evaluation header acceptance: queue/progress, display-count controls, view/reference tools, and session actions should read as grouped regions in the 64px-class header. The progress count must stay visible at 1440x810 and the narrow desktop stress width.
+- Evaluation canvas acceptance: selected item or sub-unit boundary, current metadata strip, retry/loading shell, and bottom/session tool state must remain visible when switching between one-item, multi-item, and long-artifact layouts.
+- Automation-config acceptance: left item list keeps item hierarchy and enable switch state; middle panel shows either an enablement prerequisite or strategy/config controls; right panel keeps required context/reference/rationale fields stable; result-use mode remains visible near final save.
+- Long reference/output acceptance: short content still has a readable minimum block, long content caps at a declared height and scrolls inside the panel, and the dialog or workbench does not grow beyond the viewport.
+
+## Analytics And Tracking Recipe
+
+Use for creator insights, topic health, community quality, retention, AI quality, moderation progress, and operational dashboards.
+
+- Start with scope and comparison: selected object/group, time range, baseline/comparison target, and data freshness must be visible near the top.
+- Aesthetic logic: analytics should feel calm and exact. Use restrained color, consistent chart rhythm, clear grouping, and strong numeric alignment; avoid decorative chart styling that makes comparison harder.
+- Interaction logic: every chart needs a route to exact rows, exceptions, drill-down, or expanded view. Do not leave users with a beautiful summary and no way to inspect the underlying objects.
+- Behavioral psychology: users distrust ambiguous metrics. Show freshness, missing/partial data, baseline availability, and whether a zero means zero, unsupported, stale, or still loading.
+- Use a chart/table pairing: charts show trend or distribution; tables show exact objects, ranks, exceptions, or drill-down rows.
+- Multi-level headers and grouped metrics are valid when they help comparison, but keep the sticky header readable and avoid nested table confusion.
+- Maximize/detail states are part of the design, not an afterthought. Large charts, dense tables, and detail drill-down need a focused expanded view.
+- Data quality states must be explicit: missing baseline, partial data, stale data, no result, unsupported scope, and loading should not look like normal zero values.
+- For monitoring dashboards, expose progress and quality as separate dimensions; do not bury exception review inside the same visual weight as normal summary cards.
+- For large report systems, capture at least four screenshot baselines: report list, report detail default module, a long table/chart module with local navigation, and an object-detail or drill-down view. If the surface has a presentation/annotation mode, capture that mode separately at its intended full-viewport size.
+- Large report details need fixed context before visual polish: module menu, current scope/filter band, selected module, data freshness, export state, and parent-return path. If any of these disappear while scrolling, add a side rail, sticky header, local anchor, or restored return state instead of relying on page memory.
+- Object or user detail pages inside analytics should not feel like separate products. Keep the selected object rail, detail header, comparison cards, trend/knowledge/table sections, and next/previous or search path connected to the parent report.
+- Live explanation or annotation modes spawned from analytics need a separate precision-workspace recipe: full-viewport artifact, right-side item navigator, bottom fixed toolbar, mode-specific controls, zoom state, annotation undo/redo/clear, and state reset rules when the current item changes.
+
+## Empty, Loading, Error, Success Templates
+
+Empty:
+
+- Local empty: icon/skeleton/checklist inside the final region, 120px-class illustration max, one title, one short reason, one next action.
+- First-use empty: can be warmer, but still shows the first useful action and does not push the product structure below the fold.
+- Filtered empty: name the active filter/scope and offer reset.
+- Permission empty: say what is blocked and what remains possible.
+
+Loading:
+
+- Use skeleton matching the final layout for feed/list/card/table.
+- Use progress text for import/upload/generation/long-running tasks.
+- Keep the destination geometry stable; avoid replacing a dense page with a centered spinner.
+
+Error:
+
+- Retryable: short message + retry.
+- Partial: show loaded content, mark missing/stale content, and keep available actions usable.
+- Fatal: use Result/full-page only when the whole surface cannot proceed.
+
+Success:
+
+- Confirm completion and show the next useful action, not just a toast.
+- For publish/export/share, make the resulting object or destination visible.
+
+## Density And Component Targets
+
+- Productive compact: 16-24px page padding, 12-16px panel inner padding, 8-12px gaps, 32-40px controls, 13-14px secondary text, restrained shadows.
+- Consumer relaxed: 20-32px page rhythm, larger content cards, 15-16px body text, clearer media/avatar affordances, more breathing room around reactions and creation.
+- Mobile compact: 12-16px horizontal padding, 8-12px component gaps, 44px-class tap rows/actions where possible, bottom actions aware of safe-area and keyboard. Use smaller visual density only when repeated use needs it and the tap target remains reliable.
+- Radius: compact controls 6-8px; cards/panels 8-12px; mobile sheets/dialogs 12-16px. Do not use the same oversized radius everywhere.
+- Color: use semantic tokens; primary color leads actions and selection. Accent colors need meaning: status, category, trust, AI, or creation.
+- Typography: major screen title 16-22px in product surfaces; compact panel headings 14-16px; body and metadata must not compete with page title.
+
+## Design-To-Code Adaptation Checklist
+
+When implementing from a design or creating a new screen in code, verify these against the rendered surface:
+
+- Layout regions are named in code or component structure, not hidden inside anonymous nested cards.
+- CSS/layout uses bounded dimensions, grid/flex rules, sticky regions, overflow handling, and collapse rules; it does not depend on one ideal viewport.
+- Visual judgment survives implementation: hierarchy, density, rhythm, material treatment, and mood match the checkpoint instead of degrading into default component-library output.
+- Interaction judgment survives implementation: modal/drawer/detail return context, primary/secondary action hierarchy, progressive disclosure, and risk-matched confirmation behave as designed.
+- Behavioral judgment survives implementation: pending, disabled, retry, cancel, offline/interrupted, duplicate action, and recovery states are modeled in component state, not only as best-effort toasts.
+- Token use is consistent: no feature-local spacing/color/radius scale unless it is promoted or justified.
+- Data-driven sections can mount/unmount/reorder without breaking the grid, gaps, sticky header, or primary action placement.
+- Upload, preview, review, long-task, and generated-output areas keep stable geometry across empty, loading, partial, success, and error states.
+- Screenshot or browser/device evidence covers the primary viewport plus stress viewport(s), long text, empty data, partial data, and an error or permission state.
+
+## Screenshot Acceptance
+
+Before calling a UI done, inspect desktop and mobile/narrow screenshots where relevant:
+
+- First viewport: primary workflow is visible; the screen is not mostly banner, blank illustration, or unrelated dashboard content.
+- Hierarchy: the eye lands on the right object/action within five seconds.
+- Geometry: shell, control bar, primary region, secondary panel, and feedback state align to a clear grid.
+- Density: no large dead zones; no nested-card clutter; no card-in-card framing unless the inner card is a repeated item or modal content.
+- States: happy, empty, loading, error, disabled/permission, long-content, and narrow-width states keep the same layout logic.
+- Text: labels fit controls, long names truncate/wrap predictably, no text overlaps, no hero-scale type inside compact panels.
+- Actions: primary action is obvious, destructive action is separated, disabled action has a reason.
+- Trust: generated/high-impact content shows source/context/status near the output.
+- Responsiveness: secondary panels collapse before primary content becomes unreadable; mobile safe area and keyboard do not cover the active input/action.
+
+If a screenshot passes only because the data is ideal, test again with long names, no data, partial data, and an error state.