# Blocks — Figma Code Connect Guide

Canonical reference for **authoring and maintaining Figma Code Connect templates**
(colocated mapping files) for `@chainlink/blocks` components.

This guide covers how to read component source and write accurate mappings. It
does **not** cover implementing product pages or app routes—use
`skills/blocks-ui-builder/SKILL.md` and `libs/blocks/AGENTS.md` for that.

This is the package-facing runtime guide for Code Connect work in this package.

For runtime routing and source precedence, start with `AGENTS.md`.

The maintainer skill at `skills/blocks-figma-connect/SKILL.md` is **workflow only**. If anything in that skill (or in chat) disagrees with this guide, **this file wins**.

---

## Role of Code Connect

Use Code Connect mappings to:

- identify the likely Blocks component for a Figma node
- expose a rough composition skeleton
- map Figma component properties to public Blocks props
- reduce search time across the component library

Do not treat generated snippets as final API truth. They can lag behind
component source, omit required state handling, or pick a nearby abstraction that
needs refinement.

## What to read before editing a mapping

Inspect, for the component you are mapping:

1. **`.tsx`** — exported props, subcomponents, constants, and JSDoc
2. **`.stories.tsx`** — canonical, copyable compositions
3. **`.mdx`** — `## When to use`, anatomy, and related alternatives (so the
   template points at the right abstraction, not a lookalike)

When sources disagree on facts, follow the ordering in `AGENTS.md`. The mapping
must match **`.tsx`** for prop and export names.

## Mapping conventions

Templates should:

- import public components from `@chainlink/blocks`
- map only to public props and public subcomponents
- keep the rendered JSX close to the smallest useful Blocks composition
- preserve meaningful Figma text, state, and variant props
- avoid product-specific data, routing, analytics, or app state
- avoid private package paths and local implementation imports

Prefer a mapping that teaches the right abstraction over one that recreates every
pixel of a single Figma instance.

## Component families

For composed components, include the public family members that consumers need.

Examples:

- `Select`, `SelectTrigger`, `SelectContent`, `SelectItem`, `SelectValue`
- `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`,
  `DropdownMenuItem`
- `Modal`, `ModalHeader`, `ModalTitle`, `ModalDescription`, `ModalFooter`

Confirm the exact exported names in the component source before writing the
template.

## Checklist before shipping a mapping

- public imports come from `@chainlink/blocks`
- prop names match component source
- composed components include required subcomponents
- finite variant values match exported constants or source types
- templates stay small and reusable
- generated snippets have been checked against stories and source