Badge anatomy

Shields.io popularized the two-part "flat" badge format used on GitHub README files. A badge consists of a left label (key), right value, and a background color conveying status.

https://img.shields.io/badge/<LABEL>-<MESSAGE>-<COLOR>

Common CI/status badges

Badge type	Purpose
Build passing/failing	Shows CI pipeline status
Coverage %	Test coverage from Codecov, Coveralls
npm version	Current published package version
License	Open source license (MIT, Apache, GPL)
Downloads	npm/PyPI weekly download count

How to embed a badge in a README

Badges are image URLs that can be embedded in Markdown or HTML:

Markdown (with link):
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://your-ci-url)

Markdown (no link):
![License](https://img.shields.io/badge/license-MIT-blue)

HTML:
<a href="https://your-ci-url">
  <img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build Status" />
</a>

Dynamic badge APIs

Shields.io: The most widely used badge service. Supports hundreds of endpoints (GitHub, npm, PyPI, Docker, custom JSON endpoints). URL pattern: https://img.shields.io/badge/<label>-<message>-<color>
Badgen: Faster badge rendering, compatible Shields.io URL format. https://badgen.net/badge/<label>/<status>/<color>
Flat Badge: Minimal style badges with a flat design emphasis.

Badge color conventions

Color	Convention	Example use
Green (brightgreen)	Passing / success / healthy	Build passing, tests passing
Red	Failing / error / broken	Build failing, critical issue
Yellow / orange	Warning / unstable / partial	Coverage below threshold, deprecation notice
Blue	Informational / version / neutral	Version number, license type
Gray (inactive)	Inactive / unknown / disabled	CI not configured, status unknown