Skip to content

Commit f9ead75

Browse files
Copilotankurrera
Copilot
and
ankurrera
committed
Add Skills System UI flow and interaction documentation
Co-authored-by: ankurrera <186232326+ankurrera@users.noreply.github.com>
1 parent 992f35a commit f9ead75

1 file changed

Lines changed: 348 additions & 0 deletions

File tree

‎SKILLS_SYSTEM_UI_FLOW.md‎

Lines changed: 348 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,348 @@
1+
# Skills System UI Flow and Structure
2+
3+
## Page Layout
4+
5+
```
6+
┌─────────────────────────────────────────────────────────────────────┐
7+
│ HEADER (Sticky) │
8+
│ [← Back] Skills [☰ Menu] │
9+
└─────────────────────────────────────────────────────────────────────┘
10+
11+
┌─────────────────────────────────────────────────────────────────────┐
12+
│ QUICK CREATE PANEL │
13+
│ [+ New Area - Skill] [+ New Characteristic] │
14+
└─────────────────────────────────────────────────────────────────────┘
15+
16+
┌──────────────────────┬──────────────────────────────────────────────┐
17+
│ CHARACTERISTICS │ SKILLS - AREAS │
18+
│ (Left - 30%) │ (Right - 70%) │
19+
│ │ │
20+
│ Characteristics │ Skills – Areas [All][Active][Inactive] │
21+
│ [+ New] │ [🔍 Search...] [+ New] │
22+
│ │ │
23+
│ ┌────────────────┐ │ ┌─────────────┐ ┌─────────────┐ │
24+
│ │ 💪 Strength │ │ │ [Cover Img] │ │ [Cover Img] │ │
25+
│ │ Level 3 ⭐ │ │ │ Web Dev │ │ Guitar │ │
26+
│ │ 440/500 XP │ │ │ Programming │ │ Music │ │
27+
│ │ ████████░░ 88% │ │ │ Level 5 ⭐ │ │ Level 2 ⭐ │ │
28+
│ │ [✏️] [🗑️] │ │ │ 440/550 XP │ │ 285/500 XP │ │
29+
│ └────────────────┘ │ │ ██████████ │ │ ██████░░░░ │ │
30+
│ │ │ [✏️] [🗑️] │ │ [✏️] [🗑️] │ │
31+
│ ┌────────────────┐ │ │ [⚡Active] │ │ [⚪Inactive] │ │
32+
│ │ 🧠 Intelligence│ │ └─────────────┘ └─────────────┘ │
33+
│ │ Level 2 ⭐ │ │ │
34+
│ │ 285/400 XP │ │ ┌─────────────┐ ┌─────────────┐ │
35+
│ │ ███████░░░ 71% │ │ │ [Cover Img] │ │ [Cover Img] │ │
36+
│ │ [✏️] [🗑️] │ │ │ Fitness │ │ Writing │ │
37+
│ └────────────────┘ │ │ Health │ │ Content │ │
38+
│ │ │ Level 8 ⭐ │ │ Level 3 ⭐ │ │
39+
│ [+ New │ │ 2100/2500XP │ │ 450/900 XP │ │
40+
│ Characteristic] │ │ ██████████ │ │ ████░░░░░░ │ │
41+
│ │ │ [✏️] [🗑️] │ │ [✏️] [🗑️] │ │
42+
│ │ │ [⚡Active] │ │ [⚡Active] │ │
43+
│ │ └─────────────┘ └─────────────┘ │
44+
└──────────────────────┴──────────────────────────────────────────────┘
45+
```
46+
47+
## Component Hierarchy
48+
49+
```
50+
Skills Page
51+
│
52+
├── Header
53+
│ ├── Back Button (→ /)
54+
│ ├── Title: "Skills"
55+
│ └── Menu Button
56+
│
57+
├── Quick Create Panel
58+
│ ├── New Area-Skill Button
59+
│ └── New Characteristic Button
60+
│
61+
└── Main Content (Two Columns)
62+
│
63+
├── Left Column (30%) - Characteristics Panel
64+
│ ├── Header ("Characteristics" + New Button)
65+
│ ├── Characteristic Cards (List)
66+
│ │ ├── Icon + Name
67+
│ │ ├── Level + Star
68+
│ │ ├── XP Display (current/next)
69+
│ │ ├── Progress Bar
70+
│ │ └── Actions (Edit, Delete)
71+
│ └── Create Characteristic Form (inline)
72+
│
73+
└── Right Column (70%) - Skills Grid
74+
├── Header
75+
│ ├── Title: "Skills – Areas"
76+
│ ├── Filter Buttons (All/Active/Inactive)
77+
│ ├── Search Input
78+
│ └── New Skill Button
79+
│
80+
├── Skill Cards (Grid)
81+
│ ├── Cover Image
82+
│ ├── Name + Description
83+
│ ├── Area Tag
84+
│ ├── Level + Star
85+
│ ├── XP Display
86+
│ ├── Segmented Progress Bar (10 blocks)
87+
│ ├── Actions (Edit, Delete)
88+
│ └── Active/Inactive Toggle
89+
│
90+
└── Create Skill Form (inline)
91+
```
92+
93+
## User Interactions
94+
95+
### Creating a Characteristic
96+
```
97+
1. User clicks [+ New] or [+ New Characteristic]
98+
↓
99+
2. Inline form appears with:
100+
- Icon selector (emoji grid)
101+
- Name input
102+
- Initial XP input
103+
↓
104+
3. User fills form and clicks [Create]
105+
↓
106+
4. Mutation sent to Supabase
107+
↓
108+
5. Database trigger calculates level
109+
↓
110+
6. React Query cache updates
111+
↓
112+
7. New card appears in list
113+
↓
114+
8. Toast notification: "Characteristic created successfully!"
115+
```
116+
117+
### Editing XP (Inline)
118+
```
119+
1. User clicks [Edit] icon on characteristic
120+
↓
121+
2. Card enters edit mode:
122+
- Icon becomes input
123+
- Name becomes input
124+
- XP input appears
125+
↓
126+
3. User changes XP value
127+
↓
128+
4. User clicks [Save]
129+
↓
130+
5. Mutation updates database
131+
↓
132+
6. Trigger recalculates level
133+
↓
134+
7. Card updates with new level and progress
135+
↓
136+
8. Toast: "Characteristic updated successfully!"
137+
```
138+
139+
### Filtering Skills
140+
```
141+
1. User types in search box: "web"
142+
↓
143+
2. Grid filters in real-time
144+
↓
145+
3. Only "Web Development" shows
146+
147+
OR
148+
149+
1. User clicks [Active] filter
150+
↓
151+
2. Grid filters to show only is_active = true
152+
↓
153+
3. Inactive skills hidden
154+
```
155+
156+
### Creating a Skill
157+
```
158+
1. User clicks [+ New Skill] or [+ New Area-Skill]
159+
↓
160+
2. Inline form expands with fields:
161+
- Name (required)
162+
- Description
163+
- Area
164+
- Cover Image URL
165+
- Initial XP
166+
↓
167+
3. User fills and submits
168+
↓
169+
4. New skill card appears in grid
170+
↓
171+
5. Toast: "Skill created successfully!"
172+
```
173+
174+
### Deleting with Confirmation
175+
```
176+
1. User clicks [Delete] icon
177+
↓
178+
2. Custom confirmation dialog opens:
179+
"Delete Skill"
180+
"Are you sure you want to delete 'Web Development'?
181+
This action cannot be undone."
182+
[Cancel] [Delete]
183+
↓
184+
3. User clicks [Delete]
185+
↓
186+
4. Mutation deletes from database
187+
↓
188+
5. Card disappears with animation
189+
↓
190+
6. Toast: "Skill deleted successfully"
191+
```
192+
193+
## Data Flow
194+
195+
### Read (on page load)
196+
```
197+
Skills Page Mounts
198+
↓
199+
useSkills() hook
200+
↓
201+
React Query: ['skills', user.id]
202+
↓
203+
Supabase Query: SELECT * FROM skills WHERE user_id = ?
204+
↓
205+
Apply RLS Policy
206+
↓
207+
Return data
208+
↓
209+
Update component state
210+
↓
211+
Render skill cards
212+
```
213+
214+
### Create
215+
```
216+
User submits form
217+
↓
218+
createSkill.mutate()
219+
↓
220+
Supabase: INSERT INTO skills
221+
↓
222+
Database trigger calculates level
223+
↓
224+
Return new skill with level
225+
↓
226+
React Query invalidates cache
227+
↓
228+
Re-fetch skills
229+
↓
230+
UI updates
231+
↓
232+
Toast notification
233+
```
234+
235+
### Update
236+
```
237+
User edits XP
238+
↓
239+
updateSkill.mutate({ id, xp })
240+
↓
241+
Supabase: UPDATE skills SET xp = ? WHERE id = ?
242+
↓
243+
Trigger recalculates level
244+
↓
245+
Return updated skill
246+
↓
247+
Cache invalidation
248+
↓
249+
UI re-renders with new level/progress
250+
```
251+
252+
## Progress Bar Visualization
253+
254+
### Characteristic Progress Bar (Standard)
255+
```
256+
Current XP: 440
257+
Next Level XP: 500
258+
Progress: 440 / 500 = 88%
259+
260+
Visual:
261+
████████░░ 88%
262+
263+
CSS: Single div with width: 88%
264+
```
265+
266+
### Skill Progress Bar (Segmented - 10 blocks)
267+
```
268+
Current XP: 440
269+
Next Level XP: 500
270+
Progress: 88%
271+
272+
Block calculation:
273+
Block 1: 88% - 0*10 = 88% → 100% filled
274+
Block 2: 88% - 1*10 = 78% → 100% filled
275+
...
276+
Block 8: 88% - 7*10 = 18% → 100% filled
277+
Block 9: 88% - 8*10 = 8% → 80% filled (partial)
278+
Block 10: 88% - 9*10 = -2% → 0% filled
279+
280+
Visual:
281+
██ ██ ██ ██ ██ ██ ██ ██ █░ ░░
282+
283+
CSS: 10 divs, each with calculated fill percentage
284+
```
285+
286+
## Responsive Behavior
287+
288+
### Desktop (> 1024px)
289+
- Two columns: 30% / 70%
290+
- Grid: 3 columns for skills
291+
- All features visible
292+
293+
### Tablet (768px - 1024px)
294+
- Two columns: 35% / 65%
295+
- Grid: 2 columns for skills
296+
- Slightly tighter spacing
297+
298+
### Mobile (< 768px)
299+
- Single column layout
300+
- Characteristics on top
301+
- Skills grid below
302+
- 1 column for skills
303+
- Collapsible sections
304+
305+
## State Management
306+
307+
```typescript
308+
// Component State
309+
- isCreating: boolean (show/hide create forms)
310+
- searchQuery: string (filter skills)
311+
- filterActive: "all" | "active" | "inactive"
312+
- isEditing: boolean (edit mode for cards)
313+
- showDeleteDialog: boolean (confirmation dialogs)
314+
315+
// React Query State
316+
- skills: Skill[] (cached data)
317+
- characteristics: Characteristic[] (cached data)
318+
- isLoading: boolean (loading states)
319+
- mutations: createSkill, updateSkill, etc.
320+
```
321+
322+
## Navigation Flow
323+
324+
```
325+
Index (/)
326+
↓
327+
Habits (/habits)
328+
↓
329+
[Skills Button]
330+
↓
331+
Skills (/skills) ←──────┐
332+
↓ │
333+
[Back Button] ──────────┘
334+
↓
335+
Index (/)
336+
```
337+
338+
## Summary
339+
340+
The Skills System provides a comprehensive, production-ready solution for managing skills and characteristics with:
341+
- ✅ Intuitive two-column layout
342+
- ✅ Real-time XP tracking and level calculation
343+
- ✅ Full CRUD operations with confirmation
344+
- ✅ Search and filtering
345+
- ✅ Persistent storage
346+
- ✅ Clean, Notion-style design
347+
- ✅ Type-safe implementation
348+
- ✅ Responsive design

0 commit comments

Comments
 (0)