Understanding Your JSONC Design Brief

After HandoffPro analyzes your UI screenshot, you get a JSONC design brief—a structured, machine-readable specification of your design. But what exactly is JSONC, why does HandoffPro use it, and how do you actually use it to generate code? Understanding your design brief is a key step in the design handoff process.

This guide walks through the anatomy of a HandoffPro brief, explains each section in detail, and shows you how to integrate it into your AI coding workflow with Cursor, Claude Code, and other assistants.

What is JSONC and Why HandoffPro Uses It

JSONC stands for JSON with Comments. It's a superset of JSON that allows inline comments (using // syntax), making it both human-readable and machine-readable.

Here's why HandoffPro uses JSONC instead of plain JSON:

1. Comments provide context – The AI can explain why it made certain decisions (e.g., "Extracted from button hover state" or "Estimated based on visual spacing").

2. Human-friendly – Developers can read the brief and understand the design system without needing to parse raw JSON.

3. AI-friendly – AI coding assistants like Cursor and Claude Code can parse JSONC natively and use it to generate code.

Unlike plain text descriptions (which are ambiguous) or raw JSON (which lacks context), JSONC gives you the best of both worlds.

Anatomy of a HandoffPro Brief

A HandoffPro JSONC brief is divided into several sections. Let's walk through each one.

1. Metadata Section

The metadata section provides high-level information about the component:

{
  "metadata": {
    "componentName": "PricingCard",
    "description": "A pricing tier card with plan name, price, feature list, and CTA button",
    "viewport": "desktop",
    "analysisDate": "2026-02-10"
  }
}

Key fields:

• componentName – A semantic name generated by the AI based on the design
• description – A plain-English summary of what the component does
• viewport – The assumed screen size (desktop, tablet, mobile)

This section helps you (and the AI) understand what you're building before diving into the details.

2. Color Tokens Section

The colorTokens section contains the color palette extracted from your screenshot:

{
  "colorTokens": {
    "primary": "#3b82f6", // Primary brand color (used for CTA button)
    "primaryHover": "#2563eb", // Hover state for primary button
    "background": "#ffffff", // Card background
    "backgroundAlt": "#f8fafc", // Subtle background for feature list
    "textPrimary": "#0f172a", // Heading and body text
    "textSecondary": "#64748b", // Muted text (price subheading)
    "border": "#e2e8f0", // Card border
    "accent": "#10b981" // Success/checkmark color
  }
}

Why this matters:

• Consistency – Instead of hardcoding hex values throughout your code, you can define these tokens as CSS variables or a Tailwind config. These follow the design tokens standard used across the industry.
• Theming – If you capture both light and dark mode screenshots, HandoffPro will generate separate color tokens for each theme.

Pro tip: If you're using Tailwind CSS, you can map these tokens directly to your tailwind.config.js. The JSONC format is closely related to the W3C Design Tokens JSON format, making it compatible with modern design systems.

export default {
  theme: {
    extend: {
      colors: {
        primary: "#3b82f6",
        primaryHover: "#2563eb",
        // ... rest of tokens
      }
    }
  }
}

3. Typography Section

The typography section defines font styles used throughout the design:

{
  "typography": {
    "headingLarge": {
      "fontSize": "32px",
      "fontWeight": 700,
      "lineHeight": "40px",
      "fontFamily": "Inter, sans-serif"
    },
    "headingMedium": {
      "fontSize": "24px",
      "fontWeight": 600,
      "lineHeight": "32px",
      "fontFamily": "Inter, sans-serif"
    },
    "bodyMedium": {
      "fontSize": "16px",
      "fontWeight": 400,
      "lineHeight": "24px",
      "fontFamily": "Inter, sans-serif"
    },
    "bodySmall": {
      "fontSize": "14px",
      "fontWeight": 400,
      "lineHeight": "20px",
      "fontFamily": "Inter, sans-serif"
    }
  }
}

Key fields:

