GitHub Wrapped (Single-file HTML, Verifiable Data)

This skill generates a GitHub “Year in Review / Wrapped” as a single self-contained HTML file with a Bilibili-style narrative (scroll/page scenes, cinematic transitions, share card). The non-negotiable requirement is verifiability: every number must be traceable to saved

gh api

raw responses committed alongside the report.

Non-negotiables

• No fabricated data: if GitHub APIs cannot provide a metric, show

  —

  and explain the limitation in-page.
• Save raw API responses: the report is invalid without a

  raw/

  folder containing the original JSON (and the GraphQL queries used).
• Ship one

  .html

  : no runtime

  gh

  calls; embed a dataset into the HTML.
• External CDNs are optional (fonts/icons/screenshot libs/music) but must never break core navigation/rendering if they fail to load.
• Build step-by-step: start with a tiny scaffold (≤ ~400 LOC) and iterate towards a 5k–10k LOC finished report; never try to ship the full “final” file in one pass.

What to ask the user first

• YEAR

  (default: current year)

• USER

  (default:

  gh api user --jq .login

  )
• Output language for the page copy (Chinese is usually preferred for CN users; this doc stays English)
• Timezone (default:

  Asia/Shanghai

  for CN users)
• Whether to enable a music widget (autoplay may be blocked; must have a user-gesture fallback)

Recommended layout

data/github-wrapped-$YEAR/
  raw/                  # verifiable gh API responses (JSON)
  processed/             # dataset.json derived from raw/
frontend/standalone/
  github-wrapped-$YEAR.html

Pipeline (raw → dataset → single HTML)

1) Collect raw JSON with

gh api

(always paginate)

Pagination rules:

• GraphQL:

  --paginate --slurp

• REST:

  --paginate

Minimum raw set (recommended filenames):

• raw/user.json

  (profile, createdAt)

• raw/contributions.json

  (GraphQL

  contributionsCollection(from,to)

  )

• raw/user_repos.json

  (REST repos list; stars/forks are snapshots)

• raw/starred_repos_pages.json

  (GraphQL starred repos ordered by

  STARRED_AT

  , includes topics/language)

• raw/prs_${YEAR}_pages.json

  (GraphQL Search: merged PRs in the year; additions/deletions)

• raw/contributed_repos_pages.json

  (GraphQL

  repositoriesContributedTo

  )

• raw/events_90d.json

  (optional; REST events; 90-day limit; only for best-effort easter eggs)

Bundled templates (open only what you need):

• scripts/collect_raw.sh

