stillmade-sdk 0.1.8 → 0.1.9

package/UI_AESTHETIC.md

@@ -98,6 +98,10 @@ listing previews read its raw palette. Do not maintain a parallel theme.
 - Create, import review and production workspaces use the available page width,
   with normal page gutters. Do not present these pages as centered modal-like
   cards or nest decorative bordered panels. Actual transient dialogs are separate.
+- The Block Builder (Create and the project dialog's Create with AI) fills its
+  whole area with no page gutter (owner, October 13, 2026). Its toolbar is the
+  back arrow and name, then one segmented control for Preview, Marketplace and
+  Advanced (Files, Tests, Versions, team sharing); drafts save automatically.
 - Validation details are collapsed by default. Show passed, needs-attention and
   untested counts, plus actionable remaining requirements outside the disclosure.
   Never hide failures or weaken admission checks to simplify the interface.
@@ -173,6 +177,45 @@ Versions in each context. Project Type Builder uses Workflow, Preview and Publis
 workflow checks belong inside Preview, and saved versions belong inside Publish.
 Importing remains a source action, not another entity type.
 
+## Pictures over words
+
+The app and every Block should work at a glance. Decide every sentence: drop
+words nobody needs to finish the task (intros, subtitles that restate the
+heading, "how it works", labels next to an icon that already says it); show a
+thumbnail, swatch, sample or icon where one says the same thing; and put words
+that might help in a closed info toggle or a closed "More" section. Errors,
+charges and credit approvals, stale inputs and destructive confirmations stay
+visible, in few words. Empty states are an icon, a few words and one action.
+
+Buttons that make something name what they make ("Write", "Generate image",
+"Make video"), never "Run" or "Run step"; see "Run buttons say what they do and
+what they cost" below for the price, the model chip and when a confirmation shows.
+
+`packages/design-system/block-kit.css` holds the shared classes for this
+(`sm-stage`, `sm-empty`, `sm-choices`, `sm-actions`, `sm-status`, `sm-more`,
+`sm-hint`); the app imports it and the host injects it into every Block view.
+Reference page: `packages/design-system/block-kit.html`. Block authoring rules:
+`docs/sdk/INTERFACE_DESIGN.md`.
+
+## Compact: one screen, no scrolling
+
+A Step, Block view, dialog or settings page fits one laptop screen (about 720 px
+of height) without scrolling. When it does not, fold, shrink or move something
+up; never add another section below the work. Approved October 18, 2026 with
+before/after examples from an Image Panels project (Voiceover 1,210 px to about
+200 px).
+
+- Label and control on one row. No label stacked above a short control, no card
+  around a single control, no help line under every field.
+- Status is a dot or a few words ("No narration yet"), never a paragraph; the
+  reason sits behind an info toggle.
+- Files are tiles: a saved file is a thumbnail or chip, adding one is a + tile.
+  Never the bare "Choose File / No file chosen" picker; size limits only when a
+  file is too big.
+- Rare tools (version update, schedule, history, reload) are icon buttons in the
+  header with a tooltip, plus a dot on the Step chip when one needs attention.
+- Mockups: `docs/ui-review/compact-principles.html`.
+
 ## Icon preference
 
 When a recognizable icon can convey the same action or meaning as a text label,
@@ -181,6 +224,27 @@ a surrounding circle or circular button outline/background. Preserve a generous
 invisible hit area and keyboard focus indication. Give icon-only controls an
 accessible name and a tooltip; retain visible text when the meaning would be unclear.
 
+## Run buttons say what they do and what they cost
+
+- The button that starts a Step, Block or job never says "Run step", "Run",
+  "Run in project" or "Review cost". It names what happens: Write, Generate,
+  Make video, Make voiceover, Transcribe, Research, Send. While it works it says
+  so ("Writing…") with Stop beside it; afterwards it offers the same action again.
+- When the run costs credits, the price is part of the button:
+  "Write · 1 credit", "Generate · 28 credits". Paid with the person's own key it
+  reads "Write · your key". When the price is not known before a quote, the button
+  shows only the action and the quote opens the review.
+- When the model, quality or count can change, one chip with a caret sits right
+  before the button and shows the current choice (for example
+  "GPT Image 2 · Low · 2"). It opens priced picture tiles; picking one updates the
+  price on the button at once. When nothing can change, there is no chip.
+- Pressing the priced button is the approval, so no confirm dialog follows it.
+  The run still fetches the server's quote and checks it against the price shown.
+  The review opens only when that quote is higher, when the Block needs its first
+  paid review, or when the run fails and needs a decision.
+- Steps use `StepRunControls` and `client/src/blocks/runAction.js` for the verb
+  and price; reuse them instead of writing new run buttons.
+
 ## Dialog placement and dismissal
 
 - Center search and other transient dialogs in the viewport, independent of the