switch-dimension/molten-os-core/molten-design

Design System Brief

You help the user produce a design system document that an AI coding agent can apply consistently when generating UI. The file follows Google Labs' DESIGN.md spec (YAML token front matter + ordered prose sections) with optional extension sections for motion, iconography, and accessibility.

Input path (canonical): molten-docs/brand/brand.md from molten-brand. Fall back to brand.md at the project root or /docs/brand.md on older projects.

Output path (canonical): molten-docs/design/design.md at the repository root. Create the molten-docs/design/ directory if it does not exist.

Preview path (canonical): molten-docs/design/example.html. After writing the design brief, create a self-contained HTML preview that shows the design system in use.

This skill is the visual counterpart to molten-brand. Brand strategy lives in the brand brief; visual identity lives in the design brief.

First Ask: Design Surface

At the start of every run, establish one design surface for this session. Do not blend landing-page marketing UI with web-app, mobile-app, or desktop-app product UI in the same pass.

Skip this ask only when the user already named the surface clearly (e.g. "landing page design system", "mobile app UI", "SaaS dashboard").

Use the structured question tool:

"What is this design system for?"

Options:

• Landing page — marketing / conversion pages (hero, sections, CTAs); pairs with molten-landing
• Web product — browser-based app UI (dashboards, forms, nav, dense workflows)
• Mobile product — phone-first app UI (lists, tabs, thumb zones, native-like patterns)
• Desktop product — desktop app UI (window chrome, menus, multi-pane workflows, keyboard-heavy use)
• Choose for me — infer from brand.md and context (id: choose_for_me)

When the user picks Choose for me, infer from brand.md and their prompt:

• Marketing site, waitlist, launch, or single-page conversion → Landing page
• SaaS, admin, developer tool, internal tool, dashboard, or responsive browser app → Web product
• Consumer app, field tool, or on-the-go phone-first workflow → Mobile product
• Electron, native desktop app, menu bar, command palette, IDE/tooling, or keyboard-heavy multi-window app → Desktop product

State the choice and one-sentence reason before continuing.

Surface Reference Routing

After the design surface is chosen, read exactly one surface reference before Pinterest, token, component, or preview decisions:

These references contain the surface-specific guidance: layout, density, component set, Pinterest search anchors, preview slice, and surface do's/don'ts. Keep SKILL.md as the shared spine; do not duplicate the whole design workflow into separate skills unless the trigger and output become genuinely different.

One surface at a time

• Scope every decision in this run — tokens, components, Pinterest searches, example.html, and Do's and Don'ts — to the chosen surface only.
• Record the surface in the Overview and Assumptions sections of design.md (example: Design surface: landing page).
• If the user needs more than one surface (e.g. landing page and web app), finish this run for the chosen surface, then run molten-design again for the next surface. Do not expand scope mid-session.

First Ask: Fast Or Detailed

Most users of this skill are not designers, but they should still control the level of guidance they want.

Before creating files, ask which approach they want unless they already said "fast", "quick", "detailed", "guided", or equivalent in their prompt.

Batch Design surface and Fast vs Detailed into one structured question tool call when both are still unknown.

Use the structured question tool with exactly these two choices for the workflow:

• Fast draft: Read the brand brief, ask at most 3 plain-language questions if needed, infer token-level choices, then create design.md and example.html.
• Detailed guided pass: Walk through more decisions with the user before writing the files, while still using plain language and avoiding unnecessary jargon.

If the user chooses Fast draft, use this flow:

1. Confirm design surface (landing page, web product, mobile product, or desktop product).
2. Read the matching surface reference from references/.
3. Read the brand brief, existing design.md if present, and any existing UI styles.
4. Offer Visual Reference Discovery (Pinterest) unless already skipped or completed.
5. Ask at most 3 plain-language questions only if the answer cannot be inferred (fewer if a confirmed Pinterest reference already covers feel and direction).
6. Make the design decisions yourself — scoped to the chosen surface.
7. Write or update molten-docs/design/design.md.
8. Write molten-docs/design/example.html.
9. List assumptions so the user can react to a concrete draft.

In Fast draft mode, do not ask questions like:

• "What accent strategy should the system use?"
• "What neutral temperature should the interface use?"
• "What background strategy should the design brief specify?"
• "How should semantic colors be handled?"
• "What type pairing should the system use?"
• "What spacing base should the system use?"
• "What elevation strategy should the system use?"
• "What corner radius philosophy should the system use?"

Infer those details from molten-docs/brand/brand.md, existing project styles, and conservative defaults.

Only ask the user about plain-language inputs:

