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
- 参考文档references/favicon-generation-workflow.md4.8 KB
- 参考文档references/portfolio-design-session.md5.4 KB
- 参考文档references/portfolio-honesty-rebuild-2026-08.md3.0 KB
- 参考文档references/scientific-data-api-patterns.md2.4 KB
- 参考文档templates/index.html4.7 KB
- 脚本templates/main.js970 B
- 其他templates/styles.css3.8 KB
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
-
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
-
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#A8E6CFaccents - Always pick the palette that matches the user's brand and industry — ask if uncertain
- Dark Tech (default for engineers/AI/robotics founders):
-
Responsive Layout:
- Mobile-first approach with CSS Grid + Flexbox
- Media queries for all screen sizes
- Hamburger menu on mobile
-
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
- 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. - Map the claim surface — title/meta, nav CTAs, hero, about, projects (often a JS data file like
js/projects.js), research (oftenjs/research.js), contact, footer, console easter egg (js/main.js). - 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. - 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.
- 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.
- 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. - 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.
- 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.
- Deploy + verify —
vercel deploy --prod --yes, then curl the LIVE aliased URL: grep for expected new strings,grep -cremoved 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-targetattribute, 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:
- Obsidian vault — search for
about me.md, company notes, project descriptions - GitHub repos — check for existing projects, READMEs, portfolio content
- Previous conversations (session_search) — look for personal details, preferences, past portfolio discussions
- Extract structured info: name, age, location, title, companies/products with descriptions, expertise areas, research domains, philosophy
- 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 glassrgba(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.mdfor 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):
- Check the HTML — look for commented-out
<img>tags near a placeholder div (e.g.<!-- <img src="..." class="profile-img" ... -->alongside adiv.image-placeholderwith an icon and "Your photo here" text) - 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>. - Uncomment the
<img>tag and updatesrcandalttext. - Place the image file at the path referenced in
src(e.g.assets/images/profile.jpg). - 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: coverhandles the final display, but a extreme aspect ratio wastes most of the image. - Optimize — resize to max 800px wide, JPEG quality 90%. Profile images should be under 100KB.
- 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.jsonwith 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
- Navbar —
navbar-scrolledclass on scroll > 60px for backdrop blur - Mobile Menu — hamburger toggle with close-on-link-click
- Smooth Scroll — all
href="#section"links with 80px navbar offset - Reveal Animations — IntersectionObserver on
.glass-cardand headings - Parallax Glow — optional: hero background orbs track mouse position
- Console Easter Egg — subtle branded message in devtools
Verification (Final Checklist)
Before declaring done:
- All files created with correct structure
- HTML is valid and semantic
- Glassmorphism renders properly (not just code — check visually)
- Text contrast is sufficient on glass cards
- Mobile menu opens and closes
- Smooth scroll works to every section
- Vercel deployment returns HTTP 200 on all routes
- CSS/JS have immutable cache headers in vercel.json
- 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-filtermay 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
researchDataobject 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
.jsor.cssfiles return 404 despite correct paths, inline them intoindex.htmlusing<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
web-ui-verification
Verify web UIs via headless Chrome CDP, no vision needed.
test-driven-development
TDD: enforce RED-GREEN-REFACTOR, tests before code.
systematic-debugging
4-phase root cause debugging: understand bugs before fixing.
spike
Throwaway experiments to validate an idea before build.
simplify-code
Parallel 4-agent cleanup of recent code changes.
scroll-driven-3d-websites
Scroll-scrubbed 3D promo sites (Three.js + GSAP).