Communitygithub.com

设计令牌

将网站的视觉系统创建为 CSS 自定义属性,涵盖调色板、排版比例、间距、圆角和阴影,并完成对比度检查。当有人要求配色方案、基于单一品牌色的调色板、字体配对、类型比例、“看起来一致”、深色模式、现有网站的品牌重塑,或开始构建但没有定义样式时,请使用此技能。

设计令牌 是什么?

设计令牌(Design Tokens)是一种在网站开发中创建一致性视觉系统的有效方法。此技能指导开发者定义一套命名的值(如颜色、字体、间距、圆角等),并通过 CSS 自定义属性进行管理。其核心优势在于通过为颜色分配功能角色(如 `--bg`、`--text`、`--accent`)而非具体颜色名称,使品牌重塑或主题切换变得极其简单,只需修改令牌值。该技能支持浅色和深色模式,并提供了详细的可访问性对比度检查方法,确保所有文本和背景对符合 WCAG 标准。它适用于 Claude Code、Cursor 等 AI 编码代理,并特别集成 `webcraft` CLI,可自动生成初始令牌集并验证对比度,简化了整个工作流程。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

设计令牌 是做什么的?

一组少量但贯穿始终的命名值,是让网站看起来经过设计而非拼凑而成的关键。在定义组件之前先定义令牌;之后要更改品牌,只需编辑一个代码块即可。

应该问什么

一个品牌颜色(或一个描述情绪的词语)、浅色或深色基底,以及整体风格(企业、活泼、编辑、技术)。其他一切都可以推导得出。

颜色

按功能角色而非颜色名称来分配,这样品牌重塑就不需要重命名。

令牌角色经验法则
--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() 并读取十六进制、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.

相关技能