SyntaxPilot
Courses/Vibe Coding/Lesson 9
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Vibe Coding · Lesson 9 of 40

Project: personal portfolio site

multi-section pageresponsive designmobile viewCSS flexbox and grid in plain wordsimages and alt textcontact linksaccessibility basicsLighthouse score

Vibe Coding: build real apps with AI · Episode 9. Every agent run below is real: Claude Code 2.1.319 (model claude-sonnet-5-5) in print mode (claude -p), on 7 November 2026, in /home/ravi/projects/portfolio (a Git repository). me.jpg is an illustrated avatar (not a real person) saved as a 3000×3000 JPEG, like a phone photo. Pages were served with python3 -m http.server 8088 and opened in Chromium; Lighthouse is version 13.6.0 from npm with its default (mobile) settings. Replies are quoted exactly, shortened where marked ....

Why a portfolio

A recruiter says "send me your work". Ravi's projects (the flat expense app from Episode 7, the tip calculator from Episode 8) sit in laptop folders. Twenty screenshots in a chat get lost. One link that shows who you are, what you built and how to reach you, on any phone: a portfolio website.

A multi-section page (a restaurant menu)

A restaurant menu A portfolio page
sections: starters, mains, desserts <section> elements: About, Projects, Skills, Contact
tabs to jump to desserts menu links: href="#projects"
each section's printed name id="projects": the link's target
<nav class="nav">
  <a class="logo" href="#top">Ravi</a>
  <ul>
    <li><a href="#about">About</a></li>
    <li><a href="#projects">Projects</a></li>
    <li><a href="#skills">Skills</a></li>
    <li><a href="#contact">Contact</a></li>
  </ul>
</nav>
...
<section id="about" class="section about"> ... </section>
<section id="projects" class="section"> ... </section>

nav is the menu, ul a list, li a list item, a a link. href="#about": the # means "a place on this page", the element with id="about".

One prompt

ravi@laptop:~/projects/portfolio$ claude -p "Make my personal portfolio website: index.html plus style.css. I'm Ravi, a beginner who builds small apps with AI. Sections: About me (with my photo me.jpg), Projects (1. Flat expense splitter in Python, screenshot settle.png; 2. Tip calculator web page, screenshot tip.png), Skills, and Contact (email ravi@example.com and GitHub github.com/ravi-builds). It must look good on phones and laptops." --allowedTools Read Write Edit Glob
1 Bash   ls -la            → me.jpg  settle.png  tip.png
2 Write  index.html        (85 lines)
3 Write  style.css         (240 lines)
4 Reply: "I haven't opened the page in a browser, so I haven't seen how it
   looks on a phone or laptop. ...
   - Extras: a menu bar that stays at the top and jumps to each section,
     and an automatic dark mode when the visitor's device is set to dark.
   I wrote the project descriptions and the skills list myself, so please
   change them to match what you actually did. ...
   me.jpg is 1.5 MB, which will make the page slow to load on mobile."

Its notes are your to-do list: it hasn't looked at the page, it wrote the descriptions itself (Ravi checked them; they're true), and the photo is heavy. On a 1280px laptop: menu, photo beside the intro, two project cards side by side.

