YuukiFST/stageshow

stageshow 是做什麼的？

微型產品 UI：一個可信的介面，在其空間中框架化，作為一張靜態圖片或一個發生單一事件的短動畫。觀看者能識別出螢幕，並看到事件發生。

核心理念

它看起來像一個真實的產品，簡化為觀看者所需的內容，以有意圖的方式框架化，且每個動作都有其原因。

五種失敗方式：

• 資訊過多。 每行都有真實文字，到處都是數字，一切塞得滿滿當當。細節越多，就越像生成的。
• 線框圖。 兩個灰色團塊和一個按鈕。建得太小，或剝奪了使其可識別的元素。
• 盒子化。 整個視窗縮成一個邊距均等的卡片：貼上的螢幕截圖，而非產品截圖。
• 扁平化。 在同一個帶邊框的卡片中，每個物件都有相同份量。視覺無處可落。
• 平淡無奇。 一個帶有游標的灰色視窗，無論需求是什麼都是如此。需求的風格和能量（藍圖、彩色玻璃、動態島、吉祥物）是關鍵；要按照要求來建構，並遵循規則，就像 examples/hero-demo 對待其打字彈出視窗和終端機衛星（衛星是較小的第二個物件，如收據、手機或細節卡片，跨越首圖的邊緣）那樣。

解決方案：一個完整、結構化的螢幕，使用平靜的灰色，僅在故事相關的地方使用真實文字，其他地方使用佔位線條，保留呼吸空間，並進行裁切，將視覺焦點放在故事所在之處。簡化文字，而非上下文。一個空角落，列表下方的空白，填滿面板的行列，在底板上（背後有背景層或色調一致的區域）浮動的視窗：未完成的，而非平靜的。

這些是經過創作的插畫，而非瀏覽器自動化：a.click() 繪製游標按壓，a.set() 改變場景。

施力程度

要像一個產品設計師打造一個會被評判的發布頁面那樣去建構它。examples/ 中的黃金範例是標準，而非參考：如果你的作品與最接近的黃金範例相比顯得更空、更平或更小，那就是首要修復目標。然後，以你所認識最嚴格的設計師的眼光來審視框架，那位會擷取一個錯誤的畫面並回傳「這是什麼？」的設計師：一個偏離頭像的點、一個獨佔一行的單位、島嶼下方的拖拽條、觸碰到卡片的文字。如果你能想像那張截圖，你就找到了下一個修復目標。

工作流程

大部分品質在編寫任何程式碼之前就已決定。先撰寫計畫：位置在哪、焦點物件是什麼、動作、成果、哪些可以省略。

