THE GITHTML FIELD GUIDE
Make report statuses understandable without color
Write the status in text and use color only as an additional cue. Labels such as Passed, Needs review, and Not checked communicate more reliably than green, amber, and gray dots alone. Explain what each status means and include the evidence or next action needed to interpret it responsibly.
Define the status vocabulary
A colored badge can conceal an ambiguous process. Does green mean tested, approved, complete, or merely unchanged? Define a small set of statuses in terms of observable conditions. For example, Checked may mean that a reviewer inspected the exported artifact, while Not checked means no conclusion should be drawn. Keep those distinctions visible.
Avoid treating Unknown as equivalent to Failed. A missing observation and a negative result require different next steps. In a review table, include a brief reason or an evidence link where needed. The status should summarize the assessment without replacing the information required to understand its scope.
Use redundant visual cues
Color can help scanning, but the label must remain meaningful if color is unavailable or difficult to distinguish. Include the status word inside the badge or cell. Shapes and icons may supplement it, but an unexplained symbol can be just as ambiguous as a colored dot. Ensure the visible wording is also available to assistive reading.
Check foreground and background contrast for the actual badge colors, including dark appearance. Pale text on a pastel surface can look polished while being hard to read. Do not infer adequate contrast from a palette name or from how it looks on one display. Review links and focus states separately if the status itself is interactive.
Review the meaning in plain text
Copy the relevant section into a plain-text view or inspect it without decorative styling. Can you still distinguish a completed check from an unresolved issue? Can you identify the owner and next action? If not, the report is relying on presentation to carry essential information.
- Define each status with a concrete meaning.
- Use visible labels rather than color-only dots.
- Distinguish failed checks from checks that were not performed.
- Add a reason, evidence reference, or next action where necessary.
- Inspect both light and dark color pairs.
- Check a grayscale or unstyled view to confirm that the review conclusion remains intact.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.