brandvm/webflow-style-guide

Webflow 風格指南：單一佈局，適用所有網站

風格指南是原型與 Webflow 中第一個建立的頁面，用於所有其他頁面之前。它先驗證變數、標籤樣式與類別的正確性，再讓其他頁面依賴它們；同時它將每個類別套用於某個元素上，因此 Webflow 的清除未用樣式永遠不會誤刪那些只被 CMS、腳本或尚未建構的頁面所使用的類別。

其佈局是固定的。專案只需提供內容，而非佈局：

• sg.css 是頁面本身的佈局樣式（Sg 類別）。
• scripts/gen-style-guide.mjs 根據 Webflow 快照、CSS 與專案的範例來產生頁面。
• scripts/check-style-guide.mjs 在類別遺漏於頁面、組合類別從未同時存在於同一元素，或佈局偏離時會失敗。
• scripts/sections.mjs 是兩個腳本共用的區段清單。
• 每個排版範例都帶有 data-sg-type（其名稱），讓原型的 pnpm measure:type 可以在 1440 與 390 寬度下輸出實際渲染的排版參數（尺寸、行高、字距、字重），以便在類別匯入 Webflow 前比對設計稿的排版表。

適用的共同規則（webflow-build › rules.md：Designer 優先，未經確認不得提交或推送），以及 Webflow 中的建構規則：每個批次皆需獲得許可。

佈局

框架。 左側為固定側邊欄，列出所有區段（含編號）並可連結至對應區段；當前閱讀中的區段會被標示。右側為一個內容欄。在 991px 及以下時，側邊欄會變成導航下方的一條水平滾動連結列。

為初次接觸的人設計。 頁面必須能讓從未見過該網站的人（如客戶或第一天上班的開發者）能夠理解。

• Overview（概覽）以頁面說明開頭，接著是四個使用卡片（如何找到頁面、如何閱讀一行、先複用再新增、在此處新增）、網站一覽（數量統計）、所使用的字型、變數集合與斷點。
• 每個區段以編號、標題及一行說明開頭（該文字位於 scripts/sections.mjs，每個網站都相同），說明該區段的用途與使用方式。
• 按鈕、表單與元件的範例位於面板（panel）上；類別名稱位於晶片（chip）中；長表格在滾動時會保持其名稱可見。
• 所有標籤使用網站本身的字型。不使用等寬字型：Designer 類別僅保留一種字型家族，而系統等寬字型則會帶來自己的斜線零。
• 框架從頁面取得顏色（中性線條與低透明度面板），因此在淺色或深色網站上顯示一致。

區段， 永遠按此順序排列，使用以下名稱與 id。若某區段無任何內容則可省略；不可新增、重新命名或重新排序。

#	區段名稱	id	來源
1	Overview（概覽）	overview	自動產生：使用說明、數量統計、字型、集合、斷點
2	Colors（色彩）	colors	所有不在 Colors Semantic 中的 Color 變數
3	Themes（主題）	themes	區段、所有設定 Colors Semantic 模式的類別，以及各模式的角色對照表
4	Typography（排版）	typography	所有設定 Typography Styles 模式的類別、原生標籤樣式（標題、段落、連結）、Body 樣式的字型特性，以及字型比例尺
5	Utilities（工具類別）	utilities	Size、Weight、Leading、Tracking、Text 與 Max Width 類別
6	Spacing, radius and layout（間距、圓角與佈局）	spacing	Spacing（每項附帶一條尺寸條）、Radius 與 Layout 變數
7	Buttons and links（按鈕與連結）	buttons	範例
8	Forms（表單）	form-elements	範例（項目使用 section=forms；Webflow 拒絕使用 forms 作為元素 id）
9	Components（元件）	components	範例
10	Page sections（頁面區塊）	page-sections	範例，以半尺寸畫面顯示
11	Other classes（其他類別）	other-classes	自動產生：以上所有類別未涵蓋的項目

