Google’s Gemini 2.5 Pro includes a genuinely useful party trick: upload a photo of a hand-drawn wireframe, describe what you want, and watch it generate working HTML and CSS. It’s impressive. It’s also not magic. What you get is a solid starting point that needs real work before you’d dare put it live. This tutorial walks you through the full workflow — from sketch to functional portfolio site — including the parts where the AI fumbles and you have to step in.
We’re building a simple portfolio landing page: hero section, project grid, contact form. The kind of thing a designer might sketch on paper during a client call. Gemini will convert that sketch to code in under five minutes. Then we’ll spend the rest of the time fixing what it got wrong, making it responsive, and adding the polish that actually matters. Think of this as collaborative coding where the AI does the grunt work and you do the thinking.
You’ll need a Google account with access to Gemini 2.5 Pro through AI Studio or the Gemini API. A basic understanding of HTML and CSS helps, but you don’t need to be a front-end wizard. If you can spot when a button looks weird or spacing feels off, you’re qualified. For the refinement stage, we’ll use Claude Code to iterate faster, but you could use any code editor with AI assistance.
Draw your portfolio wireframe. Seriously, grab paper and a pen. Label the sections clearly: “Hero – Name & Tagline Here”, “Projects Grid – 3 columns”, “Contact Form”. Gemini needs context, so annotations matter more than artistic skill. Draw boxes for images, lines for text, arrows to show hierarchy. Take a clear photo with good lighting — no shadows obscuring your labels.
The sketch doesn’t need to be pixel-perfect. Gemini interprets intent, not exact measurements. But be explicit about structure. If you want a navigation bar, draw it and label it “Nav: Home, Projects, About, Contact”. If a section should have a background color, write “dark background” next to it. The more context you provide visually and through labels, the less you’ll need to fix later.
Open AI Studio, start a new chat with Gemini 2.5 Pro, and upload your photo. Now comes the critical part: the prompt. Don’t just say “make this a website.” Be specific about technology, structure, and style. Here’s a prompt that actually works:
Convert this hand-drawn wireframe into a complete HTML file with embedded CSS.
Structure:
- Single-page portfolio layout
- Semantic HTML5 elements
- Mobile-first responsive design
- CSS Grid for project section
- Flexbox for navigation and hero
Style requirements:
- Modern minimal aesthetic
- Primary color: #2563eb (blue)
- Dark hero section with white text
- Sans-serif font stack: Inter, system-ui, sans-serif
- Smooth scroll behavior
- 16px base font size
Include:
- Fixed navigation with smooth scrolling to sections
- Hero with name, tagline, CTA button
- Projects grid (3 columns on desktop, 1 on mobile)
- Simple contact form with name, email, message fields
- Footer with social links placeholders
Output clean, production-ready code with comments.Gemini will generate the code in about 30 seconds. Copy it, save it as index.html, and open it in a browser. You’ll have something that looks surprisingly decent. The structure will match your sketch, the colors will be applied, and it’ll probably even be somewhat responsive. But zoom in and you’ll spot the problems: inconsistent spacing, generic placeholder content, form that doesn’t actually work, accessibility attributes missing.
Pro tip ✅
Take a screenshot of your first generated result before you change anything. When you iterate later, you’ll want to compare what Gemini gave you versus what you actually needed. It’s a useful reference for understanding where AI code generation consistently falls short.
Open the HTML file in your editor. First pass: fix spacing and alignment issues. Gemini often generates inconsistent padding and margin values. Look for sections where padding jumps from 2rem to 4rem to 3rem with no logic. Standardize it. Create a spacing scale: 0.5rem, 1rem, 2rem, 4rem, 8rem. Replace all the random values with your scale.
Next, tackle the navigation. Gemini probably generated anchor links that scroll to section IDs, but the smooth scroll behavior might be janky or non-existent. Add this to your CSS if it’s missing:
html {
scroll-behavior: smooth;
}
/* Offset for fixed nav */
section {
scroll-margin-top: 80px;
}Now check the project grid. Gemini likely used CSS Grid correctly for desktop, but the mobile breakpoint might be awkward. Projects probably stack at tablet sizes when you’d prefer two columns. Adjust the media query:
.projects-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
gap: 2rem;
}
@media (max-width: 768px) {
.projects-grid {
grid-template-columns: 1fr;
gap: 1.5rem;
}
}
Here’s where Gemini consistently fails: accessibility. The generated code probably has semantic HTML tags, but it’s missing ARIA labels, focus states, and keyboard navigation considerations. Start with the navigation. If Gemini generated a mobile hamburger menu, it probably doesn’t have proper ARIA attributes:
MenuAdd focus-visible styles so keyboard users can see where they are:
a:focus-visible, button:focus-visible {
outline: 3px solid #2563eb;
outline-offset: 2px;
}
/* Remove default outline */
a:focus:not(:focus-visible), button:focus:not(:focus-visible) {
outline: none;
}The contact form definitely needs work. Gemini generates input fields, but they’re missing proper labels, autocomplete attributes, and error states. Fix each input:
Name *Warning ⚠️
Gemini won’t generate functional form handling. You’ll need to add JavaScript for validation and submission, or connect it to a backend service like Formspree or Netlify Forms. The AI gives you the HTML structure, not the actual functionality.
Now that the foundation is solid, use Claude Code to refine details faster. Copy your HTML into a new Claude conversation and ask for specific improvements. This works better than vague requests:
Review this portfolio HTML and improve:
1. Add micro-interactions: subtle hover effects on project cards and buttons
2. Implement a color scheme with CSS custom properties for easy theming
3. Add a subtle gradient to the hero background
4. Create smooth fade-in animations for sections on scroll
5. Ensure all interactive elements have :hover, :focus, and :active states
Maintain the existing structure. Only enhance the CSS.Claude will return enhanced CSS with CSS variables, smooth transitions, and polished interactions. It’s better at refinement than Gemini is at initial generation. Copy the suggested improvements back into your file, test them, and iterate. Ask Claude to generate different color schemes by just changing the CSS custom properties:
Generate three alternative color schemes using CSS custom properties:
1. Dark mode variant
2. Warm earth tones
3. Cyberpunk neon
Provide each as a separate :root block I can swap in.Pro tip ✅
Keep your conversation with Claude focused on one aspect at a time. Instead of “make it better,” ask for specific improvements: typography hierarchy, spacing rhythm, or animation timing. You’ll get more useful, targeted suggestions.
Replace all the placeholder text with actual content. This is where you’ll notice layout issues the AI couldn’t predict. Long project titles might break your grid. A bio paragraph longer than three sentences might throw off your hero section spacing. Real content reveals real problems.
Test on actual devices, not just browser dev tools. Chrome’s responsive mode is useful, but it doesn’t show you how Safari on iOS handles your fixed navigation or how Firefox renders your CSS Grid. Open your file on your phone. Share it with friends on different devices. You’ll find issues: buttons too small to tap comfortably, text too light on certain backgrounds, sections that feel cramped on tablet sizes.
Run your HTML through the W3C validator and an accessibility checker like WAVE or axe DevTools. Fix the errors. Gemini-generated code often has minor HTML validation issues: missing alt attributes, improper heading hierarchy, or invalid ARIA usage. Clean it up. This is the difference between a demo that looks good in a screenshot and a site you’d actually deploy.
Gemini doesn’t think about performance. Your generated code probably inlines all CSS, includes no image optimization, and has zero consideration for loading speed. Extract your CSS into a separate file for caching. If you added images, optimize them — use WebP format with fallbacks, add width and height attributes to prevent layout shift, implement lazy loading for below-the-fold content:
Add meta tags that Gemini definitely didn’t include: Open Graph for social sharing, viewport for mobile, description for SEO. These basics matter:
Pro tip ✅
Use Lighthouse in Chrome DevTools to audit your page. Run tests for performance, accessibility, best practices, and SEO. Each category shows specific issues to fix. Aim for scores above 90 in all categories before you consider the site truly production-ready.
Gemini will generate z-index values seemingly at random. Your navigation might be z-index: 1000, a modal z-index: 10, and a dropdown z-index: 9999. Create a rational z-index scale in your CSS variables and apply it consistently. You only need 3-4 layers: base (1), elevated (10), overlay (100), modal (1000).
The AI often creates overly specific selectors. You’ll see things like “.hero-section .hero-content .hero-title” when just “.hero-title” would work. Simplify your CSS. Remove unnecessary specificity. Use class names that describe purpose, not position. “.card-title” is better than “.projects-grid-item-heading”.
Typography hierarchy will be inconsistent. Gemini might use six different font sizes with no systematic scale. Define a type scale using CSS custom properties:
:root {
--text-xs: 0.75rem;
--text-sm: 0.875rem;
--text-base: 1rem;
--text-lg: 1.125rem;
--text-xl: 1.25rem;
--text-2xl: 1.5rem;
--text-3xl: 1.875rem;
--text-4xl: 2.25rem;
}
h1 { font-size: var(--text-4xl); }
h2 { font-size: var(--text-3xl); }
h3 { font-size: var(--text-2xl); }Avoid 🚫
Don’t trust Gemini’s color contrast choices blindly. Light gray text on white backgrounds might look fine at a glance but fail WCAG standards. Use a contrast checker and aim for at least 4.5:1 ratio for normal text, 3:1 for large text.
Gemini 2.5 Pro’s image-to-code feature is genuinely useful for getting past the blank page. It converts a sketch into structured, semantic HTML faster than you could scaffold it manually. But it’s not autonomous web development. The AI gives you a foundation that needs refinement, accessibility work, performance optimization, and real-world testing. That’s not a criticism — it’s the current reality of AI-assisted coding.
The 12-minute claim in the headline? That’s how long the initial generation takes. The actual work — making it production-ready — takes another 30-60 minutes depending on complexity. That’s still faster than building from scratch, but it’s collaborative development, not automated development. Use Gemini to skip the boring parts: basic structure, initial styling, responsive breakpoints. Then apply your judgment to make it actually good.
If you’re learning web development, this workflow teaches you what matters in production code by showing you what the AI misses. If you’re an experienced developer, it speeds up prototyping and client mockups significantly. Either way, ship the sketch-to-code output as-is and you’ll regret it. Do the finishing work, and you’ll have something worth putting your name on.