• scripts/queries/*.graphql

• references/data_sources.md

• references/single_file_engineering.md

2) Build a deterministic dataset (Python, no guessing)

Write a builder that reads only

raw/*.json

and outputs

processed/dataset.json

:

• Deterministic: same raw input → same dataset output.
• Transparent: write limitations into

  meta.dataProvenance.notes[]

  .
• Stable for rendering: keep optional fields nullable; avoid breaking changes.

Template:

scripts/build_dataset_template.py

Schema guidance:

references/dataset_schema.md

For larger analysis recipes (stars-by-month scatter points, timezone-safe hour buckets, holiday detection, category heuristics), see

cookbook/python/

.

3) Embed

dataset.json

into the HTML (no runtime fetch)

Your HTML must contain a stable anchor:

<script id="dataset" type="application/json">{}</script>

Embed rules:

• Always escape

  <

  as

  \u003c

  before writing into the HTML.
• If the dataset block is missing/corrupted, the embed script should fail loudly (or repair it).
• The page must show a visible overlay if dataset parsing fails (avoid “cover only, buttons dead”).

Template:

scripts/embed_dataset_into_html_template.py

Step-by-step delivery (400 LOC → 10k LOC)

Single-file cinematic reports get long fast. To stay correct and maintainable, ship in iterations:

• Iteration 0 (contract): agree on a minimal

  dataset.json

  schema and render placeholders (show

  —

  for missing fields).
• Iteration 1 (≤ 400 LOC): build the skeleton: cover + “Start”, 2–3 scenes, nav mode toggle stub, dataset parse with a visible failure overlay.
• Iteration 2 (≤ 1.5k LOC): implement the navigation engine (paged/free), reveal system, and a basic card/list system.
• Iteration 3 (≤ 4k LOC): add core charts (heatmap, tower, radar), but keep them simple and verifiable.
• Iteration 4 (≤ 7k LOC): add mobile paged-mode strategy (hide heavy blocks via

  data-mhide="paged"

  + bottom-sheet that moves DOM nodes).
• Iteration 5 (≤ 10k LOC): polish (motion tokens, full-screen HUD, share card, optional music/fireworks), and do a regression pass for desktop + mobile.

Keep this file (SKILL.md) high-level. Put long code samples and analysis recipes into

cookbook/

and implementation notes into

references/

to avoid prompt bloat.

Single-file HTML engineering notes (battle-tested)

• Boot layer: always include an explicit “Start” button; do not rely on scroll-only starts.
• Two navigation modes:

  paged

  (wheel/keys, plus touch swipe on mobile) and

  free

  (normal scroll).
• Mobile paged mode: each scene must fit one viewport; hide heavy blocks via

  data-mhide="paged"

  and open them in a bottom-sheet that moves existing DOM nodes (avoid duplicate IDs).
• Touch affordances: heatmap tap → toast; radar touchstart → point lift + tooltip.

See

references/single_file_engineering.md

for deeper patterns.

Responsive UX (Desktop + Mobile) — hard-won lessons

The page is one file, but it’s effectively two products: desktop cinematic and mobile slide deck. Treat responsive work as surgically isolated changes to avoid regressions.

Desktop (readable without full-screen)

• Prefer a wide-but-bounded content column (

  --maxw

  as a

  clamp()

  ), and reduce

  --gutter

  slightly on short viewports (e.g. 768px height) instead of shrinking typography.
• Use density variants rather than truncating content:
  • Multi-column lists for long leaderboards (keep metadata visible).
  • “Dense” list styling (tighter padding/gaps) for better above-the-fold readability.
• Avoid CSS-stretching canvases (radar charts): size canvas from its rendered rect and DPR, or enforce an

  aspect-ratio

  and draw in CSS pixels.
• If a 3D/transform section makes buttons unclickable, assume a stacking-context problem first (z-index + transforms + pointer-events).

Mobile (paged-mode = slide deck)

• Gate layout changes with

  @media (max-width: 620px) and (pointer: coarse)

  (width-only rules can accidentally affect small desktop windows).
• In mobile

  paged

  mode, avoid inner scrolling in scenes; hide heavy blocks with

  data-mhide="paged"

  and expose them via a bottom-sheet modal that moves the existing DOM node (so IDs and event listeners remain valid).
• Use touch-first affordances: tap feedback (toast), big hit targets, and optionally draggable floating controls (mode toggle / music) respecting safe-area insets.

For implementation patterns (bottom sheet node-moving, draggable HUD controls, canvas DPR sizing, and stacking-context pitfalls), see

references/responsive_ui_patterns.md

.

Narrative + UI quality bar (Bilibili-style pacing)

Design as a storyboard: each scene answers one question, then transitions.

Suggested pacing:

1. Grand cover + “Start” (cinematic; optional fireworks)
2. “How long since we met GitHub” (account createdAt → years)
3. “Your 2025 pulse” (activity tier + distribution)
4. Heatmap/city + streak + craziest day
5. “Time Tower” (12 months; month selector + star-time scatter points)
6. “Radar / hexagon” (categories; points lift/glow on hover or touch)
7. “New interests unlocked” (2025 stars vs previous years)
8. “Extreme moments” (night-owl / holidays; clearly mark best-effort)
9. “Open Source Award” (external contribution highlight; award ceremony feel)
10. Finale share card (screenshot-friendly; optional fireworks)

Interaction rules:

• Every button/card should be clickable with feedback (links when available; otherwise micro-interaction/toast).
• “Free scroll” vs “Page mode” must behave differently (page mode should snap/lock navigation by wheel/keys, and support touch swipe on mobile).
• Unify motion tokens (duration/easing) across scenes; prefer

  transform/opacity

  .

Known data limits (must disclose)

• Contribution calendar provides day-level counts, not a complete commit list per day.
• Events API keeps only ~90 days of history.
• Repo

  stargazers_count/forks_count

  are current snapshots, not year-increment.
• Private contributions / hidden settings can skew the public view.

Debug checklist

See

references/debug_checklist.md

for the full checklist. Common root causes:

• A JS parse error stops all handlers (duplicate

  const

  , missing

  )

  )
• A broken embedded dataset block breaks JSON parsing
• A blocked external script was treated as required instead of optional

Bundled resources (progressive disclosure)

• scripts/

  : reusable collection/build/embed templates (execute without loading into context)

• cookbook/

  : analysis recipes and larger Python snippets (open only what you need)

• references/

  : schema + storyboard + debugging notes (open only the specific file you need)