Communitygithub.com

設計標記 (Design Tokens)

建立網站的視覺系統,以 CSS 自訂屬性為基礎,涵蓋色板、字體級距、間距、圓角與陰影,並會檢查對比度。每當有人要求配色方案、從一個品牌色建立色板、字體配對、字體級距、「讓它看起來一致」、深色模式、重新設計現有網站的色彩,或是從零開始建立網站但沒有定義樣式時,就使用此技能。

設計標記 (Design Tokens) 是什麼?

這個 AI 代理技能是關於建立一個以角色為基礎的設計標記系統,專門用來建立一致且易於維護的網站視覺語言。它強調整組樣式之前,先定義一組命名的 CSS 自訂屬性,涵蓋顏色、字體排印、間距、圓角和陰影。這個技能對於建立全新的網站主題,或是將現有網站重新命名為新的品牌色系特別有用。它支援多種平台,包括標準的 CSS 開發工作流程、WordPress 的 theme.json 格式,以及透過 MCP 工具整合。這個技能的核心方法是使用 `webcraft` CLI 或 MCP 工具中的 `generate_tokens` 工具,從一個單一的品牌色和一種「心情」字詞來產生初始的標記集。然後,系統會自動進行對比度檢查,以確保符合無障礙標準(WCAG)。關鍵原則是使用語意化角色(例如 `--text`、`--bg`、`--accent`)而非特定顏色名稱,以便日後更容易重新命名;在調色盤中混入微妙的色調,讓中性色與強調色協調;以及使用流體字體級距(`clamp()`)和間距,以確保在不同螢幕尺寸之間能有流暢的過渡。該技能也提供了針對現有網站進行重新命名的策略,強調先將硬編碼值對應到角色,然後再進行交換,以防止回歸問題。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/imperfec-t/webcraft/tree/HEAD/skills/design-tokens

在你喜歡的 AI 中提問

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

說明文件

設計標記(Design Tokens)

一組經過命名的少量數值,並在所有地方一致使用,是讓網站看起來經過設計而非拼湊而成的關鍵。在定義元件之前先定義標記;稍後若要更改品牌,只需編輯一個區塊即可。

需要詢問的內容

一個品牌色(或一個情緒字詞)、淺色或深色底色,以及整體調性(企業、俏皮、編輯、技術)。其餘所有內容都可以推導出來。

顏色

以角色而非顏色名稱來工作,這樣重新命名品牌時就不需要重新命名。

標記角色經驗法則
--bg頁面背景米白色或接近黑色,永遠不要使用純 #fff 或 #000
--surface卡片、輸入框亮度與 --bg 相差 2 到 4%
--text內文文字在 --bg 上至少要有 7:1 的對比度
--muted次要文字在 --bg 上至少要有 4.5:1 的對比度
--border極細線條將文字顏色的 10 到 15% 混合到背景顏色中
--accent按鈕、強調品牌色
--accent-ink在 --bg 上的連結和強調文字將品牌色調暗(或在深色背景上調亮)直到通過 4.5:1 的對比度
--on-accent在強調色上的文字白色或深色中,何者能通過 4.5:1 的對比度

指導原則:

  • 將中性色稍微向強調色的色調方向偏移(2 到 6% 的飽和度)。純灰色放在溫暖的強調色旁邊會顯得不協調。
  • 大約在 10% 的表面積上使用強調色。如果每樣東西都被強調,那就等於沒有強調。
  • 很少需要第二個強調色。只有為了表示不同的意義(例如成功或特價)時,才添加一個。
  • 對於深色模式,不要做反轉處理。隨著層級提高,提高表面的亮度,並稍微降低強調色的飽和度,使其不會發光。

如果 webcraft CLI 可用,請用它來產生一組起始標記,而不是手動推導數值。它會應用上述所有規則,調整亮度直到每一對都通過對比度檢查,並分別建立深色主題:

webcraft tokens "#e4572e" --tone editorial -o tokens.css      # 也可以使用:--base dark, --radius pill
webcraft tokens "#e4572e" --format theme-json                 # 使用相同數值的 WordPress theme.json

在 MCP 用戶端內部,同樣的功能是 generate_tokens 工具。將輸出視為初稿:用肉眼調整,然後重新檢查。

在最終確定之前,檢查每一對文字和背景:

webcraft contrast "#1b1b1f" "#f6f4ef"
webcraft contrast --tokens tokens.css
python scripts/contrast.py --tokens tokens.css   # 無需安裝的備用方案,僅限十六進位值

第一種形式會印出一對組合的對比度和 WCAG 等級。第二種形式會讀取一個 CSS 檔案,並檢查每個主題區塊(:root、[data-theme]、prefers-color-scheme)中的標準角色配對,會解析 var() 並讀取 hex、rgb()、hsl()、oklch() 和 color-mix()。失敗的配對是新網站上最常見的無障礙缺陷,而且對於視力良好且在良好螢幕上觀看的人來說是看不見的,這就是為什麼這是一個腳本而不是人為判斷的原因。

字體排印

  • 最多兩個字體家族:一個用於標題,一個用於內文。通常,一個字體家族使用兩種粗細會更好。
  • 透過結構對比來配對(襯線展示字體搭配無襯線內文字體,或壓縮展示字體搭配一般內文字體),而不是兩個相似的无襯線字體。
  • 內文字體大小 16 到 18px,行高 1.5 到 1.7,行長度 60 到 75 個字元。
  • 展示字體:行高 0.95 到 1.1,字距追蹤隨尺寸增大而變為負值。
  • 使用帶有 clamp() 的流體級距,這樣在不同斷點之間就不會有跳躍感:
