this repo has no description
Create DESIGN.md
+161
+161
DESIGN.md
+161
DESIGN.md
···
1
+
## Design System
2
+
3
+
### Design Intent
4
+
5
+
The interface should feel like a compact developer console for studying data behavior. It is educational product UI, not a marketing site. The design should make route state, table data, cache behavior, search params, pagination, and live query updates easy to inspect.
6
+
7
+
Physical scene: a developer is working through examples on a laptop or external monitor during a focused learning session, switching between editor, browser, and docs. Both light and dark themes are valid because the app may be used in daytime workshops or late-night debugging.
8
+
9
+
### Visual Strategy
10
+
11
+
**Register**: product
12
+
**Color strategy**: restrained
13
+
**Surface model**: tinted warm neutrals with amber as the single instructional accent
14
+
**Shape language**: square, technical, grid-like
15
+
**Texture**: hairline borders, dense spacing, table rhythm, monospace labels
16
+
17
+
The design should not look like a Pokemon fan interface. Pokemon is just the dataset. The product is the prefetching behavior.
18
+
19
+
### Color Tokens
20
+
21
+
All color should come from `src/styles/tokens.css` unless a new token is intentionally added.
22
+
23
+
**Primitive families**
24
+
25
+
- `--color-amber-*`: primary instructional accent.
26
+
- `--color-warm-*`: tinted neutral ramp for light and dark surfaces.
27
+
- `--color-green-*`: cached or available state.
28
+
- `--color-red-*`: error state.
29
+
30
+
**Semantic roles**
31
+
32
+
- `--bg-primary`: app page background.
33
+
- `--bg-secondary`: header, secondary bands, hovered rows, form surfaces.
34
+
- `--bg-tertiary`: deeper nested surface when separation is needed.
35
+
- `--bg-card`: primary content panels.
36
+
- `--text-primary`: main reading text and active labels.
37
+
- `--text-secondary`: section labels and supporting labels.
38
+
- `--text-muted`: hints, subtitles, disabled states, metadata.
39
+
- `--accent-default`: active accent, selected state, instructional callouts.
40
+
- `--accent-subtle`: hover and quiet emphasis background.
41
+
- `--border-default`: normal hairline separation.
42
+
- `--border-strong`: table headers, stronger dividers, emphasis borders.
43
+
- `--status-cached`, `--status-fetching`, `--status-idle`, `--status-error`: data state indicators.
44
+
45
+
Do not use raw black or white. Keep new colors in OKLCH and add semantic aliases before using them repeatedly.
46
+
47
+
### Typography
48
+
49
+
**Primary UI font**: JetBrains Mono via `--font-mono`.
50
+
**Display font**: Barlow via `--font-display`.
51
+
52
+
Use monospace for route names, status labels, tables, filters, buttons, and console controls. Use display type sparingly for major headings, especially the landing page title and large article titles.
53
+
54
+
Current scale:
55
+
56
+
- `--text-xs`: dense labels, table headings, badges.
57
+
- `--text-sm`: default body and controls.
58
+
- `--text-base`: landing descriptions and prominent card titles.
59
+
- `--text-lg`: console card headings.
60
+
- `--text-xl` and above: section headings and hero headings.
61
+
62
+
Uppercase labels should be short. Avoid long uppercase prose because it harms scan speed.
63
+
64
+
### Layout
65
+
66
+
The app uses a compact, document-like structure:
67
+
68
+
- Sticky horizontal navigation at the top.
69
+
- Landing page with a concise intro and grouped example links.
70
+
- Example pages with `max-w-7xl`, 24px page padding, a section header, then a strategy/content split.
71
+
- Console cards for data tables, filters, skeletons, and controls.
72
+
73
+
The strategy route layout uses:
74
+
75
+
- Left column: explanation panel through `StrategyArticle`.
76
+
- Right column: interactive console content through `ConsoleCard`.
77
+
- Desktop split: `minmax(0,0.9fr)` and `minmax(34rem,1.1fr)`.
78
+
79
+
Keep table areas dimensionally stable while loading. Existing examples reserve height with `min-h-125` and skeleton rows; preserve that pattern to prevent layout jump.
80
+
81
+
### Components
82
+
83
+
**Header**
84
+
85
+
- Sticky, top aligned, z-indexed above examples.
86
+
- Horizontal overflow is acceptable and intentional.
87
+
- Active nav item uses `>` as a terminal prompt.
88
+
- Theme toggle cycles system, light, dark.
89
+
90
+
**Example cards**
91
+
92
+
- Used on the landing page as route launchers.
93
+
- Zero radius, one-pixel border, visible hover border shift.
94
+
- The recommended starting example uses `--accent-surface` and an uppercase badge.
95
+
- Keep card copy short and behavior-specific.
96
+
97
+
**ConsoleCard**
98
+
99
+
- Primary framed work surface.
100
+
- White or dark card background via `--bg-card`.
101
+
- One-pixel border, zero radius, 24px padding.
102
+
- Use hover only when the whole card is interactive.
103
+
104
+
**SectionHeader**
105
+
106
+
- Route title and `//` subtitle.
107
+
- Border-bottom separates the console header from route content.
108
+
- Keep subtitles terse and implementation-focused.
109
+
110
+
**PokemonTable**
111
+
112
+
- Monospace table with uppercase headers.
113
+
- Row hover uses secondary background.
114
+
- IDs are muted, names are primary, types are compact badges.
115
+
- Preserve readability over decoration.
116
+
117
+
**StatusDot**
118
+
119
+
- `cached`: green with subtle ring.
120
+
- `fetching`: amber with reduced-motion-safe pulse.
121
+
- `idle`: neutral.
122
+
- `error`: red with subtle ring.
123
+
124
+
Status dots should always be paired with visible or accessible labels when the meaning is not obvious from surrounding copy.
125
+
126
+
**Forms and Pagination**
127
+
128
+
- Inputs inherit console styling: zero radius, secondary background, accent focus.
129
+
- Buttons and pagination links use bordered rectangular controls.
130
+
- Disabled pagination should be visible but inert.
131
+
- Search state should be reflected in URL search params and visible page text.
132
+
133
+
### Motion
134
+
135
+
Motion is functional. The fetching dot pulse is the canonical motion pattern. Keep transitions short (`--duration-fast` or `--duration-normal`) and limited to color, opacity, transform, or shadow. Respect `prefers-reduced-motion`.
136
+
137
+
Do not animate layout properties. Do not introduce ornamental motion.
138
+
139
+
### Accessibility
140
+
141
+
- Preserve visible focus rings on links, buttons, and inputs.
142
+
- Do not rely on color alone for status when the context is ambiguous.
143
+
- Keep contrast at WCAG 2.1 AA or better.
144
+
- Theme changes must remain keyboard accessible.
145
+
- Loading skeletons should reserve space and avoid flashing.
146
+
- Reduced motion must disable repeated attention-grabbing animation.
147
+
148
+
### Copy Rules
149
+
150
+
- Be concrete about behavior: prefetch, cache, loader, synced collection, search param, live query.
151
+
- Use route names consistently with the nav sequence.
152
+
- No em dashes in product copy.
153
+
- Avoid hype, jokes, or generic SaaS wording.
154
+
- Replace placeholder instructional content before treating a route as finished.
155
+
156
+
### Known Design Debt
157
+
158
+
- `StrategyArticle` still uses lorem ipsum and a decorative oversized rounded/shadowed panel. It does not yet match the sharper console system.
159
+
- The landing page lists six examples, while the header includes eight. The home page should include the live query examples or label them as a separate advanced group.
160
+
- `Header` contains `flex-hteshrink-0`, which appears to be a typo for a flex/shrink utility.
161
+
- `README.md` still contains starter TanStack instructions and direct `pnpm` commands, which conflict with repo Vite+ rules.