一行（Row）。 頁面上的每個項目都是一個 Sg Row：左側顯示 Designer 所見的名稱、CSS 類別，以及白話說明（綁定什麼、各斷點的值、狀態）；右側則為即時範例。一個區段由一個標題與一列行組成。數值表（各模式的角色、字型比例尺、間距、佈局）則以一個 Sg Table 顯示在某一行的範例中：名稱欄，然後是每種模式或值一欄。

框架中不包含專案類別。 框架僅使用 Sg 類別，因此無論專案的排版比例尺或區段內距為何，頁面外觀都保持一致。專案類別僅出現在範例中。

變數是標準，而非限制

頁面顯示網站實際擁有的所有內容。範本中的集合、名稱與起始值（webflow-build 慣例 §4，包含預設字型 Geist）是變數的標準佈局與使用方式；專案可以自由更改數值，以及新增、重新命名或移除變數、模式與集合。

• 任何位於語義集合之外的 Color 變數會顯示為色票（swatch）；任何設定模式的類別會成為主題或排版列；任何產生器無法依角色識別的集合則會以表格形式顯示在「Spacing, radius and layout」區段中。
• 如果網站以不同名稱命名標準集合，需在 design/style-guide/config.json 中說明，例如： { "collections": { "semantic": "Themes", "typeStyles": "Type Styles" } } （keys：semantic、typeStyles、typeRole、typeScale、spacing、radius、layout）。
• 保持不變的是佈局：框架、區段順序、行的結構。

範例（區段 7 到 10）

有兩種方式提供範例；兩種方式會產生相同的行。

1. 來自真實頁面， 因此能與頁面保持同步。在頁面上包裹標記：

<!-- sg:start section=components | name=Card | class=.card | note=用於列表與首頁 -->
<a class="card" href="/work/item" data-card>…</a>
<!-- sg:end -->

2. 手動撰寫， 用於那些無法獨立在頁面上顯示的項目（例如按鈕狀態、表單部件）。每個區段一個檔案，置於 design/style-guide/items/ 中，每個項目由註解標頭與其標記組成：

<!-- sg: section=buttons | name=Button Is Secondary | class=.button.is-secondary | note=Button 的組合類別 -->
<a class="button is-secondary" href="#buttons">次要按鈕</a>

• section 可以是 buttons、forms、components 或 page-sections；name 為必填；class 與 note 為選填。
• 對於元件與頁面區塊，優先使用真實頁面區塊。手動複製的範例容易與實際頁面脫節，而在較早的建構中，用手動複製預覽所建立的元件曾遺失其腳本鉤子。
• 產生器會從範例中移除 ids、for、data-* 鉤子與 id 參考，並將其標記為 inert：這是元件的圖片，而非可運作的副本，因此不會有腳本附加，且其中沒有任何元素可獲得焦點。
• 頁面設有 noindex，因此頁面上可以安全地存在第二個 h1：Typography 區段會顯示一個真實的 h1 作為 All H1 Headings 標籤樣式的範例，而範例本身也可能包含一個。
• page-sections 範例會以半尺寸顯示在密封的框架中。當該頁面在 Webflow 中存在後即可移除該範例：屆時頁面會自行保留其類別。區段 1 到 9 則永久保留。
• 不使用內聯 style 屬性：Webflow 匯入器會將每個內聯樣式轉為雜湊組合類別。色彩色票、圓角框與間距條則改用每個變數各自對應的單一組合類別。

在原型中（第一頁）

1. 原型資料夾已存在（webflow-prototype › 專案設定）且其 Webflow 快照為最新（pnpm css）。
2. 執行 pnpm style-guide。它會產生 design/style-guide/index.html 與 src/css/style-guide.css。絕對不要手動編輯這兩個檔案。
3. 加入專案的範例（按鈕與表單項目；元件與頁面區塊隨著頁面建構逐步加入），然後再次執行。
4. 執行 pnpm check:style-guide 直到通過。
5. 審查人員需在 1440、820、667 與 390 四種寬度下檢視頁面，並在開始第一個內容頁面之前批准該頁面。
6. 從此刻起，每個新類別或元件都應在相同工作中加入對應行：新增範例、pnpm style-guide、pnpm check:style-guide。

