From 4cfa55a934e21a357ed897fb4c86076d6e192c55 Mon Sep 17 00:00:00 2001 From: Rachel Stiansen Date: Sun, 27 Sep 2026 15:52:32 +0200 Subject: [PATCH 1/4] docs: #29 add UI specification --- docs/ui-specification.md | 155 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 docs/ui-specification.md diff --git a/docs/ui-specification.md b/docs/ui-specification.md new file mode 100644 index 0000000..c1f7a10 --- /dev/null +++ b/docs/ui-specification.md @@ -0,0 +1,155 @@ +# UI specification + +This document describes the planned user interface for the album catalogue +using static example data. It is a lightweight specification of how albums +will be presented and how users can search, filter, sort and browse the +catalogue before the client is connected to the backend. + +## Example data + +| Title | Artist | Year | Genres | Rating | Reviews | +| --- | --- | ---: | --- | ---: | ---: | +| Abbey Road | The Beatles | 1969 | Rock | 4.8 | 1240 | +| Rumours | Fleetwood Mac | 1977 | Rock, Pop | 4.7 | 980 | +| Thriller | Michael Jackson | 1982 | Pop, R&B | 4.6 | 1530 | +| Nevermind | Nirvana | 1991 | Rock, Grunge | 4.5 | 870 | +| OK Computer | Radiohead | 1997 | Alternative Rock | 4.7 | 760 | +| Back to Black | Amy Winehouse | 2006 | Soul, R&B | 4.6 | 640 | + +These examples represent the main information shown for an album in the +search results. Album artwork can also be displayed when available. + +## Search and browse view + +The main page consists of a search field, filtering and sorting controls, +and a list or grid of matching albums. + +### Search + +The user can search for albums by title or artist. A search is submitted by +pressing Enter or clicking the search button. The result view is then updated +with albums matching the search. + +### Filters + +The user can narrow the result set by genre and decade. Each available filter +option shows the number of matching albums. + +Selected filters are shown above the results and can be removed individually +or cleared together. + +### Sorting + +The result set can be sorted without changing the current search or filters. +Planned sorting options include title, release year and community rating. + +### Results and paging + +The result view shows the number of matching albums and presents the albums +as cards. Each card gives the user enough information to identify and compare +albums without opening the detail view. + +An initial set of results is loaded first. The user can request more results +using a "Load more" control. Newly loaded albums are added to the existing +results. + +### Album details + +Selecting an album opens a detail view for that album. The detail view presents +the album artwork and the available information about the album in more detail. + +The user can return to the search results without having to start the search +again. + +## Empty result state + +To avoid dead-end filter combinations, filter options that would produce zero +results are not shown. The count next to each available option lets the user +see how many albums would remain before applying the filter. + +A text search can still return no matching albums. In that case, the result +area shows a clear "No albums found" message together with an option to clear +the search or active filters. + +## Wireframe + +The wireframes show the intended structure of the interface rather than final +visual styling. + +### Search and browse view + +```text +┌─────────────────────────────────────────────────────────────────────────────┐ +│ ALBUM CATALOGUE About / Info │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Discover your next album │ +│ │ +│ ┌──────────────────────────────────────────┐ ┌──────────┐ │ +│ │ Search by album or artist... │ │ Search │ │ +│ └──────────────────────────────────────────┘ └──────────┘ │ +│ │ +├───────────────────┬─────────────────────────────────────────────────────────┤ +│ FILTERS │ 42 albums Sort: Rating ▾ │ +│ │ │ +│ Genre │ Active: [ Rock × ] [ 1990s × ] Clear all │ +│ □ Rock (24) │ │ +│ □ Pop (18) │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ □ R&B (12) │ │ │ │ │ │ │ │ +│ □ Soul (8) │ │ COVER │ │ COVER │ │ COVER │ │ +│ │ │ │ │ │ │ │ │ +│ Decade │ ├──────────────┤ ├──────────────┤ ├──────────────┤ │ +│ □ 1960s (7) │ │ OK Computer │ │ Nevermind │ │ Abbey Road │ │ +│ □ 1970s (11) │ │ Radiohead │ │ Nirvana │ │ The Beatles │ │ +│ □ 1980s (9) │ │ 1997 │ │ 1991 │ │ 1969 │ │ +│ □ 1990s (12) │ │ Alt. Rock │ │ Rock, Grunge │ │ Rock │ │ +│ □ 2000s (6) │ │ ★ 4.7 (760) │ │ ★ 4.5 (870) │ │ ★ 4.8 (1.2k)│ │ +│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ │ +│ │ [ Load more ] │ +└───────────────────┴─────────────────────────────────────────────────────────┘ +``` + +### Album detail view +```text +┌─────────────────────────────────────────────────────────────────────────────┐ +│ ALBUM CATALOGUE │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ← Back to results │ +│ │ +│ ┌──────────────────────┐ OK Computer │ +│ │ │ Radiohead │ +│ │ │ │ +│ │ ALBUM COVER │ 1997 · Alternative Rock │ +│ │ │ ★ 4.7 · 760 ratings │ +│ │ │ │ +│ └──────────────────────┘ [ Rate this album ] │ +│ │ +│ ───────────────────────────────────────────────────────────────────────── │ +│ │ +│ Community reviews [ Write review ] │ +│ │ +│ ★★★★★ username 2 days ago │ +│ Really enjoyed this album... │ +│ │ +│ ★★★★☆ username 1 week ago │ +│ Great album, especially... │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +## Design considerations + +The interface will be designed to work with both keyboard and pointer input. +Search, filters, sorting and album cards must have visible labels and focus +states, and information such as ratings and active filters must not rely on +colour alone. + +The result grid will adapt to smaller screens rather than requiring horizontal +scrolling. + + +Only an initial set of results is requested and rendered. Additional results +are loaded on demand, reducing unnecessary data transfer and rendering for +large result sets. \ No newline at end of file From 5d5b2054cc3462c4e670bb5b241ca94132d1e65d Mon Sep 17 00:00:00 2001 From: Rachel Knutsen Stiansen Date: Thu, 1 Oct 2026 11:25:39 +0200 Subject: [PATCH 2/4] docs: #29 format UI specification --- docs/ui-specification.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/ui-specification.md b/docs/ui-specification.md index c1f7a10..e81f8bf 100644 --- a/docs/ui-specification.md +++ b/docs/ui-specification.md @@ -7,14 +7,14 @@ catalogue before the client is connected to the backend. ## Example data -| Title | Artist | Year | Genres | Rating | Reviews | -| --- | --- | ---: | --- | ---: | ---: | -| Abbey Road | The Beatles | 1969 | Rock | 4.8 | 1240 | -| Rumours | Fleetwood Mac | 1977 | Rock, Pop | 4.7 | 980 | -| Thriller | Michael Jackson | 1982 | Pop, R&B | 4.6 | 1530 | -| Nevermind | Nirvana | 1991 | Rock, Grunge | 4.5 | 870 | -| OK Computer | Radiohead | 1997 | Alternative Rock | 4.7 | 760 | -| Back to Black | Amy Winehouse | 2006 | Soul, R&B | 4.6 | 640 | +| Title | Artist | Year | Genres | Rating | Reviews | +| ------------- | --------------- | ---: | ---------------- | -----: | ------: | +| Abbey Road | The Beatles | 1969 | Rock | 4.8 | 1240 | +| Rumours | Fleetwood Mac | 1977 | Rock, Pop | 4.7 | 980 | +| Thriller | Michael Jackson | 1982 | Pop, R&B | 4.6 | 1530 | +| Nevermind | Nirvana | 1991 | Rock, Grunge | 4.5 | 870 | +| OK Computer | Radiohead | 1997 | Alternative Rock | 4.7 | 760 | +| Back to Black | Amy Winehouse | 2006 | Soul, R&B | 4.6 | 640 | These examples represent the main information shown for an album in the search results. Album artwork can also be displayed when available. @@ -111,6 +111,7 @@ visual styling. ``` ### Album detail view + ```text ┌─────────────────────────────────────────────────────────────────────────────┐ │ ALBUM CATALOGUE │ @@ -149,7 +150,6 @@ colour alone. The result grid will adapt to smaller screens rather than requiring horizontal scrolling. - Only an initial set of results is requested and rendered. Additional results are loaded on demand, reducing unnecessary data transfer and rendering for -large result sets. \ No newline at end of file +large result sets. From cc7c8a9f8b8d0d8cbd8c5f85896ca3e1637b4e47 Mon Sep 17 00:00:00 2001 From: Rachel Knutsen Stiansen Date: Thu, 1 Oct 2026 11:36:03 +0200 Subject: [PATCH 3/4] docs: #29 link UI specification --- docs/architecture.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 6444165..4692d8a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,8 +1,9 @@ # Architecture decisions The main technical choices for Crate and why we made them. Most are implemented -in M2 and M3. The API contract is `schema.graphql`, and the data model is in -`docs/data-model.md`. +in M2 and M3. The API contract is `schema.graphql`, the data model is in +`docs/data-model.md`, and the planned interface is described in +`docs/ui-specification.md`. ## 1. PostgreSQL + GraphQL Yoga From 89dcf1ee341ae05297bf256b4190ca857f4b23de Mon Sep 17 00:00:00 2001 From: Rachel Knutsen Stiansen Date: Thu, 1 Oct 2026 20:16:20 +0200 Subject: [PATCH 4/4] docs: #29 add decade filtering to GraphQL schema --- docs/data-model.md | 4 ++-- schema.graphql | 7 +++++++ 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/data-model.md b/docs/data-model.md index 8aebd5b..6bc4cd3 100644 --- a/docs/data-model.md +++ b/docs/data-model.md @@ -31,7 +31,7 @@ schema already describes the operations the client will need. ## Search results -`searchAlbums` accepts one search term, optional genre filters and a sort +`searchAlbums` accepts one search term, optional genre and decade filters and a sort choice. It returns a cursor-based connection so the client can load results in pages. The connection also contains the total number of matches and genre -facet counts for the filter UI. +and decade facet counts for the filter UI. diff --git a/schema.graphql b/schema.graphql index 5900c6b..f8fc7f5 100644 --- a/schema.graphql +++ b/schema.graphql @@ -63,6 +63,7 @@ type AlbumConnection { pageInfo: PageInfo! totalCount: Int! genreFacets: [GenreFacet!]! + decadeFacets: [DecadeFacet!]! } type AlbumEdge { @@ -70,6 +71,11 @@ type AlbumEdge { node: Album! } +type DecadeFacet { + decade: Int! + count: Int! +} + type ReviewConnection { edges: [ReviewEdge!]! pageInfo: PageInfo! @@ -125,6 +131,7 @@ type RemoveFromCratePayload { input AlbumSearchInput { query: String! genreIds: [ID!] + decades: [Int!] sort: AlbumSort! }