implement-ui

name	implement_ui
description	Convert a provided UI design source into an implementation-ready design brief that maps visual intent to Torus design tokens, icons, reusable components, and code targets. Use when a Jira ticket or developer provides Figma or another design reference and the team needs governed implementation guidance before coding. Supports durable feature briefs and lightweight ticket-level briefs.
examples	["$implement_ui docs/exec-plans/current/epics/intelligent_dashboard/tile_chrome slice=section-chrome figma=https://figma.com/...","Use implement_ui for MER-5258; the Jira ticket has the Figma links","Before implementing this UI tweak with harness-work, run implement_ui against this Figma link"]
when_to_use	["A feature or ticket has meaningful UI work and the visual source of truth is Figma or another design reference.","The team needs to map design intent to existing tokens, icons, reusable components, and repo conventions before implementation.","A ticket is small enough for `harness-work`, but still needs design-system triage before coding."]
when_not_to_use	["The work is backend-only or does not materially change the UI.","There is no external design reference and local code inspection alone is sufficient.","The task is direct implementation after design mapping is already settled.","The task needs end-to-end Figma-backed UI implementation, iteration, and fidelity verification; use `ui_workflow` instead."]

Required Resources

Always load before running:

• references/workflow.md
• references/repo_waypoints.md
• references/guardrails.md
• references/target_organization.md
• references/design_system_sources.md
• assets/templates/ui_implementation_brief_template.md

Load when needed:

• references/icon_mapping.md
  • when the brief needs to map a new icon, verify whether an icon already exists, or recommend icon-system extension
• references/fidelity_rules.md
  • when the brief must describe static vs dynamic fidelity, overflow handling, or implementation constraints that affect layout matching
• references/responsive_validation.md
  • when the design includes breakpoint-specific behavior, dense dashboards, charts, stacked layouts, or any responsive ambiguity that should be called out before coding

When running in feature mode, also read:

• <feature_dir>/prd.md
• <feature_dir>/fdd.md when present
• <feature_dir>/plan.md when present

When the feature lives under an epic, also consult relevant epic docs under docs/exec-plans/current/epics/<epic_slug>/.

Mission

This skill does not implement UI code directly.

It produces an implementation-ready design brief that:

• identifies the visual source of truth
• maps design to existing Torus design tokens, icons, and reusable components
• identifies gaps that need developer confirmation
• recommends where code should live

Use it as a bridge between design references and the repo-local UI workflow, which then feeds implementation skills such as harness-develop or harness-work.

In this repository, when a Figma-backed UI task needs implementation fidelity and iterative comparison against the current UI, this skill should be treated as the governed brief-generation phase inside the repo-local ui_workflow skill documented at .agents/ui-workflow/README.md, not as the full workflow by itself.

Preferred Execution Context

This skill can run in plain Codex mode.

Prefer Tidewave when available for:

• complex UI surfaces
• responsive layouts
• dashboard or chart-heavy views
• work where visual fidelity is especially important

Why:

• Tidewave enables faster runtime inspection, viewport resizing, and visual verification against the design source.
• In practice this often produces a stronger brief with fewer hidden assumptions than Codex-only execution.

If Tidewave is not available, continue in Codex and record uncertainty more explicitly in Open Questions / Requires Approval.

Modes

Choose one mode up front:

• full

  • Use for feature work that already has a spec pack.
  • Write a durable artifact to <feature_dir>/design/<slice_slug>.md.
  • This mode is appropriate when the design materially affects planning or slice-level implementation.

• lightweight

  • Use for harness-work tickets or smaller UI changes.
  • Produce the brief in chat by default.
  • Do not create a file unless the user explicitly asks to persist the brief.

If the request does not specify a mode:

• prefer full when feature_dir is provided
• otherwise prefer lightweight

Workflow

