品牌指南

品牌指南 是做什麼的？

建立一份 brand-kit.json 來描述使用者的產品，讓其他技能可以取用 — 包含色彩、字型、語調、應做/不應做語言、可選的標誌。其他 Cogny 技能（/tiktok-launch-video、/reddit-launch-video、/linkedin-launch-video、/landing-page-review、/ad-copy-writer）在存在此檔案時會讀取它。

此技能的設計核心是體認到 使用者並非總能存取其網站的原始碼。系統提供六條路徑來建立指南，按優先級排列。遇到第一個能取得足夠資訊的路徑即停止。

使用方式

/brand-kit https://example.com — 從即時網站中提取 /brand-kit ~/git/our-site — 從本機儲存庫（Tailwind / CSS 變數）中提取 /brand-kit ~/Desktop/logo.png — 從標誌或螢幕截圖中提取色調 /brand-kit ~/Desktop/homepage.png logo.png — 結合網站截圖與標誌 /brand-kit — 與使用者進行面談

輸出

brand-kit.json 將會寫入至（按優先級，選擇對使用者設定最合理的那個路徑）：

1. .agents/brand-kit.json（如果 .agents/ 目錄存在）
2. .claude/brand-kit.json（如果 .claude/ 目錄存在）
3. ./brand-kit.json（否則 — 目前的運作目錄）

務必列印出寫入的路徑，以便使用者可以移動檔案。

結構

{
  "name": "cogny",
  "site": "https://cogny.com",
  "logo": {
    "path": "./brand/logo-square.png",
    "use_in_video": false
  },
  "colors": {
    "background": "#1f1d1d",
    "foreground": "#ede8e3",
    "primary":    "#b09acd",
    "accent":     "#c9badf",
    "muted":      "#9a9494",
    "card":       "#282525",
    "fuchsia":    "#d4848a",
    "success":    "#7ec8a4",
    "amber":      "#d4a857"
  },
  "type": {
    "family":   "'JetBrains Mono', 'Fira Code', ui-monospace, monospace",
    "weight_display": 700,
    "weight_body":    500,
    "letter_spacing_display": "-0.02em"
  },
  "voice": {
    "register":   "technical, direct, anti-jargon, CLI-aesthetic",
    "person":     "first-person plural (we / your)",
    "do":         ["concrete numbers", "name the tradeoff", "name the tool"],
    "dont":       ["leverage", "unlock", "revolutionary", "next-gen"]
  },
  "source": "repo: ~/git/cogny/tailwind.config.ts + src/index.css",
  "captured_at": "2026-04-25"
}

最低可行指南：colors.background、colors.foreground、colors.primary、type.family、voice.register。缺少這五項中的任何一項都不算完成。

---

路徑 0 — Cogny MCP 上下文樹（成本最低，如果已連線則優先執行）

使用時機：cogny MCP 伺服器存在於 .mcp.json 中。使用者可能已經在其上下文樹中記錄了他們的品牌 — 語調、色調、風格 — 在這種情況下，重新抓取是多餘的。

mcp__cogny__get_context_tree_overview              # 查看已記錄的內容
mcp__cogny__search_context query="brand"           # 色調、語調、設計記號
mcp__cogny__search_context query="positioning"     # 語調 + 風格通常存放在此
mcp__cogny__read_context_node node_id="…"

如果樹返回了品牌 / 色調 / 語調節點，則從這些數值填入指南。如果某些內容看起來過時或矛盾，才與路徑 1 或 3 進行交叉比對。

如果 cogny MCP 未連線，或者樹中沒有與品牌相關的內容，則落至路徑 1。

路徑 1 — 具有 Tailwind / CSS 變數的儲存庫（訊號最佳）

使用時機：使用者擁有網站的原始碼存取權。

依序尋找：

# Tailwind 設定檔 — 自訂色彩命名空間
fd -t f 'tailwind\.config\.(ts|js|mjs|cjs)$' <repo>
# CSS 自訂屬性（大多數現代框架）
fd -t f '(globals|index|app|theme|variables)\.css$' <repo>
# 設計記號
fd -t f '(design-tokens|tokens|theme)\.json$' <repo>

當找到 Tailwind 設定檔時，尋找一個自訂色彩命名空間（通常是品牌名稱，例如 cogny: {...}）：

// tailwind.config.ts (cogny 範例)
colors: {
  cogny: { dark: "#1f1d1d", purple: "#b09acd", secondary: "#7E69AB", light: "#c9badf" }
}

當找到 CSS 檔案時，使用 grep 搜尋標準的 CSS 自訂屬性名稱：

grep -E '^\s*--(background|foreground|primary|accent|muted|card)' <css-file>

將這些數值對應到指南結構中。如果你同時找到 --primary（HSL 或十六進位）和 Tailwind 命名空間，則優先使用 Tailwind 命名空間 — 它通常代表明確的品牌意圖，而非 shadcn 的預設值。

