v1.0.0 to v1.0.0

- description: Add beautiful shadcn/ui-styled README badges, charts, and header banners to projects using shieldcn, and build entire READMEs with the visual README Studio. Use when adding badges, shields, status indicators, star-history/download charts, or header banners to README files, docs, or markdown, or when building/generating a README. Triggers include "add badges", "add shields", "readme badges", "npm badge", "GitHub stars badge", "CI badge", "star history chart", "readme header", "readme banner", "build a readme", "readme builder", "readme generator", "github readme tool", "shieldcn", or any request to add project status badges, charts, or headers to documentation.

- Add beautiful [shadcn/ui](https://ui.shadcn.com)-styled badges to READMEs and docs using [shieldcn](https://shieldcn.dev) — a free, open-source shields.io alternative.

- ## Badge URL format

- https://shieldcn.dev/{provider}/{...params}.svg → SVG (default, for READMEs)

- https://shieldcn.dev/{provider}/{...params}.png → PNG

- https://shieldcn.dev/{provider}/{...params}.json → raw data

- ## Markdown pattern

- <!-- or without link -->

- ## Providers & endpoints

- | Provider | Endpoint | Example |

- |----------|----------|---------|

- | npm version (tag) | `/npm/v/{package}/{tag}` | `/npm/v/next/canary` |

- | npm downloads/wk | `/npm/dw/{package}` | `/npm/dw/react` |

- | npm downloads/mo | `/npm/dm/{package}` | `/npm/dm/react` |

- | npm downloads/yr | `/npm/dy/{package}` | `/npm/dy/react` |

- | npm scoped | `/npm/v/@scope/pkg` | `/npm/v/@types/node` |

- | PyPI downloads/mo | `/pypi/dm/{package}` | `/pypi/dm/flask` |

- ### GitHub

- Both formats work: `/github/{topic}/{owner}/{repo}` or `/github/{owner}/{repo}/{topic}`

- |-------|----------|---------|

- | Stars | `/github/stars/{owner}/{repo}` | `/github/stars/vercel/next.js` |

- | Forks | `/github/forks/{owner}/{repo}` | `/github/forks/vercel/next.js` |

- | License | `/github/license/{owner}/{repo}` | `/github/license/vercel/next.js` |

- | Release | `/github/release/{owner}/{repo}` | `/github/release/vercel/next.js` |

- | CI status | `/github/ci/{owner}/{repo}` | `/github/ci/vercel/next.js` |

- | Issues | `/github/issues/{owner}/{repo}` | `/github/issues/vercel/next.js` |

- | Open PRs | `/github/open-prs/{owner}/{repo}` | `/github/open-prs/vercel/next.js` |

- | Contributors | `/github/contributors/{owner}/{repo}` | `/github/contributors/vercel/next.js` |

- | Last commit | `/github/last-commit/{owner}/{repo}` | `/github/last-commit/vercel/next.js` |

- | Watchers | `/github/watchers/{owner}/{repo}` | `/github/watchers/vercel/next.js` |

- | Downloads | `/github/dt/{owner}/{repo}` | `/github/dt/vercel/next.js` |

- | Dependabot | `/github/dependabot/{owner}/{repo}` | `/github/dependabot/vercel/next.js` |

-

- CI supports `?workflow=name&branch=main` query params.

-

- ### Social

-

- | Provider | Endpoint | Example |

- |----------|----------|---------|

- | Discord by invite | `/discord/members/{inviteCode}` | `/discord/members/nextjs` |

- | YouTube subs | `/youtube/subscribers/{channelId}` | `/youtube/subscribers/UCxxxxxx` |

-

- ### Code quality

-

- | Provider | Endpoint | Example |

- |----------|----------|---------|

-

- ### Agent skills (skills.sh)

-

- Addressed as `{owner}/{repo}/{skill}` — the GitHub repo (skills.sh `source`) plus the skill slug.

-

- | Badge | Endpoint | Example |

- |-------|----------|---------|

- | Trending rank | `/skills/trending/{owner}/{repo}/{skill}` | `/skills/trending/vercel-labs/agent-skills/vercel-react-best-practices` |

- | Hot rank | `/skills/hot/{owner}/{repo}/{skill}` | `/skills/hot/vercel-labs/agent-skills/vercel-react-best-practices` |

- ### Custom badges

- |------|----------|---------|

- | HTTPS endpoint | `/https/{hostname}/{path}` | Proxy any JSON endpoint |

- ## Query parameters

- Append to any badge URL as `?key=value&key2=value2`.

- |-------|--------|---------|-------|

- | `mode` | `dark`, `light` | `dark` | Color mode |

- | `split` | `true`, `false` | `false` | Two-tone label/value split |

- | `logo` | SimpleIcons slug, `ri:Name`, `false` | auto | Icon source |

- | `logoColor` | hex (no `#`) | auto | Icon color |

- | `color` | hex (no `#`) | — | Background color |

- | `labelColor` | hex (no `#`) | — | Label side bg (split mode) |

- | `theme` | `zinc`, `slate`, `blue`, `green`, `rose`, `orange`, `violet` | — | Color theme |

- | `font` | `inter`, `geist`, `geist-mono` | `inter` | Font family |

- | `statusDot` | `true`, `false` | auto for CI | Show status indicator dot |

- ## Common recipes

- ### Typical README badge row

- ```md

- <p align="center">

- <a href="https://www.npmjs.com/package/{pkg}"><img src="https://shieldcn.dev/npm/{pkg}.svg" alt="npm" /></a>

- <a href="https://github.com/{owner}/{repo}/stargazers"><img src="https://shieldcn.dev/github/stars/{owner}/{repo}.svg" alt="stars" /></a>

- <a href="https://github.com/{owner}/{repo}"><img src="https://shieldcn.dev/github/license/{owner}/{repo}.svg" alt="license" /></a>

- <a href="https://github.com/{owner}/{repo}/actions"><img src="https://shieldcn.dev/github/ci/{owner}/{repo}.svg" alt="CI" /></a>

- </p>

- ```

- ### Secondary variant (lighter)

- ```md

- 

- ### Branded variant (brand-colored bg)

- 

- ### Split badge (two-tone)

-

- ```md

- 

- ```

- ### Light mode

- ```md

- 

- ```

- ### Custom icon

- ```md

- 

- 

- ### No icon

-

- ```md

- 

- ```

- ## Charts

- shieldcn also renders line charts (inlined SVG/PNG, styled like the badges). Use them for star history, issues over time, or download trends.

- ```

- https://shieldcn.dev/chart/github/stars/{owner}/{repo}.svg → star-history chart

- https://shieldcn.dev/chart/github/issues/{owner}/{repo}.svg → issues over time

- https://shieldcn.dev/chart/npm/{package}.svg → npm downloads

- https://shieldcn.dev/chart/json.svg?values=10,25,40,30,60 → inline JSON data

- Markdown: ``

-

- Query params: `theme`, `font`, `color`, `fill`, `area`, `width`, `height`, `title`, `icon`, `mode`.

-

- ## Headers

- Repository header banners (logo + title + tagline) from a single image URL — great at the top of a README.

- ```

- https://shieldcn.dev/header/{preset}.svg?title=Acme&subtitle=A%20delightful%20toolkit

- Presets: `surface`, `gradient`, `dots`, `grid`, `graph`, `glow`, `transparent`. Query params: `logo`, `theme`, `size`, `align`, `font`, `border`, and `image=<url>` for a photo background (any image or Unsplash URL, fetched and inlined, with an auto scrim tunable via `overlay`/`tint`).

- Center a header at the top of a README:

- ```md

- <p align="center">

- <img src="https://shieldcn.dev/header/gradient.svg?title=Acme&subtitle=A%20delightful%20toolkit" alt="Acme" />

- </p>

- ```

- ## README Studio (visual builder)

- For building an entire README visually (not just one badge), point the user to the free README Studio: https://shieldcn.dev/studio

- It is a Figma-style editor — a document of reorderable blocks (Text/Markdown, Header, Badges, Chart, Table, Image), a live preview, and a property inspector — that exports clean GitHub-flavored Markdown. It has an "Adaptive" toggle that exports badges/headers/charts as GitHub `<picture>` elements that follow the reader's light/dark theme. Suggest it when the user wants to compose, redesign, or generate a whole README rather than add a single badge.

- ## Rules

- 1. Always use `.svg` for markdown images (best quality, smallest size)

- 2. Use `<a>` wrapper to make badges clickable links

- 3. Use `<p align="center">` to center badge rows in GitHub READMEs

- 4. Replace `{owner}`, `{repo}`, `{package}` with actual values — never leave placeholders

- 5. Default variant (`default`) works on both light and dark GitHub themes

- 6. Icons are auto-resolved per provider — only set `?logo=` to override

- 7. For npm scoped packages, use the full scope: `/npm/v/@scope/package`

- 8. Prefer `variant=secondary` for subtle badge rows

- 9. Keep badge rows to 3–6 badges for readability

- 10. Link each badge to its relevant page (npm registry, GitHub stars page, etc.)

- Full documentation: https://shieldcn.dev/docs

- API reference: https://shieldcn.dev/docs/api-reference

- Badge builder: https://shieldcn.dev (interactive UI)

- README Studio (visual README builder): https://shieldcn.dev/studio

- Studio docs: https://shieldcn.dev/docs/studio

- Charts docs: https://shieldcn.dev/docs/charts

- Headers docs: https://shieldcn.dev/docs/headers