1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
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
|
