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
- 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.