在同一批檔案中進行字型偵測：

grep -E "(font-family|fontFamily|--font-)" <repo>/src/**/*.{css,ts,tsx,js} 2>/dev/null | head

---

路徑 2 — 即時網站 URL（無需原始碼即可運作）

使用時機：使用者僅有公開的 URL。

步驟：

1. 使用 WebFetch <url> 擷取首頁，並提取所有內聯 <style> 區塊以及 head 中的樣式表連結。
2. 擷取主要樣式表（head 中最大的 CSS 連結，通常如此）。curl -sL <css-url> | head -c 200000 就足夠了 — 尋找 CSS 自訂屬性（--primary、--background 等）和 @font-face 規則。
3. 在 /site.webmanifest、/manifest.json 或 /manifest.webmanifest 尋找資訊清單。資訊清單包含 theme_color、background_color 和圖示列表 — 對品牌指南來說是金礦。
4. 尋找 favicon 和高解析度標誌：

   curl -sL "<site>/favicon.ico" -o /tmp/favicon.ico
   curl -sL "<site>/apple-touch-icon.png" -o /tmp/touch.png
   # 或從首頁 HTML 中的 <link rel="icon"> 提取
   

   網站上最大的 PNG 圖示（Apple touch icon、資訊清單圖示）就是品牌標記。
5. 偵測字型：在內聯 CSS 中搜尋 body、html 或 h1 上的 font-family 宣告。如果在 <head> 中看到 Google Fonts 連結，字型系列名稱就在 URL 中。

如果網站是靜態前端（Next.js 等），打包後的 CSS 通常包含與開發原始碼相同的自訂屬性 — 因此，即使沒有儲存庫存取權，你仍然可能恢復完整的品牌色調盤。

如果你只得到部分資訊（例如，從資訊清單中得到 theme_color，但沒有完整色調盤），則繼續使用路徑 3，從標誌 / 螢幕截圖中填補缺口。

---

路徑 3 — 標誌或螢幕截圖色調提取（總是有效的備用方案）

使用時機：使用者上傳了一張標誌圖片、首頁截圖或品牌素材 PNG/JPG。

使用者通常 會有 一些圖片 — 桌面上的標誌、Slack 頭像、網站截圖。直接使用 FFmpeg 從中提取色調盤：

# 從任何圖片生成一個小型色調盤圖片（最多 6 種不同顏色）。
ffmpeg -y -i <input.png> \
  -vf "palettegen=max_colors=6:reserve_transparent=0:stats_mode=single" \
  -frames:v 1 -update 1 /tmp/_palette.png

# 將這些色調盤顏色以十六進位形式讀回。PPM 標頭為
#   P6\n<W> <H>\n255\n  → 對於標準的 16x16 色調盤，為 13 個位元組。
ffmpeg -y -i /tmp/_palette.png -c:v ppm -f image2 -update 1 - 2>/dev/null \
  | tail -c +14 \
  | xxd -c 3 -p \
  | awk '!seen[$0]++' \
  | head -8 \
  | awk '{print "#" toupper($1)}'

cogny 標誌的輸出結果（暖色暗背景上的漸層 C）：

#1D1B1B   ← 背景
#5F4953   ← 深紫色
#BB93B9   ← 薰衣草色（主要品牌色）
#CA8B9D   ← 珊瑚粉
#D2858C   ← 珊瑚色（強調色）

對應規則 — 色調盤按頻率排序，但 角色 分配由你決定：

• 最暗的顏色 → colors.background（如果它覆蓋 >40% 的像素）
• 最亮的非白色 → colors.foreground（如果沒有接近白色的顏色，預設為 #fafafa）
• 飽和度最高的色彩 → colors.primary
• 飽和度第二高的色彩 → colors.accent

看一眼原始圖片進行確認 — 演算法角色分配約有 70% 的機率是正確的。

從螢幕截圖中獲取字型資訊：基於圖片的字型偵測並不可靠。你可以：

• 詢問使用者（"這張圖片中的標題字型是……？"），或者
• 使用免費工具，如 WhatTheFont 或 Fontspring Matcherator — 向使用者顯示 URL，不要嘗試以程式設計方式進行。

可選：使用 node-vibrant 進行語意色調盤（執行一次 npm install，即可獲得 vibrant/muted/dark-vibrant/light-vibrant 類別 — 對於主要/強調角色對應更有用）：

npm install -g node-vibrant
node -e "
  const Vibrant = require('node-vibrant');
  Vibrant.from(process.argv[1]).getPalette().then(p => {
    const out = {};
    for (const k of ['Vibrant','Muted','DarkVibrant','LightVibrant','DarkMuted','LightMuted']) {
      if (p[k]) out[k] = p[k].hex;
    }
    console.log(JSON.stringify(out, null, 2));
  });
" <input.png>

使用可用的工具即可。FFmpeg 已隨影片技能一同提供，因此它是預設選項。

---

