/paper-to-code-components

name: paper-to-code-components
description: Use when implementing Paper MCP, Paper-to-code, design-to-code, Viewfinder, or Paper-exported JSX in React/Next.js apps. Covers component candidates, choosing the canonical artboard among iterations, data-driven charts/visualizations, globals.css tokens for arbitrary values, shadcn reuse, data-paper-* roots, and avoiding monolithic JSX.

Paper-to-Code Componentization

You turn Paper designs into React/Next code with component boundaries identified before JSX grows.

Hard rule: before writing implementation JSX for a Paper design, map the design hierarchy and component candidates. Pixel fidelity and componentization are both required.

RED/GREEN Intent

This skill prevents these Paper-to-code failures:

• Dumping a whole artboard into one giant route or component
• Spotting repeated cards, rows, or controls only after the file is huge
• Collapsing distinct icons or logos into one `name`-switched mega-component
• Rebuilding a list, row, or card in a new section instead of reusing a component already extracted for it
• Removing Viewfinder `data-paper-*` attributes from useful roots
• Adding client hooks only to manage static visual variants
• Building from whichever artboard is easiest to convert instead of the one the stakeholder treats as canonical — multi-iteration files routinely include simplified handoff/cleanup frames
• Flattening a chart into pixels: dropping error bars, whiskers, ranges, or stacked segments and modelling one value where the design encodes several
• Re-deriving a chart from a screenshot or from className literals when transforms make those literals wrong
• Dumping every component into one flat folder so data charts sit intermixed with prose, chrome, and decoration

GREEN outcome: repeated visual groups are extracted once, components are grouped by kind (data visualizations in their own folder, not intermixed with chrome and prose), page files read as composition, charts carry every data dimension the design encodes, and the build still matches Paper — reconciled against the artboard the stakeholder considers canonical, not whichever one it was built from.

1. Extract the Design Hierarchy First

Before coding, inspect the Paper selection/tree/screenshot and identify:

1. Page shell and semantic regions 2. Navigation, hero, content sections, sidebars, overlays, and footers 3. Repeated cards, rows, messages, list items, badges, pills, and controls 4. Icon button variants, CTA variants, input variants, and menu items 5. Reusable asset treatments: avatars, logo lockups, screenshot frames, masks, shadows, and image crops

Scan the entire design, not one section at a time. The same row, list, or card pattern often reappears in sections far apart on the canvas, styled to look section-specific. A title-and-description list under one heading and the same list under another heading are one component. Catalog each recurring structure once, noting every section it appears in.

**Pick the canonical frame first.** A Paper file often holds many parallel iterations of the same screen, plus handoff/cleanup frames — and they are not interchangeable. The most code-ready artboard (clean, named flex cells) is frequently a *simplified* handoff frame where fiddly detail was dropped (chart error bars, extra states, decorations), while the visually richest version is an absolute-positioned exploration. Do not default to whichever is easiest to convert. Confirm which frame is canonical from the user's current selection or by asking; when frames disagree on what a component shows or how much data it carries, build the richer encoding and flag the discrepancy instead of silently shipping the simpler one.

Write a short hierarchy note in your working context before implementation. Do not skip this because the export looks straightforward.

2. Choose Component Candidates

Create a named component when any of these are true:

1. A visual group appears two or more times, including near-duplicates 2. A semantic region has a reusable role, such as `PricingCard`, `MessageRow`, or `FeatureSection` 3. A control has variants, such as `IconButton`, `Pill`, `Badge`, or `CTAButton` 4. A repeated card, row, message, or list item changes only text, icon, media, color, or state 5. An asset treatment repeats, such as an avatar frame, logo mark, image mask, or screenshot shell

Near-duplicates use variant props or slots. Do not copy and tweak the same JSX block.

Before building each section, check the candidates you already cataloged for a structural match and reuse it. Do not create a second component for a pattern you already have just because it sits in a different section or holds different text.

3. One Component Per Icon

Icons and logos that differ in their actual artwork are distinct components, not variants of a shared one.

1. Give every visually distinct icon or logo its own named component, named for what it depicts: `<Kimi />`, `<OpenAI />`, `<Anthropic />`, `<Gemini />`, `<MiniMax />`. 2. Never bundle distinct icons behind one component that switches on a `name`, `type`, or `variant` prop, or an internal map or `switch`. No `BrandIcon name="kimi"`, no `<Icon type="openai" />`, no `icons[name]` lookup that inlines many `<svg>` bodies. 3. The near-duplicate-to-variant rule in Section 2 does NOT apply to icons. Different vector paths are different artwork, so they are different components. Variant props are for shared markup that differs by text, color, size, or state, never for swapping one `<svg>` body for another. 4. Shared chrome around an icon is the exception worth extracting. If every logo sits in the same dashed-circle frame, make one `LogoFrame` or `AvatarFrame` wrapper and pass the distinct icon component in as `children`. The frame is shared; the mark stays per-icon. 5. Put each icon in its own file under the project's icon location, match the exported SVG exactly (viewBox, paths, fills), and reuse existing icon components