Communitygithub.com

turtleneck

網頁與應用程式的設計技能,會先偵測正在建置的內容類型,然後挑選一個風格預設集,並提供對應的 CSS/Tailwind/SwiftUI 配方。

turtleneck 是什麼?

turtleneck 是一個為 AI 代理(如 Claude Code、Cursor)設計的專業技能,用於為網頁或應用程式 UI 選擇並套用一致的設計系統。它會先根據專案請求、相依套件和路由來「偵測」應用程式類型(如登陸頁、儀表板、AI 產品或串流服務),然後從 keynote、enterprise、cinema 等預設集中挑選一個。每個預設集是從該類別的五個大型參考網站混合而成,而非直接複製。此技能會覆蓋通用的「避免 AI 預設」技能,提供嚴格的排版、色彩對比(AA 無障礙標準)、響應式設計和元件規則,並透過 `tokens.css` 和特定預設集的變數來實作。它支援純 HTML/CSS、Tailwind CSS(v3/v4、shadcn)和 SwiftUI,並提供完整的指南、配方和測試流程,確保在任何解析度下都能產出高品質、品牌導向的介面。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/n-stau/turtleneck/tree/main/skills/turtleneck

在你喜歡的 AI 中提問

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

說明文件

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:偵測應用程式類型(必須執行,在任何程式碼之前)

  1. 現有的設計系統或明確的風格要求優先。 專案記號、元件庫主題、品牌指南,或「做成深色和紅色」:使用它,僅保留以下核心規則,跳過表格。
  2. 讀取線索:請求;README;相依套件(package.json、pyproject.toml、Podfile、Package.swift、Gemfile、*.csproj);路由;現有 CSS;產品類別和受眾。
  3. 挑選一個預設集:
類別線索(請求、產品、依賴、路由)預設集
高階硬體實體產品、消費性裝置、生活風格小物、發布頁面、「乾淨」、「簡約」、「高階」;SwiftUI 行銷畫面;沒有明確線索keynote
商業軟體辦公室/生產力、B2B、CRM/ERP、內部網路、IT/合規、醫療保健;依賴 @fluentui/*、@microsoft/teams-js、office-addin-*、@azure/*、Blazor/.NET;路由 /admin、/settings、/reportsenterprise
串流影片、電影/電視、影集、預告片、直播活動、VOD;依賴 hls.js、video.js、shaka-player、@mux/*、react-player;路由 /watch、/browse、/titlecinema
音樂與社交音樂/音訊、播放清單、創作者、社交動態、約會、健身課程、年輕訂閱服務;依賴 howler、tone、wavesurfer.js、expo-av;路由 /player、/playlist、/profilevibe
遊戲硬體GPU/PC 零件、遊戲主機、周邊、電競、基準測試、驅動程式、「FPS」;依賴 three、@react-three/fiber + 圖表庫;路由 /specs、/compare、/driverspower
開發者與雲端API、SDK、CLI、代管、部署、資料庫、可觀測性、支付 API、「為開發者打造」;依賴 next、@radix-ui/*、stripe、prisma、drizzle、trpc、turbo;路由 /docs、/changelog、/pricingdevtool
AI模型、助手、聊天、代理、「AI 驅動」作為產品;依賴 openai、@anthropic-ai/sdk、ai、langchain、transformers;路由 /chat、/research、/modelslab
旅遊住宿、航班、叫車、飯店、訂房、行程;日期選擇器、地圖(leaflet、mapbox-gl);路由 /search、/stays、/trips、/bookjourney
零售商店、賣場、目錄、市集、購物車、結帳、優惠、生鮮雜貨、時尚;依賴 @shopify/*、@medusajs/*、@commercetools/*、snipcart、@stripe/stripe-js 搭配產品目錄;路由 /shop、/products、/p/、/cart、/checkout、/categorymarket
金融銀行、信用卡、支付、錢包、保險、借貸、儲蓄、投資、消費者帳戶儀表板;依賴 plaid、react-plaid-link、@adyen/*、dinero.js、currency.js;路由 /accounts、/cards、/rates、/apply、/transfer(賣給開發者的支付 API 是 devtool)vault
汽車汽車、摩托車、電動自行車、電動車充電、行動服務、經銷商、試駕;配置器、續航里程和規格頁面;路由 /models、/configure、/inventory、/test-drive、/dealersdrive
頁面類型預設集(平手時)
文件網站、更新日誌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。 結果是類別的混合,而非該公司的網站(請參閱「商標與資產」)。

  1. 線索薄弱或衝突:使用 keynote。
  2. 在開始建構之前,先用一行話說明選擇,例如「風格:devtool(Next.js + Prisma,路由有 /docs 和 /pricing,賣給開發者)。」然後完整閱讀 styles/<preset>.md(keynote 請閱讀 styles/keynote.md)。

預設集可以改變的內容

僅透過 tokens.css(:root)中的變數,加上少量自身的規則來改變:

  • 字型(顯示用、內文、等寬)以及字型比例、字重、字距、行高;
  • 眉題和引言樣式、內文大小(UI 永遠不低於 14px,閱讀文字永遠不低於 16px);
  • 表面和文字顏色、淺色/深色預設、一個強調色及其上的文字、連結和焦點顏色;
  • 圓角、邊框、陰影、瓷貼填滿;按鈕高度、內邊距、字重、大小寫;
  • 導覽列高度、填滿和模糊;內容寬度、章節和瓷貼間距;
  • 緩動函數、持續時間、顯示動畫距離、懸停和按下回饋;
  • 圖像和文案風格(在其 md 檔案中)。

以下每一行都適用於所有預設集。

工作流程

  1. 尊重專案。 載入 tokens.css + styles/<preset>.css,或合併 Tailwind 主題,或新增 SwiftUI 調色盤。預設集可能會連結其 md 檔案中命名的免費字型;頁面在使用備用字型堆疊時仍須看起來正常。永遠不要為了樣式而新增 npm 依賴。
  2. 用三行話寫出頁面計畫:頁面銷售的一件事、包含背景的章節順序,以及一個「亮點」(一個翻轉章節、一個大數字統計的 bento 網格、一個示範、一個影片、黏性滾動)。
  3. 先寫文案:簡短標題(預設集設定長度)、一個副標題行、引言最多兩行。
  4. 根據配方建構,逐個章節進行。
  5. 在每個測試寬度下驗證(響應式)、淺色和深色(如預設集皆有):截圖、溢位檢查、檢查清單。在報告完成前修正問題。

核心規則

排版

  • 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手機橫向
6401280px 在 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

…

[因翻譯而截斷]

相關技能