Communitygithub.com

AlessandroFare/fluxychat

使用 Refactoring UI(Wathan & Schoger)的具体规则设计和改进用户界面——约束间距/字体/颜色/阴影比例、通过字重和颜色而非字号实现视觉层次、通过模拟光线实现深度。适用于构建或样式化任何 UI(Web、应用、仪表盘、着陆页、组件),选择字号、间距、颜色、阴影或边框半径时,设计调色板或设计 Token 时,以及每当有人指出 UI“看起来不对劲”、“看起来业余”、“感觉杂乱/平淡/未完成”或要求“让它更好看”时。

fluxychat 是什么?

此技能基于 Refactoring UI 原则,为 AI Agent 提供了一套严格的视觉设计系统,用于构建高质量的用户界面。它核心包含三大模块:一套预定义的“设计尺度”(间距、字体、颜色、阴影等),要求严格从中取值,避免凭感觉随意选取;一套“设计流程”,包括从功能而非布局开始、先灰度后色彩、移动端优先等具体步骤;以及一套通过“消除竞争”来创造视觉层次的技术,如使用有限范围的文本颜色、通过减弱次要元素来突出主要元素等。该技能适用于所有主流 AI 编码工具(如 Cursor、Claude Code),使用时可直接引用其提供的 `assets/tokens.css` 作为基础设计 Token,并在遇到具体问题时参考 `references/diagnose.md` 等辅助文档。通过消除设计中的随意性,它能帮助开发者快速产出专业、一致且可访问的 UI。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AlessandroFare/fluxychat/tree/HEAD/.agents/skills/refactoring-ui-skill-main

在你喜欢的 AI 中提问

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

文档

Refactoring UI

视觉设计不是天赋。它是一套一次性做好的系统决策,加上少量创造层次结构的技术。这个技能就是这些系统和技术。

导致 UI 看起来业余的最大原因是临时拼凑值——这里 17px,那里 #3B82F6,悬停状态用 lighten(5%)。始终从一个尺度进行设计。


系统——使用它们,不要重新推导

从这些列表中选择。永远不要发明一个不在列表中的值。

间距和尺寸

基准 16px,由其因子和倍数构建而成:

4  8  12  16  24  32  48  64  96  128  192  256  384  512  640  768

小端紧密,大端分散。任何两个相邻值之间的差距不得小于约 25% —— 这使得选择变得明确。线性的“4 的倍数”尺度是失败的:它无法帮助你决定使用 120px 还是 124px。

将其用于 margin、padding、width、height、图标大小、边框宽度——所有空间相关的东西。同时固定一小套不透明度值(例如 .05 .1 .2 .4 .6 .8),用于禁用状态、覆盖层和悬停色调,而不是每次都凭肉眼调节滑块。逻辑与其他尺度相同:一次决定,处处复用。

字号比例

12  14  16  18  20  24  30  36  48  60  72

不是由比例(4:5、2:3、黄金比例)构建的模块化尺度。那些会产生分数像素值,在不同浏览器中舍入不一致,并且对于界面密度来说过于稀疏——手工挑选的值,根据感觉选择,反而更好。

单位:仅使用 px 或 rem。绝不要使用 em。 em 相对于当前字体大小,因此一个内嵌在 1.25em 父元素中的 .875em 会计算为 17.5px——不在你的尺度中。尺度会悄然消失。

字重

两个字重就足够了:

  • 400 或 500 — 正文和大多数 UI 文本
  • 600 或 700 — 任何需要强调的内容

在 UI 中不要使用低于 400 的字重。要弱化强调,使用更浅的颜色或更小的大小——绝对不要使用更轻的字重。

颜色

你需要的颜色远多于五色板生成器所能提供的。

  • 灰色:8–10 种色阶。 几乎整个 UI 都是灰色的——文本、背景、面板、边框、表单控件。三四种色阶永远不够。从一个非常深的灰色开始,而不是纯黑(纯黑看起来不自然)。
  • 主色:5–10 种色阶,一种或最多两种主色。
  • 强调色:每种 5–10 种色阶 —— 破坏性红色、警告黄色、积极绿色,以及产品需要区分的其他颜色(图表序列、日历事件、标签)。对于复杂的 UI,十种颜色 × 5–10 种色阶是正常的。

将它们命名为 100(最浅)→ 900(最深),基准为 500。

按此顺序构建色阶: 首先选择 500(对于主色/强调色,它应该是可以作为按钮背景的色阶)。然后找到边缘——900 通常是你的文本色,100 是背景色;alert 组件会用到两者,所以设计一个组件并从中读取两个值。然后填充 700 和 300 作为其相邻值的完美折中,然后以同样的方式填充 800 600 400 200。

