soia-design-explorer

This is a public design artifact workflow wrapper layer. It converges the external huashu-design capability into clear inputs, explicit dependency paths, controllable outputs, and reproducible verification; it does not replace product specs or production implementation.

Customer-readable description

What this skill can do

Customer wants	Skill will do	Customer can see
High-fidelity prototype / deck / animation	Collect goals, canvas, content, and assets, then call the upstream workflow to generate step by step	Artifact paths, previews, gaps, and verification evidence
style exploration	Generate 2–4 comparable directions so users don't have to choose blindly from text alone	Direction differences, real visuals, and recommendations with rationale
design review	Tiered review of existing pages or screenshots	Conclusions, severity, and priority fix actions

Not for routine front-end implementation, CSS bug fixes, low-fidelity wireframes, or PRD writing.

How customers use it

Provide:

Delivery type:prototype / deck / animation / style-exploration / review；
Platform and canvas;
Audience, purpose, and success criteria;
Real content and assets;
The user's own brand guidelines (file, URL, or an explicit statement of "none");
Output categories and paths;
huashu-design The explicit installation root path.

When requirements are ambiguous, first offer 2–3 mutually exclusive form options. When brand information is insufficient, use a neutral exploratory direction and mark placeholders; do not guess brand colors from memory.

Dependencies and installation

Install this skill and external dependencies:

npx skills add soia-team/soia-open-skills -g -a '*' -s soia-design-explorer -y
npx skills add alchaincyf/huashu-design -g -y

huashu-design is a third-party external dependency, not maintained or copied by this repository. The upstream public repository is https://github.com/alchaincyf/huashu-design; its README and LICENSE currently state that it has used MIT since 2026-05-14, and it may be used personally or commercially. Before upgrading, the upstream version and license should still be rechecked.

This skill does not scan $HOME to guess the upstream. Each time, the path must be provided via this input, an environment variable, or configuration:

~/.config/soia-skills/soia-open-skills/soia-design/soia-design-explorer/config.yml
SOIA_DESIGN_EXPLORER_CONFIG_FILE=<custom-config-path>
HUASHU_DESIGN_ROOT=<huashu-design-root>

Suggested configuration:

schema_version: 1
env:
  HUASHU_DESIGN_ROOT: "<huashu-design-root>"
  DESIGN_EXPLORER_TEMP_ROOT: "<optional-temp-root>"
  DESIGN_EXPLORER_STATE_ROOT: "<optional-state-root>"

Brand guidelines are not a skill dependency. Customers may provide brand guidelines, logos, color palettes, fonts, screenshots, and copy rules; when not provided, clearly record the gap.

Logs and completion receipt

完成：<产物或评审结果>。

日志摘要：
- type/platform: <类型与画幅>
- upstream: <显式路径与读取的参考，不输出秘密>
- inputs: <品牌/内容/素材完整度>
- created/updated: <产物路径>
- skipped/failed: <数量和原因>

验证：<浏览器、截图、导出打开或交互检查>
问题与下一步：<placeholder、缺素材或无>

Trigger conditions

Create a high-fidelity HTML prototype or interactive demo;
Create HTML slides, animations, presentation video assets, or design variants;
Provide direction recommendations, reviews, or revision suggestions for existing visual drafts;
The user explicitly mentions soia-design-explorer、huashu-design、prototype or “visual direction.”

Boundaries

Outputs are design exploration artifacts or reviews and do not automatically become production code, business contracts, or product specs.
Before modifying existing files, overwriting exports, publishing, or writing remotely, you must preview and obtain confirmation.
Do not load or assume any organization-internal workspace, governance directory, brand skill, or file-writing rules.
The upstream is an independent third-party project; only read files relevant to the current task within the explicit root path, and do not modify third-party skills.

Minimal workflow

Step 1. Lock down the task form

Choose only one primary form at a time:

prototype: Clickable page or flow;
deck: HTML slides or exported presentation deck;
animation: Timeline animation and optional MP4/GIF;
style-exploration: 2–4 comparable visual directions;
review: Structured design review.

Step 2. Check input completeness

Before generating, list available / missing / placeholder：

real copy and data;
logo, product images, screenshots, fonts;
brand guidelines provided by the user;
target platform, aspect ratio and accessibility requirements;
output purpose, audience and success criteria.

If missing assets would significantly affect the result, ask first. When placeholders are allowed, they must be marked in the artifact and in the receipt.

Step 3. Parse and validate upstream

From explicit input,HUASHU_DESIGN_ROOT or configuration, read the root path. If the path is missing, stop and give the installation/configuration command; do not recursively scan the user's home directory to guess the install location.

HUASHU_DESIGN_ROOT="${HUASHU_DESIGN_ROOT:?set explicit huashu-design root}"
test -f "$HUASHU_DESIGN_ROOT/SKILL.md"

First read the upstream SKILL.md, then read its direct references according to the task:

General process and validation:references/workflow.md、references/verification.md；
Review:references/critique-guide.md；
Slides:references/slide-decks.md、references/editable-pptx.md；
Animation:references/animations.md、references/video-export.md；
Style exploration:references/design-styles.md、references/scene-templates.md。

Filenames may change in upstream versions; if a file does not exist, report the actual gap rather than inventing content.

Step 4. Choose the output destination by five categories

Classify first, then write files:

Category	Examples in this skill	Destination
A Temporary	one-off previews, intermediate screenshots, temporary renders	User-specified `DESIGN_EXPLORER_TEMP_ROOT`; otherwise `${TMPDIR}/soia-design-explorer/<slug>/`，`TMPDIR` if unset, ask first
B Audit	records of high-impact actions such as publishing, overwriting, remote writes	User-specified `DESIGN_EXPLORER_STATE_ROOT` or `${XDG_STATE_HOME}/soia-design-explorer/`; if not configured, ask first
C Deliverables	HTML, PPTX, PDF, MP4, GIF, final screenshots	the delivery directory explicitly specified by the user; must not default to writing to cwd or Downloads
D Product feature as log	design records explicitly specified by the target product	obey only the target project's public/local rules; do not create conventions from this skill
E Pure stdout	brief reviews that need no archiving	do not write to disk

Before writing to category C/D or overwriting an existing file, show the absolute target, current state and expected file list. Category A must not masquerade as a final deliverable.

Step 5. Generate and iterate

first make the smallest visible version, then expand;
for style exploration, first produce 2–4 substantially different directions;
for a prototype, first ensure the critical path is clickable, then polish the visuals;
for a review, first give the conclusion and issue severity levels, then repair suggestions;
all brand choices must be evidenced by user assets or citable public brand materials.

Step 6. Validate

Perform at least one validation proportionate to the delivery type:

open in a browser and check key viewports;
Playwright/upstream validation script screenshots;
the exported file opens and the page count/duration matches expectations;
the prototype's key interactions are clickable;
review covers advantages, severity-ordered issues, and the top 3 priority actions.

Only claim checks that were actually run. A preview passing does not equal production implementation acceptance.

Reference files

Execution checklist:references/execution-checklist.md