SanyamPunia/verso

verso 是做什麼的？

將現有介面的一部分轉變為文藝復興盛期工作筆記本的一頁：鐵膽墨水褪成棕色，書寫在棉紙上。

參考文獻為李奧納多·達文西的五張素描：溫莎解剖筆記（RCIN 919070 背面）、萊斯特手稿攤開頁、維特魯威人、阿倫德爾手稿攤開頁以及福斯特手稿筆記本頁面。在首次轉換前，請先閱讀 references/style.md。該文件說明了風格的每個物理事實及其對應的 UI 設計決策。以下決策僅在參考該文件後才有意義。

本技能包含的檔案

• references/style.md 研究資料：紙張、墨水、手寫、構圖、帶有量測對比度的調色板，以及常見 UI 部件到手稿部件的對應表。
• assets/manuscript.css 主題作為純 CSS，作用域限定在 .ms-scope 下，並透過 data-ms-paper 提供四種紙張預設。所有數值的唯一來源。
• assets/defs.svg 四個 SVG 濾鏡（羽毛筆、自由手繪線條、毛邊、墨跡）。每個文件掛載一次。
• assets/sketches.svg 可放置於頁面上的鋼筆素描：幾何構造、機械結構、引導線、墨漬、帶有字母標記的光線、陰影填充實體。
• examples/ 兩個完整的轉換範例，每個都包含轉換前和轉換後的檔案：before.html 和 after.html（設定卡，使用 windsor 預設），以及 release-before.html 和 release-after.html（發行說明，使用 leicester 預設）。examples/index.html 將它們並排顯示，並可切換預設。請將 after 檔案視為完成的轉換必須達到的標準。

步驟 1. 確定作用範圍

使用者指定一個部分：一個檔案、一個組件、一個路由、一個選擇器或一個描述。僅轉換該部分，不影響其他部分。

• 如果未指定目標，請詢問。不要僅憑猜測就重新風格化整個應用程式。
• 找到該部分的根元素。所有主題都依附於該根元素上的一個 ms-scope 類別，因此應用程式的其餘部分不受影響。
• 如果該部分被其他畫面共用（例如設計系統的按鈕、佈局），請告知使用者並詢問是要轉換共用部分還是建立一個本地副本。

步驟 2. 先閱讀專案，再開始撰寫

• 了解專案的樣式處理方式：Tailwind、CSS modules、純 CSS、CSS-in-JS 函式庫、組件庫。將主題以該習慣用法移植。不要在已有樣式系統的專案中引入第二個樣式系統。
• 閱讀專案的規則檔案（CLAUDE.md、AGENTS.md 或類似檔案）。如果它禁止在組件中使用原始十六進位顏色，則先將 --ms-* 值作為 tokens 加入其唯一的樣式表中，然後再使用 tokens。如果它有字體比例或字體載入器，則透過該載入器加入三種字體（例如 Next.js 中的 next/font/google），而不是透過僅適用於純 HTML 的 @import 行。
• 保留專案自身的基礎樣式。透過變體或類別重新風格化其 Button，不要將其替換為原始的 <button>。

步驟 3. 一次安裝基礎元素

1. Tokens 和類別。 引入 assets/manuscript.css，或其在專案習慣用法中的等效物。在 Tailwind v4 中，tokens 放在 @theme 中，多層次的部分（.ms-page::before、.ms-frame、.ms-cast、.ms-button）放在 @layer components 中，因為偽元素堆疊不適合 utilities。
2. 濾鏡。 一次掛載 assets/defs.svg，放在作用域根元素內部或之前。在 React 中，將其製作成一個小組件。沒有它，框架和線條將呈現直線，毛邊效果消失，這是一個靜默失敗：請檢查它。
3. 字體。 EB Garamond（閱讀用）、IM Fell English（標題用）、La Belle Aurore（邊緣註記用）。僅載入使用的字重。

步驟 4. 選擇預設

根據部分的形狀選擇預設，參考 references/style.md 的第 6 節表格。簡而言之：

• windsor 適用於表單、設定和密集的工具面板，
• leicester 適用於文章、文件、發行說明、主視覺和空狀態，
• arundel 適用於儀表板、畫布和包含許多小部件的面板，
• forster 適用於狹窄的卡片、側邊欄、清單和行動裝置畫面。

在作用域根元素上設定為 data-ms-paper="..."。windsor 不需要屬性。使用者可以指定預設或手稿名稱，且以使用者指定為準。每個表面僅使用一種預設。

步驟 5. 逐一轉換部分

使用 references/style.md 中的對應表逐一處理該部分。最重要的規則如下：