Responsive design (water takes the glass's shape)

Responsive design means one page that reshapes itself for any screen width: one column on a phone, side by side on a laptop.

  1. In the HTML head: <meta name="viewport" content="width=device-width, initial-scale=1"> tells phones to use their real width instead of shrinking a desktop page.
  2. Mobile-first CSS: rules for the smallest screen first, then add.
  3. A media query applies rules only when a condition is true:
/* phones first: one column */
.about { display: flex; flex-direction: column; align-items: center; gap: 24px; }
.cards { display: grid; grid-template-columns: 1fr; gap: 24px; }

/* Laptops and tablets */
@media (min-width: 700px) {
  .about { flex-direction: row; text-align: left; gap: 48px; }
  .cards { grid-template-columns: repeat(2, 1fr); }
}

Flexbox and grid in plain words

Real life CSS Use
a queue: one line, across or down Flexbox: display: flex; + flex-direction: row or column the About section: photo above text on a phone, beside it on a laptop
an egg tray: rows and columns Grid: display: grid; + grid-template-columns the project cards
equal slices 1fr: one fraction of the free space repeat(2, 1fr) = two equal columns

The phone view: screenshots cut off

At 360px the layout works, but the settle screenshot loses its Balance column and the tip screenshot shows only its top. Why:

.card img {
  width: 100%;
  aspect-ratio: 16 / 10;
  object-fit: cover;
  object-position: top;
  ...
}

aspect-ratio: 16 / 10 forces a box shape, and object-fit: cover fills it by cropping whatever doesn't fit.

ravi@laptop:~/projects/portfolio$ claude -p "On a phone-sized screen (360px wide), the project screenshots in the cards are cut off: settle.png loses the right side (the Balance column is cut) and tip.png only shows the top of the page. Show each whole screenshot instead, without stretching it. Change only what's needed." --allowedTools Read Edit
 .card img {
+  display: block;
   width: 100%;
-  aspect-ratio: 16 / 10;
-  object-fit: cover;
-  object-position: top;
+  height: auto;

height: auto keeps each image's own shape. Fixed on the phone, but re-test the laptop: the tall phone screenshot makes a giant card, and grid stretches the other card in the same row to match, leaving a big empty space. A fix for one screen broke another.

ravi@laptop:~/projects/portfolio$ claude -p "The whole screenshots show now, but on a laptop the Tip Calculator card is very tall and the Flat Expense Splitter card has a big empty space under its text. Give both screenshots the same height (about 220px) with the whole image fitted inside that area: not cropped, not stretched. Change only what's needed." --allowedTools Read Edit
 .card img {
   display: block;
   width: 100%;
-  height: auto;
+  height: 220px;
+  object-fit: contain;
"If an image's shape doesn't match the card width, you'll see empty bands
 beside or above it."

object-fit: contain is cover's opposite: fit the whole image inside the box, with empty bands if the shape differs. Re-tested on both screens: equal cards, whole screenshots.

Images and alt text

<img class="avatar" src="me.jpg" alt="Photo of Ravi" width="220" height="220">
...
<img src="settle.png" alt="Screenshot of the flat expense splitter showing who owes whom" loading="lazy">
...
<img src="tip.png" alt="Screenshot of the tip calculator web page" loading="lazy">

Alt text is what an image says to someone who can't see it. A screen reader (an app that reads the page aloud) reads it; the browser shows it if the image fails to load; search engines read it too. Good: what matters in the image. Bad: "image", "screenshot", a file name. Decorative images get alt="" so they're skipped.

What assistive technology gets (real output of Playwright's ariaSnapshot()):

- main:
  - img "Photo of Ravi"
  - paragraph: Hi, I'm Ravi 👋
  - heading "I build small apps with AI." [level=1]
  ...
  - heading "Projects" [level=2]
  - article:
    - img "Screenshot of the flat expense splitter showing who owes whom"
    - heading "Flat Expense Splitter" [level=3]
  - article:
    - img "Screenshot of the tip calculator web page"
    - heading "Tip Calculator" [level=3]

Headings go in order (h1 → h2 → h3), so screen-reader users can jump between them.

Lighthouse (a vehicle check-up)

Lighthouse is, in Google's words, "an open-source, automated tool to help you improve the quality of web pages". Run it from Chrome DevTools (the Lighthouse tab), the command line (npx lighthouse <url>), a Node module, or PageSpeed Insights. Main scores out of 100:

Check-up Lighthouse Means
engine and speed Performance how fast the page loads
can everyone use it Accessibility contrast, alt text, labels...
safety checks Best Practices no console errors, safe links...
easy to find SEO (search engine optimisation) can search engines read it

Run 1: a 1.5 MB photo

ravi@laptop:~/projects/portfolio$ npx lighthouse http://localhost:8088/
Performance 100 · Accessibility 100 · Best Practices 96 · SEO 100
total-byte-weight        Total size was 1,660 KiB
image-delivery-insight   Improve image delivery: Est savings of 1,565 KiB
errors-in-console        Failed to load resource: ... 404 (File not found)
                         http://localhost:8088/favicon.ico

A 3000px photo shown in a 240px circle.

ravi@laptop:~/projects/portfolio$ claude -p "Lighthouse says 'Improve image delivery: Est savings of 1,565 KiB'. me.jpg is a 1.5 MB, 3000x3000 photo but it's shown at only 240px. Make a smaller copy called me-480.jpg (480x480, good quality, Pillow is installed) and use it in index.html. Keep me.jpg as the original." --allowedTools Read Edit "Bash(python3:*)"
... python3 -c "... im.resize((480,480), Image.LANCZOS).save('me-480.jpg', quality=85 ...)"
-rw-r--r-- 1 root root    8137 me-480.jpg
-rw-r--r-- 1 root root 1567791 me.jpg
Reply: "- Why 480: that's 2x the 240px display size, so it stays sharp on
   retina screens. ...
 - Size looks small: 8 KB is low for a 480px photo ... Open the page and
   check that it looks right before you ship it.
 - Width attribute: the <img> still has width="220" height="220", which
   doesn't match the 240px you described. ...
 I didn't re-run Lighthouse."
ravi@laptop:~/projects/portfolio$ npx lighthouse http://localhost:8088/
total-byte-weight        Total size was 136 KiB
image-delivery-insight   Est savings of 29 KiB

1,660 KiB → 136 KiB, about 12 times lighter. Scores: Performance 100 · Accessibility 100 · Best Practices 96 · SEO 100. The 96 is one console error: favicon.ico (the tiny tab icon browsers request automatically) not found.

A real contrast bug a perfect score missed

The agent added an automatic dark mode. Lighthouse had tested only light mode. With Chrome forced into dark mode:

$ npx lighthouse http://localhost:8088/ --only-categories=accessibility \
    --chrome-flags="--headless=new --force-dark-mode --blink-settings=preferredColorScheme=0"
Accessibility 92
color-contrast  Background and foreground colors do not have a sufficient contrast ratio.
  <a class="button" href="#projects">
  Element has insufficient color contrast of 3.04 (foreground color: #ffffff,
  background color: #8b85ff, font size: 12.0pt (16px), font weight: normal).

Contrast ratio compares the brightness of text and background: 1:1 is invisible, 21:1 is black on white. WCAG (the Web Content Accessibility Guidelines) say normal text needs at least 4.5:1, large text (18pt, or 14pt bold) 3:1.

ravi@laptop:~/projects/portfolio$ claude -p "Lighthouse in dark mode says: ... insufficient color contrast of 3.04 (foreground color: #ffffff, background color: #8b85ff ...). In light mode it's fine. Fix the dark-mode button contrast so it's at least 4.5:1. Change only what's needed." --allowedTools Read Edit
+@media (prefers-color-scheme: dark) {
+  /* white on #8b85ff is only 3.04:1; dark text gives ~6:1 */
+  .button { color: var(--bg); }
+}
"I haven't re-run Lighthouse. By my calculation the contrast against the
 #8b85ff background is about 6:1, up from 3.04."
Accessibility 100      (dark mode, re-run)
button: rgb(18, 20, 28) on rgb(139, 133, 255)   → contrast 6.04 : 1

The AI's "about 6:1" was a claim; we measured 6.04:1.

Press Tab: focus moves from link to link and the focused one gets an outline (the focus ring). After three presses, "Projects" is outlined; Enter follows the link. Never let an AI remove the outline to look cleaner.

<li>Email: <a href="mailto:ravi@example.com">ravi@example.com</a></li>
<li>GitHub: <a href="https://github.com/ravi-builds" target="_blank" rel="noopener">github.com/ravi-builds</a></li>
  • mailto: opens the visitor's email app with the address filled in.
  • target="_blank" opens a new tab; rel="noopener" stops the new tab from controlling this page. Use them together.
ravi@laptop:~/projects/portfolio$ git log --oneline
76ea957 Dark-mode button contrast
bf8db7d Same-height screenshots
526d868 Smaller photo (480px)
5c91ef2 Show whole screenshots
0c4c601 Portfolio v1 (AI)

Accessibility checklist

  1. Every image has meaningful alt text (decorative: alt="")
  2. Text contrast at least 4.5:1, in light and dark mode
  3. Headings in order: h1 → h2 → h3
  4. Tab through everything; the outline always shows
  5. Links say where they go (not "click here")
  6. Test at 360px and on a laptop

Lighthouse helps; your eyes and keyboard finish the job.

Common mistakes (real)

What happened What you see Why Fix
object-fit: cover on screenshots Balance column cut off on a phone cover crops to fill the box contain + a fixed height
fixing for the phone only a giant card on the laptop a fix for one screen can break another re-test every screen after every change
a 3000px photo shown at 240px 1,660 KiB page the browser downloads every pixel a 480px copy: 136 KiB
trusting a perfect score dark mode: contrast 3.04, Accessibility 92 Lighthouse tested light mode only test dark mode; 4.5:1

Mini project

Build your own portfolio with any AI tool: About (photo), Projects (2-3 cards), Skills, Contact. Test at 360px, on a laptop and in dark mode; run Lighthouse (Chrome DevTools → Lighthouse); fix one finding with a one-change prompt that pastes the exact message.

What a good outcome looks like

No horizontal scrolling at 360px; whole screenshots; every image with meaningful alt text; photo resized near its display size; Accessibility 100 in light and dark mode; Tab reaches every link with a visible outline; one commit per fix.

Practice questions

  1. What does <meta name="viewport" content="width=device-width, initial-scale=1"> do?
Answer

It tells phones to lay out the page at their real width instead of pretending to be a wide desktop screen and shrinking it.

  1. Flexbox or grid for a row of cards that should become 2 columns on laptops and 1 on phones?
Answer

Grid: grid-template-columns: 1fr; and, inside @media (min-width: 700px), repeat(2, 1fr).

  1. object-fit: cover vs contain?
Answer

cover fills the box and crops the overflow; contain fits the whole image inside, leaving empty bands.

  1. Write good alt text for a screenshot of a tip calculator showing ₹366.67 per person.
Answer

For example: "Tip calculator showing ₹1,000 with a 10% tip split between 3 people: ₹366.67 each".

  1. Why can Lighthouse say 100 for accessibility when the page has a contrast problem?
Answer

It only tests what it renders: here the light colour scheme. Dark mode, keyboard use and many content issues need your own checks.

Quiz

.cards { display: grid; grid-template-columns: 1fr; }
@media (min-width: 700px) {
  .cards { grid-template-columns: ???; }
}

A) 2px · B) repeat(2, 1fr) · C) flex-direction: row · D) object-fit: cover

Answer

B. Two equal columns, only at 700px and wider; phones keep one column.

Interview questions

  1. What is responsive design and how do you implement it? One page that adapts to screen width: a viewport meta tag, mobile-first CSS, flexible layouts (flexbox/grid) and media queries for wider screens; test at real widths.
  2. Flexbox vs grid? Flexbox lays items out in one direction (a row or a column); grid lays them out in rows and columns at once.
  3. Name three accessibility basics. Meaningful alt text, sufficient colour contrast (4.5:1 for normal text), and full keyboard access with a visible focus indicator. Also: ordered headings and labelled form fields.
  4. How do you speed up a page with large images? Resize and compress images to roughly their display size (2× for high-density screens), use modern formats, lazy-load below-the-fold images, and measure with Lighthouse.

Glossary

Term Meaning (plain words) Example
Portfolio a website showing who you are and what you built Ravi's site
<section> one part of a page About, Projects
<nav> the menu of links the top bar
Jump link a link to a place on the same page href="#projects"
Responsive design one page that adapts to any screen width phone vs laptop
Viewport meta tag tells phones to use their real width width=device-width
Mobile-first write phone styles first, then add for wider screens one column first
Media query CSS that applies only when a condition is true @media (min-width: 700px)
Pixel (px) a dot on the screen; CSS's basic unit 360px phone
Flexbox lays items out in one row or one column display: flex
Grid lays items out in rows and columns display: grid
fr one fraction of the free space in a grid repeat(2, 1fr)
object-fit how an image fills its box cover, contain
aspect-ratio a box's width-to-height shape 16 / 10
Alt text what an image says to someone who can't see it alt="Photo of Ravi"
Screen reader an app that reads a page aloud used by blind people
Accessibility everyone can use the page contrast, keyboard, alt text
Accessibility tree the page as assistive tech sees it: roles and names img "Photo of Ravi"
Lighthouse Google's open-source automated page-quality tool scores out of 100
Performance how fast a page loads 100
Best Practices Lighthouse's checks for errors and safe patterns 96
SEO search engine optimisation: can search engines read the page 100
KiB kibibyte, 1,024 bytes (about a kilobyte) 136 KiB
Favicon the small icon on a browser tab favicon.ico
Dark mode a dark colour scheme the device asks for prefers-color-scheme: dark
Contrast ratio brightness difference of text vs background 3.04:1 fails, 6.04:1 passes
WCAG Web Content Accessibility Guidelines 4.5:1 for normal text
Focus ring the outline showing which element the keyboard is on Tab → "Projects"
mailto: a link that opens an email app mailto:ravi@example.com
target="_blank" open a link in a new tab GitHub link
rel="noopener" the new tab can't control this page with _blank
Pillow a Python image library resizing me.jpg

Summary

  • A portfolio is one page in sections, with jump links to each id.
  • Responsive design: viewport meta tag, mobile-first CSS, media queries; flexbox for one direction, grid for rows and columns.
  • cover crops, contain fits; a fix for one screen can break another, so re-test every screen.
  • Alt text on every image; resize images to how they're shown (1,660 KiB → 136 KiB).
  • Lighthouse is a check-up, not a guarantee: a 100 hid a dark-mode contrast failure (3.04 vs the 4.5:1 rule).
  • Test the keyboard (focus ring) and the contact links.

Next episode: Project: a to-do app with local storage: state, add/edit/delete, localStorage, JSON and edge cases.