AGENT SKILL

portfolio-website-design

Build professional portfolio websites — dark or light theme, glassmorphism cards, founder/engineer positioning — with full deployment (Vercel / GitHub Pages).

License 许可
MIT
最近更新
2026-08-16
Stars
★ 0
Forks
0

01 前言 Front Matter

name
portfolio-website-design
author
Hermes Agent
license
MIT
version
1.2.0
metadata
{ "hermes": { "tags": [ "design", "html", "css", "portfolio", "glassmorphism", "ux", "ui", "vercel", "deployment" ], "related_skills": [ "static-site-deployment", "claude-design", "popular-web-designs" ] } }
platforms
[ "linux", "macos", "windows" ]
description
Build professional portfolio websites — dark or light theme, glassmorphism cards, founder/engineer positioning — with full deployment (Vercel / GitHub Pages).

02 资源文件 7

03 SKILL.md 正文

Portfolio Website Design

Build a complete, deployable portfolio site that positions the user professionally. Supports dark and light themes with glassmorphism cards, responsive layout, and a clear information hierarchy.

When To Use

Use this skill when the user requests:

  • A complete portfolio or personal website
  • A developer / engineer / founder landing page
  • Professional online presence with project showcase
  • Any request to "prepare my portfolio"

Key Features

  1. Glassmorphism Design:

    • Semi-transparent card backgrounds with backdrop blur
    • Works on both dark and light themes (different CSS variables per theme)
    • Subtle borders for depth without overwhelming content
    • Ensure proper contrast — text must be readable on blurred backgrounds
  2. Color Palette (choose one):

    • Dark Tech (default for engineers/AI/robotics founders): bg: #0a0a0f, accents: Emerald #10b981 + Amber #f59e0b
    • Light Professional (default for consultants/designers): white bg, Olive #3D9970 + Light Green #A8E6CF accents
    • Always pick the palette that matches the user's brand and industry — ask if uncertain
  3. Responsive Layout:

    • Mobile-first approach with CSS Grid + Flexbox
    • Media queries for all screen sizes
    • Hamburger menu on mobile
  4. Complete Sections:

    • Hero with headline + CTA
    • About / personal story
    • Expertise / services / skills (3-column cards)
    • Ventures / Companies / Projects (for founders with multiple ventures)
    • Research or technical depth section (for engineers)
    • Philosophy / operating principles (optional, adds personality)
    • Contact with email + social links
    • Footer

Honesty Audit: Claims → Receipts

Before building or rebuilding a portfolio, audit every claim against the user's actual artifacts (disk, repos, deployed projects). A portfolio's job is to show what has been DONE, not what is INTENDED. Every public claim must survive an interview. This is a core user preference (Truth Over Ego) — a claim with no receipt is a liability, not a feature.

When to run this

  • Responding to critique like "your site overclaims" or "you've shipped nothing"
  • Rebranding (company name change, identity shift)
  • Before applying to programs / accelerators / scholarships where claims get checked

Workflow

  1. Locate the source, not just the live URL — find the local project dir (e.g. ~/Projects/portfolio-website/). Curl the live site to see served HTML, but audit the source files for edits.
  2. Map the claim surface — title/meta, nav CTAs, hero, about, projects (often a JS data file like js/projects.js), research (often js/research.js), contact, footer, console easter egg (js/main.js).
  3. Verify every claim against disk — check ~/Projects/ for real artifacts (code, PDFs, STLs, protos, market reports). A venture with no on-disk artifact gets removed or relabeled "planned/concept". Count real things: find <project> -type f | wc -l, prototype dirs, build outputs.
  4. Fix dead links to real artifacts — if an artifact exists but the site links elsewhere (e.g. paper PDF present, button points at a GitHub profile), point the button at the real file.
  5. Label research honestly — "proof-of-concept / educational pipeline", NOT "drug discovery" for a 2-qubit VQE toy model. Mark planned items "Roadmap — not yet run". The page can stay up; the framing must be true.
  6. Brand coherence — title, meta, footer, console log, and JS data (lab: fields) must all name the SAME single company. Flag mismatches (site says UMG Africa, research data says Version Extreme Cooperation) and email-domain lag after a rebrand — change with user confirmation, don't silently pick.
  7. Receipts over aspirational metrics — replace counters like "5 Active Ventures" / "∞ First Principles" with verifiable numbers: "1 Company / 52 Prototypes Built / 4 R&D Programs". Every number must be countable from disk.
  8. Truthful role titles — "Form 5 student and founder", never "engineer" before credentials exist. Navbar "Open to opportunities" instead of "Available for projects" when nothing is shipped.
  9. Deploy + verify — vercel deploy --prod --yes, then curl the LIVE aliased URL: grep for expected new strings, grep -c removed strings (must be 0), new asset paths return 200 (see static-site-deployment).

