bruno-baeta/clean-ui

Clean UI

界面简洁、现代，支持浅色和深色主题，适配屏幕，数据优先，具有真实产品质感，而非 AI 生成。以下规则源于真实的调整请求。每一条规则在被违反时都曾激怒过用户：请将其视为硬性要求，而非建议。

Skill 文件

路径相对于此 skill 文件夹。

文件	何时使用
references/informacao.md	每个新屏幕或重新设计，在布局之前使用。 如何选择展示内容、优先级顺序以及每个信息项的位置（库存、用户问题、级别、筛选器、位置地图、书面计划）。
references/padroes-aprovados.md	用户已批准的模块（“好多了”）：决策卡、包含阈值线的决策度量图表、带有随时间变化余额的状态卡、用户自己的列表、季节性支持、移动端头部、优先级排序、超宽屏。用作内容的起点，而非固定骨架。
references/armadilhas.md	已导致返工的技术错误（Tailwind v4、无合并的 cn、[&>*]: 的特异性、next-themes、带有旧 CSS 的服务器、测试本地数据库中没有的状态）。在编写代码前阅读。
references/migracao.md	重新设计整个应用（多个屏幕）：先设计已批准的参考屏幕，由您创建基础（框架、页面组件、body 中的 tokens、保存的主题），使用共享的通用简介并行推进，集成（按需请求 kit，仅在最后删除旧代码，重启，验证所有内容）。
references/exemplos.md	错误和正确的真实案例。在创建新屏幕或不确定某些内容是否足够好时阅读。
references/dashboards.md	每个包含数字、图表或地图的屏幕。 区分业余与专业的要素、原则（NN/g、Stephen Few、IBM Carbon）、7 种构图（选择适合信息规划的一种）、宽屏和超宽屏的规则、图表的颜色和装饰。
references/paletas.md	现成且经过验证的调色板（Cobalto、Indigo、Cyan、Coral），包含灰色、强调色、有序色阶和两个主题的系列色。请在此处选择，切勿使用零散的颜色。
assets/tokens.css	新项目或无品牌标识的项目：浅色和深色主题（遵循系统，可手动切换）、字体、焦点、图表和触摸均已配置（Tailwind v4）。附带 Cobalto 调色板仅作为起点：用所选调色板的完整模块替换（paletas.md 末尾）。包含 tall 变体、正/负/警告状态和手指光标。
references/exemplos-dashboards/	用户的 7 个现代仪表盘参考。在绘制任何仪表盘之前全部打开。
references/anatomia-dashboard.md	转化为尺寸的参考：卡片、标题、指标、标签、图表顶部的数字、图表、整体中的部分、仪表、表格、移动端以及不应复制的内容。
assets/dashboard.tsx	仪表盘套件，根据参考测量：DashCard、Kpi、IconCircle、DeltaChip、StatusChip、TrendDot、CountBadge、Tabs、SeriesStat、StatColumns、Dashed、KeyValue、StackedBar、LegendGrid、Gauge、表格的 TH/TR 类、TooltipCard、PillMark、用于 Recharts 的 chart props、ListaAlta（垂直卡片中的列表，按高度分页）、Divergentes（总计和扣除项）、Quadro100（每 100 个中的数量）、Colunas（浮动列；瀑布图和漏斗图因难以理解已被否决）、useFitRows（适合的行数）和 useFitHeight（根据窗口剩余空间确定图表高度；当上方卡片增大时重新计算）。
assets/painel.tsx	地图助手：useMapColumns（地图列的宽度）和 FillMap（填充整个区域的全球地图）。
assets/ui.tsx	现成的基础组件（Card、Section、IconBox、Chip、Pill、Button、BottomActions、ListRow、ListCard、StatCard、DateBlock、FillEmpty、InfoTip、NavLoading、Spinner、ThemeToggle、FitScreen）。重复使用或适配，而非重新发明。如果项目已有等效组件，则使用项目的组件。
scripts/lint-ui.mjs	node <skill>/scripts/lint-ui.mjs src：扫描修改后的代码（鼠标悬停导致移动、省略号、彩色边框、窄宽度、禁用字体、破坏其中一个主题的固定颜色、“—”、“ · ”、小写、“标签: 值”）。
scripts/check-ui.mjs	node <skill>/scripts/check-ui.mjs http://localhost:3000/rota --out=prints：在 320 和 390 px（移动端）以及浏览器内容区域（1366×650、1536×730 和 1920×950（笔记本和显示器）以及 2560×960、2752×1100（Windows 缩放 125% 的 21:9）和 3440×1300（超宽屏 21:9））下截图，覆盖深色 和 浅色主题，并测量水平溢出和垂直溢出（卡片超出第一屏底部边缘或高于屏幕）、重复的相似列表、拉伸的图表和过宽的列表行、“…”、相邻卡片高度不同（也在无背景的包装器内）、卡片内部空白或内容分散、不完整的网格、无容器的图标、鼠标悬停导致移动、内部滚动、内容狭窄、字体、可点击元素无手指光标、卡片边框在行间几乎对齐、信息图标气泡超出屏幕（逐个打开）、移动端滚动条、过宽的表格行（任何重复的行）、内容挤压、移动端列表行标题或描述换行以及空白或错误页面（等待加载；如果数据未加载，则检查无效）。每个发现项都附带尺寸和主题。项目需要安装 Playwright；--user/--pass 用于需要密码的页面。

