readme-forge-design git:20261102.03ea076A

Immutable. This exact content never changes and is served at /api/v1/blob/ff18134d6b7d81d0.

---
name: readme-forge-design
description: Optional design layer for readme-forge. Designs whole READMEs as a set of SVG cards from one JSON spec (page kit — terminal-window hero, contact dock, numbered section headers, about card, tech-stack grid with brand icons, project and achievement cards, themed stats, footer; keynote style, light + dark), and generates self-contained animated SVG banners (20 styles, including WebGL-shader looks rebuilt in SVG — spinning vortex, edge light beam, voronoi shatter, RGB prism blinds — plus ShaderGradient grain, landing-page spotlight, synthwave, isometric, orbit, ribbon), footers, dividers and clickable CTA buttons in dark and light variants, and builds GitHub personal and organization profile READMEs from 19 archetypes with tested widgets and profile Actions. Use when the user asks for a README banner/header/footer, "make my README look amazing / professional", a full README redesign, a card-style or keynote-style README, CTA buttons, or a GitHub profile README. For the README's facts, commands and accuracy, use the core readme-forge skill.
---

# readme-forge-design

Make READMEs and GitHub profiles look designed, without external services: every asset is an SVG committed to the repo.

Skill directory: `SKILL_DIR` = the folder containing this file. Scripts are stdlib-only Python 3.8+.

**Division of labour.** This skill owns the look. The core `readme-forge` skill owns the facts: it writes project READMEs from the code and checks every command, env var and path with `verify_readme.py`. When you design a project README, run the core skill's fact-gathering and verification first, or keep the existing text untouched. Scoring (`score_readme.py`) and link checks (`check_links.py`) also come from the core skill; if it isn't installed, tell the user in one line and skip those steps.

| User wants | Mode | Read first |
|---|---|---|
| The whole README designed: every section as a card, "professional", "like this one" (a card/keynote-style example) | **K. Page kit** | `references/page-kit.md` |
| Banner / header / footer / CTA buttons only | **G. Design** | `references/design.md` |
| Personal GitHub profile (`username/username` repo) or org profile (`.github/profile/README.md`) | **B. Profile** (offer K for a fully designed one) | `references/profile-readme.md`, `references/widgets.md` |

## Mode K — Page kit (whole README as cards)

