Communitygithub.com

Portfolio Site Builder

Build a distinctive personal portfolio for a designer, developer, photographer, writer, or freelancer, with clear structure, deliberate type, and restrained motion.

What is Portfolio Site Builder?

A reusable skill for personal portfolio sites: introduce the person, show the work, and keep the page from looking like a generic template.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MorganMarshall/ZeroSkills/tree/HEAD/skills/zero-web-design-portfolio

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Design Portfolio

Build a portfolio that does three things well: introduces the person, shows their work with context, and makes it easy to get in touch. A portfolio is not a landing page — visitors want to browse, not be funneled. Design for discovery.

Work in three passes

  1. Plan. Decide the direction and structure before writing code (see below).
  2. Build. Implement the plan with design tokens, so every color, size, and space comes from one system.
  3. Review. Critique the result against the checklist at the end, and fix what falls short.

If the user's brief names a style, palette, font, or layout, follow it exactly. Their words always win over the defaults in this skill.

1. Plan before code

Write a short plan covering:

  • Who this is and what they do. The person's role, discipline, seniority level, and who will visit the site (recruiters, clients, collaborators, other designers). If the brief doesn't say, propose one in a sentence and state that you assumed it.
  • Aesthetic direction. Pick one (editorial minimal, soft technical, warm crafted, stark documentary, experimental) and commit to it, with a one-line reason tied to the person's work. A photographer's portfolio and a front-end developer's should look different.
  • Tokens. Four to six named colors as hex values, the typefaces and their roles, the spacing unit, the radius scale, and the shadow style. Portfolio sites often benefit from very light or no accent — let the work carry color.
  • Hero idea. Open with who they are and a single representative project, or a tight two-line intro with a link into the work. Avoid animated typing effects and stock stock-photo imagery.

Then check the plan against the brief. If a part of it is what you would produce for any similar request, change that part and note what you changed. A generic plan produces a generic portfolio.

2. Design system

Color

  • Define the palette as CSS custom properties on :root: a neutral scale (background, surface, border, muted text, text), one primary accent, and optionally one secondary.
  • Portfolio sites often look strongest with muted or no accent. Let the work — images, screenshots, case studies — provide the color. Use the accent only for links, active states, and one or two deliberate highlights.
  • Support light and dark with prefers-color-scheme by redefining the tokens, not by overriding individual rules.
  • Keep contrast at 4.5:1 for body text and 3:1 for large text and UI borders.

Typography

  • Use at most two families. If two, give them clearly different roles (a display face for the name and headlines, a text face for reading).
  • Choose faces for the discipline rather than the first default that comes to mind, and load web fonts with font-display: swap and a full fallback stack.
  • Build a type scale (ratio around 1.2 to 1.333) and make headlines fluid with clamp().
  • Set the person's name and section headings tight (line-height 1.05 to 1.15, slightly negative letter-spacing at large sizes). Body text open (16 to 18px, line-height 1.5 to 1.7).
  • Keep line length between 45 and 75 characters (max-width: 65ch is a good default).

Layout and spacing

  • Use a 4/8px spacing scale defined as tokens, and use it everywhere.
  • Give sections room to breathe: 80 to 120px vertical padding on desktop, 48 to 64px on mobile.
  • Constrain the container to about 1100 to 1200px, and keep reading text narrower.
  • Build mobile-first with CSS grid and flexbox. Everything must work from 360px up with no horizontal scrolling; wide images, code, and diagrams scroll inside their own container.
  • Vary the rhythm between sections (density, alignment, scale) instead of repeating one block. Left-align long text.
  • Use a clear grid for the project gallery (two or three columns on desktop, one on mobile). Vary aspect ratios between projects when the assets allow — not every project needs a uniform card.

Surfaces and components

  • Use one radius system with two or three sizes, matched to hierarchy (smaller on inputs and buttons, larger on containers).
  • Use 1px low-contrast borders instead of heavy shadows for project cards. Portfolio work should look like it sits on the page, not stacked above it.
  • Give every interactive element hover, :focus-visible, active, and disabled states. Never remove an outline without replacing it.
  • One primary button per view, labeled specifically ("View project", "Get in touch"), with a touch target of at least 44px.
  • Project cards should show: the project title, a short descriptor (role, year, tech), and the hero image or screenshot. No generic "Feature One" labels.

