design-to-react-algorithms

dot-skills 设计稿到 React 转换最佳实践

将 Sketch 文件逆向转换为像素级精准的 React + CSS 的流水线，并以迭代时确保回归安全为核心约束。该技能围绕设计稿转代码的级联效应组织：第 N 阶段的错误决策会污染第 N+1 阶段及之后的所有输出，因此各类别按其影响下游的范围排序。

用户的首要要求——“每次改进都不会导致回归”——只有在迭代循环、图层树和布局求解器都正确之后才可落实，之后才能开始润色样式。请按优先级顺序阅读规则。

适用场景

• 构建一个读取 .sketch 文件（或同类设计源文件）并输出 React + CSS 的转换器
• 迭代现有转换器，而每次改进都有可能破坏其他组件
• 诊断转换后的组件为何“几乎匹配”设计稿，却未通过视觉回归测试
• 为设计稿转代码流水线设计快照门禁／基线策略
• 当源文件使用自由形态几何时，选择使用 flexbox、grid 还是绝对定位
• 将 Sketch 专属原语（MSImmutableFlexGroupLayout、attributedString、curvePoint、MSImmutableStyleCorners）转换为符合 CSS 惯例的写法

按优先级划分的规则类别

排序体现了级联关系——先修复前面的阶段；如果上游树结构有误，后续阶段的修复都会白费。

优先级	类别	影响	前缀
1	逆向工程迭代策略	严重	iter-
2	树结构重建与符号解析	严重	tree-
3	布局算法（Flex／自由形态推断）	严重	layout-
4	坐标与几何运算	高	geom-
5	视觉回归与差异算法	高	diff-
6	样式转换（颜色、渐变、阴影、边框）	中高	style-
7	排版运算	中	type-
8	路径与形状渲染	中	path-

快速参考

1. 逆向工程迭代策略（严重）

• iter-bisect-from-root — 从上到下转换，再从下到上二分，以 O(log n) 定位回归
• iter-baseline-snapshot-gate — 每项更改都必须通过已提交的基线检查，才能合并
• iter-convert-symbols-before-instances — 对符号 → 实例进行拓扑排序；绝不要内联重复项
• iter-freeze-design-tokens-first — 在转换任何组件之前，将 sharedSwatches/layerStyles 提取为 CSS 变量
• iter-one-family-per-pr — 每次迭代只转换一个组件系列
• iter-keep-known-good-branch — 保留一个基线分支，作为三方回归排查的锚点

2. 树重建与符号解析（关键）

• tree-resolve-overrides-before-emit — 将 overrideValues 应用于主对象，生成具名属性
• tree-hash-subtrees-for-componentization — 通过结构哈希发现设计师遗漏的重复内容
• tree-collapse-passthrough-groups — 移除无样式的单子节点组；保留世界坐标
• tree-hoist-shared-style-via-subtree-equivalence — 使用子树等价性和修饰符类，而非逐属性去重
• tree-clipping-mask-is-stacking-context — hasClippingMask 要求使用 isolation: isolate 和 clip-path
• tree-foreign-symbols-become-library-imports — 外部符号应作为包导入，而非重复项

3. 布局算法（关键）

• layout-flex-group-enum-mapping — 将 MSImmutableFlexGroupLayout 枚举一一映射到 CSS flex 属性
• layout-infer-flex-from-axis-projection-overlap — 使用一维分离轴测试，将自由布局转换为 flex 行或列
• layout-detect-grid-via-2d-coordinate-clustering — 使用 ε 对边缘坐标聚类，以检测 CSS Grid
• layout-promote-freeform-when-equal-gaps — 容差范围内间距相等时，使用 display: flex; gap: Npx
• layout-reverse-engineer-padding-not-margin — 将内边距转换为父级 padding；重新定位子项
• layout-preserve-wrapping-enabled — wrappingEnabled 是源文件表示响应式意图的唯一方式
• layout-ignore-layout-is-absolute-escape — flexItem.ignoreLayout: true → 相对于 position: relative 父级使用 position: absolute

4. 坐标与几何运算（高优先级）

