portfolio-website-design
Create full portfolio websites with glassmorphism effects using olive, light green, and amber color schemes.
- License 许可
- MIT
- 最近更新
- 2026-08-16
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- portfolio-website-design
- author
- Hermes Agent
- license
- MIT
- version
- 1.4.0
- metadata
- { "hermes": { "tags": [ "design", "html", "css", "portfolio", "glassmorphism", "ux", "ui" ], "related_skills": [ "claude-design", "popular-web-designs" ] } }
- platforms
- [ "linux", "macos", "windows" ]
- description
- Create full portfolio websites with glassmorphism effects using olive, light green, and amber color schemes.
02 资源文件 8
- 参考文档references/catppuccin-portfolio-pattern.md20.4 KB
- 参考文档references/circuit-svg-background-pattern.md10.4 KB
- 参考文档references/ibrahim-portfolio-2026.md4.0 KB
- 参考文档references/portfolio-chatbot-implementation.md3.6 KB
- 参考文档references/portfolio-game-implementation.md2.9 KB
- 参考文档templates/index.html4.7 KB
- 脚本templates/main.js970 B
- 其他templates/styles.css3.8 KB
03 SKILL.md 正文
Portfolio Website Design
This skill creates full portfolio websites with modern design elements including glassmorphism effects and a specific color palette of olive, light green, and amber.
When To Use
Use this skill when the user requests:
- A complete portfolio website
- Modern design with glassmorphism effects
- Specific color schemes (olive, light green, amber)
- Responsive layouts for all device sizes
- Professional presentation of projects and services
Design Approaches
Approach A: Glassmorphism (Light)
The classic glassmorphism look — semi-transparent cards on a light or patterned background. Best for creative/design portfolios.
Approach B: Dark Theme + Glass Elements (Hybrid)
A dark background (#08080e range) with glass cards overlaid. The glass provides depth against the dark, while the dark background gives a premium, engineering/product feel. Preferred by technical founders, robotics/AI engineers, and deep-tech builders.
This session produced a hybrid portfolio for a Tanzanian deep-tech founder — see references/ibrahim-portfolio-2026.md for the full case study.
Approach C: Catppuccin Dual-Theme System (Dark/Light Toggle)
A complete dual-theme system using Catppuccin's Mocha (dark) and Latte (light) palettes. The user gets a persistent theme toggle (🌙/☀️) in the navigation bar — their choice is saved to localStorage and survives reloads.
C1: Dual Theme (Toggle Available)
See references/catppuccin-portfolio-pattern.md for the full CSS variables, toggle HTML, and JS implementation.
C2: Dark-Only Mode (No Toggle)
Some founders prefer a permanent dark theme — no light mode, no toggle button, no flash of light on page load. This is common for deep-tech / engineering profiles where dark mode signals a "serious tools" aesthetic.
To convert a dual-theme portfolio to dark-only:
- Remove the light CSS block entirely — delete the entire
[data-theme="light"] { ... }ruleset. Only:root(dark) remains. - Fix the CSS comment — change
:root, [data-theme="dark"]to just:rootand update the comment to reflect dark-only. - Remove the theme toggle HTML — delete the
<button class="theme-toggle" id="themeToggle">element from the nav. - Remove the theme toggle CSS — delete the
.theme-toggle { ... }and.theme-toggle:hover { ... }rule blocks. - Remove the theme toggle JS — delete the entire
const themeToggle = ... addEventListener('click', ...)block. Renumber any remaining JS sections. - Remove
data-themefrom<html>— change<html lang="en" data-theme="dark">to<html lang="en">. The CSS defaults are now dark without needing the attribute. - Replace all toggle-related emojis — the moon/sun on the button and in JS are gone automatically with the toggle removal.
Verification after dark-only conversion:
grep -c '\\[data-theme="light"\\]' index.html # expect 0
grep -c 'themeToggle' index.html # expect 0
grep -c 'Latte' index.html # expect 0
Pitfalls:
- If you remove
data-theme="dark"from<html>but keep[data-theme="dark"]in CSS, the page still works but the selector is an empty constraint. Clean both for a single source of truth. - The
--btn-textvariable (dark text on light buttons) must remain — it's not a light-theme artifact, it's needed for contrast even in dark mode. - The
--glassand--glass-bordervalues for dark mode (semi-transparent white) stay as-is. - Gradient orbs continue working — their
--orb-*-bgvariables were already dark-specific.
Approach D: Progress Bar Skills with Animated Proficiency
For engineering/technical portfolios, replace (or supplement) the standard tag-skill categories with animated progress bars that show proficiency levels by domain. Especially effective for audiences who want to see depth: embedded engineers, AI developers, and mechatronics founders.
Implementation (see references/catppuccin-portfolio-pattern.md for complete code):
<div class="skill-progress-item">
<div class="skill-progress-header">
<span class="skill-name">⚙️ Embedded Systems</span>
<span class="skill-pct">90%</span>
</div>
<div class="skill-progress-track">
<div class="skill-progress-fill" style="width:90%"></div>
</div>
</div>
CSS pattern:
.skill-progress-track: full-width8pxheight,border-radius: 100px, background uses--surface0..skill-progress-fill: height100%,border-radius: 100px,background: linear-gradient(90deg, var(--green), var(--teal)), defaultwidth: 0%, transitions viatransition: width 1.2s cubic-bezier(0.16,1,0.3,1).- The
width: X%is set as an inline style on each.skill-progress-fill. The scroll-reveal (IntersectionObserver) triggers the.visibleclass. Withtransitionon the fill, the bars animate from 0 to their target width when they enter the viewport. No JS needed beyond the existing reveal observer — CSS transition handles the animation. - Container grid:
grid-template-columns: 1fr 1fr(collapses to 1fr below 900px).
Pitfalls:
- Don't set
widthon the fill in CSS — use inlinestyle="width:X%"so each bar has a different value. - Proficiency percentages should be credible, not inflated. A 19-year-old engineer with 90% in everything looks fake. Use 70-90% range for core domains, lower for secondary skills.
- The scroll-reveal animation fires once per element. After the bar animates to its target width, it stays there. No additional JS needed.
Approach E: Integrations / Tools Grid Section
A dedicated section listing tools, platforms, and frameworks the founder works with. Organised into categorical cards with colour-coded icon badges and tag clouds. Best placed after the Skills section, labelled "Tools & Integrations" or "My Stack".
Implementation (full code in references/catppuccin-portfolio-pattern.md):
- 5-card grid (auto-fill, min 260px) with coloured icon badges per category:
- AI & Cloud Platforms (mauve badge)
- PCB Design & CAD (blue badge)
- Languages & Frameworks (green badge)
- Hardware & Embedded (peach badge)
- Agentic & Automation (pink badge)
- Each card: header row with coloured icon
div+ title/subtitle, then a<div class="int-tags">with<span>chips for each tool. - Nav link in the nav bar (e.g. "Tools") that scrolls to
#integrations.
Pitfalls:
- Card icon backgrounds use
color-mix(in srgb, var(--mauve) 20%, transparent)— this adapts to both dark and light themes without hardcoded rgba. - This section works best as a visual complement to the skills section, not a replacement. Skills says "how good I am", Integrations says "what I actually use".
- Some founders prefer SVG icons over emoji for the category header icons. Offer the choice. SVGs look more premium on engineering/technical portfolios. Use inline Lucide-style
<svg>elements withcurrentColorso they adapt to both dark and light themes. - Variant: Brand Logo Tool Chips — Instead of plain
<span>text tags, you can render each tool as a pill with its official logo from the Simple Icons CDN (https://cdn.simpleicons.org/{slug}/fff). See Approach G below for full implementation.
Approach F: Custom SVG Background Texture
For deep-tech / engineering portfolios, replace the grid or solid dark background with a programmatically generated SVG that mirrors the founder's domain:
- Circuit traces: horizontal bus lines, vertical bus lines, diagonal data paths — drawn as thin lines at low opacity (0.02–0.06)
- Glowing vias/nodes: small circles at trace intersections with SVG blur filters (feGaussianBlur)
- Geographic outline: a subtle polygon of the founder's continent/country — grounds the portfolio in place
- Data waveforms:
<polyline>with sine-wave math (sin + sin harmonics) across the full viewport width - Binary / data stream accents: text elements with "01001110" patterns in corners
- Ambient orbs: large blurred radial gradient circles that float via CSS animation (inherits from the orb system)
This background should be extremely subtle (overall opacity 0.03-0.08) — it's a premium texture, not a wallpaper. Content readability always comes first.
See references/circuit-svg-background-pattern.md for the full generation pattern and Python script.
Approach G: Brand Logo Tool Chips (Simple Icons CDN)
For the integrations grid, replace plain <span> text tags with brand logo chips — each tool appears as a small pill with its official logo from the Simple Icons CDN. This dramatically increases visual polish and credibility.
How it works:
<span class="tool-chip">
<img class="tool-logo" src="https://cdn.simpleicons.org/anthropic/fff"
alt="Anthropic" loading="lazy"
onerror="this.style.display='none';this.nextElementSibling.style.display='flex'">
<span class="tool-logo-fallback" style="background:#d97757">A</span>
<span class="tool-chip-name">Anthropic</span>
</span>
The <img> attempts to load the official SVG logo from the CDN. On failure (no icon for that slug), the onerror handler hides the image and reveals the .tool-logo-fallback span — a colored letter-initial badge. This means every tool always has a visual, even obscure ones without a Simple Icons entry.
CSS pattern:
.tool-grid { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 14px; }
.tool-chip {
display: inline-flex; align-items: center; gap: 7px;
padding: 6px 12px; border-radius: 8px;
background: var(--surface0); border: 1px solid var(--glass-border);
transition: all 0.2s; cursor: default;
}
.tool-chip:hover {
transform: translateY(-2px);
border-color: color-mix(in srgb, var(--mauve) 30%, transparent);
}
.tool-chip img.tool-logo { width: 18px; height: 18px; object-fit: contain; flex-shrink: 0; }
.tool-logo-fallback {
width: 18px; height: 18px; border-radius: 4px;
display: none; align-items: center; justify-content: center;
font-size: 10px; font-weight: 700; color: #fff; flex-shrink: 0;
}
.tool-chip-name { font-size: 0.75rem; font-weight: 500; white-space: nowrap; }
Sizing guide: Logo = 18×18px. Chip padding = 6px 12px. These are compact enough to fit many in a row on desktop, but large enough to be readable and touch-friendly.
Integration with Approach E: Replace <div class="int-tags"> with <div class="tool-grid">. Keep the card framework (header, icon badge, title, subtitle) identical. The card categories and colored icon badges remain.
Pitfalls:
- Simple Icons CDN is a third-party dependency (3100+ brands, MIT-licensed). The onerror+fallback pattern means zero visual breakage if the CDN is down — it degrades to colored initials.
- Not every tool has a Simple Icons entry (e.g., Gazebo, Railway, Ollama). Assign a reasonable brand-hex color for the fallback background.
/fffrenders the icon white. Works on dark chip backgrounds. For light theme, use.../000or omit the suffix for the default colored icon. Since icons are tiny (18px), a single white-on-semi-dark-chip style works acceptably in both themes with the fallback providing brand color.- Loading from CDN adds ~44 HTTP requests (one per tool). Each SVG is ~200-800 bytes. Total page weight impact is negligible (~20KB). Use
loading="lazy"on each<img>. - Simple Icons' URL pattern follows
https://cdn.simpleicons.org/{slug}/color— the/fffsuffix overrides the color to white. For brand-colored icons (e.g., if the chip background changes), omit the suffix.
Approach H: Mass Emoji→SVG Icon Replacement
Some founders want zero emoji on their portfolio — everything replaced with clean SVG icons. This is common for deep-tech and engineering profiles where emoji can feel informal. This approach covers the full-site migration.
When to apply
Offer this when:
- The user says "no emoji, use icons", "replace emojis with icons", or "make it look more premium"
- During the initial build, before showing the founder a draft (ask: "Do you prefer emoji or icons on the skill badges and section headers?")
- As a polish pass after the first deploy
Icon source: inline Lucide-style SVGs
Use inline <svg> elements from the Lucide icon set (MIT license, ~800 icons). Every icon is a self-contained viewBox="0 0 24 24" with fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round". They automatically inherit the text color via currentColor and adapt to both theme modes.
Key icons used in the production portfolio:
| Context | Lucide icon name | SVG path count |
|---|---|---|
| About: Mind/Brain | brain |
6 paths |
| About: AI/Robotics | bot |
4 paths + 1 rect + 1 circle |
| About: Code | code-2 (angle brackets) |
2 polylines |
| About: Satellite/Tech | hard-drive |
4 paths |
| Flywheel: Growth | sprout |
2 paths |
| Flywheel: Connection | link-2 |
2 paths |
| Flywheel: Swarm | (custom ant/bug) | 8 paths |
| Flywheel: Ghost/language | ghost |
7 paths |
| Flywheel: Water/space | droplet |
1 path |
| Skills: Settings/Embedded | settings (gear) |
12 paths |
| Skills: AI Agentic | bot |
4 paths + 1 rect + 1 circle |
| Skills: AI/LLMs | brain |
6 paths |
| Skills: Mobile | smartphone |
1 rect + 1 line |
| Skills: IoT | globe |
1 circle + 1 line + 1 ellipse path |
| Skills: Mechatronics | wrench |
3 paths |
| Skills: Full-Stack | monitor |
1 rect + 2 lines |
| Skills: PCB Design | hexagon (hex grid) |
3 lines + 1 polygon |
| Integrations: Cloud | cloud |
1 path |
| Integrations: Circuit | cpu / rectangle |
3 paths + 1 rect |
| Integrations: Languages | code-2 |
2 polylines |
| Integrations: Hardware | microchip |
5 lines + 1 rect |
| Integrations: Agentic | settings (gear) |
12 paths |
| Nav/Footer: Globe | globe |
1 circle + 1 line + 1 ellipse path |
mail |
1 rect + 1 path | |
linkedin |
1 path + 1 rect + 1 circle | |
| GitHub | github |
2 polylines |
| X/Twitter | x |
2 lines |
| YouTube | youtube |
1 polygon |
| Chat (closed) | message-circle |
1 path |
| Chat (close/X) | x |
2 lines |
| Chat send | send |
1 line + 1 polygon |
| Play button | play |
1 polygon |
| Lightning/energy | zap |
1 polygon |
| Check/correct | check |
1 polyline |
Mass replacement technique
Use a Python script with a replacements array to batch-find every emoji in the HTML and replace it with its SVG equivalent:
with open('index.html', 'r') as f:
content = f.read()
replacements = [
# About stat cards
('<div class="icon">🧠</div>', '<div class="icon"><svg width="1em" ...brain paths...></svg></div>'),
('<div class="icon">🤖</div>', '<div class="icon"><svg width="1em" ...bot paths...></svg></div>'),
# ... every emoji occurrence ...
]
for old, new in replacements:
if old in content:
content = content.replace(old, new)
print(f"✓ Replaced: {old[:30]}...")
else:
print(f"✗ NOT FOUND: {old[:40]}...")
with open('index.html', 'w') as f:
f.write(content)
Where emojis typically hide:
| Location | Typical emojis |
|---|---|
| Skill names (progress bar labels) | ⚙️ 🤖 🧠 📱 🌐 🔧 💻 📐 |
| Integration category icons | ☁️ 🔬 ⌨️ 🔌 🧩 |
| About stat card icons | 🧠 🤖 ⌨️ 🛰️ |
| Flywheel card emoji spans | 🌿 🔗 🐜 👻 💧 |
| Project visual placeholders | 🐜 👻 🌿 🔗 💧 |
| Contact link labels | 📧 💻 🐦 🔗 ▶ |
| Nav link CTA / section labels | Various |
| Chatbot JS strings (greetings, responses) | 👋 😊 🤔 🌍 🤝 💪 🌟 |
| Footer | 🌍 or similar globe |
| Chat toggle / send buttons | 💬 ✕ ➤ |
| YouTube section | 🎬 ▶ |
| Favicon (data URI) | ⚡ in <text> element |
Chatbot JS strings require special handling: Emojis embedded in JavaScript string literals (the chatbot's response objects) need text equivalents or trimming. Example:
# JS string replacements (strip emoji from chatbot response text)
js_emoji_fixes = [
(' from Africa. 🌍', ' from Africa.'),
('anything! 😊', 'anything!'),
('👋 I\'m Ibrahim\'s virtual', 'I\'m Ibrahim\'s virtual'),
('you? 🤔', 'you?'),
]
for old, new in js_emoji_fixes:
content = content.replace(old, new)
Favicon (no-emoji variant)
Replace an emoji-based favicon (<text y='.9em' font-size='90'>⚡</text>) with an inline SVG polygon:
<link rel="icon" type="image/svg+xml"
href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><polygon points='60,10 20,55 50,55 40,90 80,45 50,45' fill='%23a6e3a1'/></svg>">
Key points: URL-encode the < and > as < and > in the data URI to avoid HTML parser conflicts. The %23 encodes the # in hex colors.
Verification
After replacement, verify zero emoji remain:
remaining = []
for i, ch in enumerate(content):
cp = ord(ch)
if (0x1F300 <= cp <= 0x1F9FF) or (0x2600 <= cp <= 0x27BF):
remaining.append(f'U+{cp:04X} {ch} at pos {i}')
if remaining:
print(f'{len(remaining)} emojis remaining:')
for r in remaining:
print(r)
else:
print('✅ Zero emojis!')
The only expected survivor is the favicon if it still uses an emoji — intentionally replace it with a polygon.
Pitfalls
- Every emoji occurrence is a separate entry in the replacements array. There's no one-size-fits-all regex for this. Expect 30-50 replacements for a full portfolio.
- Inline SVGs in chatbot JS strings: The chatbot responses are JS string literals, not HTML. You cannot put
<svg>...</svg>inside a JS string used astextContent. Instead, strip the emoji and use clean text. The chatbot's greeting becomes "Hi! I'm Ibrahim's virtual assistant." instead of "👋 Hi! I'm...". - Chat toggle button emoji→SVG swap uses innerHTML, not textContent. After replacing the emoji with an SVG, the JS that toggles the button must also use
innerHTML = '<svg>...'instead oftextContent = '💬'. Update both the initial HTML and the JS toggle handler. - Preserve JS string integrity. When you replace emoji inside JS strings (greetings, responses), only remove the emoji character — don't break the string delimiters or escape sequences.
- Deploy and hard-refresh. After the replacement, force a Vercel deploy with
--forceflag to CDN-bust:vercel deploy --prod --yes --force. Users must hard-refresh (Ctrl+Shift+R) since the old HTML may be cached by the browser, not just the CDN.
Approach I: AI Visibility & SEO for Portfolio Sites
Making a portfolio discoverable by AI crawlers (ChatGPT, Perplexity, Google AI) and search engines requires structured data and proper meta tags. Apply this after the visual design is final.
Required Meta Tags
Include these in <head>:
<title>Your Name — Title | Company — Tagline</title>
<meta name="description" content="155-char rich summary with keywords, role, and location." />
<meta name="keywords" content="targeted, keywords, separated, by, commas" />
<meta name="author" content="Full Name, Company" />
<meta name="robots" content="index, follow" />
<meta name="referrer" content="origin" />
<meta name="theme-color" content="#1e1e2e" />
<link rel="canonical" href="https://your-site.vercel.app/" />
<link rel="sitemap" type="application/xml" href="/sitemap.xml" />
Open Graph & Twitter Cards
For rich link previews on Facebook, LinkedIn, Discord, Slack, and X/Twitter:
<!-- Open Graph -->
<meta property="og:type" content="website" />
<meta property="og:url" content="https://your-site.vercel.app/" />
<meta property="og:title" content="Your Name — Title | Company" />
<meta property="og:description" content="Rich description for social shares." />
<meta property="og:image" content="https://your-site.vercel.app/profile.jpg" />
<meta property="og:locale" content="en_US" />
<!-- Twitter Card -->
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="Your Name — Title | Company" />
<meta name="twitter:description" content="Rich description for X/Twitter." />
<meta name="twitter:image" content="https://your-site.vercel.app/profile.jpg" />
JSON-LD Structured Data (Google & AI Crawlers)
This is the single most impactful addition for AI discoverability. ChatGPT, Google AI, and Perplexity parse JSON-LD directly.
Three-node pattern (Person + Organization + WebSite):
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Person",
"name": "Full Name",
"givenName": "First Name",
"description": "Rich bio — role, what you build, where.",
"birthDate": "2006",
"nationality": { "@type": "Country", "name": "Tanzania" },
"jobTitle": "Founder & Engineer",
"knowsAbout": ["Swarm Robotics", "AI Agents", "Programming Language Design"],
"alumniOf": "University Name",
"affiliation": {
"@type": "Organization",
"name": "Your Company",
"description": "What the company does"
},
"url": "https://your-site.vercel.app",
"sameAs": ["https://github.com/yourhandle"]
},
{
"@type": "Organization",
"name": "Your Company",
"description": "Company description with subsidiary details.",
"url": "https://your-site.vercel.app",
"foundingDate": "2026",
"founder": { "@type": "Person", "name": "Your Name" },
"subsidiary": [
{"@type": "Organization", "name": "Sub A", "description": "..."},
{"@type": "Organization", "name": "Sub B", "description": "..."}
]
},
{
"@type": "WebSite",
"name": "Your Portfolio",
"url": "https://your-site.vercel.app",
"description": "Portfolio site description."
}
]
}
</script>
Key points:
@graphwraps multiple nodes — cleanest way to describe a person + their company + their website in one blockknowsAboutis an array — list 5-8 core skills as plain stringssameAscan include GitHub, LinkedIn, YouTube, X/Twitter URLsalumniOfhelps establish credibility for young founders- All subsidiary companies within the holding company go under the Organization node
Sitemap
Create /sitemap.xml at project root:
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://your-site.vercel.app/</loc>
<lastmod>2026-07-21</lastmod>
<changefreq>monthly</changefreq>
<priority>1.0</priority>
</url>
</urlset>
Link it from the HTML <head>: <link rel="sitemap" type="application/xml" href="/sitemap.xml" />
Robots.txt
Create /robots.txt to explicitly welcome AI crawlers:
User-agent: *
Allow: /
User-agent: GPTBot
Allow: /
User-agent: Claude-Web
Allow: /
User-agent: Googlebot
Allow: /
Sitemap: https://your-site.vercel.app/sitemap.xml
Key point: The default Allow: / already permits all well-behaved crawlers. The explicit GPTBot and Claude-Web entries are a signal to AI companies that you want your content in their training data — some AI crawlers check for explicit opt-in before indexing.
Alt Text for Images
Every <img> should have descriptive alt text:
<!-- Bad -->
<img src="profile.jpg" alt="Ibrahim" />
<!-- Good -->
<img src="profile.jpg" alt="Ibrahim — Founder & Engineer at UMG Africa, Tanzania" />
For tool logos (Simple Icons chips), the alt attribute already carries the tool name — this is sufficient. For decorative SVGs (inline icon replacements), use aria-hidden="true" instead of alt text.
Verification
After deploying, verify with curl:
curl -s "https://site.vercel.app/" | grep -c '<meta ' # expect 15+
curl -s "https://site.vercel.app/" | grep -c 'og:' # expect 6
curl -s "https://site.vercel.app/" | grep -c 'application/ld+json' # expect 1
curl -s "https://site.vercel.app/" | grep -c 'rel="canonical"' # expect 1
curl -s "https://site.vercel.app/robots.txt" | head -3 # expect valid
curl -s "https://site.vercel.app/sitemap.xml" | head -3 # expect valid
Pitfalls:
- JSON-LD must be valid JSON — no trailing commas, no HTML entities inside strings except
&for the&character. Use a JSON validator. - The
robots.txttakes 24-48 hours for Google to re-crawl. It's not instant. - Open Graph images must be absolute URLs (
https://...), not relative paths. Relative OG image URLs are silently ignored by all platforms. theme-colormeta tag sets the browser tab color on mobile Chrome. Use your dark background color so the tab doesn't flash white on page load.- Sitemap
lastmodshould be updated when significant content changes. For a single-page portfolio, monthly is reasonable.
Key Features
-
Glassmorphism Design (both approaches):
- Semi-transparent backgrounds with backdrop blur
- Subtle borders for depth
- Proper contrast for readability (critical on dark themes)
-
Color Palette (customizable per brand):
- Default: Olive (#3D9970), Light Green (#A8E6CF), Amber (#FFD700)
- Hybrid dark variant used in session: Green (#00d4aa), Green-dim (#00a884), Amber (#f5b342)
- Principle: pick 1 primary accent + 1 secondary accent (warm contrast). The primary should pop against the background. Gradient text titles using primary → secondary gradient.
-
Optional Interactive Features (ask before building — not every founder wants these):
- Profile photo upload — SVG placeholder avatar with file-upload + localStorage persistence. User uploads their own photo and it survives page reloads. Implementation: inline SVG fallback,
<input type=file>hidden trigger, FileReader + localStorage save. - Interactive portfolio chatbot — An AI-powered assistant that answers visitor questions about the founder's background, projects, skills, and contact info. Speed-dial toggle, intent-based response matching, suggestion chips for follow-up questions. See
references/portfolio-chatbot-implementation.md. - Embedded educational game — A visual programming puzzle themed around the founder's domain. 8+ levels teaching real concepts. Persistent progress in browser. CRITICAL: always confirm with the founder before building a game — some consider games unprofessional on a portfolio and will ask for removal. See
references/portfolio-game-implementation.md.
- Profile photo upload — SVG placeholder avatar with file-upload + localStorage persistence. User uploads their own photo and it survives page reloads. Implementation: inline SVG fallback,
-
Responsive Layout:
- Mobile-first approach
- Flexible grid systems
- Media queries for all screen sizes
-
Complete Sections:
- Hero section with call-to-action (profile photo + tagline grid layout for dark themes)
- About section with personal narrative (mission-driven, problem-first framing)
- Company/ventures showcase (flywheel visualization for holding companies)
- Projects/portfolio gallery (alternating left-right card layout)
- Skills grid with category breakdown or animated progress bars (see Approach D)
- Integrations/tools grid section (see Approach E)
- Play/game section (retention mechanic — confirm interest first)
- Contact section with social links
- Footer
-
Theme Toggle: dual dark/light theme using Catppuccin palettes (see Approach C). Persistent across visits via localStorage. Toggle button in the nav bar. Alternative: dark-only mode — if the founder prefers permanent dark, strip the toggle entirely (see Approach C2).
-
Progress Bar Skills: animated proficiency bars that fill from 0 to target width when scrolled into view (see Approach D).
-
Integrations / Tools Grid: categorical cards listing tools, platforms, and frameworks the founder uses — organised as icon-badge cards with tag clouds or brand logo chips from Simple Icons CDN (see Approaches E and G).
-
Custom SVG Backgrounds: programmatic SVG textures that mirror the founder's engineering domain — circuit traces, geographic outlines, waveforms, glowing nodes. Generated via Python and saved as a standalone
.svgreferenced in CSSbackground: url(...). Requires no external assets or CDN. Seereferences/circuit-svg-background-pattern.md. -
AI Visibility & SEO: JSON-LD structured data, Open Graph tags, Twitter Cards, sitemap, robots.txt, canonical URL, descriptive alt text, and comprehensive meta tags for discoverability by ChatGPT, Google AI, Perplexity, and search engines (see Approach I).
Workflow
-
Planning:
- Define site structure based on user requirements
- Plan content organization
- Determine specific features needed
-
Design System:
- Establish color palette (1 primary + 1 secondary accent)
- Define typography hierarchy
- Create glassmorphism component styles (lighter on light themes, subtle on dark themes)
- Plan responsive behavior
-
Implementation:
- Build as a single self-contained HTML file (preferred — no build step, deployable anywhere)
- Write semantic HTML
- Implement CSS with glassmorphism effects
- Add JavaScript for interactivity (scroll reveals, nav, optional features)
- Ensure responsive design
-
Photo Integration (when user already has a real photo):
- Locate: check
~/Downloads/for "WhatsApp Image" or user-named files; usels -lt ~/Downloads/ | headto find the most recent - Choose frame shape before cropping:
- Circular frame (default for portrait profiles): crop source image to square, then resize to 400x400.
from PIL import Image img = Image.open('source.jpg') min_dim = min(img.size) left = (img.width - min_dim) // 2 top = (img.height - min_dim) // 2 img_square = img.crop((left, top, left + min_dim, top + min_dim)) img_resized = img_square.resize((400, 400), Image.LANCZOS) img_resized.save('profile.jpg', 'JPEG', quality=85, optimize=True) - Rectangle frame (preferred by some founders — shows full body/portrait, more modern): do NOT crop to square. Preserve original aspect ratio. Resize width to ~300px and let height scale.
CSS changes for rectangle frame:from PIL import Image img = Image.open('source.jpg') new_w = 300 new_h = int(img.height * new_w / img.width) img_resized = img.resize((new_w, new_h), Image.LANCZOS) img_resized.save('profile.jpg', 'JPEG', quality=90, optimize=True).profile-frame { width: 300px; height: 420px; border-radius: 16px; padding: 5px; } .profile-inner { border-radius: 12px; } .profile-inner img { width: 100%; height: 100%; object-fit: cover; } .profile-ring { display: none; }
- Circular frame (default for portrait profiles): crop source image to square, then resize to 400x400.
- Default display pattern: the
<img>tag should havesrc="profile.jpg"and be visible by default; the SVG placeholder should be hidden (style="display:none") as a fallback for the upload flow. This is the reverse of the upload-only pattern where SVG is shown first. - Upload flow still works: the FileReader + localStorage mechanism replaces
img.srcwith the uploaded data URL on change, and restores from localStorage on page load — overriding the defaultprofile.jpg. - Post-photo cleanup: once the final photo is in place, the founder may want to remove the "Upload your photo" button entirely. Offer this as cleanup. To remove: delete the
<div class="photo-credit">block from HTML, and delete the photo upload JS section (FileReader listener + localStorage restore). This simplifies the page and removes unnecessary UI.
- Locate: check
-
Deployment & Verification (for static asset changes):
git addthe new/updated assets and changed HTML- Deploy:
vercel deploy --prod --yes --force(the--forceflag busts Vercel's CDN cache — critical for image changes) - Verify with curl:
curl -sI "https://<site>.vercel.app/profile.jpg" | head -5 # Expect HTTP/2 200 - If the image is missing, check the HTML reference path — Vercel serves from project root, so
src="profile.jpg"resolves tohttps://site.vercel.app/profile.jpg
-
Optional Interactive Features (confirm interest first, then build):
- Propose options: theme toggle (dark/light), profile photo upload, chatbot, embedded game
- Let the founder choose which (if any) they want — never build all three/large features by default
- Theme toggle is low-commitment — offer it early since it impresses and is ~50 lines of CSS+JS
- Profile photo with upload capability
- Portfolio chatbot with intent matching
- Embedded game themed to the founder's domain (only if confirmed)
- See reference files for implementation patterns
-
Assets:
- Create placeholder images for projects
- Prepare icons (using inline SVG or Font Awesome)
- Optimize all assets for web
-
Testing:
- Verify responsive behavior
- Check browser compatibility
- Test form validation
- Ensure accessibility standards
HTML Structure
Two viable approaches:
Option A: Single Self-Contained File (Recommended for simplicity)
index.html (all HTML + CSS + JS inline)
Preferred when there's no build step, no framework, and you want to deploy anywhere (Vercel, GitHub Pages, Netlify) with zero config. Best for founder/engineer portfolios with interactive features (game, chatbot).
Option B: Separate Directories (For larger projects)
- index.html
- css/
- styles.css
- js/
- main.js
- assets/
- images/
- icons/
CSS Guidelines
-
Glassmorphism Implementation:
.glass { background: rgba(255, 255, 255, 0.85); border-radius: 15px; box-shadow: 0 8px 32px rgba(31, 38, 135, 0.37); backdrop-filter: blur(10px); -webkit-backdrop-filter: blur(10px); border: 1px solid rgba(255, 255, 255, 0.18); } -
Color Variables:
:root { --olive: #3D9970; --light-green: #A8E6CF; --amber: #FFD700; } -
Responsive Design:
- Mobile-first approach with media queries
- Flexible grids using CSS Grid and Flexbox
- Properly sized touch targets
JavaScript Functionality
-
Core:
- Navigation: smooth scrolling, active link highlighting, mobile hamburger toggle
- Scroll reveal animations (IntersectionObserver)
- Glassmorphism hover effects on cards
-
Optional: Profile Photo Upload:
- SVG placeholder avatar with circuit / tech pattern
- Hidden
<input type="file">triggered by label - FileReader API to load image as data URL
- localStorage persistence so the photo survives page reloads
- Default photo pattern: if the user provides a real image, embed it as
<img src="profile.jpg">visible by default, with the SVG hidden as fallback. The upload mechanism overridesimg.srcon new upload and restores from localStorage on page load — this way the site always shows a real face, even to first-time visitors. - Photo optimization:
- Circular frames (default): crop to square, resize to 400x400, JPEG quality=85, optimize=True. Target ~25-35KB.
- Rectangle frames: preserve original aspect ratio, resize width to ~300px, JPEG quality=90, optimize=True. Target ~40-60KB for portrait shots.
- Always use
Image.LANCZOSfor downscaling (best quality).
-
Optional: Embedded Educational Game:
- Grid-based visual programming puzzle themed to founder's domain
- Command palette (Forward, Left, Right, Repeat)
- Program list rendered as removable step chips
- Step-by-step execution with delay (simulates robot movement)
- Collision detection, boundary checking, win conditions
- Star rating system based on solution efficiency vs optimal
- Multi-level progression with browser localStorage persistence
- See
references/portfolio-game-implementation.md
-
Optional: Portfolio Chatbot:
- Floating action button (toggle open/close)
- Chat panel with header, message area, input, suggestion chips
- Intent-matching response engine (regex keyword categories)
- Typing indicator simulation (delayed response)
- Markdown-like formatting in responses (bold, line breaks)
- See
references/portfolio-chatbot-implementation.md
Verification
Before final delivery:
- Ensure all files are created in the correct structure
- Verify HTML is valid and semantic
- Check CSS for proper glassmorphism implementation
- Test JavaScript functionality
- Confirm responsive behavior across devices
- Validate form submission process
Content Strategy
- Position the founder's narrative — don't just list what they build, explain WHY. Frame challenges as engineering opportunities. Mission-driven storytelling resonates more than feature lists.
- For holding companies / multiple ventures: use a flywheel visualization showing how each entity feeds the next. This communicates strategy, not just a list of brands.
- Interactive features: confirm interest before building a game or chatbot. Some founders want a clean, professional portfolio without gamification. Offer the option, don't assume.
Pitfalls
- Don't overuse glassmorphism effects (can impact readability, especially on dark themes with light text)
- Ensure proper contrast for text on semi-transparent backgrounds — use text-shadow or solid-text variants on noisy backdrop-filter areas
- Test performance of backdrop-filter on different devices (mobile Safari especially)
- Don't forget to include fallbacks for older browsers
- Make sure all interactive elements are accessible (keyboard navigation, ARIA labels)
- Custom SVG background opacity: the background is a fixed
.svgreferenced via CSSurl(). Keep overall opacity 0.03-0.08 so it textures without distracting. Use CSSopacityon the::beforepseudo-element that loads it, not on the SVG itself — this allows the SVG to remain at full opacity for visual quality while the CSS layer controls the dimming. - Custom SVG background file size: a full-viewport circuit SVG with Africa outline and waveforms is ~20KB. That's acceptable, but avoid embedding raster images or complex gradients inside the SVG — keep it as vector lines and simple fills only.
- Custom SVG background viewport coverage: use
background: url('bg.svg') center center / cover no-repeatso the SVG scales to fill any screen size. The SVG viewBox should be0 0 1440 900(a common laptop screen ratio) — elements near the edges may clip on ultrawide or portrait screens, but the low opacity makes this unnoticeable. - Profile photo SVG placeholder: ensure the SVG is visually appealing as a fallback — if the user never uploads a photo, the placeholder is their permanent avatar. Circuit/pattern SVGs work better than generic silhouettes for tech founders.
- Game levels: design levels that progressively teach concepts (sequence → turns → loops → pathfinding). The game should be beatable but challenging. Always provide a "Reset level" option.
- Chatbot intent matching: regex-based matching is simple and fast but misses typos. The suggestion chips pattern compensates — offer 3-4 contextual follow-ups after each response so users can click instead of type.
- Chatbot scope: keep the knowledge base focused. A portfolio chatbot should know about the person's background, projects, skills, and contact info — not attempt general conversation.
- Confirm interactive features upfront: before building a game, chatbot, or photo upload, verify the founder actually wants it. A developer who asked for a "good portfolio to shine in the tech world" may not want a game on it. Phrase as: "I can add a game, chatbot, or photo upload if you'd like — or keep it clean. What suits your style?" This avoids wasted work and the awkward removal conversation.
- When game is removed: replace with a testimonial section, timeline/milestones, or expanded project details. The portfolio should still feel complete without it. The chatbot suggestion chips and greeting should also be updated to remove game references.
- Default photo display: when embedding a real photo, reverse the default visibility. The
<img>with the real photo should be visible (display:blockor default inline) and the SVG placeholder should be hidden (style="display:none"). The upload JavaScript should then modify the img.src (not toggle visibility between two elements). This prevents a flash of the SVG placeholder before the page JS runs. - Deployment verification for assets: after deploying images or static files to Vercel, verify with curl before assuming it worked. Vercel's CDN sometimes caches old versions of the HTML that reference missing images. Check:
curl -sI "https://<site>.vercel.app/<asset>" | head -5— expect HTTP 200. Also check the HTML serves correctly:curl -s "https://<site>.vercel.app/" | grep 'src="profile.jpg"'
🔴 Critical: Scroll-Reveal Animation Selector Bug
When using IntersectionObserver for scroll-reveal animations, never use document.querySelector('.reveal') — this returns only the FIRST matching element. All other .reveal elements will remain invisible (opacity: 0) and never animate in, making the page appear broken or blank below the fold.
Always do this instead:
// CORRECT — observes EVERY .reveal element individually
document.querySelectorAll('.reveal').forEach(el => {
new IntersectionObserver((entries) => {
entries.forEach(e => {
if (e.isIntersecting) e.target.classList.add('visible');
});
}, { threshold: 0.1, rootMargin: '0px 0px -40px 0px' }).observe(el);
});
Why this is critical: the page loads, CSS sets .reveal { opacity: 0 }, JS only attaches the observer to the first element. All sections below the hero stay transparent. The user sees a blank page and reports "it doesn't load." Vercel's CDN can make the fix appear to not deploy — always force a vercel deploy --prod --yes --force after this fix, then hard-refresh in the browser (Ctrl+Shift+R / Cmd+Shift+R).
This selector pitfall applies generally: anytime you query elements by class to attach behavior, default to querySelectorAll + iteration unless you have a specific reason to target only the first match.
🔴 User Preference: Emoji-Free Portfolios (Deep-Tech Founders)
Some founders explicitly want zero emoji on their portfolio. This is especially common for deep-tech / engineering profiles where emoji can feel informal, unprofessional, or out of character. When building a portfolio for an AI/robotics/engineering founder:
- Ask upfront during the planning phase: "Do you prefer emoji or clean SVG icons on the skill badges, section headers, and cards?" Defaulting to icons saves a correction cycle.
- If they say "replace emojis with icons" or "use icons instead of emoji" — apply the full Mass Emoji→SVG Replacement (Approach H) across every section: skill names, integration category icons, about stat cards, flywheel cards, contact links, chatbot, footer, and even the favicon.
- Chatbot text is a common oversight — emoji in JS string literals (greetings, responses) must be manually stripped. They can't hold SVG elements.
- The theme toggle button uses moon/sun emoji. If going dark-only (Approach C2), the toggle is removed entirely, solving this naturally. If keeping the toggle, replace the moon/sun emoji with SVG versions using
innerHTMLinstead oftextContent. - After replacement, verify with a character-range scan (see Approach H Verification) — don't rely on visual review alone. Emoji can hide in JS strings, the favicon, and CSS
content:pseudo-elements.
Reference Files
This skill includes the following reference files:
references/ibrahim-portfolio-2026.md— Full case study of a hybrid dark-theme portfolio for a Tanzanian deep-tech founder (photo upload, chatbot, and the build-then-remove cycle of an embedded game).references/portfolio-game-implementation.md— Pattern for building an embedded educational game (level system, grid rendering, execution engine, star ratings).references/portfolio-chatbot-implementation.md— Pattern for building a portfolio chatbot (intent matching, suggestion chips, UI components).references/circuit-svg-background-pattern.md— Programmatic SVG background generator: circuit traces, geographic outlines, data waveforms, glowing nodes. Full Python script with customization guide.references/catppuccin-portfolio-pattern.md— Complete implementation of the Catppuccin dual-theme system (Mocha dark + Latte light), progress bar skills with animated fills, and integrations/tools grid section. CSS variables, theme toggle JS, grid layouts, and all category icons.
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).