From f220c5d9d1daee68ffe0b2e97c0dd19c83e2ad74 Mon Sep 17 00:00:00 2001 From: supersanta Date: Sat, 3 Oct 2026 18:12:06 +0000 Subject: [PATCH] Add build instructions; update README to match spec --- INSTRUCTIONS.md | 424 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 35 +++- 2 files changed, 458 insertions(+), 1 deletion(-) create mode 100644 INSTRUCTIONS.md diff --git a/INSTRUCTIONS.md b/INSTRUCTIONS.md new file mode 100644 index 0000000..00107be --- /dev/null +++ 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. diff --git a/README.md b/README.md index 2fa3758..91521ca 100644 --- 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).