turtleneck 是做什麼的?
為應用程式選擇正確的風格,然後嚴謹地建構它。每種風格都是一個預設集:一個包含變數覆蓋的檔案,建立在一個共享核心之上。預設的 keynote 預設集就是核心本身。其他每個預設集是從該類別的五個大型網站混合而成,絕非複製其中任何一個。
啟用此技能時,它會覆蓋通用的「避免 AI 預設」技能(例如 frontend-design),當兩者衝突時:在 keynote 中,使用系統字型、句子式眉題和色調漸層標題是正確的。
此檔案旁的其他檔案:
tokens.css:核心和 keynote 的值。每個顏色都是light-dark(light, dark);color-scheme在:root、.a-dark、.a-light或data-theme上選擇一半。所有預設集的鈎子都在其:root中列出。共用元件也在這裡:字型比例、按鈕、瓷貼、.a-grid、.a-rail、.a-stats、.a-reveal。styles/<preset>.css:變數覆蓋加上少量僅限該預設集的規則。在tokens.css之後載入。styles/<preset>.md:每個預設集一個頁面:使用時機、記號表、規則、元件差異、字型、避免事項、檢查清單。recipes-html.md:頁面骨架、導覽列、主視覺、瓷貼、bento 網格、圖庫、比較區塊、頁尾(手機上使用手風琴)、顯示動畫,以及共用的預設集模式(翻轉區塊、搜尋主視覺、滑軌、規格表、方案卡片、程式碼框架)。tailwind.md、swiftui.md:給那些技術堆疊的相同記號。test-widths.html?src=<url>[&h=800][&full=1]:在 320/375/414 寬度下並排顯示頁面,並附有溢位報告;full=1會將每個框架延伸到其文件高度,以便進行全頁手機螢幕截圖。example.html和../../demos/在 agent-skills 儲存庫中:完成的頁面。
步驟 0:偵測應用程式類型(必須執行,在任何程式碼之前)
- 現有的設計系統或明確的風格要求優先。 專案記號、元件庫主題、品牌指南,或「做成深色和紅色」:使用它,僅保留以下核心規則,跳過表格。
- 讀取線索:請求;README;相依套件(
package.json、pyproject.toml、Podfile、Package.swift、Gemfile、*.csproj);路由;現有 CSS;產品類別和受眾。 - 挑選一個預設集:
| 類別 | 線索(請求、產品、依賴、路由) | 預設集 |
|---|---|---|
| 高階硬體 | 實體產品、消費性裝置、生活風格小物、發布頁面、「乾淨」、「簡約」、「高階」;SwiftUI 行銷畫面;沒有明確線索 | keynote |
| 商業軟體 | 辦公室/生產力、B2B、CRM/ERP、內部網路、IT/合規、醫療保健;依賴 @fluentui/*、@microsoft/teams-js、office-addin-*、@azure/*、Blazor/.NET;路由 /admin、/settings、/reports | enterprise |
| 串流 | 影片、電影/電視、影集、預告片、直播活動、VOD;依賴 hls.js、video.js、shaka-player、@mux/*、react-player;路由 /watch、/browse、/title | cinema |
| 音樂與社交 | 音樂/音訊、播放清單、創作者、社交動態、約會、健身課程、年輕訂閱服務;依賴 howler、tone、wavesurfer.js、expo-av;路由 /player、/playlist、/profile | vibe |
| 遊戲硬體 | GPU/PC 零件、遊戲主機、周邊、電競、基準測試、驅動程式、「FPS」;依賴 three、@react-three/fiber + 圖表庫;路由 /specs、/compare、/drivers | power |
| 開發者與雲端 | API、SDK、CLI、代管、部署、資料庫、可觀測性、支付 API、「為開發者打造」;依賴 next、@radix-ui/*、stripe、prisma、drizzle、trpc、turbo;路由 /docs、/changelog、/pricing | devtool |
| AI | 模型、助手、聊天、代理、「AI 驅動」作為產品;依賴 openai、@anthropic-ai/sdk、ai、langchain、transformers;路由 /chat、/research、/models | lab |
| 旅遊 | 住宿、航班、叫車、飯店、訂房、行程;日期選擇器、地圖(leaflet、mapbox-gl);路由 /search、/stays、/trips、/book | journey |
| 零售 | 商店、賣場、目錄、市集、購物車、結帳、優惠、生鮮雜貨、時尚;依賴 @shopify/*、@medusajs/*、@commercetools/*、snipcart、@stripe/stripe-js 搭配產品目錄;路由 /shop、/products、/p/、/cart、/checkout、/category | market |
| 金融 | 銀行、信用卡、支付、錢包、保險、借貸、儲蓄、投資、消費者帳戶儀表板;依賴 plaid、react-plaid-link、@adyen/*、dinero.js、currency.js;路由 /accounts、/cards、/rates、/apply、/transfer(賣給開發者的支付 API 是 devtool) | vault |
| 汽車 | 汽車、摩托車、電動自行車、電動車充電、行動服務、經銷商、試駕;配置器、續航里程和規格頁面;路由 /models、/configure、/inventory、/test-drive、/dealers | drive |
| 頁面類型 | 預設集(平手時) |
|---|---|
| 文件網站、更新日誌 | devtool |
| 管理儀表板 | 商業用戶用 enterprise;開發者面向用 devtool |
| 商店 | market;單一高階產品頁面是 keynote |
| 作品集 | 產品/設計作品用 keynote;電影、攝影、動態用 cinema |
| 手機應用程式畫面 | 具有原生感的工具用 keynote;消費性媒體和社交用 vibe |
| 遊戲 / 遊戲工作室 | 競技和硬體類用 power;故事驅動、預告片用 cinema |
| 其他產品中的 AI 功能 | 該產品自身的類別;僅當 AI 是產品時用 lab |
| 其他產品中的預訂流程 | 僅搜尋和結果頁面用 journey |
使用者風格詞彙直接對應:「Apple 風格 / 高階 / 乾淨」= keynote;「Microsoft / Fluent」= enterprise;「Netflix 風格」= cinema;「Spotify 風格 / TikTok 風格」= vibe;「遊戲 / NVIDIA 風格」= power;「Stripe / Vercel / GitHub 風格」= devtool;「OpenAI / Anthropic 風格」= lab;「Airbnb / Booking 風格」= journey;「Amazon / IKEA 風格」= market;「銀行 / PayPal 風格」= vault;「Tesla / BMW 風格」= drive。
結果是類別的混合,而非該公司的網站(請參閱「商標與資產」)。
- 線索薄弱或衝突:使用
keynote。 - 在開始建構之前,先用一行話說明選擇,例如「風格:devtool(Next.js + Prisma,路由有 /docs 和 /pricing,賣給開發者)。」然後完整閱讀
styles/<preset>.md(keynote 請閱讀styles/keynote.md)。
預設集可以改變的內容
僅透過 tokens.css(:root)中的變數,加上少量自身的規則來改變:
- 字型(顯示用、內文、等寬)以及字型比例、字重、字距、行高;
- 眉題和引言樣式、內文大小(UI 永遠不低於 14px,閱讀文字永遠不低於 16px);
- 表面和文字顏色、淺色/深色預設、一個強調色及其上的文字、連結和焦點顏色;
- 圓角、邊框、陰影、瓷貼填滿;按鈕高度、內邊距、字重、大小寫;
- 導覽列高度、填滿和模糊;內容寬度、章節和瓷貼間距;
- 緩動函數、持續時間、顯示動畫距離、懸停和按下回饋;
- 圖像和文案風格(在其 md 檔案中)。
以下每一行都適用於所有預設集。
工作流程
- 尊重專案。 載入
tokens.css+styles/<preset>.css,或合併 Tailwind 主題,或新增 SwiftUI 調色盤。預設集可能會連結其 md 檔案中命名的免費字型;頁面在使用備用字型堆疊時仍須看起來正常。永遠不要為了樣式而新增 npm 依賴。 - 用三行話寫出頁面計畫:頁面銷售的一件事、包含背景的章節順序,以及一個「亮點」(一個翻轉章節、一個大數字統計的 bento 網格、一個示範、一個影片、黏性滾動)。
- 先寫文案:簡短標題(預設集設定長度)、一個副標題行、引言最多兩行。
- 根據配方建構,逐個章節進行。
- 在每個測試寬度下驗證(響應式)、淺色和深色(如預設集皆有):截圖、溢位檢查、檢查清單。在報告完成前修正問題。
核心規則
排版
- UI 使用一個字型家族(僅真正的程式碼、按鍵和 API 值使用等寬字型)。顯示字重來自預設集。
- 字距隨尺寸增大而變緊;內文字體的負字距永遠不超過 -0.022em。
- 顯示尺寸是流暢的
clamp(min, rem + vw, max);務必在中間項混入 rem。 - 閱讀用內文 16-17px;僅在密集 UI、元資料行和頁尾中使用 14px。行高 1.45-1.6。
- 標題使用
text-wrap: balance;長詞換行(overflow-wrap、hyphens)。 - 重要的數字要大並使用表格數字;它們的標籤要小。
色彩
- 品牌顏色優先。 來自使用者或專案的品牌顏色會取代預設集的強調色,後者僅作為備用。預設集仍決定佈局、排版、圓角、密度、圖像和動態。
- 強調色配方(品牌顏色或任何強調色變更),在
:root上設定一次:--a-blue:填滿色,也就是提供的品牌顏色(舊名稱保留;意思是「強調色」)。--a-on-accent:墨水色或白色,取在填滿色上能達到 4.5:1 對比度者。--a-blue-hover:比填滿色深一階的顏色(在深色預設下則淺一階),其標籤仍須通過對比度要求。--a-accent-text:light-dark(a, b),品牌色調在亮度上偏移,直到在每個主題的--a-bg和--a-bg-alt上達到 4.5:1 對比度。連結、強調眉題和焦點環(需達 3:1)會讀取它。 具有墨水色主要按鈕的預設集(lab、journey)將墨水色保留在--a-button-*中;品牌色仍放在此處。
- 一個強調色,小範圍使用:主要行動呼籲按鈕、焦點、連結、標誌標記、小徽章和「推薦」標記。不應用於大面積表面或內文,除非預設集另有說明。狀態顏色僅用於狀態。
- 中性表面使用 2-4 個階層;根據預設集的規定,透過色調、極細邊框或一層柔和陰影來區分。
- 文字永遠不是純黑底白字;內文灰色是一個具有 AA 對比度的真實灰色。
- 處處滿足 AA 標準:文字以及按鈕標籤在其填滿色上需達 4.5:1,大型文字、圖示和具有意義的邊框需達 3:1。
- 深色模式是一個不同的調色盤,而非反相:凸起的表面用稍亮一階的色調,不使用陰影來表示深度。
佈局與節奏
- 內容有最大寬度限制:文字欄位(
--a-content)在一個寬網格(--a-content-wide)內部,具有流暢的邊距。 - 章節交替使用頁面和替代顏色;瓷貼在其章節內使用相反的填滿色。
- 當預設集指定時,將主視覺和章節開頭置中;瓷貼內部的文字和長篇文案靠左對齊。
- 每個頁面一個亮點;最多一個翻轉(深色或淺色)章節,除非預設集是基於色帶建構的。
響應式(嚴格規則:每個解析度,每個預設集)
- 流暢的排版和間距來自 clamp 記號;375px 時用小值,1440px 時用大值。
- 沒有可能導致破版的固定寬度或高度:使用
max-width+ 邊距、min()、minmax(0, 1fr)、aspect-ratio、min-height。永遠不使用100vh(改用svh/dvh)。包含文字的 Flex/Grid 子元素需設定min-width: 0。 - 網格根據空間重新排列:使用
repeat(auto-fit, minmax(min(100%, 20rem), 1fr)),而非裝置斷點。 - 媒體縮放:
max-width: 100%; height: auto;SVG 保留viewBox。 - 導覽:低於 834px(或當 6 個以上連結無法容納時:使用容器查詢),文字連結會移入全螢幕選單(原生
popover,無需 JS);用一條優先於基本連結樣式的規則隱藏其<li>(配方:全域導覽)。保留標誌、搜尋和一個動作保持可見。沒有文字連結(僅有搜尋、帳戶、購物車):則不使用漢堡選單。 - 任何寬度下都沒有水平捲軸;僅有特意設計的捲動區域(圖庫、滑軌、程式碼)會在其自身的盒子內部溢出。
- 觸控目標 >= 44x44px:小型藥丸形按鈕、色票、槳型按鈕、導覽連結需獲得一個不可見的點擊區域(
.a-hit)。 - 安全區域:
viewport-fit=cover;邊距和底部內邊距使用env(safe-area-inset-*)。 - 非常大的螢幕:排版和內容在其最大寬度處停止;背景保持全幅出血。
- 手機橫向:主視覺不得需要視口高度;任何黏性元素覆蓋不超過三分之一。
- 200% 縮放:相當於一半寬度的視口;所有內容重新排列,無任何內容被裁剪。
在說完成之前測試寬度(瀏覽器窗格:resize_window 到每個寬度,截圖,加上 document.documentElement.scrollWidth === innerWidth 和一個寬於視口的元素列表):
| 寬度 | 代表 |
|---|---|
| 320 | 小型手機,640 的 200% 縮放 |
| 375 / 414 | 標準 / 大型手機 |
| 768 / 1024 | 平板直立 / 橫向,小型筆電 |
| 1280 / 1440 | 筆電 / 桌上型電腦(參考寬度) |
| 1920 / 2560 | 全高清 / QHD,超寬螢幕 |
| 812x375 | 手機橫向 |
| 640 | 1280px 在 200% 縮放 |
每個寬度報告:截圖已拍攝、溢位是/否、修正了什麼。Headless Chrome 會將視窗限制在 500px 以下;在瀏覽器窗格中測試手機寬度,或使用 test-widths.html?src=<page url>(相同 http 根目錄)。
Headless 捕捉:在 <html> 上設定 data-theme="light|dark" 來強制主題;顯示動畫內容在靜態捕捉中不可見,因此傳遞 --virtual-time-budget=5000 或在 <html> 上設定 data-reveal="off";一個 100svh 的主視覺在一個高大的全頁視窗中會拉伸,因此為了捕捉而將其固定(min-height: 800px)(&full=1 兩者都做)。
元件
- 按鈕:最小高度 44px(較小的視覺元素需獲得點擊區域),句子式大小寫,除非預設集規定全大寫,無圖示,僅可有一個尾隨的角括號或箭頭,無漸層。主要按鈕使用填滿樣式,次要按鈕依預設集而定。
- 連結:明顯是連結(顏色或底線);如果預設集使用「了解更多 ›」風格的角括號。
- 瓷貼/卡片:當整個瓷貼可連結時,設定一個定位點(內部的按鈕是一個
span)。圓角、填滿、邊框和陰影來自預設集;永遠不應同時使用填滿 + 邊框 + 陰影。 - 焦點環:2px 實線
--a-focus,偏移 1px,在每個互動元素上。 - 導覽列:根據預設集使用實色或毛玻璃效果,最多一個黏性欄位,標記當前頁面。
- 頁尾:低調:小字型灰色連結在欄中,法律條款行;在手機上,欄會變成
<details>手風琴。
圖像
- 真實的主題:產品、其 UI、使用者自己的照片和媒體。大尺寸,有目的地裁剪。
- 無使用筆記型電腦的庫存人物、無 3D 模糊形狀、無表情符號、無吉祥物、無每個標題前的圖示。
- 沒有資產時:將主題繪製為一個 SVG
<symbol>,透過 CSS 變數重新著色,或是一個以正確比例呈現的誠實灰色佔位符。
動態
- Transition named pr
…
[因翻譯而截斷]