hirowyh/settle

settle 是做什麼的？

將如「一個按起來手感很棒的開關」或「一個展示待辦事項 App 的短循環動畫」的請求，轉化為具有物理般自然動態的實際元件。每個元件的動畫手法一致，但視覺風格則根據每次請求重新設計，或繼承自使用者現有的專案。

以下路徑皆相對於此檔案所在的資料夾。從工作資料夾（專案根目錄或元件放置的資料夾）執行所有腳本時，請使用完整路徑：node <此資料夾>/scripts/deal.mjs …：腳本會將其產生的檔案寫入您執行指令的目錄。

請求執行流程

1. 讀取上下文。判斷是否在一個專案中：檢查是否存在包含框架名稱的 package.json，或是一個包含 HTML 頁面的資料夾。如果在專案中，請注意其撰寫樣式的方式、其 token 或主題設定的外觀，以及它已使用的任何動畫庫。然後閱讀請求：判斷它屬於 references/kinds/ 中的哪種結構、是展示用還是產品的一部分，以及其中的初學者用語代表什麼（references/words.md 提供了翻譯）。
2. 處理或繼承外觀。
   • 如果專案已有自己的外觀，則保留它：將該外觀對應到工作表的變數上，並只處理其所缺少的部分，使用 --keep palette,type。
   • 否則就處理外觀：node scripts/deal.mjs --brief "<一行描述的請求>" --kind <control, data-view, composite 或 flow>，並根據請求中的用語加上 references/words.md 提供的 flag。如果在專案中，請加上 --project，以便後續的元件繼承此外觀。建置外觀 1，即處理後的外觀：--pick 1。僅在外觀 1 與主題衝突時才選取外觀 2 或 3，並說明衝突原因：--pick 2 --because "早餐菜單的深色背景"。相關規則請參考 references/tokens.md。
   • 處理後的外觀會有一個「方向」，它決定了元件的裝扮；請求則設定其「形式」。請閱讀 references/directions.md 中該方向的章節，且每個方向都應在簡報之前，從最頂層開始閱讀。
3. 撰寫簡報或分鏡腳本。
   • 對於控制項、資料視圖或複合元件，用兩行陳述簡報並直接建置：說明它是什麼、該方向如何應用於此主題、外觀、簽名時刻，以及你選擇的預設值。「一個用於讀書網站的番茄鐘計時器。工具：計時器使用廚房計時器的錶盤，分鐘刻度圍繞錶圈；外觀 1，油灰與黑色；簽名時刻：開始按鈕變成逐漸減少的進度條；25 分鐘，5 分鐘休息。」
   • 對於隨時間變化的流程，或可能代表兩種完全不同意思的請求，展示分鏡腳本（格式請參考 references/kinds/flow.md）並等待確認。
   • 在開始建置前，先想像任何類似請求會得到什麼結果。然後修改簡報中與該想像相符的部分。
4. 在元件放置的位置進行建置。
   • 無專案： 一個基於 assets/page.html 或 assets/reel.html（如果是展示短片）的單一 HTML 檔案。它包含工作表、方向的頁面規則、完整複製到 head 模組腳本中的核心引擎（assets/kernel.js），以及 references/motion.md 中該元件所需的配方。
   • 有專案： 一個使用專案框架和樣式的元件。核心引擎作為模組複製一次，工作表則放在專案的全域樣式表中。references/stacks/ 中每個技術棧都有一個對應的說明文件。
   • 為已存在的元件添加動畫： 保留其標記和外觀，並為其每個狀態變化賦予文法所定義的動作（references/craft.md，第 3 節），透過閘門進行。
   • references/kinds/ 中的結構檔案會根據每個部分變化的類型，說明應該從哪些配方開始。
