Creating a website with AI: practical guide to prompt engineering for developers

Build a One-Page Portfolio Site in a Weekend Using an AI Assistant: Developer's Guide

Developing a single-page portfolio site with the help of an AI assistant like Claude Code showcases a fresh take on web development. This approach lets you build a fully functional project in a short time without hiring outside experts—just basic HTML/CSS knowledge and prompt engineering skills.

Prep Stage: Content and Structure

Before writing any code, gather your content and map out the project architecture. The AI can generate text content if you provide enough context: chat histories, talk materials, project descriptions. For a bio, ask for three versions—short, medium, and detailed—to speed things up.

Nail down the page structure before your first prompt. Here's a recommended layout for a speaker's portfolio site:

• Fixed 300px sidebar
• Main content with sections
• Hero section with photo and key info
• Bio block
• Talk topic cards
• Achievements section with stats
• Photo and video gallery
• Contact info

Crafting Prompts: From Skeleton to Polish

The golden rule for AI assistants: describe the end result, not the steps. Your first prompt should generate the basic framework with the right structure and semantics.

Example of an effective starter prompt:

Create a one-page portfolio site for a speaker.

Style: Dark theme (background #0a0a0a), Raleway font via Google Fonts, accent color #3182CE.

Layout: Two columns. Left: sticky 300px sidebar with round photo, name, title, social links. Right: main content sections—Bio, Talk Topics (cards), Achievements (stats), Gallery (photo grid), Contacts.

Requirements: Pure HTML, CSS, and vanilla JS. No frameworks or external dependencies except Google Fonts.

Once you have the skeleton, iterate to refine. Each round tackles one specific task:

• Typography and color scheme
• Responsive design
• Interactive elements
• Animations and micro-interactions

Technical Implementation Details

Responsive Layout and Cross-Browser Compatibility

Mobile responsiveness needs special focus. After desktop tweaks, explicitly request mobile fixes:

On mobile (<768px), the layout breaks: sidebar and content side-by-side, content overflows. Fix: Stack sidebar on top horizontally (photo and contacts in a row), main content full-width below.

Key cross-browser tips:

• Test in Chrome, Safari, Firefox
• Add vendor prefixes for CSS properties
• Check tablets (768-1024px)

Performance Optimization

After visuals are done, optimize. Common issues and fixes:

• Image Optimization:

- Convert PNG to WebP

- Resize to needed dimensions

- Add lazy loading

• Resource Loading:

- Async Google Fonts

- Preload critical assets

- Defer iframe loading

• Performance Metrics:

- LCP (Largest Contentful Paint)

- FID (First Input Delay)

- CLS (Cumulative Layout Shift)

Example optimization prompt:

Site scores 38 on PageSpeed Insights. Issues: large images (12MB profile photo), render-blocking resources, no lazy loading for videos. Optimize: Convert images to WebP, preload hero image, defer iframe loading.

Deployment and Hosting

Hosting Options

• Netlify/GitHub Pages — free, dead simple
• Custom VPS — full control, needs setup

VPS Deployment Pitfalls

• Case-sensitive filenames (Linux is picky)
• Absolute vs. relative paths
• File permissions and user isolation
• Project structure organization

Tips to avoid headaches:

• Use lowercase filenames
• No spaces or special chars
• Document your setup
• Use Git for version control

Key Takeaways

• Iterative Process: Break dev into small tasks; each iteration fixes one issue
• Quality Checks: Test across browsers, run performance tools
• Documentation: Log changes and decisions for easy rollbacks
• Optimization: Treat performance as a separate phase after visuals

Code Best Practices

Project Structure

Organize files logically:

project/
├── index.html
├── styles/
│   ├── main.css
│   ├── mobile.css
│   └── animations.css
├── scripts/
│   └── main.js
├── images/
│   ├── optimized/
│   └── original/
└── assets/
    └── fonts/

CSS Methodology

Use meaningful BEM class names:

.speaker-card {
    /* card styles */
}

.speaker-card__image {
    /* image styles inside card */
}

.speaker-card__image--rounded {
    /* modifier for rounded image */
}

JavaScript for Interactivity

Add basic interactions without frameworks:

// Scroll-triggered animations
const observerOptions = {
    threshold: 0.1,
    rootMargin: '0px 0px -50px 0px'
};

const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
        if (entry.isIntersecting) {
            entry.target.classList.add('animate-in');
        }
    });
}, observerOptions);

// Apply to all .animate-on-scroll elements
document.querySelectorAll('.animate-on-scroll').forEach(el => {
    observer.observe(el);
});

Common Mistakes and Fixes

• Vague Prompts — AI spits out generic templates
• No Constraints — AI sneaks in unwanted libraries
• Skipping Optimization — Pretty but sluggish site
• Ignoring Mobile — Miss half your audience

Quality Control Tools

• PageSpeed Insights — performance audits
• Lighthouse — full site checks
• BrowserStack — cross-browser testing
• Git — version control and rollbacks

— Editorial Team