Communitygithub.com

turtleneck

为网页和应用UI选择正确的视觉风格,并通过预设样式系统实现。基于项目类型和行业自动检测,应用整合了多个大型参考网站风格的预设,支持纯HTML/CSS、Tailwind和SwiftUI。

turtleneck 是什么?

turtleneck 是一个AI代理技能,旨在帮助开发者快速为网页或应用UI选择并实现合适的视觉风格。它通过检测项目类型(如登录页、产品页、仪表盘、文档站等)和行业(如硬件、商业软件、流媒体、游戏等),自动从多个预设(如 keynote、enterprise、cinema、vibe、power、devtool、lab、journey、market、vault、drive)中选择一个。每个预设是五个同类大型参考网站风格的混合,而非简单复制,并提供了详细的变量覆盖、组件配方和响应式测试指南。该技能支持纯HTML/CSS、Tailwind CSS(v3/v4,包含 shadcn)和 SwiftUI 多种技术栈,并强调尊重现有设计系统、品牌色彩和可访问性(AA无障碍标准)。其工作流程包括:先识别项目类型和预设、读取预设文档、编写页面计划、使用配方构建、并在多种视口下严格测试以确保响应式正确性。

兼容平台✓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);: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:检测应用类型(强制性,在任何代码之前)

  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 驱动”作为产品;依赖 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 仅用于搜索和结果页面

用户风格词直接映射:“苹果风格/高级/干净” = keynote;“微软/Fluent” = enterprise;“网飞风格” = cinema;“Spotify 风格/TikTok 风格” = vibe;“游戏/NVIDIA 风格” = power;“Stripe / Vercel / GitHub 风格” = devtool;“OpenAI / Anthropic 风格” = lab;“Airbnb / Booking 风格” = journey;“亚马逊/宜家风格” = market;“银行/PayPal 风格” = vault;“特斯拉/宝马风格” = 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. 用 3 行编写页面计划:页面销售的核心内容、带背景的区块顺序、以及一个“亮点”(翻转章节、大统计便当盒、演示、视频、粘性滚动)。
  3. 先写文案:简短标题(预设设置长度)、一行副标题、引言最多两行。
  4. 根据配方构建,逐区块进行。
  5. 在每个测试宽度下验证(响应式),在预设同时支持浅色和深色模式下进行验证:截图、溢出检查、检查清单。在报告完成前修复问题。

核心规则

类型

  • 一个字体家族用于 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手机横屏
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(较小的视觉元素获得点击区域),句子大小写,除非预设指定大写,无图标,除尾随的插入符号或箭头外。主要填充,次要按预设。
  • 链接:明显是链接(颜色或下划线);在预设使用的地方使用“了解更多 ›”风格的插入符号。
  • 磁贴/卡片:当整个磁贴链接时为一个 Tab 停止(内部按钮是 span)。圆角、填充、边框和阴影来自预设;永远不要同时使用填充 + 边框 + 阴影。
  • 焦点环:2px 实线 --a-focus,偏移 1px,在每个交互元素上。
  • 导航:按预设为实心或玻璃效果,最多一个粘性栏,当前页面标记。
  • 页脚:安静:列中小的灰色链接,法律行;在手机上列变为 <details> 手风琴。

图像

  • 真实主体:产品、其 UI、用户自己的照片和媒体。大,有意裁剪。
  • 没有使用笔记本的库存人物图片,没有 3D 斑点,没有表情符号,没有吉祥物,没有在每个标题前的图标。
  • 没有资源时:将主体绘制为一次 SVG <symbol>,通过 CSS 变量重新着色,或者以正确比例放置一个诚实的灰色占位符。

动效

  • 过渡命名 pr

…

[内容已截断以进行翻译]

相关技能