# Block interface design Design focused Block workspaces with strong defaults, bounded choices, icons, and progressive disclosure. # Block interface design Simplicity first: show the work and the next useful action. The app owns project navigation; a Block owns its production surface. Neither needs a second shell. ## Mandatory authoring rules — for LLMs and creators These are requirements, not optional conventions. Authors must follow them; they are not all machine-enforced. Explicit user requests may authorize the named exception, but do not authorize unrelated technical UI. - Do not add Technical result, Result details, JSON dumps, source editors, manifests, debug consoles, or diagnostic panels to a production workspace unless the user explicitly requests that surface or the stated task is source/debug inspection. A collapsed disclosure is still an added surface. - Do not nest decorative cards, bordered panels, or modal shells around the same work area. Use one workspace with spacing and labels. Nested containers needed for layout are fine; repeated visible framing is not. - Do not duplicate the host's step navigation, counters, or workspace identity. - Do not append a generic Workflow tools menu to production Blocks. Batch, loop, schedule, memory, migration, and diagnostic tools are not default workspace chrome; add a specific surface only when explicitly requested. - Show the useful output itself, not a technical representation of the output. - Keep required approvals, errors, progress, and stale-input warnings visible. These are operational feedback, not optional diagnostic panels. - Do not lock page scrolling or introduce sticky headers unless the task explicitly needs them. A production page must keep all controls reachable. The host owns page scrolling; embedded workspaces may scroll their own content, but must not trap scrolling or clip controls below the viewport. - Do not keep media galleries, asset inputs, or control strips sticky by default. They belong to the same scrolling task surface. A fixed timeline/inspector is appropriate only when the actual editing task requires that layout, with all controls still reachable; it is not a default for every Block. - Do not add an ambiguous settings gear for task actions. Show the immediate action directly; label secondary task controls by purpose. Do not disguise source, wiring, or debug controls as ordinary production settings. For an existing Block, apply the [SDK update procedure](/block-sdk/PASTE_TO_LLM.md#updating-existing-blocks-through-the-sdk) to the actual owned source and a new release/remix. These requirements do not authorize rewriting published packages or silently repinning saved projects. ## Rules — implemented enforcement These are implementation facts, not aesthetic suggestions. - The host supplies the Project Type step bar. Production workspaces do not add another step counter or Back/Next bar. - For custom views the host omits its duplicate title and outer frame border. Sandbox isolation remains enabled. - The host does not append a generic Technical result disclosure to custom workspaces. Stored outputs and required approval actions are preserved. - Shared form containment wraps adjacent labeled controls and keeps checkboxes compact. - Admission rejects a primary textarea with 12 or more rows when no task presentation is detected. This is a narrow heuristic, not proof of a usable visual workspace: `StillMade.render` can render text cards. - HTML, JavaScript, permission, and appearance validation remain separate checks. Simplicity never bypasses safety or approval. The SDK exports `INTERFACE_DESIGN_RULES` separately from `INTERFACE_DESIGN_CONVENTIONS`. The older `INTERFACE_DESIGN_PRINCIPLES` export is a compatibility alias for conventions, not enforced guarantees. ## Conventions — design guidance Static review warns about more than eight visible controls, ungrouped large option sets, and multiple primary headings. Warnings are not hard failures. The following guidance requires design review; it is not automatically enforced. ### Do not - Repeat the Block name, step number, or workflow navigation in nested panels. - Place a workspace in a card inside another card merely to create hierarchy. - Use dialogs as permanent page layout or put a dialog inside another dialog. - Give every section a border. Use spacing and short labels. - Put twenty controls in the initial view, even if they wrap. - Show camera, timing, patch, variant, and export settings before they are needed. - Make users read a technical plan to reach the actual work. - Call text scene descriptions a visual storyboard, frame review, or motion preview. - Present placeholder imagery as the actual approved assets. - Lead with JSON, manifests, MCP, transport details, or diagnostics. - Add decorative circles around icons, emoji controls, or unlabeled icon buttons. - Claim approval, rendering, or successful testing without the actual result. - Hide spending approvals, failures, or stale-source warnings for neatness. - Discard drafts or selections when collapsing controls or changing layout. ### Prefer One obvious primary action, strong defaults, and the controls needed for the current decision. Group advanced adjustments behind labeled disclosures. Use recognizable line icons with accessible names, tooltips, keyboard focus, and generous hit areas; keep text when an icon is ambiguous. Use StillMade theme tokens, typography, and spacing. Give the preview, timeline, images, or other task object the main surface. Only include source or diagnostic surfaces when authorized under the mandatory authoring rules above; do not add them automatically, even collapsed. Motion workflows distinguish planning notes from actual frame approval. Frame Review should display the exact images being approved before Motion Designer uses them. Motion preview should display the composition, not just its layer descriptions. These are product acceptance requirements to verify, not guarantees established by static admission. ## Known coverage gap Existing pinned Blocks can still contain excessive nested panels and text-only plans. Host containment does not redesign their interfaces. Correct those through new versioned Block releases and explicit upgrades; do not rewrite immutable releases or silently change a saved workflow's pins.