Motion

  • Use 150 to 250ms ease-out transitions for state changes, so motion shows what changed.
  • Prefer one orchestrated moment (a page-load sequence or a hero reveal) over entrance animations on every section.
  • Animate only transform and opacity.
  • Respect prefers-reduced-motion by turning off non-essential motion.
  • For the project gallery, a subtle hover scale or border reveal is enough. Don't add hover overlays that obscure the project image.

Imagery and icons

  • Never ship broken or placeholder images. Use the assets provided, or generate clean CSS/placeholder blocks that signal where the image goes (labelled with the project name).
  • Use consistent aspect ratios for project thumbnails, or a masonry-style grid if the assets vary widely.
  • Keep one icon set with one stroke weight for social links and UI chrome. Write meaningful alt text.
  • For case studies, use real screenshots, mockups, or photos. No lorem ipsum and no wireframe sketches as final work.

3. Page structure

A portfolio typically follows this arc:

  • Hero: who they are (name + role), one sentence about what they do or their current focus, and a clear link into the work. Contact details or social links nearby.
  • Selected work: a curated gallery of 4 to 8 projects. Each item links to a detail page or expanded section. Quality over quantity.
  • About (optional): a brief paragraph about background, interests, and where to find them. A photo if they have one — candid is fine, no need for a headshot unless they want it.
  • Contact: a simple way to reach them — email link, contact form, or links to preferred channels. Make it visible without scrolling on mobile.
  • Footer: social links (GitHub, LinkedIn, Dribbble, Instagram, etc.), copyright, and maybe a short tagline.

Case study / project detail pages:

  • Project name, role, year, tech stack, and link to the live project or repo.
  • The problem or context in a paragraph or two.
  • Screenshots, mockups, or walkthroughs with brief annotations.
  • What they learned or what they'd do differently (this is what separates real portfolios from highlight reels).
  • A link to the next project for continued browsing.

Copy

  • Write real, specific copy. No lorem ipsum and no "Feature One".
  • Use the person's actual name and role, not a fictional persona.
  • Write from the visitor's point of view in plain words, sentence case, and active voice.
  • Make project titles say what the project is, not clever abstractions. "Client CRM dashboard" beats "Synergy engine."
  • Keep project descriptions to two or three sentences: what it is, what you did, and the outcome if there was one.

Technical floor

  • Use semantic HTML (header, nav, main, section, footer), a single h1, and heading levels in order.
  • Make everything keyboard navigable, add a skip link on long pages, and use ARIA only where native elements fall short.
  • Include the viewport meta tag, a title, a description, and a favicon.
  • Keep dependencies minimal. A small portfolio can be one self-contained HTML file with inline CSS and JS. In an existing project, follow its stack and conventions instead of introducing new ones.
  • Prevent layout shift by setting width and height or aspect-ratio on media.
  • Link to external repos and live demos with clear labels ("GitHub", "Live site").

Common tells to avoid

These show up on portfolios built without a point of view:

  • A generic "Hi, I'm [Name], a [Role]" hero with a stock illustration or pixel art avatar.
  • Skill bars or percentage bars ("90% HTML", "80% JavaScript"). Nobody reads them and they're meaningless.
  • A uniform card grid where every project has the same aspect ratio, shadow, and hover effect.
  • An animated timeline that's hard to read on mobile.
  • Every project card with the same gradient overlay on hover.
  • A "download resume" button that actually links to a Google Docs URL.
  • A page full of links with no work to look at.

Final review

Before presenting the work, check it (with a screenshot or browser if available):

  • Spacing and alignment follow the scale, with no stray values.
  • Contrast and focus rings pass, and every interactive state exists.
  • Layout holds at 360px, tablet, and desktop.
  • Nothing is placeholder, broken, or unlabeled.
  • The work gallery feels curated, not exhaustive — four strong projects beat ten mediocre ones.
  • A stranger can say who the person is, what they do, and how to contact them within five seconds of seeing the home page.
  • Every project links to a real place or a plausible detail page, and external links are clearly labelled.

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

Related Skills