Read `references/page-kit.md` first.
1. Gather real content. Profile: the batched interview from `references/profile-readme.md`. Project: run the core skill's fact-gathering; commands and install steps stay in `markdown` blocks so `verify_readme.py` can check them.
   **If the user pasted a sample README** (theirs or someone else's), map each of its patterns with the "Learning from a sample README" table in page-kit.md: typing banner → hero `roles`, YAML about-me → `code`, portrait → `portrait`, badge wall → `certs`, project table → `projects` with `links`, LeetCode/Codeforces → `stats`. Take the layout, never the content, and drop widgets whose hosts are dead.
2. `python SKILL_DIR/scripts/make_page.py --init profile|project > page.json`. Fill every `{{…}}` from that content and delete fields or blocks with no data (the script refuses to run with placeholders left). Never invent metrics, awards or descriptions. Choose the theme from the brand (page-kit.md rule 4), or pass `accents` to match a logo.
3. `python SKILL_DIR/scripts/make_page.py --spec page.json --preview preview.html` writes every card (light + dark) and the README. Open the preview, check both themes for clipped text, shorten copy that the script had to shrink a lot, and re-run.
4. Score with the core skill (`score_readme.py`, `--profile` for profiles) and `check_links.py` when network is allowed. Don't commit `preview.html`.
5. Tell the user what was written, where it goes, and any setup (the snake workflow; stats cards are a shared public instance).

## Mode G — Design (header, footer, banners)

Read `references/design.md` first.
1. Choose the header pattern (centered stack / minimal / splash / profile hero) and a banner style + palette from the style table (project type, brand colour, audience). If it isn't obvious, generate 2–3 options and show the user.
2. Generate the assets (dark + light, self-contained, committed to the repo):
   ```bash
   python SKILL_DIR/scripts/make_banner.py --style <style> [--palette <p>] [--accent "#HEX"] [--logo <file>] --title "<name>" --subtitle "<pitch ≤ 12 words>" [--tag "<category>"] --out .github/assets
   python SKILL_DIR/scripts/make_banner.py --kind footer --style <minimal|wave|vortex> --title "<credit line>" --out .github/assets
   python SKILL_DIR/scripts/make_banner.py --kind divider --style <aurora|beam> --out .github/assets
   ```
   `python SKILL_DIR/scripts/make_banner.py --list` prints every style and palette. For profiles, put the assets in `assets/`. For Hugging Face, use `#hf-dark-mode-only` / `#hf-light-mode-only` instead of `<picture>`.
3. Pass `--href <url>` so the printed snippet is already wrapped in a link, and paste it exactly as printed. Never type `<a href="…"><picture>` on one line with the `<source>` on the next: GitHub empties that `<picture>`, so the dark variant never shows and the click opens the SVG file. Then put the pitch, badges (one style, palette colour) and link row below it, as in design.md §2.
   **If the project has a logo** (look for `logo.*`, `icon.*`, `assets/brand/*`, or ask), pass `--logo`. It is embedded in the SVG (no external request). Spotlight centres it above the title, vortex puts it in the eye of the vortex, and other styles place it on the left. Use a transparent PNG about 320 px wide or an SVG; a logo with a white box looks wrong on dark banners. Pick a palette (or `--accent`) that matches the logo's colours.
   **Shader looks:** `vortex` (default `inferno` palette: warm black, red-orange blades, condensed serif caps), `beam` (light racing around the edge over a nebula), `shatter` (voronoi glass), `prism` (RGB-split blinds with a swipe). These use CSS animation only, so they stop for visitors with reduced motion. For a **ShaderGradient** look, use `--style shader --palette halo|pensive|interstella|universe|mandarin|nighty`. For a **landing-page** feel, use the spotlight hero + CTA buttons (`--kind button`) from design.md §10 and `templates/design/hero-landing.md`, optionally repeating the CTA before the footer with `templates/design/cta-section.md`.
4. End with a footer (design.md §3): license line, credit, back-to-top, plus the footer SVG for polished projects and profiles.
5. Run the core skill's `score_readme.py` and fix the `design` findings (missing dark variant, mixed badge styles, external fonts in SVGs, oversized assets).
6. **Visual check:** if a browser is available, render the README or the SVGs and look at both themes. At minimum, open each SVG once to confirm the title is fully visible.

Never: hotlink a third-party banner by default, put the only copy of the pitch inside an image, use more than 2 animations above the fold, or animate the text in from blank.

## Mode B — Profile README

1. Read `references/profile-readme.md`. Collect (batch in one question): GitHub username, name/role/one-liner, current focus, top skills (or derive from their public repos if they allow), socials, preferred **archetype** (minimal · stats dashboard · creative/animated · code-mode · data/ML · student · OSS maintainer · retro · badges wall · Actions-dynamic · org · game mode · typing · anime/art · fancy fonts · descriptive · simple-but-innovative · icons · just an image; if they name an awesome-github-profile category, use the mapping in profile-readme.md), and dark-mode preference.
2. Start from `templates/profile/<archetype>.md`. Replace every `{{PLACEHOLDER}}`; delete sections with no data rather than leaving placeholders. Generate the profile hero banner and footer with `make_banner.py` (Mode G) in the user's accent colour. Offer the 3D contribution calendar (`workflows/profile-3d.yml`) for profiles that want a 3D visual.
3. Widgets: pick from `references/widgets.md`. Rules: ≤ 4 dynamic cards; use `<picture>` or theme params for dark/light; give each a descriptive alt; add the self-host / Actions fallback comment for stats cards; skill icons only for skills the user really uses (≤ 15). Never invent stats, employers, projects or links: they come from the user or their public profile.
4. If the archetype needs automation (snake, latest blog posts, WakaTime, metrics, the tic-tac-toe game), also write the workflow from `templates/profile/workflows/` (the game also needs `templates/profile/game/tictactoe.py` at `.github/scripts/`) and tell the user which secrets/settings to add.
   For **fancy fonts**, generate every styled string with `python SKILL_DIR/scripts/fancy_text.py "TEXT" --style <style>`; never type the Unicode yourself.
5. Run `score_readme.py --profile` and `check_links.py` from the core skill (if network allowed) and fix failures.
6. Tell the user exactly where it goes: repo named exactly like their username, public, `README.md` at root (org: `.github` repo → `profile/README.md`).

## Learning loop — adapt to this user's taste

If the core skill is installed, use its `scripts/learn.py` (see "Learning loop" in its SKILL.md) for design choices too. Skip it if the user said not to learn.

1. Before choosing, run `learn.py observe README.md`, then `learn.py suggest --repo <path> --context mode=<design|profile|page-kit> --decision banner.style:<your first choice>,<2–4 fitting alternatives> --decision banner.palette:<first choice>,<alternatives>`. Put your own best choice first: it stays the pick until there is evidence. Add `--decision profile.archetype:…` for profiles and `--decision page.theme:…` for the page kit.
2. Use each `pick` and follow every saved `preferences` line, unless the user asks for something else now. Record rejections and praise with `learn.py reward banner.style=<style> --value 0|1`.
3. After generating, snapshot the choices with a `file:` marker, so the script can tell later whether the user kept or replaced the asset:
   ```bash
   python <core SKILL_DIR>/scripts/learn.py snapshot README.md --context mode=design --choice banner.style=beam@file:.github/assets/header-dark.svg --choice banner.palette=ghost@file:.github/assets/header-dark.svg
   ```

## Final message to the user

Keep it short: which assets and files you wrote, how to preview both themes, and any setup they must do (Actions secrets, making the profile repo public).