脚本是指导性的：检查每个发现项，最重要的是，打开截图并查看。

1. 流程（导致返工的最主要原因）

1. 只做要求的事。 未经明确要求，切勿删除、替换或“简化”现有元素。如果建议需要删除某些内容，请先询问。不确定时，保持原样。
2. 遵守要求的断点。 要求在移动端调整：Web 端不变（使用 sm:/md: 保留 Web 端，反之亦然）。
3. 在发布前展示，查看所有尺寸。 在说“看起来不错”之前，打开检查中 每个 尺寸的截图（包括 1366、1536 和 2752，这些尺寸下表格可能换行且卡片可能溢出），而不仅仅是 390 和 1920。委托给代理的工作也是如此：请亲自检查。在本地运行，在 移动端（390 px，并检查 320 px） 和 Web 端（1366×650、1536×730 和 1920×950，浏览器的实际内容区域） 下截图，覆盖 两个主题，真正查看每个截图，并且仅在获得明确批准后才执行 commit/push/deploy。
4. 新屏幕或重新设计：先处理信息，再处理布局。 遵循 references/informacao.md（并查看 references/padroes-aprovados.md 中的模块以及 references/armadilhas.md 中的错误）：产品已知信息的清单（包括旧屏幕显示的所有内容）、按紧急程度排序的用户问题、优先级级别、每个信息的筛选器、位置地图和书面计划。构图由此计划得出。由您选择构图和调色板（如果项目有品牌则使用品牌调色板；否则从 paletas.md 中选择与主题匹配的调色板）。不要构建多个版本或屏幕视图供用户选择。 构建一个最好的版本，并用简短的语言解释每个元素为何在各自的位置。切勿从以前项目的骨架开始，也不要默认重复“4 个指标 + 卡片网格 + 列表”。
5. 同一细节被否决两次 = 并排选项。 仅在用户已经否决了同一细节（如标签位置、字体）两次时，才在截图中展示该细节的 2 或 3 种变体。切勿用于整个屏幕。
6. 删除或重新创建文件后，在检查前重新启动开发服务器（或重新保存 CSS）：Tailwind 可能仍在提供旧 CSS，不包括新类。
7. 在每次截图前使用清单（第 10 节）进行审查。 如果没有对称性，则尚未准备好。

2. 排版

• 禁用字体（AI 感）： Inter、Roboto、Arial、Helvetica、用作品牌字体的 system-ui、Geist、Poppins、Montserrat、Space Grotesk、Open Sans、Lato。
• AI 较少使用的优秀字体： Plus Jakarta Sans（首选且已获批）、Manrope、Onest、Figtree、Hanken Grotesk、Schibsted Grotesk、Instrument Sans、Albert Sans、Familjen Grotesk。对于强调标题，使用 Bricolage Grotesque。每个应用使用一个字体家族。
• 数字使用 font-variant-numeric: tabular-nums（tabular-nums）。不要使用带有截断或点状零的等宽字体。
• 通过适度的粗细和大小来建立层级。上方小标签（12 px，暗淡颜色），下方值（16 px，半粗体）。并排的值使用相同的字体大小。不要使用巨大的彩色文本。
• 所有可见文本以大写字母开头，包括单独的缩写（“Qui”、“Sex”）。在句子中间，正常书写：“Vs terça anterior”，而非“Vs Ter anterior”。标题使用句子大小写，切勿全大写。