• fontSize – Exact pixel size (AI measures this from your screenshot)
• fontWeight – Numeric weight (400 = regular, 600 = semibold, 700 = bold)
• lineHeight – Vertical spacing between lines of text
• fontFamily – Detected font (or a fallback if the AI can't identify it)

Using with Tailwind: You can map these to custom text utilities:

// tailwind.config.js
export default {
  theme: {
    extend: {
      fontSize: {
        'heading-lg': ['32px', { lineHeight: '40px', fontWeight: '700' }],
        'heading-md': ['24px', { lineHeight: '32px', fontWeight: '600' }],
        'body-md': ['16px', { lineHeight: '24px', fontWeight: '400' }],
      }
    }
  }
}

Then in your components:

<h1 className="text-heading-lg">Plan Name</h1>
<p className="text-body-md">Feature description</p>

4. Spacing Section

The spacing section captures padding, margins, and gaps:

{
  "spacing": {
    "cardPadding": "32px", // Inner padding of the card
    "sectionGap": "24px", // Gap between heading and feature list
    "featureGap": "16px", // Gap between individual features
    "buttonMarginTop": "32px" // Space above CTA button
  }
}

This is critical for pixel-perfect implementation. Instead of eyeballing spacing values, you can copy these directly into your CSS or Tailwind classes.

5. Components Section

The components section breaks down individual UI elements:

{
  "components": [
    {
      "type": "button",
      "variant": "primary",
      "properties": {
        "paddingX": "24px",
        "paddingY": "12px",
        "fontSize": "16px",
        "fontWeight": 600,
        "borderRadius": "8px",
        "backgroundColor": "#3b82f6",
        "textColor": "#ffffff"
      },
      "states": {
        "hover": {
          "backgroundColor": "#2563eb"
        },
        "active": {
          "backgroundColor": "#1d4ed8"
        }
      }
    },
    {
      "type": "list",
      "variant": "feature-list",
      "properties": {
        "gap": "16px",
        "iconSize": "20px",
        "iconColor": "#10b981"
      }
    }
  ]
}

This section gives you a component-by-component breakdown of the design. You can use it to:

• Build reusable components (e.g., a <Button variant="primary"> in React)
• Ensure consistent styling across your app
• Reference exact dimensions and colors for each element

A Complete Example

Here's what a full HandoffPro brief looks like for a pricing card:

{
  // Component metadata
  "metadata": {
    "componentName": "PricingCard",
    "description": "A pricing tier card with plan name, price, feature list, and CTA button",
    "viewport": "desktop"
  },
 
  // Extracted color palette
  "colorTokens": {
    "primary": "#3b82f6",
    "primaryHover": "#2563eb",
    "background": "#ffffff",
    "textPrimary": "#0f172a",
    "textSecondary": "#64748b",
    "border": "#e2e8f0",
    "accent": "#10b981"
  },
 
  // Typography specifications
  "typography": {
    "headingLarge": {
      "fontSize": "32px",
      "fontWeight": 700,
      "lineHeight": "40px"
    },
    "bodyMedium": {
      "fontSize": "16px",
      "fontWeight": 400,
      "lineHeight": "24px"
    }
  },
 
  // Spacing values
  "spacing": {
    "cardPadding": "32px",
    "sectionGap": "24px",
    "featureGap": "16px"
  },
 
  // Component breakdown
  "components": [
    {
      "type": "button",
      "variant": "primary",
      "properties": {
        "paddingX": "24px",
        "paddingY": "12px",
        "fontSize": "16px",
        "fontWeight": 600,
        "borderRadius": "8px",
        "backgroundColor": "#3b82f6",
        "textColor": "#ffffff"
      }
    }
  ]
}

This brief gives you everything you need to implement the pricing card pixel-perfect.

Using with Cursor

Cursor has built-in support for reading and understanding structured design specs. Here's how to use your HandoffPro brief:

1. Copy the JSONC brief from HandoffPro (use the copy button).

2. Open Cursor's chat panel (Cmd+L on macOS).

3. Paste the brief and add a prompt like:

   "Implement this component using React and Tailwind CSS. Follow the exact color tokens and spacing defined in the brief. Use the component structure defined in the 'components' section."

4. Add context about your project (optional but recommended):

   "My project uses Next.js 15 with the App Router, TypeScript, and shadcn/ui components. Use Lucide icons for any icons needed."

Cursor will generate code that matches the design spec. If you've also included the implementation prompt that HandoffPro generates (the Markdown file), paste that as well for even better results.

Using with Claude Code

Claude Code (Anthropic's AI assistant in VS Code) works similarly:

1. Save the JSONC brief to your project directory (e.g., design-briefs/pricing-card.jsonc).

2. Reference it in your chat with Claude Code:

   "@design-briefs/pricing-card.jsonc Implement this component as a React functional component with TypeScript. Use Tailwind CSS for styling and follow the exact tokens defined in the brief."

3. Claude Code will read the file and generate code based on the spec.

The advantage of saving the brief as a file is that you can reference it across multiple sessions and keep it version-controlled in your repo.

The Implementation Prompt

HandoffPro also generates a second output: an implementation prompt in Markdown format. This prompt provides:

• High-level context about the component (what it does, where it's used)
• Key interaction patterns (e.g., "Button should have hover and focus states")
• Accessibility considerations (e.g., "Use aria-label for icon-only buttons")
• Suggested tech stack (React, Vue, Tailwind, etc.)

Best practice: Paste both the JSONC brief AND the implementation prompt into your AI assistant. The brief provides the structure, and the prompt provides the context. Together, they give the AI everything it needs to generate production-ready code.

Tips for Best Results

Here are a few tips to get the most out of your HandoffPro briefs:

1. Reference your existing design system – If you already have a design system (e.g., Tailwind config, CSS variables), tell the AI to use it instead of hardcoding values.

   "Use the color tokens from the brief, but map them to my existing Tailwind theme instead of hardcoding hex values."

2. Provide component structure – If you have a component library (e.g., shadcn/ui, Radix UI), tell the AI to use those components as building blocks.

   "Use shadcn/ui's Button component for the CTA, and apply the styling from the brief as overrides."

3. Iterate with multiple screenshots – If your first brief isn't perfect, upload additional screenshots (e.g., different states, zoom levels, or related screens) to refine the output.

4. Keep briefs in version control – Save your JSONC briefs to a design-briefs/ folder in your repo. This creates a living design system that evolves with your codebase.

Conclusion: JSONC Bridges the Gap

HandoffPro's JSONC brief is more than just a list of colors and font sizes—it's a structured contract between design and code. It removes ambiguity, ensures pixel-perfect implementation, and makes it trivial to work with AI coding assistants.

Instead of describing your design in vague terms ("make it look modern"), you can hand the AI a precise, machine-readable spec and get back production-ready code.

Ready to generate your first brief? Upload a screenshot to HandoffPro and see how structured design specs transform your workflow.