How to build your case portfolio without lying

The portfolio that doesn’t convert

Most dev portfolios look like screenshot catalogs. Screenshot of the site, client name, link. No context, no process, no result. The visitor sees 10 pretty thumbnails and has no idea what problem each project solved.

This format doesn’t differentiate you from anyone else. Every dev has screenshots. What the client wants to know before hiring is: have you solved a problem similar to mine? How did you solve it? What was the result?

A portfolio that converts doesn’t show what you did. It shows what you solved. The difference seems subtle, but it changes everything when closing a contract.

A case isn’t a screenshot. It’s a story.

A well-documented case answers four questions:

What was the problem? What pain did the client arrive with? Slow site, no SEO, no conversion, manual processes, outdated system. The problem is the hook that connects the portfolio visitor with the case. If they have the same pain, they keep reading.

What did you do? What was the technical and strategic solution? Stack used, architecture decisions, optimizations applied. It doesn’t need to be a tutorial. It needs to show that you thought about the problem before jumping into code.

What was the result? Numbers. Lighthouse before and after. Load time. Google position. Conversion increase. Operational cost reduction. Results without numbers are opinions. Results with numbers are proof.

What did the client think? A real testimonial. It doesn’t need to be long. One sentence from the client confirming the project solved their problem is worth more than 3 paragraphs of you explaining how good you are.

On my site, each case follows this structure. Family Pilates shows: problem (slow WordPress, Lighthouse 65), solution (migration to Astro, local SEO), result (Lighthouse 98, LCP 0.8s). AutoPars shows: problem (auto parts marketplace without a platform), solution (React + Supabase with 5 integrations), result (complete system with 3 panels running in production).

Numbers that matter (and numbers that don’t)

Not every number impresses. “Site with 50 pages” says nothing about quality. “Lighthouse score of 98” does. Choose metrics the client understands and that demonstrate real value.

Metrics that work:

• Lighthouse Score (before vs after)
• LCP / load time (real seconds)
• Google position for specific keyword
• Hosting cost (before vs after)
• Development time (shows efficiency)
• ROI when measurable (“site paid for itself with X clients”)

Metrics that impress nobody:

• “50+ React components” (client doesn’t know what a component is)
• “10,000 lines of code” (more code isn’t better)
• “Modern stack” (vague, proves nothing)
• “Responsive design” (this is an obligation, not a differentiator)

With GPM2, the number that matters is Lighthouse 95+ with zero client-side JavaScript. For a tax consulting site, that means fast loading and strong technical SEO. The client doesn’t need to know it’s Astro. They need to know their site loads in under 1 second.

With FitPlan, the number that matters is “37% reduction in cancellations” after implementing inactivity notifications. That number speaks the language of a gym owner. It’s more convincing than any technical detail.

How to document when the project is small

“But my project is just a landing page, there’s no case to tell.” Yes there is. Every LP has a problem, solution, and result.

LP for a dental clinic:

• Problem: clinic invested R$3k/month in Google Ads and received 2-3 contacts
• Solution: optimized LP with WhatsApp CTA, FAQ with objections, Schema.org
• Result: 8-12 contacts/month with the same ads investment

That’s a case. You don’t need a marketplace with 5 integrations to have a story. You need measurable results.

If you’re starting out and have no clients yet, personal projects count. But present them as real cases: what problem you wanted to solve, how you solved it, and what the technical result was (Lighthouse, performance, SEO). A personal project with Lighthouse 100 is better than a client project with Lighthouse 50. What matters is the quality of the work, not who paid for it.

Cases page: structure that works

The portfolio cases page needs two things: quick overview and depth on demand.

Overview (listing). Card with: project name, category (LP, webapp, institutional), one sentence about the main result, and thumbnail. The visitor scans 5-8 cases in 10 seconds and clicks on what seems relevant to their problem.

Individual case page. Here comes the full story: problem, solution, result, testimonial. With real screenshots (not generic mockups), concrete metrics, and link to the live site when possible.

On my site, the cases page follows exactly this structure. Cards with summaries in the listing, dedicated page with details for each project. The visitor researching “dev for clinic site” sees the Family Pilates case and understands in 30 seconds that I’ve already solved this type of problem.

Avoid technical jargon on the cases page. The visitor might be the business owner, not the CTO. “We migrated from WordPress to Astro with SSG and Vercel deployment via CI/CD” doesn’t communicate value. “The site went from 4 seconds to 0.8 seconds load time, and hosting that cost R$100/month is now free” does.

What not to put in the portfolio

Projects you can’t show. If the client requested confidentiality, respect it. Mention the sector (“B2B marketplace in the automotive sector”) without revealing names or sensitive data.

Old projects that don’t represent your current level. The site you built in 2019 with jQuery and Bootstrap might’ve been good at the time, but if it’s in your portfolio in 2026, the visitor thinks that’s your current level. Keep only what represents the quality you deliver today.

Work that isn’t yours. Seems obvious, but there are devs who put agency projects where they did 10% of the work as if it were a solo project. Be honest about your role. “I was responsible for the frontend and integrations” is more respectable than pretending you did everything.

Excessive quantity. 5-8 well-documented cases sell more than 30 thumbnails without context. Quality beats quantity in portfolios. Curation is part of the job.

How to ask for testimonials without being awkward

Many devs don’t ask for testimonials because they find it invasive. The truth is that most satisfied clients don’t mind giving a testimonial. They just don’t think of it spontaneously.

The right moment: right after delivery, when the client is happy with the result. Send a simple message: “I’m glad the project turned out the way you wanted. If it makes sense, a short testimonial about the experience would really help me. It can be just text, 2-3 sentences about the result.”

If the client agrees, guide with questions: “What was the problem before? How is it now?” This avoids generic testimonials like “Great professional, I recommend” and generates testimonials with substance.

With Tok Final and Soline, client testimonials are part of the case page. I didn’t ask for anything elaborate. I asked for a short message about the result. The client sent it via WhatsApp in 2 minutes.

Portfolio is a sales tool

A portfolio isn’t a showcase. It’s a sales argument. When you enter a commercial conversation and the lead asks “have you done something similar?”, you send the link to the specific case. Not the entire portfolio. The specific case that shows you’ve already solved the problem they have.

In my prospecting flow for aesthetic dentistry clinics, when the dentist asks about results, I send the direct link to the relevant case. I don’t need to explain much. The case speaks for me: problem, solution, result, numbers.

A well-built portfolio sells without you needing to sell. It’s the silent proof that you know what you’re doing.

• Does each case have problem, solution, and result documented?
• Do results have concrete numbers (Lighthouse, time, ROI)?
• Is the language accessible to non-technical people?
• Do you have real testimonials from at least 3 clients?
• Does the cases page have overview (cards) and depth (individual page)?
• Do the cases represent your current level of work?
• Do you remove old projects that no longer represent your quality?

The best marketing a dev can do is show real work with real results. No exaggeration, no lies, no pretty screenshots without context. A well-documented case sells for you while you’re coding the next project.