ux-ui-maxpro

ux-ui-maxpro

一本用于在本仓库的设计系统中精确复现参考 UI 的操作指南，避免偏离成近似效果或捏造内容。针对 snapcn 技术栈优化（Next.js App Router + Tailwind v4 + 由 token 驱动的 app/globals.css、DESIGN.md 规则），但方法不依赖特定技术栈。

唯一准则

先测量，再编写。 切勿凭目测直接将参考图写进代码。先提取书面规范，再按规范编写代码。猜测只会得到「差不多」，而用户说「哪怕一点改动都不行」时，恰恰拒绝的就是「差不多」。

1. 从参考图中提取规范

像分析设计系统一样查看截图，并在修改任何文件前记下具体数值：

• 结构：有多少个区域（顶栏、侧边栏、内容区），以及每个区域的宽度和高度。注意顶栏是否带有边框、阴影、模糊效果，还是与页面背景齐平。
• 网格：最宽断点下的列数、间距，以及列数如何逐级减少（4 → 3 → 2 → 1）。对于瀑布流，注意卡片高度是否不同、差异有多大——这种错落节奏通常正是设计的重点。
• 卡片 / 瓷砖：圆角半径、表面颜色、有无边框、是否带阴影，叠加元素（头像、按钮）的尺寸和距角落的内边距。
• 字体：每种文本用途（标题、标语、元信息、导航链接）的字号、字重和颜色。注意哪些文本用途会在同一基线上并排显示（例如粗体标题 + 灰色标语）。
• 胶囊按钮 / 控件：胶囊高度、水平内边距、间距，以及激活与未激活状态的样式（常见做法是黑白反转）。
• 颜色：取样精确的表面灰色和强调色。它们很少是纯 #fff / #000。

将这份规范放在手边；你编写的每个类名都应能对应到一个测量值。

2. 将每个元素映射到真实数据

为每个参考元素确定它在本项目中对应的真实数据。绝不捏造看起来像实时数据的数字（这是本仓库的一贯规则）：「63 人在线」指示器应改为真实推导出的计数（例如组件总数）；「11 小时前更新」应使用来自 API 的真实时间戳，并提供平稳的回退方案，而不是硬编码字符串。如果没有真实数据可以对应，就删掉该元素，不要造假。补上参考图中缺少的无障碍功能——仅含图标的链接应添加 aria-label / title，筛选胶囊应添加 aria-pressed。

3. 通过 token 设置样式，绝不使用十六进制值

根据 DESIGN.md，组件不得硬编码颜色、圆角或阴影。参考图所需的任何新表面样式（例如画廊卡片的灰色）都应成为 app/globals.css 中的新语义 token：

• 在 :root（浅色）和 .dark（深色）中都添加原始值——必须提供对应的深色值，即使参考图只有浅色模式；深色值需凭目测调整。
• 在 @theme inline 中注册该 token（--color-<name>: var(--<name>)），以便使用 bg-<name> / text-<name> 工具类。
• 如果要实现精确效果，必须偏离 DESIGN.md 中已有的规范（例如胶囊按钮、模糊效果的标签、无边框卡片），就给 DESIGN.md 添加一条简短补充说明，避免后续贡献者将其「修正」回去。

4. Masonry 方案

• CSS columns（columns-N，子元素使用 break-inside-avoid mb-*）是默认方案：它会按列从上到下排列，服务端渲染（SSR）时不会产生布局偏移，而且——最重要的是——会让所有卡片处于同一个 DOM 父元素下，因此稳定的 React key 可以在筛选和排序时保留卡片的挂载状态。除非设计确实需要从左到右的行顺序，否则请使用此方案。
• JS 平衡分列（测量高度，并将内容放入最短的列）可实现按行优先的顺序，但会增加首次绘制前的测量步骤，并导致子元素在不同列父元素之间重新挂载。只有在行顺序是硬性要求时才使用。
• 营造多变的节奏感：当源媒体尺寸统一（例如全部为 16:9）时，根据索引或 slug 的稳定函数，为每张卡片分配确定的平铺形状，这样即使列表经过筛选或重新排序，形状也不会改变。让实际媒体内容在平铺区域中完整显示并居中（除非用户选择裁切，否则绝不裁切）——根据静态平铺宽高比与媒体宽高比的比较，计算受限的尺寸。

5. 重媒体网格

包含 100 个以上实时播放器或视频的网格不能一次性全部挂载。请复用此仓库中经过验证的模式：通过 IntersectionObserver（rootMargin: "200px 0px"）延迟挂载每个预览，挂载前保留占位内容，并在卡片滚出屏幕时暂停播放，确保同一时间只渲染少量内容。筛选导致卡片卸载时，其播放器会自动释放；请保持 key 稳定，避免幸存卡片被不必要地重新挂载。

6. 在两种主题中通过叠加对比验证

只有效果匹配才算“完成”——请用证据证明：

• 运行应用，并在与参考图完全相同的断点处截取构建后的页面。
• 将两张图以约 50% 不透明度叠加（或并排放置），检查每个测量值：栏高、基线对齐、胶囊高度和间距、间隙、卡片圆角、叠加层尺寸和内缩值。
• 在每个断点边界处调整尺寸，并确认列数按规定变化。
• 切换浅色/深色主题，确认所有新增设计 token 在两种主题下都显示正确。
• 沿键盘导航路径（胶囊 → 控件 → 卡片）逐项切换，并确认焦点环和 ARIA 均正常。
• 打开你并未打算修改的同级页面，并确认它们的字节内容完全一致——共享界面的修改很容易造成影响外溢。

只有在叠加对比结果匹配且同级页面未受影响后，才能认定工作完成。