3. 颜色和主题

• 始终是双主题，浅色和深色。 每个应用自诞生起就支持两个主题：遵循系统主题（prefers-color-scheme）并提供一个切换按钮（assets/ui.tsx 中的 ThemeToggle），并保存用户选择。电子邮件和预览也应响应 prefers-color-scheme。任何屏幕都不能仅存在于一个主题中。
• 颜色始终通过 token 使用（var(--card)、bg-card、text-muted-foreground）。切勿在组件、图表或 SVG 中使用 #000、#fff、bg-black、text-white 或散落的十六进制颜色：这会破坏另一个主题。
• 深色： 非常暗的背景（接近黑色），卡片稍亮一级，边框柔和，文本近乎白色。浅色： 非常浅灰色的背景，白色卡片，轻微边框，文本近乎黑色。两者一视同仁，并在截图中检查。
• 调色板并非固定，但也不是零散的。 不存在标准的“黑色 + 橙色”：使用 references/paletas.md 中的完整调色板（灰色、强调色、色阶和系列颜色，这些已通过对比度和色盲验证），根据主题选择并展示渲染效果。不要混合零散的颜色（一个地方的蓝色，另一个地方的黄色，又一个地方的红色）。有品牌的项目遵循其调色板（例如，MegaLab 选择了橙色）；只有在对两个主题的卡片对比度至少达到 3:1 且对色盲用户可区分时，才能使用新颜色（如果代理有 dataviz 指南，请使用其验证器）。
• 中性基底，颜色有目的。 灰色约占屏幕的 90%。每个应用使用一个强调色（按主题版本）。有序数据（数值、级别、范围）使用 单一颜色 的色阶（--seq-1..4），切勿使用灰色、蓝色、黄色和红色的彩虹色。无序系列使用固定顺序的 --cat-1..3。红色/黄色警报色仅用于真正的状态，并附有图标和标签。绿色永远不是品牌色，但可以出现在数据中：表示“改善”的变化标签、良好状态以及经过验证的调色板中的分类系列 3。没有随机的紫色，没有棕色。
• 数字永不染色。 值和标签使用文本颜色；数据的颜色放在旁边的小标记中（点、细条、带有彩色小条的标签）。
• 改善和恶化变化（如用户参考所示）：柔和绿色标签和柔和红色标签，始终带箭头，以便无法区分颜色的人识别（DeltaChip）。无变化：灰色标签。
• 相似状态（例如：错误、困难、良好、容易）需要彼此明显不同的颜色。
• 没有彩色边框或光环来突出显示卡片。突出显示仅使用柔和的背景色（bg-primary/10）。
• 文本在两个主题中始终可读，包括点击后的图表图例和工具提示。

4. 布局和对称性

• Web 端全宽。 没有居中的窄内容（max-w-* + 页面上的 mx-auto）。使用网格填充屏幕。
• 宽屏应增加列数，而非拉伸内容。 从 1920 px 及以上以及超宽屏 21:9（2560 和 3440 px），使用 3xl:（1920 px）和 4xl:（2560 px）增加列数（在 tokens.css 中定义）；切勿使用 min-[1920px]:（在 Tailwind v4 中它输给 lg:），打开之前隐藏的面板（侧边详情、图表旁边的表格），并限制比例：时间图表最多约 4:1，条形图和地图最多约 2.5:1，列表行最多约 720 px。参见 references/dashboards.md 第 4 节。
• 移动端优先。 舒适的侧边间距（16 px），不紧凑，轮播图有水平呼吸空间，首项上方有空间。
• 适配屏幕高度。 内容在两个维度上适应窗口，而不仅仅是宽度。没有固定大小的地图、图表、图像或卡片超出第一屏底部边缘或高于窗口（只有列表可以继续向下滚动页面）：地图、图表和大型图像的高度受窗口限制（max-h-[calc(100dvh-<header>)]、h-[min(…,60dvh)]、SVG 使用带 `preserveAspectRatio=