Skip to main content

Figma Guidance

Source: .agents/references/coding-standard/figma-guidance.md

Content​

Figma Guidance

Use this guidance for any design-driven implementation from Figma links, node IDs, screenshots, or explicit Figma specs.

Tailwind config is the source of available styles​

Before mapping Figma values to class names, read the project's Tailwind setup so utilities and tokens actually exist:

  • Primary file: tailwind.config.js at the repo root defines theme (spacing, typography, colors, shadows, etc.) and pulls in extensions from tailwindConfigs/ (for example ./tailwindConfigs/colors).
  • Prefer classes that exist in config over inventing utilities. If Figma specifies a pixel value or token that has no matching key in extend.spacing, fontSize, colors, etc., use arbitrary values (for example p-[10px]) only when appropriate.
  • Colors and NPL utilities: Confirm the exact text-*, fill-*, bg-*, and semantic names exist under theme.extend / merged colors rather than guessing from Figma naming alone.
  • Typography: Confirm font size / line height combos (for example text-label-md) exist under theme.extend.fontSize (or equivalent) before using them.

MCP Requirement​

  • When the user provides a Figma URL (or explicitly references Figma design nodes), first use Figma MCP tools such as get_design_context, get_metadata, and get_screenshot.
  • Only proceed with visual/design-driven implementation when those tools are available and succeed.
  • If Figma MCP cannot be accessed or fails:
    • Do not guess or approximate from the URL alone.
    • Explicitly tell the user Figma MCP is unavailable/failed and that the design could not be read.
    • Ask for alternative context (screenshots, specs, textual details), or limit work to non-visual logic where design fidelity is not required.
  • Never claim to have seen/opened a Figma link unless it was actually fetched via Figma MCP tools.

Spacing, Padding, and Sizing​

  • Use exact spacing and padding values from Figma. Do not round to values that "look close."
  • Fetch design values via get_design_context (and get_screenshot) for relevant nodes.
  • Map Figma pixel values to this project's Tailwind spacing scale 1:1 (e.g. 8px -> 8, 12px -> 12, 16px -> 16, 24px -> 24).
  • Apply values directly in utilities:
    • 8px padding -> p-8 / px-8 / py-8
    • 12px padding -> p-12 / px-12 / py-12
    • 16px padding -> p-16 / px-16 / py-16
    • 8px horizontal + 12px vertical -> px-8 py-12
  • For gaps, use the same mapping (gap-8, gap-12, gap-16, etc.).
  • If a value is outside the spacing scale (e.g. 10px), use arbitrary values (p-[10px], gap-[10px]).
  • Use exact width/height from Figma for icons and fixed-size elements (e.g. 20x20 -> width={20} and height={20}), never rounded substitutes.

Layout and Copy Fidelity​

  • Do not omit copy/headings present in the design.
  • Use translation keys for user-facing strings where appropriate (for example t('hi-name', { name })).
  • Do not stretch buttons/cards with flex-1/w-full unless the design clearly shows full-width distribution.
  • Prefer content-sized or minimum-width controls where design indicates fixed/content sizing.
  • When icon/count/label stacks are centered in design, use centered layout/text classes (for example items-center, justify-center, text-center).

Color Mapping from Figma​

  • Follow Figma semantic hierarchy for text/fill roles:
    • Primary -> text-npl-text-primary-on-light / fill-npl-text-primary-on-light (or -on-dark on dark surfaces)
    • Secondary -> text-npl-text-secondary-on-light / fill-npl-text-secondary-on-light
    • Tertiary -> text-npl-text-tertiary-on-light / fill-npl-text-tertiary-on-light
  • Do not substitute hierarchy levels (for example, avoid using secondary where Figma specifies tertiary).
  • If active icon color differs from active text color, map from the exact Figma variable/token (get_variable_defs or get_design_context) to the matching NPL token; do not assume.

Typography Mapping​

  • Figma NPL typography tokens map directly to Tailwind typography classes.
  • Convention:
    • Figma: NPL [Type]/[size]/[weight]
    • Tailwind: text-[type]-[size] plus font-[weight] when needed
  • Examples:
    • NPL Label/md/medium -> text-label-md (+ font-medium when needed)
    • NPL Label/sm/regular -> text-label-sm
    • NPL Body/md/regular -> text-body-md
    • NPL Body/sm/regular -> text-body-sm
    • NPL Heading/md/semibold -> text-heading-md (+ font-semibold when needed)
  • Use exact tokens from the design system; do not guess.
  • Mapping conventions:
    • Label -> label, Body -> body, Heading -> heading, Para -> para
    • Sizes xs, sm, md, lg, xl map directly
  • If an existing Tailwind token matches the design system token, prefer it over custom styles.