Communitygithub.com

wuongg/wait_skills

定義「landing-page-composition-architect」(規劃者)與「cinematic-landing-page」(建構者)之間的交接合約。包含 Blueprint JSON 格式、版面系列到視覺原型的對應、建構者必須遵守的不變規則,以及雙方都必須拒絕的失敗模式。每當 Composition Blueprint 被交接,或建構者即將在沒有鎖定藍圖的情況下編寫頁面時,請閱讀此文件。

wait_skills 是什麼?

此技能定義了一個嚴格的分工合約,將登入頁面的設計與開發拆分為兩個明確的角色:「規劃者」(landing-page-composition-architect)負責決定頁面的「結構與順序」,並輸出一個鎖定的 Composition Blueprint JSON;「建構者」(cinematic-landing-page)則負責決定頁面的「視覺與動畫」,並根據 Blueprint 產生 Build Spec 後才開始編寫程式碼。 技能的核心價值在於防止任何一方越界:規劃者不得指定視覺風格,建構者不得更改頁面結構。它詳盡定義了共 15 種版面系列(Layout Family)如何映射到 6 種視覺原型(Archetype A-F)、8 條翻譯規則(涵蓋動畫預算、CTA 處理、情緒對應等)、以及嚴格的驗證關卡(Validation Gate)。任何違反合約的行為都會觸發結構化的修訂請求(Revision Protocol),而非偷偷修改。 此技能主要用於 Claude Code 等 AI agent 平台,確保複雜的登入頁面專案能在不同專家模型之間無縫且可靠地交接。它支援 V1(純 vanilla)與 V2(React + Vite + Tailwind)兩種技術堆疊,並內建了針對六種常見商業意圖(Launch、Conversion、Brand 等)的預設原型選擇,大幅減少溝通成本。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/wuongg/wait_skills/tree/HEAD/.cursor/skills/landing-page-skills-integration

在你喜歡的 AI 中提問

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

說明文件

Landing Page Skills — 整合合約 v1

兩個技能,一條管線:

User brief
   │
   ▼
[ landing-page-composition-architect ]   ← 決定「什麼」&「順序」
   │  輸出:Composition Blueprint(鎖定)
   ▼
[ INTEGRATION.md  ← 本文件 ]            ← 將 blueprint 轉譯為 build spec
   │  輸出:Build Spec(原型 + 動畫 + 技術堆疊)
   ▼
[ cinematic-landing-page ]               ← 決定「外觀」&「動畫」,撰寫程式碼
   │
   ▼
Shipped page

黃金法則。 規劃者擁有結構。建構者擁有表面。 兩者皆不可越界。本文件是他們保持誠實的方式。


1. 交接產物 — Composition Blueprint (JSON)

規劃者的最終產物必須能夠渲染成此 JSON 格式,即使它以表格形式呈現給使用者。建構者將逐字讀取此 JSON。

{
  "blueprint_version": "1.0",
  "page": {
    "intent": "I1 | I2 | I3 | I4 | I5 | I6",
    "intent_name": "Launch | Conversion | Brand | Portfolio | Product Story | Campaign",
    "awareness": "cold | warm | hot",
    "traffic": "ads | organic | social | referral | direct",
    "narrative_spine": "Hook -> Value -> Proof -> CTA",
    "pace": "fast | balanced | slow-burn",
    "density": "minimal | balanced | rich",
    "primary_emotion": "string (one word)",
    "total_sections": 5
  },
  "sections": [
    {
      "index": 1,
      "slot": "S1",
      "name": "Hero",
      "jtbd": "grab attention + set tone",
      "why_here": "first impression",
      "layout_family": "full-bleed hero",
      "content_required": ["headline", "subcopy", "hero_media"],
      "visual_weight": "very high",
      "cta_role": "soft"
    }
  ],
  "rhythm_rules": [
    "No two 'very high' weight sections adjacent.",
    "After any full-bleed hero or mood gallery, next must be centered statement or editorial block.",
    "Primary CTA appears exactly once."
  ],
  "kill_list": [
    "No FAQ",
    "No 6-card feature grid",
    "No metric band"
  ],
  "handoff_note": "One paragraph: emotion to preserve, which slots want cinematic treatment, which stay quiet.",
  "locked": true
}

不變規則。

  • sections.length ∈ [4, 9];標準意圖為 5–8。
  • 每個 slot ∈ {S1..S16},在頁面中唯一。
  • layout_family 屬於封閉列表(參見 §3)。
  • locked: true 是一個承諾:建構者不得重新排序、新增、刪除或重新命名區段。

2. 建構者可以決定的事項(以及不可決定的事項)

建構者可以決定

  • 電影級原型(A/B/C/D/E/F,來自 cinematic-landing-page)。
  • 動畫簽名、緩動曲線、滾動行為。
  • 色彩氛圍、字體排版、間距比例。
  • 媒體處理(顆粒、模糊、邊框、去背)。
  • 技術堆疊(V1 vanilla vs V2 React+Vite+Tailwind)。
  • 微文案潤飾(只要不改變意圖)。

