---
paths:
  - "web/**"
  - "templates/**"
---

# Manual Testing for UI Changes

If a PR makes frontend changes, manually verify the affected UI. This
catches issues that automated tests miss. **Treat this checklist as
blocking, not advisory** — every applicable item must be verified
before the change is ready.

Most of these items can be completed by an agent. Start with
analyzing the files, because it is cheaper than the `/visual-test`
skill (`.claude/skills/visual-test/SKILL.md`). For things you aren't
sure about, ensure either the user completes the relevant visual
tests or you've run the visual test skill on them.

## Visual appearance

- Is the new UI consistent with similar elements (alignment, spacing,
  fonts, colors, sizes)? Find the closest existing analogues and compare
  carefully.
- Is alignment correct, both vertically and horizontally? Measure
  programmatically with `getBoundingClientRect()` when in doubt —
  don't eyeball it.
- Does every state look right and match similar UI: hover, active,
  disabled, focused, selected, empty, overflowing?
- Did the change accidentally affect other parts of the UI? Use
  `git grep` to check if modified CSS is used elsewhere.
- CSS changes are notorious for unintended consequences — check every
  page and component that shares the selectors you modified, and
  demonstrate with pixel-precise before/after comparisons that there
  are none.
- Check all of the above in both light and dark themes when the
  change could plausibly affect colors, contrast, or theme-dependent
  imagery. Pure geometry/typography changes (`font-size`,
  `line-height`, `margin`, `padding`, `display`, `font-weight`,
  etc.) don't need a separate dark-theme pass —
  `web/styles/dark_theme.css` only overrides colors, so a single
  theme suffices for theme-invariant changes.

## Responsiveness and internationalization

- Does the UI look good at different window sizes? Check wide desktop
  (1920px), typical laptop (1280px), tablet, and narrow phone (480px).
  Any widths between these values should also work.
- Would the UI break if translated strings were 1.5x longer than
  English? What if they were half as long? Both directions matter.
  Think about right-to-left languages too.

## Functionality

- Are live updates working as expected?
- Is keyboard navigation, including tabbing to interactive elements, working?
- Do screen readers get sensible labels and roles for new elements?
- If the feature affects the message view, try different narrows: topic,
  channel, Combined feed, direct messages.
- If the feature affects the compose box, test both channel messages and
  direct messages, and both ways of resizing.
- If the feature requires elevated permissions, test as both a user who
  has permissions and one who does not.
- Think about feature interactions: could banners overlap? What about
  resolved/unresolved topics? Collapsed or muted messages?
- Think about edge cases in data: empty lists, very long names, single
  items vs. hundreds, special characters in strings.