Skip to content

Commit 92cd2cd

Browse files
gildesmaraisgildesmarais
committed
Refine feed directory hierarchy and interactions
1 parent 02dede1 commit 92cd2cd

4 files changed

Lines changed: 1070 additions & 423 deletions

File tree

‎docs/2026-03-21-feed-directory-ux-plan.md‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
# Feed Directory UX Plan
2+
3+
Date: 2026-03-21
4+
5+
## Goal
6+
7+
Improve the `/feed-directory/` page so the first screen communicates immediate value and shows usable feed results instead of leading with explanatory copy and form-heavy UI.
8+
9+
This plan is based on the live page at `http://localhost:4321/feed-directory/` inspected with `chrome-mcp`.
10+
11+
## Current Problems
12+
13+
### Above the fold
14+
15+
- Desktop: the first feed is only barely visible at the bottom of the viewport.
16+
- Mobile: no feed is visible above the fold.
17+
- The viewport is dominated by:
18+
- page title
19+
- explanatory intro copy
20+
- a full "Instance URL" documentation section
21+
- two stacked controls before the list becomes useful
22+
23+
### Feed row design
24+
25+
- Each row emphasizes internal identifiers (`domain / name`) but hides the more informative `channel.url`.
26+
- The rows feel like utility rows rather than browseable feed entries.
27+
- The `Configure` action is presented as a control, not as context about how the feed is already ready to use.
28+
- Mobile rows are sparse and oversized, with too much empty space around the action buttons.
29+
30+
## Constraints
31+
32+
- Do not introduce categories, tags, keywords, or other invented metadata.
33+
- Do not frame any feed as "not ready" because default parameters already make all feeds usable.
34+
- Work only with the fields that exist today:
35+
- `domain`
36+
- `name`
37+
- `channel.url`
38+
- `url_parameters`
39+
- `default_parameters`
40+
- `valid_channel_url`
41+
42+
## Strategy
43+
44+
### Above-the-fold strategy
45+
46+
The first screen should answer three questions immediately:
47+
48+
1. What is this?
49+
2. Can I use it right now?
50+
3. What should I do first?
51+
52+
That means the page should open with:
53+
54+
- little to no explanatory copy above the main interaction
55+
- search as the primary action
56+
- instance URL as contextual secondary state
57+
- actual feed entries visible immediately below
58+
59+
The long explanation of instance URLs should move below the main browsing experience or into a collapsed/help treatment.
60+
61+
### Instance URL treatment
62+
63+
The instance URL should stop behaving like a peer form field to search.
64+
65+
Recommended treatment:
66+
67+
- show it as contextual state below search, for example:
68+
- `Using instance: 1.h2r.workers.dev (Change)`
69+
- only reveal the editable input when the user chooses to change it
70+
- reveal the editable input inline rather than using a modal or popover
71+
- visually style it as a small pill, status row, or compact inline setting
72+
73+
Why:
74+
75+
- most users will keep the default instance
76+
- two prominent text inputs create unnecessary mental load
77+
- search should own the page, while instance selection should feel like supporting context
78+
- edited instance URLs should be validated inline and gently so a broken value does not silently degrade the experience
79+
80+
Recommended validation behavior:
81+
82+
- validate only when the user interacts with the field or attempts to apply the change
83+
- use short inline messaging such as `Enter a valid URL`
84+
- do not block the rest of the page with heavy alerts or modal error states
85+
86+
### Search treatment
87+
88+
Search should read like the main job of the page.
89+
90+
Recommended treatment:
91+
92+
- larger input
93+
- stronger visual prominence than any other control
94+
- search icon
95+
- generous border radius and spacing so it feels like a global finder, not a small filter field
96+
- placeholder examples grounded in real searches, for example:
97+
- `Search sites or feeds like fia, apple, news, or blog`
98+
99+
### Feed row strategy
100+
101+
Each row should explain the feed before asking the user to act.
102+
103+
Recommended content hierarchy:
104+
105+
1. `domain / name`
106+
2. source URL from `channel.url`
107+
3. ready-to-use status with defaults inline when present, for example `Ready with defaults: section=news`
108+
4. actions with clear hierarchy:
109+
- `RSS` primary
110+
- `Copy` adjacent to `RSS`
111+
- `Customize` secondary when defaults can be changed
112+
- `Edit` tertiary
113+
114+
This keeps all feeds framed as ready to use while still exposing how defaults work.
115+
116+
Recommended action labeling:
117+
118+
- use `Customize` for feeds whose defaults can be changed
119+
- avoid more technical labels such as `Options` or `Change defaults`
120+
- keep the wording plain and short
121+
122+
Recommended action styling:
123+
124+
- `RSS` uses the strongest visual treatment
125+
- `Copy` is visible text on desktop and may collapse to a compact icon treatment on mobile if needed
126+
- `Edit` should be de-emphasized to a ghost or low-contrast tertiary action on desktop and mobile
127+
128+
### High-value UI refinements
129+
130+
These additions stay within scope and improve scanability, consistency, and perceived quality:
131+
132+
- make each feed row feel like a single coherent surface instead of a label with detached controls
133+
- clamp long source URLs to a clean single line where possible instead of allowing messy wrapping
134+
- normalize row height as much as practical so scanning remains fast
135+
- add subtle row hover and focus treatment, not just button hover states
136+
- keep the primary action cluster visually tight so `RSS` and `Copy` read as the main pair
137+
- keep the action anchor consistent across rows so the user learns one reliable target area
138+
- improve typography hierarchy inside `domain / name`, with the feed name carrying slightly more emphasis than the domain
139+
140+
## Proposed Information Architecture
141+
142+
### New top section
143+
144+
- `Feed Directory`
145+
- search-first layout with little to no intro copy above the interaction
146+
- search input
147+
- compact instance URL summary with change affordance
148+
- first feed rows immediately visible
149+
150+
### Lower-priority content moved down
151+
152+
- long instance URL explanation
153+
- hosting guidance
154+
- community wiki link
155+
- contribution section
156+
157+
## Wireframes
158+
159+
### Desktop
160+
161+
```text
162+
+---------------------------------------------------------------+
163+
| Feed Directory |
164+
| [ Search sites, domains, or feed names.................... ] |
165+
| |
166+
| Using instance: 1.h2r.workers.dev [Change] |
167+
+---------------------------------------------------------------+
168+
169+
+---------------------------------------------------------------+
170+
| adfc.de / pressemitteilungen [RSS] [Copy] |
171+
| https://www.adfc.de/presse/pressemitteilungen/ (Edit) |
172+
+---------------------------------------------------------------+
173+
| apnews.com / hub [RSS] [Copy] |
174+
| https://apnews.com/%<section>s [Customize] |
175+
| Ready with defaults: section=news (Edit) |
176+
+---------------------------------------------------------------+
177+
| avherald.com / index [RSS] [Copy] |
178+
| https://avherald.com/ (Edit) |
179+
+---------------------------------------------------------------+
180+
```
181+
182+
### Mobile
183+
184+
```text
185+
+--------------------------------------+
186+
| Feed Directory |
187+
| [ Search........................... ]|
188+
| Using: 1.h2r.workers.dev [Change] |
189+
+--------------------------------------+
190+
191+
+--------------------------------------+
192+
| adfc.de / pressemitteilungen |
193+
| https://www.adfc.de/presse/... |
194+
| [RSS] [Copy] (Edit) |
195+
+--------------------------------------+
196+
197+
+--------------------------------------+
198+
| apnews.com / hub |
199+
| https://apnews.com/%<section>s |
200+
| Ready with defaults: section=news |
201+
| [RSS] [Copy] [Customize] (Edit) |
202+
+--------------------------------------+
203+
```
204+
205+
## Implementation Plan
206+
207+
### 1. Restructure page content
208+
209+
Update `src/content/docs/feed-directory/index.mdx`:
210+
211+
- replace the current intro paragraph plus full "Instance URL" section with a near action-first layout
212+
- move longer explanatory content below the directory component
213+
- keep contribution content lower on the page
214+
- update `Contribute on GitHub` to link directly to:
215+
- `https://github.com/html2rss/html2rss-configs/tree/master/lib/html2rss/configs`
216+
217+
### 2. Redesign top controls
218+
219+
Update `src/components/FeedDirectory.astro`:
220+
221+
- make search the primary visible control
222+
- demote instance URL into a compact secondary control
223+
- hide the editable instance input behind a change affordance or disclosure
224+
- reduce vertical space before the list begins
225+
- style search as the visual hero of the page
226+
- keep the top section simple and avoid introducing extra explanatory UI
227+
228+
### 3. Redesign feed rows
229+
230+
Update `src/components/FeedDirectory.astro`:
231+
232+
- show `channel.url` as visible secondary context
233+
- show inline ready-to-use default context for configurable feeds
234+
- keep `RSS` as the strongest action
235+
- add a `Copy` action beside `RSS`
236+
- reduce the prominence of `Edit`, ideally to a ghost or tertiary action
237+
- rename or reposition `Configure` so it reads as optional customization, not a gate
238+
- use `Customize` as the action label for changing defaults
239+
- make the full row read as one card-like unit
240+
- tighten the visual grouping of primary actions
241+
- improve title typography so rows are easier to scan
242+
- clamp or truncate long source URLs cleanly
243+
244+
### 4. Refine mobile layout
245+
246+
- reduce excessive vertical gaps
247+
- reduce top chrome pressure as much as possible because the Starlight shell already consumes significant vertical space
248+
- keep row content denser without hurting tap targets
249+
- ensure at least one full feed row is visible above the fold on common mobile viewports
250+
- avoid rows becoming disproportionately tall because of long text or wrapping actions
251+
- prefer horizontal action grouping that stays on one line
252+
- keep at least one full card plus part of the next card visible above the fold where possible so continuation is obvious
253+
254+
### 5. Improve empty states
255+
256+
Update `src/components/FeedDirectory.astro` and `src/components/feed-directory.js`:
257+
258+
- when search returns no matches, show a visible empty state instead of a blank list
259+
- include the active query in the message
260+
- point users toward the community wiki or contributing a new configuration
261+
- include a clear next step, not just a passive “no results” message
262+
263+
### 6. Add interaction polish
264+
265+
Update `src/components/FeedDirectory.astro` and `src/components/feed-directory.js`:
266+
267+
- show immediate feedback on copy actions, for example `Copied` for 1-2 seconds
268+
- ensure keyboard focus styles are crisp and obvious, especially around search and row actions
269+
- keep any transitions very light so the page feels fast and utilitarian rather than decorative
270+
- validate edited instance URLs inline with gentle feedback rather than failing silently
271+
- prefer inline disclosure patterns over popovers or modal flows
272+
273+
### 5. Preserve existing behavior
274+
275+
Update `src/components/feed-directory.js` only as needed:
276+
277+
- keep search behavior
278+
- keep instance URL updates
279+
- keep parameter editing behavior
280+
- make sure default-parameter feeds still generate working RSS links immediately
281+
282+
## Acceptance Criteria
283+
284+
- Desktop shows search and at least the first feed row clearly above the fold.
285+
- Mobile shows search and at least one complete feed row above the fold.
286+
- The page communicates value before documentation.
287+
- Feed rows expose useful context, not just identifiers and buttons.
288+
- Feeds with defaults are presented as immediately usable.
289+
- Search is visually dominant over instance configuration.
290+
- Empty searches produce a helpful message instead of an empty list.
291+
- Feed rows feel visually cohesive and easy to scan.
292+
- Long URLs do not degrade the row layout.
293+
- Edited instance URLs provide clear inline feedback when invalid.
294+
- Mobile actions remain on a single line in normal cases.
295+
- Empty states provide a next step.
296+
- Copy actions acknowledge success immediately.
297+
- Keyboard focus is visually obvious.
298+
- Motion remains subtle and fast.
299+
- `Contribute on GitHub` points directly to the configs directory in the repository.
300+
- No invented metadata is introduced.
301+
302+
## Notes From Live Review
303+
304+
Observed on the live local page with `chrome-mcp`:
305+
306+
- Desktop viewport was consumed by heading, intro copy, the full "Instance URL" explanation, and form controls before feed content became visible.
307+
- Mobile viewport showed no actual feed row above the fold.
308+
- Feed rows lower on the page showed that the current design underuses the available data, especially `channel.url`.

0 commit comments

Comments
 (0)