使用 HSL 而非十六进制编写颜色。 hsl(220, 95%, 34%) 和 hsl(220, 65%, 61%) 在视觉上是相关的;而 #03369E 和 #507DD7 则看不出关联。

绝对不要在运行时使用 lighten() / darken() 生成色阶。这正是你最终得到 35 种略有不同蓝色的原因。

阴影——五个层级

0 1px 3px  hsla(0,0%,0%,.2)   /* 几乎不凸起 — 按钮 */
0 4px 6px  hsla(0,0%,0%,.2)   /* 下拉菜单 */
0 5px 15px hsla(0,0%,0%,.2)
0 10px 24px hsla(0,0%,0%,.2)
0 15px 35px hsla(0,0%,0%,.2)  /* 模态框 */

通过询问这个元素在 Z 轴上位于哪个位置?来选择,而不是哪个阴影看起来不错?。离用户越近 = 越多的注意力。在 :active 时缩小按钮的阴影会使其感觉被按下;在拖拽排序时增大列表项的阴影则相反——它被解读为“现在位于其兄弟元素之上”,并同时充当拖拽的可感知提示。

这五个是默认的,在任何地方都适用。references/techniques.md 提供了同一尺度的精炼两部分版本——是平行的,但不是完全相同的值(其顶层更重)。当阴影在设计中被突出使用时,使用那个版本;否则使用这个版本。不要在同一个项目中混合使用两者。

行高和行宽

行高与字号成反比,与行宽成正比:

  • 小文本 / 宽列 → 1.5 到 2
  • 大标题 → 1 就很好

行宽:45–75 个字符,即 max-width: 20em–35em。这适用于段落,即使其容器更宽——在一个内容区域中使用混合宽度看起来更精致,而不是更差。

(em 在这里是正确的——度量应与它包装的文本一起缩放。“绝不要使用 em”规则的范围仅限于字号比例,在那里 em 会因嵌套而复合。不要“修复”这个。)

边框半径

选择一个并保持一致。小的半径 = 中性。大的半径 = 有趣。没有半径 = 严肃/正式。在一个界面中混合方形和圆角看起来总是更糟糕。


设计流程

1. 从功能开始,而不是布局。 不要设计“整个应用”——在你知道产品里有什么之前,你无法决定是使用顶部导航还是侧边栏。首先设计一个真实的功能(搜索表单、消息编辑器),让外壳自然呈现。

2. 细节稍后处理。 早期忽略字体、阴影和图标。先以灰度工作——这会迫使层次结构来自间距、对比度和大小,而不是颜色。布局可行后,再加入颜色。

3. 不要过度投入低保真设计。 草图、线框和 mockup 是可丢弃的——没有人能使用应用的静态图。它们存在的目的是探索想法;一旦做出决定就放弃它们,然后去构建真实的东西。

4. 设计最小可行版本,然后构建它。 在短的设计→编码周期中工作。不要暗示你不准备构建的功能——一个带有你还不能交付的附件区域的评论框会阻塞整个功能。锦上添花的功能稍后再设计。

5. 通过淘汰来选择。 从尺度中选择值时:猜测你认为正确的值,然后与其两侧的相邻值进行比较。其中两个会明显错误。如果外部的选项胜出,那么以那个胜出的选项作为新的中间值,重新进行比较。

6. 从过多的空白开始,然后移除它。 添加空间直到看起来不错为止,得到的是最小值。从宽松开始并修剪,得到的是正确的量。密集的 UI(仪表盘)是合理的——但要作为一个刻意的决定,而不是默认值。

7. 缩小画布。 在 1400px 的画板上设计一个小型组件往往会变得松散,因为空间是现成的去填充。从 ~400px 开始,先设计移动端布局,那里的约束是真实的——然后将其放到大屏幕上,只放松那些真正感到局促的部分。你将比你预期的改变得更少。


层次结构——效果最好的技术

屏幕上的所有内容都位于一个金字塔中:主要、次要、第三级。当一切都在竞争时,UI 读起来就是噪音。这就是让设计看起来“经过设计”的东西——而不是样式。

大小不是万能的。 仅仅依赖字号会导致主要内容太大,而次要内容太小。改用字重和颜色来承载强调,并保持大小合理。

最多三种文本颜色:

  • 深色 — 主要内容
  • 灰色 — 次要内容
  • 更浅的灰色 — 第三级内容(脚注、版权信息)

