From 0273f555deae306c804ba2963055f91ede6bb14f Mon Sep 17 00:00:00 2001 From: "dong.nguyen" Date: Tue, 6 Oct 2026 09:58:00 +0700 Subject: [PATCH] ui spec --- AGENTS.md | 54 + spec-ui-about.md | 127 +++ spec-ui-blog.md | 152 +++ spec-ui-components.md | 289 +++++ spec-ui-contact.md | 140 +++ spec-ui-engineering.md | 105 ++ spec-ui-experience.md | 150 +++ spec-ui-expertise.md | 110 ++ spec-ui-footer.md | 88 ++ spec-ui-hero.md | 144 +++ spec-ui-layout.md | 136 +++ spec-ui-navigation.md | 108 ++ spec-ui-project-detail.md | 157 +++ spec-ui-projects-list.md | 91 ++ spec-ui-projects.md | 156 +++ spec.md | 2225 +++++++++++++++++++++++++++++++++++++ 16 files changed, 4232 insertions(+) create mode 100644 spec-ui-about.md create mode 100644 spec-ui-blog.md create mode 100644 spec-ui-components.md create mode 100644 spec-ui-contact.md create mode 100644 spec-ui-engineering.md create mode 100644 spec-ui-experience.md create mode 100644 spec-ui-expertise.md create mode 100644 spec-ui-footer.md create mode 100644 spec-ui-hero.md create mode 100644 spec-ui-layout.md create mode 100644 spec-ui-navigation.md create mode 100644 spec-ui-project-detail.md create mode 100644 spec-ui-projects-list.md create mode 100644 spec-ui-projects.md create mode 100644 spec.md diff --git a/AGENTS.md b/AGENTS.md index e69de29..2cf5583 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -0,0 +1,54 @@ +# Agent Guidelines — portfolio + +## Project + +A bare **React + TypeScript + Vite** application (default `create-vite` scaffold). No custom components, utilities, or business logic yet. + +## Tech Stack + +| Layer | Tool | +|-------|------| +| Framework | React 19 | +| Language | TypeScript 6 (bundler mode, `verbatimModuleSyntax`, `noEmit`) | +| Bundler | Vite 8 | +| Linter | Oxlint 1 (`plugins: react, typescript, oxc`) | +| Package manager | pnpm | + +## Commands + +| Command | Description | +|---------|-------------| +| `pnpm dev` | Start dev server with HMR | +| `pnpm build` | Type-check (`tsc -b`) then build for production | +| `pnpm lint` | Run Oxlint | +| `pnpm preview` | Preview production build locally | + +## Project Structure + +``` +src/ + main.tsx — Entry point; renders inside StrictMode + App.tsx — Root component (currently Vite welcome page) + App.css — Component styles + index.css — Global styles, CSS variables, dark mode + assets/ — Images (hero.png, react.svg, vite.svg) +public/ + favicon.svg — Site favicon + icons.svg — SVG sprite sheet (icons used in App.tsx) +index.html — HTML shell +vite.config.ts — Vite config (react plugin only) +tsconfig.app.json — TS compiler options (bundler mode, strict linting) +.oxlintrc.json — Oxlint rules (react hooks error, exports warn) +``` + +## Code Style & Linting + +- TypeScript: `verbatimModuleSyntax`, `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch` +- Oxlint: `react/rules-of-hooks` = error, `react/only-export-components` = warn (allows constant exports) +- No framework-specific CSS library — plain CSS with CSS variables + +## File Conventions + +- Components: `.tsx`, single default export per file +- Styles: `.css` alongside components (co-located), global styles in `src/index.css` +- Assets: imported in `src/assets/`, static files in `public/` diff --git a/spec-ui-about.md b/spec-ui-about.md new file mode 100644 index 0000000..6856f19 --- /dev/null +++ b/spec-ui-about.md @@ -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: `
` 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 diff --git a/spec-ui-blog.md b/spec-ui-blog.md new file mode 100644 index 0000000..31a6c90 --- /dev/null +++ b/spec-ui-blog.md @@ -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 `
` for each post +- Code blocks: `
` 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)
diff --git a/spec-ui-components.md b/spec-ui-components.md
new file mode 100644
index 0000000..e5bace1
--- /dev/null
+++ b/spec-ui-components.md
@@ -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 |
diff --git a/spec-ui-contact.md b/spec-ui-contact.md
new file mode 100644
index 0000000..5605a7c
--- /dev/null
+++ b/spec-ui-contact.md
@@ -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: `