docs: #29 add UI specification

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
 

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.

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.

schema.graphql

@@ -63,13 +63,19 @@ type AlbumConnection {
   pageInfo: PageInfo!
   totalCount: Int!
   genreFacets: [GenreFacet!]!
+  decadeFacets: [DecadeFacet!]!
 }
 
 type AlbumEdge {
   cursor: String!
   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!
 }