所有三种都需要承载实际正文大小的文本,因此都需要 4.5:1 的对比度。“更浅的灰色”指的是仍能通过此标准的最浅色阶——大概是 9 级色阶梯度的中间,而不是浅色端。浅色端只用于禁用状态和大文本。

通过弱化来强调。 当重要元素不够突出,并且无法再添加任何东西时,转而柔化与之竞争的元素。淡化非活跃的导航项;降低侧边栏的背景色,以便主要内容向前突出。

操作: 按层次而非语义来设置样式。

  • 主要 → 实心,高对比度。通常每页只有一个。
  • 次要 → 描边,或低对比度背景。
  • 第三级 → 样式像链接一样。

破坏性操作 ≠ 大红按钮。如果“删除”不是页面上的主要操作,就给它第三级处理——然后在确认对话框内部让它变成一个大红按钮,在那里它才是真正的主要操作。

标签是最后的手段。 标签: 值 给每条数据赋予了相同的权重。大多数数据通过其格式($19.99、电子邮件地址)或上下文来标识自己。在真正需要标签的地方,将其融入值中(“库存还剩 12 件”,而不是“库存:12”),或者将其添加为明显次要的内容。例外情况:在规格表样式的页面上,用户为了标签而扫描时,则要强调标签。

平衡字重与对比度。 实心图标在视觉上很重,会压过旁边的文字——柔化它们的颜色以进行补偿。反之亦然:当 1px 的边框在浅色中过于微妙,但加深后又过于刺眼时,保持浅色并增加为 2px。增加“重量”来修复低对比度;降低对比度来修复过重的“重量”。

视觉层次 ≠ 文档层次。 语义化标记和视觉重量是独立的决定。章节标题通常是标签,而不是标题——16px 的 h1 就很好,有时标题应该完全视觉隐藏,因为内容本身已经说明了问题。


硬性规则

偏离这些会产生特定的、可识别的失败。

  1. 绝不要在有颜色的背景上使用灰色文本。 灰底白字有效是因为它降低对比度;彩色背景上的灰色看起来只是脏。白色降低不透明度看起来像是褪色和禁用,并且让图案透过字形显示出来。手动选择一种带有背景色色调的颜色,调整饱和度和明度。
  2. 绝不要为字号比例使用 em。 使用 px 或 rem。
  3. 绝不要在运行时生成色阶。 预先定义好它们。
  4. 绝不要为不应缩放的东西使用百分比宽度。 侧边栏使用固定宽度;主要内容区域弹性伸缩。元素应有 max-width,并且只在屏幕实际更小时缩小——登录卡片不应在中屏时比大屏时更宽。
  5. 绝不要在断点处按比例缩放东西。 大的元素必须比小的元素更快地缩小。一个在 14px 移动端正文字体旁的 2.5em 标题计算为 35px——太大了;它应该在那里是 20–24px。同样,按钮的内边距应随着按钮缩小而按比例收紧,而不是随其字体大小缩放。
  6. 始终使一个组周围的间距大于组内部的间距。 这是修复“哪个标签属于哪个字段”、紧凑的列表项以及看起来连接到错误段落的标题等问题的关键。模棱两可的间距是一个功能性的错误,不仅仅是丑。
  7. 绝不要将颜色作为唯一的信号。 添加图标、形状或文本提示。对于图表,通过对比度(一种颜色的从浅到深色阶)来区分系列,而不是通过色相——色盲用户能可靠地读取亮度,但不太能读取色相。
  8. 对比度最小值: 普通文本为 4.5:1。3:1 的允许值仅适用于大文本,WCAG 将其定义为 24px 常规或 18.66px 加粗——而不是 18px。除非文本真正有那么大,否则假设使用 4.5:1。当浅色文字在深色背景上失败时,反转使用:深色文字在浅色背景上(参见 references/systems.md)。另外,3:1 也适用于非文本内容(WCAG 1.4.11):如果边框是识别控件的唯一方式——比如输入框外轮廓、复选框边缘——它需要与其背景有 3:1 的对比度。仅仅用于分隔内容的极细线则不需要。这是两个不同的标记,不是同一个。
  9. 绝不要将图标缩放得与其设计尺寸相差甚远。 一个 16–24px 的图标放到 48px 会显得厚重且细节不足。相反,把它放在一个彩色圆圈里。

参考资料

