Incorporating design reviews into the code review process helps make sure that both the functionality and user experience of software are addressed during development. By combining these two review stages, teams can achieve a cohesive workflow that balances technical excellence and intuitive design.
Why integrate design and code reviews?
Before diving into best practices, it’s worth understanding why this integration is valuable:
- Improved Collaboration: It bridges the gap between designers and developers, fostering a shared understanding of goals and challenges.
- Consistency: Ensures that the implementation matches the intended design specifications.
- Reduced Rework: Catching design or implementation issues early reduces costly fixes later in the development lifecycle.
- Enhanced User Experience: Aligning design and functionality leads to cohesive, user-friendly products.
Best Practices for combining design and code reviews
1. Establish clear Expectations and roles
- Define the scope of design reviews within the code review process. Will designers verify the UI/UX elements, or will they also comment on code affecting user workflows?
- Assign responsibilities for each review type and clarify what designers and developers are expected to check.
2. Use collaborative tools
- Leverage tools that support both code and design reviews. For example, use version control systems like GitHub for code and link design specifications via tools like Figma or Zeplin.
- Consider integrations that bridge these tools, such as embedding design prototypes or screenshots directly into pull request comments.
3. Incorporate design checks into pull requests
- Require developers to reference design mockups, style guides, or interaction flows in their pull requests.
- Designers can review the visual output of code changes by accessing previews or staging environments directly from the pull request.
4. Assign dual reviewers
For each PR, include both a design reviewer and a technical reviewer. Tools like Graphite allow assigning reviewers and grouping PRs in specific categories for reviewers, such as "Waiting for review". The review can be divided:
- Design reviewers should focus on visual and UX fidelity.
- Technical reviewers should ensure proper implementation.
5. Adopt a unified feedback process
- Use a single platform for feedback to avoid siloed discussions. Centralizing comments from both designers and engineers ensures all input is considered in one place.
- Encourage designers and developers to participate in the same review session when significant UI changes are involved.
6. Create a shared design-system repository
- Maintain a shared repository that includes both code and design assets (e.g., CSS variables, UI components, and design tokens).
- Developers can reference these assets during implementation, and designers can ensure consistency.
7. Set clear criteria for approval
- Define clear metrics for when a pull request can pass both code and design reviews. This may include:
- Adherence to design mockups
- Accessibility compliance
- Responsiveness and scalability
- Establish thresholds for minor deviations that can be adjusted in future iterations without blocking the release.
8. Iterate on the process
- Regularly evaluate the effectiveness of your integrated review process. Gather feedback from designers and developers on what’s working and what needs improvement.
- Use retrospectives to refine workflows and address recurring challenges.
Example workflow for a combined review process
- PR creation: A developer submits a PR with linked design files.
- Automated checks: CI/CD pipelines validate code quality and enforce design rules.
- Design review: A designer reviews visual aspects via the linked assets and Graphite’s PR inbox.
- Code review: A developer checks technical details.
- Feedback resolution: The developer addresses feedback, updating both code and design links if necessary.
- Approval and merge: The PR progresses once both reviewers approve.
Leveraging the Graphite PR inbox for reviews
Graphite’s PR inbox serves as an "email client" for your pull requests, enabling organized and efficient reviews. It helps teams track PRs that require immediate attention, with features like:
- Default repositories: Focus on specific repositories tied to your projects.
- Custom sections: Create tailored views for PRs requiring design and code reviews.
- Collaborative filters: Share configurations across teams for consistent review standards.
By utilizing tools like Graphite, you can centralize design and code reviews to promote better cross-collaboration and speed up approvals.