@ccoalm/ccl-skills 0.1.0

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

@@ -0,0 +1,79 @@
+# Product Surface Patterns
+
+Use this as the canonical product-surface taxonomy for the organization UI/UX skill. Scenario references such as community, finance/data, AI workspace, mobile, and operational workbench add domain-shaped examples, but this file owns the generic state and surface model.
+
+## Surface Model
+
+- Consumer discovery: browse, search, feed, detail, profile, recommendation, and return loops.
+- Creation and editing: draft, validate, preview, generate, upload, save, publish, discard, and recover.
+- Decision and review: inspect evidence, compare options, see provenance, accept/reject, annotate, export, or escalate.
+- Operational workbench: scope/filter, queue, input/control region, review/output region, status strip, history, assignment, and recovery.
+- Account and settings: onboarding, consent, login, verification, profile, privacy, notification, billing/quota where relevant, and destructive account actions.
+- Analytics and data: overview, drilldown, comparison, dense table/chart, saved view, data freshness, permission scope, and export.
+- AI-assisted surfaces: prompt/input, generation, streaming/progress, citation/source, edit/review, regenerate, save/publish, refusal/degraded state, and accountability metadata.
+
+## Canonical State Taxonomy
+
+For every product feature, map these states before implementation or acceptance:
+
+- Empty: first visit, no data, no permission-scoped result, no search result, no configured source.
+- Loading: initial load, pagination, refresh, upload, generation, export, background sync, or long job.
+- Slow or weak network: delayed first feedback, retryable fetch, stale cache, degraded media, timeout, or queued state.
+- Partial: some data exists but media, source, permission, generated content, or dependency failed.
+- Error: network failure, validation failure, permission denied, upload/export failed, backend refusal, provider unavailable.
+- Disabled: unmet requirement, missing permission, unsafe state, invalid input, pending dependency, unsupported platform.
+- Success: saved, submitted, published, exported, generated, followed, approved, completed, or applied.
+- Reversal/recovery: undo, cancel, retry, restore, discard, rollback, leave, return to prior context.
+- Trust/risk: destructive, public, costly, permission-sensitive, privacy-sensitive, money/quota-sensitive, AI-generated, compliance-like, or support-traceable action.
+
+## Product Loop
+
+Use this default loop unless the product has a stronger one:
+
+1. Enter or discover the surface.
+2. Inspect current scope, data, content, or evidence.
+3. Act with visible primary and secondary options.
+4. Confirm only when consequence, cost, public visibility, privacy, or irreversibility requires friction.
+5. Recover or return with context preserved.
+
+## Scenario Lenses
+
+- Community/social: use `scenario-community-patterns.md` for feed, creator, interaction, topic, notification, moderation, and social loop specifics.
+- Education: when the target product is explicitly education, map learning/teaching/assessment/resource workflows intentionally; source education terms may be used only when they match the target product context.
+- Finance/data/trust-sensitive: use `trust-sensitive-ai-and-data-patterns.md`, `analytics-visualization-interactions.md`, and `operational-processing-workflows.md` for evidence, provenance, dense analysis, permission, and review-before-action patterns.
+- Mobile/app: use `platform-mobile-patterns.md` and app implementation skills for safe area, keyboard, orientation, native shell, and device acceptance.
+- Web/workbench: use `platform-web-desktop-patterns.md` and `layout-recipes-and-screenshot-acceptance.md` for shell, density, responsiveness, and screenshot acceptance.
+
+## Workflow Surface Extensions
+
+Use these generic workflow patterns when a product surface needs more than a simple page/detail/form. They replace source-specific formal product references; exact old business terms stay in provenance only.
+
+- Dense creation/import: source choice, upload/import, parsing or matching, manual correction, validation, preview, confirmation, save/publish, and recovery.
+- Structured editing: tree or outline plus selected-node editor, explicit add/move/split/merge/reorder/delete actions, bulk selection count, and status tags for missing/generated/verified/conflict states.
+- High-throughput review: persistent task identity/progress/filter header, artifact-dominant center, compact side or bottom controls, previous/next, annotation, final confirmation, failed media retry, and queue-end recovery.
+- Upload/processing pipeline: no source, upload, server processing, preview, completed, unsupported, failed, retry, and separate local-transfer versus server-processing state.
+- Analytics/report: stable filter bar, decision-driving metrics, chart plus inspectable table/list, drill-down path, comparison labels, permission/partial-data states, and export/share where useful.
+- Management list: search, filters, status tabs, batch action, import/export, create action, dense identity/status rows, side preview, and destructive or high-commitment modal.
+- Progress/quality monitoring: separate "how much is done" from "how good or risky it is"; support pivots by item, owner, group, status, and exception.
+- Assignment/ownership: separate unit setup from owner assignment, show unassigned/partial/assigned/in-progress/locked/completed/read-only states, and summarize affected scope before bulk apply.
+- Role owner configuration: when a product object needs different owner groups by unit, role, permission, or processing mode, show object context, role columns/cards, existing owners, add/edit/reuse actions, and empty-role affordances in one compact workbench. Long owner lists should summarize counts with full tooltip/details; reuse/copy must show the target scope and exclude the current source by default.
+- Owner selection drawers: title the drawer with the current unit and role, separate candidates from the selected list, keep selected count visible, support search and cascade filters, show qualification/relationship metadata beside each candidate, use all/partial selection states, and let users remove selected people from the selected area. A large or multi-tenant candidate list may use a tree, but leaf identity, disabled reason, and removal behavior must remain obvious.
+- Permission exception lists: treat early-access, blocked-access, and other exception owners as explicit risk lists, not normal ownership roles. The UI should explain when the exception takes effect, what output or action it changes, whether the permission survives lifecycle transitions, and how to undo it.
+- Resource/asset center: stable category rail, main list/card area, search/filter/sort, upload states, preview/full-view, ownership/availability status, and before/after identity for replacement.
+- Post-publish correction: restricted access, audit, original versus corrected values, dependent-output impact, confirmation, and reversible or support-traceable paths.
+- Entity tracking/comparison: support single-entity and all-entity modes as siblings, keep baseline/comparison visible, pair trend charts with exact row/detail evidence, preserve drill-down context, and label current/previous/target/benchmark directly instead of relying on color alone.
+- Configurable project or event management: split creation, editing, viewing, and post-publish management; keep list actions near the table toolbar; progressively reveal dependent settings; support save-after-edit and view-only states with the same layout; preview reused template data before it replaces current values; confirm destructive lifecycle actions with specific consequences.
+- Lifecycle object management: when an object moves through multiple operational phases, the list item should show identity, scope, status, permission-relevant tags, and the next executable phase together. Model each workflow variant with its own phase labels and action states, including not-started, available, hover/pressed, in-progress with percent where useful, paused, completed, exception, no-permission, and disabled-with-reason.
+- Lifecycle management actions: separate high-frequency actions from high-risk actions. Detail, edit, member/owner management, progress inspection, notification/publish, export, and check/recalculate actions can live in an overflow or drawer entry; pause/resume, end/reopen, delete, overwrite, and publish/unpublish need consequence copy, scoped confirmation, pending state, success refresh, and a visible return to the originating item.
+- Creation and configuration drawers: complex creation should not be a single flat form. Use mode selection first, then reveal dependent fields, batch-versus-per-item settings, member/scope selection, optional templates or reuse, and help/documentation entry only where it supports the current decision. Once downstream records, processing, or published outputs exist, mode and scope controls become locked or conditionally editable with a local reason.
+- Participant or membership rosters: treat roster management as its own workbench, not a subform. It needs tabs or segments for whole-object versus per-unit scope, cascade filters, search, missing-required toggle, count summaries, single add, batch import, reuse, template creation, export, batch delete, and deletion locks after downstream processing starts.
+- Roster identity and numbering: when members need local identifiers, seats, slots, groups, or access codes, expose generation/copy-from-source modes, minimum and maximum length or format constraints, overwrite consequences, newly-added-only versus all-member scope, optional auto-download/export after generation, and downloadable repair lists for invalid records.
+- External roster sync: when current membership can be refreshed from an authoritative external source, show a preview-before-apply drawer with added, removed, and changed rows grouped by scope. The preview must state whether it is informational only or actually applies the change; the apply action needs overwrite copy, scoped selection, pending state, and post-apply refresh.
+- Roster reuse and templates: reuse should be a two-step flow: searchable source/template list, then preview with metadata, per-unit tabs if applicable, counts, sticky member table, delete-template action when allowed, and explicit overwrite confirmation before applying. A successful reuse should state that out-of-scope members were filtered instead of implying a blind copy.
+- Automated roster import and identity repair: when a roster comes from file import, external sync, recognition, AI extraction, or generated identifiers, keep automation accountable. Show required scope before import, source/template download, upload and server-processing states, successful file identity, reupload, error report download, invalid-identity repair instructions, and a post-repair return action. Do not make a toast the only place users learn that imported or generated identities failed.
+- Roster scope inheritance: when a sub-scope inherits a whole-object roster, show the inheritance note near the scope tabs and make the edit path explicit. If users switch a sub-scope to independent membership, warn which future imports, generated identifiers, templates, and external sync actions will affect only that sub-scope.
+- Notification and publish settings: distinguish enablement, automatic/manual mode, recipient or role scope, content/template choice, preview/sample where the outcome is hard to infer, read-only inherited settings, and cancel/unpublish states. A publish scope change should summarize exactly who or what can see the output after confirmation.
+- Check/recalculate operations: a "check" action that triggers computation is a lifecycle transition. Show when prerequisites are missing, when computation is already running, when output is ready to view, and when the calculation state is abnormal. Polling or refresh should update the originating item, not leave the user guessing from a toast.
+- Object list import and repair: separate single add, batch import, reuse, preview update, and export; validate invalid, duplicate, missing, and unmapped rows before commit; provide templates for strict formats; preview ambiguous identity matches; keep selectors/tabs stable across scope changes; do not silently clear unsaved data.
+- Drawer and modal repair patterns: place global drawer alerts directly below the title when they affect the whole drawer, use consistent side padding, avoid nested rounded alerts that fight the container, and keep sibling title bars visually consistent.
+- Workflow conflict rules: prefer design-system tokens over local product exceptions unless repeated current sources prove the exception; preserve platform-specific behavior when mobile and desktop differ; keep newer/current sources over archive/backup; merge repeated patterns with different labels into generic rules; treat image-only patterns as weak evidence unless confirmed elsewhere.

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

