soia-dev-design-explorer

soia-dev-design-explorer

This is a public design artifact workflow wrapper layer. It is based on the Open Design atomic operations provided by soia-dev-open-design-ops and converges high-fidelity design exploration into explicit inputs, controlled outputs, and reproducible verification; it does not replace product specifications 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 size, content, and assets, and generate step by step with Open Design	Artifact paths, previews, gaps, and verification evidence
style exploration	Generate 2–4 comparable directions so users are not blindly choosing from text alone	Direction differences, real visuals, and rationale for recommendations
design review	Tiered review of existing pages or screenshots	Conclusions, severity, and prioritized fix actions

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

How customers use it

Provide:

1. Delivery type:prototype / deck / animation / style-exploration / review；
2. Platform and canvas size;
3. Audience, purpose, and success criteria;
4. Real content and assets;
5. User-provided brand guidelines (file, URL, or explicit statement of “none”);
6. Output category and path;
7. Open Design checkout path; when integrating a design system, also provide the project path or DESIGN.md。

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

Dependencies and installation

Install this skill and its hard dependencies:

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-dev-design@soia

The plugin will install together with the hard dependency soia-dev-open-design-ops . If you only want this one skill, you can use the npx route, but both skills must be installed, and they will go into the shared source of truth ~/.agents/skills：

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

Open Design’s checkout, Node/pnpm prerequisites, private configuration, daemon ports, and security boundaries are all maintained by soia-dev-open-design-ops . This skill does not embed or install Open Design; if the atomic layer is unavailable, stop the design generation path, return its installation or repair recommendations, and do not call a local substitute an Open Design deliverable.

For design systems, prioritize the official three-piece set:manifest.json、DESIGN.md、tokens.css. Existing user projects can use the DESIGN.md-only compatible integration; it must be registered by the atomic layer’s CLI/App import-local , and user project paths cannot be copied or guessed.

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.

WorkBuddy ’s loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it and requires separate installation, see docs/install/workbuddy.md。

Logs and completion receipts

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

日志摘要：
- type/platform: <类型与画幅>
- open-design: <环境/daemon/设计系统或目录检查结果，不输出秘密>
- inputs: <品牌/内容/素材完整度>
- created/updated: <产物路径>
- skipped/failed: <数量和原因>

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

Trigger conditions

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

Boundaries

• The output is a design exploration artifact or review, and does not automatically become production code, a business contract, or a product specification.
• Before modifying existing files, overwriting exports, publishing, or writing to a remote, you must preview and obtain confirmation.
• Do not load or assume any organization-internal workspace, governance directory, brand skill, or on-disk rules.
• Do not modify the upstream source code of the Open Design checkout; perform controlled operations only through atomic-layer scripts or the upstream CLI/App.

Minimal workflow

Step 1. Lock down the task form

Choose only one primary form at a time:

• prototype: clickable pages or flows;
• deck: HTML slides or exported presentation decks;
• animation: timeline animations 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.

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

Step 3. Call the Open Design atomic layer

Determine the route first, then choose the check command. The local machine may have a CLI source checkout, desktop App, or MCP installed; the three are independent of each other; running CLI-route checks without determining this first will lead to wrong conclusions:

# 从已安装 skill 调用（任意工作目录）
python3 ~/.agents/skills/soia-dev-open-design-ops/scripts/detect_route.py --json

# 在 soia-open-dev-design-skills 仓库根目录开发时
python3 skills/soia-dev-open-design-ops/scripts/detect_route.py --json

Branch according to the returned route :

route	What to do next	Evidence that the determination passed
cli	Run check_env.py + daemon_ctl.py status/health	status=ok, and health is based on /api/skills returning an array
desktop	Run desktop_ctl.py detect to get the current port	Returns daemon_api_port; the port changes on every startup, do not cache it
desktop-mcp	Same as above, and prefer MCP (start_run can assign work to OD, the HTTP API cannot)	start_run returns runId
none	Stop, fix according to suggestions and start over	—

Do not run desktop / desktop-mcp on the check_env.py。 route; it will necessarily return status=error(missing node_24 / pnpm_10_33 / daemon_7456_unreachable), that is the correct conclusion that "the CLI route is not installed on this machine", not a failure. Treating it as a failure will make the entire design process stop at a prerequisite that is not needed at all—this has actually happened.

When integrating design rules, first check whether the user-provided project has the formal trio; if not, use the user project's DESIGN.md as compatible input, and integrate it via the atomic layer's design-systems import-local . Use list_skills.pyto query functional skills; use the Open Design App's "Start from" or GET /api/design-templatesto query rendering templates. The two kinds of directories must not be conflated.

Step 4. Choose the output destination according to the 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-dev-design-explorer/<slug>/，TMPDIR if not set, 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-dev-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 functionality is the 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	Short review that does not need to be archived	Do not write to disk

Before writing to C/D categories or overwriting existing files, show the absolute target, current state, and expected file list. Category A cannot masquerade as final deliverables.

Step 5. Generation and iteration

• First make the smallest visible version, then expand;
• style exploration first produces 2–4 substantially different directions;
• prototype first ensures the critical path is clickable, then polishes the visuals;
• review first gives conclusions and issue severity levels, then gives fix suggestions;
• All brand choices are evidenced by user assets or citable public brand materials;
• When generating, continuing a session, or exporting via Open Design App/CLI, follow the atomic layer's stable entry points; do not construct undocumented API payloads.

When dispatching a run to Open Design (desktop-mcp route)

start_run let Open Design spawn the agent itself to generate, so the client can see the whole process in the interface. The output quality of this path comes from OD's generation pipeline,do not switch to write_file writing it yourself, those are two different things. Three hard constraints:

1. the prompt must inline the full text of tokens.css full text. The agent inside the run reading design-systems/<id>/ will get a 404; just writing "please follow some design system" will not work for it. The alternative is to point to a page in the project that already correctly applies that system for it to reference.
2. At the same time, write the design system package's known contradictions into the prompt as well, and specify that tokens.css + components.html takes precedence. Otherwise the agent will follow DESIGN.md 's prose and go off track (see the atomic layer's "package consistency check").
3. Real-time progress tail <data>/runs/<runId>/events.jsonl，get_run only gives status. If the file mtime does not move for a long time, the agent is thinking, not stuck; do not cancel_run。

After the run returns,must independently accept it, and cannot merely trust its self-check receipt: token purity (:root zero bare values outside), only components from the checklist present: true were used, product red-line scan, no horizontal overflow at key viewports.

Step 6. Verification

Perform at least one verification commensurate with the delivery type:

• open in a browser and check key viewports;
• Playwright/Open Design verification script screenshots;
• exported files can be opened, page count/duration matches expectations;
• the prototype's key interactions are clickable;
• review covers strengths, severity-ranked issues, and the top 3 highest-priority actions.

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

Reference files

• Execution checklist:references/execution-checklist.md