Skip to main content

Implement Design-Identical UI

Use when implementing frontend UI from Figma links, screenshots, or design specs where visual fidelity, exact spacing, layout, typography, colors, responsive states, and iterative UX/UI QA are required.

Source: .agents/skills/implement-design-identical-ui/SKILL.md

Metadata​

  • name: implement-design-identical-ui

Content​

Implement Design-Identical UI

Use this skill to coordinate a two-role loop for UI work: a Frontend Engineer implements the design, then a UX/UI QA validates the result against the design source. Prefer real subagents only when the user explicitly asks for subagents or delegation; otherwise run the two roles as clearly separated passes in the same agent. Do not mark the work complete until UX/UI QA passes, required repo checks pass, and temporary QA artifacts are cleaned up.

Required Context​

Before dispatching subagents, load:

  • AGENTS.md
  • .agents/rules/*.mdc
  • .agents/skills/feature-context/SKILL.md
  • .agents/skills/figma-spacing/SKILL.md
  • .agents/skills/create-skeleton/SKILL.md
  • .agents/skills/code-review/SKILL.md
  • .agents/references/coding-standard/figma-guidance.md
  • Relevant .agents/references/features/*.md
  • Live source files for the target route/component

This skill assumes Figma MCP is available through http://127.0.0.1:3845/mcp. Figma-driven UI work requires a Figma MCP-readable URL/node ID, get_design_context, and get_screenshot from that local MCP endpoint. Do not proceed from screenshots, design specs, or a Figma URL alone when Figma MCP fails or no MCP-readable node is available; stop and ask for the exact Figma node or MCP access to be fixed.

Figma MCP Access Order​

Use the local Figma MCP endpoint as the source of truth. A hosted/plugin Figma connector reporting requires reauthentication is not sufficient reason to stop until the agent has tried the local endpoint path.

  1. Prefer callable Figma MCP tools that are configured against http://127.0.0.1:3845/mcp and fetch get_design_context plus get_screenshot.
  2. If a hosted connector/tool returns requires reauthentication, treat that as connector-specific. Try the local MCP endpoint next instead of asking the user to reauth immediately.
  3. If no local-MCP-backed tool is exposed, check endpoint liveness with rtk curl -s http://127.0.0.1:3845/mcp.
    • Invalid sessionId means the local MCP server is reachable; the blocker is missing MCP session/tool access, not Figma auth.
    • Connection refused, timeout, or no response means local Figma MCP is unavailable.
  4. Stop and ask the user only after the local endpoint path fails or no MCP-capable client/tool can create a session against it. Be specific: say whether the endpoint is unreachable, session/tool access is missing, or the Figma node itself is unreadable.

Repo Defaults for Faster QA​

  • Assume the app is already running on http://localhost:3000. Do not start a new dev server, probe other ports, or ask for server approval unless localhost:3000 is unreachable.
  • Portal/admin routes are auth-gated by default. For visual QA, create src/pages/localTestPage12345.page.js immediately instead of trying the real route first.
  • The temporary preview page must render only the changed component/state with minimal mock props/data. Do not wire real services, auth, router setup, or full portal flows into it.
  • Do not run Playwright/browser QA when the change does not affect a browser-rendered surface, or when the touched files are not part of the Playwright-covered/tested UI state. In those cases, record the skip reason and run focused static checks.
  • For small visual/data-default fixes where an existing component already renders the correct Figma state, code inspection plus focused lint is sufficient; screenshot QA is optional unless the component markup/classes changed.
  • When editing an existing component from Figma, compare and update the whole component structure, not only the symptom the user mentioned. Removed tabs, reordered sections, missing fields, changed headers/footers, and moved controls are in scope unless the user explicitly limits the task to one sub-element.

Hard Gate​

Do not implement until the master agent has:

  1. Collected a Figma MCP-readable URL/node ID and fetched Figma design context plus screenshot. Fallback screenshots/specs are not sufficient for this skill.
  2. Identified target route, component, files, and write scope.
  3. Read Tailwind config and relevant existing component/token usage.
  4. Searched for reusable NPL, shared, and page-local components.
  5. Written visual acceptance criteria for the entire existing component: top-level structure, sections, controls, ordering, layout, spacing, typography, colors, copy, states, and responsiveness. Do not narrow criteria to only the user's named mismatch unless the user explicitly says to change only that sub-element.
  6. Identified whether any section depends on API/data loading. If it does, apply .agents/skills/create-skeleton/SKILL.md and include the loading skeleton state in the design contract, implementation scope, QA route/story/test fixture, screenshots, and acceptance criteria.
  7. Defined how the implemented UI will be rendered for QA, including preview fixture, required data state, viewport, and screenshot command. For portal/admin UI, always use a temporary dedicated preview route at src/pages/localTestPage12345.page.js; do not spend time trying auth-gated real routes first.
  8. Defined the screenshot artifact plan:
    • Store temporary Figma and implementation screenshots under screenshots/.
    • Name files with the component or route plus state, for example screenshots/entity-modal-upload-local.png.
    • Capture at most one implementation screenshot per viewport/state per iteration. Reuse that same screenshot for Frontend Engineer evidence and UX/UI QA validation.
    • Do not recapture screenshots when neither code, viewport, data state, route, nor browser state changed.
    • Prefer cropped screenshots of the changed region when the surrounding page is unchanged and responsive/full-page layout is not part of the acceptance criteria.
    • Track every temporary screenshot path in the implementation notes.
    • Delete temporary screenshots before final unless the user explicitly asks to keep them.
    • Skip screenshot artifacts for small source-only fixes when the changed files do not alter rendered markup/styles and the expected visual state is already covered by an existing component.
  9. Assigned exactly two roles and recorded who owns each role:
    • Frontend Engineer: implements only.
    • UX/UI QA: validates only and returns pass/fail feedback.
    • If the user explicitly asks for subagents, delegation, or parallel agent work and the environment exposes a callable subagent or multi-agent tool, use it for these roles.
    • Otherwise, do not ask for subagent authorization. Simulate the separation with two clearly labeled passes in the same agent: Frontend Engineer pass and UX/UI QA pass.

Workflow​

  1. Prepare the design contract

    • Extract exact values for spacing, padding, dimensions, typography, colors, icon sizes, copy, responsive behavior, and interaction states.
    • Capture top-level structure explicitly: modal/page/frame presence, header/footer visibility, container width/height/radius, close button placement, dividers, background/overlay, and every visible child section.
    • For existing component edits, compare the entire component against Figma before deciding implementation scope. List extra code UI that Figma removed and Figma UI that code lacks; either implement those structural differences or record that the user explicitly excluded them.
    • Identify each API-backed section and define its loading state. Skeletons must mirror the final layout using the create-skeleton workflow, not generic spinners, unless the design explicitly specifies a spinner.
    • Map values to existing Tailwind/NPL tokens after verifying they exist in the repo config.
    • Use arbitrary Tailwind values only when config has no matching token.
    • Do not use Tailwind size-* utilities for fixed dimensions. Use explicit w-* h-* pairs so Figma width and height stay independently traceable.
    • Include the Figma screenshot and a checklist of all visible states in the handoff. For multi-state nodes, every state in the provided node must have acceptance criteria.

  2. Dispatch Frontend Engineer

    • Implement the requested UI with the smallest scoped change.
    • For any section that waits on API/data, implement or update a dedicated skeleton component using .agents/skills/create-skeleton/SKILL.md: animate-pulse, bg-npl-neutral-light-alpha-3, explicit loading fallback before loaded content, dimensions matching final UI, no locale strings, and no data fetching inside the skeleton file.
    • Prefer existing components, hooks, services, utilities, tokens, and page-local patterns.
    • Follow repo rules: TypeScript for new files, named React function components, Tailwind utilities, no size-* utilities for fixed dimensions, classNames for conditional classes, direct t('meaningful-kebab-case-key') calls, no unnecessary useEffect/useState/useCallback, no any, no unsafe as, and page-structure placement.
    • Render the implemented state locally using http://localhost:3000/localTestPage12345 when screenshot QA is needed. Assume port 3000 is already running; only investigate server startup if the URL is unreachable.
    • Reuse the existing local browser session when possible. After code changes, wait for hot reload and capture one fresh screenshot per changed viewport/state only when the changed files affect rendered UI.
    • Do not capture a second implementation screenshot for QA if the screenshot artifact already represents the current rendered state.
    • When using src/pages/localTestPage12345.page.js, add only the minimum temporary fixture needed to render the relevant component/state. Do not wire real services or auth-only flows into the preview route. Use the existing localhost:3000 app. Delete the temporary page before final unless the user explicitly asks to keep it.
    • Put temporary screenshots in screenshots/, track the paths, and delete them before final unless the user explicitly asks to keep them.
    • Run focused checks where practical.
    • Report files changed, checks run, actual screenshot path, cleanup status, and any intentional deviations from the design contract.

  3. Dispatch UX/UI QA

    • Compare the implementation against the design source, not the engineer's explanation.
    • First compare screenshots side by side at the same viewport and scale when screenshot QA is required. For small source-only fixes that do not change rendered markup/styles, static verification may pass if it proves the previous wrong visual state can no longer be supplied.
    • Use the shared implementation screenshot captured by the Frontend Engineer when it matches the current code, viewport, route, and state. Do not independently capture another screenshot unless the shared artifact is missing, stale, wrong-state, wrong-viewport, or visibly corrupted.
    • When the QA target is a small changed region and responsive/full-page layout is not in scope, inspect a cropped screenshot of that region plus enough surrounding context to validate alignment.
    • Validate layout, spacing, padding, gaps, alignment, sizing, typography, color/token hierarchy, icons, images, copy, button sizing, responsive behavior, and design states.
    • Validate top-level structure before details: no extra/missing title bars, tabs, headers, footers, buttons, dividers, overlays, sections, fields, or controls compared with Figma.
    • Validate exact visible copy and casing. Existing translation keys that resolve to different copy are a mismatch, even if the key name looks correct.
    • Validate API-backed loading states when present: skeleton layout must match the loaded UI structure, spacing, radii, colors, and repeated item dimensions. Generic loading spinners are a mismatch unless Figma explicitly specifies one.
    • Validate counts and arrangement of repeated items: grid columns, card dimensions/aspect ratios, row gaps, empty states, product/filter chips, and media overlays.
    • Check repo styling rules that affect fidelity: Tailwind utilities, no size-* utilities for fixed dimensions, no inline styles unless unavoidable, classNames, NPL token usage, and exact Figma spacing.
    • Return PASS, or FAIL with a mismatch table: expected value, observed value, location, priority, and recommended fix.
    • QA must return FAIL when any visible element differs materially from Figma, when required screenshot evidence is missing despite a renderable UI, when only one of multiple design states was checked, or when the implementation is merely "close enough."

  4. Iterate

    • If UX/UI QA returns FAIL, pass the same QA feedback back to the Frontend Engineer verbatim.
    • If UX/UI QA reports a Skill prompt issue, the master agent must triage it before the next implementation pass:
      • If the issue is missing task-specific context, update the design contract or Frontend Engineer handoff and send the corrected instructions with the QA feedback.
      • If the issue is a durable gap in this skill that could cause future design mismatches, update this SKILL.md before continuing when it is in the current write scope. If skill editing is out of scope, record the exact proposed skill change in the final status and do not bury it inside ordinary QA feedback.
      • Keep the UI task blocked on UX/UI QA PASS; a prompt fix does not replace the required frontend fix.
    • The engineer fixes only the reported mismatches unless a small root-cause adjustment is required.
    • The engineer re-runs focused checks and updates implementation evidence, including one fresh screenshot for each viewport/state affected by the fix only when the changed files alter rendered UI.
    • Reuse unchanged Figma screenshots and unchanged implementation screenshots across iterations. Recapture only after code, viewport, route, data state, or browser state changes.
    • Send the updated result back to UX/UI QA.
    • Repeat until UX/UI QA returns PASS.

  5. Final review

    • Run focused code review using .agents/skills/code-review/SKILL.md for substantial UI changes. For small source-only fixes, do a local self-review against the touched diff and applicable rules instead of loading the full review workflow.
    • Run focused lint, type, test, or build checks appropriate to the touched files.
    • Do not finish if UX/UI QA, code review, or required checks fail.
    • Delete temporary preview routes, screenshots, downloaded Figma images, and browser QA artifacts unless the user explicitly asks to keep them. Verify cleanup with git status --short or an equivalent scoped file check before final.

Frontend Engineer Prompt​

Role: Frontend Engineer.

Implement the UI to match the provided design exactly.

Context:
- Target route/component:
- Figma MCP URL/node ID:
- Figma MCP design context and screenshot:
- Design contract:
- Files inspected:
- Reusable components/tokens found:
- Acceptance criteria:
- API-backed/loading sections and skeleton contract:
- Write scope:

Constraints:
- Follow AGENTS.md and .agents/rules/*.mdc.
- Use Tailwind/NPL tokens from this repo.
- Do not use Tailwind `size-*` utilities for fixed dimensions; use explicit `w-* h-*` pairs.
- Do not guess Figma values; fetch them through Figma MCP at `http://127.0.0.1:3845/mcp`.
- If a section loads from an API, follow `.agents/skills/create-skeleton/SKILL.md` and include the skeleton state in implementation evidence.
- Use the shared screenshot policy when screenshot QA is required: one implementation screenshot per viewport/state per iteration, reused by UX/UI QA; recapture only after code, viewport, data state, or browser state changes.
- Do not edit unrelated files.
- Do not commit or push.
- You are not alone in the codebase; do not revert others' work.
- Report files changed, checks run, screenshot paths, and cleanup status.

UX/UI QA Prompt​

Role: UX/UI QA.

Validate the implementation against the design source.

Evidence required:
- Figma screenshot/source inspected:
- Actual implementation screenshot inspected when screenshot QA is required, using the shared Frontend Engineer artifact when current:
- Render source inspected: `src/pages/localTestPage12345.page.js` for auth-gated portal/admin UI, or story/test fixture for non-portal UI
- Viewport and state checked:
- API-backed/loading skeleton states checked:
- Temporary artifact paths checked and cleanup expectation:
- If no actual screenshot, exact blocker:

Compare:
- Top-level structure: modal/page/frame, title/header/footer, close button, tabs, dividers, overlay, container width/height/radius, sections, field/control ordering.
- Layout, spacing, padding, gaps, alignment, and dimensions.
- Explicit width/height utilities for fixed dimensions; no `size-*` shortcuts.
- Typography, line height, weight, colors, icons, images, and copy.
- Loading skeleton states for API-backed sections: final-layout parity, spacing, radii, placeholder dimensions, tokens, and loading-to-loaded fallback order.
- Repeated content: counts, grid columns, card sizes, aspect ratios, chips, empty states, media overlays.
- Responsive behavior and relevant states.
- Repo styling rules: Tailwind, NPL tokens, classNames, no inline styles unless justified.

Return:
- PASS only if required screenshot evidence and every checked state are visually and behaviorally aligned; for small source-only fixes, PASS may rely on static verification when the skip reason is explicit.
- FAIL with a mismatch table: exact mismatch, expected value, observed value, location, priority, and recommended fix.
- Skill prompt issue: `none`, `task-handoff-gap`, or `durable-skill-gap`. When not `none`, include the exact missing or misleading instruction, why it caused or allowed the mismatch, and the recommended master-agent fix. This is required when the Frontend Engineer produced a materially wrong design because the skill prompt, design contract, or handoff was ambiguous, incomplete, or misleading.
- FAIL automatically if screenshot QA was required but no actual screenshot was inspected, if any required state was skipped, or if any visible element is materially different from Figma.
- Do not request or capture a duplicate implementation screenshot when the shared artifact is current and sufficient for QA.

Completion Criteria​

Complete only when:

  • UX/UI QA returns PASS.
  • Any UX/UI QA Skill prompt issue has been triaged by the master agent, with the design contract/handoff fixed for the current task and any durable skill gap patched or explicitly recorded as out of scope.
  • Code review or focused self-review finds no blocking issues.
  • Relevant checks pass, or skipped checks are explained.
  • Figma/design values were fetched from Figma MCP and not guessed.
  • Actual implementation screenshot evidence was inspected for every renderable state that required screenshot QA, using one shared current screenshot artifact per viewport/state per iteration, or the screenshot skip reason/render blocker is recorded.
  • API-backed sections have skeleton states implemented and QA-checked with .agents/skills/create-skeleton/SKILL.md, or the absence of API loading is recorded.
  • Temporary preview route and screenshots are deleted before final unless the user explicitly asked to keep them.
  • Final status confirms no unintended screenshots/ artifacts or src/pages/localTestPage12345.page.js remain.
  • The implementation stays scoped and follows repo rules.