Mac bug report checklist: repro, evidence, and handoff

The short answer: file one issue, state one observable failure, start from a known state, record exact steps and a clock anchor, separate expected from actual results, and attach the smallest artifact that proves the claim. Route rendered color evidence to the visual branch, aggregate CPU or memory trends to the performance branch, and process or system diagnostics to the owner that can act on them. After a fix, rerun the same sequence and record the new result.

This checklist is for Mac app makers, designers, front-end developers, support teams, and indie teams handling visual regressions or performance complaints. It does not replace a crash log, Instruments trace, accessibility audit, sysdiagnose, or Apple Feedback Assistant when one of those artifacts owns the next decision.

Disclosure: I build TeenyApps, including TeenyColor for local color evidence and TeenyStat for first-pass system vitals. My bias is toward small native Mac utilities. Apple's tools still own deep diagnosis.

The bug-report evidence chain

01Start from a known state, then write the repro

Keep one issue per report. Apple uses that rule in Feedback Assistant because two similar symptoms can have different causes and different owners. If a slow window and incorrect label can reproduce independently, file two reports and cross-reference them instead of making one attachment pile serve two claims.

The repro is the spine of the report. Begin with the state that exists before step one: fresh launch or already running, signed in or signed out, document open or closed, light or dark appearance, permission allowed or denied, display connected or disconnected. Without that baseline, two people can follow the same actions from different starting points and get different results.

Write the path as actions someone else can run: open this build, choose this account, go to this screen, click this control, switch this appearance, wait this long, observe this result. Keep the first version short. "Open Settings, switch to dark mode, select Team, hover the disabled Save button" is stronger than a page of guesses about CSS, SwiftUI state, browser cache, or display profiles.

Run the exact sequence again before filing. If it repeats, say how many attempts reproduced it. If it is intermittent, record both the successful and failed attempts plus the condition that changed. Frequency is evidence; "sometimes" is not.

If the report turns into a live troubleshooting session, use the Mac support call checklist to test the current paste and each clipboard history, verify the shared surface, separate local playback from transmitted audio, and record remote confirmation.

Use a clean name for the artifact set and anchor it to the clock: 2026-09-06T14-32-18Z-settings-dark-disabled-save. Put that same timestamp in the report before opening diagnostic tools. The next person can then align the visible failure, a CPU trend, a process sample, and nearby log lines without guessing which run they came from.

02Record only the conditions that can change the result

Record the app name and build, macOS version, Mac model when hardware matters, and any account, permission, appearance, display, power, or peripheral state that the repro depends on. Do not paste a full hardware inventory into every issue. Include a field only when it could explain the result or help someone reproduce it.

Apple's current Feedback Assistant guidance asks reporters to summarize the technology, platform, and version; give detailed steps; separate expected and actual results; and note factors such as iCloud or Accessibility settings that may influence the behavior. That structure works for an internal issue tracker too.

A useful environment line might read: App 2.4 (184), macOS 26.5, Apple silicon, dark mode, Screen Recording allowed, external Display P3 monitor at 2x scaling. It is compact and preserves every condition needed for this visual repro. A performance report might replace display profile and appearance with power source, thermal state, background workload, and the exact file or document used.

03Capture the screen state without leaking private data

Apple's screenshot tools are enough for most UI reports. Capture the whole screen when layout and display context matter. Capture a portion when the bug is local to one component. Use a short recording when the bug depends on hover, loading, animation, drag, or timing.

Before you attach anything, crop or mask customer names, tokens, unreleased features, and internal dashboards. A useful bug report should not turn a UI mistake into a privacy mistake.

Give each attachment a job. A screenshot proves a visible state. A recording proves order or timing. A sampled value records one rendered color. A process view names the process using a resource. A diagnostic preserves deeper state. If an attachment does not answer a question in the report, leave it out.

04Use color values when the bug is visual

A color complaint needs more than "this looks off." Capture the rendered state, sample the actual pixel, and label what the value represents: primary label, card background, warning icon, focus ring, disabled text, selected row, or destructive button.

TeenyColor fits this first-pass job because its homepage and Swift source confirm native screen sampling with Apple's color sampler, conversion to sRGB when available, selected copy formats, local history, names, pins, and text or JSON palette export. That is useful when you need to place an observed value in an issue comment without uploading a private screenshot to an online tool.

Be precise about the limit. A sampled hex value records what appeared at one pixel after the app converted the sample to sRGB. It does not preserve the original display-profile identity, name the source token, explain why the pixel rendered, or prove that every state fails. Pair the value with the screenshot, role, state, display conditions, and source value when the source is available.

For deeper color evidence, use the TeenyColor guide to report UI contrast bugs with color evidence. It keeps the screenshot, foreground/background values, and WCAG threshold together.

05Report contrast with both values, not one screenshot

Contrast bugs need a pair: foreground and background. If the text is too faint, attach the sampled foreground value, the sampled background value, text size, UI state, and the standard you are checking against.

The W3C WCAG guidance uses 4.5:1 for normal text at Level AA, 3:1 for large text, and 7:1 for normal text at Level AAA. TeenyColor's source includes WCAG contrast math and the app shows badges against white and black backgrounds. That can catch common black-or-white text mistakes quickly. For any other foreground and background pair, include both values so the reviewer can verify the pair in a full contrast checker.

