---
name: profile-cover
description: >
  Design a GitHub profile README (the special username/username repo) as
  an editorial page. Use when the user wants their GitHub profile
  designed, a profile README, a personal masthead, or to replace widget
  and badge clutter. Kerned serif mastheads as path-outlined SVGs that
  render through GitHub's proxy with zero external resources, light and
  dark pairs, GitHub-native markdown for everything that should be a
  link. No image model, no third-party stats services, nothing that can
  show a broken image.
license: MIT
---

# profile-cover

You design a GitHub profile README as an editorial page. Display type
is generated by the bundled scripts as path-outlined SVG, so it renders
identically everywhere. Everything that should be clickable stays
GitHub-native markdown. Nothing depends on a third-party service, so
nothing on the profile can 503 or rate-limit into a broken image.

## Setup

The typography scripts need two libraries:

```sh
pip install fonttools uharfbuzz
```

## Workflow

1. **Interview.** Ask who the profile is for and what one sentence it
   must say. Get: display name, an eyebrow line (place, role, cadence),
   a tagline, 3-6 items of selected work with real links, and one link
   destination per item. Never invent numbers, dates, or claims.
2. **Pick an archetype** and read exactly ONE reference:
   - `references/archetype-ledger.md`, a dense shipping ledger for
     people who release often
   - `references/archetype-buildlog.md`, a dated build log for
     students and learners in public
   - `references/archetype-stewardship.md`, a centered frontispiece
     for maintainers of one serious thing
3. **Generate the SVG strips** with the bundled script (do not
   hand-write display type):
   `python3 scripts/make_masthead.py masthead --name ... --accent-light ... --accent-dark ... --out <base>`
   and one `section` call per section head. The archetype reference
   gives the exact flags.
4. **Assemble README.md** following the archetype's markdown skeleton.
   SVGs go in `<picture>` light/dark pairs. Lists, tables, and links
   are plain markdown. Never use inline `style=` attributes; GitHub
   strips them.
5. **Check.** `python3 scripts/check_profile.py README.md *.svg` and
   fix every FAIL. Two repair rounds, then report honestly.
6. **Deliver.** The files go in the user's `username/username` repo.
   Tell the user to review on github.com in both themes before
   sharing.

## Hard rules

- Accent colors come in pairs, one for light and one for dark, both
  passing 4.5:1 against their page (#FFFFFF / #0D1117). The checker
  verifies.
- SVG backgrounds stay transparent so GitHub's own chrome shows
  through. No painted slabs.
- Labels never smaller than 12.5px; mobile scales a 900px strip to
  about 40 percent.
- No decaying copy ("this week", week numbers, live counts) unless the
  user also installs a scheduled Action that refreshes it.
- No third-party dynamic images (stats cards, badges, counters). The
  whole point is a profile that cannot break.
- The credit line is optional. If the user wants one, it links to this
  repo; never add it silently.
- Body copy is flush-left markdown; SVG content starts at x=0 so the
  column aligns. This is the layout rule that keeps the page editorial.

## What this is not

- Not a stats dashboard. If the user wants live numbers, recommend
  keeping one github-readme-stats card below the fold, and say why the
  masthead stays static.
- Not a website. It is a README that respects GitHub's renderer.