1. 媒介與場所。 靜態或動畫（循環、進入視野一次、或懸停觸發）。頁面、其背景、其寬度。以將被看到的尺寸進行設計，約 720 × 340 用於搭配文字的 Hero (hero-demo)，900 到 1100 寬用於滿版 Hero (linear)，400 × 300 用於卡片，以 1:1 顯示；展示用的寬度絕不低於約 320，但 Bento 拼貼或衛星卡片可以更小。每個可以放在手機欄位中的展示都會提供一個符合欄寬 (358) 的 compact 設計，是重新設計而非壓縮 (references/framing.md, 小型格式與頁面)。拼貼網格是一組設定：用 references/bento.md 規劃。
2. 外觀。 在手邊有產品的程式碼或網站的情況下，將其標記映射到工具包的標記 (references/looks.md)；如果開發者要求使用他們自己的元件，請在舞台內使用它們，而非工具包的小零件。否則選擇一個主題（淺色、深色、藍圖、玻璃）、一個調色盤（強調色、單色）和一個精細度：minimal 是所有長條，standard 是文字有含義的地方用文字，其他地方用長條，realistic 是真實內容隨處可見。預設為淺色、強調色、標準；在 Hero 規模、針對指定的真實產品、或主題是列表或頁面的靜態插畫時使用 realistic。使用 Text filler 編寫一次填充文字，精細度會決定細節。產品自己的圖標、其真實的瀏覽器/視窗裝飾、使其可識別的內容。一個帶有風格（可愛、紙張風格、海報色彩）的需求，需完全按照該風格建構，但仍須遵守這些規則。
3. 故事。 其形狀 (references/motion.md, 故事)：使用感受、一個流程、或系統所做的行為。三到五個節拍和一個成果，10 到 16 秒。沒有無法解釋的游標移動。數據不應在無原因的情況下在視野中回退。在更豐富的故事和更平穩的框架之間，選擇框架。
4. 從一個範例開始。 找到最接近的黃金範例（下面的黃金範例表）並將其拍攝成影片 (node scripts/film.mjs "<preview>/?capture=<gold>" --select '#example' --still --out gold.png；npm run dev 啟動預覽伺服器)。將其資料夾複製到你的專案中作為起點；不要只憑印象重寫。最快的循環：將其複製到此處的 examples/<yours>/，預覽伺服器會載入它並且 ?capture=<yours> 可以對其進行拍攝，然後當它通過審核時將其移動到主專案並修正其工具包導入路徑。保留其結構：舞台大小、裁切與出血、行與類型大小、間距、腳本的節拍、工具包零件。現在完整閱讀 references/craft.md：它很短，並且包含了黃金範例無法展示給你的靜態框架規則、以及你的黃金範例恰好未包含的情況。然後以其產品的需求取代其外觀和內容：步驟 2 的標記、產品自己的圖標、瀏覽器/視窗裝飾和文字。一個只改了名字的複製品並不算完成：它應該讀起來是需求的產品，而非黃金範例的產品。如果沒有黃金範例能講述你的故事，則分兩部分選擇：先選擇佈局（從 references/framing.md 的表格中選取；每個佈局都命名了其範例），並複製該範例，即使其故事不同；然後從故事最接近的範例中借鑒動作用於你的節拍，並以相同風格建構兩者都沒有的部分。然後進行框架化：裁切到故事發生的面板，並以最終可見的裁切來評判 (references/framing.md 包含了規則和佈局表格)。簡而言之：一個水槽，完整的或明顯超過一個；只有填充物可以出血；打開的東西要保持在原位；視窗保持其形狀；頁面是背景，因此在白色或深色頁面上的 Hero 下方不要有底板，也不要讓視窗在四面都有空氣的情況下完整顯示；僅在開發者要求時才使用 unframed；不要有死角落。在兩個寬度下分別拍攝一張靜態圖片，並與黃金範例的並排比較；如果你的顯得更空、更平或更像盒子，先修正框架再進行任何動畫。
5. 螢幕。 計算真實字串，通常為 3 到 7 個 (references/craft.md, 克制)：一個關於文字、而非元素的預算。使用工具包的標記 Bar、Text 和 Row 來建構。在其移動之前，調整每個控制項的文字。使用 data-target 和 data-cursor 標記游標觸碰的內容；使用 rect() 測量，永遠不要硬編碼。
6. 編排。 使用 Act API。保持已掛載的內容可見，並切換其狀態以使退出動畫生效（Bubble 和 Fly 明確地進行交接）。為關係添加動畫，而不僅僅是物件：一個新行會帶動其下方的行，一個調整大小的表面絕不會拉伸其文字。節拍重疊，群組交錯，成果停留，循環結束在開始的地方或以可見的原因重新開始。
7. 排練。 首先設定 poster：大多數人只會看到該幀（縮圖、減少動畫模式、螢幕截圖），因此它必須是能獨立講述故事的節拍，永遠不會是在變化中途被捕獲的，且結果會留在螢幕上而不是被收拾掉 (references/motion.md, 故事)。然後拍攝循環的影片，而不僅僅是靜態圖片：在顯示寬度和 390 寬度下檢視線稿，並逐步檢查每個按壓、選單、變形和循環接縫 (references/rehearse.md)。靜態圖片無法顯示彈出效果。閱讀每一幀，首先修復最大的可見缺陷（框架化、然後層級結構、然後動畫、然後打磨），重新拍攝。然後將其與最接近的黃金範例並排放置，並回答 references/teaching.md 中關於你靜態圖片的整體構圖和風格對照問題（視線首先落在哪裡？是否是結果？一個視窗、拼貼或設備是否明顯主導？）；任何「否」的答案都是最大的缺陷。film.mjs --gate 以 rehearsal passed 結束是必要條件，而非充分條件。然後執行 references/rehearse.md 中的最後一輪：一次全新的審查 (references/review.md) 並在元件旁放置 REHEARSAL.md（模板在 references/verify.md, 交接）：你複製的黃金範例、你更改了什麼、你沒有檢查什麼。

每輪都會反覆出現的缺陷，每個都有其規則；在交接前檢查它們：

• 內容交換而非移動 (references/motion.md, 文字與數值的更改)。
• 視覺焦點落在灰色長條上； 填充物應位於邊緣 (references/craft.md, 克制)。
• 視窗後方有底板，或視窗在四面有空氣的情況下浮動； 視窗或手機至少佔據舞台的三分之二，並延伸到邊緣之外 (references/framing.md, 規則 5 與小型格式和頁面)。
• 空白帶、裁切的控制項和陰影 (references/craft.md, 克制；references/framing.md, 規則 4)。
• 常見的 AI 風格和虛構標誌： 閃光、紫色、彩色方塊中的字母 (references/craft.md, 圖標和標誌)。
• 擁擠的行和不對齊的內縮 (references/craft.md, 克制與間距和對齊)。
• 長時間停頓和無原因的復位 (references/motion.md, 循環)。
• 選擇不在 I 型游標下方 (references/motion.md, 拖曳和選擇)。
• 手繪的狀態列或 Home Indicator； Phone 元件會繪製這兩者 (references/craft.md, 瀏覽器/視窗裝飾與設備)。
• 金額與其貨幣符號居中對齊 (references/craft.md, 間距和對齊)。

範例