5. 檢查。使用 references/review.md 中描述的 lint 檢查檔案，並使用 snap.mjs 在該檔案或專案的開發伺服器上拍攝靜態圖框。修正聯絡表中看起來不正確的部分，然後再次拍攝，最多進行三輪。如果檢查時出現異常行為（例如拖曳吸附無法正確定位或伺服器無法啟動），則給予兩次嘗試機會；如果仍然失敗，則在交付時標記為未檢查。
6. 交付（如下所述）。

應閱讀的參考文件

檔案	閱讀時機
references/craft.md	每次建置：所有動作應遵循的規則、禁用清單和常見陷阱
references/tokens.md	每次建置：如何處理或繼承外觀，以及如何使用
references/directions.md	每次無專案的建置：已處理方向的章節
references/motion.md	每次建置：工作表、基礎頁面和配方，每個動畫一個
references/kinds/control.md, data-view.md, composite.md, flow.md	元件的結構：其構成和應從哪些配方開始
references/stacks/html.md, react-next.md, vue.md, svelte.md, astro.md	元件放置的位置：獨立檔案使用 html.md，否則使用專案的技術棧
references/words.md	請求描述了一種感覺，例如「讓它更突出」
references/review.md	檢查步驟

嚴格規則

• 元件應放置在使用者工作的位置。 在專案中：使用專案的框架和樣式，不引入新的套件，如果專案已有自己的動畫庫則使用它，並沿用 settle 的時間設定。無專案時：一個包含內嵌核心引擎的獨立 HTML 檔案，其唯一的外部請求是外觀所需的一個字型連結；它必須在系統字型下也能正常運作。如有請求，可取用一張真實照片放在元件旁邊。
• 請求設定形式。 控制項應保持其真實尺寸，小工具應保持一個卡片或面板的大小，只有當請求明確要求全螢幕時才使用全螢幕。對於整個登陸頁面或網站的請求，只建立其中的動畫部分（例如應用程式的輪播），使其可以嵌入到頁面中，並在交付時將頁面設計留給專門的頁面設計技能。元件周圍的空間保持簡單。
• 外觀來自工作表與方向。 所有視覺值都來自工作表的變數或其色調，包含一個底色、一個文字色和一或兩個強調色。已處理的方向決定元件的裝扮，深色背景僅用於發生在黑暗環境中的主題。
• 動畫來自核心引擎。 每個回應使用者操作或狀態變化的動作，都必須使用 settle.track、settle.stretch 或 settle.move 搭配來自外觀 register 的預設值來執行，即 settle.register()。
• 時間來自 settle.now()。 事件處理器設定目標值；一個 requestAnimationFrame 循環根據當前時間繪製所有正在動畫中的樣式。snap.mjs 會停止這個時鐘以檢查幀數。
• 形狀應延續。 每個新狀態都基於螢幕上已有的形狀建構，變化的文字會經過短暫的模糊效果，新的容器則從其背後固定元素的後方展開。
• 手勢引導。 拖曳的值應準確地位於游標下；超過限制後則遵循橡膠帶效果；放開時會保留手勢的速度。
• 真實內容。 使用合理的具體細節，且動作名稱在整個流程中保持一致。照片來自使用者，或當他們要求真實照片卻沒有提供時，來自 scripts/photo.mjs，並在元件中註明出處；否則僅使用程式碼清晰繪製的圖形，絕不使用風景圖片（references/directions.md，圖片部分）。
• 一個簽名時刻，其餘部分保持低調。
• 未經請求則禁用： references/craft.md 中的禁用清單內所有項目，lint 會標記它們。
• 為所有人設計。 支援滑鼠、觸控和鍵盤操作，具有可見的焦點指示和 44px 的目標尺寸。在 360px 寬的螢幕上可正常顯示，文字不小於 11px；在減少動畫模式下，彈簧效果會立即結束。
• 成本考量。 每次工具呼叫都會消耗使用者的額度。只建置一次，最多檢查三輪，異常的檢查給予兩次嘗試機會，腳本本身不做除錯：在交付時說明哪些是未檢查的。

展示用或產品用

