Skip to content
← All projects

Portfolio website

Statically generated Next.js site with typed, build-validated content, MDX case studies and CSS scroll-driven animations.

Context
Personal project
Role
Solo project
Period
Sep 2026 – Present
Stack
  • Next.js
  • TypeScript
  • Tailwind CSS
  • MDX
  • Zod
  • Mermaid
  • Vercel

Context & problem

A portfolio has two very different readers. Recruiters arrive from LinkedIn or a CV, often on a phone, and scan for role, stack, experience, availability and a way to get in touch. Tech leads open one or two projects and the GitHub repo, looking for decisions, trade-offs and a sense of production.

The site had to answer "who, what and what next" in under 10 seconds, put projects and contact one click away, and be a piece of evidence in itself: fast, accessible and built with care.

Constraints

  • Content first, animation second. Everything must be readable without JavaScript, with reduced motion and when printed. Animation is decoration, never a condition for seeing information.
  • Performance budget. Targets set before building: LCP under 2.0 s and CLS under 0.05 in lab tests on mobile, and at most 150 KB of JavaScript on the home page.
  • Accessibility. WCAG 2.2 AA: skip link, landmarks, visible focus, 44 px touch targets and no information conveyed by motion alone.
  • Honest content. Some of my work is proprietary, so the site had to present projects without a public repo, without leaking code or inventing numbers.

Architecture

Portfolio build flow: typed content and MDX are validated with zod, built as static pages by Next.js and served by Vercel
Architecture diagram. Content lives in TypeScript files and MDX case studies. At build time zod validates every field and cross-reference, Mermaid diagrams are checked against their pre-rendered SVGs, and Next.js generates static pages that Vercel serves to the browser.
Open SVG in a new tab 
  • Pages. One landing page with anchored sections (Projects, Experience, Skills, About, Contact) and a statically generated page per case study at /projects/[slug]. Unknown slugs return a 404.
  • Content. Profile, experience, skills and UI strings live in typed TypeScript files; case studies are MDX with YAML frontmatter. zod schemas are the single source of truth for the types.
  • Validation at build. An invalid field breaks the build with the file and field name. Cross-checks cover slugs, dates and image files, and a strict mode fails production builds if any content placeholder is left.
  • Diagrams. Mermaid sources are rendered to SVG locally or in CI and committed. The build compares a hash to catch out-of-date diagrams, so there is no Mermaid runtime in the browser.
  • Animation. CSS scroll-driven animations where the browser supports them, an IntersectionObserver fallback where it doesn't, and nothing at all with reduced motion.

Decisions & trade-offs

  • CSS scroll-driven animations instead of GSAP ScrollTrigger. They run off the main thread and ship no JavaScript. The cost: browsers without support (Firefox, at the time of writing) need a fallback, and there are no pinned sections. Sticky positioning covers the one place that needed it.
  • Native scrolling, no smooth-scroll library. Scroll feels the way the visitor's device expects, and CSS smooth scrolling is switched off with reduced motion.
  • No 3D or WebGL. The hero background is a small inline SVG, which keeps the largest content element as text and the page light.
  • A visibility model for projects. Each project is public, private or under NDA. Private projects can't link a repo and must include an architecture diagram and a written impact, enforced by the schema rather than by memory.
  • Few client components. Most of the site renders on the server. Adding a client component needs a reason in the pull request.
  • A plain, clickable email. No obfuscation and no contact form: one click to email, one click to copy the address.
  • Built with an AI-agent workflow. I set up and orchestrated a workflow where AI agents handled market analysis, architecture, copywriting, implementation, code audit and QA. I directed the work, reviewed what each agent produced and made the decisions.

Want to talk about this project?

Get in touch