Product Composer Skill

English | 简体中文

Positioning

In 15 seconds: Product Composer is a routing, strategy, and verification skill for UI work where visual direction materially affects the result. It selects a bounded creative workflow, keeps decisions in one Design Contract, compiles inspectable image requests, scans implementation defaults, and verifies claims against evidence.

It is not an autonomous agent runtime. It does not schedule agents, own a model loop, or execute image/UI tools by itself. A compatible host reads SKILL.md, invokes the appropriate tools, and remains responsible for execution.

Runtime authority: root SKILL.md only.

This README is the human-facing map; it does not redefine the runtime contract.

The problem

UI generation often jumps directly from a vague adjective to components. That loses the causal chain between product intent, visual direction, assets, implementation, and verification. Product Composer makes that chain explicit:

• route the task before opening specialist guidance
• preserve one source of truth across stages
• separate creative direction from implementation authorization
• turn image intent into a deterministic adapter request
• detect common generic-default patterns without treating heuristics as proof
• keep maturity and parity claims proportional to evidence

When To Use

Use Product Composer for a new or substantially redesigned product, brand, or hybrid surface when one or more of these materially change the result:

• art direction, visual thesis, composition, typography, or motion
• a coherent image world or asset family
• cultural context or a supplied visual reference
• a frontier interaction or data-dense product surface
• rendered repair driven by observed evidence
• a visual-parity or artifact-maturity decision

Do not activate it for a small mechanical UI edit, non-visual engineering work, routine construction inside an already settled design system, document translation, or an audit that does not authorize redesign.

Quick start

1. Make this repository available to a skill-compatible host and use SKILL.md as the entry point.
2. Describe the product, audience, task outcome, target surface, constraints, and any accepted references.
3. Let the skill select one Phase, one Surface, and only the Modifiers that change behavior or evidence.
4. Review the resulting Design Contract before implementation or generation starts.
5. Run the repository validation commands below before changing the skill itself.

To inspect the bundled implementation case without a frontend toolchain:

python3 examples/cases/dunhuang-museum-hero/serve.py --port 4173

Then open http://127.0.0.1:4173/. The archive is a static, multi-route implementation reference; it is not an official museum website or a reusable template.

Runtime Model

Route first, then load the smallest owner set

Every task selects exactly one value on the first two axes and adds only behavior-changing Modifiers:

The route opens focused owner references rather than loading the whole knowledge base. Normal active-reference windows are capped at three documents; the single documented four-owner exception is defined in SKILL.md.

One Design Contract across the workflow

All owners read and update the same Design Contract. It records the route, complete DirectionContract projection, experience architecture, workflow and states, truth/provenance, artifact target, functional delta, locked decisions, and acceptance checks. Stage handoffs preserve the complete record rather than inventing parallel state.

request
  -> Phase / Surface / Modifier route
  -> focused owner references
  -> shared Design Contract
  -> direction or authorized vertical slice
  -> rendered evidence
  -> Verify or one-axis Repair

Direction-only Explore stops at an accepted direction. Implementation-authorized work completes the Functional delta before the first slice. Repair changes one observed causal axis at a time. validation-only work reports evidence and gaps without silently mutating the artifact.

Prompt Compiler

scripts/compile-image-prompt.py validates prompt-contract 2.0 inputs, distinguishes visual assets from UI mockup references, checks mount geometry against the consuming layout region, enforces a single exploration axis, and emits deterministic text or JSON adapter requests.

It compiles requests for an external prompt engine or UI-mockup adapter; it does not generate images itself.

UI Pattern Scanner

scripts/ui-pattern-scan.mjs walks JavaScript/TypeScript-style source trees and reports known generic-default signals in a stable JSON schema. Findings are prompts for human or agent inspection, not a visual-quality verdict.

What The Skill Preserves

Product Composer preserves product correctness, local conventions, content and asset truth, the selected visual thesis, image-family continuity, accessible state behavior, locked implementation decisions, and traceable verification.

It also keeps artifact-maturity labels evidence-gated:

• recipe: complete but non-runnable direction metadata and acceptance checks
• preview: a rendered view for a named scenario, state, and viewport, with limitations stated
• runnable starter: an executable entry point with behavioral evidence for its declared basic interaction
• tested golden: a named scenario whose applicable behavioral and rendered checks have passed
• template: a reusable package with a manifest, entry point, replaceable-input contract, provenance, smoke test, and rendered evidence

These are claim levels, not a list of artifacts shipped here. The package does not claim to include a runnable starter, tested golden, or production template.

Evidence in this repository

• 127 Python tests cover route contracts, owner windows, prompt compilation, provenance, dependency boundaries, reference integrity, and the Dunhuang static distribution.
• 19 Node tests cover scanner matching, ordering, path handling, JSON output, large output, strict mode, and controlled filesystem errors.
• examples/cases/dunhuang-museum-hero/ is a dependency-free compiled multi-route case with asset hashes, route fallback checks, and third-party notices.
• evals/source-ledger.json is repository provenance evidence; it is not a runtime reference.
• evals/discovery-scenarios.md records activation boundaries.
• evals/routing-scenarios.md records route and initial reference-window expectations.

Current limitations

• The skill depends on a host agent and its available tools; it is not a standalone UI builder.
• The Prompt Compiler validates and adapts contracts but does not call an image model.
• Scanner findings are lexical heuristics and require confirmation against the Design Contract and rendered UI.
• Structural/package evidence proves only contract validity; visual and runtime claims still require matching rendered and behavioral evidence.
• The Dunhuang case preserves a final compiled distribution, not its original source workbench, design history, or a general-purpose starter.

Package Map

SKILL.md                         runtime route and hard gates
references/                     focused Phase / Surface / Modifier owners
scripts/compile-image-prompt.py deterministic prompt-contract compiler
scripts/ui-pattern-scan.mjs     optional generic-pattern scanner
tests/                          Python and Node contract tests
evals/                          discovery, routing, and provenance evidence
examples/scenarios/             compact routing examples
examples/cases/                 final implementation reference archive
agents/openai.yaml              host-facing metadata

examples/scenarios/product-composer-routing.md shows two compact routes without copying the full owner matrix.

Roadmap

• add small, versioned prompt-contract examples for both visual-asset and UI-reference modes
• publish more evidence-complete cases across Product, Brand, and Hybrid surfaces
• add rendered scanner fixtures that connect lexical findings to reviewed visual outcomes
• keep the runtime contract small while expanding independently testable adapters

Scanner

Run the optional scanner against a source directory:

node scripts/ui-pattern-scan.mjs ./src

By default, warnings are returned in JSON with exit code 0. Use strict mode only when warnings should fail automation:

node scripts/ui-pattern-scan.mjs --strict ./src

Always confirm a finding against the active contract and the rendered result.

Validation

From the repository root:

python3 -B "$HOME/.codex/skills/.system/skill-creator/scripts/quick_validate.py" "$PWD"
python3 -B -m unittest discover -s tests -p 'test_*.py' -v
node --test tests/test_scanner.mjs

The current inventory is 127 Python tests plus 19 Node tests. The Python case-server test binds a temporary loopback port; a restricted sandbox may need permission for that local bind.

License

Apache License 2.0. See LICENSE.