@@ -0,0 +1,113 @@
+# Resource Management Interactions
+
+Use this reference when designing or implementing resource libraries, cloud-drive style asset centers, media/template management, reusable knowledge sources, saved prompts, or content-pack management.
+
+Source provenance lives in `source-map.md`. Reuse the asset-management mechanics, not the original source-domain vocabulary.
+
+## Core Pattern
+
+A resource center is a managed inventory, not a passive file list:
+
+- Users need to find, preview, trust, reuse, publish/share, update, and recover resources.
+- Navigation, ownership, status, and actions must stay visible at list density.
+- Upload/import is part of the resource lifecycle and needs the same care as browsing.
+- Resource identity should survive preview, replace, move, publish, archive, and batch operations.
+- Classify mixed sources by section or frame, not by file name. Current mainline frames can be positive visual and interaction evidence, while sections marked "reference", "to optimize", "old version", or similar should be downgraded unless code or current frames confirm them.
+
+## Information Architecture
+
+- Use a stable left tree, category rail, or workspace selector when resources have durable hierarchy.
+- Use top-level tabs or segmented controls for major availability states: personal/private, shared, pending publish, published, platform/library, team/workspace, archived.
+- Keep search, filters, sort, create/upload, import/export, and batch actions in a predictable toolbar.
+- Do not split closely compared resource states into unrelated pages; use tabs and filters when users repeatedly compare them.
+- Show active category/filter state near results so the current scope remains clear after scrolling.
+- For deep libraries, keep the left tree and the result toolbar independent: tree controls scope, tabs/filters control state, and sticky filter bars preserve the active query after scrolling.
+- For desktop asset workbenches, use a stable shell: global navigation, a 240-280px hierarchy rail when the taxonomy is deep, a compact filter block, and one dominant results/preview region. Keep the active scope, resource type, and availability state visible at all times.
+- For mainline desktop resource workbenches, keep the shell dense and operational: a narrow global nav, a left resource rail around 184-280px when needed, a main work area around 1200px at 1440-class width, 32-40px top controls, compact tabs/dropdowns/search in one control band, and list/card content below. Avoid hero spacing, oversized empty panels, or decorative cards that reduce scan density.
+- Sticky filter mode should compress, not disappear. Preserve the current query, show the compressed state, expose clear/reset and expand actions, and avoid moving the result list when the filter collapses.
+- Treat scope, sub-scope, resource type, hierarchy node, filter mode, search query, and selected item as separate axes. Do not merge them into one tab set or one query object unless the implementation still clears stale dependent state deliberately.
+- For heterogeneous search results, keep result types visually separable through columns, sections, or tabs. Use a compact search result header, keep filters near the result type, and show the active query, active scope, no-result state, and return path so users do not lose whether they searched the full library or one resource family.
+- Directory and taxonomy management needs its own interaction model: empty tree, selected node, add/edit/delete, reorder, max-depth or max-count limits, read-only nodes, nodes with children, nodes already used downstream, rename conflict, unsaved edits, cancel, save, and restore to the affected node after refresh.
+- Directory finalization should not be a blind submit. If some leaf nodes are unbound, disabled, hidden by current filters, or no longer valid after refresh, show the affected scope and require explicit continue/cancel. Preserve the selected collection, volume or tab, and return focus to the invalid node or refreshed node after the operation.
+
+## Resource List And Card Rules
+
+Every list row or card should expose enough identity for confident reuse:
+
+- Name/title, thumbnail or type icon, resource type, source, owner, visibility, status, updated time, and primary usage signal.
+- Compact row actions for preview, use/import, share/publish, edit, move, duplicate, download/export, archive, and delete where relevant.
+- Badges for generated, imported, shared, pending, published, archived, private, failed, and unsupported states.
+- Tags describe attributes; do not overload tags as filters, permissions, and workflow status at the same time.
+- Long names and dense metadata must wrap or truncate predictably without hiding status or primary action.
+- Repeated resource actions should use stable placement: preview/use/open first, then edit/replace/share/download, then archive/delete. Do not make users rediscover actions per card state.
+- Cards that represent in-progress generated/imported resources must make "still processing", "failed", "retry", and "continue editing" visibly different from complete resources.
+- Status labels need an authoritative vocabulary. Do not create ad hoc chip colors or mixed terms per screen; define which labels are workflow states, source/type labels, availability labels, and user actions.
+- Selection baskets or temporary collections should show count, item identity, remove/clear, stale or unavailable items, disabled commit reasons, and the final action. A floating basket is a commitment surface, not decoration; for dense desktop, use a narrow vertical entry plus a drawer sized to content complexity. A compact metadata basket can use a 480px-class drawer, while rich question/media previews may need a wider 760-820px-class drawer.
+
+## Upload, Import, And Parse States
+
+Treat upload/import as a first-class workflow:
+
+- No category selected, selecting files, uploading, uploaded, parsing, preview available, completed, unsupported type, failed parse, partial success, duplicate detected, and retrying.
+- No directory/category available, directory maintenance required, or missing upload destination should be explicit states rather than hidden validation errors.
+- For batch import, show per-file status and summary counts.
+- For AI knowledge sources, show source file, parse status, freshness, visibility, and whether the resource is usable by AI.
+- If a resource can be replaced or swapped, show before/after identity and preserve a cancel path until commit.
+- Permission denied or quota full should explain the blocked capability and the available next action.
+- AI parsing or enrichment needs a real waiting state, not just a spinner: show what is being processed, what action would interrupt it, whether retry is possible, and where the user returns after success.
+- Save-to-library from a lightweight capture or H5 entry is not the same as a full library surface. The lightweight flow should validate destination metadata and commit status; the full workbench owns search, hierarchy, sharing, editing, and lifecycle management.
+- Creation entry should first dispatch by resource type, because file support, metadata, parse path, editor handoff, and post-save landing can differ by type.
+- Metadata forms should cascade rather than accumulate invalid state. When a parent field changes, clear incompatible child fields, tree selections, type filters, and derived IDs; show required-field blockers before upload or parse starts.
+- Long-running parse jobs should expose submit, parsing, background/continue, completed, failed, retry, reupload, and cleanup-on-close states. Polling timers or subscriptions must stop when the dialog unmounts.
+
+## Preview And Detail
+
+- Use drawers or side panels for quick details; use large preview or full-screen mode for media, documents, or rich artifacts.
+- Keep return navigation obvious. Do not rely on browser back for core resource flow.
+- Detail views should show metadata, history, usage, permissions, related resources, and destructive actions.
+- Preview should make public/private or shared/published consequences visible before use.
+- For generated or AI-derived resources, expose source/context and review status where trust matters.
+- Rich resource preview should preserve object orientation. When a preview has an outline, page list, chapter tree, question list, media strip, or related-detail rail, selection in the rail and position in the main preview should stay linked; hover/click/focus states should tell users which child item is being inspected before they reuse, edit, download, or share it.
+- Download/export settings are decision dialogs, not passive confirmations. Group output format, visibility of sensitive fields, page/layout preset, and output variant; show selected state clearly; keep cancel and commit fixed at the bottom.
+- Long-running downloads or exports need a visible task surface: queued/running, finished, failed, retry/download action, file identity, retention window, and empty state. Do not make users guess whether a generated export is still being prepared or already expired.
+- Edit/replace flows should preserve user orientation: identify the current item, allow inline edits for small fields, cap rich text/editor height with local scrolling, and confirm destructive removal of parent items that would delete children.
+- Tag or metadata editing should distinguish generated/default metadata, user-edited metadata, locked metadata, and metadata already used downstream. If a resource has been used in another workflow, make editability and consequences explicit.
+
+## Permissions, Sharing, And Publishing
+
+- Distinguish ownership from availability: owner, editor, viewer, team/workspace, public/published, platform/library.
+- Permission or publish changes should show before/after impact and affected scope.
+- Batch changes must show selected count, affected categories, and irreversible consequences before commit.
+- Archive is preferable to delete when recovery or audit matters; delete requires explicit confirmation.
+- Shared resources need conflict handling: already exists, newer version exists, missing permission, or cannot overwrite.
+- Sharing dialogs should show both the target availability scope and the resource attributes being shared. Disable commit until the required scope is selected, and make unshare/cancel-share a separate explicit action.
+- Shared-state buttons need two distinct modes: an unshared action that opens the scope/attribute confirmation flow, and a shared state that exposes cancel/unshare without reopening the create-share flow. Refresh the authoritative shared state after either operation.
+- Permission-limited metadata should render as read-only rather than disappearing. This prevents users from thinking the resource has no metadata and protects trust in shared libraries.
+
+## Responsive And Hosted Boundaries
+
+- A desktop resource workbench can be hosted inside a mobile app shell only when the host contract is explicit. If the mobile H5 only provides a save or entry action, do not pretend the full library is mobile-optimized.
+- Hosted resource flows must account for safe area, injected app info, native/web storage availability, page-ready handoff, back behavior, orientation, and weak network recovery.
+- For narrow desktop or tablet stress widths, collapse secondary panels and advanced filters before shrinking the main preview or list below readable width.
+- Verify 1280-class and 1440-class desktop widths separately. At 1440, the workbench should show global navigation, active resource scope, controls, and usable results together. At 1280, secondary text/actions may compress or move into overflow, but the active scope, search/filter entry, primary list/card identity, and primary action must remain visible.
+- At 1280-class width, preserve the left rail and primary content before preserving every secondary control. A workable pattern is roughly 184px navigation plus a 1060px-class content region with compact 30px tabs and a single-line divider/header.
+- For mobile-first asset management, prefer task-specific entry flows, saved/recent lists, and detail/edit sheets over copying a dense desktop left-tree workbench.
+
+## Community Translation
+
+- AI cloud drive -> creator asset library, AI knowledge base, saved prompt library, reusable media pack, moderation evidence library.
+- Resource center -> topic templates, content-pack marketplace, onboarding assets, creator kit, community rule library, event materials.
+- Replace/swap -> change source media, update template, refresh AI context, replace cover/banner, revise reusable content block.
+- Publish/share -> make asset available to collaborators, community members, creators, moderators, or AI workflows.
+
+## Acceptance Checklist
+
+- Users can tell where they are, which resource scope is active, and what actions are allowed.
+- Search/filter/sort remain available at list density.
+- Upload/import/parse has item-level progress, failure, retry, and partial-success handling.
+- Resource identity, ownership, visibility, status, and usage are visible before reuse.
+- Preview, replace, share/publish, archive, and delete each have clear confirmation or recovery behavior.
+- Tags, permissions, and workflow states are visually distinct.
+- Download/export settings expose the consequences of selected format, visibility, layout, and output variant before commit.
+- Hosted or H5 entry flows state their boundary: save/capture entry versus full resource workbench.
+- Directory edits and resource creation can be completed, cancelled, retried, or resumed without losing the current library context.

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

