Files
zed/docs/src/development/ui-checklist.md
Finn Evers e52ab15eac Improve contribution guidelines and experience (#64296)
# Objective

Both our PR template and contribution guidelines are too convoluted.
This results in:
- contributors missing important information because the information is
buried in the contributing file
- worse commit descriptions post-merge due to the most important
information being buried and or a lot of boilerplate present
- the PR template often being neglected by staff themselves entirely
- more work for reviewers/engineer on triage here since they have to
repeatedly point people at the contribution gudelines

## Solution

In order to take a stab at improving this, this PR goes for the
following:
1. Shrink the PR template
- this aims at reducing the cognitive load looking at this and filling
it out whilst preserving all the important information needed for
reviewers
- a lot of text has been removed to make commit messages in the repo
more readable
- keep text still visible as opposed to having HTML comments so that
reviewers spot this and can raise

## Testing

Tested this by giving it a read myself and iterating with Kirill on the
final wording/sorting/organization of contents and files.

## Self-Review Checklist:

- [-] I've reviewed my own diff for quality, security, and reliability
- [-] Unsafe blocks (if any) have justifying comments
- [-] The content adheres to Zed's UI standards
([UX/UI](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md#uiux-checklist)
and
[icon](https://github.com/zed-industries/zed/blob/main/crates/icons/README.md)
guidelines)
- [-] Tests cover the new/changed behavior
- [-] Performance impact has been considered and is acceptable

## Showcase

<details>
  <summary>The new contribution guidelines</summary>
<img width="1209" height="1293" alt="grafik"
src="https://github.com/user-attachments/assets/6a3f5012-7f46-48b7-add2-9f2400f01c57"
/>

</details>


<details>
  <summary>The PR template in action</summary>

<img width="879" height="688" alt="grafik"
src="https://github.com/user-attachments/assets/87e5ad65-7ade-45b8-b8a8-8818c9a49ba8"
/>

</details>

---

Release Notes:

- N/A

---------

Co-authored-by: zelenenka <241371603+zelenenka@users.noreply.github.com>
2026-09-25 15:42:49 +00:00

2.8 KiB
Raw Permalink Blame History

title, description
title description
UI/UX Checklist Review UI changes for accessibility, responsiveness, consistency, and performance.

UI/UX checklist

Use this checklist when your changes affect UI.

Accessibility / Ergonomics

  • Do all keyboard shortcuts work as intended?
  • Are shortcuts discoverable (tooltips, menus, docs)?
  • Is it usable without a mouse (keyboard-only navigation)?
  • Do all mouse actions work (drag, context menus, resizing, scrolling)?
  • Does the feature look great in light and dark mode themes?
  • Are hover states and focus indicators clear and consistent?

Responsiveness

  • Does the UI scale gracefully on:
    • Narrow panes (e.g., side-by-side split views)?
    • Short panes (e.g., laptops with 13" displays)?
    • High-DPI / Retina displays?
  • Does resizing panes or windows keep the UI usable and attractive?
  • Do dialogs or modals stay centered and within viewport bounds?

Platform Consistency

  • Is the feature fully usable on Windows, Linux, and macOS?
  • Does it respect system-level settings (fonts, scaling, input methods)?

Performance

  • All user interactions must have instant feedback.
    • If the user requests something slow (e.g. an LLM generation) there should be some indication of the work in progress.
  • Does it handle large files, big projects, or heavy workloads without degrading?
  • Frames must take no more than 8ms (120fps)

Consistency

  • Does it match Zed’s design language (spacing, typography, icons)?
  • Are terminology, labels, and tone consistent with the rest of Zed?
  • Are interactions consistent (e.g., how tabs close, how modals dismiss, how errors show)?

Internationalization & Text

  • Are strings concise, clear, and unambiguous?
  • Do we avoid internal Zed jargon that only insiders would know?

User Paths & Edge Cases

  • What does the happy path look like?
  • What does the unhappy path look like? (errors, rejections, invalid states)
  • How does it work in offline vs. online states?
  • How does it work in unauthenticated vs. authenticated states?
  • How does it behave if data is missing, corrupted, or delayed?
  • Are error messages actionable and consistent with Zed’s voice?

Discoverability & Learning

  • Can a first-time user figure it out without docs?
  • Is there an intuitive way to undo/redo actions?
  • Are power features discoverable but not intrusive?
  • Is there a path from beginner → expert usage (progressive disclosure)?

See the contribution guidelines for preparing your pull request.