Pitfalls

  • JS countup counters render "0" in raw HTML / static screenshots. A critic can screenshot "0 Active Ventures" while the page animates to the real value. Audit the data-target attribute, not the rendered text; when responding to such a critique, check the JS before accepting the claim.
  • Hidden-but-present images — a real <img src="assets/images/profile.jpg" style="display:none"> next to a "Your photo here" placeholder. Enable it (drop the inline style) instead of leaving the placeholder.
  • JS data files are part of the claim surface — editing index.html alone leaves js/projects.js / js/research.js / the console easter egg contradicting the new identity. Grep the whole source dir for stale brand strings before deploying.

Workflow

Phase 0: Research (DO FIRST — most important step)

Before writing any code, research the user's background:

  1. Obsidian vault — search for about me.md, company notes, project descriptions
  2. GitHub repos — check for existing projects, READMEs, portfolio content
  3. Previous conversations (session_search) — look for personal details, preferences, past portfolio discussions
  4. Extract structured info: name, age, location, title, companies/products with descriptions, expertise areas, research domains, philosophy
  5. Identify the core narrative — is this a founder, an engineer, a researcher, or all three? The hero headline and about section must tell one coherent story.

Phase 1: Planning

  • Define site structure based on extracted content
  • Choose dark or light theme based on user's industry (dark for tech/AI/engineering, light for design/consulting)
  • Map each Obsidian note section to a page/section
  • Decide on a hero headline that captures the user's unique angle

Phase 2: Design System

  • Establish color palette (CSS custom properties)
  • Define typography hierarchy (Inter for body, JetBrains Mono / Fira Code for tech elements)
  • Create glassmorphism component styles (dark glass rgba(255,255,255,0.03) for dark themes, light glass rgba(255,255,255,0.85) for light themes)
  • Plan responsive breakpoints

Phase 3: Implementation

  • Create directory structure: index.html, css/styles.css, js/main.js
  • Write semantic HTML with sections matching extracted content
  • Implement CSS with full glassmorphism, gradients, and animations
  • Add JavaScript for: scroll effects, mobile menu, smooth anchor nav, parallax, scroll-triggered reveals
  • Use Font Awesome CDN for icons

Phase 4: Favicon & Brand Assets

Generate a complete favicon set before deployment — every portfolio needs a proper icon, not a default browser favicon.

Required files (all in project root):

File Size Purpose
favicon.svg Scalable Modern browsers (crisp at any size, supports gradients)
favicon-32x32.png 32×32 Standard browser tab
favicon-16x16.png 16×16 Bookmarks bar, tiny contexts
favicon-48x48.png 48×48 Windows pinned tabs
apple-touch-icon.png 180×180 iOS home screen
favicon.ico Multi-size Legacy browser fallback (16+32+48+256)

Generation approach — Use Python/Pillow for PNGs/ICO, hand-write the SVG:

from PIL import Image, ImageDraw

def create_favicon(size):
    img = Image.new('RGBA', (size, size), (0, 0, 0, 0))
    draw = ImageDraw.Draw(img)
    s = size / 256.0  # scale factor
    # Dark rounded-square background
    draw.rounded_rectangle([0, 0, size-1, size-1], radius=int(40*s), fill=(18, 18, 24, 255))
    # Brand mark (letter, shape, or symbol) in accent color
    # ... draw your design ...
    return img

# Generate all sizes
for name, sz in [('favicon-16x16.png',16), ('favicon-32x32.png',32),
                  ('favicon-48x48.png',48), ('apple-touch-icon.png',180)]:
    create_favicon(sz).save(name)

# ICO with multiple sizes
create_favicon(256).save('favicon.ico', format='ICO', sizes=[(16,16),(32,32),(48,48),(256,256)])