開始前（步驟 4），先拍攝最接近的範例。黃金範例是品質標竿；產品研究用於借用互動方式，絕不能用於其他產品的識別；樣本表是目錄，而非構圖。使用 npm install 和 npm run dev 執行所有內容。teaching/ 包含好/壞對照組 (references/teaching.md) 用於診斷問題；壞的一半絕不能作為起點。

黃金範例

需求	範例	學習要點
靜態或功能卡片	static-card	平和的層級結構、大膽的裁切、一個衛星物件、僅對選中的客戶、其鄰居和總計使用真實文字
深色靜態	dark-bento	一個信號只說一次；專輯封面確保它是音樂應用程式
帶手勢的動畫 Hero	hero-demo	五個節拍、命名目標、一個註解、一個向前移動的終端機
無游標的編排動畫	payout-flow	緩慢重疊的進場、閱讀時間、一個停留的成果
內容原位變化	choreography	保留的軌道、柔和遮罩、依賴時間
AI 回答	ai-chat	問題已發送、思考中、答案串流顯示（帶有高度變化）、最後是來源；沒有閃光、沒有紫色
帶卡片的 AI	ai-cards	一個選擇題卡片，選擇後作為記錄保留；一個選項卡片在對話中打開，由自己的按鈕觸發預訂
表單驗證	form-error	錯誤顯示在引起問題的欄位上，修正後清除，然後按鈕在自身確認
拖曳重新排序	reorder	一行被其拖拽把手提起，其他行讓出空間，放下到位
圖表掃描	chart-scrub	跟隨指針的細線和圓點，標題數值滾動到指標下的日期
表格內編輯	table-edit	一個儲存格在原位編輯，然後其所貢獻的總數在一個節拍後滾動更新
載入到內容	loading	骨架屏使用與內容相同的幾何形狀，行從上到下解析，全程使用真實的瀏覽器/視窗裝飾
深色 Hero	dark-hero	在黑色背景上透過表面層級創造深度，一個亮色，一個在其自身藥丸狀容器內變化的狀態
即時協作者	presence	每個人有一種顏色並隨處可見，名字跟隨其游標，在文件本身的標記中顯示工作內容
系統故事	subscriptions	一個小晶片飛入一行，MRR 滾動，第二個場景是重置
特寫	close-up	一個控制項以 1.4 倍顯示，附帶其視窗的瀏覽器/視窗裝飾，行保持完整，一個大游標與之匹配
同一物件的多個	many-of-one	一個物件的網格，從每個邊緣開始佈局，其中一個拼貼因深度而成為焦點，且是唯一有文字的一個
漸變裁切	fade-crop	一個視窗在其底部漸變淡出，下方為填充物，而非直接裁切出邊緣
產品上的面板	panel-annotation	一個設定面板置於產品的邊距上，一條引導線從設定連接到其所更改的內容
重疊視窗	overlap	一個卡片放在一個視窗前面，其邊緣對著視窗側邊欄的線條
堆疊卡片	stacked-cards	兩個相同寬度的元件，一個小間隙，下方的元件超出底部邊緣
對角角落	opposite-corners	一個 Bento 拼貼：文字在左下角，產品從右上角懸掛下來
傾斜堆疊	tilted-stack	一疊鬆散的紙張，小幅交替傾斜角度，只有最上面的卡片有文字
角落晶片	corner-chip	一個小晶片居中放置在視窗的角落，一半在外面
單色	monochrome	其他公司的產品排成一行，灰階，底部邊緣淡出
視窗行	window-row	相同高度的並排工作階段：透過深度區分焦點，被舞台邊緣裁切的相鄰視窗，只有填充物被裁剪
視窗與手機	device-pair	一個儀表板和一個鎖定畫面講述一個事件；手機跨越邊距放置，但絕不跨越人物主體
相關物件	story	一張發票、一個方案、一個連接器、滾動的總計
日曆拖曳	calendar	一個已填充內容的週，一個焦點事件，一次測量過的拖曳
自由拖曳	freeform-drag	拖曳偏移、一個測量過的網格、一個會自動吸附的放置槽
手機應用程式	phone-touch	一個卡片作為一個物件打開進入其畫面，然後循環折疊回來
動態島	dynamic-island	一個黑色形狀，其內容是一個單獨的圖層
訊息	messages	撰寫器、正在輸入、收據、氣泡的生命週期
游標	cursors, cursor-morph, cursor-resize	五種樣式、由元素驅動的類型、調整大小的邊緣和角落、完全沒有游標
註解	annotations	引導線、尺寸、流程和一個移動的目標；references/annotations.md
功能網格	bento	一個 Hero、一個視窗、一個統計數據、一個物件、一個圖表
深色標尺網格	ruled-bento	共享的標尺和技術圖像
消費者網格	staggered-bento	偏移拼貼、圖形藝術、實體物件
以圖像為主導的 Hero 網格	hero-grid	不同的背景

…

[餘下內容因翻譯要求而被截斷]