:root {
  --step--1: clamp(0.83rem, 0.8rem + 0.15vw, 0.9rem);
  --step-0:  clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
  --step-1:  clamp(1.25rem, 1.1rem + 0.6vw, 1.6rem);
  --step-2:  clamp(1.6rem, 1.3rem + 1.3vw, 2.4rem);
  --step-3:  clamp(2rem, 1.5rem + 2.6vw, 3.6rem);
  --step-4:  clamp(2.5rem, 1.6rem + 4.6vw, 5.5rem);
  --step-5:  clamp(3rem, 1.5rem + 7vw, 7.5rem);
}
  • 使用 font-display: swap 載入字體,預先載入在折疊線上使用的一或兩個檔案,如果是自行託管,則需進行子集化。

間距、圓角、陰影

:root {
  --space-1: 0.25rem; --space-2: 0.5rem; --space-3: 0.75rem; --space-4: 1rem;
  --space-6: 1.5rem;  --space-8: 2rem;   --space-12: 3rem;   --space-16: 4rem;
  --section: clamp(4rem, 3rem + 6vw, 9rem);   /* 區塊之間的垂直內距 */
  --gutter:  clamp(1rem, 0.5rem + 3vw, 3rem); /* 頁面側邊內距 */
  --container: 76rem;

  --radius-sm: 8px; --radius: 16px; --radius-lg: 28px; --radius-pill: 999px;
  --shadow: 0 1px 2px rgb(0 0 0 / .04), 0 8px 24px rgb(0 0 0 / .06);
}
  • 選擇一種轉角個性(銳利、柔和或膠囊狀)並保持一致。混合使用多種圓角是看起來不一致的最快途徑。
  • 區塊之間的間距應明顯大於區塊內部的間距;這種差距是告訴眼睛一個區塊在哪裡結束的關鍵。

輸出

交付一個 tokens.css,其中包含 :root 區塊、一個可選的 [data-theme="dark"] 區塊,以及一個簡短的表格說明每個標記在何處使用。然後說明內文文字、次要文字和按鈕文字的對比度結果。

重新命名現有網站

首先將現有的硬編碼值對應到角色(搜尋 CSS 中的十六進位色碼並計算出現次數),用標記取代它們,確認視覺上沒有任何改變,然後再交換標記的值。同時進行這兩個步驟會讓回歸問題變得無法追蹤。

Individual skills in this repo

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

hero-section

Design and build the hero (first screen) of a website, including headline layout, media treatment, CTA, proof badge, marquee and entrance animation. Use this whenever someone asks for a hero section, a landing page header, "the top of my homepage", a cinematic or animated intro, a video background, a text marquee, or says their first screen looks plain or generic.

homepage-blueprint

Plan the section structure and content slots of a homepage for an agency, freelancer, studio or service business before any design or code. Use this whenever someone asks "what sections should my homepage have", "plan my website", "structure a landing page for my business", wants a wireframe or sitemap for a service site, or starts building a homepage without a clear outline.

launch-qa

Run a pre-launch quality check on a website covering performance, accessibility, SEO basics, forms, cross-device behavior and content, and report findings ranked by severity with fixes. Use this whenever someone says a site is "ready to launch", "going live", asks "can you check my site", wants a QA pass, a website audit, a Lighthouse-style review, or wants to know why a page is slow or scoring badly.

responsive-layout

Build page layouts that work from phones to wide desktops using CSS grid, flexbox, container queries and fluid sizing, including card grids, bento grids, split sections, sticky sidebars and navigation that collapses. Use this whenever someone says their site "breaks on mobile", asks for a responsive grid, a bento layout, a mobile menu, fixing horizontal scroll or overflow, or is laying out any multi-column section.

scroll-motion

Add scroll-driven and entrance animation to a website with GSAP, ScrollTrigger and Lenis, including reveals, parallax, pinned sections, horizontal scroll, line drawing, counters and preloaders. Use this whenever someone wants a site to "feel premium", asks for smooth scrolling, scroll animations, parallax, text reveals, a pinned or sticky scroll section, an animated preloader, or names GSAP, ScrollTrigger, Lenis, Locomotive or AOS.

site-teardown

Analyze a live website and turn it into a section-by-section build brief that another person or AI can rebuild from, with brand name, colors, fonts and images swapped for placeholders. Use this whenever someone shares a URL and says "analyze this site", "make something like this", "give me a prompt to build this", "recreate this effect", "clone the layout with my branding", or asks how a page's animation or structure works, even if they never say "teardown".

website-workflow

Plan and sequence a whole website build, from structure through design, code, WordPress and launch, by routing each stage to the right webcraft skill. Use this when someone asks to "build me a website", "design my site from scratch", "redo our homepage", wants an end-to-end plan for a marketing, agency, studio or service site, or the request spans more than one of structure, look, layout, motion, CMS and QA.

wordpress-theme-build

Turn a static HTML/CSS/JS design into a custom WordPress theme that the client can edit, covering theme structure, theme.json, enqueueing scripts, block patterns, custom post types and editable content. Use this whenever someone wants to convert a design or static site to WordPress, build a custom or block theme, make sections editable in Gutenberg, add GSAP or other scripts to a theme properly, or asks why their theme edits are lost or their content is hard-coded.

相關技能