Merge pull request #16 from bertyuan/docs

Add technical research and UI design documents

1 files changed, 195 insertions, 0 deletions

diff --git a/docs/ui-design-documents.md b/docs/ui-design-documents.md
new file mode 100644
index 0000000..1b0cc73
--- /dev/null
+++ b/docs/ui-design-documents.md
@@ -0,0 +1,195 @@
+# UI Design Documents
+
+> Last Updated: 2026-04-06  
+> Scope: Current implementation in this repository (Next.js frontend + Payload content system)
+
+## 1. Document Purpose
+
+This document captures the UI design of the current implementation and serves as a baseline for future iterations. It covers:
+
+- Information architecture and page structure
+- Visual language and component conventions
+- Interaction behavior, responsiveness, and accessibility baseline
+- Actionable UI improvements for the current codebase
+
+## 2. Product Positioning and Design Principles
+
+The site is currently positioned as a content-first technical blog. The UI follows these principles:
+
+1. Reading first: prioritize hierarchy, contrast, and low visual noise.
+2. Lightweight navigation: keep access to posts, tags, and login straightforward.
+3. Consistent style: use dashed borders, corner crosses, and subtle motion as a recognizable theme.
+4. Low learning cost: both anonymous and authenticated flows should be intuitive.
+5. Cross-device consistency: preserve the same visual language across desktop and mobile.
+
+## 3. User Roles and Core Journeys
+
+| Role | Primary Goal | Core Routes |
+| --- | --- | --- |
+| Visitor | Browse and read content quickly | `/`, `/posts`, `/posts/[slug]`, `/tags` |
+| Returning reader | Filter by topic and engage | `/tags/[tag]`, `/posts/[slug]` (comments) |
+| Authenticated user | Comment, share, subscribe | `/login` -> `/posts/[slug]` |
+| Content admin | Publish and maintain content | `/admin` (Payload admin) |
+
+## 4. Information Architecture
+
+### 4.1 Route and Page Responsibilities
+
+| Route | Responsibility | Main File |
+| --- | --- | --- |
+| `/` | Hero + latest posts + newsletter CTA | `src/app/(main)/(home)/page.tsx` |
+| `/posts` | Paginated post list | `src/app/(main)/(home)/posts/page.tsx` |
+| `/posts/[slug]` | Post detail + share + comments | `src/app/(main)/(home)/posts/[slug]/page.tsx` |
+| `/tags` | Tag index | `src/app/(main)/(home)/tags/page.tsx` |
+| `/tags/[tag]` | Tag-filtered posts + pagination | `src/app/(main)/(home)/tags/[...slug]/page.tsx` |
+| `/about` | MDX content page (profile) | `src/app/(main)/(home)/(mdx)/about/page.mdx` |
+| `/login` | OAuth login page | `src/app/(main)/(auth)/login/page.tsx` |
+| `404` | Not found page | `src/app/(main)/not-found.tsx` |
+
+### 4.2 Global Layout Structure
+
+- The main shell is based on `HomeLayout`, with custom `Header` and `Footer`.
+- Content sections consistently use the `Section` wrapper for border/corner styling.
+- Vertical rhythm is maintained using dashed separators between major blocks.
+
+Related files:
+
+- `src/app/(main)/(home)/layout.tsx`
+- `src/components/sections/header/index.tsx`
+- `src/components/sections/footer.tsx`
+- `src/components/section.tsx`
+
+## 5. Visual Design Guidelines
+
+### 5.1 Typography and Layout
+
+- Primary font: `Geist`; monospace font: `Geist Mono`.
+- Home and detail pages use strong heading hierarchy (`text-3xl` to `text-6xl`).
+- Secondary information uses muted color tokens to improve reading focus.
+
+### 5.2 Color and Theme
+
+- Color tokens are mapped to `fumadocs` variables (`src/styles/globals.css`).
+- Supports `light`, `dark`, and `system` theme modes.
+- Cards use translucent backgrounds (`bg-card/50`) with hover transitions.
+
+### 5.3 Shape and Decoration
+
+- Signature visual elements: dashed borders + corner cross markers.
+- Hero and separators use textured pattern backgrounds (`bg-dashed`).
+- Footer uses a grid + gradient overlay to create depth.
+
+### 5.4 Icon System
+
+- Base icons come from `lucide-react`; brand icons are wrapped in `Icons`.
+- Icons are used for navigation, status communication, and interaction feedback.
+
+## 6. Page-Level Design Notes
+
+### 6.1 Home `/`
+
+Structure:
+
+1. Hero (personal positioning + CTA + social links)
+2. Posts section heading
+3. Latest 3 posts
+4. Newsletter subscription block
+
+Notes:
+
+- Hero uses background imagery and fade-in motion for first-screen identity.
+- The messaging is personal-brand oriented rather than marketing oriented.
+
+### 6.2 Posts List `/posts`
+
+- Shows total count and current range (for example `1-5`).
+- Uses horizontal information cards for fast scanning.
+- Pagination supports numbered jumps and ellipsis.
+
+### 6.3 Post Detail `/posts/[slug]`
+
+- Top area includes title, description, and tags.
+- Main area renders rich text content.
+- Desktop includes a sticky side panel for author/date/share.
+- Bottom includes comments (posting requires login).
+
+### 6.4 Tags `/tags` and `/tags/[tag]`
+
+- `/tags`: tag grid with counts.
+- `/tags/[tag]`: reuses the posts-list visual pattern for consistency.
+
+### 6.5 Login `/login`
+
+- Centered card layout aligned with global style (dashed borders + corner markers).
+- Currently supports Google/GitHub OAuth only.
+
+## 7. Core Component Interaction Guidelines
+
+| Component | Current Behavior | Design Intent |
+| --- | --- | --- |
+| `Header` | Sticky nav, search, theme toggle, mobile menu | Keep global actions always reachable |
+| `PostCard` | Fully clickable card with title/summary/meta/image | Improve list browsing efficiency |
+| `TagCard` | Tag chip with optional count | Encourage topic discovery |
+| `NewsletterForm` | Validation + success/error feedback | Reduce subscription friction |
+| `ThemeToggle` | Theme switch with transition effect | Keep switching smooth and perceptible |
+| `UserButton` | Session-aware menu (sign in/sign out) | Minimize account operation complexity |
+
+## 8. Motion and Feedback
+
+Implemented interaction feedback:
+
+- Hero background fade-in (`motion`)
+- Hover transforms on icons and buttons
+- Theme transition via `startViewTransition`
+- Share action success toast after copy
+
+Guideline:
+
+- Keep motion short, lightweight, and functional; avoid distracting animation.
+
+## 9. Responsive and Accessibility Baseline
+
+### 9.1 Responsive Behavior
+
+- Uses Tailwind breakpoint system (`sm` to `2xl`).
+- Header collapses into a menu on smaller screens.
+- Post detail layout falls back from dual-column to single-column on small screens.
+
+### 9.2 Accessibility
+
+Current baseline:
+
+- Core semantic structure is in place (`main`, `section`, `article`).
+- Key icon buttons include accessible labels.
+
+Recommended improvements:
+
+1. Improve visible keyboard focus states for custom controls.
+2. Audit all icon-only links to ensure explicit accessible naming.
+
+## 10. Current Issues and Priority Improvements
+
+### P0 (high priority)
+
+1. Mixed language tone across content should be standardized.
+2. Missing explicit empty states for posts/tags views.
+3. Newsletter flow can further improve repeated-submit protection messaging.
+
+### P1 (medium priority)
+
+1. Add reusable skeletons for list views (future-proof for client data loading).
+2. Extract a shared page-header component to reduce repeated patterns.
+3. Add design token documentation (spacing, radius, border rules).
+
+### P2 (low priority)
+
+1. Add visual regression screenshot baseline for key pages.
+2. Add a component snapshot guide under `docs/`.
+
+## 11. Next Iteration Design Checklist
+
+- [ ] Extract a shared page-header component
+- [ ] Add reusable empty-state modules
+- [ ] Run an accessibility-focused pass
+- [ ] Define and enforce copy language policy
+- [ ] Build component visual reference documentation