@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/two-source-extraction-pattern.md

@@ -0,0 +1,167 @@
+# Two-Source Extraction Pattern (Design + Code)
+
+Use when extracting frontend skill content from **both** a design source (Figma / Sketch / Penpot / equivalent) and a code source (web React monorepo / mobile app monorepo / native iOS-Android workspace). The two sources together describe what the product should look like AND how it is built; either one alone produces incomplete or contradictory skill content.
+
+This is a sub-pattern of the main extraction workflow — charter / source register / batch loop / sanitize / dual-track / commit all still apply. This reference covers the **two-source-specific procedural discipline** layered on top. The concrete design judgments (file classification, deprecation markers, token validation, naming/versioning) live in `product-ui-ux-design/references/`; this file routes to them rather than duplicating them.
+
+## When this pattern applies
+
+- Figma project + React web monorepo for the same product → both feed `product-ui-ux-design` + `web-react-dev`.
+- Figma project + Flutter / native iOS / Android workspace → both feed `product-ui-ux-design` + `app-cross-platform-dev`.
+- Design tokens (typography / color / spacing / motion) need cross-validation against implementation tokens.
+- Multi-package frontend monorepo with mixed targets (web app + admin console + design-system package + shared utils) — class-based subproject mapping is essential.
+
+## When this pattern does NOT apply
+
+- Code-only extraction (no design source available) → use the main workflow.
+- Design-only extraction (no implementation yet) → use the main workflow + route findings to design skills.
+- Backend service extraction → use the main workflow; sibling stacks via the sibling mini-map rule.
+
+## Source pinning (snapshot before mining)
+
+Before each batch loop iteration, pin both sources so mining and cross-validation operate on a fixed snapshot:
+
+- Design source: file key + version (the explicit version id from the design tool's version history, not just `lastModified`) + selected page/frame node ids + token export timestamp (if a token bridge tool is in use).
+- Code source: branch + commit SHA + lockfile hash (`package-lock.json` / `pnpm-lock.yaml` / `yarn.lock` / `Podfile.lock` / `pubspec.lock` as applicable) + any generated-asset content hash.
+
+If either snapshot changes during the batch (designer pushes a new version; branch rebases; tokens re-export; a code-mod sweep lands), the batch is invalidated. Either restart the batch on a fresh pinned snapshot or mark the affected cross-source rows `stale — re-mine` and exclude them from this commit. Do not land token, drift, or routing rules from mixed snapshots; they describe a state that never existed.
+
+## Source register extends the standard row
+
+This pattern **extends** the standard source-register row defined in `source-register.md` (`source_id | source_type | class | path/file_key | status | min_depth | actual_depth | extracted_mechanisms | discarded_business_details | target_skill | evidence_link`). The columns below are the additions and the conventions specific to two-source extraction; do not omit the required columns from the standard row when applying this pattern.
+
+This pattern **specializes the standard singular `target_skill` field into plural `target_skills`** (see below). The shared register schema remains singular until a parent rewrite lands plural ownership across all extraction classes; treat the plural variant as a documented per-pattern specialization, not a contradiction.
+
+| Column added or specialized | Convention |
+| --- | --- |
+| `source_type` | `design` or `code` |
+| `class` | for `source_type=design`: `A1` (rules source — design system / tokens), `A2` (business module / page-layout source), `B` (deprecated / reference-only). For `source_type=code`: `web`, `native`, `pkg-shared`, `infra`, `legacy`, `excluded-support`. |
+| `path / file_key` | design: design-file key placeholder; code: monorepo-relative path. Real keys/paths live only in the private alias map. |
+| `target_skills` | **plural — list every affected skill.** A single source row often updates `product-ui-ux-design` + `web-react-dev` (or + `app-cross-platform-dev`) + `testing-strategy`; never collapse to one target when the mechanism touches design judgment + implementation + tests. Each owner gets its own target-output row downstream. |
+| `pinned_snapshot` | the version/SHA captured by the pinning rule above |
+
+Real source identifiers (design file keys, monorepo paths, contributor names) live in the project's private alias map per the Extraction lifecycle handoff rule in `SKILL.md`. The shared register carries only sanitized placeholders.
+
+### Subproject classification for `source_type=code`
+
+The five-class `web / native / pkg-shared / infra / legacy` scheme covers runtime sources of truth. Real monorepos also contain support packages that look like code but **cannot define positive skill rules**. Add a sixth class:
+
+- `excluded-support` — candidate examples: Storybook / docs / examples / generated SDK output / fixtures and mocks / visual preview sandboxes / vendor mirrors / test-data builders. Inspectable for *context* only; never the runtime source. Findings drawn from an `excluded-support` package alone must be downgraded to working hypothesis or routed to the runtime source that the support package serves.
+
+**Classification is by runtime participation, not by package type.** Before marking any package `excluded-support`, run the runtime-participation test:
+
+- Is the package imported by production code (any path that reaches a release artifact)?
+- Is it included in any runtime bundle (web bundle, app image, server container, lambda)?
+- Does it define contract or wire-format semantics actually executed at runtime (request serialization, auth headers, error normalization, schema validation, capability checks)?
+- Is its output published to a real consumer (real users, real services, real downstream pipelines)?
+
+If **any** answer is yes, the runtime slice classifies as `web` / `native` / `pkg-shared` / `infra` — even if the package is generated, vendored, fixture-shaped, or "support"-named. A package may have a runtime slice AND a support slice; split it conceptually in the register (one runtime row + one support row) before mining. Mis-applying `excluded-support` to a runtime package will silently dodge real rule extraction.
+
+## Where the design judgments live (route to these)
+
+This file is the *procedure*. The *judgments* — which file is the source of truth, what deprecation markers mean, how tokens align across sources, how naming drift is resolved — live in dedicated references. Load them when you reach the corresponding step in the quickstart below.
+
+| Two-source decision needed | Owning reference (load this) |
+|---|---|
+| Identifying which design file is the real source-of-truth; A1/A2/B file classification; team deprecation-marker discipline; business-module file should have zero file-local styles | `product-ui-ux-design/references/design-system-source-of-truth.md` |
+| Code monorepo subproject classification + the `excluded-support` carve-out; per-class routing; retire/isolate/coexist for stack outliers | `product-ui-ux-design/references/multi-stack-strategy.md` |
+| Token cross-source validation procedure (match / drift / missing / renamed) + per-class token table + audit YAML shape | `product-ui-ux-design/references/multi-project-token-consistency.md` |
+| Design ↔ code naming drift; `FooV2` coexistence; date-stamp-as-page-name discipline; conflict precedence between discriminators | `product-ui-ux-design/references/design-impl-naming-and-versioning.md` |
+| Visible state / runtime behavior / cross-owner acceptance (states families, navigation/return paths, disabled reasons, recovery controls, timing/feedback, accessibility, responsive variants) | `skill-extraction-workflow/references/uiux-routing-map.md` — load **first** before deciding whether a finding is design-judgment vs implementation vs testing |
+
+Routing precedence: load the UI/UX routing map first; it tells you which owner(s) a cross-source decision belongs to. The four `product-ui-ux-design` references above own only the **design-judgment** slice; runtime behavior, implementation mechanics, and test strategy route to `web-react-dev` / `app-cross-platform-dev` / `testing-strategy` / `product-ui-ux-design` (acceptance) — each gets its own target-output row, not one collapsed owner.
+
+Do not duplicate the content from these references in this file. If a rule shifts, it shifts in one place.
+
+## Token cross-validation must record context
+
+Tokens with the same name in design and code can legitimately disagree when they live in different contexts (brand vs product, light vs dark mode, tenant override, platform-specific). Before declaring drift, classify each token comparison by **context**:
+
+- `global-brand` — colors/typography defined by the brand layer; design file is authoritative.
+- `product-semantic` — product-level semantic tokens (e.g. `surface.default`, `text.muted`); design and code should match within a context.
+- `platform` — platform-specific token (iOS vs Android vs web); differences expected, not drift.
+- `theme-mode` — light/dark/high-contrast variant; value differs by mode, not by source.
+- `tenant / runtime` — value injected at runtime per tenant; design carries placeholder, code carries injection point.
+- `local-exception` — explicit override in a specific surface; documented divergence.
+
+Only compare tokens **within the same context**. A value mismatch across contexts is a **mapping**, not drift. Validation must run for every token class touched by the batch (typography / color / spacing / radius / shadow / motion) or explicitly mark untouched classes `not in scope` with evidence — sampling one class and claiming cross-source consistency is a false pass.
+
+**Non-drift context classifications require both-side evidence.** When labeling a comparison `mapping` (rather than `drift`), record:
+
+- Design-side context evidence — the design-file frame, layer, theme variable, or token-export field that declares this context.
+- Code-side context evidence — the code symbol, theme switcher, tenant config field, or build target that declares this context.
+- Owner — the team or skill that owns the cross-context mapping.
+- Lifecycle — `permanent` (intentional ongoing mapping) or `expires_when:<concrete trigger>` (temporary divergence pending reconciliation).
+
+If any of the four is missing, the comparison is `unresolved drift`, not `mapping`. A stale code comment, a single-side TODO, or an undocumented runtime override is not evidence; it is the failure mode itself.
+
+## Sanitization additions specific to two-source extraction
+
+These extend the main `recurring-anti-patterns-checklist.md` and the R0 hard-gate audit; they do **not** replace either. Zero hits required across all categories before commit.
+
+### Design-source-specific patterns
+
+| Anti-pattern | Symptom | Fix |
+|---|---|---|
+| Design file key in shared skill content | `https://www.figma.com/file/<key>/...`, `https://www.figma.com/design/<key>/...`, `https://www.figma.com/proto/<key>/...`, `figma://file/<key>...` deep-links, bare 22-char alnum key, `?node-id=<id>` and `?fileVersion=<id>` query params | URL/link → "the design system file"; key, version id, and node id → private alias only |
+| Design project / team name in skill text | `<product-name> Design System`, `<team-name>'s tokens` | "the platform's design-system project" |
+| Real page / frame / business-noun names | "<product> <business-flow> detail page", "<product> <entity> management" | Generic role: "feature detail page", "entity-list page" |
+| Real contributor names | `designed by <name>` in metadata, `Last edited by <name>` | Strip; provenance only |
+| Real component instance names that leak business identity | a tenant-named picker, a bureau-named approval card | Generic role: "tenant-scoped picker", "approval card" |
+
+### Code-monorepo-specific patterns
+
+| Anti-pattern | Symptom | Fix |
+|---|---|---|
+| Real subproject path | `<monorepo>/<env>/<product>/<role>-web` | "the operator web package" (role) |
+| Real package / workspace name | `@<org>/<product>-ui-kit`, pnpm workspace name `@<org>/<product>-*`, yarn workspace path | `<ui-kit-package>` / `<workspace-scope>` placeholder |
+| Real import path examples | `import { Foo } from '@<org>/<pkg>'` | `import { Foo } from '<pkg-shared>'` |
+| Internal API base URL | product API host, environment-scoped internal host | `<api-base-url>` placeholder |
+| Build pipeline / CI workflow names | `<product>-ci`, `<product>-staging-deploy`, GitHub Actions workflow file names that contain product | "the project's CI pipeline" |
+| Git provenance literals | real branch names, commit SHAs, remote URLs, tags in code excerpts or examples | strip; provenance only — examples use `<branch>` / `<sha>` |
+| Mobile / desktop app identifiers | iOS bundle id `com.<org>.<product>`, Android applicationId, macOS bundle id, Expo slug | `<app-bundle-id>` placeholder |
+| Env-var prefixes carrying brand | `<PRODUCT>_API_KEY`, `<PRODUCT>_FEATURE_FLAG_*` | `<APP>_*` placeholder |
+| Storybook / dev-tool URLs | product Storybook host, real preview deploy URLs | "the project's Storybook" / "preview deployment" |
+
+The specific grep commands and per-project allow-lists for these categories live in the private alias map per the parent skill's R0 rule. The shared file carries only the category list above.
+
+## Quickstart adaptation for two-source
+
+The main extraction quickstart (charter / register / batch / sanitize / review / commit) applies; substeps that change:
+
+1. **Charter** — declare both sources in scope, name the source corpora at a class level (not by specific keys).
+2. **Source register** — extended standard row above; pin both sources; classify every design file AND every monorepo subproject (including the `excluded-support` carve-out) before mining. For design-file classification load `product-ui-ux-design/references/design-system-source-of-truth.md`; for subproject classification load `product-ui-ux-design/references/multi-stack-strategy.md`.
+3. **Batch plan** — batches are typically by feature surface, with design + code mined together per feature (NOT design in one batch, code in another — that loses cross-source validation).
+4. **Per-batch loop** — runs the standard quickstart substeps; the two-source-specific insertions are:
+   - **Snapshot check** before mining: confirm both sources still match their pinned snapshot; if not, restart the batch or mark rows stale.
+   - **Source reading**: load both design and code evidence for the feature.
+   - **Cross-source token validation**: a new substep that sits **after source reading and before `3b. Draft skill / reference`**. Load `product-ui-ux-design/references/multi-project-token-consistency.md` for the procedure; classify each comparison by `token_context` (above) before declaring match/drift/missing/renamed; record results in the evidence ledger.
+   - **Drafting and `3e. Dual-track review`**: proceed per the standard quickstart.
+5. **Naming/versioning resolution** — if the batch hits design ↔ code naming drift, `FooV2` coexistence, or contradictory current-discriminators, load `product-ui-ux-design/references/design-impl-naming-and-versioning.md`.
+6. **Sanitization** — main R0 checklist + the two-source-specific anti-pattern tables above (extending, not replacing, R0).
+7. **Dual-track review** — for design-judgment skills, the review pass MUST inspect the design evidence (not just the skill text); the challenge pass focuses on what could break under chaos (deprecated files mistaken for fresh, drift undetected, business nouns leaked, snapshot drift).
+8. **Commit** — separate commits per evidence type when possible (design rules vs implementation rules vs cross-cutting), so reviewers can see which source drove each change.
+
+## Failure modes specific to this pattern
+
+- Mining deprecated design files as fresh evidence → stale rules ship to skill tree. (Mitigation: load `product-ui-ux-design/references/design-system-source-of-truth.md` for deprecation discipline.)
+- Skipping monorepo subproject classification or the `excluded-support` carve-out → support packages leak example-only patterns into rules. (Mitigation: classify every package before mining; downgrade `excluded-support` evidence.)
+- Skipping token cross-validation, or running it without `token_context` → design and code differences treated as drift when they are intentional mappings, or real drift hidden under context excuses. (Mitigation: classify context first, then compare.)
+- Cross-validating moving snapshots → fake drift / fake match shipped as rules. (Mitigation: pinning rule above; restart batch on snapshot change.)
+- Batching design in one session, code in another → cross-source validation never happens; per-feature batching prevents this.
+- Treating design-file naming as ground truth → team-convention markers (bracket prefixes etc.) silently mean "deprecated"; easy to miss without explicit deprecation rule.
+- Letting business page / component names leak into shared skill text → sanitization gap. (Mitigation: tables above + R0 hard-gate audit.)
+- Collapsing a multi-owner mechanism into a single `target_skill` → design-judgment rule lands but implementation/test owners get nothing. (Mitigation: `target_skills` is plural; UI/UX routing map loaded first.)
+- Two-source mismatch (design says X, code does Y) treated as a skill rule → coordination decision masquerading as design discipline. (Mitigation: resolve outside the skill; design + code owners decide; record only the *resolution shape* — never the specific case — in skills.)
+
+## Verification
+
+- Source register shows extended-row columns populated; both sources have pinned snapshots; every file/package has a class (including `excluded-support` where applicable) and a status; `target_skills` is a list, not a single value, whenever the mechanism touches multiple owners.
+- Token cross-validation audit ran for every token class touched by the batch (or marked `not in scope` with evidence), with `token_context` recorded per comparison; audit results in the project's alias map per `product-ui-ux-design/references/multi-project-token-consistency.md`.
+- Sanitization re-audit: 0 hits across the design-source and code-monorepo category tables above plus the main R0 categories (design-file keys/URLs/versions/node ids, Git provenance literals, workspace scopes, app bundle ids, env var prefixes, Storybook URLs, business page nouns, project/team names, contributor names).
+- Routing check: every cross-source decision is present in the target-output map and routed to its actual owners — design judgment to `product-ui-ux-design`, implementation/runtime to `web-react-dev` / `app-cross-platform-dev`, state/acceptance to `uiux-routing-map.md`'s owners, test strategy to `testing-strategy`. A decision with no owner blocks landing until the owner is named.
+- Skill content reviewable by both a designer (design evidence cited at the class level) and a frontend engineer (code evidence cited at the class level) without either party objecting to mis-routing.
+
+## Worked example (link, not content)
+
+A two-source extraction pass for a real project lives in the maintainer's private alias map at `~/.<host>/.private-aliases/<project>.yaml`. Concrete A1/A2/B file classifications, code subproject classifications (including `excluded-support`), deprecation markers, pinned snapshots, sanitization grep patterns, and token-audit rows live there. The shared skill tree carries only the methodology in this file and the design-judgment rules in the referenced files; no specific project provenance.

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/uiux-judgment-extraction.md

@@ -0,0 +1,179 @@
+# UI/UX Judgment Extraction
+
+Use this reference when extracting reusable UI/UX, frontend, app, or client-facing skill rules from Figma, code, screenshots, product reviews, or repeated implementation work.
+
+The goal is to turn source evidence into rules that help future teams produce good-looking, behaviorally sound, testable product surfaces without needing access to the original source.
+
+Figma and code have different evidence roles:
+
+- Figma is the experience-intent source: visual hierarchy, layout, component states, interaction model, content density, mood, and state families.
+- Implementation code is the runtime-behavior source: route ownership, state machines, API/cache/rollback, disabled reasons, retry, duplicate guards, bridge behavior, persistence, performance, accessibility, and recoverability.
+- Design systems and implementation themes are the visual-token source: typography family/roles, primary/semantic colors, neutral/background scale, spacing rhythm, radius, shadow/elevation, component density, and whether page-level styling follows or diverges from shared tokens.
+
+For any extraction that claims interaction logic, behavioral logic, psychology, development guidance, testing guidance, or launch acceptance, corresponding frontend/app/client code is required unless it is unavailable or explicitly out of scope. If code is unavailable, mark the result as design-intent extraction only and do not claim runtime behavior was validated.
+
+The judgment-dimension axis (the enumeration the entrypoint's adjacency-scan rule points at): visual direction/tokens, aesthetics, interaction logic, behavioral logic, psychology, accessibility, implementation ownership, testing evidence, and product readiness.
+
+## Required Method
+
+Do not start by writing principles. For each target workflow or screen family, build this chain:
+
+| Step | Required output |
+| --- | --- |
+| Observation | What exact state, layout, interaction, code path, recovery path, or runtime mechanism was inspected. |
+| Judgment | Which layer the observation affects: aesthetics, interaction logic, behavioral logic, psychology, accessibility, motion/feedback, or microcopy. |
+| Rule | A source-neutral instruction future agents can execute. |
+| Acceptance | Screenshot, rendered device/browser check, unit/component/E2E scenario, or review pressure scenario that proves the rule works. |
+
+Rules that cannot name an observation and an acceptance check stay out of executable skill guidance. Keep them as hypotheses or discard them.
+
+## Four Judgment Layers
+
+| Layer | Extract from source evidence | Convert into reusable rules |
+| --- | --- | --- |
+| Aesthetics | Visual focal point, hierarchy, density, rhythm, spacing, type scale, color weight, material treatment, mood, and whether the screen feels intentional. | Which element leads, how dense the surface should be, what visual weight belongs to primary/secondary/exception content, and how the mood supports the task. |
+| Visual direction and tokens | Typography source, primary color source, neutral/background scale, radius/shadow role, token/component theme mapping, and variant directions when no strong reference exists. | Whether to reuse the existing product visual language unchanged, tighten token usage, or compare two or three compact visual directions before implementation or acceptance. |
+| Interaction logic | Entry, current task, next action, return path, modal/drawer stack, deep link, tab/route hierarchy, input method, gesture conflict, progressive disclosure, and task continuity. | Discover -> Inspect -> Act -> Confirm -> Return flow, plus navigation, keyboard, gesture, and return-context rules. |
+| Behavioral logic | Repetition, hesitation, mistakes, waiting, abandonment, retry, undo, cancel, disabled states, interruption, stale state, and recovery. | State-machine and recovery rules: duplicate guard, rollback, retry, confirm, disabled reason, progress, queue boundary, and restore behavior. |
+| Psychology | Anxiety, uncertainty, perceived control, confidence, trust, motivation, consequence, cognitive load, fatigue, and regret avoidance. | Certainty/control/trust rules backed by visible status, consequence copy, reversible actions, local recovery, progress proof, and risk-matched friction. |
+
+For each layer, mark the delta: `new`, `confirmed`, `narrowed`, `routed`, or `no new evidence`. Do not count a restatement of a known principle as a new extraction.
+
+### Visual Direction And Token Provenance Minimum
+
+For UI/UX, Figma, web, or app extraction, the visual direction/tokens layer must record these fields before any claim of `new`, `confirmed`, or `narrowed`:
+
+- Typography: font family, size steps, line-height rhythm, weight roles, and where dense versus expressive type is allowed.
+- Color: primary/action/selection source, neutral text and background scale, line/divider color, semantic status colors, and whether raw page colors match or diverge from shared tokens.
+- Shape/material: radius scale, shadow/elevation role, surface layering, density mode, and component state variants.
+- Visual mood: the task mood the source supports, such as calm workbench, expressive creation, high-trust review, or fast repeated operation, plus where expressive treatments such as gradients or illustration are allowed.
+- Implementation mapping: the theme, token file, component library, CSS variables, or style layer that carries the source intent; if implementation code is unavailable, mark runtime token provenance unavailable and do not claim dev validation.
+- Acceptance owner: the design reference, web/app skill, testing matrix, or product workflow rule that must change. If no target changes, record why the existing rule already covers the evidence.
+
+A row that only says "tokens confirmed" or "视觉方向已确认" is incomplete. Downgrade it to `source inventory` until the fields above are filled or explicitly ruled out of scope.
+
+## Static Proxy Evidence
+
+Figma and code are not live user research. To infer behavior and psychology responsibly, use observable proxies:
+
+| Human issue | Static proxy evidence |
+| --- | --- |
+| User may not know what to do next | Primary action visibility, disabled reason, empty-state next step, route title, active tab, selected item, progressive disclosure. |
+| User may fear losing work | Draft state, autosave indicator, unsaved-change guard, undo/cancel, return context, persisted state, restore after interruption. |
+| User may make accidental bulk or destructive changes | Confirmation depth, consequence copy, preview-before-commit, apply-once versus remember choice, second confirmation, cooldown or acknowledgement. |
+| User may wait or abandon | Progress state, skeleton versus spinner choice, local retry, timeout handling, partial success, queued/pending/final distinction. |
+| User may repeat a high-volume task | Stable control positions, keyboard shortcuts or compact controls, low-noise visual rails, current item/progress, batch mode, fatigue-reducing density. |
+| User may hit weak network or runtime failure | Retry region, old-content hold during reload, offline/weak-network state, rollback, cache hit, error mapped to next action. |
+| User may lose place after navigation or orientation change | Route/context ownership, scroll restore, selected item restore, geometry reset, shell orientation cleanup, back-stack behavior. |
+| User may distrust automation or generated output | Source/caveat, editable generated state, review-before-commit, confidence/quality state, regenerate/retry, human final action. |
+
+If no proxy is visible, mark the layer `no new evidence` instead of inventing a psychology rule.
+
+## State Family Inventory
+
+For UI/UX extraction, read state families rather than only the default screen:
+
+- Initial, normal, long-content, dense-content, empty/no-data, loading, slow/weak network, error/retry, permission/no-access, disabled, confirmation, success, partial-success, failure-recovery, stale/expired, interruption/return, repeated-use/cache-hit.
+- Device and environment variants: narrow/wide, portrait/landscape, keyboard open, safe area, text scaling, dark/light mode, reduced motion, offline, bridge/native capability missing, old browser/WebView fallback.
+- Product variants when visible: first-use, returning-use, guest/authenticated, permission-limited, feature-flagged, degraded, version-incompatible, and A/B or gray-release branches.
+
+Record which states were read, unavailable, excluded, or still pending. Do not call the extraction complete if required state families are only sampled.
+
+## Aesthetic Proxies And Thresholds
+
+Use source-specific judgment, but verify with concrete proxies:
+
+- One primary visual focus per task state; secondary controls should not compete with the main artifact or decision.
+- Use stable spacing rhythm such as 4/8px increments unless the source system clearly uses another rhythm.
+- Record token provenance before extracting visual rules: the source of typography, primary color, neutral/background scale, radius, shadow/elevation, and component density. If the source has multiple plausible visual directions or the implementation code hardcodes page-level colors, treat that as extraction evidence and decide whether the reusable rule should require a visual direction comparison, token cleanup, or both.
+- Touch targets should meet platform norms: at least 44pt on iOS and 48dp on Android where touch is required.
+- Text contrast should meet WCAG expectations for normal and small text; do not rely on brand color alone for state.
+- Dense work surfaces should keep stable row/card height, fixed context when identity would be lost, and local overflow affordance instead of decorative whitespace.
+- Modal, drawer, overlay, and floating tool visual weight should match consequence: lightweight details should not look as severe as destructive confirmation.
+- Motion and delight should support task comprehension, success, or recovery; do not add decorative motion to error, permission, payment, or destructive states.
+
+## Interaction Extraction Checklist
+
+For each flow, inspect and record:
+
+- Entry sources: home/list/card/deep link/notification/search/return.
+- Current-state proof: selected item, active tab, route title, progress, pending/committed marker, scope/filter chips.
+- Next action: primary action, disabled reason, secondary action, escape/cancel, help/detail.
+- Progressive disclosure: drawer, sheet, modal, tooltip, advanced settings, detail page, preview.
+- Return path: after submit, cancel, failure, detail view, orientation change, background/foreground, and route replacement.
+- Input and gestures: keyboard reachability, IME behavior, paste/delete/caret, swipe conflict, pinch/zoom/pan, drag boundary, tap fallback.
+- Stack rules: modal-over-modal avoidance, drawer return context, overlay cleanup, deep-link recovery, native/web bridge fallback.
+
+## Behavioral And Psychology Anchors
+
+Each behavioral or psychology rule needs at least one falsifiable anchor:
+
+- Hick: reduce active choices while the user is deciding; reveal controls when inspecting or correcting.
+- Fitts: repeated or high-risk controls need stable placement and adequate hit area.
+- Miller/cognitive load: chunk dense information; do not force users to hold hidden context across modal or route changes.
+- Doherty/feedback timing: show feedback quickly for user actions; use visible pending/final states for long work.
+- Error prevention: prevent invalid input before submit when possible; when not possible, show local repair guidance.
+- User control: provide cancel, undo, retry, edit, restore, or explicit irreversible confirmation depending on consequence.
+- Trust: show source, scope, permission, timestamp, automation caveat, and consequence near the affected decision.
+- Fatigue: for repeated work, reduce visual noise, preserve motor memory, show progress, keep current item visible, and avoid surprising layout shifts.
+
+## Microcopy And Error Attribution
+
+Microcopy is part of UI/UX extraction:
+
+- Empty states should explain what is missing and what the user can do next.
+- Disabled states should name the missing requirement or permission when user action can repair it.
+- Error copy should map failure to a recovery path; avoid raw transport envelopes, stack traces, or blame-shifting.
+- Confirmation copy must state consequence, scope, and reversibility for destructive, public, costly, bulk, or default-setting actions.
+- Automation copy should separate generated suggestion from user-owned final decision.
+
+## Routing And Landing
+
+Before editing target skills, build a target-output map:
+
+- Design/reference target owns visual hierarchy, interaction model, UX states, mood, acceptance screenshots, and no-source-access usage.
+- Web or app dev target owns route/state/API/cache/bridge/gesture/performance implementation rules.
+- Testing target owns scenario matrices, assertions, device/browser smoke, accessibility checks, and recovery tests.
+- Product workflow target owns readiness gates, launch acceptance, high-risk consequences, and iteration signals when the change affects product delivery.
+- Extraction workflow owns method, coverage, evidence, and validation rules.
+
+If a source-derived rule touches more than one owner, update each owner or record why it is unchanged.
+
+## Minimum Pressure Set
+
+For UI/UX extraction beyond wording-only cleanup, pressure-test the resulting rules against:
+
+- Long content or dense content.
+- Empty/no-data.
+- Loading and slow/weak network.
+- Error with retry.
+- Permission/no-access or disabled action.
+- Narrow viewport or small device.
+- Accessibility text scaling or screen-reader/focus implication.
+- Orientation, viewport, keyboard, or safe-area change when relevant.
+- Interruption and return recovery.
+- Repeated-use or cache-hit path.
+
+For mobile/native-hosted surfaces, also check native bridge unavailable, back behavior, foreground/background, and host-shell cleanup when relevant.
+
+## Completion Gate
+
+Do not claim systematic UI/UX extraction unless all are true:
+
+- The validation pass reopened relevant Figma/design/code/runtime artifacts after the method or target skill changed. A pressure test that reads only the skill files is a static review and cannot prove the method changes future extraction behavior.
+- Source register rows for required Figma/code/state families are closed, explicitly excluded, unavailable, or downscoped.
+- Observation -> judgment -> rule -> acceptance is recorded for each landed rule.
+- Judgment-delta matrix covers visual direction/tokens, aesthetics, interaction logic, behavioral logic, and psychology.
+- Target-output map matches the actual diff across design, web/app, testing, product workflow, and extraction workflow owners.
+- Minimum pressure set is passed or explicitly marked not applicable.
+- Executable guidance has no source-domain names, internal project names, real business copy, source IDs, or one-off implementation details.
+
+## Pressure-Test Protocol
+
+Use this when validating that an extraction skill or design/client skill actually changes future behavior:
+
+1. Pick a source-backed workflow that previously exposed a failure, such as missed source reads, shallow UI/UX rules, routing gaps, accessibility gaps, or overclaim.
+2. Reopen at least one design artifact and one runtime artifact when behavior, psychology, implementation, testing, or launch acceptance is being claimed.
+3. Record what changed in the extraction method before the test, then run the source evidence through the required chain: observation, judgment, rule, acceptance.
+4. Compare the result against current skills. If the source reveals a gap, update the smallest owning skill/reference. If it confirms existing guidance, record that no new rule was needed.
+5. Mark the coverage honestly: targeted pressure test, file-level refresh, node/artifact inventory, or full workflow extraction. Never upgrade a targeted pressure test into a full-source claim.

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/uiux-routing-map.md

@@ -0,0 +1,51 @@
+# UI/UX Extraction Routing Map
+
+Use this reference before landing UI/UX, Figma, frontend, app, or client-facing extraction rules. It prevents source evidence from updating only the design skill while missing implementation, testing, product workflow, or extraction-method owners.
+
+## Routing Rules
+
+- Route by lifecycle ownership, not by where the evidence was found.
+- A Figma observation can require web/app/test updates when it describes runtime behavior.
+- A code observation can require design updates when it reveals a state users must understand visually.
+- If a rule is source-derived but an owner is not updated, record the reason in the target-output map.
+
+## Common Routing Map
+
+| Rule type | Design/reference | Web React | App/cross-platform | Testing | Product workflow | Extraction workflow |
+| --- | --- | --- | --- | --- | --- | --- |
+| Visual direction, typography source, semantic color tokens, neutral/background scale, radius/shadow role, or theme divergence | required | required when implementation/theme/CSS owns it | required when app/native theme owns it | screenshot/contrast/visual acceptance | optional for readiness gate | required when extraction method missed token provenance |
+| Visual hierarchy, focal point, density, spacing, mood | required | optional when implementation affects layout | optional when mobile/native layout affected | screenshot/visual acceptance | optional for readiness gate | no |
+| Component state semantics such as hover, active, selected, disabled, empty, loading, error | required | required for web implementation | required for app implementation | required | optional | no |
+| Entry/current/next/return flow | required | required for route/state ownership | required for navigation/native shell | required | required when it changes delivery scope | no |
+| Modal, drawer, overlay, popover, sheet, or stack behavior | required | required when web surface owns it | required when app/native shell owns it | required | optional | no |
+| Keyboard, IME, paste, focus, caret, safe area, or viewport behavior | required for UX acceptance | required for web/H5 | required for app/WebView/native | required | optional | no |
+| Gesture conflict such as swipe, drag, pinch, zoom, tap fallback | required | required when browser/H5 | required when mobile/native | required | optional | no |
+| Media preview, retry, old-content hold, zoom/pan, crop, upload progress | required | required for web/H5 implementation | required for app/native capability | required | required for high-risk media workflows | no |
+| Duplicate submit, idempotency, pending/final distinction, rollback | required for visible states | required | required | required | required for high-risk finality | no |
+| Bulk/default/destructive/public/costly action consequence | required | required if implemented in web | required if implemented in app | required | required | no |
+| Permission/no-access/feature-disabled/no-entitlement state | required | required | required | required | required when product scope changes | no |
+| Native shell bridge, WebView/WKWebView, injected app info, native storage, page-ready overlay | required for shell-dependent UX | required for H5 side | required for native side | required | optional | no |
+| Orientation, safe area, foreground/background, app restart, return recovery | required for mobile UX | required for app-hosted H5 | required | required | optional | no |
+| Automation, generated content, AI suggestion, confidence/caveat, review-before-commit | required | required when web owns generated flow | required when app owns generated flow | required | required for AI/high-impact workflow | optional if extraction method learned |
+| Analytics/chart/table dense inspection, drilldown, scroll restore | required | required for web implementation | required for app implementation | required | optional | no |
+| Accessibility: contrast, labels, focus order, touch target, text scaling, reduced motion | required | required | required | required | launch readiness when user-facing | no |
+| Microcopy: empty, error, disabled, confirmation, consequence, source/caveat | required | required where code maps messages | required where app maps messages | required | required for high-risk actions | no |
+| Performance perception: skeleton/spinner, first feedback, long task progress, cancel | required | required | required | required | launch readiness when performance-sensitive | no |
+| Domain leakage, source naming, extraction coverage, judgment-delta, evidence depth | no | no | no | no | no | required |
+
+## Default Decisions
+
+- Figma-only extraction can update design references, but must mark implementation/testing behavior as unverified unless code or runtime evidence is inspected.
+- Code-only extraction can update development and testing skills, but must not claim a new aesthetic rule unless rendered UI, screenshots, or design source is inspected.
+- Figma plus code extraction for a user-facing flow normally updates at least design/reference, the relevant web or app skill, testing strategy, and provenance when it changes visible design, runtime states, or acceptance gates. If it introduces or substantially reshapes a screen, include visual direction/token provenance in the target-output map.
+- Product workflow updates are required when the rule changes readiness gates, launch acceptance, high-risk finality, user trust, compliance, money/quota, public posting, destructive actions, or AI/user-decision boundaries.
+
+## Target-Output Prompt
+
+Before editing, fill this compact map:
+
+| Candidate rule | Evidence source | Design | Web | App | Testing | Product workflow | Extraction workflow |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Rule in one sentence | Figma node/code path/review | update/skip reason | update/skip reason | update/skip reason | update/skip reason | update/skip reason | update/skip reason |
+
+If a candidate rule has no owner, it is probably a source note, not a skill rule.