@@ -0,0 +1,133 @@
+# Scenario Community Patterns
+
+Use this scenario lens only when the target product is a community, social, creator, feed, topic, notification, moderation, or AI-social surface. The goal is not to reproduce source workflows; the goal is to design a polished community product with complete states and reusable design consistency.
+
+This file merges the former community source-pattern reference and external community benchmark reference. Apply these rules only when the target surface matches; they are not the default model for finance, education, operational, or generic product UI.
+
+## Product Surface Model
+
+Default community surfaces:
+
+- Home/feed: content discovery, recommendation, following feed, topic feed, and refresh/loading states.
+- Detail: post/thread/content detail, comment tree, related content, AI summary or assistant entry.
+- Creation: text/image/video/link creation, draft, preview, publish, failure, and post-publish feedback.
+- Interaction: like, collect/bookmark, comment, reply, share, follow, join, mention, vote, react, and report.
+- Identity: profile, creator card, user badges, level/points, relationship state, membership state, and privacy boundaries.
+- Community/topic: topic landing, pinned content, rules, moderators, join/follow state, and activity indicators.
+- Notifications: interaction notifications, system notices, moderation notices, AI task progress, and digest cards.
+- Trust and safety: report, block/mute, content hidden, account restricted, sensitive content, and moderation review.
+- AI interaction: assistant panel, prompt shortcuts, generated suggestions, streaming/loading, retry, citation/source, user correction, and failed-generation states.
+
+## Source-To-Community Mapping
+
+Translate old source patterns into community equivalents:
+
+- Workbench/dashboard cards -> home feed modules, creator task cards, notification cards, onboarding tasks, or AI assistant suggestions.
+- Exam/process states -> community workflow states such as draft, publishing, under review, visible, limited, rejected, hidden, pinned, featured, or archived.
+- Sidebar/process entries -> topic navigation, creator tools, moderation queues, notification categories, or AI workspace history.
+- Question/answer/analysis regions -> post body, comments, AI response, annotations, quoted content, and explanation panels.
+- Answer-card/card-making settings -> creation editor settings, post format controls, audience visibility, content structure, and preview settings.
+- Upload/parse/manual-correction flows -> media upload, link preview extraction, AI content parsing, draft recovery, and manual edit fallback.
+- Scan/progress panels -> upload progress, generation progress, review progress, sync state, or background task state.
+- Score/metric configuration -> creator/community analytics, engagement breakdown, retention indicators, quality signals, or moderation metrics.
+
+## Interaction Principles
+
+- Make the primary loop obvious: discover content -> react/comment/follow -> create or return.
+- Keep creation entry visible but not dominant over consumption.
+- Every social action needs clear pre-action, active, success, undo, disabled, and error states.
+- Avoid admin-heavy density in consumer views; reserve dense layouts for creator tools, moderation, settings, analytics, and AI workspaces.
+- Use optimistic UI for low-risk actions like like/bookmark/follow, but show retry/failure when the backend rejects the action.
+- Use explicit copy for destructive or externally visible actions such as delete, report, block, publish, and public sharing.
+- Keep AI surfaces accountable: show generation/loading, retry, edit, source/citation when relevant, and user correction paths.
+
+## Layout Defaults
+
+Mobile:
+
+- Prioritize bottom navigation, thumb-friendly creation entry, feed/detail transitions, and safe-area handling.
+- Use cards/lists for feeds; keep metadata compact and actions reachable.
+- Prefer sheets/floating panels for comments, sharing, reporting, and quick settings.
+- Avoid deep nested forms in primary consumer flows.
+
+Web:
+
+- Use a strong center content column for feed/detail.
+- Use side panels for topic navigation, creator/AI tools, trending content, notifications, or profile context.
+- Keep dense tables out of consumer discovery pages; use them only in moderation, analytics, or admin-like creator tools.
+- At narrower desktop widths, collapse secondary panels before compressing content text.
+
+## State Checklist
+
+This is the community/social scenario state extension. The canonical generic taxonomy lives in `product-surface-patterns.md`; add these community states when the target product uses feed, creator, social, topic, notification, or moderation loops:
+
+- Empty: first visit, no followed topics, no comments, no notifications, no search result.
+- Loading: initial load, pagination, refresh, media upload, AI generation, background sync.
+- Partial: content exists but media failed, comment failed, AI answer incomplete, permissions partly available.
+- Error: network failure, upload failed, publish failed, moderation rejection, permission denied.
+- Success: published, followed, joined, commented, shared, saved, reported.
+- Reversal: unlike, unfollow, leave, undo delete where supported, cancel upload, discard draft.
+- Trust: blocked user, muted topic, reported content, hidden content, sensitive warning, under review.
+
+## Visual Tone
+
+- Consumer-facing screens should feel approachable and active, not like an internal operations console.
+- Use compact structure where it helps repeated use, but preserve breathing room around feed content and creation controls.
+- Empty states should invite the next useful action, not merely explain absence.
+- AI entry points should be visible and useful, but should not crowd out human community interaction.
+
+## External Benchmark Questions
+
+Use external community benchmarks as product-design questions, not as features to copy:
+
+- Contribution loop: what first action does this screen enable: react, reply, follow, join, save, share, remix, create, or continue with AI?
+- Feed agency: can users influence recommendations through follow/topic tuning, hide, mute, report, less-like-this, more-like-this, latest/hot/following filters, or "why am I seeing this" cues without leaving the feed?
+- AI co-creation: does AI output create a next action such as continue, remix, ask follow-up, compare, regenerate, cite/source, edit, publish, save, share, or report?
+- Trust and safety: are report, hide, mute/block, sensitive-content handling, moderation notice, under-review, rejected/limited, appeal, and correction states visible where needed?
+- Notifications: are replies/mentions, reactions, topic/community activity, system/moderation notices, AI task progress, and digest summaries separated by urgency?
+- Onboarding: does first use move users to one meaningful action before asking for broad setup?
+
+## Community Surface Playbooks
+
+Home/feed:
+
+- Include feed mode switch, inline quality controls, participation actions beside content, freshness state, pagination/end state, stale/offline state, and trust labels when needed.
+- Avoid passive consumption-only openings, invisible ranking when trust depends on it, and too many modes before users understand the surface.
+
+Post/thread detail:
+
+- Include author/context/content/media hierarchy, AI/source labels where relevant, comment/reply states, continuation paths, and moderation controls near the object.
+- Avoid hiding trust controls behind ambiguous overflow icons.
+
+Creation/publishing:
+
+- Include draft, preview, audience/visibility, topic/tag selection, AI assistance, media upload, validation, publish, and post-publish feedback.
+- Preview public/private visibility before publish when audience can vary.
+- Keep AI-assisted output editable and reviewable before public posting.
+
+Onboarding/first use:
+
+- Ask for only the minimum preferences needed to improve the first useful feed.
+- Use contextual guidance inside feed/detail/creation instead of a long tutorial.
+
+Notifications/activity:
+
+- Separate social, system, moderation, and AI-task notifications.
+- Give each notification a destination and next action.
+
+Moderation/trust tools:
+
+- Consumer controls need report, hide, mute, block, sensitive reveal, and reason selection.
+- Moderator controls need queue, filters, assignment, decision, notes, audit trail, bulk actions, and appeals.
+
+## External Benchmark Sources
+
+Use these as provenance for community-specific judgment, not as feature lists to copy:
+
+- UX Magazine, `Seven UX Best Practices of Community Design` (`https://uxmag.com/articles/seven-ux-best-practices-of-community-design`): contribution, trust, and long-term member connection.
+- Bluesky design analysis, `Designing Algorithmic Transparency` (`https://blakecrosley.com/guides/design/bluesky`): visible and user-controllable feed algorithms.
+- Character.AI social-feed coverage (`https://www.tomsguide.com/ai/character-ai-just-launched-an-ai-powered-social-feed-and-its-like-tiktok-meets-chatgpt`): AI-generated artifacts as remixable, continuable, shareable units.
+- Higher Logic Vanilla (`https://www.higherlogic.com/vanilla-engagement-features/`) and Circle (`https://circle.so/customization/`) feature materials: onboarding, notification, reputation, moderation, access, and customization systems.
+- Activity Feed Pattern (`https://uxpatterns.dev/patterns/social/activity-feed`): real-time/pagination behavior, engagement tracking, rate limits, authorization, moderation, and audit trails.
+- Discord community onboarding material (`https://docs.discord.com/developers/game-development/how-to-create-a-community-for-your-game`): controlled first exposure, clear spaces, and harm prevention.
+- Social.plus community-in-app guide (`https://www.social.plus/answers/guide-to-building-an-online-community-in-your-app`): feeds, posts, comments, reactions, groups, notifications, identity, permissions, moderation, and analytics as product infrastructure.

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