1. Resolve the source of truth for the design.

   • Prefer explicit Figma links from the user.
   • If the user points to a Jira ticket, extract Figma links from the ticket or its comments.
   • If multiple Figma nodes exist, identify which nodes correspond to the scope being implemented.
   • For icons, first check the Torus design-system icon source at https://www.figma.com/design/4pTqLuqHbALAbZ31wvIHIX/NG-23---Torus-Design-System?node-id=2-24.

2. Classify the implementation surface.

   • liveview/heex
   • react
   • mixed
   • State the chosen surface explicitly.

3. Inventory the design.

   • layout and structure
   • typography
   • colors and semantic intent
   • iconography
   • interactive states
   • responsive behavior
   • ambiguities or missing states

4. Map the design to the existing system.

   • design tokens
   • icon system
   • existing reusable components or patterns
   • likely target modules/files
   • whether the result should stay feature-local or be extracted to design_tokens/
   • for cross-feature primitives, first check whether a shared primitive already exists under design_tokens/
   • if proposing a new shared primitive, state where it should live, how it should appear in /dev/design_tokens, and which Figma node should be linked from the catalog
   • load conditional references when icon extraction, fidelity rules, or responsive behavior need deeper guidance

5. Detect and record gaps.

   • unrecognized token usage
   • hardcoded colors with no clear token mapping
   • missing icons
   • reusable component candidates
   • missing or ambiguous design states

6. Produce the design brief.

   • Use the exact section blocks from assets/templates/ui_implementation_brief_template.md.
   • In full mode, write <feature_dir>/design/<slice_slug>.md.
   • In lightweight mode, return the brief in chat unless the user explicitly requests persistence.

7. End with a clear handoff.

   • If implementation should follow, state whether the next skill should be harness-develop or harness-work.
   • Do not proceed to coding unless the user explicitly asks.

Output Contract

Every brief must include:

• Design Sources
• Implementation Surface
• Design System Alignment
• Token Mapping
• Icon Mapping
• Component Reuse Plan
• File Targets
• Open Questions / Requires Approval

In lightweight mode, keep the same structure in chat unless the user asks for a shorter summary.

Guardrails

Follow the detailed rules in:

• references/guardrails.md
• references/target_organization.md
• references/design_system_sources.md
• references/icon_mapping.md when icon work is in scope
• references/fidelity_rules.md when fidelity or overflow behavior must be specified
• references/responsive_validation.md when responsive behavior must be assessed

Non-negotiable rules:

• Prefer existing design tokens, icons, and reusable components before proposing new ones.
• For cross-feature primitives such as buttons, icon buttons, badges, pills, tabs, and simple feedback surfaces, prefer design_tokens/ over feature-local styling unless there is a clear reason to keep the work local.
• If a new shared primitive is recommended, the brief must say that it should be wired into /dev/design_tokens and linked to its canonical Figma source when one exists.
• If a token, icon, interaction, or responsive behavior is ambiguous, record it under Open Questions / Requires Approval.
• Do not invent missing design behavior.
• Do not create or modify design tokens automatically. Recommend additions only when necessary and only with explicit approval.

Validation

Before finishing, verify that the brief:

• uses the exact section structure from assets/templates/ui_implementation_brief_template.md
• names the primary design source and the relevant Figma node ids or links
• states the implementation surface explicitly
• maps tokens, icons, reusable components, and file targets
• explicitly says whether any new primitive should live under design_tokens/ or remain feature-local
• includes /dev/design_tokens and Figma-link expectations when a new shared primitive is proposed
• records any unresolved ambiguity or approval-dependent decision in Open Questions / Requires Approval

Handoff Guidance

If the user wants implementation next:

• route the work through the repo-local UI workflow documented at .agents/ui-workflow/README.md
• use harness-develop for planned feature execution after the workflow establishes the canonical brief and UI implementation path
• use harness-work for smaller ticket-level execution after the workflow establishes the canonical brief and UI implementation path
• tell the implementer to read the resulting brief before coding