建構者不可決定

  • 區段數量。
  • 區段順序。
  • 哪個 slot 對應到哪個位置。
  • 某個區段是否存在。
  • 重新命名 slot 的目的(使用者面向的名稱可以更改;JTBD 不可更改)。
  • 新增 blueprint 中未包含的區段(無預警的 CTA 橫幅、無預警的訂閱區塊)。
  • 移除主要 CTA 或重複它。

如果建構者認為 blueprint 有誤,它必須停止並要求重新規劃,而不是悄悄修改。


3. 版面系列 → 視覺原型對應表

規劃者使用版面系列。建構者使用電影級原型(A–F)。以下是轉換表。

版面系列(規劃者)主要原型(建構者)備用方案備註
full-bleed heroA (Fixed-Viewport Hero)B若氛圍 = premium,使用 framed-canvas 變體
split heroA (pattern: split)D左側文案 / 右側媒體
centered statementD section OR A (centered)—低動畫,高可讀性
benefit railD card row—3–4 個項目,不超過圖示+標題+一行文字的卡片
card gridD grid—最多 6 個區塊;在 I3 中停用懸停動畫
staggered stackD asymmetric sectionB交替的圖片/文字列
editorial blockD editorialF (if display type)長篇形式;避免卡片 UI
mood galleryB (sticky scroll) 或 E (switcher)—根據節奏選擇:slow-burn→B, balanced→E
logo stripD quiet row—除非要求,否則不添加跑馬燈以外的動畫
metric bandD big-number row—僅在節奏非 slow-burn 時使用計數動畫
quote panelD 或 A single-scene—單一引述 > 輪播
accordion listD accordion—在 I3 中被禁止(參見 kill list)
CTA bandD centered CTAA主要 CTA 在此
sticky footer CTAD sticky footer—僅在節奏 = fast 時使用
soft footerD minimal footer—頁尾安靜退出

每頁原型上限。

  • 每頁最多 2 個簽名原型(繼承自 cinematic-landing-page 規則)。
  • Hero 區段選擇主導原型。除非規劃者的 handoff_note 明確要求電影級處理,否則其他區段預設使用 D 風格執行。

基於意圖的原型預設值(當規劃者未提示時):

意圖主導原型第二原型(可選)
I1 LaunchAE
I2 ConversionA (split)— (stay quiet)
I3 Brand EditorialF 或 BE
I4 PortfolioF 或 CB
I5 Product StoryA + B (scroll story)—
I6 Campaign / TeaserA 或 F—

4. BUILD SPEC — 建構者在撰寫程式碼前產出的產物

在撰寫任何一行程式碼之前,建構者必須根據 Blueprint 產生一個 Build Spec。這是管線中的第二份合約。

{
  "build_spec_version": "1.0",
  "blueprint_ref": "locked",
  "stack": "V1 vanilla | V2 react-vite-tailwind",
  "dominant_archetype": "A | B | C | D | E | F",
  "second_archetype": "A | B | C | D | E | F | null",
  "mood": "Dark Cinematic | Warm Editorial | Neo-Tech | Light Minimal | Light Editorial | Soft Glass",
  "sections": [
    {
      "index": 1,
      "slot": "S1",
      "layout_family": "full-bleed hero",
      "archetype": "A",
      "pattern": "framed-canvas",
      "motion": ["hero_fade_in_800ms", "subcopy_delay_200ms"],
      "media": {"type": "image | video | none", "asset_ref": "…"},
      "notes": "why this archetype was chosen for this slot"
    }
  ],
  "acceptance_criteria": [
    "First viewport = S1 composition only.",
    "Primary CTA in S15 exactly once.",
    "No adjacent 'very high' weight sections.",
    "Motion count on page <= 2 signatures."
  ]
}

建構者在撰寫程式碼之前,必須先根據 Blueprint 驗證 Build Spec(參見 §6)。驗證失敗則關閉。


5. 轉換規則(規劃者 → 建構者)

依序套用。

T1. 區段順序即法律。 blueprint 中的 sections[i].index 即頁面上的位置。建構者不得重新排序。

T2. Slot → 原型資格。 使用 §3 表格。如果某個版面系列的主要原型與 hero 已選擇的主導原型衝突,則使用備用方案。

T3. 權重 → 動畫預算。

視覺權重動畫預算
very high最多 2 個簽名互動
high1 個簽名互動
medium僅微互動(懸停、小淡入淡出)
low僅淡入淡出
very low靜態

T4. CTA 角色 → 表面處理。

CTA 角色處理方式
primary完整按鈕 + 表單/錨點,高對比度
hard按鈕,高對比度,無表單
soft帶箭頭的文字連結
none不渲染任何 CTA 元素

T5. 情緒 → 氛圍對應(建議性)。

primary_emotion(規劃者)建議氛圍(建構者)
reverence, calm, luxuryDark Cinematic / Soft Glass
clarity, trust, precisionLight Minimal / Neo-Tech
warmth, human, storyWarm Editorial / Light Editorial
energy, urgency, hypeNeo-Tech / Dark Cinematic

