@ccoalm/ccl-skills 0.6.2 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/dist/assets/marketplace/plugins/ccl-skills/hooks/hooks.json +11 -0
- package/dist/assets/marketplace/plugins/ccl-skills/hooks/remind-unverified-cli-flag.sh +309 -0
- package/dist/assets/marketplace/plugins/ccl-skills/hooks/test_remind_unverified_cli_flag.sh +483 -0
- package/dist/assets/marketplace/plugins/ccl-skills/packages/opencode-plugin/ccl-skills.ts +5 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/app-cross-platform-dev/SKILL.md +10 -8
- package/dist/assets/marketplace/plugins/ccl-skills/skills/app-cross-platform-dev/references/mobile-quality-release.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/SKILL.md +16 -17
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/references/client-routing.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/references/staged-review-contract.md +195 -7
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/references/timeout-auth-and-capabilities.md +3 -3
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/claude_review.sh +13 -5
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/codex_review.sh +9 -3
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/kimi_review.sh +9 -3
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/normalize_review_timeout.sh +22 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/opencode_review.sh +9 -3
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/review_gate.py +1540 -129
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/test_claude_review_probe.sh +8 -3
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/test_review_client_compat.py +76 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/test_review_gate.sh +1858 -3
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/test_update_review_plan_intent.sh +789 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/update_review_plan_intent.py +513 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/SKILL.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/architecture-playbook.md +2 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/data-platform-architecture.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/event-driven-architecture.md +14 -11
- package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/multi-tenant-isolation.md +2 -2
- package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/SKILL.md +5 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/SKILL.md +2 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/miniapp-product-dev/SKILL.md +13 -11
- package/dist/assets/marketplace/plugins/ccl-skills/skills/nodejs-service-dev/SKILL.md +64 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/nodejs-service-dev/agents/openai.yaml +4 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/nodejs-service-dev/references/async-lifecycle-and-performance.md +72 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/nodejs-service-dev/references/runtime-and-project-contract.md +58 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/nodejs-service-dev/references/source-map.md +41 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/nodejs-service-dev/references/verification-diagnostics-and-security.md +63 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-observability/SKILL.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-observability/references/sli-slo-design.md +25 -9
- package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-observability/references/source-register.md +1 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-release-engineering/SKILL.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-release-engineering/references/promotion-gate-and-review.md +16 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-release-engineering/references/secret-and-config-management.md +7 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-service-connectivity/references/retry-timeout-circuit-breaker.md +11 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-rd-workflow/SKILL.md +8 -10
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-rd-workflow/references/design-routing-and-readiness.md +10 -14
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-rd-workflow/references/verify-developer-experience.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/SKILL.md +135 -86
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/behavioral-aesthetic-logic.md +66 -80
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/delivery-contract.md +275 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/design-execution-checklist.md +88 -214
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/design-impl-naming-and-versioning.md +2 -2
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/design-intake-and-acceptance.md +10 -8
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/design-system-source-of-truth.md +4 -5
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/external-ui-ux-quality-benchmarks.md +112 -95
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/frontend-code-evidence-map.md +30 -21
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/interaction-design-patterns.md +22 -3
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/layout-recipes-and-screenshot-acceptance.md +20 -17
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/multi-project-token-consistency.md +7 -9
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/multi-stack-strategy.md +14 -10
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/operational-processing-workflows.md +2 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/platform-mobile-patterns.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/product-lifecycle-acceptance-and-iteration.md +9 -6
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/product-surface-patterns.md +3 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/source-map.md +37 -10
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/tokens-and-components.md +7 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/ui-ux-audit.md +8 -5
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/ui-ux-design-development.md +16 -5
- package/dist/assets/marketplace/plugins/ccl-skills/skills/product-ui-ux-design/references/visual-craft.md +4 -2
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/SKILL.md +5 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/architecture-playbook.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/audit-history-architecture.md +31 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/data-platform-architecture.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/event-driven-architecture.md +7 -4
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/multi-tenant-isolation.md +2 -2
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/notification-architecture.md +28 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/packaging-runtime-readiness.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/replay-comparison-architecture.md +28 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-architecture/references/workflow-state-architecture.md +39 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/SKILL.md +10 -7
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/ai-service-wiring-patterns.md +8 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/audit-history-patterns.md +29 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/background-job-patterns.md +16 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/batch-and-artifact-patterns.md +25 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/notification-patterns.md +40 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/public-api-security-patterns.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/replay-comparison-patterns.md +30 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/state-machine-task-patterns.md +48 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/python-service-dev/references/testing-and-quality-patterns.md +10 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/release-coordination/SKILL.md +2 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/SKILL.md +4 -4
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/coverage-exhaustion-traps.md +45 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/dual-track-review-gate.md +142 -4
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/external-practice-controls.md +21 -2
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/extraction-quickstart.md +11 -9
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/firing-point-placement.md +8 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/parallel-stack-references-pattern.md +5 -4
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/r0-leakage-audit.md +102 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/source-register.md +69 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/source-to-skill-extraction.md +10 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/uiux-judgment-extraction.md +6 -6
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/validation-and-landing.md +4 -3
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/check-ccl-skills.sh +93 -2
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/check-parallel-stack-parity.sh +119 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/extraction_review_gate.sh +22 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/impact-chain-gate.rb +49 -4
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/obligation-ledger.py +2748 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/register-firing-path-resolution.rb +20 -5
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/shared_git_surface_gate.py +1142 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_check_ccl_parallel_stack_parity.sh +183 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_check_ccl_regressions.sh +19 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_check_ccl_skill_catalog.sh +41 -4
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_ci_checkout_ref_binding.sh +120 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_entrypoint_domain_scan_terms.sh +82 -8
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_extraction_review_gate.sh +336 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_impact_chain_self_adjudication.sh +82 -10
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_obligation_ledger.sh +1416 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_obligation_ledger_repo_audit.sh +57 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_register_firing_path_wiring.sh +141 -4
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_routing_pointer_integrity.sh +3 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_shared_git_surface_gate.sh +1696 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_uiux_delivery_contract.sh +2117 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_uiux_loading_budget.sh +316 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_validate_extraction_review_state.sh +1176 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/test_validate_skill_cross_refs.sh +31 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/validate-skill.sh +9 -4
- package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/scripts/validate_extraction_review_state.py +980 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/terminal-cli-dev/SKILL.md +9 -6
- package/dist/assets/marketplace/plugins/ccl-skills/skills/testing-strategy/SKILL.md +11 -11
- package/dist/assets/marketplace/plugins/ccl-skills/skills/testing-strategy/references/client-runtime-test-matrices.md +10 -2
- package/dist/assets/marketplace/plugins/ccl-skills/skills/testing-strategy/references/fitness-functions.md +16 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/testing-strategy/references/scenario-testing.md +1 -1
- package/dist/assets/marketplace/plugins/ccl-skills/skills/testing-strategy/references/test-code-authoring-patterns.md +16 -5
- package/dist/assets/marketplace/plugins/ccl-skills/skills/tighten-doc/SKILL.md +5 -3
- package/dist/assets/marketplace/plugins/ccl-skills/skills/tighten-doc/references/delivery-face-closeout.md +16 -6
- package/dist/assets/marketplace/plugins/ccl-skills/skills/tighten-doc/references/self-benchmark-baseline.md +37 -0
- package/dist/assets/marketplace/plugins/ccl-skills/skills/web-react-dev/SKILL.md +7 -5
- package/dist/assets/marketplace/plugins/ccl-skills/skills/web-react-dev/references/complex-workspace-patterns.md +1 -1
- package/dist/assets/release.json +275 -105
- package/package.json +1 -1
|
@@ -1,214 +1,88 @@
|
|
|
1
|
-
# Design Execution
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
-
|
|
76
|
-
-
|
|
77
|
-
-
|
|
78
|
-
-
|
|
79
|
-
-
|
|
80
|
-
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
Do not make consumer discovery pages look like internal operations software.
|
|
91
|
-
|
|
92
|
-
## 3.5 Required Design Checkpoint
|
|
93
|
-
|
|
94
|
-
Before implementing or approving any visible UI change, write a compact checkpoint that can be tested against the final screen:
|
|
95
|
-
|
|
96
|
-
- Surface type: mobile consumer, web consumer, web operational, or shared system.
|
|
97
|
-
- Density mode: consumer relaxed, productive compact, or hybrid.
|
|
98
|
-
- 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):
|
|
99
|
-
- 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.
|
|
100
|
-
- 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.
|
|
101
|
-
- 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.
|
|
102
|
-
- 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`).
|
|
103
|
-
- 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.
|
|
104
|
-
- 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.
|
|
105
|
-
- Primary workflow: the shortest successful path and the main return loop.
|
|
106
|
-
- Human logic: user intent in the next 10 seconds, likely anxiety/friction, attention order, motivation to continue, and trust concern.
|
|
107
|
-
- Aesthetic logic: intended mood, visual focus, density rhythm, contrast role, material treatment, and which details should feel restrained versus expressive.
|
|
108
|
-
- 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.
|
|
109
|
-
- 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.
|
|
110
|
-
- Behavioral logic: duplicate action protection, waiting feedback, disabled reasons, undo/retry/cancel, interruption recovery, and risk-matched confirmation.
|
|
111
|
-
- 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.
|
|
112
|
-
- Layout structure: navigation/context, input/control region, content/result region, and secondary metadata.
|
|
113
|
-
- Required states: empty, loading/generating, success, failure/retry, disabled/permission, long-content, and narrow-width behavior where relevant.
|
|
114
|
-
- Trust boundary: generated content, publish/save limits, source/context/cost/model metadata, and any action that must not be implied.
|
|
115
|
-
- Visual acceptance: hierarchy, spacing, component fit, copy tone, no nested-card clutter, no generic dump of fields, and no text overflow.
|
|
116
|
-
- 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.
|
|
117
|
-
- Recipe: choose one concrete recipe from `layout-recipes-and-screenshot-acceptance.md` before drawing or coding.
|
|
118
|
-
- 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.
|
|
119
|
-
|
|
120
|
-
Run the checkpoint in this order so it changes the result, not just the wording:
|
|
121
|
-
|
|
122
|
-
1. Aesthetic logic: decide layers, white space, density, alignment, rhythm, color weight, radius/shadow restraint, and visual focus around the primary task.
|
|
123
|
-
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.
|
|
124
|
-
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.
|
|
125
|
-
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.
|
|
126
|
-
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.
|
|
127
|
-
|
|
128
|
-
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.
|
|
129
|
-
|
|
130
|
-
## 3.6 Operational Workspace Quality Pattern
|
|
131
|
-
|
|
132
|
-
For admin, operations, moderation, analytics, creator-tool, and AI-review pages, use this pattern unless a stronger product-specific design exists:
|
|
133
|
-
|
|
134
|
-
- Header: keep the app shell header factual and restrained. Do not repeat a large inner page title unless it adds task context.
|
|
135
|
-
- Control bar: place scope/filter/mode switches and primary context in a compact horizontal band near the top.
|
|
136
|
-
- Status strip: expose trust boundary, selected scope, permission/state, and mode as small operational facts, not as promotional copy.
|
|
137
|
-
- 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.
|
|
138
|
-
- 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.
|
|
139
|
-
- 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.
|
|
140
|
-
- Review state: make generated title, summary, reasons, model/prompt/cost/status, and source/trust metadata scannable without a table dump.
|
|
141
|
-
- Visual tone: quiet contrast, crisp borders, stable spacing, readable labels, no decorative gradients, no oversized cards, no unused first-screen dead area.
|
|
142
|
-
- 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.
|
|
143
|
-
- 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.
|
|
144
|
-
|
|
145
|
-
## 4. Required States
|
|
146
|
-
|
|
147
|
-
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.
|
|
148
|
-
|
|
149
|
-
Do not ship only the happy path.
|
|
150
|
-
|
|
151
|
-
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.
|
|
152
|
-
|
|
153
|
-
## 5. Component Defaults
|
|
154
|
-
|
|
155
|
-
Mobile:
|
|
156
|
-
|
|
157
|
-
- Navigation: `TabBar`, `NavBar`, `Tabs`, `CapsuleTabs`.
|
|
158
|
-
- Feed/detail: `List`, `Card`, `Avatar`, `Image`, `ImageViewer`, `Tag`, `InfiniteScroll`, `Skeleton`.
|
|
159
|
-
- Creation/AI: `ImageUploader`, `TextArea`, `Input`, `Button`, `ProgressBar`, `Toast`, `Dialog`, `Modal/Bottom sheet`.
|
|
160
|
-
- Comments/actions: `FloatingPanel`, `Popup`, `ActionSheet`, `SwipeAction`.
|
|
161
|
-
- Account/settings: `Form`, `List`, `Switch`, `Picker`, `CheckList`, `Radio`, `PasscodeInput`.
|
|
162
|
-
|
|
163
|
-
Web/Desktop:
|
|
164
|
-
|
|
165
|
-
- Feed/detail: `Card`, `List`, `Avatar`, `Image`, `Tag`, `Badge`, `Tooltip`, `Popover`, `Skeleton`, `Empty`.
|
|
166
|
-
- Creator/moderation/settings: `Form`, `Input`, `Select`, `Switch`, `Radio`, `Checkbox`, `Upload`, `Steps`, `Progress`, `Drawer`, `Modal`.
|
|
167
|
-
- Notifications/feedback: `Message`, `Notification`, `Alert`, `Result`.
|
|
168
|
-
- AI workspace: `Layout`, `Splitter`, side panels, upload, progress, streaming/loading, retry, edit, and result states.
|
|
169
|
-
|
|
170
|
-
## 6. Token Rules
|
|
171
|
-
|
|
172
|
-
- Use design-system semantic tokens before raw colors.
|
|
173
|
-
- Tokens should express a coherent product visual language, not fall back to generic neutral defaults without a reason.
|
|
174
|
-
- Preserve Light/Dark mode support when the surface supports theming.
|
|
175
|
-
- Use mobile 4/8/12 radius roles for mobile; use desktop 2/4/6/8/12/16 radius roles for web.
|
|
176
|
-
- Use desktop Default mode for consumer web readability; use Compact mode for dense tools.
|
|
177
|
-
- Do not invent one-off spacing, color, radius, or font rules unless the product requirement clearly needs a new token.
|
|
178
|
-
|
|
179
|
-
## 7. UI Copy Guardrails
|
|
180
|
-
|
|
181
|
-
**A. Domain / product copy**:
|
|
182
|
-
- Do not copy old source domain words into the new product UI.
|
|
183
|
-
- 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.
|
|
184
|
-
- Keep destructive copy explicit: delete, report, block, publish publicly, leave community, discard draft.
|
|
185
|
-
- Empty states should invite the next action, not just say no data.
|
|
186
|
-
|
|
187
|
-
**B. Microcopy structural rules**(reviewer 可直接 block 不满足的 PR):
|
|
188
|
-
- **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`。
|
|
189
|
-
- **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)。
|
|
190
|
-
- **Disabled control**:默认必有原因(tooltip / inline helper / 旁边一句话)+ 启用条件,让用户知道下一步。**例外**:unavailable by policy / permission / security 且暴露条件不安全 → **隐藏 control** 或给通用 permission 解释(不暴露具体策略);不存在"恒不可启用"且只剩 disabled 状态的 control(应直接隐藏)。
|
|
191
|
-
- **Success / confirmation 必具体**:说清成功了什么 + 如适用给下一步。`Message sent to alice@example.com — view in Sent` 而非 `Success` / `Done` / `OK`。
|
|
192
|
-
- **Voice consistency**(可枚举的 reviewer 检查项,不空喊):(a) 无内部代号 / 项目代号 / 服务名出现在用户文案;(b) 同一动作 / 对象不混用术语(如不同页面别一处叫 "send"、一处叫 "submit"、一处叫 "post");(c) 无未解释 jargon;(d) 无翻译腔(直译机翻味);(e) 时态 / 人称 / 大小写统一。
|
|
193
|
-
|
|
194
|
-
## 8. Review Checklist
|
|
195
|
-
|
|
196
|
-
Before calling a design or implementation complete, verify:
|
|
197
|
-
|
|
198
|
-
- The screen supports the primary product loop: discover/enter -> inspect -> act -> confirm -> recover/return.
|
|
199
|
-
- Main action and secondary actions have proper hierarchy.
|
|
200
|
-
- 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.
|
|
201
|
-
- Aesthetic logic passes `behavioral-aesthetic-logic.md`: mood, rhythm, contrast, material treatment, and delight support the product purpose.
|
|
202
|
-
- 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.
|
|
203
|
-
- Long names, long posts, badges, tags, and metadata do not break layout.
|
|
204
|
-
- Mobile keyboard/safe-area states are covered where relevant.
|
|
205
|
-
- Web narrow-width behavior collapses secondary panels before damaging content readability.
|
|
206
|
-
- AI states include generating, retry, edit, source/citation where relevant, and failure handling.
|
|
207
|
-
- Trust/safety states are visible and understandable.
|
|
208
|
-
- Trust-sensitive AI/data features expose source/context, permission state, recovery, and observable request/task outcomes.
|
|
209
|
-
- Visual polish passes `visual-craft.md` anti-slop and brand-consistency checks.
|
|
210
|
-
- Screenshot acceptance passes `layout-recipes-and-screenshot-acceptance.md` with realistic long text, no data, partial data, and error data.
|
|
211
|
-
- 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.
|
|
212
|
-
- 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.
|
|
213
|
-
- Component choices follow this skill and existing codebase primitives.
|
|
214
|
-
- Launch readiness and iteration risks pass `product-lifecycle-acceptance-and-iteration.md` when the work is close to release or already shipped.
|
|
1
|
+
# Design Execution Router
|
|
2
|
+
|
|
3
|
+
For runtime work, choose one delivery-depth profile, then add every work-mode and risk lens whose trigger is present. Load the union of their references; one lens never cancels another. Delivery depth is ordered `systemic redesign → new/reshaped screen → narrow visible change → copy-only`. Every work mode below is orthogonal to delivery depth and to the other modes: a source-led systemic redesign or a shared-system redesign loads both sets; a narrow implementation review loads design-to-code plus audit/review; a code-evidence audit with naming drift loads source/code evidence plus naming/version synchronization; a same-stack theme audit loads same-stack multi-project even though no stacks differ; a cross-stack redesign loads its delivery profile plus multi-stack. A source-only audit with no requested runtime slice may omit delivery depth and stop at the source-only boundary in `delivery-contract.md`.
|
|
4
|
+
|
|
5
|
+
The core workflow and state taxonomy are already in the skill entrypoint. This router is conditional context, not an always-loaded prerequisite. A runtime-visible task can enter `delivery-contract.md` directly; an unambiguous common route can enter its named reference directly. Load this router when delivery depth must be composed with specialized work-mode, platform, risk, or evidence lenses. No focused reference is always loaded. Extra context must earn its cost by changing a decision, owner, evidence layer, or acceptance criterion.
|
|
6
|
+
|
|
7
|
+
## Delivery-depth profiles
|
|
8
|
+
|
|
9
|
+
| Profile | Use when | Required references | Deliverable |
|
|
10
|
+
| --- | --- | --- | --- |
|
|
11
|
+
| Copy-only | Same component, rendering slot, or output field and behavior; no hierarchy, layout, state, interaction, navigation, or component-semantics change | `delivery-contract.md` copy-only path | Lightweight owner/evidence record plus extent/localization check |
|
|
12
|
+
| Narrow visible change | Local polish, state/copy fix, or bounded review without structural redesign | `delivery-contract.md`; one focused craft/interaction reference | Observation → risk → change → evidence |
|
|
13
|
+
| New or reshaped screen | New screen or material change to grouping, hierarchy, navigation, component semantics, or visual direction | `delivery-contract.md`, `design-intake-and-acceptance.md`, `behavioral-aesthetic-logic.md`, `visual-craft.md` | Context brief, state/flow, direction, criteria, owner handoff |
|
|
14
|
+
| Systemic redesign | Multiple surfaces, declared redesign/restyle, continuation from a redesigned surface, or a `design-judgment`/`mixed` rejected-surface recovery | New/reshaped set plus `layout-recipes-and-screenshot-acceptance.md`, relevant platform reference, and `ui-ux-audit.md` | Per-surface records following the canonical five-step order, cross-surface consistency, rendered verdict loop |
|
|
15
|
+
|
|
16
|
+
## Composable work-mode lenses
|
|
17
|
+
|
|
18
|
+
Select zero or more and union their required references with the delivery-depth set.
|
|
19
|
+
|
|
20
|
+
| Work mode | Use when | Required references | Deliverable |
|
|
21
|
+
| --- | --- | --- | --- |
|
|
22
|
+
| Shared system | Tokens, components, themes, state catalogs, or packages consumed by more than one surface/stack | `delivery-contract.md`, `tokens-and-components.md`, `design-system-source-of-truth.md`; compose with same-stack multi-project or multi-stack when their triggers apply | Consumer inventory, semantic contract, migration and evidence matrix |
|
|
23
|
+
| Source/code evidence | Auditing, classifying, or refreshing rules from Figma, code, screenshots, or another source corpus; inspecting local frontend implementation evidence, reusable primitives, source boundaries, or build/launch scripts | `source-map.md`, `frontend-code-evidence-map.md`, and [`two-source-extraction-pattern.md`](../../skill-extraction-workflow/references/two-source-extraction-pattern.md) when design+code are paired | Source classification, implementation-evidence map, coverage, contradictions, keep/merge/discard decisions |
|
|
24
|
+
| Design-to-code | Applying design decisions to client code, mapping a source/component/token to implementation, or choosing implementation primitives for a visible slice | `ui-ux-design-development.md` plus the affected client owner skill | Source-to-target translation, primitive/component mapping, state/adaptation implementation notes, and owner evidence plan |
|
|
25
|
+
| Audit/review | UI/UX audit, design walkthrough or acceptance, implementation review, code/design comparison, or usability, accessibility, responsive QA at any delivery depth | `ui-ux-audit.md`; add the triggered craft, interaction, platform, and external-authority lenses below | Findings ordered by user impact with evidence, correction, strengths, and scope limits |
|
|
26
|
+
| Naming/version synchronization | Figma↔code naming drift, deciding which `Foo`/`FooV2` artifact is active, retiring an in-flight version stamp, or maintaining the design-code terminology glossary | `design-impl-naming-and-versioning.md` | Active implementation/source resolution, migration/retirement decision, glossary evidence and recheck trigger |
|
|
27
|
+
| Same-stack multi-project | Multiple subprojects on the same end/stack share a brand or theme, need a shared theme module, or may drift to vendor defaults | `multi-project-token-consistency.md`; add multi-stack only if the same framework also spans different ends | Subproject inventory, canonical token/theme source, import/drift audit, migration and evidence matrix |
|
|
28
|
+
| Multi-stack | A feature or design system spans multiple client stacks or a composite host; a stack/UI-kit outlier; native-shell↔web-content ownership; or the same framework spans different ends | `multi-stack-strategy.md`; also load `multi-project-token-consistency.md` when the same framework spans different ends and shares brand/theme infrastructure | Per-stack and per-layer owner/consumer map, surface contract, divergence/retirement decision, and evidence matrix |
|
|
29
|
+
|
|
30
|
+
Do not downgrade a declared redesign to narrow polish because the code diff is small. Do not upgrade copy-only work because the surrounding screen is complex; use the trigger actually changed.
|
|
31
|
+
|
|
32
|
+
## Risk lenses
|
|
33
|
+
|
|
34
|
+
Load a lens only when its trigger is present.
|
|
35
|
+
|
|
36
|
+
| Trigger | Reference |
|
|
37
|
+
| --- | --- |
|
|
38
|
+
| Web/desktop layout, workbench/auth/admin surface, responsive container, browser input | `platform-web-desktop-patterns.md` |
|
|
39
|
+
| Mobile/native/App/app-hosted/H5/WebView, safe area, keyboard, orientation, text scale, gesture | `platform-mobile-patterns.md` |
|
|
40
|
+
| Mini-program host capability or package/platform convention | Keep design acceptance in `delivery-contract.md`; route host mechanics to `miniapp-product-dev` |
|
|
41
|
+
| Terminal/TUI grid, ANSI/color fallback, PTY, resize, scrollback, selection | Keep design acceptance in `delivery-contract.md`; route mechanics to `terminal-cli-dev` |
|
|
42
|
+
| Operational/admin/moderation/AI-review workspace; capture, upload/import, queue, progress monitoring, assignment/ownership, exception handling, or quality-control workflow | `operational-processing-workflows.md` |
|
|
43
|
+
| Trust-sensitive AI, finance/data, permission, provenance/citation, upload, analytics, moderation decision, long-running workflow, or instrumentation | `trust-sensitive-ai-and-data-patterns.md` |
|
|
44
|
+
| Analytics, charts, comparison, drill-down, metric explanation, creator/topic health, retention, or AI-quality metric | `analytics-visualization-interactions.md` |
|
|
45
|
+
| Complex creation, upload/import, AI draft extraction, structured editing, matching/manual correction, preview/publish/export flow | `complex-creation-interactions.md` |
|
|
46
|
+
| Resource/cloud-drive inventory, upload, batch action, media/template/content-pack center, saved prompt, knowledge source, sharing, governance, or lifecycle | `resource-management-interactions.md` |
|
|
47
|
+
| Community/social/feed/creator/topic/profile/notification/moderation/AI-social product surface | `scenario-community-patterns.md` or the matching section of `product-surface-patterns.md` |
|
|
48
|
+
| Detailed interaction, feedback strength, error/recovery, gesture, generated state, motion, or shortcut behavior | `interaction-design-patterns.md` |
|
|
49
|
+
| Attention, motivation, perceived effort, trust psychology, habit loop, or behavioral/aesthetic judgment | `behavioral-aesthetic-logic.md` |
|
|
50
|
+
| Visual polish, brand feel, anti-slop, typography/hierarchy, iconography, or material treatment | `visual-craft.md` |
|
|
51
|
+
| Layout recipe, component density, workbench structure, empty/loading/error geometry, or screenshot/render acceptance | `layout-recipes-and-screenshot-acceptance.md` |
|
|
52
|
+
| Design-system source authority, third-party mirror detection, brand-token ownership, or wrong design-source comments in code/theme files | `design-system-source-of-truth.md` |
|
|
53
|
+
| Generic surface/loop taxonomy, account/settings, decision/review, AI-assisted or workflow-extension pattern, or no focused scenario lens fits | `product-surface-patterns.md` |
|
|
54
|
+
| External theory, WCAG, platform recommendation, benchmark claim | `external-ui-ux-quality-benchmarks.md` |
|
|
55
|
+
| Launch/post-launch measurement and iteration | `product-lifecycle-acceptance-and-iteration.md` |
|
|
56
|
+
|
|
57
|
+
## Decision pass
|
|
58
|
+
|
|
59
|
+
Before handing off implementation, confirm that the design record answers these questions:
|
|
60
|
+
|
|
61
|
+
1. Who is doing which representative task, under what constraints?
|
|
62
|
+
2. What observation creates which user/task risk?
|
|
63
|
+
3. What information hierarchy, flow, state, and recovery behavior addresses that risk?
|
|
64
|
+
4. Which details are specified by a current source, which are design freedom, and which change product behavior?
|
|
65
|
+
5. What happens at narrow/large sizes, long content, alternate input, text scaling, and relevant accessibility states?
|
|
66
|
+
6. Which criterion is automatic, rendered/device, independent design judgment, user-task evidence, or production evidence?
|
|
67
|
+
7. Which producer, test, and client owners must return which evidence before a verdict?
|
|
68
|
+
|
|
69
|
+
Use `delivery-contract.md` for the field schema and completion states. Do not restate those fields here.
|
|
70
|
+
|
|
71
|
+
## Design quality checks
|
|
72
|
+
|
|
73
|
+
Apply the checks relevant to the chosen delivery depth and every triggered lens:
|
|
74
|
+
|
|
75
|
+
- The most prominent content/action matches the representative task and consequence.
|
|
76
|
+
- Required context, current state, available actions, and result/recovery remain visible when needed. For each applicable risk, decide what users may repeat, misclick, wait for, abandon, undo, retry, cancel, or recover after interruption, and provide visible state or control; do not force users to remember hidden state across route or modal transitions.
|
|
77
|
+
- States use clear signifiers and event → state → feedback mappings. Animation has a functional purpose and a reduced-motion equivalent.
|
|
78
|
+
- Friction follows consequence. Routine work is not interrupted by defensive confirmation; high-consequence action is not hidden behind transient feedback.
|
|
79
|
+
- The layout adapts from content/container constraints and survives long text, text scaling, intermediate widths, and relevant input modes.
|
|
80
|
+
- Tokens and components express semantic roles and full states. Existing libraries do not excuse weak hierarchy, missing states, or inaccessible behavior.
|
|
81
|
+
- Examples, stories, catalogs, and design-system docs used as implementation sources conform to the same token, responsive, state, and accessibility rules.
|
|
82
|
+
- Each deterministic gate names its coverage boundary; each conclusion stops at its highest verified evidence rung.
|
|
83
|
+
|
|
84
|
+
## Closeout
|
|
85
|
+
|
|
86
|
+
The design owner records criterion results and the verdict defined in `delivery-contract.md`. A source-level review, heuristic pass, automated check, or screenshot cannot silently stand in for a missing rendered, accessibility, independent-design, user-task, or production layer.
|
|
87
|
+
|
|
88
|
+
Report loaded references with their trigger when the task is large enough to persist a design record. This makes context cost and omitted lenses reviewable without forcing every task to load the corpus.
|
|
@@ -17,7 +17,7 @@ Load this reference when a task crosses the Figma↔code boundary and depends on
|
|
|
17
17
|
- **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.
|
|
18
18
|
- **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.
|
|
19
19
|
- **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.
|
|
20
|
-
- **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
|
|
20
|
+
- **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 follows every affected client owner in `delivery-contract.md`: React web → `web-react-dev`; other web → its installed owner or project convention; native mobile → `app-cross-platform-dev`; mini-app → `miniapp-product-dev`; terminal/TUI → `terminal-cli-dev`; Electron/desktop/TV → its installed owner or fail-closed project convention. 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.
|
|
21
21
|
- **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.
|
|
22
22
|
|
|
23
23
|
## Decision Checklist
|
|
@@ -48,6 +48,6 @@ When you hit a Figma↔code naming mystery:
|
|
|
48
48
|
|
|
49
49
|
## Routing
|
|
50
50
|
|
|
51
|
-
- Code-side enforcement of "no `FooV2` coexists with `Foo` after release N" → `web-react-dev
|
|
51
|
+
- Code-side enforcement of "no `FooV2` coexists with `Foo` after release N" follows every affected client owner in `delivery-contract.md`: React web → `web-react-dev`; Flutter/RN/native mobile → `app-cross-platform-dev`; mini-app → `miniapp-product-dev`; terminal/TUI → `terminal-cli-dev`; other web, Electron shell, desktop, TV, or another runtime → its installed owner or the fail-closed project-convention lookup.
|
|
52
52
|
- Test coverage of both `V1` and `V2` paths while coexistence persists → `testing-strategy`.
|
|
53
53
|
- Glossary maintenance and design-side cleanup of `_verN` / current-marker / date-stamp siblings → stays here (design discipline) plus owner update in the private archive.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Design Intake And Acceptance
|
|
2
2
|
|
|
3
|
-
Use this reference before designing, implementing, or reviewing a concrete product
|
|
3
|
+
Use this reference before designing, implementing, or reviewing a concrete product surface. It supplies design-owned intake and criteria to the five top-level stages in `delivery-contract.md`; it does not replace Test Phase 0, producer/client execution, Test Phase 1, immutable binding, or the design verdict. It adapts product-intent and UX-acceptance practices while staying source-agnostic and excluding source-specific visual themes.
|
|
4
4
|
|
|
5
5
|
## Intake Triage
|
|
6
6
|
|
|
@@ -10,7 +10,7 @@ Clarify these points quickly before making design decisions. Do not over-ask whe
|
|
|
10
10
|
| --- | --- |
|
|
11
11
|
| Product goal | What user behavior should this screen increase: discovery, first participation, creation, retention, trust, or AI-assisted contribution? |
|
|
12
12
|
| User segment | Is the user new, returning, creator, moderator, power user, or casual browser? |
|
|
13
|
-
| Platform |
|
|
13
|
+
| Platform | Which rendered layers are affected: React or other web, H5, native mobile/host, mini-app, ordinary CLI or terminal/TUI, Electron/desktop/TV shell, composite host, or another client? Which installed owner or fail-closed project convention applies to each? |
|
|
14
14
|
| Surface | Is it feed, post detail, creation, onboarding, profile, topic/community, notification, AI workspace, trust/safety, analytics, or settings? |
|
|
15
15
|
| Primary loop | What is the screen's loop: discover -> interact, create -> publish, AI -> refine -> share, report -> review, or notify -> return? |
|
|
16
16
|
| Constraints | Are there known brand, component-library, accessibility, localization, privacy, moderation, or performance constraints? |
|
|
@@ -36,7 +36,7 @@ When applying or refreshing this skill:
|
|
|
36
36
|
|
|
37
37
|
## Deliverable Types
|
|
38
38
|
|
|
39
|
-
Choose the smallest deliverable that satisfies the task.
|
|
39
|
+
Choose the smallest design-owned deliverable that satisfies the task. Runtime implementation or acceptance still follows the applicable full or lightweight record and complete design/test/producer/client owner set in `delivery-contract.md`.
|
|
40
40
|
|
|
41
41
|
### UI Concept + Layout
|
|
42
42
|
|
|
@@ -62,7 +62,7 @@ Include:
|
|
|
62
62
|
- Tokens for color, typography, spacing, radius, shadow, and mode where relevant.
|
|
63
63
|
- Component selection and variants.
|
|
64
64
|
- Component states: default, hover, active, disabled, selected, loading, error, success, empty, and destructive.
|
|
65
|
-
-
|
|
65
|
+
- Per-affected-client differences and shared semantics across React/other web, H5, native, mini-app, terminal/CLI/TUI, Electron/desktop/TV, and composite-host layers.
|
|
66
66
|
|
|
67
67
|
### Implementation Plan
|
|
68
68
|
|
|
@@ -72,6 +72,7 @@ Include:
|
|
|
72
72
|
- Reusable components and local primitives to use first.
|
|
73
73
|
- Data/state requirements for the UI.
|
|
74
74
|
- Acceptance checks and visual QA steps.
|
|
75
|
+
- The changed producer owners, affected client owners, Test Phase 0 handoff, and complete design/test/producer/client binding/return plan required by `delivery-contract.md`.
|
|
75
76
|
|
|
76
77
|
### Design Review
|
|
77
78
|
|
|
@@ -85,7 +86,7 @@ Lead with issues, then recommended fixes:
|
|
|
85
86
|
|
|
86
87
|
## Acceptance Standards
|
|
87
88
|
|
|
88
|
-
|
|
89
|
+
These checks become design criteria in the applicable full or lightweight record. Passing them locally is not completion: only the complete five-stage contract, immutable design/test/producer/client binding set, and allowed verdict/next-state pair can close a runtime-visible slice.
|
|
89
90
|
|
|
90
91
|
### Product Fit
|
|
91
92
|
|
|
@@ -106,8 +107,9 @@ A design or implementation is not complete until it passes these checks.
|
|
|
106
107
|
- Uses existing design-system tokens and components before inventing new styling.
|
|
107
108
|
- Has a coherent visual direction and avoids generic AI-template aesthetics; see `visual-craft.md`.
|
|
108
109
|
- Maintains clear hierarchy between content, metadata, actions, and system feedback.
|
|
109
|
-
- Mobile surfaces respect thumb reach, keyboard, safe area, and bottom-sheet behavior.
|
|
110
|
-
- Web surfaces collapse secondary panels before harming core content readability.
|
|
110
|
+
- Mobile/native surfaces respect thumb reach, keyboard, safe area, orientation, text scaling, and bottom-sheet behavior.
|
|
111
|
+
- React/other Web surfaces collapse secondary panels before harming core content readability.
|
|
112
|
+
- Mini-app, terminal/CLI/TUI, Electron/desktop/TV, composite-host, and other clients apply their owner-specific host, input, geometry, fallback, bridge, and rendered-evidence criteria; absence from the Web/mobile examples is not `not-applicable` proof.
|
|
111
113
|
- Text fits in buttons, tabs, cards, sidebars, and compact controls.
|
|
112
114
|
|
|
113
115
|
### Trust, Safety, And AI
|
|
@@ -121,7 +123,7 @@ A design or implementation is not complete until it passes these checks.
|
|
|
121
123
|
|
|
122
124
|
- Interactive controls have labels, keyboard/focus states where applicable, and enough hit area.
|
|
123
125
|
- Color contrast, disabled state, error state, and loading state remain readable.
|
|
124
|
-
- The design works
|
|
126
|
+
- The design works across the supported sizes, host modes, input/capability modes, and adaptation matrix of every affected rendered layer.
|
|
125
127
|
- Motion or animation does not block task completion and can degrade gracefully.
|
|
126
128
|
|
|
127
129
|
## Anti-Patterns
|
|
@@ -12,7 +12,7 @@ Load this reference when working on token decisions, theme files, design-system
|
|
|
12
12
|
## Rules
|
|
13
13
|
|
|
14
14
|
- 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.
|
|
15
|
-
- A
|
|
15
|
+
- A design portfolio that spans multiple rendered stacks must inventory React and other web, H5, native mobile, mini-app, terminal/TUI, Electron/desktop, TV, and any additional client. Assign each stack to one canonical design-system source or an explicit shared-source decision with stack-specific variants and evidence; do not infer that a desktop/mobile pair covers the rest. Business-module files should not carry their own token/style definitions; they should reference the applicable canonical source only.
|
|
16
16
|
- 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.
|
|
17
17
|
- 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.
|
|
18
18
|
- 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.
|
|
@@ -64,7 +64,7 @@ When starting work on tokens/theme/design-system:
|
|
|
64
64
|
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.
|
|
65
65
|
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.
|
|
66
66
|
2. For each `A1` file, verify whether it is team-authored or third-party-mirror via page-name pattern.
|
|
67
|
-
3. For the active `A1` files,
|
|
67
|
+
3. For the active `A1` files, map every rendered stack in the authoritative consumer inventory—React and other web, H5, native mobile, mini-app, terminal/TUI, Electron/desktop, TV, and any additional client—to exactly one canonical source or one recorded shared-source decision. If multiple sources compete for a stack, choose one as canonical and demote the others to `class B` until merged.
|
|
68
68
|
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.
|
|
69
69
|
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.
|
|
70
70
|
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.
|
|
@@ -92,6 +92,5 @@ This fallback exists because the standard rules above require a Figma file inven
|
|
|
92
92
|
|
|
93
93
|
## Routing
|
|
94
94
|
|
|
95
|
-
- Implementation enforcement of the comment-pointer rule and the `styles_count == 0` audit → `web-react-dev`
|
|
96
|
-
-
|
|
97
|
-
- Mini-program stack-specific design-system selection → `miniapp-product-dev`.
|
|
95
|
+
- Implementation enforcement of the comment-pointer rule and the `styles_count == 0` audit follows every affected client owner in `delivery-contract.md`: React web → `web-react-dev`; other web → its installed owner or project convention; native mobile → `app-cross-platform-dev`; mini-program → `miniapp-product-dev`; terminal/TUI → `terminal-cli-dev`; Electron/desktop/TV → its installed owner or the fail-closed project-convention lookup. The check must inspect the source shape actually used by that stack; a Web-only tool is not evidence for a native, terminal, or desktop client.
|
|
96
|
+
- Acceptance layer and cross-client evidence sufficiency → `testing-strategy`.
|