paper-to-code-components

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 or an installed icon set before hand-rolling new ones.

Bad: BrandIcon({ name }) with a switch (name) returning ten different <svg> blocks.

Good: Kimi, OpenAI, Anthropic, Gemini, and MiniMax as separate components, each its own SVG, with a shared LogoFrame wrapping whichever mark is passed in.

4. Define Boundaries and Props

For each component candidate, define before or while coding:

1. Component name based on the reusable structural UI role, not the content of the first place it appears or Paper layer names. A title-plus-description list is LabeledList or DefinitionList, not FailureList; a content-specific name hides the component from the next section that needs it
2. Responsibility in one sentence
3. Props for changing text, icons, media, hrefs, state, and visual variants
4. children or named slots for flexible content areas
5. The root element that keeps relevant data-paper-* attributes
6. File placement by kind — which folder the component lives in. Group by responsibility instead of one flat dump: data-visualization/chart components in a dedicated folder (e.g. components/charts/), layout/chrome (nav, header, footer) together, typography/prose primitives together, and decoration (watermarks, background figures) separate. Icons go in the project's icon location (§3). A flat folder where a Leaderboard chart sits beside a Watermark and a Para buries the substantive data components and blurs which files are figures versus chrome. Within each group, use flat kebab-case files imported directly (shadcn style) — not folder-per-component with index.ts barrels, which trip React Doctor's no-barrel-import (§9).

Keep one-off decorative leaf elements inside the nearest semantic component. Extract repeated decoration into a small component only when the treatment repeats.

5. Implementation Rules

• Preserve Paper visual fidelity: spacing, typography, color, radius, shadows, image crops, and responsive behavior must still match the design.
• Keep Viewfinder/Paper data-paper-* attributes on useful rendered roots. If splitting exported JSX, move the relevant attributes to the new component's root.
• Use the project's existing styling system: Tailwind where nearby code uses Tailwind, CSS modules where nearby code uses CSS modules, and existing tokens when present.
• Prefer React Server Components in Next.js. Add "use client" only for state, browser APIs, event handlers that need client behavior, or client-only animation libraries.
• Do not add hooks for static presentational variants. Use props, classes, CSS variables, or data attributes.
• Reuse existing app components, icons, assets, and helpers before creating new local versions.
• Reuse the components you extracted earlier in the same pass. A structure that recurs across sections gets one component rendered with different props, not a near-copy per section.

6. Standardize Arbitrary Values

When Paper-exported JSX contains arbitrary values, preserve the rendered pixels and move the values into named project tokens in globals.css before completion.

Tokenize arbitrary values for:

1. Typography: text-[21px]/9.5, tracking-[-0.02em], font families, font weights
2. Colors: text-[color(display-p3_...)], arbitrary backgrounds, borders, gradients
3. Shape and depth: rounded-[13px], custom shadows, outlines, rings
4. Layout and spacing: arbitrary widths, heights, gaps, padding, margins, transforms

Use the local Tailwind/CSS pattern already present in globals.css, such as @theme, CSS variables, or project token aliases. Replace opaque inline arbitrary classes with named utilities backed by those tokens. Do not change the visual value while naming it.

For sizing and spacing, first reach for Tailwind v4's built-in spacing scale, not an arbitrary bracket. Utilities like w-, h-, max-w-, min-w-, p-, m-, gap-, inset-, top-/left- take a bare number where <n> = n × 0.25rem (4px at the default scale), so a pixel value that lands on the scale must use the scale utility: max-w-[1160px] → max-w-290, gap-[24px] → gap-6, h-[96px] → h-24. A linter will flag max-w-[1160px] precisely because max-w-290 already exists. Keep [...] brackets only for values that do NOT land on the scale (e.g. w-[17.18px] or a one-off max-w-[680px] that you would otherwise tokenize).

Bad:

Content truncated.