T6. 節奏 → 滾動長度。

節奏總滾動長度(桌面)
fast≤ 2.5 個視口
balanced3–5 個視口
slow-burn5–8 個視口

T7. 密度 → 元件選擇。

  • minimal → 偏好純文字區段,寬留白。
  • balanced → 混合文字與媒體。
  • rich → 偏重編輯區塊;仍須遵守 kill list。

T8. Kill list 是絕對的。 kill_list 中的任何項目在 Build Spec 和程式碼中都是禁止的,即使它「看起來很酷」。


6. 驗證關卡(在撰寫任何程式碼前執行)

建構者根據 Build Spec 執行此檢查清單。所有項目都必須通過。

  • 每個 blueprint 區段在 build_spec.sections 中恰好有一行。
  • index 值是連續的,從 1 開始。
  • 未新增、移除、重新排序或合併任何區段。
  • 每行的 layout_family 與 blueprint 相符。
  • 主導原型由 hero 區段使用(index: 1)。
  • 頁面上的簽名原型總數 ≤ 2。
  • 所有區段的「簽名互動」總數 ≤ 2。
  • 主要 CTA 計數 = 1(或 0 僅在 intent = I3 且以 soft-footer 結尾時)。
  • spec 中未出現 kill_list 中的任何項目。
  • 遵守 Awareness 關卡:cold ⇒ S2 緊跟在 S1 之後。
  • 無禁止的相鄰關係(S6+S9、S11+S13 等)。

失敗 → 返回規劃者並附上 revision_request(參見 §7)。不要在未通過的關卡上繞道編碼。


7. 修訂協定

如果建構者必須退回,它會發出結構化的請求,而不是自由文字:

{
  "revision_request": {
    "reason": "layout_conflict | asset_missing | motion_budget_exceeded | kill_list_impossible | adjacency_violation",
    "affected_sections": [3, 4],
    "explanation": "one short paragraph",
    "suggested_fix": "swap S6 and S9 order | drop S13 | downgrade S1 weight to high"
  }
}

規劃者回應一個全新的鎖定 blueprint,而不是一個修補說明。Blueprint 將以 blueprint_version 的版本號來完整重新發布。


8. 雙方都必須拒絕的失敗模式

規劃者必須拒絕:

  • 發出未鎖定的 blueprint。
  • 發出少於 4 個或多於 9 個區段。
  • 包含使用者無法提供的 content_required 的 slot。
  • 重複使用 slot ID。
  • 跳過 S1 或(通常)S15。
  • 選擇 §3 封閉列表之外的版面系列。

建構者必須拒絕:

  • 在沒有鎖定 blueprint 的情況下編寫程式碼。
  • 在沒有通過 §6 的 Build Spec 的情況下編寫程式碼。
  • 「因為頁面感覺太空」而新增區段。
  • 「因為感覺多餘」而刪除區段。
  • 使用超過 2 個簽名原型。
  • 忽略 kill list。
  • 悄悄將 primary CTA 降級為 soft。

如果使用者直接要求違規,先回應一次權衡說明,然後僅在使用者明確確認時才遵從——並在 Build Spec 中受影響的行記錄為 "user_override": true。


9. 最小端到端範例

Blueprint(規劃者輸出,簡化版)

  • 意圖:I2 Conversion, cold, ads, balanced pace, balanced density。
  • 區段:S1 → S2 → S4 → S5 → S6 → S12 → S13 → S15
  • Kill list:無 S8, 無 S9, 無 S14, 無 S11。
  • 主要情緒:clarity。

Build Spec(建構者輸出,簡化版)

  • 堆疊:V2 (React + Vite + Tailwind + framer-motion)。
  • 主導原型:A (split hero)。第二原型:無。
  • 氛圍:Light Minimal。
  • 使用的動畫預算:2 / 2(hero 分割揭示 + 指標計數動畫)。
  • S1 = A split hero。S2 = D centered statement。S4 = D editorial block。 S5 = D staggered stack。S6 = D card grid (4 tiles)。S12 = D metric band。 S13 = D quote panel (single pull-quote)。S15 = D CTA band with form。
  • 驗收:主要 CTA 一次(S15);無 S6/S9 相鄰;總滾動長度約 4 個視口。

驗證

所有 §6 檢查均通過。建構者繼續進行編碼。


10. 告知使用者的內容(腳本片段)

當從規劃者交接時:

"Blueprint 已鎖定。要切換到建構技能(cinematic-landing-page)嗎? 該技能將選擇視覺原型 + 動畫 + 程式碼,不會更改區段順序。"

當建構者拒絕 blueprint 時:

"此 Blueprint 在區段 {n} 存在衝突 — {原因}。我們將返回規劃者以發布新版本,而不是自行修改。"

當使用者要求強制覆寫時:

"如果強制這樣做,我們將在該區段標記 user_override: true。 頁面仍然可以建構,但節奏規則將被破壞 — 您確認嗎?"


整合合約結束。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能