portfolio/INSTRUCTIONS.md

Portfolio Website — Build Instructions

Build a complete, production-ready personal portfolio website for me.

Source of truth

First inspect ALL files available in the project/workspace, especially CV/resume files and documents containing personal, professional, project, education, skill, certification, or contact information.

Use those files as the source of truth.

Do not invent experience, achievements, dates, employers, technologies, metrics, education, certifications, projects, or personal details.

If multiple CVs contain conflicting information:

1. Prefer the newest clearly dated version.
2. Cross-check other available documents where useful.
3. If the correct information cannot be determined, flag the conflict instead of guessing.

Goal

Create a modern, fast, professional portfolio presenting:

• Who I am
• Professional summary
• Work history / Experience
• Projects
• Technical skills
• Education
• Certifications, if present
• Contact information
• Relevant external profiles and links found in the supplied files

Prioritize real information, readability, and clarity over decorative UI.

The overall tone should be simple, informative, confident, and professional. Avoid filler language and unnecessary marketing copy.

Information architecture and section navigation

My Skills, Work History, Projects, Education, Certifications, About information, and other major portfolio content must each have a clearly defined UI and navigation state.

Do not present the portfolio as an undifferentiated long page where users must continuously scroll to discover everything.

Visitors should immediately understand:

• What sections are available
• Which section they are currently viewing
• How to move to another section
• How to return to previous content
• Which items are interactive
• Where more detailed information is available

Create a clear navigation model appropriate for the final design. This may use a persistent navigation bar, section switcher, tabs, sidebar, command-style navigation, or another well-designed approach.

The navigation itself should feel like part of the portfolio's identity rather than a generic website menu.

Important sections such as:

"About → Experience → Projects → Skills → Education / Certifications → Contact"

must be directly selectable.

On mobile, adapt this interaction appropriately rather than simply shrinking the desktop navigation.

Work history

Give work history a dedicated, recognizable UI.

Users should be able to move between employers/roles easily and understand:

• Company
• Position
• Time period
• Responsibilities
• Relevant technologies
• Significant work or achievements, only when supported by source files

Consider timelines, selectable role entries, expandable details, or another compact interaction when appropriate.

Do not bury work experience inside generic cards.

Projects

Projects should have their own distinct interface.

Make individual projects easy to browse and switch between.

Where supported by source material, show:

• Project name
• Purpose/problem
• My role
• What I worked on
• Technologies
• Relevant outcomes
• Links

Allow users to select a project and explore its details without losing their place in the overall portfolio.

Skills

Skills should also be a clearly identifiable section rather than a large unordered list of technology badges.

Organize skills into meaningful categories derived from my actual experience and source documents.

For example, only when supported by the files:

"Infrastructure" "Networking" "Cloud" "DevOps" "Development" "Operating Systems" "Virtualization" "Automation" "Databases" "Tools"

Do not invent categories or skills merely to fill the interface.

Where useful, make categories selectable so visitors can quickly explore different areas of expertise.

Do not assign arbitrary percentage bars such as "Linux 95%" or "Docker 90%" unless such measurements genuinely exist in the source material.

Section switching and animation

Switching between major sections should be a deliberate visual interaction.

When a visitor chooses:

"Experience → Projects"

or:

"Projects → Skills"

the change should have a polished animated transition rather than an abrupt content replacement.

Use transitions such as:

• Directional slide + fade
• Content crossfade
• Subtle depth transition
• Animated navigation indicator
• Shared-element movement where appropriate
• Staggered entrance of important content
• Smooth timeline/project transitions
• Micro-interactions on selected navigation items

The active section must always be visually obvious.

Animation should communicate where the user moved, not merely decorate the screen.

For example, the navigation indicator can move toward the newly selected section while the previous content exits and the new content enters with coordinated motion.

Maintain spatial consistency so users do not become disoriented.

Animations should generally be short, responsive, and interruptible. Never make visitors wait for an animation before they can continue navigating.

Support browser Back/Forward behavior where section navigation changes the URL.

Where appropriate, major sections should have addressable URLs, for example:

"/en/experience" "/en/projects" "/en/skills"

This allows a visitor to link directly to a particular part of the portfolio.

Internationalization

Design the website as multilingual/i18n-first from the beginning.

Do NOT hard-code user-facing text throughout components. Store translations in structured locale resources.

Adding another language should not require modifying page components or duplicating pages.

On the visitor's first visit, determine the initial language using this priority:

1. Previously saved explicit language choice
2. Browser language/preferences ("navigator.languages" / "Accept-Language")
3. Privacy-preserving location/region signal when reliably available
4. Default fallback language

Do not request precise geolocation or location permission merely to select a language.

Never assume that a country uniquely determines language. Region should only help choose a sensible initial locale.

Always provide a clearly visible language selector.

Persist explicit language choices locally and respect them on future visits.

Implement graceful fallback:

"requested locale → base language → default language"

Use locale-aware formatting for dates, numbers, and regional data where appropriate.

Update the HTML "lang" attribute whenever the active language changes.

Use multilingual URL structures such as:

"/en/..." "/vi/..." "/ja/..."

Add appropriate canonical and "hreflang" metadata for multilingual SEO.

Content architecture and translation