@@ -0,0 +1,130 @@
+# Figma Source Map
+
+Internal source-classification rules and provenance pointer for the organization product UI/UX skill. This file records *how* to classify, refresh, and judge design sources; it does NOT record the specific files, keys, paths, or branches that were inspected. Specific provenance lives outside the skill tree.
+
+Users of this skill never need access to the original Figma files, file keys, or source code paths. Treat any "no source access" situation as normal; rely on the distilled rules in `SKILL.md` and focused references instead.
+
+## Provenance Pointer
+
+Specific Figma file keys, project URLs, real subproject paths, real branches, real node ids, and dated re-extraction logs are kept in a private archive outside this skill tree. When auditing or re-extracting, the maintainer loads the archive locally; normal users do not.
+
+If this skill is distributed outside the controlling organization, the private archive does not travel with it, and this file alone remains usable. External distributions must verify that no project URL, file key, real subproject path, real branch, or domain-specific name has leaked into any reference file.
+
+## Conflict And Duplicate Policy
+
+When two sources disagree or overlap, decide explicitly:
+
+- **Keep** the most current, complete, reusable pattern.
+- **Merge** compatible variants into a generalized rule.
+- **Discard** stale, duplicated, lower-quality, or overly domain-specific details.
+- Never let one source file define the product domain. Source identity is provenance, not the product model.
+
+Apply the same rule to code, external benchmarks, and review feedback: use them for reusable UI/UX behavior, implementation quality, launch gates, and iteration signals only; never to infer the product's business domain.
+
+Backend service code evidence is out of scope for this skill except where it affects product-visible lifecycle: generated API freshness, async task status, artifact readiness, permission/empty/error states, and launch observability. Detailed backend service rules belong in the relevant backend skill.
+
+## Source Class Capability Map
+
+For each design source available to the maintainer, classify before extraction along five dimensions. The map below is the *shape* of classification; concrete file entries live in the private provenance archive.
+
+| Dimension | Allowed values | Purpose |
+| --- | --- | --- |
+| `label` | sanitized capability label (e.g. `<design-system-web>`, `<review-module>`, `<scan-module>`) | Reusable identifier in skill text; never use a real file name |
+| `class` | `A1` rules-as-source (design system / UI kit / icon / annotation spec) / `A2` business-module / `B` reference-or-deprecated | Determines extraction weight: A1 anchors tokens/components, A2 anchors flows/states, B is provenance-only |
+| `stack` | `desktop-web` / `mobile-h5` / `mobile-native` / `mini-app` / `mixed-host` | Determines which implementation skill cross-checks the source |
+| `surface` | `shell` / `auth-and-account` / `workbench` / `creation-and-import` / `review-and-evaluation` / `analytics-and-report` / `asset-management` / `roster-and-entity-management` / `device-and-capture` / `notification-and-recovery` | Determines which pattern reference owns the rules |
+| `freshness` | `current` / `candidate-needs-inspection` / `deprecated` / `archived` | Determines whether the source can drive hard rules |
+| `coverage` | `published-system` / `targeted-workflow` / `representative-cross-check` / `metadata-only` / `screenshot-fallback` / `unavailable` | Determines how strong the evidence is |
+
+A new source extraction must declare all six dimensions before producing rules. A source with `freshness: deprecated` or `class: B` cannot create a hard rule alone; it can only confirm a pattern present in stronger sources.
+
+## Re-Extraction Protocol
+
+For any new extraction, broad refresh, or conflict-heavy update, run `skill-extraction-workflow` first.
+
+Collection strategy default: **local-plus-external**.
+
+- Local sources are authoritative for source status: current Figma files, prior source-classification decisions, local frontend implementation evidence, and the active target product context.
+- External sources are challenge/quality inputs only: usability, accessibility, performance, community-product benchmarks, and public skill-engineering practices. They do not define the product domain or visual language.
+- If Figma or code access is unavailable, do not fabricate coverage. Apply the distilled references directly and mark source verification as unavailable.
+- If a Figma file's name carries a team-specific deprecation prefix or suffix (the team's known deprecation markers are kept in the private archive; common categories include a brand-bracketed prefix used to flag legacy snapshots, an automatic `(Copy)` suffix from Figma duplication, or an explicit "deprecated" page name in the team's working language), classify the file `freshness: deprecated` before any read. Such files cannot drive hard rules.
+- If a Figma frame carries inline version or date stamps (e.g. a version suffix `_verN`, a "current/latest" marker in the team's language, an `MMDDnew` date stamp, or a designer-added disambiguation parenthetical), treat the source as in-flight and prefer the latest stamp. Older sibling frames remain as discardable provenance.
+
+Coverage discipline:
+
+- "Full coverage" means every relevant source class has been used, routed, discarded, or marked unavailable with a reason — not "everything inspected".
+- "Targeted" passes are explicit about which surfaces and which frames were read. Do not promote a targeted pass to a full audit in language alone.
+- For large Figma files, use page-level inventory first, then targeted frame/node reads, then screenshot fallback. Failed reads are recorded with the smaller read attempted; "unavailable" requires a remediation attempt first.
+
+## Naming And Scope Decision Record
+
+A product UI/UX skill must be product-agnostic. If the skill name or default scope leaks one business domain or surface category, rename and demote the leaked context to a scenario lens (e.g. `scenario-community-patterns.md`) rather than letting it drive defaults.
+
+Routing boundary:
+
+- Implementation rules belong to `web-react-dev`, `app-cross-platform-dev`, and `miniapp-product-dev` for mini-program implementation.
+- Test-layer rules belong to `testing-strategy`.
+- This skill owns UI/UX judgment, state completeness, visual acceptance, design readiness, and scenario-specific design lenses.
+
+## Coverage Audit Frame
+
+When the maintainer claims coverage, the audit table records the shape, not the content:
+
+| Dimension | What it answers |
+| --- | --- |
+| Current product Figma files | Were the current `freshness: current` design files inspected, or only by file key? Direct team/project enumeration may or may not be possible. State clearly. |
+| Design systems | Were published desktop and mobile design-system files inspected? Were any reference-only UI kits or icon libraries promoted to rules? They should not be. |
+| Code evidence | Was implementation code cross-checked per stack class? Code is implementation evidence only, not product-domain or visual source. |
+| Backend code evidence | Was any backend module referenced? Only product-visible lifecycle consequences belong here; detailed backend belongs in backend skills. |
+| External quality benchmarks | Was at least one usability/accessibility/performance/iteration-metric source named? |
+| Public skill practice | Were public skill examples used as engineering method only, not as persona or domain donors? |
+
+Each row must be fillable as "inspected / not inspected / not applicable" with one short rationale.
+
+## Thin-Evidence Handling
+
+- Weak/reference-only files may confirm a pattern already present in stronger sources, but they cannot create a hard rule alone.
+- Image-only, archived, copied, deprecated, or `todo`-marked evidence must be labeled weak unless a stronger source confirms it.
+- When a future file is named with a "supplement" or "exploration" prefix (in the team's working language), inspect before use; do not exclude or promote by name alone.
+- Record corrections as a compact entry: scene, wrong prior rule, corrected generalized rule, decision, target reference, and source status. Keep this entry in the private archive, not in this file.
+
+## External Quality Sources
+
+Use these as named quality benchmarks only, not as visual or product-domain sources:
+
+- Nielsen Norman Group usability heuristics: heuristic review layer for status visibility, user control, consistency, error prevention, and recovery.
+- W3C WCAG 2.2: accessibility baseline for labels, keyboard, focus, contrast, target size, error identification, and consistent behavior.
+- web.dev Core Web Vitals: launch/performance benchmark for LCP, CLS, INP, and field/lab measurement.
+- Google HEART framework: iteration metric lens for happiness, engagement, adoption, retention, and task success.
+- Material Design / Atlassian Design System guidance: platform/design-system support for touch targets, progressive disclosure, empty states, errors, and feedback clarity.
+
+Extracted patterns live in `external-ui-ux-quality-benchmarks.md`.
+
+## Candidate Formal Sources Policy
+
+Some files cannot be excluded by name alone — for example, files marked as supplement or exploration in the team's working language, or any file appearing in the project that lacks an explicit current/deprecated marker. Treat them as candidates: inspect their pages, compare against current files, and only then promote, weak-keep, or discard.
+
+A candidate that survives inspection joins the current class only with explicit reason; otherwise it is `freshness: candidate-needs-inspection` and cannot drive hard rules.
+
+## Default Exclusion Set
+
+By naming convention, exclude or downgrade:
+
+- Any file whose name uses a team-specific deprecation marker (the active marker list is kept in the private archive — common categories include Figma's automatic `(Copy)` suffix, explicit deprecation page names in the team's working language, and team-specific brand prefixes used to mark legacy snapshots).
+- Slides/report documents (e.g. project-visual-summary slides). These are reference, not source.
+- Broad library placeholders (e.g. someone's team library / sandbox) that do not represent a published design system.
+- Any file with clear old / deprecated / archive labels in name or page.
+- Code-side equivalents: page or component folders with `V<N>` suffix that coexist with the unsuffixed version. Treat the suffixed one as in-flight; verify which the runtime entry imports before extracting rules from either.
+
+## Where The Specific Provenance Lives
+
+This file deliberately does not list current/strong/candidate/discarded file names. That list, with file keys, modification dates, real subproject paths, real branches, and dated re-extraction logs, lives in the maintainer's private archive (one path-private YAML per product). The archive is not published with this skill.
+
+When a future maintainer needs to refresh provenance, they:
+
+1. Load the private archive locally.
+2. Re-read the listed Figma files and code paths against the current source.
+3. Update the archive with the new dated entry.
+4. Update this file *only* if the classification rules, dimensions, or policy themselves change.
+
+The skill content remains usable even when the archive is absent.

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

@@ -0,0 +1,47 @@
+# Tokens And Components
+
+Use this file as a router for shared token/component decisions. Load the detailed design-system references only when the task needs concrete token names, component states, or platform-specific component behavior.
+
+## Desktop Design System
+
+The team's current desktop design system is a `class: A1` published source. It may be team-authored from scratch, abstracted out of a product framework file, or aligned to (or mirrored from) a third-party component library's spec. Read `platform-web-desktop-patterns.md` for desktop tokens, variable modes, component groups, and practical component-state extraction. Treat desktop pages or components marked as `todo` in the source as weak references only. Use `design-system-source-of-truth.md` to identify which file is the actual source when multiple desktop "design system" candidates exist.
+
+## Mobile Design System
+
+The team's current mobile design system is a `class: A1` published source for the mobile end. It may be team-authored, abstracted out of a mobile product framework file, or aligned to a third-party mobile component library. Read `platform-mobile-patterns.md` for mobile tokens, component groups, theming, and mobile state coverage. Use `design-system-source-of-truth.md` to identify the actual source when multiple candidates exist.
+
+## Usage Rules
+
+- Use published design-system files for tokens, component names, variants, and theme behavior.
+- Use product UI files for page composition, state coverage, and interaction-pattern evidence; do not inherit their old domain requirements.
+- Use third-party UI kits and icon libraries only as reference-only coverage checks for component categories, state variants, icon discipline, and documentation quality. Do not copy their brand, marketing IA, or visual identity into the product skill.
+- Do not hardcode colors, spacing, radii, or typography when a design-system token exists.
+- **Color tokens 优先 HSL 而非 Hex / RGB**（hand-tuning same-hue 变体）：HSL 让"同色不同亮度"（hover、disabled、bg tint、border-on-bg shade）通过只改 L 直接派生；Hex / RGB 改 1 个亮度需要算 3 通道易调不准。toolchain 支持时**优先 OKLCH / LCH** 做感知一致的 color ramp（HSL 在跨 hue 时亮度不感知统一）。Token 源用 HSL/OKLCH 表达 intent；输出层（CSS / iOS / Android）按需 convert；设计工具如 Figma 可能存 RGB，token spec 保留 HSL/OKLCH 语义即可。
+
+## Token Sync Pipeline (Figma → Front End)
+
+Design tokens have a **design-tool source of truth**, typically a Figma file with a curated token set (color, spacing, radii, typography, shadow, motion). Tokens reach the front end through a project-specific sync mechanism, not through manual front-end authoring.
+
+- The Figma token set is the canonical source. Front-end token files (CSS variables, framework theme entry, `tokens.ts`, generated SCSS / LESS variables, etc.) are downstream artifacts of the sync.
+- The sync mechanism varies by project: Style Dictionary build pipeline, Tokens Studio plugin export, a Figma-API-driven script, the component suite's theme entry that mirrors the Figma token set, or a Feishu/Lark-hosted spec doc that a script consumes. Architecture records which mechanism this project uses and where the sync script / config lives so future agents do not invent a parallel path.
+- Front-end consumers (component code, page styles) reference the synced tokens by name; they do not declare raw color literals, spacing literals, or font-size literals in component code. Hard-coded literals across components are a sync-pipeline finding, not a per-component fix.
+- Adding a token: define it in Figma first, then run the sync, then reference it in code. Adding a token only on the front end (without the Figma source) is design drift that compounds across apps.
+- Renaming or removing a token: same direction — update Figma, sync, propagate. The sync output should fail the build (or at least produce a reviewable diff) when token names change, so consumers notice.
+- Introducing a second theme (dark mode, multi-tenant brand) becomes a token-set switch in the Figma source plus a sync re-run, not a code rewrite, when this pipeline is in place.
+- **Design Tokens Format Module reached first stable version 2025.10 (published 28 October 2025 by the W3C Design Tokens Community Group)** — adopt the `$value` + `$type` JSON schema as the *interchange format* between design tools (Tokens Studio, Style Dictionary, Supernova, Figma Variables exporters) and platform code generators. Two scope caveats: (1) Community Group reports are NOT W3C Standards and not on the W3C Standards Track — DTCG is industry-converged interchange, not normative spec, so do not cite it as a compliance gate; (2) DTCG is NOT a source-of-truth replacement — source authority still lives in the design tool's connected token panel (Figma Variables / equivalent), per the team's existing "token source = design tool, not JSON export" rule. What DTCG actually buys: a token rename in the source produces a predictable downstream diff, `$type` can be set at the group level so individual tokens inherit it (per-token `$type` override is also valid and necessary in mixed-type groups — inheritance is a default, not a constraint), composite token `$value` is a structured object / array for shadow / gradient / typography / transition (not a scalar) so legacy exporters that flatten composite values will break on the migration and must be updated alongside it, and cross-tool migrations stop reinventing per-vendor JSON shapes. When picking up a project that already has a non-DTCG token JSON (e.g. legacy Style Dictionary v3 layout, raw `{"color":{"primary":"#xxx"}}` blob), schedule the migration to DTCG `$value`/`$type` alongside the next token-set restructure rather than as a separate refactor, and audit exporter/generator support for composite types as part of the migration gate.
+- Treat component coverage as a capability map, not a visual shortcut. A component is usable only when its states, placement role, density, accessibility, and failure behavior match the product surface.
+- For web, prefer mature component semantics and adapt density to the community surface: lighter for feed/profile/content consumption, denser for creator tools, moderation, settings, and AI workspaces.
+- For mobile, prefer mobile-specific components such as NavBar, TabBar, CapsuleTabs, FloatingPanel, SearchBar, SafeArea, and mobile List/Card patterns.
+- For community UI, make interaction states complete: liked/followed/joined, commenting/replying, creating/submitting, loading, empty, error, muted/blocked/reported, AI-generating, and permission-gated states. For finance/data or operational UI, make scope, permission, evidence, pending/final, export, support, and recovery states complete.
+
+## Cross-Platform Component Capability Map
+
+- Shell and navigation: desktop `Layout`, `Menu`, `Breadcrumb`, `Dropdown`, `Pagination`, `Steps`, `Splitter`; mobile `NavBar`, `TabBar`, `Tabs`, `CapsuleTabs`, `SideBar`, `IndexBar`. Use them to preserve route context, selected state, overflow, long labels, and return paths.
+- Input and creation: desktop `Form`, `Input`, `Select`, `Upload`, `DatePicker`, `Transfer`, `TreeSelect`; mobile `Form`, `Input`, `TextArea`, `Picker`, `Selector`, `ImageUploader`, `NumberKeyboard`, `PasscodeInput`. Cover focus, validation, disabled reason, keyboard/safe-area, upload progress, and preview-before-commit.
+- Content display: desktop `Card`, `List`, `Avatar`, `Image`, `Tag`, `Badge`, `Tooltip`, `Popover`, `Statistic`, `Tree`; mobile `Card`, `List`, `Avatar`, `Image`, `ImageViewer`, `Tag`, `Ellipsis`, `FloatingPanel`, `InfiniteScroll`. Cover long content, media failure, skeleton, empty, selected/hover/pressed, and secondary actions.
+- Feedback and recovery: desktop `Alert`, `Message`, `Notification`, `Modal`, `Drawer`, `Popconfirm`, `Progress`, `Result`, `Skeleton`; mobile `Toast`, `Dialog`, `Modal/Bottom sheet`, `Popup`, `ActionSheet`, `NoticeBar`, `ProgressBar`, `ProgressCircle`, `ErrorBlock`, `ResultPage`. Match feedback strength to risk: toast for lightweight status, inline alert for scoped context, modal/dialog for decisions, result page for terminal state.
+- Trust and high-impact states: use `Alert`/`NoticeBar`, `Tag`/`Badge`, `Popover`/`Drawer`, `Modal`/`Dialog`, and progress/result components to expose source, permission, pending/final state, retry safety, and support/recovery context.
+- Charts, metrics, and progress: use chart axes, legends, markers, metric cards, and progress steps only when they explain comparison, trend, distribution, current stage, or next action. Every chart needs empty/loading/partial/stale states plus a route to detail, drill-down, or exact rows when the decision depends on the data.
+- Flow and annotation: use step indicators, labels, pointers, measures, hot zones, cursor/gesture hints, and inline annotations to clarify complex interactions during design, review, onboarding, or UAT. Remove them from the final product surface unless they serve an actual user state, tooltip, or guidance role.
+- Icon discipline: icon-only controls need consistent stroke/fill weight, hit area, selected/disabled/loading/error states, accessible labels, and tooltip/sheet titles for unfamiliar actions. Do not use arbitrary icons when text, a menu label, or a safer confirmation is needed.
+- Common mobile icon set observed in source coverage: add, camera, chat, check, close, delete, edit, eye, file, filter, flag, global, heart, like, link, location, lock, mail, message, more, picture, search, send, setting, star, tag, team, warning, and error. Map icons semantically instead of decoratively.