• geom-compose-parent-transforms-before-emit — 合成 2D 仿射矩阵，不要直接拼接原始 x/y
• geom-round-only-at-leaves — 保留浮点数；仅在 CSS 边界处舍入一次
• geom-rotation-is-css-transform — Frame 是未旋转的 AABB；输出 transform: rotate()
• geom-shape-group-bounds-via-union — 边界 = 子项的轴对齐并集，并重新定位到原点
• geom-clipping-bounds-intersect-not-union — 嵌套裁剪区域取交集；绝不取并集或替换

5. 视觉回归与差异算法（高）

• diff-use-ssim-for-aa-content — 对抗锯齿内容使用 SSIM；原始像素差异在每次重新测试时都会产生误报
• diff-region-budgeted-tolerances — 按区域设定 SSIM 下限（文本 0.99、渐变 0.95、图像 1.0）
• diff-antialias-aware-pixelmatch-threshold — 使用 Pixelmatch includeAA: false 检测图标缺陷
• diff-perceptual-hash-for-wrong-component-detection — 汉明距离分桶，自动分派问题排查
• diff-subtree-bisection-to-localize-regression — 通过二分搜索禁用子树，找到引发问题的节点
• diff-baseline-per-component-not-per-page — 使用 Storybook 按 story 保存快照；范围即影响范围

6. 样式转换（中高）

• style-srgb-float-to-hex-via-gamma-correct-path — Sketch 的 sRGB 浮点值已进行伽马编码；只需直接转换
• style-preserve-display-p3 — colorSpace: 1 → 输出 color(display-p3 …)，并提供 sRGB 回退
• style-gradient-angle-via-atan2 — atan2(dx, -dy) 将 Sketch 向量转换为 CSS 渐变角度
• style-stack-multi-shadow-in-paint-order — 反转阴影数组——Sketch 按从后到前绘制，CSS 按从前到后绘制
• style-reconcile-border-position — 边框位置 0/1/2 → 扩展框架，或在外侧使用 outline
• style-per-corner-radii-shorthand — 各角半径按顺时针映射到 TL TR BR BL（而非 Sketch 的行顺序）

7. 字体排版计算（中）

• type-split-attributed-string-runs-only-when-differ — 合并相邻且属性相同的文本片段；单片段时无需内部 span
• type-pt-lineheight-to-unitless — lineHeight / fontSize → 可随字体缩放的 CSS 无单位值
• type-kerning-pt-to-em-letter-spacing — kerning / fontSize → 相对于 em 的 letter-spacing
• type-build-font-fallback-ladder — 将 Sketch 字体系列转换为 Web 字体栈；SF Pro 需要 -apple-system, BlinkMacSystemFont, …
• type-paragraph-spacing-between-not-after — 在父元素上使用 gap，而非配合 :last-child 使用 margin-bottom

8. 路径与形状渲染（中）

• path-curve-point-to-svg-cubic-bezier — 使用 curveFrom/curveTo 生成 M 和各线段的 C
• path-rectangle-with-fixed-radius-is-css — 尽早检测轴对齐的圆角矩形；输出 <div> 而非 <svg>
• path-apple-smooth-corners-via-superellipse — Apple 平滑圆角是超椭圆（n≈5），而非圆弧
• path-flatten-boolean-ops-at-parse-time — 在 Node 中通过 paper.js 解析并集/减集；输出一条扁平路径
• path-honor-winding-rule — windingRule 0/1 → SVG fill-rule nonzero/evenodd；显式指定，不依赖默认值

使用方法

1. 阅读 references/_sections.md，了解类别定义和级联原理
2. 从迭代策略（iter-*）开始——没有回归门禁，其他所有规则都只是技巧
3. 接着看树（tree-*）和布局（layout-*）——这些是承重的结构决策
4. 然后看几何（geom-*）和差异（diff-*）——这些是精度和验证层
5. 样式、类型和路径属于润色层——保真度高，但影响大多局限于局部

对于全新的转换器，请按优先级顺序遵循这些规则。对于现有转换器，请确定出现的回归由哪个阶段负责（使用 [[diff-subtree-bisection-to-localize-regression]] + [[diff-perceptual-hash-for-wrong-component-detection]] 进行排查），并在负责该问题的最高阶段修复。

参考文件

文件	说明
references/_sections.md	类别定义、影响级别、级联原理
assets/templates/_template.md	用于向此技能添加新规则的模板
metadata.json	版本、领域、参考资料
AGENTS.md	自动生成的目录（通过 scripts/build-agents-md.js 重新生成）