paper-flex

Paper Flex

You convert Paper layouts from absolute positioning into flex structure without losing the original pixels.

Hard rule: preserve existing visual nodes first. Recreate only plain layout wrappers or simple text/div surfaces whose computed styles are fully known.

RED/GREEN Intent

This skill closes failures seen without Paper-specific guidance:

• Using generic move/relative positioning instead of x-paper-clone plus update_styles
• Losing SVG path data, image fills, crops, or exact shadows by rebuilding nodes
• Breaking z-order because Paper appends x-paper-clone nodes after normal divs
• Leaving cloned absolute left/top offsets inside flex flow
• Letting shadows or filters become visible/inherited after restructuring

GREEN outcome: the converted node has a readable flex hierarchy, original SVG/image fidelity, verified z-order, and a screenshot that still matches the source.

Required First Pass

Before writing or deleting anything:

1. Call get_guide({ topic: "paper-mcp-instructions" }).

2. Call get_basic_info and get_selection to confirm target artboard/node scope.

3. Call get_screenshot on the target and keep it as the visual baseline.

4. Call get_tree_summary(depth=10) and get_children on the target.

5. Call get_computed_styles for the target and every direct visual child. Record left, top, width, height, colors, fonts, shadows, filters, radii, and image fills.

6. If text styling will be created or changed, call get_font_family_info before writing typography.

Do not start conversion from memory or screenshot alone. The computed styles are the source of truth for flex math.

Source Preservation Rules

1. Keep the original nodes until the converted layout has passed screenshot comparison.

2. Use <x-paper-clone node-id="..."> for SVGs, images, complex vectors, icons, masks, and styled shapes.

3. Never hand-redraw an SVG, image, logo, or complex decorative layer. No exceptions for "simple enough."

4. After cloning into flex flow, batch update_styles to set left: "0px" and top: "0px" on every flow clone.

5. After cloning anything that must remain overlaid, batch update_styles to set the required position, left, and top. Inline styles on <x-paper-clone> are not enough.

Conversion Workflow

1. Map the absolute children into semantic groups: background, header row, text stack, media, card, controls, overlays.

2. Compute spacing from coordinates:

gap = next.top - (current.top + current.height)
leftPadding = first.left - container.left
topPadding = first.top - container.top

3. Use Paper-compatible layout: display: flex, flex-direction, align-items, justify-content, gap, and wrapper padding.

4. Do not rely on margins. Use gap, padding wrappers, or explicit spacer frames for non-uniform spacing.

5. Build incrementally. Each write_html call should add one visual group or wrapper.

6. Use separate write_html calls whenever clone z-order matters:

1. write_html container shell
2. write_html decorative/background clones into shell
3. write_html content wrappers/divs into shell
4. update_styles cloned positions and flow offsets

7. Delete original children only after the converted children exist, positions are verified, and the screenshot matches. Verify the final child list with get_children.

Paper-Specific Traps

| Trap | Why It Breaks | Correct Move |

|---|---|---|

| Setting position styles on <x-paper-clone> | Paper ignores clone position overrides at insertion time | Clone first, then call update_styles |

| Mixing clones and divs in one write_html | Paper appends clones after divs, changing z-order | Insert decorative clones in an earlier write |

| Leaving original clone coordinates | Absolute offsets push flow items away from their flex slots | Reset flow clones to left: "0px", top: "0px" |

| Using position: relative for overlapped cards | Paper stacks instead of overlapping in fixed wrappers | Use absolute cards inside a fixed-size wrapper |

| Keeping hidden source shadows | Flex order can reveal shadows that were covered before | Remove boxShadow on clones whose shadow was hidden by a later opaque sibling |

| Applying filter to a flex parent | Filters inherit and affect children unintentionally | Apply filters only to leaf nodes that need them |

| Cloning reference SVGs blindly | Some SVG clones contain empty text children | Inspect with get_tree_summary; delete empty Text children |

Layered Cards

Open references/layered-cards.md when the design has back cards, floating badges, corner marks, or overlapping elements.

Default card stack rules:

1. Card stack wrapper is a plain fixed-size frame, not a flex container.

2. Back card is the first child.

3. Front card uses position: absolute; left: 0px; top: 0px.

4. Floating badges, labels, and corner marks are inside the stack wrapper as last children.

Good And Bad Patterns

Bad: Delete an imported SVG, write a new <svg>, put it in a flex row, and eyeball the icon.

Good: Clone the original SVG with x-paper-clone, place it in the flex row, reset its flow offsets with update_styles, then compare screenshots.

Bad: One write_html call containing a background clone and content divs.

Good: Write the shell, insert background clones in a separate call, then insert content so Paper's clone ordering cannot place backgrounds on top.

Before Marking Complete, You MUST:

1. Verify the original screenshot and converted screenshot match.

2. Verify no SVG, image, logo, mask, or complex shape was recreated instead of cloned.

3. Verify every flow clone has left: "0px" and top: "0px" via get_computed_styles.

4. Verify every absolute overlay clone has its intended position, left, and top via get_computed_styles.

5. Verify decorative/background clones appear earlier than content with get_children.

6. Verify overlapping badges/labels are last children of their stack/wrapper.

7. Verify hidden shadows are removed where flex restructuring would reveal them.

8. Verify filters are on leaf nodes only.

9. Call finish_working_on_nodes when done.

Do not skip any step. A skipped step means visual corruption.