A comprehensive guide and agent instruction set for designing, generating, and deploying animated GitHub profile READMEs that work within GitHub's JavaScript restrictions using pure SVG and CSS/SMIL animations.
username/username).@keyframes, and SMIL.<picture> elements.<script> tags, inline JavaScript, and iframes. Normal web motion libraries (Framer Motion, GSAP, Three.js) cannot execute in a GitHub README.@keyframes CSS and SMIL (<animate>, <animateTransform>) is one animation option; animated GIFs are another, and SVG animation support varies by browser and image context.github-readme-stats, shields.io) that frequently fail when GitHub API rate-limits are reached, self-contained SVGs committed to the profile repository avoid a live third-party generator dependency, though rendering and cache behavior still need testing.A top-tier animated profile combines the following modules stacked vertically in README.md:
┌────────────────────────────────────────────────────────┐
│ 1. HERO BANNER (Dark / Light Auto-Switching via <picture>)
│ - Typing terminal prompt & blinking cursor │
│ - Shimmering gradient name (letter-by-letter reveal)│
│ - Cycling typed role headlines │
│ - Hologram scanline laser sweep │
│ - Live code editor typing real project snippet │
├──────────────────────────┬─────────────────────────────┤
│ 2. SWINGING LANYARD │ 3. 3D TECH ORBIT │
│ - Damped pendulum │ - Satellites orbiting │
│ swing physics │ an atomic core │
│ - Holographic glare │ - Categorized capability │
│ - Avatar & barcode │ matrix │
├──────────────────────────┴─────────────────────────────┤
│ 4. FEATURED ENGINEERING & WORKFLOW PROJECTS (Markdown) │
├────────────────────────────────────────────────────────┤
│ 5. AUTOMATED CONTRIBUTION VISUALIZER │
│ - Snake eating contribution dots (Platane/snk) OR │
│ - 3D Isometric Night Skyline City │
├────────────────────────────────────────────────────────┤
│ 6. VERIFIED TECH BADGES & CONNECT LINKS │
└────────────────────────────────────────────────────────┘Prompt any AI image generator (ChatGPT/DALL-E, Midjourney, Gemini) to generate a clean character illustration. A pure white or transparent background is critical for clean cutouts.
High-quality anime-style digital illustration of a young developer sitting relaxed in a sleek modern ergonomic chair with a dark laptop on their lap, softly smiling at the viewer. Sunglasses resting on head, wearing a cozy dark zip-up hoodie over a tech t-shirt, jeans. Beside them on a small glass-top table: a stack of programming books with spines reading "Python", "Agentic AI", "Docker", "System Architecture"; a takeaway coffee cup with "Code. Coffee. Repeat." written on it; and a small potted desk plant. Pure white background, warm soft rim lighting, clean detailed anime art style, vibrant colors, high resolution, full body in frame.Tip: Generate 3–4 variations and select the one with the cleanest edges and clearest facial crop for the lanyard badge.
Use the master prompts below with an AI coding assistant to create standalone SVG files.
banner.svg & banner-light.svg)viewBox="0 0 1200 480" (responsive, width="100%").#ef4444, #f59e0b, #10b981).OPEN TO COLLABS).$ whoami --verbose.@keyframes with staggered opacities.0.95 opacity).#22d3ee).banner-light.svg):#ffffff to #f8fafc with slate grid.#0284c7 to #7c3aed to #db2777.lanyard.svg)viewBox="0 0 460 380".rx="16").SN-007-PASS).```css
@keyframes lanyardSwing {
0% { transform: rotate(11deg); }
15% { transform: rotate(-8deg); }
30% { transform: rotate(5.5deg); }
45% { transform: rotate(-3.5deg); }
60% { transform: rotate(2deg); }
75% { transform: rotate(-1deg); }
100% { transform: rotate(0deg); }
}
```
±0.8deg).stack.svg)viewBox="0 0 680 380".18s, 26s, 36s).Create automated GitHub Actions to regenerate contribution activity on a daily schedule.
.github/workflows/snake.yml)name: Generate Snake Contribution Animation
on:
schedule:
- cron: "0 0 * * *" # Runs daily at midnight UTC
workflow_dispatch:
push:
branches:
- main
permissions:
contents: write
jobs:
generate:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Generate snake.svg
uses: Platane/snk/svg-only@d8f6715049803e982ee5ff501b6b9b7d5deeb09b
with:
github_user_name: ${{ github.repository_owner }}
outputs: |
dist/github-contribution-grid-snake.svg
dist/github-contribution-grid-snake-dark.svg?palette=github-dark&color_snake=#38bdf8&color_dots=#161b22,#0e4429,#006d32,#26a641,#39d353
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Push snake animation to output branch
uses: crazy-max/ghaction-github-pages@c0d7ff0487ee0415efb7f32dab10ea880330b1dd
with:
target_branch: output
build_dir: dist
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}.github/workflows/profile-3d.yml)name: GitHub 3D Contribution Calendar
on:
schedule:
- cron: "0 18 * * *"
workflow_dispatch:
permissions:
contents: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
with:
persist-credentials: true # Required only for this authorized generated-asset push.
- uses: yoshi389111/github-profile-3d-contrib@f4cf497614310d7b45ab3e000a523e47c524b14f
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
USERNAME: ${{ github.repository_owner }}
- name: Commit & Push
run: |
git config user.name github-actions
git config user.email github-actions@github.com
git add -- profile-3d-contrib
if git diff --cached --quiet; then exit 0; fi
git commit -m "Generated 3D Profile Calendar"
git pushREADME.mdUse HTML <picture> elements for native dark/light mode switching and add cache-busting queries:
<div align="center">
<!-- Responsive Auto-switching Hero Banner -->
<picture>
<source media="(prefers-color-scheme: dark)" srcset="banner.svg?v=1">
<source media="(prefers-color-scheme: light)" srcset="banner-light.svg?v=1">
<img src="banner.svg?v=1" width="100%" alt="Hero Banner">
</picture>
<br><br>
<!-- Lanyard ID Badge & Capabilities Orbit -->
<p align="center">
<img src="lanyard.svg?v=1" width="41%" alt="ID Badge">
<img src="stack.svg?v=1" width="57%" alt="Tech Orbit">
</p>
</div>
---
### ⚡ About Me
> **[Your Role / Identity Headline]**
> [Concise 2-sentence summary of your specialization, experience, and passions].
- 🤖 **Current Focus:** [Core projects or frameworks]
- 🎓 **Education & Mentorship:** [Courses, teaching, or open source curricula]
- 💬 **Ask Me About:** [Key technical domains]
---
### 🚀 Featured Engineering Projects
| Repository | Focus & Capabilities | Tech Stack | Link |
| :--- | :--- | :--- | :---: |
| [**Project 1**](https://github.com/user/project1) | Brief high-impact description of the problem solved. | `Python` `AI` `Docker` | [**Explore Repo →**](https://github.com/user/project1) |
| [**Project 2**](https://github.com/user/project2) | Educational tutorial or platform tool. | `TypeScript` `Playwright` | [**Explore Repo →**](https://github.com/user/project2) |
---
### 🐍 Contribution Activity
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/<USER>/<USER>/output/github-contribution-grid-snake-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/<USER>/<USER>/output/github-contribution-grid-snake.svg">
<img src="https://raw.githubusercontent.com/<USER>/<USER>/output/github-contribution-grid-snake.svg" alt="Contribution Snake" width="100%">
</picture>
</div>
---
### 📫 Connect & Collaborate
<p align="center">
<a href="https://linkedin.com/in/<username>"><img src="https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white" alt="LinkedIn" /></a>
<a href="mailto:<email>"><img src="https://img.shields.io/badge/Email-EA4335?style=for-the-badge&logo=gmail&logoColor=white" alt="Email" /></a>
<a href="https://github.com/<username>"><img src="https://img.shields.io/badge/GitHub-181717?style=for-the-badge&logo=github&logoColor=white" alt="GitHub" /></a>
</p>?v=1 ➔ ?v=2)camo.githubusercontent.com).README.md (banner.svg?v=1). Whenever you edit an SVG, bump the parameter (?v=2).README.md with the bumped version number second.<image href="data:image/png;base64,..." />, always use PNG format.--. CSS inside XML style text still needs escaping or CDATA.&, <, >) or wrap <style> blocks in <![CDATA[ ... ]]>.<clipPath>), ensure height and padding around the text are generous (at least 8–12px padding above and below) so letters like g, y, p, and j are never sliced off.prefers-reduced-motion or static vector viewers).animation-fill-mode alone does not disable motion. Add @media (prefers-reduced-motion: reduce) rules to disable CSS animations; SMIL requires its own static fallback/version.<linearGradient id="bg-grad">), IDs can collide when SVGs are inlined into one document; separate <img> documents isolate them.banner-bg-grad, lanyard-card-grad, orbit-core-grad.<script> tags, event listeners (onclick), and external JavaScript libraries; interactive games or dynamic DOM manipulation within markdown are not supported.Cache-Control headers are served or query parameters are bumped.<feGaussianBlur> with high radius) or deeply nested SMIL loops can increase client CPU and battery usage on mobile devices.contents: write).username/username).banner.svg and banner-light.svg tested locally in both dark and light modes.output branch populated.?v=1) verified on all image links in README.md.@github-presence — Comprehensive README structure, SEO, and discoverability.@github-actions — Building and debugging automated CI/CD workflows.The SVG prompts are design specifications, not bundled working assets. Test through the hosted README image path, not only a locally opened SVG. Keep descriptive alt text and a static readable fallback. Do not fabricate clearance, employment or contribution claims. The city example writes to its current branch and may be blocked by protection; publish generated assets through an approved branch/PR workflow instead of weakening protection. Review each pinned third-party action and its output paths before granting write access; a pinned SHA alone is not a safety audit.