README Formatting (Constructive Standard)

Format README files with consistent Constructive branding including centered header logos and appropriate badges for different package types.

When to Apply

Use this skill when:

Creating a new npm, pnpm, or pgpm package
Publishing a module to npm or pgpm registry
Asked to add header images or badges to a README
Standardizing README formatting across packages
A README is missing the Constructive logo header

Header Logo

All Constructive packages should include a centered logo at the top of the README, immediately after the package title.

Standard Header (Most Packages)

# package-name

<p align="center" width="100%">
  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
</p>

Root Repository Header

For root-level README files (monorepo roots), use the filled logo with smaller height:

# Repository Name

<p align="center" width="100%">
  <img height="150" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/logo.svg" />
</p>

Badges

Badges appear in a centered paragraph below the logo. Include badges based on package type and visibility.

Badge Types

Badge	When to Use	Example
CI Status	Public repos with GitHub Actions	Shows build status
License	All public packages	MIT, Apache-2.0, etc.
npm Version	npm/pnpm packages published to registry	Shows current version
Downloads	Optional, for popular packages	Shows download count

Badge Templates

CI Status Badge:

<a href="https://github.com/{org}/{repo}/actions/workflows/ci.yml">
  <img height="20" src="https://github.com/{org}/{repo}/actions/workflows/ci.yml/badge.svg" />
</a>

MIT License Badge:

<a href="https://github.com/{org}/{repo}/blob/main/LICENSE">
  <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
</a>

npm Version Badge (from package.json in repo):

<a href="https://www.npmjs.com/package/{package-name}">
  <img height="20" src="https://img.shields.io/github/package-json/v/{org}/{repo}?filename=packages%2F{package-folder}%2Fpackage.json"/>
</a>

npm Version Badge (from npm registry):

<a href="https://www.npmjs.com/package/{package-name}">
  <img height="20" src="https://img.shields.io/npm/v/{package-name}.svg"/>
</a>

Downloads Badge (optional):

<a href="https://www.npmjs.com/package/{package-name}">
  <img height="20" src="https://img.shields.io/npm/dm/{package-name}.svg"/>
</a>

Complete Badge Section

<p align="center" width="100%">
  <a href="https://github.com/{org}/{repo}/actions/workflows/ci.yml">
    <img height="20" src="https://github.com/{org}/{repo}/actions/workflows/ci.yml/badge.svg" />
  </a>
  <a href="https://github.com/{org}/{repo}/blob/main/LICENSE">
    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
  </a>
  <a href="https://www.npmjs.com/package/{package-name}">
    <img height="20" src="https://img.shields.io/npm/v/{package-name}.svg"/>
  </a>
</p>

Package Type Guidelines

npm/pnpm Packages (Published to npm)

Include: Logo + CI badge + License badge + Version badge

# @scope/package-name

<p align="center" width="100%">
  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
</p>

<p align="center" width="100%">
  <a href="https://github.com/constructive-io/repo/actions/workflows/ci.yml">
    <img height="20" src="https://github.com/constructive-io/repo/actions/workflows/ci.yml/badge.svg" />
  </a>
  <a href="https://github.com/constructive-io/repo/blob/main/LICENSE">
    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
  </a>
  <a href="https://www.npmjs.com/package/@scope/package-name">
    <img height="20" src="https://img.shields.io/npm/v/@scope/package-name.svg"/>
  </a>
</p>

Package description here.

pgpm Packages (PostgreSQL Modules)

Include: Logo + CI badge + License badge (no npm version badge)

# @pgpm/module-name

<p align="center" width="100%">
  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
</p>

<p align="center" width="100%">
  <a href="https://github.com/constructive-io/repo/actions/workflows/ci.yml">
    <img height="20" src="https://github.com/constructive-io/repo/actions/workflows/ci.yml/badge.svg" />
  </a>
  <a href="https://github.com/constructive-io/repo/blob/main/LICENSE">
    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
  </a>
</p>

Module description here.

Internal/Private Packages

Include: Logo only (no badges needed)

# package-name

<p align="center" width="100%">
  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
</p>

Package description here.

Packages with Custom License

<p align="center" width="100%">
  <a href="https://github.com/constructive-io/repo/actions/workflows/ci.yml">
    <img height="20" src="https://github.com/constructive-io/repo/actions/workflows/ci.yml/badge.svg" />
  </a>
</p>

Complete README Template

# @scope/package-name

<p align="center" width="100%">
  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
</p>

<p align="center" width="100%">
  <a href="https://github.com/{org}/{repo}/actions/workflows/ci.yml">
    <img height="20" src="https://github.com/{org}/{repo}/actions/workflows/ci.yml/badge.svg" />
  </a>
  <a href="https://github.com/{org}/{repo}/blob/main/LICENSE">
    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
  </a>
  <a href="https://www.npmjs.com/package/@scope/package-name">
    <img height="20" src="https://img.shields.io/npm/v/@scope/package-name.svg"/>
  </a>
</p>

Brief description of what the package does.

## Installation

\`\`\`bash
pnpm add @scope/package-name
\`\`\`

## Usage

\`\`\`typescript
import { something } from '@scope/package-name';
\`\`\`

## API

Document the main exports and functions.

## License

MIT (or appropriate license)

Checklist

When formatting a README, verify:

Package title is at the top (h1)
Logo is centered below the title
Logo uses correct URL (outline-logo.svg for packages, logo.svg for roots)
Logo height is appropriate (250px for packages, 150px for roots)
Badges are in a separate centered paragraph below logo
Badge links point to correct URLs
Version badge uses correct package name (with scope if applicable)
License badge matches actual license in package
CI badge points to correct workflow file

Common Mistakes

Missing logo: Always add the header logo
Wrong logo URL: Use the raw.githubusercontent.com URL, not a relative path
Badges in wrong order: CI, then License, then Version
Missing badge links: Each badge image should be wrapped in an anchor tag
Incorrect package name in version badge: Must match exactly what's published to npm

References

Logo assets: https://github.com/constructive-io/constructive/tree/main/assets
Shields.io badges: https://shields.io/
Related skill: pnpm-publishing for publishing workflow
Related skill: pgpm (references/publishing.md) for pgpm module publishing

readme-formatting