Communitygithub.com

Im-Fran/landing-skills

用於實作登陸頁面(Landing Page)的程式碼,包含 HTML 結構、CSS、響應式佈局、字型、圖片、Meta 標籤、社群卡片、結構化資料、潛在客戶擷取表單、無障礙與載入效能,支援純 HTML、Astro、Next、Vite + React 或 Tailwind。

landing-skills 是什麼?

這是一個專門為 AI 代理(如 Claude Code、Cursor、Codex)設計的技能,用於從零開始建立功能完整的靜態登陸頁面。它強制執行一套嚴格的建構流程,從偵測開發框架、解析設計資產(文案、視覺方向、設計 Token)、到產生語義化的 HTML 與 CSS,並確保頁面在 JavaScript 關閉時仍能完整運作。此技能特別針對兩個常見錯誤提供結構性解決方案:一是不正確的間距覆蓋問題(透過區分區塊軸與內聯軸的類別來解決),二是失效的表單(強制使用真實的 action、method 與伺服器端成功頁面)。它支援 Astro、Next.js、Vite + React、純 HTML 與 Tailwind 等多種技術棧,並內建無障礙檢查、效能最佳化與手稿交接機制,確保最終產出可直接部署。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Im-Fran/landing-skills/tree/HEAD/skills/landing-build

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

預覽

來自技能 README

landing-skills preview

說明文件

登陸頁面建構

將已批准的文案、視覺方向與設計 Token 轉化為一個在 JavaScript 關閉時仍完整的靜態頁面。完整意味著訪客可以閱讀每個區塊、從頁首到達每個區塊,並提交表單。動畫與 3D 效果則後續由 landing-skills:landing-motion 實現,並建立在原本就能正常運作的頁面之上。

在未使用此技能的測試建構中,曾出現兩個錯誤,而此技能的設計正是為了讓這兩個錯誤不可能發生:

  1. 一個帶有 padding 縮寫的容器類別覆蓋了區塊的垂直間距,導致每個區塊相鄰貼合。解決方案是結構性的:區塊擁有區塊軸,容器擁有內聯軸,且兩者均不使用縮寫(步驟 5)。
  2. 一個失效的表單:action="#"、onsubmit="return false",或是一個顯示「謝謝」但丟棄資料的腳本。解決方案是:真實的 action、真實的 method、伺服器端的成功頁面,且不顯示頁面無法驗證的成功訊息(步驟 8)。

輸入

在撰寫程式碼之前,從使用者的專案中讀取這些資料。

檔案你從中取得的內容
landing/brief.mdlanding-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 依賴中AstroAstro

…

[為翻譯而截斷]

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

相關技能