路徑 4 — 顏色選擇器 / 手動輸入（總是可用）

使用時機：其他方法都失敗，或者使用者想要明確覆寫指南。

按此順序詢問，並接受部分答案：

1. 背景十六進位色碼？（使用者最常看到的頁面背景）
2. 前景十六進位色碼？（主體文字顏色）
3. 主要品牌十六進位色碼？（按鈕或連結使用的顏色）
4. 強調色十六進位色碼？（可選 — 如果有第二個品牌顏色）
5. 字型系列？（"像 Inter 這樣的無襯線字型"、"JetBrains Mono" 等 — 盡力而為，系統備用字型也可以）

三種顏色和一種字型就足夠發布了。

---

路徑 5 — 語音提取（無論顏色路徑為何，總是執行）

語音是品牌指南的一部分，但複製貼上工具經常遺漏。它會改變影片應編寫的節拍，或廣告文案技能應產生的標題。

語音的來源：首頁的英雄區塊 + 1–2 個更深入的頁面（關於、價格、部落格）。

步驟：

1. 擷取首頁英雄區塊文字（h1、h2、英雄區塊 CTA 之後的第一個段落）。
2. 擷取一個深層頁面（通常是 /about 或 /pricing）。
3. 閱讀文案並產生三個欄位：

"voice": {
  "register": "<one-line description>",
  "do":   ["pattern 1", "pattern 2", "pattern 3"],
  "dont": ["banned word 1", "banned word 2"]
}

範例（這些是真實的，源自每個公司的首頁）：

品牌	風格	應做	不應做
cogny	"technical, direct, anti-jargon, CLI-aesthetic"	concrete numbers, name the tradeoff, name the tool	leverage, unlock, revolutionary, next-gen
Linear	"operator, opinionated, fast"	second-person, terse, build-mode language	enterprise, synergy, robust
Mailchimp	"warm, conversational, plain-English"	first-person, friendly contractions, clear CTAs	utilize, paradigm, leverage

如果你無法從頁面推斷語音（例如，首頁內容非常少），請詢問使用者用一句話描述他們想要的聽覺風格。不要憑空杜撰。

---

步驟（實際流程）

1. 偵測使用者給你的輸入類型：

   • URL → 路徑 2 → 如有需要，落至 3 / 5
   • 儲存庫路徑 → 路徑 1 → 落至 5
   • 圖片路徑 → 路徑 3 + 詢問網站 URL 或儲存庫以獲取語音（路徑 5）
   • 無輸入 → 路徑 4 + 詢問他們是否有標誌可以提取

2. 逐步建立指南。在每一步之後列印部分狀態，以便使用者可以介入：

   ◆ 品牌指南 (cogny)
   ✓ 色彩    bg=#1f1d1d  fg=#ede8e3  primary=#b09acd  accent=#c9badf
   ✓ 字型      JetBrains Mono / mono
   ◇ 語音     待處理 — 正在擷取 /about 進行分析…
   

3. 在寫入檔案前向使用者顯示結果。使用者應批准顏色角色分配（背景 vs 主要等） — 這些是影響重大的決策。

4. 寫入 brand-kit.json 到最合適的位置（參見輸出區段）。如果已存在指南，請顯示差異並在覆寫前詢問。

5. 列印一行安裝提示，供下游技能使用：

   已儲存 → .agents/brand-kit.json
   由以下技能使用：/tiktok-launch-video, /reddit-launch-video, /linkedin-launch-video,
            /ad-copy-writer, /landing-page-review
   

常見錯誤

1. 將單一十六進位色碼視為品牌 — 大多數品牌都有主要色 + 強調色 + 背景-前景對。至少三種顏色。
2. 不包含語音就發布 — 色彩承載品牌 30%；語音承載 70%。不要跳過路徑 5。
3. 使用 shadcn 預設值作為品牌 — 如果使用者的 CSS 檔案中有字面上的 shadcn --primary: 240 5.9% 10%，那只是一個佔位符，不是品牌。應與首頁截圖交叉比對。
4. 讓指南被標誌漸層偽影過度飽和 — 從漸層標誌進行色調盤提取會返回 4–5 種過渡顏色。選取端點（主要色 + 強調色），丟掉中間色。
5. 讓 LinkedIn 藍 / Twitter 藍 / TikTok 粉紅混入指南 — 這些是平台 UI 顏色，會滲入螢幕截圖，並非品牌顏色。
6. 盲目信任 theme-color — 網站有時會將 theme-color 設定為與行動 Safari 的網址列相符，這是裝飾性的，可能與實際的品牌主要色不符。

相關技能

• /tiktok-launch-video、/reddit-launch-video、/linkedin-launch-video — 使用此指南
• /ad-copy-writer — 使用語音規則來撰寫適合平台的文案
• /landing-page-review — 檢查登陸頁面與品牌指南之間的一致性
• /non-commodity-content — 語音提取與此技能的面談步驟有重疊