# Repo Graphics > Generate README hero banners, GitHub social preview cards, feature grids, architecture diagrams, terminal demos, comparison tables and roadmaps as standalone HTML+SVG that match the project's own brand. Use when the user asks to improve a README, make a repo look professional, create a social preview or OG image, design a banner or header for a project, visualise an architecture or pipeline, or says their README looks plain, dated, or like a wall of text. - Skill: `benoshantonybenoy/repo-graphics` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add benoshantonybenoy/repo-graphics` - Raw SKILL.md: https://api.skillmd.com/api/skills/benoshantonybenoy/repo-graphics/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - License: MIT - Author: BenoshAntonyBenoy (https://skillmd.com/u/benoshantonybenoy) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/benoshantonybenoy/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. | The reader is asking | Template | Export | |---|---|---| | What is this? *(top of README)* | `hero-banner` | 1280 × 400 | | Is this worth clicking? *(link preview)* | `social-card` | 1280 × 640 | | What can it do? | `feature-grid` | 1280 × auto | | How do I start? | `quickstart` | 1280 × auto | | Does it actually run? | `terminal-demo` | 1280 × auto | | How does it work inside? | `architecture` | 1280 × 640 | | What happens in what order? | `flow-pipeline` | 1280 × 340 | | Why not the alternative? | `comparison-table` | 1280 × auto | | Is it any good? | `stats-strip` | 1280 × 210 | | Was it worth the change? | `before-after` | 1280 × auto | | Where is it going? | `roadmap-timeline` | 1280 × auto | | What are the basic facts? | `badge-row` | crop to content | **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/.html` to `.github/graphics/.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: ```markdown project-name ``` The `` 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?".