在 Webflow 中（第一頁）

在變數、標籤樣式、類別與版本庫套件都就緒後，且在任何其他頁面之前。每個批次都需要獲得許可。

1. 頁面。 建立 /design/style-guide 於 design 資料夾中，使用標準外殼（webflow-build 慣例 §1）。在頁面 head 程式碼中加入 noindex, nofollow；排除於網站搜尋與網站地圖之外（網站地圖設定需要特定方案：若網站無方案，則 noindex 標籤即足以防止頁面被搜尋引擎收錄；一旦方案存在，即可設定排除）。指向該頁面的連結需執行完整頁面載入。
2. Sg 類別。 從 Starter 複製的網站已包含這些類別。否則，最快速且能保留所有數值的方式：使用 WHTML 建構器匯入框架，並將 sg.css 作為其 css 傳入（變數與 calc() 會替換為純數值，rgb(r g b / a) 寫為 rgba()）。匯入器會為每個類別建立長寫法屬性、狀態與斷點，並以其縮寫 slug 命名；之後再將每個類別重新命名為 Designer 應顯示的名稱（例如 Sg Row、Sg Row Meta、Sg Table Key……）。.w--current 規則應成為 Sg Sidebar Link 的 Current 狀態，這是樣式工具本身無法產生的。這個方法僅在類別為全新時有效：對於已存在的類別，匯入器會產生編號重複的類別（參閱 webflow-build/lessons/mcp.md）。
3. 變數組合。 對於每個色彩變數，建立組合 Sg Swatch Color + Is … 綁定 background-color；對於每個圓角變數，Sg Radius + Is … 綁定 border-radius；對於每個間距變數，Sg Bar + Is … 綁定 width。產生的 src/css/style-guide.css 會列出它們，每行一個。
4. 逐區段建構，從產生的頁面出發，僅使用類別。在匯入標記之前，先建立所有類別與組合（匯入器若發現任何類別遺漏，會放棄整個類別清單）。然後將每個側邊欄連結指向對應的區段（連結類型：頁面區段），以便 Webflow 標記當前區段。
5. 元件的行應使用元件實例（component instances），而非複製其標記。
6. 在 staging 環境檢查： 網站中的每個類別都應出現在已發布的頁面或外殼中；每個組合類別的類別應同時存在於同一元素上（如果組合類別僅分開出現，仍會被清除工具刪除）；側邊欄會反白顯示目前在視窗中的區段；noindex 存在於 head 中。只有在這些條件都滿足後，清除未用樣式才是安全的。

在既有網站上

非從範本建構的網站也可以獲得相同頁面：使用 webflow-prototype 技能的 Prototype Starter 建立原型資料夾，取得網站快照，然後依「在原型中」與「在 Webflow 中」的流程操作。其 Sg 類別尚未存在，需在步驟 2 中建立。

關卡

• 原型風格指南已批准 [人員]：在原型的第一個內容頁面之前完成。
• 風格指南基礎完成 [Claude 檢查，人員批准]：Webflow 頁面包含目前所有類別；已在三種寬度下發布並檢查。
• 風格指南最終檢查 [Claude 檢查]：在建構交接時，pnpm check:style-guide 通過，且已發布頁面包含所有類別。

變更佈局

佈局的變更應在此處進行，一次影響所有網站，而非在單一專案中修改：編輯 sg.css、區段清單或範本中的產生器，在同一個工作週期中更新 Starter 網站，然後發布該變更（webflow-build › rules.md › Contributing）。專案透過 pnpm update-skills 與 pnpm style-guide 取得更新。