@ccoalm/ccl-skills 0.1.0

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

@@ -0,0 +1,214 @@
+# Design Execution Checklist
+
+Use this checklist when applying the skill to a concrete product screen, feature, implementation, or review.
+
+## 0. Resolve Target Context
+
+Before loading detailed references, translate the active task into the target product frame:
+
+- Classify the target as community/social, education, finance/data, AI workspace, operational tool, consumer content, mobile app, web workbench, settings/account, or shared system.
+- Translate source-domain terms into target-product interaction patterns; do not output source-domain UI copy or source-domain information architecture.
+- Exclude source-domain terminology, role models, and workflow structure from product-facing output.
+- If the task context is mixed, state which product assumption is being used before design or implementation.
+
+## 1. Classify The Task
+
+Identify the target surface:
+
+- Mobile consumer surface: feed/detail, creation, profile, onboarding, notifications, AI assistant, settings, or finance/data mobile task flow.
+- Web consumer surface: content/detail/community, creator center, AI workspace, finance/data research surface, settings, notifications.
+- Web operational surface: moderation, trust/safety, analytics, data/research workbench, creator tools, admin-like settings.
+- Shared system work: tokens, components, theming, interaction states, visual QA.
+
+Then load only the relevant references:
+
+Core layer:
+
+- Always: `product-surface-patterns.md`.
+- Broad design, implementation, or review work: `design-intake-and-acceptance.md`.
+- Interaction logic, attention, motivation, perceived effort, trust psychology, habit loops, or aesthetic judgment: `behavioral-aesthetic-logic.md`.
+- UI/UX audit, implementation review, code/design comparison, usability risk, accessibility, or responsive QA: `ui-ux-audit.md`.
+- UI/UX design and frontend implementation: `ui-ux-design-development.md`.
+- Product launch acceptance, lifecycle review, and iteration planning: `product-lifecycle-acceptance-and-iteration.md`.
+- Frontend visual polish, brand feel, or anti-slop review: `visual-craft.md`.
+- Layout recipes, component density, empty/loading/error templates, workbench structure, or screenshot acceptance: `layout-recipes-and-screenshot-acceptance.md`.
+- Interaction flow, feedback strength, gestures, AI generated states, or serious/trust-sensitive states: `interaction-design-patterns.md`.
+- Shared token/component capability map: `tokens-and-components.md`.
+
+Platform lenses:
+
+- Mobile/App/H5/WebView: `platform-mobile-patterns.md`.
+- Web/Desktop/workbench/auth/admin: `platform-web-desktop-patterns.md`.
+
+Scenario lenses:
+
+- Community/social/feed/creator/moderation: `scenario-community-patterns.md`.
+- External usability, accessibility, performance, or metrics benchmark: `external-ui-ux-quality-benchmarks.md`.
+- Trust-sensitive AI/data, citation, upload, permission, instrumentation, or dense operational patterns: `trust-sensitive-ai-and-data-patterns.md`.
+- Local frontend implementation evidence, codebase source classification, reusable primitives, or build/launch scripts: `frontend-code-evidence-map.md`.
+- Complex creation, upload/import, AI draft extraction, structured editing, matching, manual correction, or publish/export flows: `complex-creation-interactions.md`.
+- Analytics, visualization, charts, comparisons, drill-down reports, creator/topic health, retention, or AI quality metrics: `analytics-visualization-interactions.md`.
+- Operational processing workspaces for capture/upload, focused review, moderation queues, quality/progress monitoring, assignment, or ownership workflows: `operational-processing-workflows.md`.
+- Resource libraries, AI cloud-drive style storage, media/template centers, saved prompts, knowledge sources, content packs, sharing, or resource governance: `resource-management-interactions.md`.
+
+Provenance and multi-project lenses:
+
+- Identifying which Figma file is the real design-system source, detecting third-party-mirror design systems, deciding which file owns brand tokens, or auditing theme/code comments pointing at the wrong figma file: `design-system-source-of-truth.md`.
+- **Same-stack multi-subproject** theme consistency (e.g. multiple desktop apps, or multiple H5 apps, sharing one brand), detecting silent default-theme drift across same-stack subprojects, or deciding how to share one theme module: `multi-project-token-consistency.md`. Use this when the subprojects are on the same end (all web-desktop, or all web-h5, etc.).
+- Resolving Figma↔code naming drift, deciding which of `Foo` / `FooV2` is active, planning retirement of in-flight version stamps, or maintaining a design-code terminology glossary: `design-impl-naming-and-versioning.md`.
+- **Cross-stack** strategy when a product spans multiple client stacks (web + H5 + native + mini-app + RN), handling stack outliers (a Vue island in a React organization, a single mini-app surface, etc.), splitting design system by stack, or writing the native-shell ↔ H5 contract: `multi-stack-strategy.md`. Use this when stacks differ across subprojects, not when the subprojects share a stack.
+- **Same-framework cross-end** (e.g. React desktop + React H5 + React Native, sharing one brand and one TS toolchain but different UI-kit per end): a common middle case. Load **both** `multi-project-token-consistency.md` (for the shared theme module across same-framework subprojects) and `multi-stack-strategy.md` (for the per-end UI-kit and surface differences). Do not pick one — apply both.
+
+## 2. Translate Source Patterns
+
+Before designing or coding, state the translation explicitly:
+
+- What source pattern is being reused?
+- What target-product behavior does it become?
+- What source-domain details must be discarded?
+- Which source-domain details must remain provenance-only and excluded from product-facing output?
+
+Examples:
+
+- Source dashboard card -> community feed module, creator task card, or AI suggestion.
+- Source task/progress state -> publish, review, moderation, AI-generation, upload, or sync state.
+- Source answer/analysis region -> post body, comment, AI response, annotation, or explanation panel.
+- Source settings/report view -> creator analytics, moderation tools, trust settings, or account preferences.
+- Source complex creation/import flow -> media creation, AI draft extraction, structured content setup, event/campaign setup, or imported data cleanup.
+- Source chart/report interaction -> creator analytics, topic health, retention, trust/safety monitoring, or AI quality analytics.
+- Source operational-processing workspace -> media ingestion, moderation queue, AI output validation, evidence review, creator approval, or incident processing.
+- Source resource/cloud-drive management -> creator asset library, AI knowledge source management, saved prompt library, topic template library, media pack, or content-pack governance.
+
+## 3. Choose Product Density
+
+Pick one density mode:
+
+- Consumer relaxed: feed, detail, profile, onboarding, creation. Use readable spacing, clear hierarchy, visible reactions, and approachable empty states.
+- Productive compact: creator tools, analytics, moderation, settings, AI workspace. Use denser cards, filters, side panels, tables/lists, and compact controls.
+- Hybrid: discovery page with a secondary creator/AI panel. Keep primary content readable and collapse secondary panels first.
+
+Do not make consumer discovery pages look like internal operations software.
+
+## 3.5 Required Design Checkpoint
+
+Before implementing or approving any visible UI change, write a compact checkpoint that can be tested against the final screen:
+
+- Surface type: mobile consumer, web consumer, web operational, or shared system.
+- Density mode: consumer relaxed, productive compact, or hybrid.
+- Implementation-owner checkpoint (rule text is canonical in `SKILL.md`'s implementation-owner checkpoint section; this checklist lists only the slots to fill — a checkpoint record must cite `checkpoint rules read: product-ui-ux-design/SKILL.md#implementation-owner checkpoint`, and a record without that citation is not valid):
+  - Record before the first implementation edit for a runtime visible UI/UX slice (slice definition and rendered-vs-backend-only routing: see `SKILL.md`): persistent artifact (plan/checklist, MR notes, or evidence file) for branch/MR-bound work; the visible progress update only for a single-turn local edit reverted or discarded before the final response (chat-only exception conditions per `SKILL.md`), and any change that remains at final response, push, or MR time repeats the full checkpoint fields in a persistent artifact.
+  - Include design owner (`product-ui-ux-design`), stack implementation owner, test owner (`testing-strategy`, loaded, with its assertion layer and rendered-evidence choice recorded, not only its name), entry-rule evidence, and rendered/device evidence status.
+  - Stack owner mapping: `app-cross-platform-dev` for Flutter/RN/native mobile, `web-react-dev` for React web, `miniapp-product-dev` for mini-programs, `terminal-cli-dev` for terminal/TUI, the recorded project client-code convention, or `no-installed-owner` with the surface type named — `no-installed-owner` only when no project convention exists and the lookup completed — name the runtime/framework and where conventions were looked for; an incompletable lookup is recorded `unavailable`, never `no-installed-owner`; container-wins, project-convention lookup minimum, shared-token consuming-stack inventory, and `unknown-consumers`/`out-of-scope` handling all per `SKILL.md`'s stack-owner entry rules; an entry list limited to stacks the author happened to name is not an inventory.
+  - Entry-rule evidence: a short quote, or the exact section/rule identifier plus the decision it produced — never only a file path, runtime name, or a vague anchor; runtime copy-only edits record `not-triggered (copy-only, existing component/viewport unchanged)` plus classification evidence that is measured — new text no longer than the old in every shipped locale, by rendered extent rather than byte/character count for width-constrained components (or a named length/viewport check; an unmeasured no-overflow assertion does not qualify; acceptable anchors and copy-only conditions: per `SKILL.md`); project-convention owners quote the convention line/rule applied; `no-installed-owner` records `no owner rule available`; trust/safety/risk-bearing copy never takes the copy-only path — full checkpoint plus risk grading routed to `feature-risk-router` (per `SKILL.md`).
+  - Evidence status: `captured/verified` with an inspected artifact pointer, `planned` with a capture command, or `unavailable-with-owner`/`unavailable-no-owner` with attempt records — status semantics, fabrication bars, persistence/review-resolution rules, completion-claim consequences, and evidence-artifact sanitization (sanitized/test accounts; tokens, PII, credentials, private paths redacted) per `SKILL.md`; a bare `captured/verified` without a pointer is treated as `planned`; any status other than `captured/verified` blocks completion claims — report `pre-runtime-test ready`, `blocked`, or an explicit evidence gap with owner and next command/unblock action.
+  - Remediation: naming an owner without loading its entry rules does not satisfy the checkpoint (the copy-only `not-triggered` path exempts only the stack-owner entry-rule quote, with every other checkpoint field still required); a missed checkpoint discovered by anyone is redone with an audit of the already-made diff per `SKILL.md`'s remediation rule.
+- Primary workflow: the shortest successful path and the main return loop.
+- Human logic: user intent in the next 10 seconds, likely anxiety/friction, attention order, motivation to continue, and trust concern.
+- Aesthetic logic: intended mood, visual focus, density rhythm, contrast role, material treatment, and which details should feel restrained versus expressive.
+- Visual direction: typography source, primary color source, neutral/background scale, radius/shadow role, token source versus new page-specific values, and whether two or three compact visual options were compared or deliberately skipped.
+- Interaction logic: Discover -> Inspect -> Act -> Confirm -> Return, including what is progressively disclosed, what stays persistent, and where the user returns after modal/drawer/upload/generation/detail work.
+- Behavioral logic: duplicate action protection, waiting feedback, disabled reasons, undo/retry/cancel, interruption recovery, and risk-matched confirmation.
+- Psychology: users should know what is happening, what changed, what is safe to wait for or retry, what mistake risk exists, and how to recover without losing context or control.
+- Layout structure: navigation/context, input/control region, content/result region, and secondary metadata.
+- Required states: empty, loading/generating, success, failure/retry, disabled/permission, long-content, and narrow-width behavior where relevant.
+- Trust boundary: generated content, publish/save limits, source/context/cost/model metadata, and any action that must not be implied.
+- Visual acceptance: hierarchy, spacing, component fit, copy tone, no nested-card clutter, no generic dump of fields, and no text overflow.
+- Behavioral/aesthetic acceptance: primary action feels obvious, feedback matches consequence, friction matches risk, mood fits the surface, and the result does not feel like a generic component demo.
+- Recipe: choose one concrete recipe from `layout-recipes-and-screenshot-acceptance.md` before drawing or coding.
+- Adaptation matrix: name the primary viewport, the stress viewport(s), the collapse rule, the spacing/density mode, and the screenshot/device checks that will prove the layout. For mobile, include safe-area and keyboard behavior; for desktop workbenches, include secondary-panel collapse before primary content becomes unreadable.
+
+Run the checkpoint in this order so it changes the result, not just the wording:
+
+1. Aesthetic logic: decide layers, white space, density, alignment, rhythm, color weight, radius/shadow restraint, and visual focus around the primary task.
+2. Visual direction: if the screen is new or substantially reshaped and no strong design reference exists, compare two or three compact directions before coding or final acceptance; if reusing existing product language, state the exact theme/token source and what stays unchanged.
+3. Interaction logic: decide entry point, current task, next step, progressive disclosure, confirmation, return path, and how complex work is split across pages, drawers, sheets, toolbars, or stages.
+4. Behavioral logic: decide what users may repeat, misclick, wait for, abandon, undo, retry, cancel, or recover after interruption, and place visible state/control for each risk.
+5. Psychology: reduce cognitive load and uncertainty, explain disabled or risky actions, keep users feeling in control, and make high-impact actions feel deliberate before execution.
+
+For admin, operations, moderation, analytics, creator-tool, and AI-review workspaces, a component library is only the implementation vocabulary. Do not describe the design as "Ant Design style" or similar without the checkpoint above. A good operational screen should make the next operator action obvious within five seconds. It should not rely on a dark hero, decorative gradient bar, oversized empty illustration, or marketing-page composition; use compact controls, readable hierarchy, clear status, and obvious work regions instead.
+
+## 3.6 Operational Workspace Quality Pattern
+
+For admin, operations, moderation, analytics, creator-tool, and AI-review pages, use this pattern unless a stronger product-specific design exists:
+
+- Header: keep the app shell header factual and restrained. Do not repeat a large inner page title unless it adds task context.
+- Control bar: place scope/filter/mode switches and primary context in a compact horizontal band near the top.
+- Status strip: expose trust boundary, selected scope, permission/state, and mode as small operational facts, not as promotional copy.
+- Workbench: use a clear input/control region and a review/output region. The output region should show the shape of the future review object even before data exists.
+- Dynamic workbench: data-driven module visibility, ordering, and status are valid. The empty or no-permission view should still show the intended module structure, next action, and future data slots.
+- Empty state: prefer a compact placeholder skeleton, checklist, or next-action hint over a large illustration. Empty states should teach what will be reviewed, not fill space.
+- Review state: make generated title, summary, reasons, model/prompt/cost/status, and source/trust metadata scannable without a table dump.
+- Visual tone: quiet contrast, crisp borders, stable spacing, readable labels, no decorative gradients, no oversized cards, no unused first-screen dead area.
+- User psychology: operators need certainty and control more than delight. Show where the work came from, what changed, what is pending, what is safe to retry, and how to recover after interruption.
+- Component hierarchy: navigation, tables, modals, empty states, charts, progress steps, alerts, annotations, and toolbars are chosen for their task role. Do not drop a component onto the page until its state, density, fallback, and return behavior are defined.
+
+## 4. Required States
+
+Use `product-surface-patterns.md` as the canonical state taxonomy. For every feature, map that taxonomy to concrete UI behavior. Add community, finance/data, AI, or operational scenario states only when the target surface needs them.
+
+Do not ship only the happy path.
+
+For visual implementation, use the empty/loading/error/success templates in `layout-recipes-and-screenshot-acceptance.md`. The state must occupy the same layout geometry as the final content unless the whole surface is terminally unavailable.
+
+## 5. Component Defaults
+
+Mobile:
+
+- Navigation: `TabBar`, `NavBar`, `Tabs`, `CapsuleTabs`.
+- Feed/detail: `List`, `Card`, `Avatar`, `Image`, `ImageViewer`, `Tag`, `InfiniteScroll`, `Skeleton`.
+- Creation/AI: `ImageUploader`, `TextArea`, `Input`, `Button`, `ProgressBar`, `Toast`, `Dialog`, `Modal/Bottom sheet`.
+- Comments/actions: `FloatingPanel`, `Popup`, `ActionSheet`, `SwipeAction`.
+- Account/settings: `Form`, `List`, `Switch`, `Picker`, `CheckList`, `Radio`, `PasscodeInput`.
+
+Web/Desktop:
+
+- Feed/detail: `Card`, `List`, `Avatar`, `Image`, `Tag`, `Badge`, `Tooltip`, `Popover`, `Skeleton`, `Empty`.
+- Creator/moderation/settings: `Form`, `Input`, `Select`, `Switch`, `Radio`, `Checkbox`, `Upload`, `Steps`, `Progress`, `Drawer`, `Modal`.
+- Notifications/feedback: `Message`, `Notification`, `Alert`, `Result`.
+- AI workspace: `Layout`, `Splitter`, side panels, upload, progress, streaming/loading, retry, edit, and result states.
+
+## 6. Token Rules
+
+- Use design-system semantic tokens before raw colors.
+- Tokens should express a coherent product visual language, not fall back to generic neutral defaults without a reason.
+- Preserve Light/Dark mode support when the surface supports theming.
+- Use mobile 4/8/12 radius roles for mobile; use desktop 2/4/6/8/12/16 radius roles for web.
+- Use desktop Default mode for consumer web readability; use Compact mode for dense tools.
+- Do not invent one-off spacing, color, radius, or font rules unless the product requirement clearly needs a new token.
+
+## 7. UI Copy Guardrails
+
+**A. Domain / product copy**：
+- Do not copy old source domain words into the new product UI.
+- Use product-appropriate copy. For community products: post, reply, topic, creator, follow, join, publish, draft, review, report, block, mute, notification, AI suggestion, generated draft. For finance/data products: source, evidence, watchlist, portfolio, risk, review, explain, export, permission, data freshness, and decision support.
+- Keep destructive copy explicit: delete, report, block, publish publicly, leave community, discard draft.
+- Empty states should invite the next action, not just say no data.
+
+**B. Microcopy structural rules**（reviewer 可直接 block 不满足的 PR）：
+- **Button labels = verb + specific object**：`Save changes` / `Send message` / `Discard draft`. **Avoid generic labels when action/consequence is not obvious from context**（典型弱例：`Submit` 无对象、`OK`/`Confirm` 遮蔽结果）。在平台 dialog 标准位 `Cancel` / `Close` / `OK` / `Done` 等仍可用。Destructive 必须比中性更显式（参 [[behavioral-aesthetic-logic.md]] + `interaction-design-patterns.md` Serious/Financial 段的 destructive/irreversible/外部可见/付费 trust-sensitive 边界）：`Delete forever` 而非 `Remove`。
+- **Error message 结构**：(1) **what happened**（用户语言，非 stack trace / error code）+ (2) **why — when useful and safe to disclose**（auth/session/policy/anti-abuse/backend 内部不暴露；如 `Session expired. Sign in again.` 不必给原因）+ (3) **what to do**（具体动作：retry / contact support / 修哪个 input）. Anti-pattern：`Something went wrong` / `Error 500` / `Unknown error` 作主 copy（error code 可入 expandable technical details / support reference）。
+- **Disabled control**：默认必有原因（tooltip / inline helper / 旁边一句话）+ 启用条件，让用户知道下一步。**例外**：unavailable by policy / permission / security 且暴露条件不安全 → **隐藏 control** 或给通用 permission 解释（不暴露具体策略）；不存在"恒不可启用"且只剩 disabled 状态的 control（应直接隐藏）。
+- **Success / confirmation 必具体**：说清成功了什么 + 如适用给下一步。`Message sent to alice@example.com — view in Sent` 而非 `Success` / `Done` / `OK`。
+- **Voice consistency**（可枚举的 reviewer 检查项，不空喊）：(a) 无内部代号 / 项目代号 / 服务名出现在用户文案；(b) 同一动作 / 对象不混用术语（如不同页面别一处叫 "send"、一处叫 "submit"、一处叫 "post"）；(c) 无未解释 jargon；(d) 无翻译腔（直译机翻味）；(e) 时态 / 人称 / 大小写统一。
+
+## 8. Review Checklist
+
+Before calling a design or implementation complete, verify:
+
+- The screen supports the primary product loop: discover/enter -> inspect -> act -> confirm -> recover/return.
+- Main action and secondary actions have proper hierarchy.
+- Interaction logic passes `behavioral-aesthetic-logic.md`: the canonical Discover -> Inspect -> Act -> Confirm -> Return loop from `interaction-design-patterns.md` matches user intent, risk, trust, and motivation.
+- Aesthetic logic passes `behavioral-aesthetic-logic.md`: mood, rhythm, contrast, material treatment, and delight support the product purpose.
+- Frontend, test, and acceptance checks use `behavioral-aesthetic-logic.md`: rendered behavior preserves attention order, risk friction, recovery, trust cues, and return context, not only visual component correctness.
+- Long names, long posts, badges, tags, and metadata do not break layout.
+- Mobile keyboard/safe-area states are covered where relevant.
+- Web narrow-width behavior collapses secondary panels before damaging content readability.
+- AI states include generating, retry, edit, source/citation where relevant, and failure handling.
+- Trust/safety states are visible and understandable.
+- Trust-sensitive AI/data features expose source/context, permission state, recovery, and observable request/task outcomes.
+- Visual polish passes `visual-craft.md` anti-slop and brand-consistency checks.
+- Screenshot acceptance passes `layout-recipes-and-screenshot-acceptance.md` with realistic long text, no data, partial data, and error data.
+- The adaptation matrix was checked in the rendered implementation: primary viewport, stress viewport, collapse behavior, safe-area/keyboard where relevant, long text, empty/partial/error state, and no layout shift around loading or dynamic modules.
+- For operational/admin/AI-review workspaces, the rendered screen looks like a focused work surface, not a landing page: no hero-style banner, no decorative gradient-as-design, no oversized empty illustration, no large unused first-screen area, and no layout where the real task starts below unrelated dashboard content.
+- Component choices follow this skill and existing codebase primitives.
+- Launch readiness and iteration risks pass `product-lifecycle-acceptance-and-iteration.md` when the work is close to release or already shipped.

package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/design-impl-naming-and-versioning.md

@@ -0,0 +1,53 @@
+# Design-Implementation Naming And Versioning
+
+Load this reference when a task crosses the Figma↔code boundary and depends on **finding the matching pair** — e.g. "which code module implements this Figma frame?" or "is this V2 component the active one?". It defines how to detect naming drift between design and code, and how to detect in-flight version stacks that look stable but aren't.
+
+## Triggers
+
+- A task asks "find the implementation of <Figma surface>" and the obvious `grep` returns nothing.
+- A code tree contains both `Foo` and `FooV2` (or `Foo` and `Foo.v2.tsx`, etc.) and you must decide which is active.
+- A Figma frame name carries a date stamp / version suffix / "use this one" parenthetical.
+- A design-system refresh ships and the implementer can't tell which code locations still reference the old version.
+
+## Rules
+
+- **Name a glossary, do not improvise the translation**: when the team uses one set of terms in Figma (often in the working language, e.g. Chinese: review/scan/exam/etc.) and a different set in code (often English equivalents, sometimes translated freely as `Correct` / `Process` / `Inspect`), maintain an explicit bidirectional glossary in the private provenance archive. Future agents that try to grep without the glossary will silently miss matches.
+- **Glossary is part of onboarding**, not a per-task artifact: a new contributor or agent learning the project must encounter the glossary as part of the source-classification step. Hidden glossaries fail in proportion to how busy the project is.
+- **In-flight versioning is a smell, not a feature**: a code module named `FooV2` that coexists with the unsuffixed `Foo`, a Figma frame stamp such as a current-marker suffix / version-N suffix / date-stamp suffix / designer-added disambiguation parenthetical, and a folder name like `module.new` are all evidence that the team is mid-migration. None of them is wrong, but a *long-lived* coexistence is anti-pattern: it forces every reader to do extra work to find the active version.
+- **The active version must be discoverable from the runtime entry**: do not rely on intuition. To decide which of `Foo` / `FooV2` is active, follow the route table / router config / app entry import — whichever the runtime actually mounts. The unmounted sibling is dead weight even if it has more recent commits.
+- **Old versions should be retired on a date, not on vibes**: when introducing `FooV2`, write down the date or release that retires `Foo`. Same in Figma: when promoting `_ver1`, tag the old frame as deprecated rather than leaving siblings competing.
+- **Date stamps in design file names do not propagate to code**: never name a code module `Foo_0904.tsx` because the corresponding Figma page carries a date stamp. Translate the design version stamp into a clean code name plus a top-of-file comment that records the design-source revision.
+- **Verify business-axis frame labels by structural diff before treating the label as a product axis**: when paired figma frames carry business-axis vocabulary in the form "X / non-X" (tenant tier / customer segment / plan tier / region / vertical / industry / org type), structurally diff the two frames before code, tests, backend enums, or analytics dimensions branch on the named axis. **Diff unit** (specify it so two reviewers reach the same verdict): node path + node id + component/variant props + text content + bounds + layer visibility + interactive/prototype links. A changed component INSTANCE with changed variant props or overridden internal children counts as multiple deltas, not a single-element presence delta. **Procedure**: read both frames at matching depth, enumerate every node at the diff unit, list every delta. **If the only delta is presence/absence of a single permission-gated or state-driven element** (one quick-action cluster, one CTA button, one config row): UI evidence alone proves a permission/state-rendering delta — it does **NOT** alone prove the business axis is fake. The named axis may still be a real product/analytics/backend dimension that happens to surface through entitlement gating (plan tiers and regions often manifest exactly this way: one entitlement-controlled action toggles, with the axis itself living in product schema/PM intent). Confirm whether the gating permission is **derived from** an independent business axis (PM/PRD, product enum, backend schema, entitlement matrix) before deciding. Two outcomes: (i) gating is **not** derived from any business axis → label is misleading, the real axis is permission/state, raise rename to designer; (ii) gating **is** derived from the named axis → label is accurate, the axis is real even though UI manifests as one gated control, code/enums/analytics should keep the named axis (with the permission as its rendering mechanism). **Design-side judgment** (this skill's lane): record in the private glossary with source file, frame node ids, revision/version marker, observed delta summary, resolved axis (misleading / entitlement-derived from <axis>), and the entitlement-source evidence (PM/PRD doc, product enum file, etc.); the entry is **not a permanent cache** — re-diff when either frame changes revision or when a current-marker/version stamp appears. When outcome (i) holds, raise the label as a hygiene defect for designer rename (e.g. "with-<permission-name>" / "without-<permission-name>", "in-<state>" / "out-of-<state>"). **Routing for enforcement**: code gating → `web-react-dev` / `app-cross-platform-dev` / `miniapp-product-dev`; test coverage → `testing-strategy`; backend enum and analytics dimension changes → owning backend / data skill or human owner. This file's role ends at recording the judgment and routing. **If the diff returns a multi-element substantive delta** (multiple node-path differences, distinct INSTANCE trees with different variant props, different navigation patterns), the named axis is a **candidate** real axis — confirm against product / runtime / source-of-truth evidence (PM/PRD, route table, backend enum, data dictionary) before introducing axis-aware code, tests, enums, or analytics; multi-element delta alone is insufficient because it can still be state, permission combo, experiment, locale, or responsive variant.
+- **Designer-side dating is acceptable but needs a current-discriminator**: Figma lacks a git-like branch/version-history mechanism, so designers commonly suffix the active page with a date stamp (e.g. a `_YYYY.MM/DD` or `_MMDD` suffix) and keep older dated pages in the same file as informal version history. This is acceptable, *provided* one page is unambiguously identifiable as the current source — any of: only one page in the file carries the latest date stamp and no other page carries a later one; a `(current)` / "use this one" / `(active)` annotation on the current page; or older dated pages renamed to start with `archive/`. Without such a discriminator, a file with two or more dated pages becomes a graveyard where the maintainer cannot tell which is the source of truth. **Conflict precedence when signals contradict**: when two discriminators point at different pages — for example, an older page is annotated `(current)` but a newer dated page exists without annotation, or a page carries both a `(current)` label and an `archive/` prefix — none of the automatic signals can be trusted. Treat the file as `freshness: candidate-needs-inspection`, hold rule extraction, and confirm with the file's designer/owner which page is the live source before proceeding. Do not pick a "winning" discriminator silently. The code-side rule above (date stamps do not propagate into module names) still holds independently.
+
+## Decision Checklist
+
+When you hit a Figma↔code naming mystery:
+
+1. Open the private glossary (or ask the maintainer to create one if it doesn't exist). Translate the Figma label into all known code-side equivalents.
+2. Re-grep using each equivalent. If still no match, the implementation may not exist yet (`not-observed` per maturity gate) — flag it as a gap, do not invent a mapping.
+3. If you find `Foo` and `FooV2`: read the router/app-entry first, see which one mounts. Treat the other as legacy; do not edit the legacy version unless explicitly cleaning up.
+4. If a Figma frame has version/date stamps: read the page's other frames to see if a "current/latest" sibling exists (a sibling stamped as the chosen version or as "use this one" in the team's working language). If yes, the un-stamped sibling is stale.
+5. After resolving the mapping, add it to the glossary (one line: design label → code module → status). Future agents skip the search.
+6. If two figma frames carry business-axis "X / non-X" labels (tier / segment / region / industry / org type): structurally diff at the diff-unit granularity (node path + id + component/variant props + text + bounds + visibility + prototype links). Single-element permission/state delta → run the entitlement-source check (PM/PRD, product enum, entitlement matrix). Gating not derived from any business axis → label is misleading, raise rename, route enforcement to implementation owner. Gating derived from the named axis → axis is real, route axis-aware code/enums/analytics changes to implementation owner. Multi-element substantive delta → candidate real axis; confirm against product / runtime / source-of-truth evidence before introducing axis-aware code, tests, enums, or analytics; do not treat the figma delta alone as authorization. Glossary entry records source file, node ids, revision, resolved axis, and entitlement evidence; re-diff when frame revisions change.
+
+## Anti-Patterns
+
+- **Coexistence beyond one release**: `Foo` and `FooV2` both in `pages/`, both reachable, neither documented as legacy. Every reader pays the cost.
+- **Naming the active version by date stamp**: a Figma frame with a `MMDD` stamp and a code module copying that stamp into the filename. The stamp ages; the relationship becomes meaningless in a month.
+- **Translating without a glossary**: agent A grep's "review", agent B grep's "Correct", agent C grep's "mark". All three miss the actual code, which uses `Exam`.
+- **"use this one" siblings**: a frame the designer has stamped as the chosen version only signals that the wrong siblings have not been deleted yet. Do not assume the un-stamped frames are also current.
+- **V1/V2 dual-track on both sides with no retire plan**: when one product surface has V1 + V2 routes in code (e.g. `pages/Foo/` plus `pages/FooV2/`), V1 + V2 components on the mobile side (e.g. legacy `pages/Foo/` directly + new `pages/FooV2/*/page.tsx` re-exporting from `features/foo/`), AND multiple dated pages in the design source (e.g. `<surface>-<date1>` + `<surface>-<date2>` + `<surface>-backup`), the team is in indefinite migration. Cost compounds: type duplication, route ambiguity, dead code in tests, contradictory designer guidance to engineers. The retire-date discipline is necessary but not sufficient: a recorded date alone, without a migration checklist, creates deletion pressure that ships its own incident class — saved deep links 404, exports/QA fixtures/analytics events/persisted user state reference V1 paths after V1 is deleted, rollback becomes destructive. The retire commitment must include: an explicit migration checklist (V1→V2 redirect / compatibility adapter / data backfill); telemetry that proves residual V1 usage has dropped below a stated threshold before deletion; a rollback path; and a sunset validation step that exercises old deep links, exports, and persisted state on the post-retire build before V1 code is removed. If a retire date is recorded but the migration plan is missing, treat that as a worse state than no retire date — pressure to delete with no safety story. **What stops vs what continues**: net-new V2 feature expansion (a new module, a new tab, a new endpoint shape, a new surface area) stops until both the date AND the migration plan exist. What does NOT stop, regardless of plan status: security fixes, rollback wiring, compatibility adapters, telemetry to measure residual V1 usage, bug fixes that reduce risk in V1 or V2, and the migration work itself. Refusing to ship a security fix because the retire plan is incomplete makes the situation worse, not better — the goal of the rule is to prevent scope expansion in a half-migrated state, not to freeze risk reduction.
+- **Cross-stack naming style drift on the same field**: same semantic field rendered three different ways across web, mobile, and design — e.g. `is_xxx_checked` (web React) / `showXxxCheck` (mobile React) / a local-language label that translates to "toggle Xxx" (Figma). Each side individually defensible; together they break grep, glossary, and engineering↔design discussion. Pick one naming style per cross-cutting concept and treat it as part of the glossary, not a per-side stylistic choice. Typos that leak into the active path (e.g. `useShcool…` shipped instead of `useSchool…`) are part of this pattern, not a separate one — they reach the glossary the same way.
+- **Frame-per-state ≠ frame-per-version**: when a Figma file shows the same module name repeated N times (e.g. `<module-name> ×6`), the default extraction reading is "N coexisting versions." That reading is wrong about half the time — on mobile design files especially, frame repetition is the designer's way of expressing state variants (default / hover / selected / Modal-overlay / single-mode / all-mode / different permission combos). Inspect each repeated frame's bounding box and any state-name suffix before treating the cluster as a version graveyard. The dual-track coexistence rule applies to genuine version siblings, not to state cardinality. (Genuine version siblings carry date stamps, version suffixes, or explicit deprecation markers; state variants do not.)
+- **In-file deprecation marker vs in-file design-system tag library — read the content, not the name**: a section literally named with a local-language phrase that translates to "use this as canonical" (or "source of truth", "official version") looks like a version-marker section. Open it before drawing conclusions. If the content is a set of category/state/modality `Tag` instances (e.g. enum-style chips for type, source, status), the section is a **tag library**, not a version marker — the section name is misleading-but-internal. Real version markers tag a specific page or frame as canonical; tag libraries enumerate values used across the file. Misclassifying a tag library as a version marker corrupts the dual-track-coexistence audit.
+- **Same-name V1/V2 coexistence breaks bare "X is deprecated" deprecation markers — discriminator is mandatory**: when the user-facing label "X" exists in both an old V1 route (often a sub-page embedded under a legacy section) and a new V2 route (often a standalone top-level route), a figma annotation that says only "X is deprecated, ignore" (in any language) is **ambiguous by construction**. A literal reader will conclude the entire X capability is deprecated and either (a) wrongly retire V2 or (b) skip both and miss V2's active feature surface. The deprecation marker MUST carry a version, path, or source-route discriminator — e.g. "the OLD `<legacy-section>/X` is deprecated; the new standalone `X` route is active" — or it is an audit failure on the design side. The audit path when you hit such an ambiguous marker: (1) resolve the user-facing label X through the private glossary so you have its known code-side synonyms across languages and renames; (2) inspect the route table / router config / app-entry imports — the authoritative signal for which of V1/V2 actually mounts at runtime is the route table, not grep counts; (3) only after the glossary + runtime-entry pass, use grep on each synonym as discovery support. Escalate to the file owner when the marker lacks a discriminator AND the runtime + glossary evidence cannot identify which side is being deprecated — not merely when grep returns more than one file (tests, stories, and dead files inflate that count; multilingual route names deflate it).
+- **Implicit retire-without-delete (intra-file commented-out alternative components)**: same anti-pattern as V1/V2 dual-track, expressed at intra-file granularity. A page that renders `<Foo />` and carries `{/* <FooV1 /> */}` / `{/* <FooV2 /> */}` block-comments alongside is the same debt: the source reader cannot tell whether the commented siblings are "removed", "paused for rollback safety", or "in-flight before re-enable". The default resolution is **delete with rationale recorded in the removing commit message**, OR attach a dated `TODO(YYYY-MM-DD, owner):` comment naming the condition under which the sibling re-enables. **Re-enabling the commented sibling is NOT a routine cleanup response** — it requires the runtime owner to confirm the sibling is the actual intended active path, plus test coverage / feature-flag gating / a recorded rollback rationale; without that confirmation, re-enabling silently reintroduces duplicate UI, stale side effects, or stale permission behavior. Bare `{/* <X /> */}` blocks grow because every future reader has to decide whether to delete or restore, with no signal — the same propagation that the V1/V2 file-level rule prevents.
+- **Business-axis frame label resolved without the entitlement-source check (symmetric anti-pattern, both directions)**: paired figma frames labeled with a business axis ("X / non-X" by tier / segment / region / industry / org type) whose only structural delta is one permission-gated or state-driven UI element, resolved without checking whether the gating permission is derived from an independent business axis. Two failure shapes, both expensive: (a) reader trusts the label, introduces code branches / test fixtures / backend enums / analytics dimensions for an axis the design never actually meant (false axis ships into the contract; removing it later is expensive — consumers, dashboards, persisted records); (b) reader treats single-delta UI as definitely misleading and strips a real product axis from code / enums / analytics because the UI happened to surface through one entitlement-gated control (plan tier, region, or industry that legitimately gates one action — re-introducing the axis later is equally expensive). The fix is **structural diff PLUS entitlement-source check** (PM/PRD, product enum, entitlement matrix) before trusting **or** rejecting the label; glossary entry stores source file + node ids + revision + resolved axis + entitlement evidence so the next reader can verify rather than re-decide.
+- **Shared-API + diverged-frontend V2 rewrite is the lowest-risk dual-track shape (positive pattern)**: when V1 and V2 share the same backend API, same permission code, and same shared components — diverging only in the page shell (filters, layout, pagination, integration) — the V2 retire migration plan is correspondingly small *on the backend / permission / cross-service axis*. There is no DB migration, no permission re-grant, no cross-service contract change. But "small backend plan" is NOT "no checklist": even pure-frontend V2 rewrites routinely change route shape, query-param schemas, local-storage / persistence keys, default filter values, pagination cursor shape, analytics event names, and export entry-point URLs. The dual-track rule's compatibility checklist still applies to all of those — saved deep links, persisted user state, exports/QA fixtures, and analytics events must continue to work or have an explicit redirect/migration. The right framing: skip the DB/API/permission migration items **only after verifying those contracts are actually unchanged**; never skip the route / query / persistence / export / analytics compatibility items, and always run the post-retire sunset validation (open old deep links, check persisted state, check exports) before V1 file deletion. Size the migration to the divergence; do not skip the checklist when V2 forks the API, and do not bloat the checklist when V2 only forks the page shell — but the frontend-only checklist is still a checklist, not a single-line redirect.
+
+## Routing
+
+- Code-side enforcement of "no `FooV2` coexists with `Foo` after release N" → `web-react-dev` and `app-cross-platform-dev`.
+- Test coverage of both `V1` and `V2` paths while coexistence persists → `testing-strategy`.
+- Glossary maintenance and design-side cleanup of `_verN` / current-marker / date-stamp siblings → stays here (design discipline) plus owner update in the private archive.

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

@@ -0,0 +1,129 @@
+# Design Intake And Acceptance
+
+Use this reference before designing, implementing, or reviewing a concrete product screen. It adapts product-intent and UX-acceptance practices while staying source-agnostic and excluding source-specific visual themes.
+
+## Intake Triage
+
+Clarify these points quickly before making design decisions. Do not over-ask when the answer is obvious from the current task.
+
+| Dimension | Questions |
+| --- | --- |
+| Product goal | What user behavior should this screen increase: discovery, first participation, creation, retention, trust, or AI-assisted contribution? |
+| User segment | Is the user new, returning, creator, moderator, power user, or casual browser? |
+| Platform | Is this mobile app, mobile web, consumer web, creator web, moderation/admin-like web, or cross-platform? |
+| Surface | Is it feed, post detail, creation, onboarding, profile, topic/community, notification, AI workspace, trust/safety, analytics, or settings? |
+| Primary loop | What is the screen's loop: discover -> interact, create -> publish, AI -> refine -> share, report -> review, or notify -> return? |
+| Constraints | Are there known brand, component-library, accessibility, localization, privacy, moderation, or performance constraints? |
+| Evidence | Which references apply: Figma-derived patterns, external community benchmarks, existing codebase UI, or explicit user-provided screenshots? |
+
+If the user asks for "all of it" or gives a broad design request, deliver in this order:
+
+1. Product intent and primary loop.
+2. UX flow and required states.
+3. UI concept and layout.
+4. Design-system/tokens/component mapping.
+5. Implementation plan or review checklist.
+
+## Evidence Integrity
+
+When applying or refreshing this skill:
+
+- Do not claim a Figma page, code path, screenshot, metric, or review was checked unless it was actually inspected in the current task or already distilled in the references.
+- If source access is unavailable, say so briefly and use the distilled rules rather than blocking normal design work.
+- If evidence is thin, limit the recommendation to patterns supported by stronger references and state what would improve confidence.
+- Keep source names and old product terms out of product-facing UI copy and product structure.
+- For conflicting evidence, keep the clearer current reusable pattern, merge compatible variants, and discard stale or overly domain-specific details.
+
+## Deliverable Types
+
+Choose the smallest deliverable that satisfies the task.
+
+### UI Concept + Layout
+
+Include:
+
+- Visual direction tied to the product goal.
+- Main screen structure, hierarchy, and navigation.
+- Key modules, cards, panels, actions, and responsive behavior.
+- States that affect layout, such as empty, loading, long content, and collapsed side panels.
+
+### UX Flow
+
+Include:
+
+- Entry point, main path, success state, and return loop.
+- Error, empty, permission, moderation, AI failure, and undo paths.
+- Cross-surface transitions such as feed -> detail -> comment, AI result -> draft -> publish, notification -> thread.
+
+### Design System Mapping
+
+Include:
+
+- Tokens for color, typography, spacing, radius, shadow, and mode where relevant.
+- Component selection and variants.
+- Component states: default, hover, active, disabled, selected, loading, error, success, empty, and destructive.
+- Web/mobile differences.
+
+### Implementation Plan
+
+Include:
+
+- File or component boundaries where known.
+- Reusable components and local primitives to use first.
+- Data/state requirements for the UI.
+- Acceptance checks and visual QA steps.
+
+### Design Review
+
+Lead with issues, then recommended fixes:
+
+- Functional UX gaps.
+- State coverage gaps.
+- Visual hierarchy and layout problems.
+- Component/token violations.
+- Trust, moderation, AI, accessibility, and responsive risks.
+
+## Acceptance Standards
+
+A design or implementation is not complete until it passes these checks.
+
+### Product Fit
+
+- The target user and primary loop are clear.
+- The main action supports a real target-product behavior, not just navigation.
+- The screen gives users a reason to return, continue, or contribute.
+- AI entry points support the target product loop instead of becoming isolated chat.
+
+### UX Completeness
+
+- The canonical state taxonomy in `product-surface-patterns.md` is mapped to concrete UI behavior for this surface.
+- Long names, long posts, dense metadata, image/video failures, and permissions do not break the layout.
+- New-user and returning-user behavior are both considered when relevant.
+- Destructive, public, or moderation-related actions have confirmation and consequence copy.
+
+### Visual And Component Quality
+
+- Uses existing design-system tokens and components before inventing new styling.
+- Has a coherent visual direction and avoids generic AI-template aesthetics; see `visual-craft.md`.
+- Maintains clear hierarchy between content, metadata, actions, and system feedback.
+- Mobile surfaces respect thumb reach, keyboard, safe area, and bottom-sheet behavior.
+- Web surfaces collapse secondary panels before harming core content readability.
+- Text fits in buttons, tabs, cards, sidebars, and compact controls.
+
+### Trust, Safety, And AI
+
+- Report, hide, mute/block, sensitive, under-review, rejected, limited, and appeal/recovery states exist where relevant.
+- AI-generated, AI-assisted, human-authored, cited, edited, or community-verified states are distinguishable when trust depends on them.
+- AI output can be edited, retried, saved, shared, reported, or discarded as appropriate.
+- Moderation status communicates what happened, why it happened, and what the user can do next.
+
+### Accessibility And Responsiveness
+
+- Interactive controls have labels, keyboard/focus states where applicable, and enough hit area.
+- Color contrast, disabled state, error state, and loading state remain readable.
+- The design works at the expected mobile and desktop widths.
+- Motion or animation does not block task completion and can degrade gracefully.
+
+## Anti-Patterns
+
+Use `design-execution-checklist.md` for product-density and copy guardrails, and `scenario-community-patterns.md` for per-surface Avoid rules. Do not duplicate those lists here; during review, cite the specific violated rule and the concrete screen evidence.

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

@@ -0,0 +1,97 @@
+# Design System Source Of Truth
+
+Load this reference when working on token decisions, theme files, design-system files, or any task that asks "which Figma file is the real source for this color/component/spacing?". It defines how to identify the design-system source, how to keep design and code in sync, and how to detect and route business-file leaks.
+
+## Triggers
+
+- Adding or editing theme/token files in any subproject.
+- Onboarding a new subproject and deciding which theme to inherit.
+- Spotting two Figma files that both seem to define brand tokens.
+- A design-system Figma file appears suspiciously complete (90+ pages, full component catalog) — verify whether it is a team-authored system or a third-party mirror.
+
+## Rules
+
+- A Figma file labeled "design system" in the team's project list may actually be a **figma mirror of a third-party component library** (third-party kits like Ant Design, antd-mobile, Material, or Polaris are illustrative — the same pattern recurs across many ecosystems). Confirm by checking the page list for explicit names like `<Library> System for Figma` or `Figma to <Library>`; if present, treat the file as the third-party spec, not as team-authored tokens. The team's brand customisation usually lives in a smaller separate file, often named for a product framework refresh, a brand-system file, or a workbench/shell file — name conventions vary across teams.
+- A figma project that spans multiple end stacks should split design-system files by stack: one for desktop, one for mobile (and one for any non-React mini-app / native surface). Business-module files should not carry their own token/style definitions; they should reference the design-system file only.
+- A business-module Figma file is correctly scoped when its `/v1/files/<key>/styles` and `/v1/files/<key>/components` endpoints return zero file-local entries — all styles inherited from the design-system file. Non-zero counts on a business file = the file has forked tokens, which is a refactor flag.
+- Theme/token source files in code must include an explicit machine-checkable pointer to the design-system Figma source: top-of-file comment with the file's labeled name (not the team-internal nickname) and node-id of the token frame. Pointing the comment at a business-module file instead of the design-system file is a documented anti-pattern — the next person edits the wrong source.
+- Deprecated design files must carry an explicit signal: a dated deprecation page, an archive folder, or a tracked deprecation list in the private provenance archive. Do not rely only on file-name prefixes (brand prefix, copy suffix, etc.) — prefixes are easy to miss in tooling. Keep the active marker list in the private archive and audit each load.
+
+## Portfolio Role Taxonomy
+
+The existing `class A1 / A2 / B` labels are too coarse when a single product's design portfolio holds more than one file claiming to be system-canonical. Before treating any single `A1` file as the source-of-truth, classify every `A1` candidate by role.
+
+| role | what it is | health rules to apply |
+|---|---|---|
+| `source-of-truth` | currently authoritative system file: Brand / Semantic layer fully bound, Components tier populated, multi-mode resolved, consumed by current production code. One per stack. | full Design-Source Health Check + alignment audit against live code |
+| `upgrade-plan` | one or more files describing the next-version system (refresh / vendor migration / new brand). May intentionally not match current production code. A single upgrade plan may exist as a main file plus per-feature `upgrade-plan-supplement` files. | Migration-State `target` audit only; do not audit against current code for drift; treat supplements as parts of the same plan, not independent sources |
+| `combined-active` | a single file that mixes system-level content (components / tokens / variables) with per-feature business pages and exploration sketches, still being edited. Often the team's original monolith, the central brainstorm scratchpad before content is extracted into dedicated files, or the shared seed file new proposals start in. May coexist with a separate `source-of-truth` that received its extracted content. | partial-authority: only the portions not yet superseded by a dedicated file are evidence; mark each page with its supersession state (`migrated-to: <file_label>` / `still-authoritative` / `wip`); pages still-authoritative get the same rules as the role that page would belong to in a split portfolio |
+| `exploration-wip` | working file for direction trials and variant proposals only, with no business or system content the team relies on. Distinct from `combined-active`: nothing here is the canonical answer to anything. | weak evidence only; do not extract rules; do not audit against code |
+| `ui-kit` | component-spec file (button states, form patterns, layout primitives) documenting shape and behavior without owning brand tokens; tokens reference source-of-truth. May exist in a version chain (current ui-kit aligned to current `source-of-truth` + legacy ui-kits retained for historical reference); audit must determine which is current by inspecting the link back to source-of-truth, not by file name or recency. | verify cross-file token references back to current source-of-truth; flag any locally-defined token as a fork; legacy ui-kits in the chain treat as `class B` reference-only |
+| `platform-shell` | platform-specific surface file (desktop product chrome, mobile app chrome) consuming source-of-truth tokens; may exist per platform | same as `ui-kit` |
+| `interaction-spec` | file focused on UX flow / behavioral annotation / state transitions / gesture spec, rather than visual composition or token definition. Recognizable by naming convention pairs such as `(UI)` / `(UX)` companion files, by page content (flow diagrams, swimlanes, state machines, interaction notes), or by an explicit annotation-tool spec doc. | health-check skipped; evidence used for interaction logic / behavioral logic rules only, not token / component / visual rules |
+| `icon-library` | file owning icon set, stroke discipline, sizing rules; owns its own dimension tokens, consumes color tokens from source-of-truth | verify color / size token references; flag locally-defined color tokens as a fork |
+| `per-feature` | already covered as `class A2`: business-module file inheriting all tokens, owning page-composition evidence only | existing `A2` rules (`styles_count == 0`, `components_count == 0`) |
+
+### Portfolio-pass rule
+
+When the portfolio holds multiple `A1`-shaped files, the audit MUST enumerate the full portfolio and assign a role to every entry **before** judging any single file. Single-file-in-isolation audits produce predictable false findings:
+
+- Mistaking an `upgrade-plan` for a broken `source-of-truth` because its values do not match production code.
+- Mistaking a `ui-kit` for a competing `source-of-truth` because it defines components.
+- Mistaking a `combined-active` monolith for either a broken `source-of-truth` (because not all roles are clean inside it) or an inert `exploration-wip` (because it has scratch pages). It is neither — record per-page supersession state.
+- Treating an `interaction-spec` file as a visual/token source because the team named it after a product surface. Read the page content, not the file name.
+- Treating an `exploration-wip` as authoritative because it was the most-recently-edited file.
+
+### Predecessor / ancestry tracking
+
+The portfolio enumeration must record relations between files, not only per-file roles. For each entry, capture at least one of:
+
+- `predecessor_of: <file_label>` — an earlier file that has since been split into newer files; the newer file is now authoritative for the migrated content.
+- `derived_from: <file_label>` — a newer file that extracted content out of a predecessor; the predecessor may still hold non-migrated pages.
+- `supplements: <file_label>` — a companion file (most often `upgrade-plan-supplement` to `upgrade-plan`, or a `per-feature` extension to a parent product surface).
+- `succeeds-version: <file_label>` — a later version in a ui-kit / platform-shell version chain; the predecessor in the chain becomes legacy.
+- `no-relations` — explicitly stand-alone (rare in mature portfolios; flag for review).
+
+Sibling files without recorded relations are treated as competing source candidates, which is usually wrong: most files in a mature portfolio descend from earlier monoliths or supplement an existing parent. Missing ancestry is a portfolio-enumeration defect, not a system defect — fix the enumeration before judging the files.
+
+Record the portfolio (entries + relations) in the private provenance archive (one entry per file: role + relations + last-updated + owner + relation to current production code). The audit references the archive, not its own assumption about which file is canonical.
+
+## Decision Checklist
+
+When starting work on tokens/theme/design-system:
+
+0. Enumerate every file in the project's design portfolio (system, upgrade plan + supplements, combined-active monoliths, exploration, UI kit version chain, platform shells per stack, icon library, interaction-spec, per-feature). Assign a Portfolio Role from the taxonomy above to every entry, plus the predecessor / derived / supplements / succeeds-version / no-relations relation to other entries. Recording the portfolio with role AND relations is mandatory before any single-file judgment; missing relations is a portfolio-enumeration defect, not a system defect.
+1. Pull the project's Figma file inventory; mark each entry `class A1` (rules-as-source), `class A2` (business-module), or `class B` (deprecated/reference) using the source-map rules.
+2. For each `A1` file, verify whether it is team-authored or third-party-mirror via page-name pattern.
+3. For the active `A1` files, confirm one per stack (desktop / mobile H5 / native / mini-app). If multiple compete, choose one as canonical and demote the others to `class B` until merged.
+4. For the theme/token source file in code, verify its top-of-file Figma comment points at the canonical `A1` file's node-id, not at a business-module file.
+5. For each `A2` business file, confirm `styles_count == 0` and `components_count == 0` via Figma API. Non-zero = file-local forked tokens; route to the design-system maintainer to merge.
+6. Cross-check deprecation: every file the team treats as deprecated must appear in the private deprecation list. Files-only-marked-by-prefix get a follow-up to add them explicitly.
+
+## Anti-Patterns
+
+- **Mistaking a third-party mirror for a team design system**: leads to "we already have a complete design system" claims that ignore the missing brand customisation layer.
+- **Pointing the theme-file Figma comment at a business module**: future edits chase the wrong frame; design-code drift accumulates.
+- **Business module owns its own tokens**: `styles_count > 0` on an `A2` file is a fork. New brand updates ship only to the design-system file and silently bypass the business module.
+- **Deprecation-by-prefix-only**: a brand prefix used to mark legacy snapshots will eventually conflict with active naming. Maintain a tracked deprecation list outside the file names.
+- **Single-file audit without portfolio enumeration**: judging one design file in isolation, comparing it to current code, and reporting "drift" or "incomplete system" without checking whether other portfolio files (upgrade plan, exploration WIP, UI kit, platform shell) explain the difference. The recurring failure shape is N revisions of the audit verdict as the auditor discovers each missing role in turn — every additional file the user surfaces flips an earlier conclusion. Fix: enumerate the portfolio first, assign roles, then audit each role with the rules that apply to it.
+- **Two `colorPrimary`-shaped variables in one source with no per-platform role naming**: a design-system file that defines both a tier-correct `Brand/.../colorPrimary` AND a free-floating orphan brand variable (e.g. a `Global/<brand-color>` / `legacy/brandColor` / un-grouped top-level brand token, often in product-vernacular or non-English naming) holding a different value. Whether the divergence is intentional cross-platform branding or accidental legacy is irrelevant to consumers — they cannot tell which is "the" brand because neither name carries the platform role. Fix is in the source: either (a) consolidate to one value and remove the orphan, or (b) rename to express the divergence explicitly (`colorPrimary-web` / `colorPrimary-native`, separate variable collections per platform, etc.). See `multi-project-token-consistency.md` for the cross-platform brand-divergence classification and the consumer-side audit signal.
+
+## Green-Field Fallback (No Existing Figma DS Yet)
+
+A new product or a new team may not have a Figma design-system file at all. The rules above assume one exists; without one, do not stall the build. Instead:
+
+1. Define the **token role taxonomy** first, in code or a short doc, before any Figma file: primary, primary-text-on-fill, fill/surface, text strong/secondary/muted, border/line, background, semantic (success/warning/danger/info), and any product-specific semantic role (e.g. "evidence", "automated", "destructive"). Names only at this stage; values can be placeholders.
+2. Set placeholder hex values that satisfy contrast and obvious-brand-distance from the third-party library default. Pick values that are clearly the team's own (not a vendor default), record them as the working palette, and note that they are provisional.
+3. Inject these token roles at the entry layer of every same-stack subproject from day one (`ConfigProvider theme={brandTheme}` / `MaterialApp.theme` / equivalent). The injection mechanism is the source-of-truth — the values can still be replaced when a designer commits them.
+4. When a Figma design-system file later arrives, register it in the private archive, point the code's theme source file at it via a top-of-file comment with file name + node-id, and replace the placeholders. The role taxonomy survives unchanged; only the values shift.
+5. Do not block product work on "we don't have a design system yet." A token role taxonomy + injected theme is a sufficient starting design system; the Figma file is provenance and refinement, not a prerequisite.
+
+This fallback exists because the standard rules above require a Figma file inventory; without one, those rules return "no action" instead of "act on the role taxonomy". The fallback fills that gap.
+
+## Routing
+
+- Implementation enforcement of the comment-pointer rule and the `styles_count == 0` audit → `web-react-dev` (tools) and `testing-strategy` (acceptance).
+- Native stack-specific design-system selection → `app-cross-platform-dev`.
+- Mini-program stack-specific design-system selection → `miniapp-product-dev`.