ghstats/docs/design-guidelines.md

Design Guidelines

Visual conventions for ghstats SVG cards. All cards share a single frame shape so they stack cleanly in a README — two cards sit side-by-side inside GitHub's ~816 px content column.

Card frame

Property	Value
Width × Height	340 × 200 (matches github-profile-summary-cards)
Corner radius	6 px
Stroke	theme.Stroke at theme.StrokeOpacity
Fill	theme.Background
Font family	'Segoe UI', Ubuntu, Sans-Serif
Title	15 px, weight 600, theme.Title, anchored at (20, 30)

Generated by header(width, height, bg, stroke, strokeOpacity, titleColor, title) in internal/card/svg.go.

Theme role mapping

Theme field	Used for
Title	Card title text
Text	Primary content (values, names)
Background	Card fill + stroke around donut slices to separate colors
Stroke + StrokeOpacity	Card outline
Muted	Axis lines, axis labels, icons, legend metadata
Accent	Bars, area fills, stat values, fallback slice color

Cards MUST NOT hardcode colors outside these fields. If a new visual needs a shade, pick the closest existing field — don't extend the schema without a strong reason.

Row-based cards (profile, stats)

Single-column rows of icon + label or icon + label + value.

Metric	Profile	Stats
First row baseline (y)	60	55
Row spacing	20 px	20 px
Row x padding	20	20
Icon scale	12/16 = 0.75 from 16×16 Octicon viewBox	same
Icon color	theme.Muted	same
Value font	12 px, theme.Text	12 px, weight 600, theme.Accent, right-anchored at x = 320

Cap rows at what fits: up to 7 rows per card. Stats splits commits into lifetime + last-year rows.

Donut cards (language breakdowns)

Metric	Value
Donut centre	(250, 110)
Outer radius	55
Inner radius	30
Top-N entries shown	5 (overflow collapses into "Other")
Slice stroke	theme.Background, 1.5 px (gap between slices)
Legend origin	(20, 55)
Legend row height	20 px
Swatch size	10 × 10
Legend font	11 px

Language colors come from linguist via GraphQL (repo.languages.edges[].node.color). Missing colors fall back to theme.Accent.

When there's exactly one slice (one language at 100%), the renderer emits two concentric <circle> elements instead of a pie arc, because SVG's A command from point P back to the same P draws nothing. Regression guarded by TestDonutSingleSlice.

Bar-chart cards (productive time)

Metric	Value
Chart area	x ∈ [35, 325], y ∈ [45, 155] (110 tall)
Bars	24 bars, 1 px gap
Bar fill	theme.Accent
Y-axis ticks	niceTicks(max, 5) — 1/2/5 × 10^k ladder
X-axis labels	Hours 0, 6, 12, 18, 23
Axis caption	"hour of day" bottom-center
Title format	Commits by Hour (<window>, UTC±N.NN)
Hover	<title>HH:00 — N commits</title> inside each bar

Area-chart cards (contributions)

Metric	Value
Chart area	x ∈ [28, 312], y ∈ [45, 150] (105 tall)
Curve	Catmull-Rom → cubic Bezier (tension 0.5)
Fill	theme.Accent at 25% opacity
Stroke	theme.Accent, 2 px
Y-axis	Both sides, mirrored, same tick values
X-axis labels	mm/yy, stride-thinned to ~6 labels regardless of bucket count
Axis caption	"mm/yy" bottom-center
First/last labels	Always printed (pinned endpoints)

Missing months in the [first, last] range are inserted as zero-count rows to keep the curve time-continuous.

Icons

• Sourced from Primer Octicons 16×16 set.
• Stored as raw <path d="…"/> strings in internal/card/icons.go.
• Rendered inside <g transform="translate(x,y) scale(0.75)" fill="muted">…</g> (scaled to fit the 12 px box).
• Used: iconRepos, iconCompany, iconLocation, iconClock, iconLink, iconPeople, iconStar, iconCommit, iconPR, iconIssue, iconReview.

Add new icons by copying the <path> from Octicons and appending to icons.go. Keep them to the same 16×16 viewBox so the existing scale math applies.

Fit-the-frame invariant (MUST hold before release)

Every card MUST render entirely inside the 340 × 200 frame for every profile the card can encounter, not just the author's. That means:

Thing that varies	Worst case to design for
Star counts, commit counts, streak lengths, active days	10-digit formatted integer (e.g. 1,234,567,890)
Repo / language / company / location names	40+ char strings with CJK / emoji
Number of active years	20+ years (contribution history can start in 2008)
Contribution calendar weeks	53 — not 52 — when the window spans a year transition

Concrete rules this implies:

• Reserve columns. When a card has N equal-width columns, treat 340 / N as the hard limit for each column's widest element. No centered text can be wider than its column.
• Right-anchored values (stats rows, top-starred bars) must leave a safety margin. Right edge ≤ width − 6; do not place an icon to the right of a right-anchored number (they collide on multi-digit values).
• Long strings get truncated, not wrapped. Use truncateName (top-starred) or pick a layout that allows clipping via text-overflow semantics. Never let a wide string push a later element off-screen.
• Variable-count grids (heatmap 7×N, by-year N bars) must compute cell size from the container width, not the other way round. Don't hardcode a cell size that only works for the author's profile.
• Month / year tick labels within ~20 px of the right edge must be skipped (they read past the frame otherwise).

Review checklist (before merging any card change)

Render the dracula theme against at least three profiles or synthetic fixtures:

1. Tiny: a brand-new account with 0 commits, 0 stars, 1 repo.
2. Typical: the author's profile (tiennm99 via demo/ regeneration).
3. Adversarial: seven-digit commit counts, 40-char repo / company / location names, 20 active years, 53-week span. A small synthetic *.json fixture is fine; it doesn't need a token.

Then open every affected SVG at 1× and 2× zoom and verify:

• No <text>, <rect>, <circle>, <line>, or path coordinate exceeds x=340 or y=200, or falls below x=0 / y=0.
• No two elements overlap in a way that makes either unreadable.
• Right-anchored numbers don't collide with icons, swatches, or bars.
• Peak-vs-dim highlighting still reads at a glance (dracula Background → Accent contrast is fine; light themes like github or nord_bright need a separate check).

The demo/<theme>/ gallery auto-regenerates on every push to main; use the last CI run as the dracula reference, and stress-test the adversarial case locally before pushing.

Accessibility

• Contrast is the theme author's responsibility — we don't validate at runtime.
• Tooltips (<title>) on productive-time bars let screen readers announce counts.
• No motion, no <animate> elements — profile READMEs render statically.

Text overflow

• Long strings (bio, repo names) are not truncated; they're XML-escaped and printed as-is.
• If a card looks crowded at 340 px width, that's a card design problem — fix the layout, not the data.