mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
docs: add spec_v1.md (v1 completion record) and move all specs to docs/design/
This commit is contained in:
1 parent
59951a7224
commit
e922ce64b8
18 files changed
+628
No files matched your search
@@ -0,0 +1,127 @@
|
||||
# UI Spec — About Section
|
||||
|
||||
## Overview
|
||||
|
||||
Section giới thiệu bản thân, engineering philosophy, và current interests.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
AboutSection
|
||||
├── SectionHeading ("About Me")
|
||||
├── ProfileBlock
|
||||
│ ├── Name/Title
|
||||
│ └── Bio (paragraph)
|
||||
├── PhilosophyBlock
|
||||
│ ├── Title ("How I Think About Engineering")
|
||||
│ └── Philosophy points
|
||||
│ ├── Build for the real problem
|
||||
│ ├── Think in systems
|
||||
│ ├── Measure impact
|
||||
│ └── Keep learning
|
||||
├── CurrentInterests
|
||||
│ └── List of current explorations
|
||||
└── CTA ("Read more") → /about (optional)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content
|
||||
|
||||
| Element | Content |
|
||||
|---|---|
|
||||
| **Section title** | About Me |
|
||||
| **Bio** | _[TBD — bio paragraph]_ |
|
||||
| **Philosophy title** | How I Think About Engineering |
|
||||
| **Philosophy points** | Build for real problem, Think in systems, Measure impact, Keep learning |
|
||||
| **Current interests** | AI in logistics, Digital twins, Simulation, LLM, Computer Vision, High-performance systems |
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
### Desktop
|
||||
|
||||
- Single column, max-width 800px
|
||||
- Bio: left-aligned, body font size
|
||||
- Philosophy: 4 cards hoặc 4 subsections, grid 2x2
|
||||
- Current interests: tag-style pills hoặc bullet list
|
||||
- Spacing: section padding 80px vertical
|
||||
|
||||
### Mobile
|
||||
|
||||
- Single column, stacked
|
||||
- Philosophy cards: single column stack
|
||||
- Tags: wrap, full-width
|
||||
- Spacing: section padding 48px vertical
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Element | Size | Weight |
|
||||
|---|---|---|
|
||||
| Section heading (H2) | 40px desktop / 32px mobile | 600 |
|
||||
| Bio | 16–18px | 400 |
|
||||
| Philosophy title (H3) | 24px | 500 |
|
||||
| Philosophy point | 16px | 400 |
|
||||
| Interest tag | 14px | 400 |
|
||||
|
||||
---
|
||||
|
||||
## Philosophy Cards
|
||||
|
||||
| Variant | Content |
|
||||
|---|---|
|
||||
| Build for the real problem | Không bắt đầu bằng technology. Bắt đầu bằng problem. |
|
||||
| Think in systems | Architecture, Integration, Scalability, Reliability, Observability |
|
||||
| Measure impact | Performance, Reliability, Cost, Operational efficiency, Business impact |
|
||||
| Keep learning | AI/ML, Computer Vision, LLM, Distributed systems, Performance engineering |
|
||||
|
||||
---
|
||||
|
||||
## Current Interests
|
||||
|
||||
- Render as tag pills
|
||||
- Accent color border, transparent background
|
||||
- Hover: accent background, white text
|
||||
- No click behavior (informational)
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- H2 cho section heading
|
||||
- H3 cho philosophy subsections
|
||||
- Semantic HTML: `<article>` cho philosophy cards
|
||||
- Contrast >= 4.5:1
|
||||
- Focus visible trên tags khi hover
|
||||
|
||||
---
|
||||
|
||||
## Animation
|
||||
|
||||
- Fade-in khi scroll vào viewport
|
||||
- Cards stagger (100ms delay each)
|
||||
- Subtle, 300ms duration
|
||||
|
||||
---
|
||||
|
||||
## State
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| Default | Normal render |
|
||||
| Hover | Tags fill with accent |
|
||||
| Scroll reveal | Fade-in + slide-up |
|
||||
| Reduced motion | Disable all animations |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Bio data-driven từ `profile.ts`
|
||||
- Philosophy points có thể extend — component phải handle dynamic content
|
||||
- Không hard-code philosophy count
|
||||
@@ -0,0 +1,152 @@
|
||||
# UI Spec — Blog Section
|
||||
|
||||
## Overview
|
||||
|
||||
Trang danh sách và chi tiết các bài viết kỹ thuật.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
### Blog List Page
|
||||
|
||||
```
|
||||
BlogListPage
|
||||
├── PageHeader
|
||||
│ └── Title (H1)
|
||||
└── ArticleList (×N)
|
||||
└── ArticleCard (×N)
|
||||
├── Date
|
||||
├── Title
|
||||
├── Summary (1–2 lines)
|
||||
├── Tags
|
||||
└── Read time
|
||||
```
|
||||
|
||||
### Blog Detail Page
|
||||
|
||||
```
|
||||
BlogDetailPage
|
||||
├── PageHeader
|
||||
│ ├── Back link
|
||||
│ ├── Title (H1)
|
||||
│ ├── Meta
|
||||
│ │ ├── Date
|
||||
│ │ ├── Read time
|
||||
│ │ └── Tags
|
||||
└── ArticleContent
|
||||
└── Markdown rendered content
|
||||
├── Headings (H2, H3)
|
||||
├── Paragraphs
|
||||
├── Code blocks (syntax highlighted)
|
||||
├── Images
|
||||
├── Lists
|
||||
└── Blockquotes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content Model
|
||||
|
||||
```ts
|
||||
interface Article {
|
||||
id: string;
|
||||
slug: string;
|
||||
title: string;
|
||||
summary: string;
|
||||
date: string; // ISO date
|
||||
readTime: number; // minutes
|
||||
tags: string[];
|
||||
coverImage?: string;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
### Desktop
|
||||
|
||||
- Blog list: max-width 800px, single column
|
||||
- Article cards: bordered, padding, hover shadow
|
||||
- Blog detail: max-width 700px, prose width
|
||||
- Code blocks: full-width within content, dark bg
|
||||
- Sidebar (optional): table of contents, sticky
|
||||
|
||||
### Mobile
|
||||
|
||||
- Blog list: single column, full-width cards
|
||||
- Blog detail: full-width content, smaller code blocks
|
||||
- No sidebar
|
||||
|
||||
---
|
||||
|
||||
## ArticleCard
|
||||
|
||||
| Variant | Style |
|
||||
|---|---|
|
||||
| Default | Border, padding, flex column |
|
||||
| Hover | Shadow, lift 2px |
|
||||
|
||||
---
|
||||
|
||||
## Code Block
|
||||
|
||||
| Variant | Style |
|
||||
|---|---|
|
||||
| Default | Dark background, monospace font, syntax highlighting |
|
||||
| Line numbers | Optional, muted color |
|
||||
| Copy button | Top-right corner, icon-only |
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Element | Size | Weight |
|
||||
|---|---|---|
|
||||
| Page title (H1) | 40px / 32px mobile | 600 |
|
||||
| Article title (H2) | 24px | 600 |
|
||||
| Article summary | 14px | 400 |
|
||||
| Article meta | 14px | 400 |
|
||||
| Tag | 12px | 400 |
|
||||
| Body text | 16px | 400 |
|
||||
| Code | 14px | 400 |
|
||||
| Code block | 14px | 400 |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- H1 page title, H2 article titles, H3/H4 in content
|
||||
- Semantic `<article>` for each post
|
||||
- Code blocks: `<pre><code>` semantic
|
||||
- Table of contents: `nav` with `aria-label="Table of contents"`
|
||||
- Syntax highlighted code: not critical for accessibility
|
||||
- Focus visible on all interactive elements
|
||||
|
||||
---
|
||||
|
||||
## Animation
|
||||
|
||||
- Article cards fade-in stagger (80ms delay)
|
||||
- Code block copy button: feedback animation (200ms)
|
||||
|
||||
---
|
||||
|
||||
## State
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| Default | Normal render |
|
||||
| Hover | Card lift + shadow |
|
||||
| Loading | Skeleton cards |
|
||||
| Reduced motion | Disable animations |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Content from markdown/MDX files
|
||||
- Slug-based routing (`/blog/:slug`)
|
||||
- SEO metadata per article
|
||||
- Code highlighting via library (e.g., shiki)
|
||||
@@ -0,0 +1,289 @@
|
||||
# UI Spec — Reusable Components
|
||||
|
||||
## Overview
|
||||
|
||||
Common UI components used across the portfolio.
|
||||
|
||||
---
|
||||
|
||||
## Button
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
Button
|
||||
├── Icon (optional)
|
||||
├── Text
|
||||
└── Loading spinner (optional)
|
||||
```
|
||||
|
||||
### Variants
|
||||
|
||||
| Variant | Background | Text | Border | Use case |
|
||||
|---|---|---|---|---|
|
||||
| Primary | Accent | White | None | CTA |
|
||||
| Secondary | Transparent | Accent | 1px accent | Secondary action |
|
||||
| Ghost | Transparent | Muted | None | Tertiary action |
|
||||
| Icon | Transparent | None | None | Icon-only button |
|
||||
|
||||
### Sizes
|
||||
|
||||
| Size | Padding | Font size |
|
||||
|---|---|---|
|
||||
| Small | 8px 12px | 12px |
|
||||
| Medium | 12px 24px | 16px |
|
||||
| Large | 16px 32px | 18px |
|
||||
|
||||
### States
|
||||
|
||||
| State | Style |
|
||||
|---|---|
|
||||
| Default | Variant style |
|
||||
| Hover | Lighter/darker shade |
|
||||
| Active | Darker shade |
|
||||
| Disabled | Muted bg/text, no pointer, opacity 0.5 |
|
||||
| Focus | Visible outline (2px accent) |
|
||||
| Loading | Spinner, disabled text |
|
||||
|
||||
---
|
||||
|
||||
## Badge
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
Badge
|
||||
└── Text
|
||||
```
|
||||
|
||||
### Variants
|
||||
|
||||
| Variant | Background | Text | Border |
|
||||
|---|---|---|---|
|
||||
| Default | Accent | White | None |
|
||||
| Outline | Transparent | Accent | 1px accent |
|
||||
| Muted | Muted bg | Muted text | None |
|
||||
|
||||
### Sizes
|
||||
|
||||
| Size | Padding | Font size |
|
||||
|---|---|---|
|
||||
| Small | 4px 8px | 11px |
|
||||
| Medium | 6px 12px | 12px |
|
||||
|
||||
### Use cases
|
||||
|
||||
- Category tags
|
||||
- Status indicators
|
||||
- Project categories
|
||||
|
||||
---
|
||||
|
||||
## Card
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
Card
|
||||
├── Header (optional)
|
||||
│ ├── Title
|
||||
│ └── Meta
|
||||
├── Body
|
||||
│ └── Content
|
||||
└── Footer (optional)
|
||||
├── Actions
|
||||
└── Meta
|
||||
```
|
||||
|
||||
### Variants
|
||||
|
||||
| Variant | Border | Background | Shadow |
|
||||
|---|---|---|---|
|
||||
| Default | 1px border | Surface | None |
|
||||
| Elevated | None | Elevated | Subtle shadow |
|
||||
| Featured | 4px accent top | Surface | Subtle shadow |
|
||||
|
||||
### States
|
||||
|
||||
| State | Style |
|
||||
|---|---|
|
||||
| Default | Variant style |
|
||||
| Hover | Shadow + lift 2px |
|
||||
| Clickable | Cursor pointer |
|
||||
| Focus | Visible outline |
|
||||
|
||||
---
|
||||
|
||||
## Tag
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
Tag
|
||||
└── Text
|
||||
```
|
||||
|
||||
### Variants
|
||||
|
||||
| Variant | Background | Text |
|
||||
|---|---|---|
|
||||
| Default | Muted bg | Muted text |
|
||||
| Accent | Accent bg | White |
|
||||
|
||||
### Use cases
|
||||
|
||||
- Technology labels
|
||||
- Skill tags
|
||||
- Filter pills
|
||||
- Category labels
|
||||
|
||||
---
|
||||
|
||||
## SectionHeading
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
SectionHeading
|
||||
├── Number (optional, "01", "02")
|
||||
├── Title (H2 or H3)
|
||||
└── Subtitle (optional)
|
||||
```
|
||||
|
||||
### Variants
|
||||
|
||||
| Variant | Size |
|
||||
|---|---|
|
||||
| Large | 40px desktop / 32px mobile |
|
||||
| Medium | 24px |
|
||||
| Small | 20px |
|
||||
|
||||
---
|
||||
|
||||
## CodeBlock
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
CodeBlock
|
||||
├── Header (optional)
|
||||
│ ├── Language label
|
||||
│ └── Copy button
|
||||
├── Code (pre > code)
|
||||
│ ├── Line numbers (optional)
|
||||
│ └── Syntax highlighted content
|
||||
└── Footer (optional)
|
||||
```
|
||||
|
||||
### Styles
|
||||
|
||||
| Property | Value |
|
||||
|---|---|
|
||||
| Background | Dark bg (#1a1a1a) |
|
||||
| Font | Monospace, 14px |
|
||||
| Padding | 16px |
|
||||
| Border-radius | 6px |
|
||||
| Border | 1px border |
|
||||
| Overflow | Auto (scroll) |
|
||||
|
||||
### Features
|
||||
|
||||
- Syntax highlighting (shiki)
|
||||
- Copy to clipboard button
|
||||
- Line numbers (optional)
|
||||
- Language label in header
|
||||
|
||||
---
|
||||
|
||||
## ImageGallery
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
ImageGallery
|
||||
├── Main image
|
||||
├── Thumbnails (optional)
|
||||
└── Navigation arrows (optional)
|
||||
```
|
||||
|
||||
### Variants
|
||||
|
||||
| Variant | Description |
|
||||
|---|---|
|
||||
| Single | Single image, lazy loaded |
|
||||
| Grid | Multiple images in grid |
|
||||
| Carousel | Slidable with arrows |
|
||||
|
||||
### States
|
||||
|
||||
| State | Style |
|
||||
|---|---|
|
||||
| Loading | Skeleton placeholder |
|
||||
| Error | Fallback icon + alt text |
|
||||
| Hover | Zoom (subtle) |
|
||||
|
||||
---
|
||||
|
||||
## Tooltip
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
Tooltip
|
||||
└── Text
|
||||
```
|
||||
|
||||
### Variants
|
||||
|
||||
| Variant | Position |
|
||||
|---|---|
|
||||
| Default | Above element |
|
||||
| Below | Below element |
|
||||
| Left | Left of element |
|
||||
| Right | Right of element |
|
||||
|
||||
### Behavior
|
||||
|
||||
- Appears on hover
|
||||
- Appears on focus
|
||||
- Disappears on hover out / blur
|
||||
- Max-width: 250px
|
||||
- Word wrap
|
||||
|
||||
---
|
||||
|
||||
## Container
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
Container
|
||||
└── Children
|
||||
```
|
||||
|
||||
### Variants
|
||||
|
||||
| Variant | Max-width | Padding |
|
||||
|---|---|---|
|
||||
| Wide | 1200px | 0 24px |
|
||||
| Content | 800px | 0 24px |
|
||||
| Full | None | 0 24px |
|
||||
|
||||
---
|
||||
|
||||
## TimelineMarker
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
TimelineMarker
|
||||
└── Dot
|
||||
```
|
||||
|
||||
### Variants
|
||||
|
||||
| Variant | Style |
|
||||
|---|---|
|
||||
| Default | Circle, accent outline, 12px |
|
||||
| Active | Circle, accent fill, 14px |
|
||||
| Completed | Circle, muted outline, 12px |
|
||||
@@ -0,0 +1,140 @@
|
||||
# UI Spec — Contact Section
|
||||
|
||||
## Overview
|
||||
|
||||
Section trang thông tin liên hệ: email, GitHub, LinkedIn, và optional contact form.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
ContactSection
|
||||
├── SectionHeading ("Contact")
|
||||
├── ContactInfo
|
||||
│ ├── Email (link)
|
||||
│ ├── GitHub (link)
|
||||
│ └── LinkedIn (link)
|
||||
└── ContactForm (Phase 2 / optional)
|
||||
├── Name
|
||||
├── Email
|
||||
├── Subject
|
||||
├── Message
|
||||
└── Submit button
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content
|
||||
|
||||
| Element | Value |
|
||||
|---|---|
|
||||
| **Email** | _[TBD — email]_ |
|
||||
| **GitHub** | _[TBD — github URL]_ |
|
||||
| **LinkedIn** | _[TBD — linkedin URL]_ |
|
||||
| **Form** | Optional (Phase 2) |
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
### Desktop
|
||||
|
||||
- Single column, max-width 600px
|
||||
- Contact info: row of 3 links, icon + text
|
||||
- Form (if present): stacked inputs, max-width 500px
|
||||
|
||||
### Mobile
|
||||
|
||||
- Single column
|
||||
- Contact info: stacked or 2-column grid
|
||||
- Form: full-width inputs
|
||||
|
||||
---
|
||||
|
||||
## Contact Links
|
||||
|
||||
| Variant | Style |
|
||||
|---|---|
|
||||
| Default | Icon + text, muted color |
|
||||
| Hover | Accent color |
|
||||
| Focus | Visible outline |
|
||||
|
||||
---
|
||||
|
||||
## Contact Form (Phase 2)
|
||||
|
||||
| Field | Type | Required |
|
||||
|---|---|---|
|
||||
| Name | text input | Yes |
|
||||
| Email | email input | Yes |
|
||||
| Subject | text input | Yes |
|
||||
| Message | textarea | Yes |
|
||||
| Submit | button | — |
|
||||
|
||||
| Variant | Style |
|
||||
|---|---|
|
||||
| Input default | Border, padding, transparent bg |
|
||||
| Input focus | Accent border, shadow |
|
||||
| Input error | Red border, error message below |
|
||||
| Submit default | Accent bg, white text |
|
||||
| Submit hover | Lighter accent |
|
||||
| Submit disabled | Muted bg, no pointer |
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Element | Size | Weight |
|
||||
|---|---|---|
|
||||
| Section heading (H2) | 40px / 32px mobile | 600 |
|
||||
| Link text | 16px | 400 |
|
||||
| Form label | 14px | 500 |
|
||||
| Form input | 16px | 400 |
|
||||
| Form placeholder | 16px | 400 |
|
||||
| Submit text | 16px | 500 |
|
||||
| Error message | 14px | 400 |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- H2 section heading
|
||||
- Links: `aria-label` with platform name
|
||||
- Form: `<label>` for each input, `aria-describedby` for errors
|
||||
- Form validation: aria-invalid on invalid fields
|
||||
- Submit: `aria-disabled` when disabled
|
||||
- Focus visible on all form elements
|
||||
- Error messages: `role="alert"`
|
||||
|
||||
---
|
||||
|
||||
## Animation
|
||||
|
||||
- Links: color transition 150ms
|
||||
- Form: focus ring 200ms
|
||||
- Submit: hover/active transitions 150ms
|
||||
|
||||
---
|
||||
|
||||
## State
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| Default | Normal render |
|
||||
| Hover | Link color change |
|
||||
| Focus | Visible outline |
|
||||
| Form error | Red border + message |
|
||||
| Form success | Success message |
|
||||
| Form submitting | Disabled button + loading state |
|
||||
| Reduced motion | Disable transitions |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Phase 1: links only (mailto: for email)
|
||||
- Phase 2: form with external service (Formspree, etc.)
|
||||
- Form validation: client-side + server-side
|
||||
- Rate limiting on form submit (Phase 2)
|
||||
- Spam protection (Phase 2)
|
||||
@@ -0,0 +1,105 @@
|
||||
# UI Spec — Engineering Section
|
||||
|
||||
## Overview
|
||||
|
||||
Section giới thiệu các lĩnh vực engineering focus: Architecture, AI/ML, Experiments.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
EngineeringSection
|
||||
├── SectionHeading ("Engineering")
|
||||
├── Tabs or SubSections
|
||||
│ ├── Architecture
|
||||
│ ├── AI / ML
|
||||
│ └── Experiments
|
||||
└── ContentBlocks (×N)
|
||||
├── Title
|
||||
├── Description
|
||||
└── RelatedProjects (links)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content
|
||||
|
||||
### Architecture
|
||||
|
||||
- System design, distributed systems, integration architecture
|
||||
- Link to relevant projects
|
||||
|
||||
### AI / ML
|
||||
|
||||
- Computer Vision, Object Detection, OCR, YOLO, ONNX, LLM
|
||||
- Link to relevant projects
|
||||
- Not an AI portfolio — frame as "applying AI to real problems"
|
||||
|
||||
### Experiments
|
||||
|
||||
- Local LLM, MoE, llama.cpp, GPU optimization
|
||||
- Performance tracing, benchmarking
|
||||
- Engineering experiments blog posts
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
### Desktop
|
||||
|
||||
- Tab navigation hoặc sequential sections
|
||||
- Each tab/section: max-width 800px
|
||||
- Content: text + related project cards
|
||||
|
||||
### Mobile
|
||||
|
||||
- Accordion-style sections (expand/collapse)
|
||||
- Single column
|
||||
- Smaller font sizes
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Element | Size | Weight |
|
||||
|---|---|---|
|
||||
| Section heading (H2) | 40px / 32px mobile | 600 |
|
||||
| Tab/Section title (H3) | 24px | 500 |
|
||||
| Description | 16px | 400 |
|
||||
| Related project link | 14px | 500 |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- H2 section, H3 subsections
|
||||
- Tabs: `role="tablist"`, `role="tab"`, `role="tabpanel"`
|
||||
- Keyboard: arrow keys for tabs, Enter to activate
|
||||
- Screen reader: active tab announced
|
||||
|
||||
---
|
||||
|
||||
## Animation
|
||||
|
||||
- Tab content fade-in (200ms)
|
||||
- Accordion: smooth height transition (300ms)
|
||||
|
||||
---
|
||||
|
||||
## State
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| Default | First tab/section active |
|
||||
| Tab active | Accent underline, content visible |
|
||||
| Accordion open | Expanded content |
|
||||
| Reduced motion | Disable transitions |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Data-driven từ `projects.ts` (filter by category)
|
||||
- Tab state in URL (`?tab=ai-ml`)
|
||||
- Shareable URLs
|
||||
@@ -0,0 +1,150 @@
|
||||
# UI Spec — Experience Section
|
||||
|
||||
## Overview
|
||||
|
||||
Timeline hiển thị kinh nghiệm làm việc, tập trung vào achievements và impact.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
ExperienceSection
|
||||
├── SectionHeading ("Experience")
|
||||
└── ExperienceTimeline
|
||||
└── ExperienceEntry (×N)
|
||||
├── TimelineMarker
|
||||
├── Company/RoleHeader
|
||||
│ ├── Title
|
||||
│ ├── Company
|
||||
│ └── Duration
|
||||
├── Responsibilities
|
||||
│ └── List items
|
||||
├── FeaturedAchievement (optional)
|
||||
│ ├── AchievementTitle
|
||||
│ ├── Context
|
||||
│ ├── TechnicalWork
|
||||
│ ├── Impact (with metrics)
|
||||
│ └── Tags (technologies)
|
||||
└── ExpandableDetails (optional)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content Model
|
||||
|
||||
```ts
|
||||
interface ExperienceEntry {
|
||||
id: string;
|
||||
title: string;
|
||||
company: string;
|
||||
duration: string; // e.g. "2021 – Present"
|
||||
location?: string;
|
||||
responsibilities: string[];
|
||||
achievements?: FeaturedAchievement[];
|
||||
}
|
||||
|
||||
interface FeaturedAchievement {
|
||||
id: string;
|
||||
title: string;
|
||||
context: string;
|
||||
technicalWork: string[];
|
||||
impact: string;
|
||||
metrics?: string[];
|
||||
technologies: string[];
|
||||
featured: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
### Desktop
|
||||
|
||||
- Timeline line bên trái
|
||||
- Entries bên phải timeline
|
||||
- Mỗi entry: full-width card
|
||||
- Featured achievement: nested card với accent border
|
||||
- Metrics: highlight box (accent background, white text)
|
||||
- Tags: row of pills
|
||||
|
||||
### Mobile
|
||||
|
||||
- Timeline line ẩn
|
||||
- Entries: stacked cards
|
||||
- Featured achievement: full-width nested card
|
||||
- Metrics: inline highlight
|
||||
- Tags: wrap pills
|
||||
|
||||
---
|
||||
|
||||
## Timeline Marker
|
||||
|
||||
| Variant | Style |
|
||||
|---|---|
|
||||
| Default | Circle, accent color, 12px diameter |
|
||||
| Active (current role) | Circle, accent fill, 14px diameter |
|
||||
| Completed | Circle, accent outline, 12px diameter |
|
||||
|
||||
---
|
||||
|
||||
## Featured Achievement
|
||||
|
||||
| Variant | Style |
|
||||
|---|---|
|
||||
| Default | Accent left border (4px), padding, subtle bg |
|
||||
| Metrics | Accent bg, white text, bold |
|
||||
| Tags | Pill style, muted bg, muted text |
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Element | Size | Weight |
|
||||
|---|---|---|
|
||||
| Section heading (H2) | 40px / 32px mobile | 600 |
|
||||
| Role title | 20px | 600 |
|
||||
| Company | 16px | 400 |
|
||||
| Duration | 14px | 400 |
|
||||
| Responsibility | 14px | 400 |
|
||||
| Achievement title | 18px | 500 |
|
||||
| Impact metric | 16px | 600 |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- H2 section, H3 entry titles
|
||||
- Semantic `<time>` cho duration
|
||||
- `aria-label` cho timeline
|
||||
- Metrics: semantic highlight, không chỉ màu
|
||||
- Keyboard navigate giữa entries
|
||||
|
||||
---
|
||||
|
||||
## Animation
|
||||
|
||||
- Timeline line draw từ trên xuống khi scroll vào viewport
|
||||
- Entries fade-in stagger (150ms delay)
|
||||
- Featured achievement: accent border appear
|
||||
|
||||
---
|
||||
|
||||
## State
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| Default | Normal render |
|
||||
| Hover | Entry subtle lift (shadow) |
|
||||
| Scroll reveal | Fade-in + slide-up |
|
||||
| Reduced motion | Disable animations |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Data-driven từ `experience.ts`
|
||||
- Entries có thể 0 → render empty state
|
||||
- Featured achievements là optional trong entry
|
||||
- Không hard-code entry count
|
||||
@@ -0,0 +1,110 @@
|
||||
# UI Spec — Expertise Section
|
||||
|
||||
## Overview
|
||||
|
||||
Hiển thị các nhóm kỹ năng/chuyên môn thành các card nhóm.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
ExpertiseSection
|
||||
├── SectionHeading ("Core Expertise")
|
||||
└── SkillGroupsGrid
|
||||
├── SkillGroup (×5–6)
|
||||
│ ├── GroupTitle (H3)
|
||||
│ └── SkillsList
|
||||
│ └── Skill items (×5–8 mỗi group)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content
|
||||
|
||||
| Group | Skills |
|
||||
|---|---|
|
||||
| **Software Engineering** | Java, Go, TypeScript, Distributed Systems, REST APIs, Microservices |
|
||||
| **System Architecture** | System Design, Integration Architecture, Event-driven Architecture, Message Queues, API Design |
|
||||
| **Logistics Technology** | Sortation, Warehouse/Facility Operations, Package Flow, Operational Intelligence, Facility Modeling |
|
||||
| **AI / ML** | Computer Vision, Object Detection, OCR, Model Deployment, LLM, AI-assisted Engineering |
|
||||
| **Infrastructure** | Docker, Linux, CI/CD, Networking, Middleware |
|
||||
| **Engineering Practices** | Agile/Scrum, Technical Documentation, System Maintenance, Performance Optimization, Technical Research |
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
### Desktop
|
||||
|
||||
- Grid: 3 columns (2x3)
|
||||
- Mỗi card: border, padding, subtle background
|
||||
- Group title: accent color, H3
|
||||
- Skills: bullet list hoặc tag pills
|
||||
- Row gap: 24px, column gap: 24px
|
||||
|
||||
### Mobile
|
||||
|
||||
- Single column stack
|
||||
- Mỗi card full-width
|
||||
- Skills: 2-column tag pills
|
||||
- Padding card: 16px
|
||||
|
||||
### Tablet
|
||||
|
||||
- Grid: 2 columns (3x2)
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Element | Size | Weight |
|
||||
|---|---|---|
|
||||
| Section heading (H2) | 40px / 32px mobile | 600 |
|
||||
| Group title (H3) | 20px | 500 |
|
||||
| Skill item | 14px | 400 |
|
||||
|
||||
---
|
||||
|
||||
## SkillGroup Card
|
||||
|
||||
| Variant | Style |
|
||||
|---|---|
|
||||
| Default | Border, transparent bg |
|
||||
| Hover | Border accent color, subtle shadow |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- H2 section, H3 group titles
|
||||
- Semantic `<ul>` cho skill lists
|
||||
- Contrast >= 4.5:1
|
||||
- Group titles có `id` cho anchor link (optional)
|
||||
|
||||
---
|
||||
|
||||
## Animation
|
||||
|
||||
- Cards fade-in khi scroll vào viewport
|
||||
- Stagger: 80ms delay per card
|
||||
- Hover: border color transition 200ms
|
||||
|
||||
---
|
||||
|
||||
## State
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| Default | Normal render |
|
||||
| Hover | Border accent, subtle shadow |
|
||||
| Scroll reveal | Fade-in + slide-up |
|
||||
| Reduced motion | Disable animations |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Data-driven từ `skills.ts`
|
||||
- Số lượng groups và skills có thể thay đổi
|
||||
- Group không có skill nào → không render card đó
|
||||
@@ -0,0 +1,88 @@
|
||||
# UI Spec — Footer
|
||||
|
||||
## Overview
|
||||
|
||||
Footer đơn giản ở cuối mỗi trang. Chứa copyright, social links, nav links.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
Footer
|
||||
├── Container (max-width, centered)
|
||||
├── FooterContent
|
||||
│ ├── Copyright
|
||||
│ ├── NavLinks
|
||||
│ │ ├── Home
|
||||
│ │ ├── About
|
||||
│ │ ├── Projects
|
||||
│ │ └── Contact
|
||||
│ └── SocialLinks
|
||||
│ ├── GitHub
|
||||
│ ├── LinkedIn
|
||||
│ └── Email
|
||||
└── BackToTop (optional)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content
|
||||
|
||||
| Element | Value |
|
||||
|---|---|
|
||||
| **Copyright** | `© {year} {name}. All rights reserved.` |
|
||||
| **Nav links** | Home, About, Projects, Contact |
|
||||
| **Social links** | GitHub, LinkedIn, Email |
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
### Desktop
|
||||
|
||||
- Single row or 2-row layout
|
||||
- Copyright left, links center, social right
|
||||
- Or: centered single row
|
||||
|
||||
### Mobile
|
||||
|
||||
- Centered, stacked
|
||||
- Social links: row
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Element | Size | Weight |
|
||||
|---|---|---|
|
||||
| Copyright | 14px | 400 |
|
||||
| Nav link | 14px | 400 |
|
||||
| Social label | 14px | 400 |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- `role="contentinfo"`
|
||||
- Semantic `<footer>` element
|
||||
- Links: `aria-label` với platform name
|
||||
- Back to top: `aria-label="Back to top"`
|
||||
|
||||
---
|
||||
|
||||
## State
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| Default | Normal render |
|
||||
| Hover | Link color change |
|
||||
| Focus | Visible outline |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Minimal, non-distracting
|
||||
- Not more prominent than main content
|
||||
- Copyright year auto-update
|
||||
@@ -0,0 +1,144 @@
|
||||
# UI Spec — Hero Section
|
||||
|
||||
## Overview
|
||||
|
||||
Section đầu tiên của homepage. Truyền tải identity, positioning, CTA chính.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
Hero
|
||||
├── ContentBlock
|
||||
│ ├── Name (H1, large display)
|
||||
│ ├── Title (H2, "Senior Software Engineer")
|
||||
│ ├── Tagline (3-line description)
|
||||
│ ├── CTA Group
|
||||
│ │ ├── Primary CTA ("View Projects")
|
||||
│ │ └── Secondary CTA ("Contact Me")
|
||||
│ └── Social Links
|
||||
│ ├── GitHub
|
||||
│ ├── LinkedIn
|
||||
│ └── Email
|
||||
└── VisualBlock
|
||||
└── Engineering visual (SVG/Canvas/abstract graphic)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content
|
||||
|
||||
| Element | Content |
|
||||
|---|---|
|
||||
| **Name** | _[TBD — name]_ |
|
||||
| **Title** | Senior Software Engineer |
|
||||
| **Tagline** | Building scalable software systems, intelligent logistics solutions, and practical AI applications. |
|
||||
| **Primary CTA** | View Projects → /projects |
|
||||
| **Secondary CTA** | Contact Me → /contact |
|
||||
| **Social** | GitHub, LinkedIn, Email |
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
### Desktop
|
||||
|
||||
- 2-column: content trái (60%), visual phải (40%)
|
||||
- Content: vertically centered
|
||||
- Name: 64px, bold
|
||||
- Title: 24px, muted color
|
||||
- Tagline: 18px, 3 lines max
|
||||
- CTA buttons: row, gap 16px
|
||||
- Social links: row below CTA, icon-only, muted → accent on hover
|
||||
|
||||
### Mobile
|
||||
|
||||
- Single column, stacked
|
||||
- Visual block ẩn hoặc thu nhỏ
|
||||
- Name: 40px
|
||||
- Content: vertically centered, padding rộng
|
||||
- CTA buttons: full-width, stacked vertically
|
||||
- Social links: row, centered
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Element | Size | Weight |
|
||||
|---|---|---|
|
||||
| Name (H1) | 64px desktop / 40px mobile | 700 |
|
||||
| Title (H2) | 24px | 400 |
|
||||
| Tagline | 18px | 400 |
|
||||
| CTA text | 16px | 500 |
|
||||
| Social label | 14px | 400 |
|
||||
|
||||
---
|
||||
|
||||
## Visual Block
|
||||
|
||||
- Không stock photo
|
||||
- Engineering-inspired abstract graphic
|
||||
- Options: system diagram, data-flow visual, animated nodes
|
||||
- Subtle animation: nodes connect, lines draw
|
||||
- Không distracting, không blocking content
|
||||
- fallback: static SVG nếu animation phức tạp
|
||||
|
||||
---
|
||||
|
||||
## Buttons
|
||||
|
||||
### Primary CTA
|
||||
|
||||
- Background: accent color
|
||||
- Text: near-white
|
||||
- Padding: 12px 24px
|
||||
- Border-radius: 6px
|
||||
- Hover: lighter accent
|
||||
- Active: darker accent
|
||||
|
||||
### Secondary CTA
|
||||
|
||||
- Background: transparent
|
||||
- Border: 1px solid border color
|
||||
- Text: accent color
|
||||
- Hover: accent background, white text
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- H1 duy nhất trên trang
|
||||
- CTA buttons: semantic `<a>` styled as button
|
||||
- Social links: `aria-label` với platform name
|
||||
- Visual block: `role="presentation"`, `aria-hidden="true"`
|
||||
- Contrast ratio >= 4.5:1 cho text
|
||||
- Focus visible trên tất cả interactive elements
|
||||
|
||||
---
|
||||
|
||||
## Animation
|
||||
|
||||
- Fade-in content từ dưới (subtle, 300ms)
|
||||
- Visual block: nodes connect animation (nếu dùng)
|
||||
- Hover trên buttons: scale 1.02
|
||||
- Không parallax, không continuous animation
|
||||
|
||||
---
|
||||
|
||||
## State
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| Default | Normal render |
|
||||
| Hover | Button hovers, social link hovers |
|
||||
| Focus | Keyboard navigation |
|
||||
| Reduced motion | Disable all animations |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Không hard-code content trong JSX — data-driven từ `profile.ts`
|
||||
- Social links có thể empty → không render link đó
|
||||
- CTA chỉ render khi URL có sẵn
|
||||
@@ -0,0 +1,136 @@
|
||||
# UI Spec — Layout & Theme
|
||||
|
||||
## Overview
|
||||
|
||||
Global layout structure, theme system, and page transitions.
|
||||
|
||||
---
|
||||
|
||||
## Layout Structure
|
||||
|
||||
```
|
||||
App
|
||||
├── Navigation (sticky top)
|
||||
├── Main Content
|
||||
│ └── Page Container
|
||||
│ └── Page Content
|
||||
└── Footer (bottom)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Page Container
|
||||
|
||||
| Property | Value |
|
||||
|---|---|
|
||||
| Max-width | 1200px (wide sections), 800px (content sections) |
|
||||
| Padding | 0 24px (desktop), 0 16px (mobile) |
|
||||
| Margin | Auto center |
|
||||
|
||||
---
|
||||
|
||||
## Section Spacing
|
||||
|
||||
| Property | Value |
|
||||
|---|---|
|
||||
| Vertical padding | 80px (desktop), 48px (mobile) |
|
||||
| Between sections | 0 (continuous flow) |
|
||||
|
||||
---
|
||||
|
||||
## Theme System
|
||||
|
||||
### Modes
|
||||
|
||||
| Mode | Description |
|
||||
|---|---|
|
||||
| Dark | Primary mode, near-black background |
|
||||
| Light | Secondary mode, white background |
|
||||
| System | Follow OS preference |
|
||||
|
||||
### Default
|
||||
|
||||
- System preference
|
||||
- Persist in `localStorage`
|
||||
|
||||
### CSS Variables
|
||||
|
||||
```css
|
||||
/* Dark mode (default) */
|
||||
--bg-primary: #0a0a0a;
|
||||
--bg-surface: #141414;
|
||||
--bg-elevated: #1a1a1a;
|
||||
--text-primary: #f0f0f0;
|
||||
--text-secondary: #a0a0a0;
|
||||
--text-muted: #666666;
|
||||
--accent: #60a5fa;
|
||||
--border: #2a2a2a;
|
||||
--shadow: rgba(0, 0, 0, 0.3);
|
||||
|
||||
/* Light mode */
|
||||
--bg-primary: #ffffff;
|
||||
--bg-surface: #f5f5f5;
|
||||
--bg-elevated: #ffffff;
|
||||
--text-primary: #0a0a0a;
|
||||
--text-secondary: #404040;
|
||||
--text-muted: #808080;
|
||||
--accent: #2563eb;
|
||||
--border: #e0e0e0;
|
||||
--shadow: rgba(0, 0, 0, 0.1);
|
||||
```
|
||||
|
||||
### Single Accent Color
|
||||
|
||||
- Only one accent color per theme
|
||||
- Avoid multi-color palette
|
||||
- Use accent for: links, active states, CTAs, badges, highlights
|
||||
|
||||
---
|
||||
|
||||
## Theme Toggle
|
||||
|
||||
| Property | Value |
|
||||
|---|---|
|
||||
| Location | Navigation bar (right side) |
|
||||
| Icon | Sun/Moon icon |
|
||||
| Tooltip | Current mode (dark/light/system) |
|
||||
| Click behavior | Cycle: dark → light → system → dark |
|
||||
|
||||
---
|
||||
|
||||
## Page Transitions
|
||||
|
||||
- Fade transition between routes (200ms)
|
||||
- No slide, no parallax
|
||||
- Respect `prefers-reduced-motion`
|
||||
|
||||
---
|
||||
|
||||
## Responsive Breakpoints
|
||||
|
||||
| Breakpoint | Width | Description |
|
||||
|---|---|---|
|
||||
| Mobile | < 768px | Single column, touch-optimized |
|
||||
| Tablet | 768–1023px | Adaptive grid |
|
||||
| Desktop | >= 1024px | Multi-column, wide layouts |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- `prefers-color-scheme` media query
|
||||
- `prefers-reduced-motion` media query
|
||||
- Theme toggle: `aria-label` with current mode
|
||||
- Focus visible: accent color outline (2px)
|
||||
- Contrast ratio >= 4.5:1 for all text
|
||||
- No theme flash on page load (inline script)
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Theme state in context/provider (not global store)
|
||||
- Persist preference in `localStorage`
|
||||
- Inline script in `<head>` to prevent flash
|
||||
- CSS variables for all theme values
|
||||
- No hardcoded colors in components
|
||||
@@ -0,0 +1,108 @@
|
||||
# UI Spec — Navigation
|
||||
|
||||
## Overview
|
||||
|
||||
Sticky navigation bar xuất hiện ở top mọi trang. Chứa logo, menu links, theme toggle.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
Navigation
|
||||
├── Container (max-width, centered, padding)
|
||||
│ ├── Logo (link → /)
|
||||
│ ├── Menu (desktop)
|
||||
│ │ ├── Home
|
||||
│ │ ├── About
|
||||
│ │ ├── Experience
|
||||
│ │ ├── Projects
|
||||
│ │ ├── Engineering
|
||||
│ │ ├── Blog
|
||||
│ │ └── Contact
|
||||
│ ├── ThemeToggle (dark/light/system)
|
||||
│ └── MobileMenuButton (hamburger)
|
||||
└── MobileMenu (overlay, slide-in từ phải)
|
||||
├── Menu links (vertical stack)
|
||||
└── ThemeToggle
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Props
|
||||
|
||||
```ts
|
||||
interface NavigationProps {
|
||||
currentPage: string;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Desktop Behavior
|
||||
|
||||
- Sticky top, z-index cao nhất (trừ modal)
|
||||
- Background: surface color, backdrop-blur khi scroll
|
||||
- Logo bên trái, menu giữa, theme toggle bên phải
|
||||
- Menu links: text color muted, active state accent color, hover underline nhẹ
|
||||
- Spacer giữa menu và theme toggle
|
||||
|
||||
---
|
||||
|
||||
## Mobile Behavior
|
||||
|
||||
- Logo bên trái, hamburger bên phải
|
||||
- Menu button: icon 3 lines, toggle thành X khi mở
|
||||
- Mobile menu: full-screen overlay, slide-in từ phải
|
||||
- Menu links: vertical stack, font-size lớn, padding rộng
|
||||
- Click ngoài overlay → đóng menu
|
||||
- Click link → đóng menu + navigate
|
||||
- Body scroll lock khi menu mở
|
||||
|
||||
---
|
||||
|
||||
## Responsive Breakpoints
|
||||
|
||||
| Breakpoint | Width | Behavior |
|
||||
|---|---|---|
|
||||
| Mobile | < 768px | Hamburger menu |
|
||||
| Tablet | 768–1023px | Full menu |
|
||||
| Desktop | >= 1024px | Full menu |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- `role="navigation"` trên container
|
||||
- `aria-label="Main navigation"`
|
||||
- Mobile menu: `aria-expanded`, `aria-controls`
|
||||
- Focus trap khi menu mở
|
||||
- Escape → đóng menu
|
||||
- Focus return về hamburger button khi đóng
|
||||
- Semantic `<nav>` element
|
||||
- Skip link (first focusable element) → "Skip to content"
|
||||
|
||||
---
|
||||
|
||||
## State
|
||||
|
||||
- `isOpen` (mobile menu)
|
||||
- `currentPage` (active link highlighting)
|
||||
- `scrolled` (background blur trigger)
|
||||
|
||||
---
|
||||
|
||||
## Variants
|
||||
|
||||
| Variant | Context |
|
||||
|---|---|
|
||||
| Default | All pages |
|
||||
| Scrolled | When page scroll Y > 0 |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Không hard-code links — derive từ routes
|
||||
- Logo clickable → /
|
||||
- Theme toggle không trigger re-render toàn bộ app (context-based)
|
||||
@@ -0,0 +1,157 @@
|
||||
# UI Spec — Project Detail Page
|
||||
|
||||
## Overview
|
||||
|
||||
Trang chi tiết từng featured project. Tuân theo storytelling template.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
ProjectDetailPage
|
||||
├── PageHeader
|
||||
│ ├── Breadcrumb (Projects → Project title)
|
||||
│ ├── Title (H1)
|
||||
│ ├── Meta
|
||||
│ │ ├── Category badge
|
||||
│ │ ├── Role
|
||||
│ │ └── Technologies (tags)
|
||||
│ └── Links (GitHub, Demo — optional)
|
||||
├── StoryBlock (×9 sections)
|
||||
│ ├── 01 — Context
|
||||
│ ├── 02 — Problem
|
||||
│ ├── 03 — Constraints
|
||||
│ ├── 04 — Solution
|
||||
│ ├── 05 — Architecture
|
||||
│ │ └── ArchitectureDiagram (SVG/interactive)
|
||||
│ ├── 06 — Implementation
|
||||
│ ├── 07 — Challenges
|
||||
│ ├── 08 — Result
|
||||
│ │ └── Metrics (highlight boxes)
|
||||
│ └── 09 — Lessons Learned
|
||||
└── Navigation
|
||||
├── Previous project
|
||||
└── Next project
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content Model
|
||||
|
||||
```ts
|
||||
interface ProjectDetail {
|
||||
id: string;
|
||||
title: string;
|
||||
summary: string;
|
||||
category: ProjectCategory;
|
||||
role: string;
|
||||
technologies: string[];
|
||||
githubUrl?: string;
|
||||
demoUrl?: string;
|
||||
|
||||
sections: ProjectSection[];
|
||||
}
|
||||
|
||||
interface ProjectSection {
|
||||
id: string;
|
||||
number: number; // 01–09
|
||||
title: string;
|
||||
content: string; // markdown or HTML
|
||||
type: 'text' | 'diagram' | 'metrics' | 'code';
|
||||
images?: string[];
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
### Desktop
|
||||
|
||||
- Single column, max-width 800px
|
||||
- Page header: centered, large title
|
||||
- Story blocks: sequential, each separated by divider
|
||||
- Architecture diagram: full-width within content area
|
||||
- Metrics: grid of highlight boxes
|
||||
- Previous/Next nav: row at bottom
|
||||
|
||||
### Mobile
|
||||
|
||||
- Single column
|
||||
- Page header: stacked, smaller title
|
||||
- Diagram: scrollable horizontally hoặc fit-width
|
||||
- Metrics: stack vertically
|
||||
- Previous/Next: stacked buttons
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Element | Size | Weight |
|
||||
|---|---|---|
|
||||
| Page title (H1) | 40px / 32px mobile | 600 |
|
||||
| Section number | 14px | 400 |
|
||||
| Section title (H3) | 24px | 500 |
|
||||
| Section content | 16px | 400 |
|
||||
| Meta info | 14px | 400 |
|
||||
| Tech tag | 12px | 400 |
|
||||
| Metric | 16px | 600 |
|
||||
|
||||
---
|
||||
|
||||
## Architecture Diagram
|
||||
|
||||
| Variant | Style |
|
||||
|---|---|
|
||||
| Static SVG | Rendered SVG, zoom/pan if needed |
|
||||
| Interactive (future) | Clickable nodes, zoom, pan, tooltips |
|
||||
|
||||
---
|
||||
|
||||
## Metrics
|
||||
|
||||
- Accent background, white text
|
||||
- Grid layout (2 columns desktop, 1 column mobile)
|
||||
- Each metric: number (large) + label (small)
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- H1 page title, H3 section titles
|
||||
- Semantic `<article>` cho project
|
||||
- Breadcrumb: `aria-label="Breadcrumb"`
|
||||
- Diagram: `alt` text, `aria-label`
|
||||
- Links: `aria-label` với URL description
|
||||
- Focus visible trên tất cả elements
|
||||
- Content: semantic headings hierarchy
|
||||
|
||||
---
|
||||
|
||||
## Animation
|
||||
|
||||
- Story blocks fade-in khi scroll
|
||||
- Diagram: fade-in
|
||||
- Metrics: counter animation (optional, subtle)
|
||||
|
||||
---
|
||||
|
||||
## State
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| Default | Normal render |
|
||||
| Loading | Skeleton for content |
|
||||
| Error | 404 or not-found state |
|
||||
| Reduced motion | Disable animations |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Data-driven từ `projects.ts`
|
||||
- Sections có thể partial (không phải project có đủ 9 sections)
|
||||
- Missing images → graceful degradation
|
||||
- Missing URLs → hide link buttons
|
||||
- Diagram: static fallback if interactive unavailable
|
||||
@@ -0,0 +1,91 @@
|
||||
# UI Spec — Projects List Page (/projects)
|
||||
|
||||
## Overview
|
||||
|
||||
Trang danh sách tất cả projects, với filter theo category.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
ProjectsListPage
|
||||
├── PageHeader
|
||||
│ └── Title (H1)
|
||||
├── FilterBar
|
||||
│ └── CategoryFilter (pills)
|
||||
│ ├── All
|
||||
│ ├── Software Engineering
|
||||
│ ├── Logistics
|
||||
│ ├── AI / ML
|
||||
│ ├── Computer Vision
|
||||
│ ├── Architecture
|
||||
│ └── Experiment
|
||||
└── ProjectGrid (×N)
|
||||
└── ProjectCard (same as homepage card)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
### Desktop
|
||||
|
||||
- Page header: centered, H1
|
||||
- Filter bar: row of pills, centered
|
||||
- Grid: 2 columns
|
||||
- Active filter: accent background
|
||||
|
||||
### Mobile
|
||||
|
||||
- Page header: stacked
|
||||
- Filter bar: horizontal scroll pills
|
||||
- Grid: 1 column
|
||||
- Active filter: accent fill
|
||||
|
||||
---
|
||||
|
||||
## FilterBar
|
||||
|
||||
| Variant | Style |
|
||||
|---|---|
|
||||
| Default | Transparent bg, muted border, muted text |
|
||||
| Active | Accent bg, white text |
|
||||
| Hover | Accent border |
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Element | Size | Weight |
|
||||
|---|---|---|
|
||||
| Page title (H1) | 40px / 32px mobile | 600 |
|
||||
| Filter pill | 14px | 500 |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- H1 page title
|
||||
- Filter pills: `role="listbox"`, active item `aria-selected="true"`
|
||||
- Keyboard navigate filters (arrow keys)
|
||||
- Project cards: `<article>` semantic
|
||||
|
||||
---
|
||||
|
||||
## State
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| Default (All) | Show all projects |
|
||||
| Filtered | Show only selected category |
|
||||
| Empty | No projects in category → show message |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Data-driven từ `projects.ts`
|
||||
- Filter state trong URL query param (`?category=ai-ml`)
|
||||
- URL state shareable
|
||||
- ProjectCard reuse từ homepage component
|
||||
@@ -0,0 +1,156 @@
|
||||
# UI Spec — Projects Section
|
||||
|
||||
## Overview
|
||||
|
||||
Homepage section hiển thị 3–4 featured projects dạng grid cards.
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
ProjectsSection
|
||||
├── SectionHeading ("Featured Projects")
|
||||
├── ProjectGrid (×3–4)
|
||||
│ └── ProjectCard (×N)
|
||||
│ ├── CategoryBadge
|
||||
│ ├── Title
|
||||
│ ├── Summary (1–2 lines)
|
||||
│ ├── TechStack (tags)
|
||||
│ ├── Metrics (optional)
|
||||
│ └── CTA ("View Details")
|
||||
└── ViewAllLink → /projects
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content Model
|
||||
|
||||
```ts
|
||||
interface Project {
|
||||
id: string;
|
||||
title: string;
|
||||
summary: string;
|
||||
category: ProjectCategory;
|
||||
role: string;
|
||||
technologies: string[];
|
||||
metrics?: string[];
|
||||
featured: boolean;
|
||||
githubUrl?: string;
|
||||
demoUrl?: string;
|
||||
images?: string[];
|
||||
}
|
||||
|
||||
type ProjectCategory =
|
||||
| "software-engineering"
|
||||
| "logistics"
|
||||
| "ai-ml"
|
||||
| "computer-vision"
|
||||
| "architecture"
|
||||
| "experiment";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Layout
|
||||
|
||||
### Desktop
|
||||
|
||||
- Grid: 2 columns (2x2)
|
||||
- Cards: equal height, flex layout
|
||||
- Category badge: top-left corner
|
||||
- Title: H3, accent color
|
||||
- Summary: 2 lines max, truncate
|
||||
- Tech stack: row of small pills
|
||||
- Metrics: accent highlight box
|
||||
- CTA: link/button dưới cùng
|
||||
|
||||
### Mobile
|
||||
|
||||
- Single column stack
|
||||
- Cards full-width
|
||||
- Summary: 1 line max
|
||||
- Tech stack: wrap pills
|
||||
- CTA: full-width button
|
||||
|
||||
### Tablet
|
||||
|
||||
- Grid: 1 column (or 2 if cards small)
|
||||
|
||||
---
|
||||
|
||||
## ProjectCard
|
||||
|
||||
| Variant | Style |
|
||||
|---|---|
|
||||
| Default | Border, padding, flex column |
|
||||
| Hover | Shadow, border accent, lift 2px |
|
||||
| Featured | Accent top border (4px) |
|
||||
|
||||
---
|
||||
|
||||
## CategoryBadge
|
||||
|
||||
| Category | Color |
|
||||
|---|---|
|
||||
| software-engineering | accent color |
|
||||
| logistics | accent color |
|
||||
| ai-ml | accent color |
|
||||
| computer-vision | accent color |
|
||||
| architecture | accent color |
|
||||
| experiment | accent color |
|
||||
|
||||
_Only one accent color — use different icon/symbol per category if needed._
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
| Element | Size | Weight |
|
||||
|---|---|---|
|
||||
| Section heading (H2) | 40px / 32px mobile | 600 |
|
||||
| Card title (H3) | 20px | 600 |
|
||||
| Summary | 14px | 400 |
|
||||
| Tech tag | 12px | 400 |
|
||||
| Metric | 14px | 600 |
|
||||
| CTA | 14px | 500 |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
- H2 section, H3 card titles
|
||||
- Cards: `<article>` semantic
|
||||
- Links: `aria-label` với project name
|
||||
- Category badge: `aria-label` với category
|
||||
- Focus visible trên CTA
|
||||
- Contrast >= 4.5:1
|
||||
|
||||
---
|
||||
|
||||
## Animation
|
||||
|
||||
- Cards fade-in stagger (100ms delay)
|
||||
- Hover: lift + shadow transition 200ms
|
||||
- CTA: color transition 150ms
|
||||
|
||||
---
|
||||
|
||||
## State
|
||||
|
||||
| State | Description |
|
||||
|---|---|
|
||||
| Default | Normal render |
|
||||
| Hover | Lift, shadow, border accent |
|
||||
| Focus | Visible outline |
|
||||
| Scroll reveal | Fade-in + slide-up |
|
||||
| Reduced motion | Disable animations |
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
- Data-driven từ `projects.ts`
|
||||
- Chỉ render featured projects trên homepage
|
||||
- Filterable by category (future phase)
|
||||
- CTA navigate to `/projects/:projectId`
|
||||
@@ -0,0 +1,441 @@
|
||||
# Specification — v2 Features
|
||||
|
||||
> **Document:** `spec-v2.md`
|
||||
> **Version:** 0.1.0
|
||||
> **Status:** Draft — awaiting review
|
||||
> **Branch:** `dev_v2`
|
||||
> **Parent branch:** `dev` (v0.0.1)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Phase 1 (Foundation) + Phase 2 (Core Portfolio) đã hoàn thành trong v0.0.1. v2 tập trung vào:
|
||||
|
||||
1. **Resume download** (P1)
|
||||
2. **Blog system** — MDX-based articles (P1)
|
||||
3. **SEO** — metadata, Open Graph, sitemap (P1)
|
||||
4. **Analytics** — privacy-friendly page view tracking (P2)
|
||||
5. **Testing** — Vitest + Testing Library (P5)
|
||||
6. **CI/CD pipeline** (P5)
|
||||
|
||||
---
|
||||
|
||||
## 1. Resume Download
|
||||
|
||||
### Requirement
|
||||
|
||||
- Nút "Download Resume" trong nav hoặc Contact page
|
||||
- Link đến file PDF (placeholder ban đầu)
|
||||
- Khi chưa có PDF → ẩn nút, hoặc hiển thị "Coming soon"
|
||||
- PDF sẽ upload vào `public/resume.pdf`
|
||||
|
||||
### Implementation
|
||||
|
||||
```tsx
|
||||
// Navigation.tsx
|
||||
{resumeAvailable && (
|
||||
<Link to="/resume" className="nav-link">Resume</Link>
|
||||
)}
|
||||
|
||||
// OR ContactPage.tsx
|
||||
<a href="/resume.pdf" download className="btn-primary">Download Resume</a>
|
||||
```
|
||||
|
||||
### Data
|
||||
|
||||
- `public/resume.pdf` — PDF file (user tự upload)
|
||||
- Không cần data module
|
||||
|
||||
### Acceptance
|
||||
|
||||
- [ ] Nút Resume hiển thị trong nav
|
||||
- [ ] Click → download PDF
|
||||
- [ ] Khi chưa có PDF → nút ẩn hoặc disabled
|
||||
- [ ] Responsive trên mobile
|
||||
|
||||
---
|
||||
|
||||
## 2. Blog System
|
||||
|
||||
### Requirement
|
||||
|
||||
Blog cho phép viết technical articles bằng Markdown/MDX, render trên client.
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
src/
|
||||
content/
|
||||
blog/
|
||||
post-1.mdx
|
||||
post-2.mdx
|
||||
components/
|
||||
blog/
|
||||
BlogListPage.tsx
|
||||
BlogPostPage.tsx
|
||||
ArticleCard.tsx
|
||||
CodeBlock.tsx
|
||||
```
|
||||
|
||||
### Features
|
||||
|
||||
#### 2.1. Frontmatter
|
||||
|
||||
Mỗi article có frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Building High-Performance Event Simulation with Go"
|
||||
date: "2024-06-15"
|
||||
tags: ["engineering", "golang", "simulation"]
|
||||
summary: "Discrete event simulation for logistics facilities"
|
||||
---
|
||||
```
|
||||
|
||||
#### 2.2. Blog List Page (`/blog`)
|
||||
|
||||
- Hiển thị danh sách articles
|
||||
- Sort theo date (newest first)
|
||||
- Filter theo tags (pill buttons)
|
||||
- Mỗi article card: title, date, tags, summary
|
||||
|
||||
#### 2.3. Article Page (`/blog/:slug`)
|
||||
|
||||
- Render MDX content
|
||||
- Code blocks với syntax highlighting
|
||||
- TOC (table of contents) sidebar (desktop)
|
||||
- Reading time estimate
|
||||
- Breadcrumb navigation
|
||||
|
||||
#### 2.4. Code Highlighting
|
||||
|
||||
- Dùng `rehype-prism-plus` hoặc `rehype-raw` + `prismjs`
|
||||
- Không dùng library nặng như `react-syntax-highlighter`
|
||||
- Theme: dark/light compatible với CSS variables
|
||||
|
||||
#### 2.5. MDX Processing
|
||||
|
||||
- Dùng `@mdx-js/react` + `@mdx-js/rollup` (Vite plugin)
|
||||
- Build-time compilation (không runtime)
|
||||
- Frontmatter extracted tại build time
|
||||
|
||||
### Vite Config Changes
|
||||
|
||||
```ts
|
||||
// vite.config.ts
|
||||
import mdx from '@mdx-js/rollup'
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [
|
||||
react(),
|
||||
mdx({
|
||||
providerImportSource: '@mdx-js/react',
|
||||
}),
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
### Acceptance
|
||||
|
||||
- [ ] `/blog` hiển thị danh sách articles
|
||||
- [ ] Article card có title, date, tags, summary
|
||||
- [ ] Click article → navigate đến `/blog/:slug`
|
||||
- [ ] MDX content render đúng
|
||||
- [ ] Code blocks có syntax highlighting
|
||||
- [ ] Tags filter hoạt động
|
||||
- [ ] TOC sidebar (desktop only)
|
||||
- [ ] Reading time hiển thị
|
||||
- [ ] Responsive
|
||||
- [ ] Không crash khi missing article
|
||||
|
||||
---
|
||||
|
||||
## 3. SEO
|
||||
|
||||
### Requirement
|
||||
|
||||
Mỗi page có metadata riêng cho SEO và social sharing.
|
||||
|
||||
### Implementation
|
||||
|
||||
#### 3.1. Dynamic Metadata
|
||||
|
||||
Dùng `react-helmet-async` (hoặc `@remix-run/react` helmet nếu cần SSR sau này).
|
||||
|
||||
```tsx
|
||||
import { Helmet } from 'react-helmet-async'
|
||||
|
||||
// HomePage.tsx
|
||||
<Helmet>
|
||||
<title>{profile.name} — Senior Software Engineer</title>
|
||||
<meta name="description" content={profile.bio} />
|
||||
<link rel="canonical" href={siteUrl} />
|
||||
</Helmet>
|
||||
```
|
||||
|
||||
#### 3.2. Open Graph
|
||||
|
||||
Mỗi page có OG tags:
|
||||
|
||||
```html
|
||||
<meta property="og:title" content="..." />
|
||||
<meta property="og:description" content="..." />
|
||||
<meta property="og:image" content="/og-image.png" />
|
||||
<meta property="og:url" content="..." />
|
||||
<meta property="og:type" content="website" />
|
||||
```
|
||||
|
||||
#### 3.3. Sitemap
|
||||
|
||||
- Generate `sitemap.xml` tại build time
|
||||
- Dùng `vite-plugin-sitemap` hoặc tự viết script
|
||||
- Include tất cả public pages
|
||||
|
||||
#### 3.4. Robots.txt
|
||||
|
||||
- `public/robots.txt`
|
||||
- Allow all (trừ `/admin` nếu có sau này)
|
||||
|
||||
#### 3.5. Structured Data (JSON-LD)
|
||||
|
||||
- `Person` schema cho homepage
|
||||
- `Article` schema cho blog posts
|
||||
- `BreadcrumbList` cho nested pages
|
||||
|
||||
### Acceptance
|
||||
|
||||
- [ ] Mỗi page có `<title>` và `<meta description>` riêng
|
||||
- [ ] OG tags đúng trên mỗi page
|
||||
- [ ] `sitemap.xml` generated tại build
|
||||
- [ ] `robots.txt` có trong `public/`
|
||||
- [ ] JSON-LD structured data
|
||||
- [ ] Canonical URL đúng
|
||||
|
||||
---
|
||||
|
||||
## 4. Analytics
|
||||
|
||||
### Requirement
|
||||
|
||||
Privacy-friendly analytics — không dùng Google Analytics.
|
||||
|
||||
### Options
|
||||
|
||||
**Option A: Plausible Analytics** (recommended)
|
||||
- Lightweight, privacy-first
|
||||
- No cookie banner needed
|
||||
- Simple script integration
|
||||
|
||||
**Option B: Umami**
|
||||
- Self-hosted option
|
||||
- Open source
|
||||
- Similar to Plausible
|
||||
|
||||
**Option C: Custom minimal tracking**
|
||||
- Track page views only
|
||||
- Store in localStorage
|
||||
- Batch send to endpoint (optional)
|
||||
|
||||
### Implementation (Plausible)
|
||||
|
||||
```tsx
|
||||
// main.tsx
|
||||
<script
|
||||
defer
|
||||
data-domain="yourdomain.com"
|
||||
src="https://plausible.io/js/script.outbound-links.js"
|
||||
/>
|
||||
```
|
||||
|
||||
Hoặc dùng `react-use-plausible`:
|
||||
|
||||
```tsx
|
||||
import { usePlausible } from 'react-use-plausible'
|
||||
|
||||
const plausible = usePlausible()
|
||||
// Auto pageview tracking
|
||||
```
|
||||
|
||||
### Acceptance
|
||||
|
||||
- [ ] Page view tracking hoạt động
|
||||
- [ ] Không cookie banner
|
||||
- [ ] Không ảnh hưởng performance
|
||||
- [ ] Configurable via env var (ENABLE_ANALYTICS)
|
||||
|
||||
---
|
||||
|
||||
## 5. Testing
|
||||
|
||||
### Requirement
|
||||
|
||||
Unit tests cho components và hooks. E2E tests cho critical paths.
|
||||
|
||||
### Stack
|
||||
|
||||
- **Vitest** — unit/integration tests
|
||||
- **@testing-library/react** — component tests
|
||||
- **@testing-library/jest-dom** — assertions
|
||||
- **Playwright** — E2E tests
|
||||
|
||||
### Test Structure
|
||||
|
||||
```
|
||||
src/
|
||||
__tests__/
|
||||
hooks/
|
||||
useTheme.test.tsx
|
||||
components/
|
||||
Navigation.test.tsx
|
||||
Footer.test.tsx
|
||||
Badge.test.tsx
|
||||
pages/
|
||||
HomePage.test.tsx
|
||||
e2e/
|
||||
navigation.spec.ts
|
||||
theme.spec.ts
|
||||
responsive.spec.ts
|
||||
```
|
||||
|
||||
### Critical Tests
|
||||
|
||||
#### useTheme
|
||||
|
||||
```tsx
|
||||
test('cycles through themes correctly', () => {
|
||||
const { result } = renderHook(() => useTheme())
|
||||
act(() => { result.current.cycleTheme() })
|
||||
expect(result.current.theme).toBe('light') // or 'dark'
|
||||
})
|
||||
|
||||
test('persists theme to localStorage', () => {
|
||||
renderHook(() => useTheme())
|
||||
expect(localStorage.getItem('portfolio-theme')).toBe('dark')
|
||||
})
|
||||
```
|
||||
|
||||
#### Navigation
|
||||
|
||||
```tsx
|
||||
test('renders all nav items', () => {
|
||||
render(<Navigation />)
|
||||
navItems.forEach(item => {
|
||||
expect(screen.getByText(item.label)).toBeInTheDocument()
|
||||
})
|
||||
})
|
||||
|
||||
test('NavLink highlights active route', () => {
|
||||
render(<MemoryRouter initialEntries={['/about']}> <Navigation /> </MemoryRouter>)
|
||||
expect(screen.getByText('About')).toHaveClass('active')
|
||||
})
|
||||
```
|
||||
|
||||
#### HomePage
|
||||
|
||||
```tsx
|
||||
test('renders hero section', () => {
|
||||
render(<HomePage />)
|
||||
expect(screen.getByRole('heading', { name: profile.name })).toBeInTheDocument()
|
||||
})
|
||||
```
|
||||
|
||||
### Acceptance
|
||||
|
||||
- [ ] useTheme tests pass
|
||||
- [ ] Navigation tests pass
|
||||
- [ ] HomePage tests pass
|
||||
- [ ] E2E: navigation works
|
||||
- [ ] E2E: theme toggle works
|
||||
- [ ] E2E: responsive layout correct
|
||||
- [ ] Test coverage > 70%
|
||||
|
||||
---
|
||||
|
||||
## 6. CI/CD Pipeline
|
||||
|
||||
### Requirement
|
||||
|
||||
GitHub Actions pipeline:
|
||||
|
||||
1. **Lint** — oxlint
|
||||
2. **Type check** — tsc -b
|
||||
3. **Test** — vitest
|
||||
4. **Build** — vite build
|
||||
5. **Deploy** — to Vercel (on main branch push)
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
# .github/workflows/ci.yml
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [dev, main]
|
||||
pull_request:
|
||||
branches: [dev]
|
||||
|
||||
jobs:
|
||||
ci:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: pnpm/action-setup@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 20
|
||||
cache: pnpm
|
||||
- run: pnpm install --frozen-lockfile
|
||||
- run: pnpm lint
|
||||
- run: pnpm build
|
||||
- run: pnpm test
|
||||
```
|
||||
|
||||
### Vercel Integration
|
||||
|
||||
- Connect GitHub repo
|
||||
- Auto deploy on `dev` → preview
|
||||
- Auto deploy on `main` → production
|
||||
- Environment variables: `SITE_URL`, `PLAUSIBLE_DOMAIN` (optional)
|
||||
|
||||
### Acceptance
|
||||
|
||||
- [ ] CI pass trên push vào dev
|
||||
- [ ] Lint pass
|
||||
- [ ] Build pass
|
||||
- [ ] Tests pass
|
||||
- [ ] Preview deploy trên Vercel
|
||||
- [ ] Production deploy khi merge vào main
|
||||
|
||||
---
|
||||
|
||||
## Implementation Order
|
||||
|
||||
Ưu tiên thực hiện:
|
||||
|
||||
1. **Resume download** (5 phút, trivial)
|
||||
2. **SEO** (metadata, OG, sitemap) — cần làm trước khi deploy
|
||||
3. **Blog system** (MDX + articles) — P1, substantial work
|
||||
4. **Analytics** (Plausible) — quick win
|
||||
5. **Testing** (Vitest + E2E) — P5, important but can iterate
|
||||
6. **CI/CD** (GitHub Actions) — P5, automate after features done
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope (v2)
|
||||
|
||||
- CMS integration (Phase 5+)
|
||||
- Multi-language / i18n (Phase 5+)
|
||||
- Interactive diagrams / simulations (Phase 5+)
|
||||
- Search functionality (Phase 5+)
|
||||
- Contact form with backend (Phase 5+)
|
||||
- Resume PDF generation (user uploads manually)
|
||||
|
||||
---
|
||||
|
||||
## Approval
|
||||
|
||||
- [ ] All requirements reviewed and confirmed
|
||||
- [ ] Implementation order agreed
|
||||
- [ ] Ready to start coding
|
||||
+2225
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,174 @@
|
||||
# Specification — v1 (Foundation + Core Portfolio)
|
||||
|
||||
> **Document:** `spec_v1.md`
|
||||
> **Version:** 1.0.0
|
||||
> **Status:** Completed
|
||||
> **Branch:** `dev` (merged from `dev_v1`)
|
||||
> **Tag:** `v0.0.1`
|
||||
> **Commit:** `7e42bd8` (feat) + `59951a7` (docs)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
v1 implements **Phase 1 (Foundation)** and **Phase 2 (Core Portfolio)** from `spec.md`. All pages, components, theming, and responsive layout are complete.
|
||||
|
||||
---
|
||||
|
||||
## Completed Features
|
||||
|
||||
### 1. Foundation
|
||||
|
||||
| Feature | Status | Details |
|
||||
|---------|--------|---------|
|
||||
| Vite 8 + React 19 + TypeScript 6 | Done | Bundler mode, strict linting |
|
||||
| Oxlint 1 | Done | `react/rules-of-hooks` error, `react/only-export-components` warn |
|
||||
| React Router v6 | Done | Pin `6.30.6`, 7 routes defined |
|
||||
| CSS Variables + Theming | Done | `data-theme` attribute, dark/light/system |
|
||||
| Responsive Design | Done | Mobile menu, fluid containers, touch-friendly |
|
||||
|
||||
### 2. Routing & Pages
|
||||
|
||||
| Route | Page | Component | Status |
|
||||
|-------|------|-----------|--------|
|
||||
| `/` | Home | `HomePage` | Done |
|
||||
| `/about` | About | `AboutPage` | Done |
|
||||
| `/experience` | Experience | `ExperiencePage` | Done |
|
||||
| `/projects` | Projects List | `ProjectsListPage` | Done |
|
||||
| `/projects/:id` | Project Detail | `ProjectDetailPage` | Done |
|
||||
| `/engineering` | Engineering | `EngineeringPage` | Done (placeholder content) |
|
||||
| `/contact` | Contact | `ContactPage` | Done |
|
||||
|
||||
### 3. Layout Components
|
||||
|
||||
| Component | File | Status |
|
||||
|-----------|------|--------|
|
||||
| `Layout` | `src/components/layout/Layout.tsx` | Done — wraps Navigation + main + Footer |
|
||||
| `Navigation` | `src/components/layout/Navigation.tsx` | Done — desktop menu, mobile drawer, theme toggle |
|
||||
| `Footer` | `src/components/layout/Footer.tsx` | Done — copyright, nav links, social links |
|
||||
|
||||
### 4. Page Sections (HomePage)
|
||||
|
||||
| Section | Component | Status |
|
||||
|---------|-----------|--------|
|
||||
| Hero | `src/components/sections/Hero.tsx` | Done — name, title, tagline, CTA, social links |
|
||||
| About | `src/components/sections/About.tsx` | Done — bio, engineering philosophy, current interests |
|
||||
| Expertise | `src/components/sections/Expertise.tsx` | Done — skill groups grid |
|
||||
| Experience | `src/components/sections/Experience.tsx` | Done — timeline with responsibilities |
|
||||
| Projects | `src/components/sections/Projects.tsx` | Done — featured projects grid |
|
||||
| Contact | `src/components/sections/Contact.tsx` | Done — email, GitHub, LinkedIn links |
|
||||
|
||||
### 5. UI Components
|
||||
|
||||
| Component | File | Props/Features | Status |
|
||||
|-----------|------|----------------|--------|
|
||||
| `Button` | `src/components/ui/Button.tsx` | `variant`, `size`, `disabled` | Done |
|
||||
| `Badge` | `src/components/ui/Badge.tsx` | `variant: accent | outline | muted` | Done |
|
||||
| `Tag` | `src/components/ui/Tag.tsx` | `accent` | Done |
|
||||
| `Card` | `src/components/ui/Card.tsx` | `as`, children | Done |
|
||||
| `SectionHeading` | `src/components/ui/SectionHeading.tsx` | `title`, `subtitle` | Done |
|
||||
| `SocialLinks` | `src/components/ui/SocialLinks.tsx` | `links`, `variant` | Done |
|
||||
|
||||
### 6. Theming
|
||||
|
||||
| Feature | Status | Details |
|
||||
|---------|--------|---------|
|
||||
| `ThemeProvider` | Done | Context provider, `data-theme` on `<html>` |
|
||||
| `useTheme()` hook | Done | Returns `{ theme, resolvedTheme, setTheme, cycleTheme }` |
|
||||
| Theme cycle | Done | `dark` ↔ `light` ↔ `system` (system skips to opposite) |
|
||||
| localStorage persistence | Done | Key: `portfolio-theme` |
|
||||
| System preference detection | Done | `prefers-color-scheme: dark` |
|
||||
| CSS variables for both themes | Done | `src/index.css` root + `[data-theme="dark"]` |
|
||||
|
||||
### 7. Data Layer
|
||||
|
||||
| Module | File | Content | Status |
|
||||
|--------|------|---------|--------|
|
||||
| Profile | `src/data/profile.ts` | Name, title, tagline, bio, links, interests, philosophy | Done |
|
||||
| Skills | `src/data/skills.ts` | 6 skill groups × 5-6 skills each | Done |
|
||||
| Experience | `src/data/experience.ts` | 1 entry with 3 featured achievements | Done |
|
||||
| Projects | `src/data/projects.ts` | 4 projects with sections, metrics, tech stacks | Done |
|
||||
|
||||
### 8. Types
|
||||
|
||||
| Interface | File | Fields | Status |
|
||||
|-----------|------|--------|--------|
|
||||
| `Profile` | `src/types/index.ts` | name, title, tagline, bio, email, links, interests, philosophy | Done |
|
||||
| `SkillGroup` | `src/types/index.ts` | title, skills[] | Done |
|
||||
| `ExperienceEntry` | `src/types/index.ts` | id, title, company, duration, location, responsibilities, achievements | Done |
|
||||
| `FeaturedAchievement` | `src/types/index.ts` | id, title, context, technicalWork, impact, metrics, technologies, featured | Done |
|
||||
| `Project` | `src/types/index.ts` | id, title, summary, category, role, technologies, metrics, featured, urls | Done |
|
||||
| `ProjectDetail` | `src/types/index.ts` | extends Project + sections[] | Done |
|
||||
| `ProjectSection` | `src/types/index.ts` | id, number, title, content, type | Done |
|
||||
| `PhilosophyPoint` | `src/types/index.ts` | title, description, keywords[] | Done |
|
||||
| `ProjectCategory` | `src/types/index.ts` | 6 union types | Done |
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
App.tsx
|
||||
└── ThemeProvider
|
||||
└── BrowserRouter
|
||||
└── Layout
|
||||
├── Navigation (top bar + mobile drawer)
|
||||
├── <Routes>
|
||||
│ ├── HomePage (Hero + About + Expertise + Experience + Projects + Contact)
|
||||
│ ├── AboutPage
|
||||
│ ├── ExperiencePage
|
||||
│ ├── ProjectsListPage
|
||||
│ ├── ProjectDetailPage
|
||||
│ ├── EngineeringPage
|
||||
│ └── ContactPage
|
||||
└── Footer
|
||||
```
|
||||
|
||||
**Data flow:** All content comes from `src/data/*.ts` modules. Components are presentational — no hardcoded text except labels/CTAs.
|
||||
|
||||
**CSS:** Global variables in `src/index.css`, component styles in `src/App.css`. No CSS library.
|
||||
|
||||
---
|
||||
|
||||
## Known Limitations
|
||||
|
||||
| # | Limitation | Impact | v2 Plan |
|
||||
|---|------------|--------|---------|
|
||||
| 1 | No Blog system | Cannot publish articles | Phase 4: MDX-based blog |
|
||||
| 2 | No SEO metadata | No `<title>`, `<meta>`, OG tags per page | Phase 5: react-helmet-async |
|
||||
| 3 | No Analytics | No page view tracking | Phase 5: Plausible |
|
||||
| 4 | No Testing | No unit/E2E tests | Phase 5: Vitest + Playwright |
|
||||
| 5 | No CI/CD | Manual builds only | Phase 5: GitHub Actions |
|
||||
| 6 | No Resume download | No PDF resume | v2: Add link/button |
|
||||
| 7 | Engineering page placeholder | "Coming soon" text | v2: Populate with real content |
|
||||
| 8 | Projects use `<a href>` not `<Link>` | Client-side nav broken on projects page | v2: Fix to `<Link>` |
|
||||
| 9 | No i18n | Vietnamese-only | Future: English support |
|
||||
| 10 | No CMS | Content in TS files | Future: headless CMS or MDX |
|
||||
|
||||
---
|
||||
|
||||
## Files Summary
|
||||
|
||||
| Category | Count | Path |
|
||||
|----------|-------|------|
|
||||
| Pages | 7 | `src/pages/*.tsx` |
|
||||
| Layout components | 3 | `src/components/layout/*.tsx` |
|
||||
| Section components | 6 | `src/components/sections/*.tsx` |
|
||||
| UI components | 6 | `src/components/ui/*.tsx` |
|
||||
| Data modules | 4 | `src/data/*.ts` |
|
||||
| Hooks | 1 | `src/hooks/useTheme.tsx` |
|
||||
| Types | 1 | `src/types/index.ts` |
|
||||
| CSS | 2 | `src/index.css`, `src/App.css` |
|
||||
| **Total source files** | **30** | |
|
||||
|
||||
---
|
||||
|
||||
## Approval
|
||||
|
||||
- [x] All Phase 1 + Phase 2 requirements implemented
|
||||
- [x] TypeScript compiles without errors
|
||||
- [x] Oxlint passes
|
||||
- [x] Build succeeds
|
||||
- [x] Responsive on mobile/desktop
|
||||
- [x] Tagged `v0.0.1` on branch `dev`
|
||||
- [x] AGENTS.md updated with project context
|
||||
Reference in new issue
Block a user