Create a canonical portfolio content/data layer separate from presentation and translations.

Professional facts must remain identical across languages. Only their presentation should be translated.

Translate naturally rather than word-for-word.

Preserve where appropriate:

• Company names
• Product names
• Project names
• Technical terminology
• Technology names
• URLs
• Proper nouns

Never translate content in a way that changes its meaning or exaggerates my experience.

If source documents contain multiple languages, reconcile them into one canonical representation before generating locale-specific presentation content.

Visual design

Use a clean, modern, technical aesthetic appropriate for an experienced technology professional.

The site must be:

• Responsive
• Mobile-first
• Accessible
• Keyboard navigable
• Fast
• SEO-friendly
• Dark/light-mode friendly
• Visually polished
• Easy to scan
• Informative without feeling dense

Avoid a generic AI-generated portfolio appearance.

Specifically avoid excessive gradients, oversized hero typography, excessive rounded cards, meaningless statistics, buzzwords, filler copy, and visual clutter.

Use my actual career, projects, technologies, and professional information to establish the site's identity.

The visual philosophy should be: Simple at first glance, detailed when explored.

Animation and interaction

Include eye-catching but tasteful animations throughout the experience.

Prioritize animation for meaningful interactions:

• Entering the portfolio
• Changing major sections
• Selecting a work experience
• Selecting a project
• Switching skill categories
• Opening additional details
• Changing language
• Changing theme
• Navigation hover/focus
• Returning to previous content

Animations should make the interface feel responsive and alive while preserving the simplicity of the content.

Do not animate everything.

Avoid distracting particle effects, excessive parallax, constant background movement, long intro sequences, or animation that interferes with reading.

Animations must:

• Remain smooth on normal hardware
• Prefer GPU-friendly transforms and opacity
• Avoid unnecessary JavaScript
• Respect "prefers-reduced-motion"
• Degrade gracefully when animation is disabled
• Never block navigation
• Work correctly on touch devices
• Work correctly with keyboard navigation
• Remain usable on lower-powered mobile devices

The desired balance is:

Simplicity + information + technical identity + fluid navigation + memorable interaction.

Engineering

Before implementation:

1. Inspect the entire repository and available files.
2. Understand the existing stack and conventions.
3. Find and inspect relevant CV/resume/document files.
4. Extract and normalize factual portfolio information.
5. Resolve conflicts using the source-of-truth rules.
6. Determine supported languages.
7. Design the canonical content model.
8. Design the i18n, locale detection, fallback, and routing architecture.
9. Design the section/navigation architecture.
10. Design the animation and transition system.
11. Then implement.

If this is an existing project, preserve its stack and conventions unless there is a strong technical reason to change them.

Maintain clear separation between:

• UI components
• Canonical portfolio data
• Translation resources
• Locale detection/routing
• Section navigation
• Animation/transition behavior
• SEO/metadata
• Configuration

Do not duplicate entire pages for different languages.

Avoid unnecessary dependencies.

Never expose missing translation keys such as "hero.title" to visitors.

Docker and deployment

The final website must be built and deployed using a Docker image.

Provide a production-ready Docker setup.

Include:

• "Dockerfile"
• ".dockerignore"
• Multi-stage build where appropriate
• Production-mode runtime
• Small runtime image where practical
• Non-root runtime user where practical
• Correct exposed/configurable port
• Environment-variable configuration
• Correct inclusion of static assets and locales
• Health check where appropriate
• No embedded secrets or credentials

The project should support approximately:

"docker build -t portfolio ."

and an appropriate documented "docker run" command.

Document in the README:

• Local development
• Production build
• Docker build
• Docker run
• Ports
• Environment variables
• How portfolio content is structured
• How to add/update projects
• How to add/update work history
• How to add skills
• How to add another language

Performance

Treat performance as a feature.

Optimize:

• Initial bundle size
• Images
• Fonts
• JavaScript
• Animations
• Loading behavior
• Caching
• Core Web Vitals

Do not introduce a large animation/UI library for effects that can reasonably be implemented using CSS or dependencies already present in the project.

Quality and verification

Before considering the task complete:

• Run the project.
• Run lint checks.
• Run type checks.
• Run available tests.
• Build the production version.
• Build and run the Docker image.
• Test responsive layouts.
• Test desktop and mobile navigation.
• Test direct URLs to major sections.
• Test browser Back/Forward navigation.
• Test every supported locale.
• Test automatic language detection.
• Test manual language switching.
• Test persistence across reloads.
• Test locale fallback.
• Check for untranslated strings.
• Check broken links.
• Check keyboard navigation.
• Check accessibility basics.
• Test dark/light mode.
• Test "prefers-reduced-motion".
• Test section transitions.
• Test Experience/Project/Skill switching.
• Verify animations remain usable on mobile.
• Check metadata, canonical URLs, and multilingual SEO.
• Verify every professional claim against the supplied files.

Fix issues encountered rather than merely reporting them.

Do not stop at a scaffold, wireframe, mockup, or generic portfolio template.

Deliver a complete, polished, interactive, multilingual, Docker-deployable portfolio website based entirely on my actual professional information.

The final experience should feel like an interactive professional profile rather than a CV pasted onto a webpage.