展示用元件，例如登陸頁面的展示短片，應使用完整的動畫。產品內部的控制元件，使用者越常看到，動畫就應越少：每天使用上百次的元件不應有動畫，每天使用數十次的元件則使用快速且輕微的動畫。references/craft.md 中有相關表格（Emil Kowalski 的頻率規則）。

檔案放置位置

無專案時，在工作資料夾下以主題的簡短名稱命名（例如 tea-timer.html），除非使用者指定了路徑。在專案中，按照技術棧說明的指示放置，並以專案自身的風格命名，然後放置在一個使用者可以開啟的地方：如果請求未指定，則建立一個獨立的頁面或路由。將元件中可調整的數值統一放在腳本頂部：包括資料，以及任何 register 未設定的時間參數。

交付

回覆應包含：

• 元件的存放位置、如何開啟（檔案路徑，或路由及啟動開發伺服器的指令），以及一行關於它是什麼及其簽名時刻的描述。
• 兩到三個建議嘗試的操作：「將旋鈕拖到末端之外」、「按下 Tab 鍵，然後使用方向鍵」。
• 兩個可供調整的參數，名稱需與腳本頂部出現的一致。
• 如果有圖形暫代照片，說明照片應放置的位置：應被替換為 <img> 的元件。
• 如果有任何未檢查的項目，例如在真實手機上的 Safari 瀏覽器。
• 提供重新處理部分外觀的選項（node scripts/deal.mjs --redeal palette），並為模糊的請求提供三個不同的變體，並附上切換開關。

對於展示短片，提供匯出影片的選項：node scripts/export.mjs reel.html --out reel.mp4（或 --gif）會使用 ffmpeg 渲染，平均每個影格取四個子影格以實現動態模糊。

腳本

腳本	功能
scripts/deal.mjs --brief "…" [--tone …] [--register …] [--dark] [--project]	產生三個外觀；--pick <n> 會列印所選的工作表（並在加上 --project 時將其保留為專案的外觀）；--redeal <part> 會重新處理某個部分；--check 會檢查函式庫
scripts/lint.mjs <file>	對獨立檔案進行靜態檢查；如果出現 FAIL 則以 exit 1 退出
scripts/snap.mjs <file 或 url> --out <dir> --sheet [--size WxH] [--times …] [--do "…"] [--calm]	在停止的時鐘上使用真實輸入和聯絡表拍攝靜態圖框，然後執行頁面標題中列出的針對靜止頁面的檢查
scripts/export.mjs <reel> [--out reel.mp4] [--gif]	將展示短片匯出為 MP4 或 GIF，使用四子影格動態模糊
scripts/photo.mjs "<顯示的內容>" [--out photo.jpg]	獲取一張開放授權的照片（CC0、公共領域或 CC BY），儲存在執行位置，並在元件中附上出處行；僅在使用者要求真實照片時使用

這些腳本需要 Node 22 或更新版本和一個 Chromium 瀏覽器：snap.mjs 會在其常見位置找到 Chrome、Chromium、Edge 或 Brave，其他瀏覽器可透過環境變數 CHROME 指定。如果找不到任何瀏览器，它會一行說明：請根據 references/review.md 審查程式碼，並在交付時將幀數標記為未檢查。Export 還需要 ffmpeg，photo.mjs 則需要網路連線。無需安裝其他套件。

在無 shell 環境下

當無法執行腳本時（例如在沒有 shell 的聊天環境中）：請閱讀 library/directions.json、library/palettes.json 和 library/type.json，保留那些種類和語調與請求相符的條目，並根據請求字元長度在每個列表中循環計數來選取條目位置，這樣不同的請求會得到不同的外觀。使用相同的檔案進行建置，根據 references/review.md 中的評分標準審查程式碼，並在交付時說明幀數未經檢查。

致謝

• [Emil Kowalski 的技能](https://github.com/emil

…

[因翻譯而截斷]