Figma Guidance

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

Content

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

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.

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.

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.

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).

Design-driven implementation should change visual presentation, layout, and copy without silently changing existing product behavior.

Before replacing or simplifying existing UI logic, inspect what the current code does for special cases such as:
- plan eligibility and visibility
- pricing, discounts, trial prices, and free-trial vs paid-trial behavior
- validation and submit blocking
- API request/response contracts
- routing/query params/back links
- analytics/tracking events
- permissions, current-plan state, and upgrade/downgrade rules
If Figma only shows one visual state, treat it as a visual example, not proof that other existing states should be removed.
Preserve existing conditional branches unless the behavior change is explicitly present in the user request, product spec, Figma annotation, or accepted implementation plan.
When a design appears to conflict with existing logic, stop and call out the conflict. Ask whether to preserve behavior with the new styling or intentionally change the behavior.
When removing a visible option or state for design reasons, verify whether hidden data paths still need to behave correctly. For example, hiding a plan from selection must not remove unrelated pricing, trial, billing, or checkout behavior.
Tests for design-driven changes should include at least one existing non-happy-path behavior when the edited component already had meaningful branches, such as one-dollar trials vs free trials, current-plan exceptions, validation errors, or hidden-but-supported plan states.

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.

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.