Use authored foreground and background values for a conformance claim when they are available. W3C warns that antialiasing can make edge pixels differ from the color specified by the author, and it says threshold ratios should not be rounded. Keep rendered samples as evidence of what the user saw, but do not turn a softened glyph-edge pixel into the source color.

06Capture system trend before blaming the app

Performance reports get noisy fast. A Mac can feel slow because the app is doing real work, another process is busy, memory pressure is high, a browser tab is misbehaving, a video export is running, or a fanless Mac is thermally constrained.

TeenyStat is useful as a quiet first signal. The homepage and source confirm aggregate and per-core CPU usage, used memory, fan speed when available, 60-point sparklines, session high and low values, and threshold alerts. Its source reads CPU through host_processor_info, memory through host_statistics64, and fan values through SMC keys where the Mac exposes them.

The 60 points are a short rolling window, not permanent telemetry. At the default three-second interval they cover about three minutes; the one, five, and ten-second settings cover about one, five, and ten minutes. Record the interval with the screenshot. TeenyStat does not name a process or show Apple's Memory Pressure, so use Activity Monitor when the report needs process ownership, CPU History, Memory Pressure, swap, or a safe quit decision. The TeenyStat guide to capturing CPU and memory evidence for Mac bug reports connects the rolling window to the right escalation artifact.

07Match the escalation artifact to the owner

Activity Monitor is the right handoff when the next decision depends on process-level evidence. Choose the artifact by the question, not by habit.

For an Apple platform or framework issue, Feedback Assistant is the owning path. Its Mac app automatically attaches a sysdiagnose, UI issues benefit from screenshots or recordings, and app issues may benefit from a minimal sample project. Apple also asks for a Mac System Information Report for crashes, kernel panics, hardware bugs, and printing issues.

Quitting or force quitting changes the evidence and can lose work. Record the clock and collect the safe pre-quit artifact first when possible, then say exactly when the process was terminated.

Define the rerun before the report leaves your hands

Write the acceptance check while the failure is still visible. Reuse the same starting state, build path, account, document, appearance, display, power state, action sequence, wait time, and observation point. State which result changes a fail to a pass and which diagnostic must stay quiet or recover.

A fix is not verified because the reporter can no longer see the symptom after restarting everything. Rerun the named sequence on the fixed build, preserve the same clocked evidence points, and record pass, fail, or not reproduced. If a condition had to change, the comparison needs that caveat.

Copyable Mac bug report template

1. Summary: name the app or technology, platform, version, symptom, and triggering condition.
2. Starting state: record account, document, permission, appearance, display, power, or hardware state only when relevant.
3. Steps to reproduce: list the shortest numbered path you repeated.
4. Expected result: what should happen.
5. Actual result: what happened instead.
6. Frequency and clock: record attempts, results, and one timestamp with time zone for the evidence window.
7. Environment: app build, macOS version, Mac model when relevant, and connected display or peripheral details when relevant.
8. Focused evidence: attach a screenshot, recording, color pair, system trend, process view, log, or diagnostic only when it supports a named claim.
9. Owner and escalation: name who acts next and attach a deeper diagnostic only when that owner needs it.
10. Privacy check: remove customer data, credentials, private paths, and unreleased information that the owner does not need.
11. Rerun contract: define the same sequence and observable result that will verify a fix.

Six checks before you file

1. The title identifies the product area, failure, and condition without opening the attachments.
2. The repro begins from a known state and records whether the same sequence repeated.
3. Expected and actual results describe observable behavior, not a guess about the cause.
4. Every attachment answers a question named in the issue.
5. The report routes deeper evidence to the tool or team that can act on it.
6. The fix can be tested with the same starting state, steps, timing, and observation point.

Sources checked

• TeenyColor claims were checked against the TeenyColor homepage and local Swift source for screen sampling, sRGB conversion, copy formats, local history, names, pins, export, and WCAG contrast badges against white and black.
• TeenyStat claims were checked against the TeenyStat homepage and local Swift source for CPU reads, memory reads, fan speed reads, per-core CPU, sparklines, session high/low values, thresholds, and fanless-Mac behavior.
• Apple Support: Take a screenshot on Mac.
• Apple Developer: Feedback Assistant for report summaries, reproduction steps, expected and actual results, contextual factors, sysdiagnose, System Information, sample projects, screenshots, and recordings.
• Apple Support: View CPU activity in Activity Monitor on Mac.
• Apple Support: View memory usage in Activity Monitor on Mac.
• Apple Support: Run system diagnostics in Activity Monitor on Mac for Sample Process, Spindump, System Diagnostics, and Spotlight Diagnostics.
• Apple Support: Quit an app or process in Activity Monitor on Mac.
• W3C: Understanding Success Criterion 1.4.3 Contrast (Minimum) for authored color pairs, antialiasing, and unrounded thresholds.

FAQ

What should a Mac bug report include?

A useful Mac bug report covers one issue and records a concise title, known starting state, exact steps, app and macOS versions, expected and actual results, frequency, a clock anchor, and only the evidence needed to investigate and rerun the failure.

When should I use Activity Monitor diagnostics for a bug report?

Use Activity Monitor when the report needs a process owner or deeper evidence. Apple documents a three-second Sample Process report, Spindump for an unresponsive app terminated with Force Quit, and broader system or Spotlight diagnostics.

Can a color picker prove a UI bug?

A color picker can record an observed rendered pixel, but it cannot identify the source token or prove conformance by itself. Include the UI state, foreground and background source values when available, observed samples, and the applicable WCAG threshold.