Variants and responsive design

Misaki Studio uses separate mechanisms for size changes, reusable visual alternatives, and runtime interaction states. Keeping them separate makes the Component easier to preview and produces a clearer React contract.

Choose the right mechanism

• Need: Adapt the same Component to its container width · Use: Responsive screens · Example: A card changes from horizontal to stacked.

• Need: Expose a named visual choice to a caller · Use: Component variant · Example: outline, destructive, sm, or selected.

• Need: Style one node for a CSS interaction · Use: Hover, focus, or active style · Example: A button darkens on hover.

• Need: Drive one node's private visual modes from logic · Use: Per-node style variant · Example: An internal icon changes style from state.

• Need: Decide whether an element exists at runtime · Use: Condition · Example: Show an error only when validation fails.

A state can drive a variant or condition, but state stores information; it is not itself a style layer.

Responsive screens share one hierarchy

Screens under one Screen List do not contain separate element copies. They share one Body and ordered node tree. The widest/default screen supplies the base structure and styles; narrower screens add overrides for the properties that need to change.

Misaki Studio sorts screens from wider to narrower and resolves the applicable style stack through the selected screen. Generated visual output uses container-query rules, so the Component adapts to the width provided by its parent rather than only the browser viewport.

This matters in practice: an isolated preview can look correct at 450 pixels while the same Component receives a different width inside a grid, sidebar, or nested Component. Test the exported Component in its actual container.

Build a responsive Component in the editor

1. Design the widest/base screen with the complete semantic hierarchy.

2. Add a narrower screen to the same Screen List.

3. Select the narrower screen and change only properties that should differ there.

4. Reuse the same elements; do not duplicate the hierarchy just to change layout.

5. Mark an element as skipped on a screen only when it should be absent at that container size.

6. Preview several widths around each authored screen rather than checking only the exact screen values.

A separate Screen List is an independent board group with its own shared Body. Use it only when the file genuinely needs another screen/board set, not as a breakpoint inside the first set.

Component variants are a public API

Component variants are file-wide named alternatives. The generated Component exposes them through a typed input shaped like:

variant?: (keyof typeof Variants)[]

All axes live in one selectable list, so a caller can compose values such as outline and sm. The base/default appearance has no variant ID and is styled through the ordinary base layer.

One selected variant ID applies its layer whenever that variant is present. A declared combination of two or more IDs applies only when that exact combination is selected, which is useful when the combination needs an adjustment neither variant supplies alone.

Use Component variants for intentional caller-facing choices. Do not rebuild the same contract with conditions and private per-node variants: doing so hides the choice from the generated typed API and makes every node responsible for reproducing the logic.

Build Component variants in the editor

1. Define and finish the base Component first.

2. In Logic, enable the Component's Variants data-structure slot.

3. Add a small flat set of names such as outline, filled, sm, and lg.

4. Return to Design, select one or more current variants, and change only the styles that differ.

5. Add a variant combination only when the joint selection needs its own override.

6. Preview the base, every individual variant, and meaningful combinations.

Per-node and interaction styles

Hover, focus, and active are interaction style layers that export as CSS state selectors. They can also combine with Component variants, so an outline button can have its own hover change.

Per-node style variants are an advanced, private mechanism scoped to one node. They need logic to choose the active value. Use them only when the visual state should not become part of the Component's public variant contract.

Ask an agent to add responsive overrides

Coverage: UI + MCP.

Select the Website project and inspect <component reference>. Read its screen and element tree. Add one narrower screen to the existing Screen List, then apply only a screenId layout override to <container element> so its children stack vertically. Preserve the base style, variants, logic, and timelines. Read the resulting tree and style back, capture previews at the wide and narrow widths, and run diagnostics.

The agent can use get-file-tree, add-screen, get-style, update-style with the returned screenId, get-preview-screenshot, and get-diagnostics. It must not use add-screen-list when the goal is another breakpoint in the existing set.

Ask an agent to add Component variants

Inspect <component reference> and its current data structure. Add Component variants named outline and compact. Style only the returned variant IDs: give outline a border change and compact a spacing change. Do not create per-node style variants or conditional logic. Preview the base, each variant, and the combined selection; then show the generated variant type.

The relevant operations are get-data-structure, add-variants, update-style with variantIds, add-variant-combination only if the joint state needs a distinct layer, get-preview-screenshot, and export-code.

Verify responsive and variant work

For responsive changes, verify the base width, each authored screen, widths between the authored values, and the Component inside its real parent container. Confirm that a narrow override did not leak into the base style.

For variants, verify the default appearance, each individual value, supported combinations, hover/focus/active states, and the generated TypeScript contract. A valid screenshot is not enough if the consumer cannot select the intended variant safely.

Undo and persistence

Screens, screen overrides, Component variants, variant combinations, and per-node variants are persisted Component content and should be undoable. Selecting a screen or current variant for editing is view state.

An exported file or consuming application is outside the Component's Undo history. Re-export after verification, and use the destination's own version control to recover external file changes.

Limits and failure states

• Mockups have no Screen List, responsive screens, preview runtime, or export.

• A screenId style write is valid only for a Screen in the same visual file.

• The default screen uses the base style rather than its own override layer.

• A narrow screen should override only differences; copying every base property makes the cascade harder to maintain.

• Per-screen timeline configuration is stored and serialized, but current exported element targets are not scoped to the corresponding container-query breakpoint. Treat separate-screen animation export as unfinished.

• Variant, state, condition, and responsive screen are related but not interchangeable.