@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/trust-sensitive-ai-and-data-patterns.md

@@ -0,0 +1,96 @@
+# Trust-Sensitive AI And Data Patterns
+
+Use this reference when designing or implementing product surfaces that include AI answers, uploaded files, citations, analytics, financial-like data, moderation decisions, user permissions, or long-running data workflows.
+
+This file extracts reusable behavior and engineering-quality patterns from trust-sensitive AI/data frontends. It does not make the skill a finance-product skill.
+
+Important: these frontends are **not** visual-design sources for this skill. Do not absorb their page composition, visual polish, information architecture, density, copy tone, or interaction taste as positive UI/UX examples. Use them only where the implementation shows reusable mechanics for trust-sensitive AI/data work, instrumentation, recoverability, permissions, upload/task state, and launch checks.
+
+## Source Evidence
+
+Finance frontend sources inspected and classified:
+
+- Trust-sensitive AI frontend source: usable behavior evidence for tests, upload progress, document readers, reference panels, analytics hooks, API request instrumentation, global error handling, and feedback collection. Not a visual/UI benchmark.
+- Operations frontend source: usable behavior evidence for permission context, dense data tables, truncated cell portal tooltip, CSV utilities, notifications, and build-mode separation. Not a consumer UI benchmark.
+- Typed Vue frontend source: usable engineering evidence for typed build, Element Plus, Pinia, and typed API/client structure. Not a design source.
+- Marketing-site frontend source: weak engineering evidence for build/lint/start/push flow and localized pages. Not a visual source.
+
+## Patterns To Absorb
+
+### Evidence And Provenance
+
+- AI answers, data summaries, and document-derived content should expose source, citation, reference item, file, timestamp, or data scope when user trust depends on it.
+- Reference panels, drawers, and preview readers are better than hiding sources in a generic tooltip.
+- If content is generated from uploaded or selected material, preserve the selected source/context in the UI after generation.
+- Community translation: AI-generated post drafts, summaries, recommendations, and moderation explanations should show source/context and editable status.
+
+### AI Chat Trust Patterns
+
+- **Disclaimer placement matters more than disclaimer copy** (NN/g research on AI chatbots discouraging error-checking, 2025): generic footer or system-prompt-area disclaimers ("AI can make mistakes, please verify") scroll out of view after a few exchanges and do not measurably change user error-checking behavior. Place the disclaimer adjacent to the input box (visible whenever the user composes a new message) or pinned to the response area, not in chrome that scrolls away. Pair the disclaimer with a specific user action ("Double-check before applying to high-stakes decisions") rather than abstract warning copy. Repeat the disclaimer during onboarding, not only on first message. Audience-scoped exception: in power-user / professional / internal-tool surfaces (engineering Copilot, ops console, analyst workbench) a permanently sticky disclaimer becomes warning fatigue and consumes prime workspace — there, allow a compact / dismissible / org-managed disclaimer state and instead surface risk inline on uncertain or high-stakes outputs. Consumer / first-time-user / high-stakes-decision surfaces remain the default-sticky case.
+- **Source citations must be verifiable, not decorative**. Style citations distinctly from main response text (different typographic weight or container), place each citation adjacent to the specific claim it supports rather than only at the end of the answer, use meaningful link labels (page title, section heading) instead of generic "Source" / "[1]", deep-link to the relevant passage when the source supports it, and surface the actual quoted text in a hover/preview/expanded reader instead of forcing the user to leave the chat to verify. Set expectation explicitly that "sources may not always link to accurate information" — citation presence is not citation correctness, and well-formatted citations to fabricated or wrong-passage URLs are a common failure mode.
+- **Step-by-step "thinking" or chain-of-thought displays imply certainty the model does not have**. NN/g advises against rendering visible reasoning as a primary trust signal because users read the visible structure as evidence of correctness. If a thinking / expanded-reasoning panel is shown (for transparency or debug), default it collapsed, label it as model self-report not verified reasoning, and do not promote it to the same visual weight as the answer. Confidence scores stated by the model itself are similarly unreliable as trust signals and should not be styled as authoritative percentages.
+- **Promote critical-thinking follow-up prompts alongside regenerate/continue, contextually**. After a substantive answer, surface affordances like "How certain are you of this?", "What might be wrong with this answer?", "Show me the sources you used", "What did you not consider?" alongside (not replacing) regenerate / continue. This converts a one-way oracle into a checkable exchange and creates an in-product habit of verification rather than putting all the verification load on disclaimer copy. Trigger them contextually rather than as always-on UI to avoid nagging professional users who already have their own review workflow: surface them when the answer has low confidence / no citations / high-impact domain, during first-run onboarding, or behind an overflow menu / "/" command surface. Default-on critical-thinking prompts on a power-user surface read as the product distrusting the user.
+- **Refusal copy needs transitional wording for benign blocked requests; terse final refusal is correct for adversarial / regulated requests**. For benign out-of-scope or policy-missing situations (user asked something the model can't answer, missing permission, surface scope mismatch), avoid a flat "I can't help with that" — provide (a) what specifically is out of scope, (b) what near-by request would be in scope, (c) a non-AI fallback path (human support, documentation link, alternate tool) when the user genuinely needs help with the original ask. For adversarial requests — jailbreak attempts, prompt-injection probes, policy-evasion phrasing, compliance-regulated refusals (export controls, PII extraction, illegal content) — a terse, final refusal is the right pattern; suggesting "near-by" requests leaks workarounds and reads as the refusal being negotiable. Decision: benign blocked → transitional + redirect; adversarial / regulated → terse + final. Recent research on Abrupt Refusal Secondary Harm (ARSH, arXiv 2025) documents user disengagement and trust loss when *emotionally-loaded* conversations terminate with bare safety boilerplate; that finding applies to the benign-blocked case, not the adversarial one.
+
+### Error Boundary And Recovery
+
+- Use page or feature-level error boundaries for complex AI/data/document surfaces.
+- Error UI should include a user-facing message, retry, return/home or fallback action, and development-only detail.
+- Global error capture should dedupe repeated messages, track source, component, route, and stack where appropriate.
+- Community translation: feed/detail should degrade gracefully; composer/AI workspace should preserve drafts and selected context after recoverable failures.
+
+### Request And Operation Instrumentation
+
+- API requests should record request id, path/module, method, duration, status, backend code, upload metadata, and active operation id when available.
+- Auth/session invalid states should reset identity and route users to re-authentication without misleading success.
+- Upload, AI generation, publishing, report/moderation, and notification actions should have observable start/success/fail events.
+- Do not expose raw backend errors to end users in production unless they are intentionally user-facing.
+
+### Upload And Long Task UX
+
+- Global upload/task progress should support pending, uploading, success, error, retry, cancel, dismiss, collapse, view/open result, file size, and progress.
+- Long-running operations need stable task ids and visible persistence outside the initiating button.
+- Cancelling in-flight upload or generation should use `AbortController` or equivalent cancellation when possible.
+- Closing a task panel with active work should confirm consequence.
+- Community translation: media upload, AI generation, video processing, moderation review, and export tasks should stay visible and recoverable.
+
+### Feedback Loops
+
+- Like/dislike alone is too weak for AI quality. Ask for structured reasons and optional text when feedback matters.
+- Use feedback reasons that map to product improvements: inaccurate, incomplete, unclear, irrelevant, unsafe, repetitive, too slow, or other.
+- Submit state, disabled state, outside-click behavior, and max length should be explicit.
+- Community translation: collect feedback on AI suggestions, recommendations, moderation decisions, creator tools, and onboarding prompts.
+
+### Dense Data And Operational Tables
+
+- Dense tables should have stable column width roles, persistent row identity, sort/filter state, pagination, and clear empty states.
+- Long cells need truncation detection and portal tooltip/popover that avoids viewport clipping.
+- Column configuration and filters are first-class controls for repeated operations.
+- Community translation: use this for creator dashboards, moderation queues, analytics, notification logs, and AI task histories, not for relaxed consumer feeds.
+
+### Permission And Capability States
+
+- Permission should be centralized where possible and exposed as loading plus explicit capabilities.
+- Hidden or disabled actions should not imply the user can complete work they cannot complete.
+- Failed permission load should default to least privilege and offer refresh/retry where appropriate.
+- Community translation: publish, comment, DM, upload, export, moderate, report, and community-admin actions need visible capability states.
+
+## Build And Launch Signals
+
+Borrow these from finance frontends when a target project supports them:
+
+- Build variants for development/test/production/local modes.
+- Type checking before build for typed frontends.
+- Lint, format, unit tests, coverage, and bundle analysis where available.
+- Preview command for launch smoke testing.
+- Bundle/compression/report scripts for performance-sensitive products.
+- Tests around upload, session restore, panel width, request failure, error handling, markdown/media rendering, and long-content behavior.
+
+## What Not To Absorb
+
+- Do not absorb visual layout, visual style, interaction taste, information architecture, product copy, or consumer-facing polish from these projects.
+- Do not treat these projects as evidence that a UI is good because it exists in production code.
+- Do not copy finance terminology, compliance posture, data schemas, or business workflows into non-finance product UI. When the target product is finance/data, keep terminology intentional, user-safe, and tied to evidence, provenance, permission, and risk states.
+- Do not make consumer community feeds feel like operational analytics tools.
+- Do not overfit to Vue, React, Element Plus, Radix, shadcn, or Next.js; absorb component semantics and quality gates, not framework-specific architecture.
+- Do not treat instrumentation as a substitute for good UX. Users still need clear feedback, recovery, and control.

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

@@ -0,0 +1,106 @@
+# UI/UX Audit
+
+Use this reference when the task is to review, QA, compare, or improve UI/UX in a design file or frontend implementation. It turns the extracted design system, Figma screens, and frontend implementation patterns into a concrete audit procedure.
+
+This is not a domain-compliance audit. For finance, healthcare, legal, or regulated products, use this as the UI/UX layer and add the appropriate domain rules separately.
+
+## Evidence Sources
+
+Use these sources in this order:
+
+1. Current target product code and screenshots.
+2. Relevant source Figma file or design-system file.
+3. `interaction-design-patterns.md` for flow, feedback, state, gesture, and trust-sensitive behavior.
+4. `visual-craft.md` for brand feel, hierarchy, anti-slop, motion, and polish.
+5. `tokens-and-components.md`, `platform-mobile-patterns.md`, and `platform-web-desktop-patterns.md` for tokens and component semantics.
+6. `frontend-code-evidence-map.md` for local code evidence classification and reusable behavior patterns, never as product-domain requirements.
+
+Reusable capability observations already extracted:
+
+- Mobile design system: Button, List, Card, Image, ImageViewer, NoticeBar, FloatingPanel, Dialog, Empty, ErrorBlock, Modal, Progress, Result, Skeleton, SwipeAction, Toast, NavBar, Popup, TabBar, SafeArea, ImageUploader, PasscodeInput, and Example Pages.
+- Desktop design system: Button, Layout, Splitter, Menu, Dropdown, Steps, Form, Input, Select, Upload, Card, Empty, List, Tag, Tooltip, Alert, Drawer, Message, Modal, Notification, Progress, Result, Skeleton, and Table/Tabs marked `【todo】` as weak guidance only.
+- Desktop shell/workbench capability class: sidebar, content cards, login states, workbench, AI assistant, responsive panel collapse, empty cards, process entries, Stepper, Alert, Message, Dialog, and upload/import workflow.
+- Mobile app interaction source: onboarding/login, agreement consent, keyboard states, task cards, tab navigation, AI upload, multi-item review, Toast, Modal, settings/profile, and interaction-note sections.
+- Implementation primitive catalog: see `ui-ux-design-development.md`.
+
+## Audit Severity
+
+Report findings by user impact, not by how easy they are to fix:
+
+- **P0 Blocking**: user cannot complete the primary task, destructive action can happen accidentally, sensitive operation lacks confirmation, auth/permission state is misleading, or mobile layout hides the primary action.
+- **P1 High**: key state is missing, flow loses context, feedback is ambiguous, responsive behavior breaks core reading/action, AI/trust output lacks source or failure handling, or design system divergence creates visible inconsistency.
+- **P2 Medium**: hierarchy, spacing, copy, hover/focus/disabled, empty state, loading, or component choice harms comprehension but has a workaround.
+- **P3 Polish**: microcopy, motion, icon choice, truncation, minor spacing, or visual rhythm issue that does not block the task.
+
+Always include concrete file/line references for code reviews and Figma file/page/section references for design reviews when available.
+
+## Audit Procedure
+
+1. **Classify the surface**: mobile consumer, web consumer, web operational, AI workspace, shared component, onboarding, settings, trust/safety, or analytics.
+2. **Name the primary task**: what the user must be able to do in one sentence.
+3. **Trace the flow**: entry, context, action, feedback, recovery, return.
+4. **Map required states**: happy, first-use, empty, loading, partial, error, retry, permission, disabled, success, undo/cancel, long-content, and responsive states.
+5. **Compare UI primitives**: check whether the implementation uses the closest existing component and token semantics instead of one-off UI.
+6. **Check UX clarity**: hierarchy, action priority, copy, affordance, consequence, source/provenance, and next action.
+7. **Check accessibility basics**: readable contrast, keyboard/focus where relevant, touch target size, visible labels, reduced-motion risk, safe-area/keyboard behavior on mobile.
+8. **Check visual craft**: anti-slop, product-level identity, spacing rhythm, typography scale, consistent iconography, appropriate density.
+9. **Check serious-domain adaptation** when relevant: source, timestamp, partial data, confirmation, audit labels, and no unsafe optimistic UI.
+
+## UI Checks
+
+- Typography hierarchy matches the surface: display for brand/product moments, compact headings for dashboards, readable body text for feed/detail/comment/AI output.
+- Color and radius come from tokens or a clearly stated product reason.
+- Cards, buttons, inputs, tags, tabs, and modals do not all share the same visual weight.
+- Empty, loading, and error visuals are sized to context: compact inside cards/drawers, larger for full-page blocks.
+- Long labels, names, tags, badges, comments, titles, file names, and generated text truncate or wrap predictably.
+- Icons are semantic, not decorative filler. Critical actions use familiar symbols and accessible labels/tooltips.
+- Data-heavy screens keep scan lines stable: sticky headers, aligned controls, consistent row/card heights, and visible active filters.
+- Mobile screens respect safe area, bottom actions, keyboard visibility, and one-handed reach.
+- Web screens collapse secondary panels before damaging primary content readability.
+
+## UX Checks
+
+- The user can identify the current location, current object, current mode, and next action without reading documentation.
+- Primary and secondary actions are visually distinct; destructive actions are explicit and separated.
+- Feedback strength matches consequence: inline < toast < alert < sheet/drawer < modal/dialog < full-page block.
+- Selection, filters, tabs, sort, and comparison targets remain visible after they affect content.
+- A failed upload, failed image, failed AI generation, failed external link, or failed data fetch has a retry or recovery path.
+- Cancel, close, back, clear, remove, retake, replace, undo, or exit behavior is explicit where users can lose work.
+- AI output is not treated as final by default. Provide generating, failed, reviewed, editable, regenerate, source/citation, and copy/share states where relevant.
+- Trust-sensitive data shows provenance: source, timestamp, data scope, confidence caveat, and partial-result labels.
+
+## Code Review Signals
+
+Look for these implementation signals in frontend code:
+
+- Good: reusable async wrapper, explicit `loading/error/onRetry`, toast queue/dedupe, privacy/consent modal, safe-area/keyboard handling, route-driven selected navigation, permission-gated menu rendering, tooltip on truncation, retryable image/upload components.
+- Risk: raw hex colors inside feature components, duplicated local token sets, inline modal styles, `--` values without error/partial labels, console-only failures, silent catch blocks, primary action disabled without reason, layout based only on desktop width, no long-text handling, no retry path.
+- Risk in serious products: optimistic success before server confirmation, missing source/timestamp, ambiguous AI result status, destructive action hidden in generic menu, or external link failure only logged.
+
+## Figma Review Signals
+
+Look for these design-file signals:
+
+- Good: named states, component variants, selected/hover/disabled/loading/error states, explicit empty/error pages, mobile keyboard frames, responsive widths, AI open/closed states, upload/progress/retry states, modal and toast examples.
+- Risk: only happy-path frames, duplicated components without variants, domain-specific old workflow mixed into generic rules, unchecked `【todo】` components treated as final, no narrow-width frame, no error/permission/empty state, visual styles detached from design-system tokens.
+
+## Output Format
+
+When asked to review or audit UI/UX (in any working language), lead with findings:
+
+- Severity, issue title.
+- Evidence: file/line or Figma file/page/section.
+- User impact.
+- Suggested correction.
+
+Then add a short summary:
+
+- What is already strong.
+- What should be fixed first.
+- Any scope limitation, such as "this is UI/UX only, not finance compliance".
+
+Keep findings specific. Do not list generic best practices unless tied to an observed issue.
+
+## Review Discipline
+
+- **Debuggable taste — trace every subjective finding to a broken principle.** "This feels off / cluttered / cheap" is not a finding until it names *which* principle it violates: visual hierarchy, scan path, action priority, state coverage, density fit, affordance/clickability, semantic consistency, trust/provenance cue, or accessibility. If you cannot immediately name it, make a targeted articulation attempt before deciding. When observable user impact remains (the user is slower, confused, distrusts, or cannot complete the task) but the principle is still unclear, mark it `needs articulation / second look` **at its impact-based severity** — never downgrade a real P0/P1 to P3 because the reviewer's vocabulary is weak; severity is set by user impact (per Audit Severity), not by how easily a finding is named. Only when no user-impact evidence survives the articulation attempt is it a preference — then drop it or record P3 polish labeled taste. This keeps reviews defensible and actionable and stops "vibes" findings, without suppressing real-but-hard-to-name defects.

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

@@ -0,0 +1,176 @@
+# UI/UX Design And Development
+
+Use this reference when the task is to design a UI/UX surface and implement it in frontend code. It bridges Figma-derived design rules with reusable implementation patterns observed in mobile and web frontend sources.
+
+This reference is for new-product UI/UX execution. Do not copy education-domain workflows, wording, assets, product assumptions, or information architecture from source artifacts.
+
+## Working Mode
+
+Before coding, define:
+
+- **Surface type**: mobile consumer, web consumer, web operational, AI workspace, onboarding, settings, trust/safety, analytics, or shared component.
+- **Primary user job**: one sentence describing what the user must accomplish.
+- **Density**: consumer relaxed, productive compact, or hybrid.
+- **Source pattern**: which Figma/code pattern is being reused and what domain details are discarded.
+- **State set**: use the canonical taxonomy in `product-surface-patterns.md`, then add implementation-specific loading, retry, cancellation, permission, long-content, and responsive behavior.
+
+Do not start from a decorative layout. Start from the user job, interaction loop, and required states.
+
+## Design-To-Code Sequence
+
+1. **Map the frame to product primitives**: identify shell, navigation, content area, action area, feedback area, modal/drawer/sheet, and terminal states.
+2. **Pick a layout recipe**: use `layout-recipes-and-screenshot-acceptance.md` for workbench, consumer web, mobile, table/list, editor, state, density, and screenshot rules.
+3. **Choose existing components first**: use local codebase primitives or the design-system equivalent before creating custom UI.
+4. **Define tokens before styles**: color, type, spacing, radius, elevation, and motion should map to existing tokens or a named semantic role.
+5. **Implement state model**: represent loading/error/empty/partial/success/permission explicitly in data and UI.
+6. **Implement responsive behavior**: mobile safe area and keyboard behavior; web secondary panel collapse and min/max widths.
+7. **Implement feedback**: inline validation, toast/message, alert/notice, drawer/sheet, modal/dialog, result page.
+8. **Verify by screenshot**: check realistic happy, empty, loading, error, long-content, and narrow-width screenshots before claiming done.
+9. **Verify against UI/UX audit**: run the checks in `ui-ux-audit.md` before claiming done.
+
+## Mobile Frontend Patterns
+
+Use mobile patterns from the local frontend evidence map:
+
+- Use a page-level responsive container for mobile surfaces; avoid ad hoc full-screen wrappers.
+- Put global toast/provider behavior at layout level, not inside individual feature components.
+- Wrap async feature sections with a reusable loading/error/retry abstraction rather than branching every page by hand.
+- Use safe-area utilities for bottom tabs, sticky actions, and fullscreen task surfaces.
+- Use keyboard-aware wrappers for bottom sheets, dialogs, and forms with input fields.
+- Keep bottom navigation durable; use screen-level NavBar for back/close/title behavior.
+- Keep destructive or consent actions in dialog/alert-dialog patterns with explicit primary and secondary actions.
+- For upload/media/review flows, include preview, remove/replace, progress, retry, permission denied, confirm, and completion.
+
+When adapting these patterns, translate the UI copy and information architecture to the new product.
+
+## Web/Desktop Frontend Patterns
+
+Use web patterns from the local frontend evidence map and the desktop design system:
+
+- Use a stable shell: account context, primary navigation, selected state, collapsed state, and content viewport.
+- Use Ant Design-style component semantics where the codebase already has Ant Design or similar mature primitives.
+- Use route-driven selected menu state; do not rely only on local click state.
+- Use permission-gated rendering for menus and actions that users cannot access.
+- Use task/process tabs only for active user work such as uploads, generation jobs, imports, reviews, drafts, or downloads.
+- Use tooltip/popover for truncated names, disabled reasons, metric definitions, and compact explanations.
+- Use drawers for detail inspection or setup when parent list/table context should remain available.
+- Use stepper/progress/result patterns for upload/import/configure/review/publish flows.
+
+When adapting these patterns, avoid carrying over old role names, product categories, or workflow-specific labels.
+
+## Implementation Primitive Catalog
+
+Use this as the canonical implementation primitive catalog. Other references should point here instead of re-listing source-code primitives.
+
+Mobile behavior primitives:
+
+- Page shell and responsive container, such as `ResponsiveContainer`.
+- Async loading/error/retry wrapper, such as `AsyncContent`.
+- Section-level error block with retry action, such as `ErrorBlock`.
+- Toast provider with queue, dedupe, type, and position behavior, such as `MiniToastProvider`.
+- Consequential decision dialogs for consent, update, discard, and destructive actions, such as `PrivacyModal` and `UpdateConfirmDialog`.
+- Keyboard and visual-viewport handling, such as `KeyboardAvoider`; cover iOS visual viewport and Android resize/overlay differences without relying on one browser behavior.
+- Route-aware bottom tabs with active state and restrained animation, such as `TabBar`; active state should survive nested routes and programmatic navigation.
+- Upload/media preview, remove/replace, progress, retry, permission denied, confirm, and completion patterns.
+
+Web/desktop behavior primitives:
+
+- Central token/theme override surface, such as a shared Less/theme file.
+- Route-driven navigation selection and collapsed/expanded shell state, such as `SiderMenus`.
+- Permission-gated menu/action rendering.
+- Process/task tabs for active user work, such as `SiderProcessTabs`; use an event or state model for append, replace, delete, select, and cleanup when work can start outside the current route.
+- Truncation tooltip/popover for long labels and table cells; enable tooltips from measured overflow rather than always showing noisy hover content.
+- Explicit collapse affordance and hover state, such as `SiderFoldLine`.
+- Reusable compact empty component, such as `Empty`.
+- Stepper/progress/result patterns for upload/import/configure/review/publish flows.
+- Sticky filter bars, sticky table headers, and fixed action columns for dense analytics or management tables.
+- Split workbench geometry for review/editor surfaces: compact top context, primary flexible preview/result area, and fixed 320-500px side settings or metadata panel.
+
+## Component Selection Rules
+
+Prefer the closest existing primitive:
+
+- Feed/list/detail: Card, List, Avatar, Image, Tag, Badge, Skeleton, Empty.
+- Creation/AI: Form, TextArea/Input, Upload/ImageUploader, Button, Progress, Toast/Message, Drawer/Sheet, Dialog/Modal, Result.
+- Comments/replies: List, Avatar, TextArea, ActionSheet/Popover, SwipeAction where mobile-appropriate.
+- Notifications: List, Badge, NoticeBar/Alert, Message/Toast, Empty.
+- Creator/moderation/admin tools: Table/List/Card, filters, Tags, Drawer, Modal/Popconfirm, Alert, Result.
+- Analytics: Card, Statistic, chart container, Tooltip/Popover, filter toolbar, empty/error/partial labels.
+- Settings/account: Form, Input, Select/Picker, Switch, Radio/Checkbox, Alert, Dialog.
+
+Create a new component only when no existing primitive can express the interaction or when duplication is already meaningful.
+
+## Token And Styling Rules
+
+- Mobile implementation should map to CSS variables or design-system utility classes for primary/background/text/border/radius roles.
+- Web implementation should map to Less/theme variables or component theme overrides before using raw colors.
+- Raw hex values inside feature components are acceptable only for temporary integration or data visualization palettes; otherwise promote them to semantic tokens.
+- Use semantic radius roles: compact controls, cards/panels, bottom sheets/dialogs, circular icons/avatars.
+- Do not create a second visual system inside one feature.
+- Do not introduce page-local gradients, shadows, or oversized radii unless they are part of the product-level visual direction.
+
+## State Implementation Rules
+
+Every implemented feature should map the canonical state taxonomy in `product-surface-patterns.md` to explicit UI and data ownership. Add these implementation rules:
+
+- Loading should use skeleton or progress that matches the final layout.
+- Empty should explain the missing content and offer the next useful action.
+- Error should provide visible message plus retry or next step when recoverable.
+- Partial should show what loaded, what did not, and whether data is stale.
+- Disabled controls should have a visible or discoverable reason.
+- Success should confirm completion and expose the next action.
+- Cancel/undo should exist when users can lose drafts, selections, uploads, or generated output.
+- Permission state should say what is blocked and what the user can still do.
+
+Avoid silent catches and console-only errors for user-triggered actions.
+
+## AI UI/UX Development Rules
+
+- AI input surfaces must show attachment state, selected source/context, streaming/loading, stop, retry, and failed states.
+- AI output must support copy/share, regenerate, edit or use-as-draft, source/citation where relevant, and reviewed/unreviewed distinction.
+- AI actions should not block the primary manual workflow; use side panels or drawers on web and bottom sheets/fullscreen task views on mobile.
+- Long-running AI tasks should persist visibly as task/process entries, notifications, or progress cards.
+- For serious domains, show source, timestamp, data scope, and caveat near the AI output.
+
+## Responsive Acceptance
+
+Mobile:
+
+- Safe top/bottom areas are respected.
+- Keyboard does not hide the active input or primary action.
+- Bottom action bars do not cover content.
+- Long labels and generated text wrap or truncate predictably.
+- Tap targets are reachable and not crowded.
+
+Web:
+
+- Primary content keeps a usable min width.
+- Secondary panels collapse before the main task becomes unreadable.
+- Dense toolbars wrap or condense predictably.
+- Sidebar collapsed mode remains discoverable.
+- Tables/lists preserve row identity and selected/filter state.
+
+Screenshot acceptance:
+
+- First viewport shows the primary workflow, not a decorative banner or empty dead area.
+- Empty/loading/error states keep the same geometry as the final content where possible.
+- Realistic long labels, long generated text, no data, partial data, and permission-disabled cases do not break spacing or hierarchy.
+- Operational workspaces look like focused work surfaces; consumer surfaces look content-led and approachable.
+
+## Development Review Checklist
+
+Before finishing UI/UX implementation, verify:
+
+- The code uses local primitives and tokens before custom markup/styles.
+- The flow maps to `discover -> inspect -> act -> confirm -> return`.
+- Canonical states from `product-surface-patterns.md` are implemented, not just documented.
+- Feedback strength follows `interaction-design-patterns.md`.
+- Mobile safe-area/keyboard and web responsive behavior are covered.
+- Global feedback providers, async wrappers, and route/workspace state are mounted at the shell level when multiple feature pages rely on them.
+- Long-running uploads, imports, downloads, generation, or review jobs remain visible after route changes and have retry/fail/complete states.
+- Designed states have a code owner: shell/provider state, route state, feature state, server task state, or local draft state. Do not leave a designed state as static markup with no data transition.
+- AI/trust-sensitive output has source, state, retry, and review affordances where relevant.
+- No source-domain terms, assets, or workflow assumptions leaked into the new product.
+- Visual polish passes `visual-craft.md`.
+- Screenshot acceptance passes `layout-recipes-and-screenshot-acceptance.md`.
+- UI/UX review passes `ui-ux-audit.md`.

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

@@ -0,0 +1,111 @@
+# Visual Craft
+
+Use this reference when a task involves frontend visual polish, brand feel, anti-slop review, or turning a design-system pattern into a production-quality app/web interface.
+
+## Scope
+
+Visual distinctiveness must live at the product and design-system level, not as one-off screen art. A product should feel recognizable, intentional, and polished across its core surfaces, whether community, finance/data, AI, operational, mobile, or web. Do not make every screen visually different just to be memorable.
+
+This reference complements `tokens-and-components.md` and `design-execution-checklist.md`. It does not override source Figma tokens, component rules, accessibility, density, or trust/safety requirements.
+
+## Aesthetic Direction
+
+Before designing or coding a visible surface, state the intended visual direction in one sentence:
+
+- What should users feel: calm, lively, premium, playful, editorial, utilitarian, intimate, or creator-focused?
+- Which product behavior should the visual direction support: browsing, replying, creating, AI co-creation, moderation, or returning?
+- What is the memorable product-level trait: recognizable content cards, expressive creator identity, calm AI assistance, refined topic spaces, or trustworthy moderation?
+
+Rules:
+
+- Commit to a coherent product-level visual language and reuse it across surfaces.
+- Use boldness intentionally. A consumer feed can be expressive; moderation, settings, analytics, and account surfaces should usually be quieter.
+- Distinctiveness should come from typography hierarchy, color rhythm, interaction polish, content treatment, and consistent details, not random decoration.
+
+## Differentiation And Coherence
+
+Coherence is the baseline, not the finish line. A fully coherent system can still look like every other product in its category — every competitor can be internally consistent and mutually interchangeable. Coherence keeps the product category-literate; deliberate risk is what gives it its own face. **Precedence:** design-system tokens, accessibility, semantic status colors, trust/safety, high-risk-flow conventions, and rendered-evidence gates all outrank differentiation — the rules below apply only to what remains after those are satisfied, where "satisfied" means recorded through the owning checkpoint or gate with evidence, not self-asserted. An unknown or unchecked gate is not satisfied; treat it as blocking.
+
+- **Name one product-quality anchor first.** State the single thing a first-time user should take away. For brand or consumer surfaces this is often a memorable visual signature (a feeling, a posture); for utilitarian, internal, or high-trust tools it is more often speed, scannability, confidence, recoverability, or quiet consistency. Every aesthetic decision should serve that anchor without weakening usability. A design that tries to be memorable for everything is memorable for nothing.
+- **Differentiate with deliberate, costed risks — never on the safety-critical layer.** Beyond the category-baseline safe choices users already expect, take one or two intentional departures (an unexpected typeface, a non-semantic accent peers underuse, denser or looser spacing, a grid-break, a motion signature), each staying inside the accessibility baseline (readability, target size, focus/reading order, reduced-motion, long-content, responsive stress). For each, state what it gains and what it costs; an unjustified departure is noise, not identity. On any safety-, trust-, privacy-, or compliance-sensitive surface — money/quota, auth/account/session, permissions, user/tenant data, moderation, destructive/public/external-visible actions, AI disclosure, error/retry/recovery, audit, and anything the skill's risk tags (see `feature-risk-router`) flag — convention is the safety mechanism: do not differentiate by altering semantic colors, status treatment, critical control placement, confirmation patterns, readability, or recovery conventions. Differentiate only in surrounding brand tone or non-critical polish.
+- **Coherence is a system property: re-validate on every override.** When the user or a later iteration changes one axis, re-check that the others still cohere (an expressive aesthetic paired with timid motion, a bold palette with no supporting decoration, an editorial layout on a data-dense surface). Nudge gently and offer a fitting alternative. For aesthetic-preference tradeoffs the user's final choice wins (recommend, do not decide) — but only among options that already pass the precedence gates above; a preference never converts a failing accessibility, trust/safety, privacy, compliance, semantic-status, or rendered-evidence gate into "accepted" (record blocked / handoff per the owning gate instead).
+- **Avoid unreasoned convergence to generic defaults.** Do not re-reach for the same generic safe default across iterations without a reason, and note the subtle trap that the well-known "safe alternative" to an overused default (font, layout, accent) is itself a generic default. A design-system, platform, or accessibility default is itself a sufficient reason — challenge only habit-driven defaults outside those systems, and record the reuse reason rather than invent novelty. Changing established product/design-system tokens or component semantics goes through the design-system source-of-truth path (`tokens-and-components.md`, `design-system-source-of-truth.md`), not front-end-only churn.
+
+## Anti-Slop Checks
+
+Avoid generic AI-looking frontend patterns unless the product's own design system explicitly requires them:
+
+- Purple/blue gradients on white backgrounds as the default visual identity.
+- Repeated three-column feature grids with icon-in-circle, bold title, and two-line description.
+- Decorative icons inside colored circles used everywhere.
+- Decorative blobs, waves, or geometric shapes that are not part of the product's own design language.
+- Emoji used as generic UI iconography or section decoration in place of consistent icons — unless emoji are the product content, user-authored or reaction vocabulary, or an established design-system semantic.
+- Stock-photo placeholder blocks, generic/fake testimonial sections, or the cookie-cutter left-text / right-image hero used as a default layout — real sourced proof and a deliberate split hero are fine when justified by the design checkpoint.
+- Filler CTA labels such as "Get Started" / "Learn More" that do not name the actual action.
+- Lorem ipsum or "your text here" as readable user-facing copy in shipped, review, or acceptance surfaces — use real or realistic content from the spec/source. Loading/skeleton states are still required, but use inert skeleton geometry or localized loading text, not lorem; non-user-facing component-demo fixtures are exempt.
+- Center-aligning most headings, body text, cards, and action groups.
+- Applying the same large border radius to cards, buttons, inputs, tabs, and containers.
+- Generic marketing copy such as "unlock the power", "all-in-one solution", "revolutionize", or "streamline your workflow".
+- Defaulting to neutral system-like typography without a deliberate brand reason.
+
+Design-system typography roles count as a deliberate brand reason when they already encode the product's intended voice.
+
+If a pattern appears in a Figma source, preserve it only when it has a clear product purpose or established token/component role. Do not amplify source artifacts into a generic template.
+
+## Typography
+
+- Use the design-system typography roles first.
+- Give major brand/product surfaces a clear display rhythm, but keep feed body text, comments, notifications, forms, and moderation text highly readable.
+- Do not introduce a new font family unless the product needs a brand move and implementation can load it reliably.
+- Avoid more than two primary font families in a product surface unless the design system already supports that.
+- Keep heading hierarchy meaningful; do not use large type to compensate for weak layout structure.
+- **不同字号文字并列时按 baseline 对齐**（不是 center align）— 同行混排数字+标签 / icon+文字时基线对齐让视觉读得整齐；center align 在字号差大时会产生"漂浮"感。
+- **Line-height 与 font-size 成比例**（小字 line-height ratio 大、大字 ratio 小）— 通常 body 14-16px 用 1.5、heading 32px+ 用 1.1-1.2；line-height 不该全 product 一个固定 px。
+- **彩色背景上默认不用 neutral grey 做 de-emphasis**：层次首选同色系亮度变化（lighter / darker tint of the bg）；neutral grey 在彩色 bg 上常 contrast 失败且失去 grey 的层次语义。例外：token 化的 warm/cool grey 经 contrast 测试通过可用。
+- Typographic micro-craft (apply unless the design system already encodes its own): build the size scale on a consistent ratio (a major-third 1.25 or perfect-fourth 1.333 step is a common starting point), not arbitrary per-screen sizes; keep prose/body measure roughly 45–75 characters per line (~66 comfortable) — this targets reading columns, not data tables, code, dense forms, or dashboards; do not skip heading levels for visual size (don't jump `h1`→`h3` — pick the right size for the chosen level); use real typographic characters (curly quotes, a real `…` ellipsis glyph) in human-facing editorial copy, not in code, logs, CLI text, identifiers, or ASCII-constrained files; use proportional numerals in prose and reserve `font-variant-numeric: tabular-nums` for numbers that align in columns, counters/timers, or metrics that update in place.
+
+## Color And Theme
+
+- Use semantic tokens before raw colors.
+- Let one primary color family lead and use sharp accents sparingly for interaction, AI, trust/safety, or creation moments.
+- Avoid timid, evenly distributed palettes where every module has the same visual weight.
+- Preserve Light/Dark mode behavior where the surface supports it.
+- Trust, warning, danger, moderation, and AI provenance colors must remain understandable and accessible.
+- **Never encode actionable meaning by color alone** — status, error/risk, selection, comparison, or a required category distinction must pair color with a label, icon, shape, position, or pattern so color-blind users (≈8% of men have red-green deficiency) and grayscale contexts still read it; avoid a red-vs-green-only distinction. Purely decorative/brand tint may stand alone when losing the color would not change understanding or action.
+- Dark mode is a redesign, not a lightness inversion: resolve text/surface/border/accent/status from tokenized Light + Dark pairs in the design-system source (no Dark pair = no dark-mode claim); separate surfaces by **elevation** (lighter = higher) rather than flipping lightness; prefer softened near-white body text over pure `#FFF` and validate WCAG contrast per surface/elevation (a single fixed near-white can fail on mid-dark surfaces); tune accent saturation per role so saturated colors don't vibrate on dark surfaces, without mechanically desaturating brand/status colors; and declare `color-scheme: dark` (or `light dark`) once the controls/tokens are actually themed, so supported form controls, scrollbars, system colors, and the page canvas render consistently.
+- Before introducing or substantially reshaping a screen, state the visual direction: typography source, primary token, neutral/background scale, radius/shadow role, and which values come from the existing theme. If the existing theme is weak or no strong reference exists, compare two or three compact visual directions instead of styling from habit. When alternatives are genuinely useful, make them **meaningfully different on the variables left after the Precedence gates** — hierarchy, density, surface/material treatment, attention model, and (where not token-fixed) type pairing or color temperature; you need not vary every axis, and never change design-system typography roles, component semantics, semantic-status colors, contrast, or accessibility behavior just to look different. If one direction is clearly product-correct, or the surface is utilitarian/high-trust and should reuse the existing visual language, state that instead of inventing filler options. Direction swap-test: with the same content and constraints, if two options share the same hierarchy, density, token rhythm, component emphasis, and attention model, merge them or replace the weaker one.
+
+## Motion And Interaction Polish
+
+- Use motion for high-value moments: first load, feed refresh, publish success, AI generation, upload progress, notification arrival, or trust-state transition.
+- Prefer one coherent motion system over scattered decorative micro-interactions.
+- Motion must not block reading, replying, moderation, publishing, or recovery actions.
+- Provide stable hover, focus, active, disabled, loading, selected, and error states for interactive elements.
+- Respect reduced-motion and low-performance contexts when implementation supports them.
+
+## Spatial Composition
+
+- Consumer relaxed surfaces can use more breathing room, visual rhythm, and atmospheric detail.
+- Productive compact surfaces should favor density, scanning, sticky controls, and predictable alignment.
+- Use asymmetry, overlap, or grid breaks only when they improve orientation or brand feel without harming readability.
+- Keep long content, metadata, badges, tags, and action groups from overlapping or pushing primary content out of view.
+- Text containers should have readable line lengths; avoid full-width paragraphs on desktop.
+- **Classify the surface archetype by region, not by page.** One page usually mixes archetypes — marketing/story, app/workbench, dashboard/analytics, onboarding/auth, trust/safety, docs — and each follows different composition rules. Marketing/story: brand-first hierarchy, the first viewport reads as one composition (a poster, not a document), one job per section, and cards earn their role — a card should group or enable something (pricing, comparison, proof), not just tile content into a generic grid. App/tool/dashboard: calm surface hierarchy, dense but readable, minimal chrome, one accent, navigation and status legible over decoration. Any region with live data, controls, or status takes app/tool composition plus the required-state and trust rules even inside a landing page.
+- **Subtraction is the default — after inventorying what is required.** Before cutting, map the required states (loading/empty/error/success/partial), accessibility affordances, and trust/provenance cues; only decorative or redundant elements are eligible. Within that eligible set, if an element does not earn its pixels, cut it and fix visual noise by removal before addition — decorative card grids, redundant headings, and chrome that competes with the primary task go first. Required states, accessibility affordances, and trust cues are never "chrome".
+
+## Backgrounds And Details
+
+- Background treatment should clarify product mood or depth; it should not compete with content.
+- Use texture, layering, shadow, glass, patterns, or atmospheric detail sparingly and consistently.
+- Do not add decorative effects that reduce contrast, scroll performance, or mobile clarity.
+- Cards and panels should not all look equally loud. Establish a hierarchy between feed content, side panels, AI, and system messages.
+
+## Acceptance Questions
+
+Before calling frontend visual work polished, ask:
+
+- Does the screen have a clear product-level visual point of view?
+- Does it avoid generic AI frontend patterns?
+- Does the visual direction support the target product loop instead of distracting from it?
+- Are typography, color, spacing, radius, motion, and background choices tied to existing tokens or an explicit product reason?
+- Does the screen remain readable, accessible, and performant on mobile and desktop?