dot-skills Design-to-React Conversion Best Practices

The reverse-engineering pipeline that converts Sketch files into pixel-perfect React + CSS, with regression-safe iteration as the load-bearing constraint. The skill is organized around the cascade effect of design-to-code conversion: a wrong call in stage N corrupts every output from stage N+1 onward, so categories are ordered by how much downstream they own.

The user's primary requirement — "each improvement doesn't cause regressions" — is enforceable only if the iteration loop, the layer tree, and the layout solver are correct before you start polishing styles. Read the rules in priority order.

When to Apply

• Building a converter that ingests a .sketch file (or equivalent design source) and emits React + CSS
• Iterating on an existing converter where each improvement risks breaking other components
• Diagnosing why a converted component "almost matches" the design but visual-regression fails
• Designing the snapshot-gate / baseline strategy for a design-to-code pipeline
• Choosing between flexbox vs grid vs absolute positioning when the source is freeform geometry
• Translating Sketch-specific primitives (MSImmutableFlexGroupLayout, attributedString, curvePoint, MSImmutableStyleCorners) into idiomatic CSS

Rule Categories by Priority

The ordering is the cascade — fix earlier stages first; later-stage fixes are wasted if the upstream tree is wrong.

Quick Reference

1. Reverse-Engineering Iteration Strategy (CRITICAL)

• iter-bisect-from-root — Convert top-down, bisect bottom-up to localize regressions in O(log n)
• iter-baseline-snapshot-gate — Every change must pass committed baselines before merge
• iter-convert-symbols-before-instances — Topologically sort symbols → instances; never inline duplicates
• iter-freeze-design-tokens-first — Extract sharedSwatches/layerStyles to CSS variables BEFORE any component
• iter-one-family-per-pr — Scope conversions to one component family per iteration
• iter-keep-known-good-branch — Maintain a baseline branch as a three-way regression triage anchor

2. Tree Reconstruction & Symbol Resolution (CRITICAL)

• tree-resolve-overrides-before-emit — Apply overrideValues against master into named props
• tree-hash-subtrees-for-componentization — Structural hashing finds repetition designers missed
• tree-collapse-passthrough-groups — Drop no-style single-child groups; preserve world coords
• tree-hoist-shared-style-via-subtree-equivalence — Subtree equivalence + modifier classes, not per-property dedup
• tree-clipping-mask-is-stacking-context — hasClippingMask requires isolation: isolate + clip-path
• tree-foreign-symbols-become-library-imports — Foreign symbols are package imports, not duplicates

3. Layout Algorithms (CRITICAL)

• layout-flex-group-enum-mapping — Map MSImmutableFlexGroupLayout enums 1:1 to CSS flex properties
• layout-infer-flex-from-axis-projection-overlap — 1D separating-axis test for freeform → flex row/column
• layout-detect-grid-via-2d-coordinate-clustering — Cluster edge coordinates with ε to detect CSS Grid
• layout-promote-freeform-when-equal-gaps — Equal gaps within tolerance → display: flex; gap: Npx
• layout-reverse-engineer-padding-not-margin — Insets become parent padding; rebase children
• layout-preserve-wrapping-enabled — wrappingEnabled is the only way the source signals responsive intent
• layout-ignore-layout-is-absolute-escape — flexItem.ignoreLayout: true → position: absolute over position: relative parent

4. Coordinate & Geometry Math (HIGH)

• geom-compose-parent-transforms-before-emit — Compose 2D affine matrices, don't concatenate raw x/y
• geom-round-only-at-leaves — Carry floats through; round once at the CSS boundary
• geom-rotation-is-css-transform — Frame is unrotated AABB; emit transform: rotate()
• geom-shape-group-bounds-via-union — Bounds = axis-aligned union of children, rebase to origin
• geom-clipping-bounds-intersect-not-union — Nested clips intersect; never union or replace

5. Visual Regression & Diff Algorithms (HIGH)

• diff-use-ssim-for-aa-content — SSIM for antialiased content; raw pixel diff false-positives on every retest
• diff-region-budgeted-tolerances — Per-region SSIM floors (text 0.99, gradient 0.95, image 1.0)
• diff-antialias-aware-pixelmatch-threshold — Pixelmatch includeAA: false for icon defect detection
• diff-perceptual-hash-for-wrong-component-detection — Hamming distance buckets route triage automatically
• diff-subtree-bisection-to-localize-regression — Disable subtrees in binary search to find the offending node
• diff-baseline-per-component-not-per-page — Storybook per-story snapshots; scope = blast radius

6. Style Translation (MEDIUM-HIGH)

• style-srgb-float-to-hex-via-gamma-correct-path — Sketch sRGB floats are already gamma-encoded; direct conversion only
• style-preserve-display-p3 — colorSpace: 1 → emit color(display-p3 …) with sRGB fallback
• style-gradient-angle-via-atan2 — atan2(dx, -dy) reframes Sketch vector to CSS gradient angle
• style-stack-multi-shadow-in-paint-order — Reverse shadow array — Sketch paints last-first, CSS first-last
• style-reconcile-border-position — Border position 0/1/2 → frame expansion or outline for outside
• style-per-corner-radii-shorthand — Per-corner radii map to TL TR BR BL clockwise (not Sketch's row order)

7. Typography Math (MEDIUM)

• type-split-attributed-string-runs-only-when-differ — Coalesce identical adjacent attribute runs; single-run case needs no inner span
• type-pt-lineheight-to-unitless — lineHeight / fontSize → CSS unitless that scales with the font
• type-kerning-pt-to-em-letter-spacing — kerning / fontSize → em-relative letter-spacing
• type-build-font-fallback-ladder — Sketch family → web stack; SF Pro needs -apple-system, BlinkMacSystemFont, …
• type-paragraph-spacing-between-not-after — Use gap on the parent, not margin-bottom with :last-child

8. Path & Shape Rendering (MEDIUM)

• path-curve-point-to-svg-cubic-bezier — M + per-segment C from curveFrom/curveTo
• path-rectangle-with-fixed-radius-is-css — Detect axis-aligned rounded rects early; emit <div> not <svg>
• path-apple-smooth-corners-via-superellipse — Apple smooth corners are superellipses (n≈5), not circular arcs
• path-flatten-boolean-ops-at-parse-time — Resolve union/subtract via paper.js in Node; ship one flat path
• path-honor-winding-rule — windingRule 0/1 → SVG fill-rule nonzero/evenodd; explicit, not default

How to Use

1. Read references/_sections.md for category definitions and the cascade rationale
2. Start with the iteration strategy (iter-*) — without the regression gate, every other rule is just techniques
3. Then tree (tree-*) and layout (layout-*) — these are the load-bearing structural decisions
4. Then geometry (geom-*) and diff (diff-*) — these are the precision and validation layers
5. Style, type, and path are the polish layer — high fidelity but mostly local impact

For a brand-new converter, follow the rules in priority order. For an existing converter, identify which stage owns the regression you're seeing (use [[diff-subtree-bisection-to-localize-regression]] + [[diff-perceptual-hash-for-wrong-component-detection]] to triage) and fix at the highest stage that owns it.

Reference Files