Repo Graphics

repo-graphics

Turn a plain README into one that looks considered — without opening a design tool, installing anything, or inventing a brand from scratch.

Output is always a standalone HTML file: inline styles, inline SVG, system fonts, no network calls. It opens from file://, renders identically in CI, and stays editable by anyone with a text editor five years from now.

When to use this

Trigger on any of these, whether or not the user names the skill:

• "make my README look better / more professional / less dated"
• "create a banner / header / hero / cover image for this repo"
• "I need a social preview / OG image / link preview"
• "diagram the architecture" · "show how the pipeline works"
• "compare us to " · "add a roadmap"
• a repo is being prepared for launch, Show HN, or a release announcement

Do not use this for application UI, marketing sites, slide decks, or logo design. Those want a real design process, not a template. Say so and stop.

The five-minute path

If the user just wants something better than what they have, do this and do not ask more questions:

1. Find the brand (§Branding). If there is no site and no logo, use the neutral system as-is — it is already designed and it is not a placeholder.
2. Build a hero banner and a social card. Those two carry 90% of the impression. Everything else is optional.
3. Write files to .github/graphics/, export PNGs, and hand back the exact Markdown to paste.

Only go wider when the user asks, or when the README obviously needs it — a 30-line feature list wants a feature-grid, an unexplained system wants an architecture.

Choosing the graphic

Match the reader's question to the template. Read references/catalog.md for the full spec of each, including exact export sizes and the slots to fill.

One graphic per question. A README with five graphics answering the same question is worse than one with none — the reader stops trusting any of them. Three is a healthy maximum for most repos.

Branding

Order of preference. Stop at the first one that works.

1. A live URL. Fetch it, read the CSS custom properties and computed styles, and take: the most-used non-neutral colour as --rg-accent, the body colour as --rg-fg, the page background as --rg-bg, and the dominant border-radius as --rg-radius.
2. A logo or screenshot. Sample the dominant non-neutral colour for the accent. Keep every neutral from the default system — logos rarely carry a usable full palette, and inventing one produces mud.
3. An existing repo colour. A README badge colour or docs theme.
4. Nothing. Use the defaults. They are a designed neutral system, not a fallback, and shipping them is a legitimate outcome.

Then rewrite the :root block in each generated file. Every template inlines its own copy of the tokens — that is what makes the files portable, so you must apply the palette to each file you generate, not to a shared stylesheet. templates/_tokens.css is the canonical reference for what each token means.

Full extraction procedure, including the dark-theme derivation and the contrast gate: references/brand.md.

Hard rules

These are what separate this output from generic AI design. Do not relax them because a user asks for something "more exciting" — offer a different template instead.

Colour

• Exactly one accent. Everything else is a neutral from the token set.
• The accent marks emphasis. It is never a background gradient behind text, never a rainbow, never two accents "for contrast".
• Body text must clear 4.5:1 against its background in both themes; large text and non-text marks must clear 3:1. Verify before delivering — scripts/validate.mjs checks every generated file.

Type

• Only the sizes in the scale. No arbitrary values between steps.
• One typeface family for text, one mono. System stacks only — a webfont means a network call, which breaks file:// and CI rendering.
• Headings get negative tracking (-.02em to -.036em). Large type set at default tracking is the single most common tell of untouched output.

Structure

• 1px hairline borders carry structure. Shadows are a last resort, never decorative, never coloured.
• Grids are gapless with shared hairlines — cells belong to one object rather than floating as disconnected cards.
• Whitespace is the main tool. When something looks wrong, the answer is almost always more padding, not more colour.

Never

• Emoji as bullets, icons, or section markers.
• Purple-to-pink gradients, glassmorphism, or a glow on anything.
• Stock illustration, 3D blobs, or isometric people.
• Fabricated numbers, benchmarks, logos, or testimonials. If the user has no real metrics, use a different template — do not invent plausible ones.

Honesty constraints

This skill produces material that makes claims on the user's behalf in public. Hold the line on these even under pressure:

• Never fabricate a metric. No invented benchmarks, download counts, user numbers, or "trusted by" logos. If stats-strip has nothing real to show, say so and skip it.
• Never invent terminal output. Run the command and paste what it printed. A reader who copies the command and sees something different is gone.
• before-after must use a real before. Their actual old README, not a strawman built to lose.
• comparison-table must concede rows. Name real alternatives, and let them win where they genuinely win. An all-ticks column is read as an advert and discounts everything else on the page.
• Never imply an affiliation or endorsement that does not exist — no company logos, no "as used by", no fake sponsor tier.

Producing a graphic

1. Copy the template from templates/<name>.html to .github/graphics/<name>.html.
2. Rewrite the :root and :root[data-theme="dark"] blocks with the project's tokens.
3. Fill every data-slot element. Delete slots you have no real content for — an empty slot rendering as placeholder text is worse than a shorter graphic.
4. Check the text actually fits. Long repo names overflow the hero at 66px; drop a step on the type scale rather than shrinking to an off-scale size.
5. Export. See references/export.md — npm run render if the user has Playwright, otherwise tell them to open the file and screenshot the bordered region, which is exactly the export area.
6. Hand back the Markdown snippet, using the theme-aware form:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset=".github/graphics/hero-banner-dark.png">
  <img alt="project-name" src=".github/graphics/hero-banner.png" width="100%">
</picture>

The <picture> element is the only way to serve a dark-mode README image on GitHub. Always export both themes and always emit this form — a light banner on a dark README is the exact problem this skill exists to fix.

Reference files

Read these on demand, not up front:

• references/catalog.md — every template: slots, sizes, editorial rules
• references/brand.md — extraction procedure, dark derivation, contrast gate
• references/export.md — PNG/SVG export, retina, CI, cropping

assets/gallery.html renders all twelve at once — open it when the user asks "what can this make?".