Math Atlas Problem Optimization
End-to-end workflow for creating or optimizing an interactive math problem page with
verified formulas, accurate history, contributor avatars + profile links, and a
high-quality Canvas visualization.
When to use
- User asks to optimize/fix/create a problem page at
/problems/<slug>
- User reports incorrect formulas, bad visualization, or missing references
- User wants to add a new mathematical problem to the atlas
Architecture (read this first)
Each problem is one self-contained file under src/content/problems/<slug>.ts that
calls defineProblem({...}). There is no central problems.ts data array and no separate
coreFormulas record — formulas, videos, authors, timeline all live inline in that object.
A new/edited problem touches up to four places:
src/content/problems/<slug>.ts — the defineProblem(...) object (data, formulas, videos, authors, timeline)
src/content/problems/index.ts — import the export and add it to the configuredProblems array
src/components/viz/classic-viz.tsx — the draw<Name> function + <Name>Viz wrapper
- Two viz registries —
src/components/viz/viz-loader.tsx and src/components/ui/problem-card.tsx
Types live in src/lib/problem-types.ts. Helpers (defineProblem, scholarSearch) in src/lib/problem-template.ts.
Workflow
Phase 1 — Audit
- Navigate to the page in the browser (
npx next dev) and take a full-page screenshot
- Read the problem file
src/content/problems/<slug>.ts
- Read the
draw<Name> function in src/components/viz/classic-viz.tsx
- Note issues: vague descriptions, missing/weak authors, no avatars, weak references, flat visualization, media-hype framing
Phase 2 — Research
Spawn a research agent to gather verified data. See references/research-checklist.md:
- Precise formal statement with LaTeX, plus 1-2 equivalent formulations
- Verified historical timeline with exact paper citations
- Key contributors (provers, verifiers, generalisers) with institutions
- For each person: homepage / Google Scholar / X(Twitter) / LinkedIn (verify identity!)
- Avatar source per contributor (personal photo for people, logo for orgs)
- DOI / arXiv links for all papers
- 2-3 relevant YouTube videos (verify each
videoId exists)
Be skeptical of recent (current-year) AI/math news — distinguish the exact result from
media conflation, and lean on primary sources (arXiv, the proof PDF, the problem's own catalogue).
Phase 3 — Write/update the problem file
Edit src/content/problems/<slug>.ts. See references/data-schema.md for the
field-by-field guide. Key fields: status, field, year, shortDescription, longDescription,
vizComponent, collections, coordinates, connections, authors, papers, timeline,
formulas, videos.
For a new problem, also register it in src/content/problems/index.ts (import + array entry).
Phase 4 — Formulas
Set the inline formulas: ProblemFormula[] array (2-4 entries), each { label, latex, description }:
- Main statement — the theorem / problem definition
- Key mechanism — the underlying quantity or bound that drives the result
- Classification / structure — a structural quantity, or the contrasting bound (e.g. the conjecture vs. the disproof)
Use String.raw for LaTeX; keep descriptions ≤120 chars.
Phase 5 — Authors: avatars + profile links
See references/data-schema.md "Authors" section.
- Avatars (
avatarUrl): for a person, use a personal photo; for a company/institution
entity author, use the org logo. Download assets into public/people/<name>.<ext> (photos) or
public/orgs/<name>.<ext> (logos) and reference "/people/..." / "/orgs/...". Local assets
avoid the next.config.ts remotePatterns allowlist (only upload.wikimedia.org +
scholar.googleusercontent.com) and never expire (LinkedIn/Twitter CDN URLs are signed and expire).
- Links: prefer Google Scholar; the Homepage slot falls back personal-site → Scholar →
Twitter/LinkedIn. Rendered as brand logos by
src/components/ui/author-card.tsx via
src/components/ui/brand-icons.tsx (Google Scholar, X, LinkedIn, Wikipedia). Fields:
homepageUrl, scholarUrl, twitterUrl, linkedinUrl, wikipediaUrl.
- Order: put the result's main contributors first, historical figures last.
Phase 6 — Visualization
Add a draw<Name> function + <Name>Viz wrapper at the end of classic-viz.tsx, then register the
PascalCase name in both viz-loader.tsx and problem-card.tsx. See
references/viz-patterns.md:
- Show the actual mathematical objects (point sets, vector fields, mappings), not abstract decoration
- Add pointer interactivity (mouse controls a meaningful parameter; gentle
time animation when idle)
- Mark key features (fixed points, singularities, the active element) with blue glow + label
- Style: dark bg (
#050505), white strokes, blue (#60a5fa) highlights; degrade gracefully on card previews
Phase 7 — Verify
- Reload the page in the browser, take a screenshot
- Check formulas render (no KaTeX errors) and the visualization animates + responds to the pointer
- Confirm every avatar serves (200) and each profile link / video resolves
- Run
npx next build — must pass TypeScript and static generation with no errors
- Verify all DOI/arXiv/homepage URLs are valid (curl 200) and
videoIds exist (YouTube oEmbed)
File map
| What |
Where |
| Problem data (per problem) |
src/content/problems/<slug>.ts — defineProblem({...}) |
| Problem registry |
src/content/problems/index.ts — configuredProblems array |
| Types |
src/lib/problem-types.ts (Problem, Author, ProblemFormula, Video, …) |
| Helpers |
src/lib/problem-template.ts (defineProblem, scholarSearch) |
| Visualization |
src/components/viz/classic-viz.tsx — draw* fn + *Viz wrapper |
| Viz registries (BOTH) |
src/components/viz/viz-loader.tsx and src/components/ui/problem-card.tsx |
| Author card + avatars |
src/components/ui/author-card.tsx |
| Brand link icons |
src/components/ui/brand-icons.tsx |
| Avatar assets |
public/people/<name>.<ext> (photos), public/orgs/<name>.<ext> (logos) |
| Image domain allowlist |
next.config.ts → images.remotePatterns |
| Page template |
src/app/problems/[slug]/page.tsx |
References
- references/research-checklist.md — what to verify during research
- references/data-schema.md — field-by-field guide for the problem file
- references/viz-patterns.md — Canvas visualization conventions and patterns
1---2name: math-atlas-problem3description: Optimize or create a math problem page in Math Atlas. Covers research, formula verification, visualization, problem data accuracy, author avatars/links, and browser testing. Use when asked to optimize, fix, or create a /problems/<slug> page.4metadata:5 source: https://skillmd.com/skills/resciencelab/math-atlas-problem6---78# Math Atlas Problem Optimization910End-to-end workflow for creating or optimizing an interactive math problem page with11verified formulas, accurate history, contributor avatars + profile links, and a12high-quality Canvas visualization.1314## When to use1516- User asks to optimize/fix/create a problem page at `/problems/<slug>`17- User reports incorrect formulas, bad visualization, or missing references18- User wants to add a new mathematical problem to the atlas1920## Architecture (read this first)2122Each problem is **one self-contained file** under `src/content/problems/<slug>.ts` that23calls `defineProblem({...})`. There is no central `problems.ts` data array and no separate24`coreFormulas` record — formulas, videos, authors, timeline all live inline in that object.2526A new/edited problem touches up to four places:27281. `src/content/problems/<slug>.ts` — the `defineProblem(...)` object (data, formulas, videos, authors, timeline)292. `src/content/problems/index.ts` — import the export and add it to the `configuredProblems` array303. `src/components/viz/classic-viz.tsx` — the `draw<Name>` function + `<Name>Viz` wrapper314. **Two** viz registries — `src/components/viz/viz-loader.tsx` **and** `src/components/ui/problem-card.tsx`3233Types live in `src/lib/problem-types.ts`. Helpers (`defineProblem`, `scholarSearch`) in `src/lib/problem-template.ts`.3435## Workflow3637### Phase 1 — Audit38391. Navigate to the page in the browser (`npx next dev`) and take a full-page screenshot402. Read the problem file `src/content/problems/<slug>.ts`413. Read the `draw<Name>` function in `src/components/viz/classic-viz.tsx`424. Note issues: vague descriptions, missing/weak authors, no avatars, weak references, flat visualization, media-hype framing4344### Phase 2 — Research4546Spawn a research agent to gather verified data. See [references/research-checklist.md](references/research-checklist.md):4748- Precise formal statement with LaTeX, plus 1-2 equivalent formulations49- Verified historical timeline with exact paper citations50- Key contributors (provers, verifiers, generalisers) with institutions51- For each person: homepage / Google Scholar / X(Twitter) / LinkedIn (verify identity!)52- Avatar source per contributor (personal photo for people, logo for orgs)53- DOI / arXiv links for all papers54- 2-3 relevant YouTube videos (verify each `videoId` exists)5556Be skeptical of recent (current-year) AI/math news — distinguish the *exact* result from57media conflation, and lean on primary sources (arXiv, the proof PDF, the problem's own catalogue).5859### Phase 3 — Write/update the problem file6061Edit `src/content/problems/<slug>.ts`. See [references/data-schema.md](references/data-schema.md) for the62field-by-field guide. Key fields: `status`, `field`, `year`, `shortDescription`, `longDescription`,63`vizComponent`, `collections`, `coordinates`, `connections`, `authors`, `papers`, `timeline`,64`formulas`, `videos`.6566For a **new** problem, also register it in `src/content/problems/index.ts` (import + array entry).6768### Phase 4 — Formulas6970Set the inline `formulas: ProblemFormula[]` array (2-4 entries), each `{ label, latex, description }`:71721. **Main statement** — the theorem / problem definition732. **Key mechanism** — the underlying quantity or bound that drives the result743. **Classification / structure** — a structural quantity, or the contrasting bound (e.g. the conjecture vs. the disproof)7576Use `String.raw` for LaTeX; keep descriptions ≤120 chars.7778### Phase 5 — Authors: avatars + profile links7980See [references/data-schema.md](references/data-schema.md) "Authors" section.8182- **Avatars** (`avatarUrl`): for a **person**, use a personal photo; for a **company/institution83 entity** author, use the org logo. Download assets into `public/people/<name>.<ext>` (photos) or84 `public/orgs/<name>.<ext>` (logos) and reference `"/people/..."` / `"/orgs/..."`. Local assets85 avoid the `next.config.ts` `remotePatterns` allowlist (only `upload.wikimedia.org` +86 `scholar.googleusercontent.com`) and never expire (LinkedIn/Twitter CDN URLs are signed and expire).87- **Links**: prefer Google Scholar; the **Homepage** slot falls back personal-site → Scholar →88 Twitter/LinkedIn. Rendered as brand logos by `src/components/ui/author-card.tsx` via89 `src/components/ui/brand-icons.tsx` (Google Scholar, X, LinkedIn, Wikipedia). Fields:90 `homepageUrl`, `scholarUrl`, `twitterUrl`, `linkedinUrl`, `wikipediaUrl`.91- **Order**: put the result's **main contributors first**, historical figures last.9293### Phase 6 — Visualization9495Add a `draw<Name>` function + `<Name>Viz` wrapper at the end of `classic-viz.tsx`, then register the96PascalCase name in **both** `viz-loader.tsx` and `problem-card.tsx`. See97[references/viz-patterns.md](references/viz-patterns.md):9899- Show the actual mathematical objects (point sets, vector fields, mappings), not abstract decoration100- Add pointer interactivity (mouse controls a meaningful parameter; gentle `time` animation when idle)101- Mark key features (fixed points, singularities, the active element) with blue glow + label102- Style: dark bg (`#050505`), white strokes, blue (`#60a5fa`) highlights; degrade gracefully on card previews103104### Phase 7 — Verify1051061. Reload the page in the browser, take a screenshot1072. Check formulas render (no KaTeX errors) and the visualization animates + responds to the pointer1083. Confirm every avatar serves (200) and each profile link / video resolves1094. Run `npx next build` — must pass TypeScript and static generation with no errors1105. Verify all DOI/arXiv/homepage URLs are valid (curl 200) and `videoId`s exist (YouTube oEmbed)111112## File map113114| What | Where |115|------|-------|116| Problem data (per problem) | `src/content/problems/<slug>.ts` — `defineProblem({...})` |117| Problem registry | `src/content/problems/index.ts` — `configuredProblems` array |118| Types | `src/lib/problem-types.ts` (`Problem`, `Author`, `ProblemFormula`, `Video`, …) |119| Helpers | `src/lib/problem-template.ts` (`defineProblem`, `scholarSearch`) |120| Visualization | `src/components/viz/classic-viz.tsx` — `draw*` fn + `*Viz` wrapper |121| Viz registries (BOTH) | `src/components/viz/viz-loader.tsx` **and** `src/components/ui/problem-card.tsx` |122| Author card + avatars | `src/components/ui/author-card.tsx` |123| Brand link icons | `src/components/ui/brand-icons.tsx` |124| Avatar assets | `public/people/<name>.<ext>` (photos), `public/orgs/<name>.<ext>` (logos) |125| Image domain allowlist | `next.config.ts` → `images.remotePatterns` |126| Page template | `src/app/problems/[slug]/page.tsx` |127128## References129130- [references/research-checklist.md](references/research-checklist.md) — what to verify during research131- [references/data-schema.md](references/data-schema.md) — field-by-field guide for the problem file132- [references/viz-patterns.md](references/viz-patterns.md) — Canvas visualization conventions and patterns