How to Write an Issue for a UI UX Designer

How to Write Design Issue Tickets

This page explains how to create design tickets using the Blank Design Issue Template in GitHub. The focus is on writing clear overviews, documenting design iterations, and ensuring a complete engineering handoff.

---

How to Use This Template

• Overview: Write a 1–2 sentence “X for Y” summary (e.g., “We need to update the nav header so that users on mobile devices can view and dismiss the header.”).
• Action Items: Break down the design work into a checklist of specific requirements and steps.
• Design Iterations: Add a new section each week with notes and screenshots; use the dropdown snippet provided.
• In Progress/In Review: Move tickets between these states to reflect status for PMs and teammates.
• Hand Off Materials: Document the Figma section name and include before/after screenshots of the final design.
• Engineering Handoff: Fill in all handoff materials, add the ready for dev lead label, and comment: “This ticket is ready for engineering handoff.”

---

Emphasis on Iteration

Design work should be documented week to week. Each iteration shows progress, captures feedback, and keeps everyone aligned. Think of iteration sections as a running log of design decisions — valuable for PMs, engineers, and future reference.

---

Using the Design Issue Template

When opening a design ticket, use the Blank Design Issue Template provided in GitHub. Below are the key sections and how to complete them:

1. Overview

• Write a 1–2 sentence summary in the “X for Y” format (what is being done for what purpose).
• Keep it concise and focused on the reason for the design change.

2. Action Items

• Use a checklist to outline design requirements and steps.
• Include tasks such as design explorations, documenting interactions in Figma, and finalizing handoff materials.

3. Design Iterations

• Designers should iterate weekly and record each iteration in its own <details> section.
• Each iteration should include:
  • A link to notes or feedback.
  • A screenshot of the current design version.
• Use the iteration dropdown snippet in the template to stay consistent.

💡 Iterations are critical: they capture design history, feedback, and decision-making — don’t skip them.

4. Hand Off Materials

• Add the Figma section name where the finalized design lives.
• Include before and after screenshots to clearly show what has changed.
• This section should only be filled in once the design is finalized.

5. Designer Resources

• Use the iteration dropdown snippet for additional rounds of feedback.
• Follow the engineering handoff checklist:
  1. Ensure all handoff materials are complete.
  2. Add the ready for dev lead label.
  3. Comment: “This ticket is ready for engineering handoff.”

---

Best Practices

• Keep tickets short, clear, and visual.
• Always link directly to Figma (not just screenshots).
• Use descriptive titles and labels so tickets are searchable.
• Treat tickets as a record of what changed, why, and how.

---

✅ Following this structure ensures design tickets are clear, collaborative, and fully prepared for engineering handoff.