Mockup 文件示意積木
寫文件的工具，不是產品元件。
在 Storybook 開啟問題：截圖第一天就開始過期
改一次按鈕位置，全手冊的圖都要重錄。於是沒人重錄。於是手冊開始說謊， 而且說謊的方式很難察覺——圖看起來很專業，只是跟現在的系統不一樣。
做法：用真元件排出示意圖
- 重點控制項 → 元件庫的真元件 ＋
<Spotlight>圈起來 - 其餘區域 →
<Placeholder>佔位留白 - 整體版面 →
<MockScreenFrame>
元件改版，示意圖跟著改版。沒有人需要去重拍任何東西。
使用規約
重點包 Spotlight（真元件），其餘一律 Placeholder。
不要用 Placeholder 去「假裝」一個真元件。那又變成一種會過期的截圖， 只是畫得比較醜。
初始畫面不能取決於瀏覽器環境
文件站是靜態產生的，第一次渲染永遠發生在沒有瀏覽器的地方。 任何「初始狀態要讀瀏覽器」的元件都會踩到同一個坑：
// ✗ 伺服器端沒有 matchMedia；就算加了防呆，
// 伺服器算出 false、瀏覽器算出 true → hydration mismatch
const [expanded, setExpanded] = useState(
window.matchMedia("(prefers-reduced-motion: reduce)").matches
);
// ✓ 初始值固定，掛載後才套用使用者偏好
const [expanded, setExpanded] = useState(false);
useEffect(() => {
if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) setExpanded(true);
}, []);
這條適用於所有取決於瀏覽器環境的初始狀態：主題偏好、視窗寬度、觸控能力、
減少動態偏好。症狀是畫面閃一下或 React 在主控台抱怨 hydration 不一致，
而它只在正式建置後才看得到——npm start 的開發模式不會重現。
聚光用的是同一套視覺語言
<Spotlight> 用的 .spotlight-ring 與 Coachmark 完全相同。
讀者在文件與系統裡看到的是同一種「看這裡」。
琥珀色專屬「已改動未送出」，不得用於聚光。
播放器的元件層規約
把多張示意圖串成一條流程的多步播放器（模式層的說明見 零截圖文件示意）還沒有收進本元件庫， 但它的元件層規約已經定稿。這四條都是實作時會踩到的，與模式無關：
上面那條〈初始畫面不能取決於瀏覽器環境〉是它的第一條前提，不重複寫。
減少動態偏好：預設展開，不輪播
開啟「減少動態」的使用者，看到的應該是全部展開的靜態版本， 而不是「一樣會輪播，只是沒有轉場動畫」。
理由：這個偏好設定的訴求不是「不要轉場特效」，是不要有東西自己在動。 自動輪播本身就是那個東西。
控制項要夠大
輪播控制列的預設長相通常是兩個小箭頭加一排小圓點。那是給示意用的，不是給人點的。
| 控制項 | 規格 | 為什麼 |
|---|---|---|
| 上一步／下一步 | 文字按鈕（「‹ 上一步」），桌機 36px 高 | 純箭頭在觸控裝置上難點，而且讀屏念不出來 |
| 步驟圓點 | 視覺 10px，命中區 28px | 圓點大小是視覺需求，命中區是可用性需求，兩者不必相等 |
| 全部控制項 | 觸控裝置由 tap-target 撐到 44px | 見無障礙四原則 |
字幕要獨立一行放在按鈕上方，不要和按鈕擠在同一列—— 字幕長度會變，擠在一起時按鈕位置會隨著步驟跳動。
小螢幕：讓示意圖自己捲
示意圖有最小寬度（低於它版面會擠壞，反而失去示意的作用）。 窄螢幕的正解是讓步驟容器可以橫向捲動，不是讓示意圖跟著縮排。
.flow-step { overflow-x: auto; }
.mock-frame { min-width: 460px; }
讓示意圖自己捲，頁面不捲。
不要讓整個頁面出現橫向捲軸。讀者會以為是版面壞了， 而且一旦頁面能橫向捲，文字段落的閱讀也跟著壞掉。
字幕格式
| 位置 | 格式 |
|---|---|
| 每一步 | ① ② ③ 開頭 ＋ 一句「做什麼」 |
| 最後一步 | 盡量寫「完成後你會看到：…」 |
| 單張示意圖 | 標題＝一句話主旨；字幕＝一句補充（位置或後果） |
「完成後你會看到」這句的作用是給讀者一個驗收條件。 沒有它，讀者做完最後一步之後不知道自己做對了沒有，於是會再做一次—— 而在後台系統裡，「再做一次」經常就是重複送出。
一張示意圖最多一個聚光。次要資訊用徽章或提示框呈現。
不要一張圖圈三個地方。三個重點等於沒有重點， 而讀者會開始懷疑自己是不是漏看了第四個。
取捨
示意圖不會百分百等於實際畫面（版面是簡化的）。這是刻意的—— 讀者需要的是「該點哪裡」，不是像素級復刻。
列印
.mock-placeholder 在列印樣式下補淡邊框：部分印表機仍會剝掉背景色，
補邊框至少保留形狀與標籤。詳見 列印與匯出。
取用
npx shadcn@latest add https://kielchang.github.io/dooping-design-book/r/mockup.json
延伸閱讀：模式 → 零截圖文件示意