turtleneck 是做什么的?
为应用选择正确的视觉风格,然后用纪律来构建它。每个视觉风格都是一个预设:一个文件,它覆盖共享核心之上的变量。默认预设 keynote 就是核心本身。每个其他预设是五个大型同类网站的风格混合,而非复制其中任何一个。
当此技能激活时,它会覆盖通用的“避免AI默认风格”技能(如 frontend-design),在它们不一致的地方:在 keynote 中,系统字体、句子大小写的眉毛文字和色调渐变标题是正确的。
此文件旁边的文件:
tokens.css:核心和 keynote 值。每个颜色都是light-dark(light, dark);:root、.a-dark、.a-light或data-theme上的color-scheme选择一半。所有预设的钩子都在其:root中列出。共享组件也在此:类型比例、按钮、磁贴、.a-grid、.a-rail、.a-stats、.a-reveal。styles/<preset>.css:变量覆盖加上一些预设专属规则。在tokens.css之后加载。styles/<preset>.md:每个预设一页:何时使用、标记表、规则、组件变更、字体、避免项、检查清单。recipes-html.md:页面骨架、导航、英雄区、磁贴、便当盒、画廊、对比、页脚(手机上为手风琴)、展示效果,以及共享的预设模式(翻转带、搜索英雄、轨道、规格表、计划卡、代码框架)。tailwind.md、swiftui.md:这些技术栈的相同标记。test-widths.html?src=<url>[&h=800][&full=1]:页面在 320/375/414 宽度下并排显示,并带有溢出报告;full=1使每个框架扩展到其文档高度,用于全屏手机截图。example.html和 agent-skills 仓库中的../../demos/:完成的页面。
步骤 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 驱动”作为产品;依赖 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 仅用于搜索和结果页面 |
用户风格词直接映射:“苹果风格/高级/干净” = keynote;“微软/Fluent” = enterprise;“网飞风格” = cinema;“Spotify 风格/TikTok 风格” = vibe;“游戏/NVIDIA 风格” = power;“Stripe / Vercel / GitHub 风格” = devtool;“OpenAI / Anthropic 风格” = lab;“Airbnb / Booking 风格” = journey;“亚马逊/宜家风格” = market;“银行/PayPal 风格” = vault;“特斯拉/宝马风格” = 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 依赖。 - 用 3 行编写页面计划:页面销售的核心内容、带背景的区块顺序、以及一个“亮点”(翻转章节、大统计便当盒、演示、视频、粘性滚动)。
- 先写文案:简短标题(预设设置长度)、一行副标题、引言最多两行。
- 根据配方构建,逐区块进行。
- 在每个测试宽度下验证(响应式),在预设同时支持浅色和深色模式下进行验证:截图、溢出检查、检查清单。在报告完成前修复问题。
核心规则
类型
- 一个字体家族用于 UI(仅真正的代码、键和 API 值使用等宽)。显示字重来自预设。
- 字距随着字号增大而收紧;正文的负字距不超过 -0.022em。
- 显示字号是流体的
clamp(min, rem + vw, max);始终在中间项中混合rem。 - 正文 16-17px 用于阅读;14px 仅在密集 UI、元信息行和页脚中使用。正文行高 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-*中;品牌色仍在此处。
- 一个强调色,小范围使用:主要 CTA、焦点、链接、logo 标记、小徽章和“推荐”标记。不用于大表面或正文文本,除非预设特别说明。状态颜色仅用于状态。
- 中性表面使用 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 | 全高清/四倍高清,超宽 |
| 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(较小的视觉元素获得点击区域),句子大小写,除非预设指定大写,无图标,除尾随的插入符号或箭头外。主要填充,次要按预设。
- 链接:明显是链接(颜色或下划线);在预设使用的地方使用“了解更多 ›”风格的插入符号。
- 磁贴/卡片:当整个磁贴链接时为一个 Tab 停止(内部按钮是
span)。圆角、填充、边框和阴影来自预设;永远不要同时使用填充 + 边框 + 阴影。 - 焦点环:2px 实线
--a-focus,偏移 1px,在每个交互元素上。 - 导航:按预设为实心或玻璃效果,最多一个粘性栏,当前页面标记。
- 页脚:安静:列中小的灰色链接,法律行;在手机上列变为
<details>手风琴。
图像
- 真实主体:产品、其 UI、用户自己的照片和媒体。大,有意裁剪。
- 没有使用笔记本的库存人物图片,没有 3D 斑点,没有表情符号,没有吉祥物,没有在每个标题前的图标。
- 没有资源时:将主体绘制为一次 SVG
<symbol>,通过 CSS 变量重新着色,或者以正确比例放置一个诚实的灰色占位符。
动效
- 过渡命名 pr
…
[内容已截断以进行翻译]