SVG favicon — write by hand (Pillow can't produce SVG). Use <linearGradient> for polish, keep geometry simple so it reads at 16×16.

HTML <link> tags — add to <head> after <title>:

<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
<link rel="icon" type="image/x-icon" href="/favicon.ico" />

Browsers pick the best format from this list — SVG gets priority on modern browsers, ICO is the legacy fallback.

Design guidelines:

  • Use the site's accent color for the brand mark (emerald for dark tech, olive for light)
  • Dark background (#121218) works universally — the mark pops against it
  • Keep geometry bold and simple — fine detail vanishes at 16×16
  • A small accent dot or secondary element adds character without clutter
  • Match the favicon style to the site's overall design language

Verification: After deploy, curl the favicon URL directly to confirm HTTP 200:

curl -sL -o /dev/null -w "%{http_code}" https://your-site.vercel.app/favicon.svg

Reference: See references/favicon-generation-workflow.md for the full script and SVG template used on Ibrahim's portfolio.

Phase 4b: Profile Image Swap

When the site has a placeholder <div> instead of a real photo (common in scaffolded portfolios):

  1. Check the HTML — look for commented-out <img> tags near a placeholder div (e.g. <!-- <img src="..." class="profile-img" ... --> alongside a div.image-placeholder with an icon and "Your photo here" text)
  2. Check the JS — there's usually toggle logic (getElementById('profileImg') / getElementById('profilePlaceholder')) that shows the image and hides the placeholder on load. This is already wired — just uncomment the <img>.
  3. Uncomment the <img> tag and update src and alt text.
  4. Place the image file at the path referenced in src (e.g. assets/images/profile.jpg).
  5. Crop tall photos — if the source photo is a tall portrait (e.g. 597×1280), center-crop to 4:5 ratio focusing on the face/upper body before saving. The CSS object-fit: cover handles the final display, but a extreme aspect ratio wastes most of the image.
  6. Optimize — resize to max 800px wide, JPEG quality 90%. Profile images should be under 100KB.
  7. Verify — deploy, curl the image URL for HTTP 200, then visually confirm it renders in the hero section.
from PIL import Image
img = Image.open('source_photo.jpg')
w, h = img.size
# Center-crop to 4:5
crop_h = int(w / (4/5))
img_cropped = img.crop((0, 0, w, crop_h))
# Resize for web
img_final = img_cropped.resize((400, 500), Image.LANCZOS)
img_final.save('assets/images/profile.jpg', 'JPEG', quality=90)

Phase 5: Deployment Config

  • Create vercel.json with cleanUrls, security headers, and cache headers for static assets
  • Verify Vercel CLI is logged in (vercel whoami)
  • Deploy with vercel deploy --prod --yes

Phase 6: Verification

  • Check live URL returns HTTP 200 on all paths
  • Verify favicon files serve correctly (curl each one)
  • Verify CSS, JS, and icon CDN resources load
  • Confirm responsive layout at 1440px, 768px, 375px
  • Test smooth scrolling and mobile menu interaction
  • Verify all sections render with correct content

HTML Structure

portfolio-website/
├── index.html          ← Single-page scroll site
├── vercel.json         ← Vercel deployment config
├── favicon.svg         ← SVG favicon (scalable, modern browsers)
├── favicon-*.png       ← PNG favicons (16, 32, 48px)
├── favicon.ico         ← Legacy ICO (multi-size)
├── apple-touch-icon.png ← iOS home screen (180×180)
├── css/
│   └── styles.css      ← All styles (no separate theme files)
├── js/
│   └── main.js         ← Interactivity + animations
└── assets/
    └── images/         ← Optional project images, profile pic

Keep it single-page scroll for portfolios under 8 sections. Multi-page only if the user explicitly requests it.

CSS Guidelines

Dark Glass (default for tech portfolios):

.glass-card {
  background: rgba(255, 255, 255, 0.03);
  border: 1px solid rgba(255, 255, 255, 0.06);
  backdrop-filter: blur(12px);
  -webkit-backdrop-filter: blur(12px);
  transition: all 0.3s ease;
}
.glass-card:hover {
  background: rgba(255, 255, 255, 0.05);
  border-color: rgba(255, 255, 255, 0.1);
}

Light Glass (alternate for light themes):

.glass-card {
  background: rgba(255, 255, 255, 0.85);
  border: 1px solid rgba(255, 255, 255, 0.18);
  box-shadow: 0 8px 32px rgba(31, 38, 135, 0.15);
  backdrop-filter: blur(10px);
}

Dark Theme Color Variables:

:root {
  --bg-primary: #0a0a0f;
  --bg-card: rgba(255, 255, 255, 0.03);
  --border-glass: rgba(255, 255, 255, 0.06);
  --text-primary: rgba(255, 255, 255, 0.9);
  --text-secondary: rgba(255, 255, 255, 0.4);
  --accent-primary: #10b981;   /* emerald */
  --accent-secondary: #f59e0b; /* amber */
  --glass-bg: rgba(255, 255, 255, 0.03);
}

Scroll-Triggered Reveal (adds polish):

.reveal {
  opacity: 0;
  transform: translateY(24px);
  transition: opacity 0.7s cubic-bezier(0.16, 1, 0.3, 1),
              transform 0.7s cubic-bezier(0.16, 1, 0.3, 1);
}
.reveal.visible {
  opacity: 1;
  transform: translateY(0);
}

JavaScript Functionality

  1. Navbar — navbar-scrolled class on scroll > 60px for backdrop blur
  2. Mobile Menu — hamburger toggle with close-on-link-click
  3. Smooth Scroll — all href="#section" links with 80px navbar offset
  4. Reveal Animations — IntersectionObserver on .glass-card and headings
  5. Parallax Glow — optional: hero background orbs track mouse position
  6. Console Easter Egg — subtle branded message in devtools

Verification (Final Checklist)

Before declaring done:

  1. All files created with correct structure
  2. HTML is valid and semantic
  3. Glassmorphism renders properly (not just code — check visually)
  4. Text contrast is sufficient on glass cards
  5. Mobile menu opens and closes
  6. Smooth scroll works to every section
  7. Vercel deployment returns HTTP 200 on all routes
  8. CSS/JS have immutable cache headers in vercel.json
  9. Content matches what was extracted from the user's vault — no hallucinated projects

Pitfalls

  • Don't preselect colors. The Olive/LightGreen/Amber palette from v1.0 is one option among many. Dark emerald/amber is more appropriate for tech founders. Always match the palette to the user's industry.
  • Don't skip research. Building a portfolio without first reading the user's vault/repos produces generic output that misses their actual narrative.
  • Glassmorphism overuse hurts readability — use it on section cards, not on every element.
  • Dark glass with white text needs careful contrast. Use rgba(255,255,255,0.9) for headings, rgba(255,255,255,0.4) for body — never pure black or pure white.
  • Template-first thinking. The old SKILL.md referenced templates that didn't exist. For single-page portfolios, build from scratch — it's faster and more flexible than editing a generic template.
  • Deploy is part of the deliverable. Don't stop at file creation. The user experiences the site at a URL, not in a directory tree.
  • Mobile-first is not optional. Test at 375px before delivering. Glassmorphism effects degrade on low-end mobile browsers — backdrop-filter may not be supported.
  • Company tags. For founder portfolios with multiple ventures, add status badges (✅ Live, 🟡 Beta, 🔧 Build, 🥦 Research, 🔬 Concept) to each venture card — this shows maturity at a glance.
  • Don't ship with a default favicon. A ⚡ emoji or browser-default icon looks unfinished. Generate a proper favicon set (SVG + PNG + ICO) using the Phase 4 workflow. It takes 5 minutes and elevates perceived quality immediately.
  • Research sections need data-driven content. When building a research/showcase section (e.g. quantum computing, drug discovery), pull real data from authoritative sources (PDB, PubChem, arXiv) and render it in structured tables/cards — not generic placeholder text. Use JavaScript to render data from a researchData object so the HTML stays clean and the data is easy to update. Example: protein targets with PDB IDs, drug candidates with molecular formulas and binding energies, method descriptions with equations.
  • Validate scientific claims against system capabilities. Before publishing performance claims (e.g. "screens 10,000 compounds"), verify the math: qubits → database size (2^n), Grover iterations → actual queries. A 10-qubit system screens 1024 candidates in ~25 queries, not 10,000. If PDB API calls fail or return empty, fall back to known literature data and note the source. Always cross-check PDB IDs exist at rcsb.org before publishing them.
  • Vercel may not serve separate JS/CSS files. When new .js or .css files return 404 despite correct paths, inline them into index.html using <style> and <script> tags. This is reliable because the single HTML file always deploys. Apply this proactively when adding significant new sections (research, blog, etc.) to avoid deployment surprises.

Related

See references/portfolio-design-session.md for the original Ibrahim build pattern (dark theme, glassmorphism, Vercel deploy) and references/portfolio-honesty-rebuild-2026-08.md for the claims→receipts rebuild (UMG Africa → Version Extreme Cooperation, Jenga/Hydrolith removed, quantum relabeled, verified live deploy).

04 同仓库更多 Skills