assets/tokens.css — 一个完整的、经过对比度验证的 CSS 自定义属性起始集,包含上述所有内容:间距、字体、字重、边框宽度、固定的不透明度比例、9 级冷灰色阶、9 级主色、三个强调色三元组、五个层级、一个语义角色层(--surface、--text-primary、--action…)和一个深色模式块,该块仅覆盖这些角色。复制它并根据调整色调,而不要从这些文字中重新推导尺度。在组件中引用角色,而不是原始的色阶——这正是深色模式工作的原因。每个文本/表面对在两种模式下都经过验证 ≥4.5:1,每个功能性边框 ≥3:1;故意的次阈值色阶(禁用状态、装饰分隔线、仅供大文本使用的步骤)根据标准被豁免,并在内联注释中标明。

当工作需要时加载这些:

  • references/systems.md — 从头开始构建调色板:选择基础颜色、在浅色和深色端保持饱和度、色相旋转、暖/冷灰色、以及在达到对比度时避免难看颜色的两种逃生方案。
  • references/diagnose.md — 症状 → 修复对照表。当任务是改进现有 UI 而非构建新 UI 时,首先加载。
  • references/techniques.md — 深度和灯光模拟、两部分阴影、基线对齐、字间距、打破默认组件形状以及处理用户上传的图像。

Individual skills in this repo

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

AlessandroFare/fluxychat

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet `anchor` rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.\n

AlessandroFare/fluxychat

Use when audio already placed in a HyperFrames composition needs to be mixed: a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), or automation envelopes drawn on a track's volume or any effect parameter. Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.\n

AlessandroFare/fluxychat

Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.\n

AlessandroFare/fluxychat

Install, discover, and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

AlessandroFare/fluxychat

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.\n

AlessandroFare/fluxychat

Overlay doctrine for the embedded-captions workflow — the caption MODEL (drop / rail / embed) and the rule that captions are an OVERLAY composited on top of the film, never a reserved bottom band you shift content up to avoid. Load when adding captions/subtitles to a talking-head or launch video, when deciding whether a phrase should be dropped, ride the verbatim rail, or be promoted to a scarce embedded climax, when laying out a composition that will carry captions (do NOT reserve a keep-out band), or when centering a composition on the true frame center under captions. Quotes the rail+embed model from embedded-captions and constraint #13 (captions overlay, keep-out band retired) from the product-launch-video scene agent. Applies ON TOP of embedded-captions.

AlessandroFare/fluxychat

Turn a weekly changelog .md into a finished branded changelog video (square 1080, ~45-60s, Annie VO, animated brand background, mock-UI visualizations, lowkey captions). Use when the user provides a changelog/digest markdown and wants the weekly video, or says "changelog video". Self-contained — fonts, background, lexicon, and scripts ship in this skill.

AlessandroFare/fluxychat

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

AlessandroFare/fluxychat

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

AlessandroFare/fluxychat

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

AlessandroFare/fluxychat

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition HTML.

AlessandroFare/fluxychat

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

AlessandroFare/fluxychat

Use when a HyperFrames composition needs seek-safe 2D/3D keyframes, GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

AlessandroFare/fluxychat

GATEWAY — load FIRST before composing any HyperFrames animation or video. The high-level motion law that makes a multi-scene video feel like ONE continuous camera move instead of a stack of independently-animated slides. Covers the vector law (how you exit determines how you enter, incl. the Z scale-sign rule), the film's current, carrier elements, causal motion, the Seam Gate (build-gate enforcement), the ban on idle wobble (motion must PERFORM, not breathe), stillness-before-climax, and the sustained-motion routes. Routes to the low-level technique skills (cut-the-curve — the full catalog incl. waterfall entry + nudge curve, oversized-cursor, seam-craft). These rules SUPERSEDE generic / upstream motion guidance. [continuity, direction, vector, momentum, seam, transition, ease, performance, idle-motion, narrative-motion, film-grammar]

AlessandroFare/fluxychat

A short, design-led motion graphic where motion is the message — kinetic typography, stat count-up, chart/data-viz hit, logo sting / brand lockup, lower-third / callout / social overlay, animated map (highlight regions, connect places, zoom to a location), animated tweet / news-article / headline, webpage / UI animation (scroll, cursor, callouts), or fusing a real image's geometry into a chart. Usually under 10s (up to ~30s), no narration or live-action subject; renders to MP4 or transparent overlay. Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.

AlessandroFare/fluxychat

Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.

AlessandroFare/fluxychat

Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes.

AlessandroFare/fluxychat

Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes.

AlessandroFare/fluxychat

Port an existing Remotion (React) composition''s source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing Remotion mention, reference-only code, or "make something like my Remotion video" is a fresh build (/general-video). Unclear → /hyperframes.

AlessandroFare/fluxychat

Use before UI-related work to select the smallest useful UI Skills context through the ui-skills CLI.

相关技能