Add build instructions; update README to match spec

2026-10-03 18:12:06 +00:00
parent 6d215042ad
commit f220c5d9d1
2 changed files with 458 additions and 1 deletions
--- a/INSTRUCTIONS.md
+++ b/INSTRUCTIONS.md
@@ -0,0 +1,424 @@
 # 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.
--- a/README.md
+++ b/README.md
@@ -1,3 +1,36 @@
 # Portfolio
-Personal project portfolio.
+Personal portfolio website — interactive professional profile, not a CV pasted onto a webpage.
 Built per [INSTRUCTIONS.md](./INSTRUCTIONS.md), which is the full build specification: source-of-truth rules (CV/resume files in this workspace are canonical; no invented facts), section architecture, i18n-first design, animation requirements, Docker deployment, and verification checklist.
 ## What it presents
 - About — who I am, professional summary
 - Experience — work history with dedicated timeline/role UI
 - Projects — browsable project details (purpose, role, tech, outcomes, links)
 - Skills — categorized by actual experience, no invented percentages
 - Education / Certifications
 - Contact + external profiles
 ## Key properties
 - **Section navigation** — persistent nav with addressable URLs (`/en/experience`, `/en/projects`, ...), browser Back/Forward support, animated section transitions that are interruptible and respect `prefers-reduced-motion`
 - **i18n-first** — canonical content layer separate from translations; locale detection (saved choice → browser languages → region hint → default); visible language selector with persistence; `/en/...`, `/vi/...` style URLs with hreflang/canonical metadata
 - **Design** — clean, technical aesthetic; mobile-first, responsive, accessible, keyboard navigable; dark/light mode; simple at first glance, detailed when explored
 - **Performance** — small initial bundle, no heavy animation/UI libraries for effects CSS can do
 ## Deployment
 Docker-based: multi-stage build, non-root runtime user, health check.
 ```sh
 docker build -t portfolio .
 docker run --rm -p 8080:8080 portfolio
 ```
 See INSTRUCTIONS.md → "Docker and deployment" for ports, environment variables, and content-editing guides (adding projects, work history, skills, languages).
 ## Status
 Scaffold — repo initialized. Implementation follows the engineering steps in [INSTRUCTIONS.md](./INSTRUCTIONS.md) (inspect workspace sources → canonical content model → i18n/routing/section architecture → animation system → implement → verify).