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:
- Call
get_guide({ topic: "paper-mcp-instructions" }).
- Call
get_basic_info and get_selection to confirm target artboard/node scope.
- Call
get_screenshot on the target and keep it as the visual baseline.
- Call
get_tree_summary(depth=10) and get_children on the target.
- 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.
- 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
- Keep the original nodes until the converted layout has passed screenshot comparison.
- Use
<x-paper-clone node-id="..."> for SVGs, images, complex vectors, icons, masks, and styled shapes.
- Never hand-redraw an SVG, image, logo, or complex decorative layer. No exceptions for "simple enough."
- After cloning into flex flow, batch
update_styles to set left: "0px" and top: "0px" on every flow clone.
- 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
- Map the absolute children into semantic groups: background, header row, text stack, media, card, controls, overlays.
- Compute spacing from coordinates:
gap = next.top - (current.top + current.height)
leftPadding = first.left - container.left
topPadding = first.top - container.top
- Use Paper-compatible layout:
display: flex, flex-direction, align-items, justify-content, gap, and wrapper padding.
- Do not rely on margins. Use
gap, padding wrappers, or explicit spacer frames for non-uniform spacing.
- Build incrementally. Each
write_html call should add one visual group or wrapper.
- 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
- 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:
- Card stack wrapper is a plain fixed-size frame, not a flex container.
- Back card is the first child.
- Front card uses
position: absolute; left: 0px; top: 0px.
- 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:
- Verify the original screenshot and converted screenshot match.
- Verify no SVG, image, logo, mask, or complex shape was recreated instead of cloned.
- Verify every flow clone has
left: "0px" and top: "0px" via get_computed_styles.
- Verify every absolute overlay clone has its intended
position, left, and top via get_computed_styles.
- Verify decorative/background clones appear earlier than content with
get_children.
- Verify overlapping badges/labels are last children of their stack/wrapper.
- Verify hidden shadows are removed where flex restructuring would reveal them.
- Verify filters are on leaf nodes only.
- Call
finish_working_on_nodes when done.
Do not skip any step. A skipped step means visual corruption.
1---2name: paper-flex3description: Use when converting Paper canvas or design nodes from absolute positioning to flex or auto-layout. Covers Paper MCP absolute-to-flex restructuring, x-paper-clone preservation, clone z-order, computed spacing, shadow cleanup, SVG/image fidelity, layered cards, and screenshot verification.4---56# Paper Flex78You convert Paper layouts from absolute positioning into flex structure without losing the original pixels.910Hard rule: preserve existing visual nodes first. Recreate only plain layout wrappers or simple text/div surfaces whose computed styles are fully known.1112## RED/GREEN Intent1314This skill closes failures seen without Paper-specific guidance:1516- Using generic move/relative positioning instead of `x-paper-clone` plus `update_styles`17- Losing SVG path data, image fills, crops, or exact shadows by rebuilding nodes18- Breaking z-order because Paper appends `x-paper-clone` nodes after normal divs19- Leaving cloned absolute `left`/`top` offsets inside flex flow20- Letting shadows or filters become visible/inherited after restructuring2122GREEN outcome: the converted node has a readable flex hierarchy, original SVG/image fidelity, verified z-order, and a screenshot that still matches the source.2324## Required First Pass2526Before writing or deleting anything:27281. Call `get_guide({ topic: "paper-mcp-instructions" })`.292. Call `get_basic_info` and `get_selection` to confirm target artboard/node scope.303. Call `get_screenshot` on the target and keep it as the visual baseline.314. Call `get_tree_summary(depth=10)` and `get_children` on the target.325. 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.336. If text styling will be created or changed, call `get_font_family_info` before writing typography.3435Do not start conversion from memory or screenshot alone. The computed styles are the source of truth for flex math.3637## Source Preservation Rules38391. Keep the original nodes until the converted layout has passed screenshot comparison.402. Use `<x-paper-clone node-id="...">` for SVGs, images, complex vectors, icons, masks, and styled shapes.413. Never hand-redraw an SVG, image, logo, or complex decorative layer. No exceptions for "simple enough."424. After cloning into flex flow, batch `update_styles` to set `left: "0px"` and `top: "0px"` on every flow clone.435. 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.4445## Conversion Workflow46471. Map the absolute children into semantic groups: background, header row, text stack, media, card, controls, overlays.482. Compute spacing from coordinates:4950```text51gap = next.top - (current.top + current.height)52leftPadding = first.left - container.left53topPadding = first.top - container.top54```55563. Use Paper-compatible layout: `display: flex`, `flex-direction`, `align-items`, `justify-content`, `gap`, and wrapper `padding`.574. Do not rely on margins. Use `gap`, padding wrappers, or explicit spacer frames for non-uniform spacing.585. Build incrementally. Each `write_html` call should add one visual group or wrapper.596. Use separate `write_html` calls whenever clone z-order matters:6061```text621. write_html container shell632. write_html decorative/background clones into shell643. write_html content wrappers/divs into shell654. update_styles cloned positions and flow offsets66```67687. Delete original children only after the converted children exist, positions are verified, and the screenshot matches. Verify the final child list with `get_children`.6970## Paper-Specific Traps7172| Trap | Why It Breaks | Correct Move |73|---|---|---|74| Setting position styles on `<x-paper-clone>` | Paper ignores clone position overrides at insertion time | Clone first, then call `update_styles` |75| Mixing clones and divs in one `write_html` | Paper appends clones after divs, changing z-order | Insert decorative clones in an earlier write |76| Leaving original clone coordinates | Absolute offsets push flow items away from their flex slots | Reset flow clones to `left: "0px"`, `top: "0px"` |77| Using `position: relative` for overlapped cards | Paper stacks instead of overlapping in fixed wrappers | Use absolute cards inside a fixed-size wrapper |78| 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 |79| Applying `filter` to a flex parent | Filters inherit and affect children unintentionally | Apply filters only to leaf nodes that need them |80| Cloning reference SVGs blindly | Some SVG clones contain empty text children | Inspect with `get_tree_summary`; delete empty Text children |8182## Layered Cards8384Open `references/layered-cards.md` when the design has back cards, floating badges, corner marks, or overlapping elements.8586Default card stack rules:87881. Card stack wrapper is a plain fixed-size frame, not a flex container.892. Back card is the first child.903. Front card uses `position: absolute; left: 0px; top: 0px`.914. Floating badges, labels, and corner marks are inside the stack wrapper as last children.9293## Good And Bad Patterns9495**Bad:** Delete an imported SVG, write a new `<svg>`, put it in a flex row, and eyeball the icon.9697**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.9899**Bad:** One `write_html` call containing a background clone and content divs.100101**Good:** Write the shell, insert background clones in a separate call, then insert content so Paper's clone ordering cannot place backgrounds on top.102103## Before Marking Complete, You MUST:1041051. Verify the original screenshot and converted screenshot match.1062. Verify no SVG, image, logo, mask, or complex shape was recreated instead of cloned.1073. Verify every flow clone has `left: "0px"` and `top: "0px"` via `get_computed_styles`.1084. Verify every absolute overlay clone has its intended `position`, `left`, and `top` via `get_computed_styles`.1095. Verify decorative/background clones appear earlier than content with `get_children`.1106. Verify overlapping badges/labels are last children of their stack/wrapper.1117. Verify hidden shadows are removed where flex restructuring would reveal them.1128. Verify filters are on leaf nodes only.1139. Call `finish_working_on_nodes` when done.114115Do not skip any step. A skipped step means visual corruption.
millionco