• 表面。 該部分的根元素變為 .ms-page：紙張紋理、簾紋、直紋和鏈紋、毛邊。移除內部的白色或灰色表面。最多使用一個 .ms-repair 來處理需要分隔區塊的較亮區域。
• 卡片。 卡片變為鬆散的鋼筆框架（.ms-frame）或什麼都沒有。大多數群組不需要框架：空白和手繪線條即可分隔它們，如同在紙張上一樣。僅為那些屬於框註的少數區塊使用框架。
• 陰影。 每個 box-shadow 和 elevation 都變為陰影線（.ms-cast）或移除。這個主題中沒有柔和的灰色陰影。
• 圓角。 將圓角半徑替換為 --ms-radius（手繪半徑）或無。
• 顏色。 僅使用棕色墨水。本體文字使用 --ms-ink，次要文字使用 --ms-ink-2，標題文字使用 --ms-ink-3。品牌色變為赭紅色，每個表面僅使用一次：主要動作、連結和焦點環。
• 字體。 本體文字使用 EB Garamond，搭配舊式數字。標題使用 IM Fell。章節標題使用 IM Fell 斜體，下方加雙重手繪線。永遠不要在本體文字中使用手寫字體：它僅用於簡短註記。
• 輸入欄位。 輸入框變為一條有線條的線（.ms-input），文字區域變為多條有線條的線，核取方塊變為一個帶有叉號的墨水方塊（.ms-check）。保留真實的 <input> 和 <label>，僅改變其繪圖。
• 徽章和標籤 變為圓圈文字（.ms-circled）。
• 數值列表、統計資料和表格 變為分類帳（.ms-ledger）：手繪線條上的行，點狀引導線連接到數值，使用舊式數字。
• 圖示。 保留專案的圖示。將其設為墨水色調並透過 ms-ink 濾鏡處理。不要將其替換為 emoji 或字形。
• 圖片 使用 .ms-plate：深褐色，與紙張相乘混合。
• 圖表 變為鋼筆線條和陰影填充。無漸層。使用斜體字母命名點和區域（.ms-point），如同萊斯特手稿的圖表。
• 進度條、儀表軌道和滑塊軌道 變為維特魯威刻度（.ms-scale，搭配 --value）。保留元素的角色和 aria 值。對於原生的 <input type="range"> 或 <progress>，保留原生元素並在其後繪製刻度。
• 步驟編號、排名和索引 變為邊緣的圖形編號（.ms-figno），如同福斯特手稿。
• 變更的數值 是一個修正：<del> 以鋼筆劃掉，<ins> 以手寫字體表示。僅在 UI 已同時顯示舊值和新值時使用。
• 總計和細項 可以是一個演算總和（.ms-sum），如同阿倫德爾手稿。
• 長文字中的章節 以一個普通的首字大寫（.ms-initial）開始，並以一條畫線（.ms-endrule）結束，如同萊斯特手稿。

步驟 6. 將其組成一個工作頁面

直接將卡片網格轉換為棕色卡片是失敗的模式。重新組合該部分，使其看起來像一張被填寫過的紙張，而不是被設計過的：

• 使用 .ms-folio：主欄和一個邊緣。將次要的事實、提示和說明文字移至邊緣作為 .ms-note，並在必要時用引導素描指向它們的主題。
• 讓區塊的寬度不同。將素描放在文字內部，而不是放在自己的區域。
• 傾斜兩三個小區塊，使用 .ms-tilt-l、.ms-tilt-r 或 .ms-tilt-s。永遠不要傾斜表單欄位、表格或任何超過頁面約三分之一的區塊。
• 從 assets/sketches.svg 中添加一個適合主題的鋼筆素描：設定或系統使用機械結構，佈局、資料或量測使用構造圖。如果兩者都不適合，則以相同風格繪製一個新的。每個表面使用一個素描。
• 遵守一個表面的裝飾預算：一個素描（最多兩個）、一個污漬或墨漬、一個透印效果、兩個鏡像區塊。一個包含所有這些元素的頁面看起來像一套戲服。大多數表面只需要其中兩到三個，而不是全部。
• 用最多兩個裝飾性鏡像文字區塊（.ms-mirror，aria-hidden="true"）填充真正的空白區域。使用該時期風格的義大利語書寫（自我備忘、列表、測量值）。不要將其呈現為真實引文。
• DOM 順序保持閱讀順序。佈局可能會在視覺上移動元素，但原始順序必須對螢幕閱讀器和 Tab 鍵仍然有意義。

步驟 7. 安全規範

• 對比度。 真實文字永遠不使用 --ms-wash。測量任何新元素與紙張的對比度：文字為 4.5:1，有意義的圖形或控制項邊緣為 3:1。
• 鏡像文字永遠不是內容。 標籤、數值、錯誤訊息和說明文字必須保持可讀且方向正確。
• 語意保持不變。 元素、角色、名稱、狀態和事件處理常式保持相同。轉換後的組件必須與之前完全一致。
• 控制項保持可識別。 按鈕看起來仍可點擊，欄位看起來仍可輸入，焦點始終可見（赭紅色外框）。
• 動畫。 主題的動畫是墨水效果：素描使用 data-draw 自行繪製，核取方塊中出現標記。懸停和按下時是墨跡，而不是縮放。尊重 prefers-reduced-motion，manuscript.css 已經實作了這一點。
• 效能成本。 每個帶濾鏡的元素都是一次濾鏡傳遞。將濾鏡保留在偽元素、框架和素描上，而不是長列表的行或滾動內容上。不要在本文文字上使用 ms-ink。
• 無機構標記。 不要複製圖書館或收藏家的印章、博物館的目錄編號作為品牌標誌，或將李奧納多的名字當作簽名。頁面是仿效他的風格，而不是偽裝成他的作品。
• 僅淺色模式。 紙張是一個物體，因此不會在深色模式下反相。如果應用程式有深色主題，作用域部分會保留其紙張。

步驟 8. 驗證

1. 渲染轉換後的部分並截圖。如果有瀏覽器工具可用（agent-browser、Playwright、預覽窗格），請使用它。查看結果。
2. 檢查框架和線條是否呈現波浪狀。直線表示 defs 未掛載，或濾鏡 id 衝突。
3. 使用 Tab 鍵瀏覽該部分。每個控制項都應按合理的順序被觸及，並顯示焦點環。
4. 在手機寬度下檢查頁面。folio 佈局應摺疊為單欄。
5. 如果有的話，執行專案自身的檢查（類型檢查、lint、建置）。

報告

完成後，用幾行簡短的文字告知使用者：

• 變更了哪個部分以及哪些檔案，
• 使用了哪個預設，以及為什麼它適合該部分，
• 一次性地新增了哪些內容（tokens、字體、濾鏡）以及新增的位置，
• 任何未變更的部分及其原因，
• 如何查看結果（路由或要開啟的檔案）。