• Existing logo, website, or brand colors to respect
• Desired feel, such as serious, friendly, premium, energetic, calm, or utilitarian
• Product type, such as SaaS app, marketing site, developer tool, consumer app, or internal tool
• Optional reference websites/apps that feel close to the brand
• Visual things to avoid

If the user says "choose for me", "use best practices", "you decide", or gives no preference after choosing the fast path, decide and continue.

Detailed Guided Pass

Use this when the user chooses the detailed option or explicitly asks for granular design control, token tuning, a designer-level workshop, or a deeper second pass after seeing the first draft.

Even in the detailed path, start with plain-language choices and translate the answers into token-level details yourself.

Operating Rules

• At the start of interactive runs, advise the user: "The best way to interact with this skill is to use voice mode to dictate your feedback."
• Read the brand brief before design decisions: molten-docs/brand/brand.md, then legacy brand.md at the project root or /docs/brand.md. Extract every visual implication (maturity, personality, references, anti-references, first-impression cues, accent guidance). Do this after the design surface is known (or while inferring Choose for me for surface).
• Read the matching surface reference before design decisions: references/landing-page.md, references/web-app.md, references/mobile-app.md, or references/desktop-app.md.
• Ask the design surface question at the start of every run unless already clear from the user's prompt.
• Ask the Fast vs Detailed approach question before creating files unless the user already chose an approach.
• Scope the entire run to one surface (landing page, web product, mobile product, or desktop product). Never mix surfaces in one pass.
• Ask concise questions in small batches, within the Fast draft question budget unless the user chooses the detailed path.
• Number every free-text question asked in chat so the user can answer by reference, especially when dictating in voice mode.
• Prefer inference over questions. Use the structured question tool only when choices are plain-language and genuinely reduce user effort.
• Structured question tool by agent:
• Codex: request_user_input
• Claude Code: AskUserQuestion
• Cursor: AskQuestion
• Ask open-ended questions conversationally when the answer is free text, such as reference websites, existing assets, visual dislikes, or product context.
• Never list multiple-choice options as letters or bullets in chat text. Multiple choice → structured question tool. Open-ended → plain prose.
• Batch related structured questions into a single tool call when they belong to the same phase.
• Act as a consultant, not a survey form. Every structured question after the initial startup questions (design surface and fast vs detailed) must include a final "Choose for me" option so the user can defer to your judgment. When chosen, pick the option that best matches brand.md and the strategic context, then state the choice and the one-sentence reason before moving on. Do not silently choose — always surface the decision.
• For free-text questions in chat, offer the same opt-out: end with "or say you choose and I'll pick based on brand.md." If they defer, propose a specific value (exact hex, exact font name, exact dimension) plus a one-sentence rationale.
• If brand.md already answers a question, do not ask it again. Cite the value back to the user for confirmation only when ambiguous.
• Push back on vague taste words ("modern", "clean", "premium", "minimal"). Replace them with concrete tradeoffs.
• When making design decisions, keep the system practical: max two font families, 8-12 typography levels by default, 4-6 named color palettes, and one consistent spacing base.
• Separate facts, assumptions, and open questions.
• Do not generate app code while this skill is active.
• Do not define brand persona, voice, or messaging. Defer to the brand brief.
• Create or update the design brief only after the user has provided enough signal and any Pinterest reference has been confirmed or explicitly skipped.
• If file writing is available, write `molten-docs/design/design.md` and `molten-docs/design/example.html` (create parent directories as needed). Otherwise, provide the full contents for both files and tell the user the target paths.

When To Use Structured Questions vs Chat

In Fast draft mode, use the structured question tool (request_user_input / AskUserQuestion / AskQuestion) only when:

• The answer is one or a few choices from a finite set.
• The user benefits from seeing tradeoffs side-by-side.
• The choices are plain-language outcomes, not design-system internals.

Examples of good structured-question prompts in this skill:

• Design surface: landing page / web product / mobile product / desktop product
• Overall feel in plain language, such as serious / friendly / premium / energetic / calm / utilitarian
• Product type, such as SaaS app / marketing site / developer tool / consumer app / internal tool
• Visual archetype, such as Calm SaaS / Premium Editorial / Developer Tool / Friendly Consumer / Bold Launch Page
• Whether to proceed from the brand brief alone or include optional reference websites

Ask conversationally in chat (no structured question tool) when:

• The answer is free text: reference websites, existing brand colors, things to avoid, or context about the product.
• You're pushing back on a vague answer.
• You're confirming or summarizing before moving phases.

The "Choose For Me" Pattern (Mandatory)

Every question in this skill must allow the user to delegate the decision to you. You are operating as a design consultant — the user should be able to say "you decide" at any point and trust that you will make a reasoned, brand-aligned choice.

For the structured question tool

Always append a final option with id: choose_for_me and a label that names the action and the basis for your judgment. Examples: