this repo has no description
Update PRODUCT.md
+75
-27
+75
-27
PRODUCT.md
+75
-27
PRODUCT.md
···
1
-
## Design Context
1
+
## Product Context
2
+
3
+
### Product
4
+
5
+
**Name**: Prefetching Patterns
6
+
**Register**: product
7
+
**Category**: Interactive educational blog and developer learning lab
8
+
**Current stack**: TanStack Start, TanStack Router, TanStack Query, TanStack DB, Electric SQL, Tailwind CSS v4, React 19, Drizzle, Vite+
9
+
10
+
This is a chaptered, interactive educational blog for understanding how different data loading and prefetching strategies change the feel of a React application. Each article should pair a written explanation with a working console so readers can compare baseline loading, progressively richer preloading, and a local-first synced-data approach in the same product.
11
+
12
+
The app uses Pokemon data as a familiar, low-friction dataset so the user can focus on route loaders, cache state, pagination, search, live queries, and synced collections rather than domain modeling.
2
13
3
14
### Users
4
15
5
-
**Primary audience**: Developers learning TanStack Router/Query prefetching patterns
6
-
**Context**: Educational material consumed during focused learning sessions — following tutorials, referencing implementations, or teaching workshops
7
-
**Job to be done**: Understand how different prefetching strategies work through interactive examples; eventually read companion blog posts for deeper explanation
16
+
**Primary audience**: Developers learning TanStack Router, Query, DB, Start, and Electric SQL patterns.
17
+
18
+
**Secondary audience**: Teachers, workshop leads, and technical writers who need a concrete reference implementation.
19
+
20
+
**Context**: Focused learning sessions, tutorial follow-alongs, implementation reference, workshops, and chapter-by-chapter article exploration.
21
+
22
+
**Job to be done**: Compare no preloading against increasingly capable preloading strategies, understand when data is fetched or reused, then see how local-first synced collections change the model again.
23
+
24
+
### Current Experience
25
+
26
+
The home page introduces the learning sequence and routes users into numbered chapters. The global header is a sticky, horizontally scrollable terminal-style nav with numbered route names and a three-state theme toggle.
27
+
28
+
The implemented examples are:
29
+
30
+
1. **basic**: Baseline route with no prefetching.
31
+
2. **preloading**: Route-level data prefetching.
32
+
3. **intent-preloading**: Hover and focus preloading through navigation intent.
33
+
4. **pagination**: Adjacent page preloading for previous and next Pokemon pages.
34
+
5. **filters**: Submitted name filtering with search params and prefetch behavior.
35
+
6. **debounced-filters**: Typing-driven filter prefetch using debounced interaction.
36
+
7. **live-query**: Electric SQL synced collection rendered through TanStack DB live queries.
37
+
8. **live-query-filters**: Reactive filtered live query over synced Pokemon data.
38
+
39
+
Most example routes use a two-column learning layout: a strategy article panel on the left and an interactive Pokemon console on the right. This should feel closer to Effect Institute's chaptered interactive learning model than to a standalone dashboard. The strategy article currently contains placeholder prose, so the product is not finished as teaching material until those articles explain the strategy, cache behavior, expected user observations, and implementation tradeoffs.
8
40
9
41
### Brand Personality
10
42
11
-
**Voice**: Technical, minimalistic, informative
12
-
**Tone**: Precise but approachable — like a well-crafted developer tool or technical documentation that respects the reader's intelligence
13
-
**Emotional goals**: Confidence ("I understand this now"), clarity (no cognitive load from visual noise), trust (this is correct and well-built)
43
+
**Voice**: Technical, minimal, direct.
14
44
15
-
### Aesthetic Direction
45
+
**Tone**: Precise but approachable, like a well-made developer tool that respects the reader's intelligence.
16
46
17
-
**Visual tone**: Developer console aesthetic — functional, information-dense, purposeful
18
-
**Theme**: Light AND dark mode (system preference + manual toggle)
19
-
**References**:
47
+
**Emotional goals**: Confidence, clarity, and trust. Users should feel that they can observe the system, predict what will happen next, and translate the pattern into their own code.
20
48
21
-
- https://www.effect.website/ — clean technical aesthetic, purposeful spacing, no decorative fluff, strong information hierarchy
22
-
**Anti-references**:
23
-
- AI-generated UI (GPT-5+ style) — generic gradients, glassmorphism without purpose, "designed" looking elements that serve no function
24
-
- Gradient text, side-stripe borders, glow effects
25
-
- Template-y dashboard patterns
49
+
### Product Principles
26
50
27
-
### Design Principles
51
+
1. **Comparison is the core lesson**: The product should make each strategy feel different. The user should be able to compare no preloading, route preloading, intent preloading, pagination/search preloading, and local-first live data without reading source code first.
28
52
29
-
1. **Function over decoration** — Every visual element must earn its place. No decorative gradients, no pointless shadows, no "visual interest" that doesn't aid comprehension.
53
+
2. **State should be visible**: Cache status, loading, prefetching, empty results, disabled navigation, and synced data behavior are the product. Never hide important state behind decoration.
30
54
31
-
2. **Information density is a feature** — This is teaching material. Users need to see code, data, and state at a glance. White space is good; empty space is wasteful.
55
+
3. **Examples should build in order**: The numbered sequence should move from baseline fetching to preloading, then pagination/search, then live synced data. New routes should either continue the sequence or clearly belong outside it.
32
56
33
-
3. **State should be visible** — Cache status, loading states, prefetch activity — these are the _point_ of the demo. Make them obvious without being intrusive.
57
+
4. **The article and the console teach together**: Prose should explain the why and tradeoffs. The embedded console should let users verify the behavior immediately.
34
58
35
-
4. **Respect the code** — The typography and layout should make code snippets feel at home. Monospace is appropriate here because it's literally about code.
59
+
5. **The code is the curriculum**: UI labels, route names, and component structure should map closely to real implementation concepts. Avoid marketing language where a precise technical phrase would teach more.
60
+
61
+
6. **Density is useful**: This is not a marketing landing page. Users need to scan article context, data tables, route labels, filters, pagination, and state indicators with little wasted space.
62
+
63
+
7. **Motion has instructional value only**: Animation is reserved for active fetching or interaction feedback. It should never compete with table readability.
64
+
65
+
8. **Theme parity matters**: Light, dark, and system modes are first-class. Neither mode should feel like an afterthought.
66
+
67
+
9. **Accessibility is part of the lesson**: Keyboard navigation, focus states, reduced motion, semantic labels, and sufficient contrast are required for the demo to be credible.
68
+
69
+
### Content Notes
70
+
71
+
- Replace the lorem ipsum strategy article content with route-specific chapter copy.
72
+
- Treat each route as a short educational article with an embedded interactive example.
73
+
- Keep route titles and nav labels aligned. The home page currently lists six examples while the header exposes eight; the product story should reconcile that sequence.
74
+
- Use concrete teaching copy: "hover this link", "submit a filter", "move to the next page", "watch the table reuse cached data", "watch synced rows update locally".
75
+
- Avoid decorative or vague copy. Phrases should describe observable behavior.
76
+
- The local-first chapters should explain the shift from fetching a route to subscribing to synced collections.
36
77
37
-
5. **Dark mode is not an afterthought** — Both themes should be equally considered, equally usable, and equally "correct."
78
+
### Anti-References
38
79
39
-
6. **Accessibility is non-negotiable** — WCAG 2.1 AA compliance for EU EAA requirements. Sufficient contrast, keyboard navigation, reduced motion support, screen reader friendly.
80
+
- Generic AI-generated dashboards.
81
+
- Gradient text, ornamental glows, glassmorphism, and decorative blobs.
82
+
- Marketing landing-page composition where the actual tool is below the fold.
83
+
- Template card grids that do not expose meaningful differences between examples.
84
+
- Overly playful Pokemon theming that distracts from the data-loading lesson.
85
+
- Passive blog pages where the reader cannot immediately test the concept being explained.
40
86
41
87
### Technical Notes
42
88
43
-
- Current stack: TanStack Start, Tailwind v4, JetBrains Mono (already in place)
44
-
- The warm beige + amber palette works for light mode; needs a thoughtful dark counterpart
45
-
- Status dots (cached/fetching/idle) are a key interaction pattern — preserve and refine
46
-
- Hairline borders and zero border-radius fit the technical aesthetic
89
+
- This repo uses Vite+ and the `vp` CLI. Do not use package-manager scripts directly when a `vp` command exists.
90
+
- Import Vite+ modules from `vite-plus`, not `vite` or `vitest`.
91
+
- UI is built with Tailwind v4, CSS custom properties, OKLCH tokens, zero radius, hairline borders, and JetBrains Mono.
92
+
- `src/styles/tokens.css` is the source of current color, spacing, type, theme, status, and motion tokens.
93
+
- `src/components/console/*` contains the core console primitives: cards, section headers, status dots, table, type badges, and skeletons.
94
+
- `src/components/strategy-page-layout.tsx` and `src/components/strategy-article.tsx` define the teaching route frame.