登陸頁面建構
將已批准的文案、視覺方向與設計 Token 轉化為一個在 JavaScript 關閉時仍完整的靜態頁面。完整意味著訪客可以閱讀每個區塊、從頁首到達每個區塊,並提交表單。動畫與 3D 效果則後續由 landing-skills:landing-motion 實現,並建立在原本就能正常運作的頁面之上。
在未使用此技能的測試建構中,曾出現兩個錯誤,而此技能的設計正是為了讓這兩個錯誤不可能發生:
- 一個帶有
padding縮寫的容器類別覆蓋了區塊的垂直間距,導致每個區塊相鄰貼合。解決方案是結構性的:區塊擁有區塊軸,容器擁有內聯軸,且兩者均不使用縮寫(步驟 5)。 - 一個失效的表單:
action="#"、onsubmit="return false",或是一個顯示「謝謝」但丟棄資料的腳本。解決方案是:真實的action、真實的method、伺服器端的成功頁面,且不顯示頁面無法驗證的成功訊息(步驟 8)。
輸入
在撰寫程式碼之前,從使用者的專案中讀取這些資料。
| 檔案 | 你從中取得的內容 |
|---|---|
landing/brief.md | landing-skills:landing-page 寫入的欄位。使用:語言(用於 lang);轉換動作(表單及其欄位與端點,或 none yet,或外部 URL);技術棧(依名稱,或 detect);網域(正式上線網域,或 unknown);聯絡路徑(用於頁尾與 /form-error/);可用的資產 |
landing/copy.md | 每個頁面區塊一個 H2,按頁面順序;最後一個 H2 Placeholders 列出所有空缺 |
landing/direction.md | 字型系列及其來源與授權、每個區塊的佈局行、圖片及其長寬比、表面材質,以及最後的 H2 Motion and 3D intent |
landing/tokens.css | 自訂屬性:--color-*、--font-*、--text-*、--space-*、--radius-* |
當缺少某個輸入時:
- 缺少
copy.md:不要自行撰寫行銷文案。請使用者提供文字,或建議landing-skills:landing-copy。如果使用者提供了文字,就按原文使用。切勿虛構證明:沒有推薦、標誌、統計數字或評分。缺少的部分變為[PLACEHOLDER: 需要什麼]。 - 缺少
direction.md或tokens.css:首先建議landing-skills:landing-art-direction。如果使用者堅持繼續進行,自行撰寫landing/tokens.css,包含五個前綴,從使用者提供的品牌約束推導出數值,並告知使用者這些 Token 是暫定的。 - 缺少
brief.md:詢問語言、轉換動作(表單及其提交位置,或外部 URL)、正式上線網域與聯絡路徑。 - 簡報中的欄位值為
unknown或none yet時,視為空缺而非錯誤:依照此技能為其制定的規則建構(無網域則不加入 URL 標籤,無端點則使用/api/lead佔位符,無聯絡路徑則使用佔位聯絡行),並在交接清單中列出。根據專案檔案偵測技術棧(請參閱「技術棧偵測」),而非在可以偵測時還提問。
流程
1. 偵測技術棧
使用「技術棧偵測」表格。在撰寫檔案前,先閱讀 references/adapters.md 的對應章節;它僅涵蓋與其他參考資料中純粹範例不同的部分。
2. 製作清單
在任何標記之前,請先記錄:
copy.md中的每個 H2 及其對應的<section>,並附上id。tokens.css中的每個 Token 名稱。你只會使用這些名稱來設定顏色、字型、間距與圓角。- 視覺方向要求的每張圖片、其長寬比,以及檔案是否存在。
- 簡報中的轉換動作:外部 URL(連結,無表單),或表單及其欄位與端點。當端點為
none yet時,表單提交至/api/lead,並將該空缺記錄在交接清單中(步驟 11)。 - 網域(已知或
unknown)與聯絡路徑,這些是<head>、頁尾與/form-error/所需的。
3. 撰寫
標題、描述、標準鏈結、Open Graph 與社群卡片、Favicon 組、theme-color、lang、結構化資料。範本與規則在 references/seo-meta.md 中。從 copy.md 撰寫標題與描述;使用框架的預設標題(如 starter title)是一個明顯的缺失。
4. 載入字型
自行託管視覺方向中指定的 WOFF2 檔案,使用與 tokens.css 字型堆疊完全相符的名稱宣告 @font-face,加入一個符合度量標準的回退字型,並僅預載入首屏使用的檔案(最多兩個)。references/performance.md 提供了做法與一個經測試的腳本,可計算回退值。一個指定了字型但從未載入,或回退到 system-ui 的頁面,在不同機器上渲染效果會完全不同。
5. 建構佈局骨架
頁面的每個帶狀區塊都是一個 <section class="section">,內部包含一個 <div class="container">。兩者功能永不混淆:
/* 區塊掌管垂直韻律,容器掌管寬度與內距。 */
.section { padding-block: var(--space-section-open); }
.container {
inline-size: min(100% - 2 * var(--space-gutter), var(--space-content-max));
margin-inline: auto;
}
上述 Token 名稱僅為範例;請使用你的 tokens.css 中的名稱。references/css.md 列出了每個範例假設的 Token 角色,以及當你的檔案缺少某個 Token 時的處理方式。
容器完全不設定內距,因此沒有任何規則順序或特異性可以抹除區塊的間距。絕對不要在 section 或 container 類別上使用 padding 或 margin 縮寫:縮寫會同時設定兩個軸,並靜默地取代另一個類別設定的值。這就是消除錯誤 1 的規則。references/css.md 展示了錯誤版本與正確版本並列,以及滿版出血與細線的案例。
6. 建構區塊
- 使用語義元素:
header、nav、main、section、footer、步驟使用ol、規格使用dl或table、含標題的媒體使用figure。 - 一個
h1,放在 Hero 區。每個區塊以取自copy.md的h2開頭。不要跳過標題層級。 - 依照
direction.md中該區塊的佈局行來安排佈局。當視覺方向未明確指定形狀時,從references/css.md中的範例中選擇;區塊的數量與形狀應跟隨內容,因此只有當內容確實是三樣相等的東西時,才使用三個相等的卡片。 - 使用 Token 設定每個顏色、字型、大小、間距與圓角。絕對不要在頁面 CSS 中重新宣告 Token。如果所需的值沒有對應的 Token,則從 Token 組合而成(使用
calc()、color-mix()),並在交接清單中記錄,以便視覺方向後續可以加入。 - 使用
clamp()實現流體尺寸、使用邏輯屬性、使用oklch()色彩(附上references/css.md中的回退方案),並為會隨自身寬度改變形狀的元件使用容器查詢。
7. 放置媒體
真實圖片要設定 width 和 height、描述圖片內容的 alt 文字、使用現代格式並附回退方案,且僅在 Hero 圖片上使用 fetchpriority="high"(references/performance.md)。尚未存在的資產則變成一個可見、有標籤的佔位框,保持最終的長寬比,並包含類似 [PLACEHOLDER: 照片,從上方看的工坊工作檯,3:2] 的文字。不要為此框設定 role="img":這會宣告一張不存在的照片。為每個佔位框設定視覺方向指定的長寬比、寬度與背景,使框架能顯示出規劃的佈局,而非一列相同的虛線框(references/css.md,媒體佔位符)。絕對不要繪製假的產品螢幕截圖並將其呈現為產品。
8. 建構轉換動作
簡報的轉換動作決定了你要建構的內容:
- 外部 URL(結帳頁面、預約頁面、應用程式商店):動作是一個連結,
<a class="button" href="https://...">,標籤來自copy.md。沒有表單、沒有form.js、沒有/thanks/或/form-error/頁面;跳過此步驟的其餘部分。如果簡報表示需要計算點擊次數,則由landing-skills:landing-launch加入信標。 - 表單且使用者已有端點:表單提交至該 URL,且不使用
/api/lead佔位符。僅在該端點會重導向至結果頁面時才建構結果頁面;否則在交接清單中說明端點將訪客導向何處。 - 表單且端點為
none yet:表單提交至佔位符/api/lead,由landing-skills:landing-launch建構成一個 Worker。
對於表單,請閱讀 references/forms-a11y.md。不可協商的部分:
<form action="..." method="post">,使用簡報中的端點,或action="/api/lead"並在其旁加上 HTML 註解說明該端點尚未存在,並記錄在交接清單中。- 每個欄位都有
name、可見的<label>、正確的type與autocomplete,並在需要解釋格式時使用aria-describedby連結提示。 - 在不使用 JavaScript 的情況下,瀏覽器提交表單,端點以
303重導向回應至你現在建構的兩個靜態頁面之一:/thanks/和/form-error/。一旦landing-skills:landing-launch加入了 Turnstile,沒有 JavaScript 的訪客將沒有 Token,並總是到達/form-error/,因此該頁面必須提供另一種聯繫方式,取自簡報的聯絡路徑。 - 始終將
references/forms-a11y.md中的form.js作為漸進增強的一部分一起提供。表單在沒有它的情況下仍可運作;該檔案仍是建構的一部分,因為landing-skills:landing-motion會擴展它所設定的狀態,而landing-skills:landing-launch會檢查它們。它僅在回應是 2xx 且其 JSON 主體顯示ok: true時才顯示成功。僅 2xx 只能證明有東西回應了:fetch會跟隨重導向並將最終頁面報告為 200,而靜態主機可以用普通的 HTML 頁面回應 POST。這兩種情況都在測試中發生過,且都是失敗。失敗時,腳本會告知並保留訪客輸入的內容。在伺服器確認之前,絕對不要重設表單或顯示「謝謝」。
9. 達到無障礙基本要求
跳過連結、地標、指向真實區塊 ID 的 nav 連結、連到 / 的標誌連結、每個可互動元素上的可見焦點樣式、目標至少 44x44 像素,以及對頁面實際渲染的每個文字與背景組合進行對比度檢查:每個表面上的正文文字、說明文字、提示、佔位符文字、強調色上的文字。詳細資訊與數字在 references/forms-a11y.md 中。一個在手機上隱藏連結且沒有替代方案的導覽無法達到此基本要求;請改為讓連結換行。
10. 排除動畫
在減少動畫模式下,被減少的是移動,而不是回饋,因此不要撰寫全域規則來將轉場歸零。以最終的可見狀態建構每個元素。不要有入場動畫、不要有等待腳本的 opacity: 0、不要有滾動函式庫。
對於視覺方向中 Motion and 3D intent 命名的每個時刻,留下一個替代品:靜止的海報圖片,或一個有標籤的佔位符,保持該時刻的最終尺寸與長寬比,以便在 landing-skills:landing-motion 掛載真實內容時佈局不會位移。使用 data-moment="<name>" 標記它,name 使用視覺方向為該時刻指定的簡稱;動畫效果會根據此屬性找到目標。替代品在沒有動畫的情況下應是完整的:真實圖片需有 alt 文字,或使用說明該時刻內容的佔位符文字。
<div class="hero__media" data-moment="exploded-view">
<img src="/img/exploded-poster.jpg" width="1600" height="1000" alt="裝置的層層分解:外殼、電路板、電池、鏡頭">
</div>
當意圖為 none 時,不要加入任何 data-moment 元素。
11. 檢查並交接
執行「完成定義」。然後用一個簡短的列表告知使用者:
- 建構了什麼以及位置(檔案、輸出資料夾),以及如果簡報的 Stack 欄位為
detect則寫入的解析後技術棧, - 頁面上仍存在的所有
[PLACEHOLDER: ...]以及需要提供的所有資產, - 已建構的轉換動作:連到外部 URL 的連結、提交至使用者端點的表單,或提交至
/api/lead(尚不存在)的表單, - 表單提交的每個欄位,每個一行:其
name、類型(email、tel、text、textarea)、是否為required,以及來自標記的maxlength。landing-skills:landing-launch會根據此列表設定其 Worker 的驗證、長度上限、儲存與請求大小限制,並拒絕它未被告知的欄位, - 因缺少 Token 而組合成的數值,以及
tokens.css缺少的每個可選 Token 及其使用的回退方案, - 如果簡報說
unknown則為正式上線網域,以及因此省略的 URL 標籤(標準鏈結、og:url、og:image、Sitemap), - 簡報中為
unknown的聯絡路徑,在頁尾與/form-error/中以佔位符顯示, - 每個未子集化的字型檔案及其大小(以位元組為單位),
- 每個未被執行的完成定義檢查,標記為「未執行」並附上原因,
- 來自
Motion and 3D intent的每個時刻:其data-moment名稱及其替代品的位置(區塊與元素),若意圖為none則為「無」, - 下一個技能:當視覺方向的
Motion and 3D intent命名了時刻時為landing-skills:landing-motion,然後是landing-skills:landing-review,最後是landing-skills:landing-launch(用於託管與表單端點)。
技術棧偵測
依下列順序檢查專案根目錄,並在第一個符合時停止。當專案資料夾為空時,由 brief.md 中的 Stack 欄位決定。
一旦解析出技術棧,就將其寫回:如果簡報的 Stack 欄位為 detect,則將該詞替換為解析後的技術棧(例如 Astro,或 plain HTML and CSS),且不修改 landing/brief.md 中的其他內容。後續的技能會讀取此欄位,不應再遇到未解析的詞。使用者已命名的技術棧則保持不變。當沒有 landing/brief.md 時,不要建立一個。
| 專案中的信號 | 技術棧 | 適配器章節 |
|---|---|---|
astro.config.mjs(或 .ts、.js),或 astro 在 package.json 依賴中 | Astro | Astro |
…
[為翻譯而截斷]
