Yoko Shiina

Sample specification: mobile guide for a fictional museum

This page presents a screen specification for the mobile web guide of a fictional museum. For internal screens, see the daily shift upload sample, where one person replaces a day's shift data in a single action, and the returns and refunds sample, where work passes between several people over several days.

Works saved during the visit stay with their visit after the exhibition ends, and the guide says why when an image can no longer be shown.

A mobile web guide that visitors open from a QR code, used with one hand while viewing works and at home afterwards, designed around that principle. No app and no account are needed to start.

Artwork detail for Morning on the Seine near Giverny by Claude Monet, label number 105 in the Dawn section, displayed in Room 1, with the Saved button and the note "Saved on this device".

This specification has two kinds of notes.

System side: why it takes this shape, given the data and the implementation's constraints.

User's side
User's side: where people tend to get stuck, and how the screen should handle it.

Purpose of this guide

A mobile web guide for a museum of works on paper. Visitors scan a QR code at the entrance and use it in the museum to find a work, read about it, listen to the audio guide, and save the works they want to remember.

The same guide is used again at home, sometimes months later. By then the exhibition may have ended, borrowed works may have gone back to their lenders, and the visitor may be on another device.

The design is built around one principle: works saved during the visit stay with their visit after the exhibition ends, and the guide says why when an image can no longer be shown. A visitor should not be left guessing where an image went, or why the display content recorded for a past visit differs from what is on view today.

The two situations ask for different things. During the visit: one hand, a weak connection in places, no time to sign up. At home: the whole record, on any device, after the exhibition. That is why saving starts on the device without an account, and an email address is added only when the visitor chooses.

User's side
Visitors do not separate the guide from the museum. If a saved image disappears without a word, it reads as the museum losing their things. That is why, when an image can no longer be shown or a work was not on display on the day of the visit, the guide keeps the work's information and says why, in the visitor's terms.

Setting

Northlight Museum (fictional) is a museum of prints, drawings and watercolours. Its exhibition Under Changing Skies (12 September 2026 to 10 January 2027) follows the sky through a day in five thematic sections: Dawn, Daylight, Weather, Dusk and Night. Each section is displayed in a separate room. The section names describe the exhibition content; room numbers identify the physical locations. The exhibition shows works from the collection and borrowed works, mainly paintings and some works on paper.

The museum has four floors. Rooms 1 to 4 are on the second floor and house the Dawn, Daylight, Weather and Dusk sections respectively. Room 5 houses the Night section on the lower ground floor, where there is often no connection. The exhibition spans both floors. Collection displays are on the first floor. The first digit of a label number is the room number.

The guide supports eight languages, with complete content in English and Japanese. The screens in this sample are shown in English, with their original interface text.

The artworks are real works from public collections, shown with open-access images. Their room assignments, label numbers and loans are part of the fiction.

Starting the guide
A fixed QR code with no expiry. Opening the guide creates nothing; a visit is created by the first save.
First language
The device's language if it is one of the eight, otherwise English. A language the visitor chooses takes priority.
Code
6 digits, valid for 10 minutes, typed in the same tab. A new code makes earlier codes invalid.
Limits
5 incorrect attempts per code, and 5 new codes per hour.
Staying signed in
6 months since last use. Signing out is in the Menu on every page.
Images of borrowed works
Shown during the exhibition only, as the loan agreement sets. This also applies to images kept on the device.
Images in copyright
Not shown when the rights holder has not agreed. A sentence says why.

The image terms are fictional, but follow how museums usually work: the right to show an image is agreed for each loan and each display, not owned together with the work. That is why the guide keeps image terms per display instead of a single setting on the work. The figures 10 minutes, 5 attempts, 5 codes and 6 months are fictional rules.

Who is involved

Visitors use the guide in two situations. Two other parties do not use the guide, but decide what it can show.

Uses the guide

  • Visitor during the visit

    Views works with one hand on the phone, sometimes without a connection. Finds a work by label number or room, reads, listens and saves.

  • Visitor after the visit

    Looks back at saved works, possibly on another device and after the exhibition has ended. May add an email address or correct the visit date.

Does not use the guide

  • Museum

    Publishes the displays: which works are in which room, under which label number, from when to when. A published display arrangement is never changed; a change is a new version.

  • Lenders and rights holders

    Decide whether an image of a work may be shown, and for how long. The guide follows their terms and explains them to the visitor.

The visitor is the same person in both situations. On the same device, nothing is needed to go from one to the other. To look back on another device, the visitor signs in with an email address, which they can do at any point; it is not a required step.

The word "visit" has one meaning throughout: one museum on one date, created by the first save. It is not a session and not an account. Keeping the word fixed is what lets "save to this visit" and "combine two visits" mean the same thing on the screen, in the data and in the API.

Screen structure

Four places are always one tap away in the bottom navigation: On display, Number, Floor plan and Saved. They are the places a visitor moves between while viewing the works.

Things used rarely sit in a Menu at the top right of every page: language, account, and information about the guide. Focused steps, such as entering a code or viewing an image full screen, show neither.

There is no breadcrumb. The current place is shown in three layers: the selected item in the bottom navigation, a back link named after where it leads, and the coloured band identifying the thematic section and the location of the work.

The start screen: "On display today" with the date, cards for the exhibition Under Changing Skies and for the collection displays, and buttons to enter a label number or open the floor plan.
01 StartToday's displays come first. There is no welcome text: people who scan the code want to start looking.
The works list of Under Changing Skies: the band identifying the Dawn section and its floor, and works in two columns on square mats.
02 Works listWorks are grouped by room. Each group starts with a band in the corresponding thematic section colour, labelled with the section name and floor. The band stays at the top while scrolling through that group of works. Works sit on square mats and are never cropped.
Artwork detail for Yatsumi Bridge by Utagawa Hiroshige, a tall print shown in full on its mat, with the label number, title, artist and the Saved button below.
03 Artwork detailPortrait works are limited in height, so the label number, title and artist stay on the first screen. Saving sits right under the caption.
The record of a visit on Tuesday 27 October 2026, viewed after the exhibition ended: three saved works, one with an empty mat and the note "Image shown during the exhibition only", and links to the works displayed in each room on the visit date.
04 A visit after the exhibitionA visit keeps the display arrangement of its day: which works were displayed in each room, with their label numbers and order. A borrowed work keeps its information, and says that its image was shown during the exhibition only.

The screens are designed in Figma as 44 screens in seven sections, with the colours set up for light and dark mode. This page shows the four main ones; the full set is in Figma.

User flow

The flow below follows seven stages, from using the guide during the visit to looking back afterwards. The first four happen during the visit; the last two are usually later. Adding an email address is optional and can happen at either time. Each stage pairs a possible difficulty with how the guide handles it.

Open the guide

Done by
Visitor during the visit
Where people get stuck
A sign-up screen or an app download stands between the QR code and the exhibition.
How it is handled
The QR code opens today's displays in the device's language. Nothing is created and nothing is asked.

Find a work

Done by
Visitor during the visit
Where people get stuck
It is unclear how to get from a label on the wall to the page about the work, and typing a full number on a phone is slow.
How it is handled
Typing the first digit of the label number shows the room number and the works displayed there. A work opens only when the visitor chooses it, so a wrong digit never opens the wrong page. The works list and the floor plan lead to the same page.

Look and listen

Done by
Visitor during the visit
Where people get stuck
The image is cropped to fit, the caption is pushed below the screen, or the audio fails in a room without a connection.
How it is handled
Images keep their proportions on a mat, and portrait works are limited in height so the title stays on the first screen. Text that has already loaded stays available offline; the audio says that it needs a connection.

Save

Done by
Visitor during the visit
Where people get stuck
Saving asks for an account, or it is unclear where a saved work is kept.
How it is handled
Saving works at once, without an account, and says "Saved on this device". The first save mentions, once, that an email address keeps the works on other devices too.

Add an email address (optional)

Done by
Visitor during the visit · Visitor after the visit
Where people get stuck
The guide says before any proof that the address is already registered, or the code arrives as a link that opens in another browser, where the saved works are not.
How it is handled
One flow for new and returning visitors, with a 6-digit code typed in the same tab. After the code, the page says what happened to the saved works: kept, added to an earlier account, or added to the same visit from another device.

Look back

Done by
Visitor after the visit
Where people get stuck
The list no longer matches what the visitor remembers: works seem to be missing, or the works shown for a room differ from what was there on the visit date.
How it is handled
Before signing in, Saved shows the works saved in this browser. After signing in, it shows visits by date, on any device. Each visit shows its saved works and links to the works displayed in each room on that day, and saving from there adds to that visit.

After the exhibition

Done by
Visitor after the visit
Where people get stuck
Images of borrowed works disappear without a word, and the visitor thinks the save is broken.
How it is handled
The work stays, with all its information. Where the image was, a sentence says it was shown during the exhibition only.

Browsing and saving need no account. Before signing in, saved works stay in this browser on this device. Signing in adds them to an account, where they are kept as visits by date and can be seen on other devices. This keeps the steps during the visit short, and a problem with signing in does not stop anyone from looking at the art.

User's side
The moments that cause most doubt come later: at home, on another device, after the exhibition. That is why the flow continues after the visit, and why the last two steps get as much care as the first five.

Images, notices and actions

The works are why people open the guide, so images follow how works on paper are shown: on a mat, at their own proportions. Notices stay quiet unless the visitor needs to do something.

Images

In lists, every work sits on a square mat of the same size and keeps its proportions inside it. Nothing is cropped, so portrait and landscape works sit in an even rhythm.

On the artwork detail, the image is as wide as the screen. A portrait work that would be taller than 440 px at full width is shown 440 px high, centred on its mat. The label number, title and artist then stay on the first screen of a typical phone.

When an image cannot be shown, the mat stays in place and carries a sentence that says why. An empty mat on its own would look like a loading failure.

Kinds of notice

KindUsed when
ErrorSomething the visitor entered needs correcting: a code that does not match, a label number with no match. Icon, text and the error colour; the typed value stays.
InformationSomething to know, with nothing wrong: a description only in English, an image shown during the exhibition only. Grey text, announced once; an information icon where the notice stands apart from the content, such as above a description.
ConnectionThe connection is lost or back. A notice under the top bar that starts with what still works, announced once; "Back online" for a moment when it returns.
ConfirmationAn action had a result the visitor should see: "Saved on this device", "You have signed out." Short, next to where the action happened.
DecisionA choice that cannot be undone: signing out with changes not yet sent. A dialog that says what will be lost before the buttons.

Colour is never the only signal. Every notice says what it means in words, errors and connection notices add an icon, and section colours always come with the section name.

How actions are offered

Kind of actionHow it looksReason
The main action on a pagePrussian blue fillOne per page, so the next step is easy to find: "Send code", "Combine visits".
Saving a workA toggle under the caption: outlined before saving, filled once saved, with a label that says where the work is keptSaving is frequent and easy to undo, so it starts light. Once saved, the fill and the label show at a glance that the work is saved and where it is kept.
Adding an email address or signing inOutlineAn option, not a request. A filled button would read as the expected next step.
Actions with consequencesThe label states the result"Combine visits" instead of "Save date", "Sign out and remove it" instead of "Sign out": what happens is clear before pressing.
Losing something the visitor cannot get backOutline in the error colour, never the main actionIn the sign-out dialog, "Stay signed in" is the main action, so losing changes takes a deliberate choice.
Actions not possible right nowShown as unavailable, with the reason next to itAudio and changing the date need a connection. The visitor learns why, and that it will work again, instead of finding a feature gone.

Borders are kept for things that can be pressed and for images. Plain text is separated by space, rules or a change of background.

Prussian blue is the only action colour. It comes from the exhibition itself: the pigment was made in Europe in the 18th century, and Hokusai and Hiroshige later used it for sky and water. Section colours identify thematic sections and are also used for their corresponding rooms on the floor plan. They are never used for actions or status.

User's side
In a dark exhibition room, a bright screen catches the eye of everyone nearby. Quiet notices, a dark mode that follows the device, and a dark full-screen viewer keep the screen from competing with the works.

States

The two state diagrams below cover saved works and artwork images. Each state has a defined appearance and label, so the screens and specification describe it consistently.

A saved work

Not savedSaved on this deviceNot yet addedSaved

The image of a work

ShownPeriod endedNot shown

Arrows with two heads go both ways. Every move is listed below, with what causes it.

The state of a save on the server never depends on the order in which requests arrive. Within one device the order of actions decides; between devices the later action does. That is why "Not yet added" can end in Saved or Not saved without the visitor seeing a work flicker back.

User's side
"Saved on this device" and "Saved" are different words on purpose. Before signing in, the work is only in this browser, and the visitor should know that before clearing the browser or switching phones.

Every state and what moves it

A saved work

  • Not savedNOT_SAVED
    Shown as
    "Save this work"
    Moves to
    • Saved on this device (saved before signing in)
    • Saved (saved while signed in, with a connection)
    • Not yet added (saved while signed in, without a connection)
  • Saved on this deviceON_DEVICE
    Shown as
    "Saved on this device"
    Moves to
    • Saved (the visitor signs in and the work is added to the account)
    • Not saved (removed)
  • Not yet addedNOT_YET_ADDED
    Shown as
    "Saved", and in the visit "Not yet added to your account"
    Moves to
    • Saved (the connection returns and the change is sent)
    • Not saved (removed before it is sent)
    • Not saved (the visitor signs out and chooses to lose the change)
  • SavedSAVED
    Shown as
    "Saved"
    Moves to
    • Not saved (removed; without a connection, the removal is shown at once and sent later)
    • Not saved (a newer removal from another device is applied)

The image of a work

  • ShownSHOWN
    Shown as
    The image on its mat
    Moves to
    • Period ended (the display period set by the loan agreement ends, online and for images kept on the device)
  • Period endedPERIOD_ENDED
    Shown as
    An empty mat: "The image of this work was shown during the exhibition only."
  • Not shownNOT_SHOWN
    Shown as
    An empty mat: "This work is still in copyright, and the guide does not show an image of it." During the exhibition, also where to see the work.

Across the save and image states, the work retains its title, caption, description, audio and transcript. Playing audio still needs a connection. A work whose image is Not shown stays so unless the rights holder agrees, and a later loan of the same work has its own terms.

Edge cases

Edge cases are grouped by what causes them. Each records what is shown, how the guide behaves, why, what it is like for the visitor, and what the visitor can do next.

Visitors use the guide on their own, so there is no "Taken on by" field as in the returns sample. Each case ends with what the visitor can do instead.

ASaving without an account

Saving starts in the browser, and an account is something the visitor adds. These cases keep that step safe.

6 cases
A1

Saving before adding an email address

Shown
"Saved on this device". After the first save only: "To see your saved works later, or on another device, you can add your email address."
Behaviour
The work is stored in this browser at once. The suggestion appears once; Saved keeps a permanent way to add an email address.
Reason
Asking for an account while the visitor is viewing works would stop many people from saving at all. "On this device" says where the work is kept.
User's side
A request repeated on every save starts to feel like a condition. Once is enough to know the option exists.
What the visitor can do next
Keep saving, or add an email address from Saved at any time.
A2

An address that has used the guide before

Shown
The same entry page and code page for every address. After the code: "Welcome back".
Behaviour
Nothing says "already registered" before the code is confirmed. The completion page is chosen after the code.
Reason
A message that depends on the address would let anyone check whether an address has used the guide.
User's side
The visitor does not need to remember whether they signed up before; the steps are the same either way.
What the visitor can do next
Enter the code. Earlier visits appear together with today's.
A3

The code arrives by email

Shown
"Keep this page open while you check your email." One field for the 6 digits.
Behaviour
The code is typed in the same tab. The single field supports paste and one-time-code autofill.
Reason
A link in the email can open in another browser, such as the one inside the mail app, which cannot see the works saved in this one.
User's side
Moving between apps on a phone makes it easy to lose the page; the page says to come back to it.
What the visitor can do next
Copy or type the code into this page.
A4

The code cannot be used

Shown
Does not match: a message above the field, with the typed value kept. Expired or too many attempts: the heading "Get a new code" and no field. Limit reached: "Try again at 15:42".
Behaviour
A mismatch keeps the field. An expired or blocked code removes it, so a field that cannot work does not invite more tries. The limit shows the time when the next code can be requested.
Reason
The heading says what the page asks for now. A time is clearer than "later".
User's side
The saved works stay on the device in the meantime, and the page says so.
What the visitor can do next
Correct the code, request a new one, or come back at the time shown.
A5

The same visit on two devices

Shown
After the code: "Welcome back", with the works added to the existing visit of that day.
Behaviour
Visits on the device are matched to visits in the account by museum and date, and a work saved on both is kept once. Only the works currently saved are added; earlier removals on the device are not sent.
Reason
A visit is one museum on one date. Two records for the same day would split it, and sending old removals could remove works saved on the other device.
User's side
The visitor sees one visit with everything saved that day, whichever phone was used.
What the visitor can do next
Nothing to do; the visit is complete.
A6

The answer to signing in does not arrive

Shown
The code page stays, with the code still in the field and a message that the guide did not get an answer. Sending again leads to the same completion page.
Behaviour
The request carries an id made on the device. Within the code's 10 minutes, sending it again returns the first result without adding anything twice. The device keeps its saved works until it has the answer.
Reason
The server may have signed the visitor in, even though the phone never received the reply.
User's side
Pressing the button again is what people do, so it has to be safe.
What the visitor can do next
Press the button again.

OAway from a connection

Room 5, which houses the Night section, is on the lower ground floor, where the signal is weak. These cases keep reading and saving working there, and make sure changes reach the account in the right state later.

6 cases
O1

Opening a work without a connection

Shown
Under the top bar: "No connection. You can keep browsing and saving works. Audio will play again when you are back online." The audio reads "Audio needs a connection", and the transcript link "Read the transcript (available offline)".
Behaviour
Works that have finished loading open as usual. The notice starts with what still works and is announced once. The audio is shown as unavailable, and the transcript is offered instead.
Reason
After the guide opens, the text and reduced images of today's displays load in the background. Audio is not loaded in advance, so that opening the guide does not use a large amount of mobile data.
User's side
A lost connection should not feel like the guide has stopped working. The visitor can still read what the audio says.
What the visitor can do next
Read the transcript, or play the audio after leaving the room.
O2

Saving while signed in, without a connection

Shown
"Saved", and below it, once: "It will be added to your account when you are back online." In the visit, a clock icon and "Not yet added to your account".
Behaviour
The save is kept on the device and sent when the connection returns, when the guide is opened again, or on a later retry. The Saved count includes it at once.
Reason
The visitor saved the work, so it is shown as saved. Only the place where it is kept is still to come.
User's side
Without the note, a work that appears on another device later than expected would make saving look unreliable.
What the visitor can do next
Nothing; it is sent when there is a connection.
O3

Saving, then removing, without a connection

Shown
The button returns to "Save this work" at once.
Behaviour
Both actions are kept in the order they were made, numbered on the device. When they are sent, the last action decides, even if both have the same time or the phone's clock was changed.
Reason
Times alone cannot always put two quick actions on one device in order.
User's side
The visitor's last action is what counts. A removed work does not come back.
What the visitor can do next
Nothing.
O4

The sign-in period ends while changes are waiting

Shown
In Saved: "Your sign-in has ended. 1 change on this device has not been added to your account yet. Sign in with name@example.com to add it." "Sign in" is offered there and in the Menu.
Behaviour
Waiting changes belong to the account they were made in. They are sent only after signing in again to the same account; signing in with another address does not send them.
Reason
On a shared phone, one person's saves must not end up in another person's account.
User's side
The changes are not lost because the sign-in period ended.
What the visitor can do next
Sign in again with the same email address.
O5

Signing out with changes not yet sent

Shown
A dialog, "Sign out?": "Nocturne: Palaces has not been added to your account yet. It will be added when you are back online. If you sign out now, it will be removed from this device, together with your other saved works and visits." Buttons: "Stay signed in" and "Sign out and remove it".
Behaviour
Saves and removals both count as changes, and the message changes with them. Staying signed in is the main action. Signing out removes the account's data and the waiting changes from the device.
Reason
Signing out must leave nothing behind on a shared device, but a change the visitor made should not disappear without warning.
User's side
The visitor decides knowing what will be lost.
What the visitor can do next
Stay signed in until back online, or sign out and let the change go.
O6

Changing the visit date without a connection

Shown
"Changing the date needs a connection", with the reason. The date field and the button are unavailable.
Behaviour
The visit stays as it is. With a connection, waiting changes for the visit are sent first, and then the date is changed.
Reason
The preview of that day's displays, and the check for another visit on that day, need the server.
User's side
The page explains why, so it does not read as a fault, and says that the visit and its saved works stay as they are.
What the visitor can do next
Change the date later, with a connection.

TThings that change over time

Exhibitions end, displays change and loans have terms. These cases keep each visit as it was, and say why when something can no longer be shown.

5 cases
T1

The image period of a borrowed work ends

Shown
In the visit, an empty mat and "Image shown during the exhibition only". On the work: "The image of this work was shown during the exhibition only."
Behaviour
The server decides on each request whether the image may be shown. Images kept on the device carry the end of their period and are not shown after it, even offline; they are removed at the next connection. The title, caption, description, audio and transcript stay.
Reason
The loan agreement sets the period. Taking the work out of the visit would lose what the visitor saved; keeping the image would break the agreement.
User's side
An empty mat with a reason reads as the museum's terms, not as a fault or a lost save.
What the visitor can do next
Read about the work and listen to the audio.
T2

A work in copyright

Shown
During the exhibition: "This work is still in copyright, and the guide does not show an image of it." and "You can see it in Room 4, second floor." Afterwards, the first sentence only.
Behaviour
The mat stays, with the explanation. The work does not open the full-screen viewer.
Reason
The rights holder has not agreed to an image. Pointing to the room offers the work itself instead.
User's side
Visitors expect an image on every work; the sentence answers the question before it is asked.
What the visitor can do next
See the work in Room 4 during the exhibition, and read about it at any time.
T3

A past visit shows the display arrangement of its day

Shown
"Find other works from this visit" lists the rooms used on the visit date, identified by their corresponding section names and colours, "as the exhibition was arranged on the day of your visit". The list of works opened for a room says "As arranged on your visit, Tuesday 27 October 2026", and works saved in that visit are marked "Saved in this visit".
Behaviour
Published display versions are never changed; the visit date selects the valid versions for the exhibition and collection displays. On display, Number and Floor plan always show the current displays. Saving from a past visit adds the work to that visit.
Reason
People remember works by the room they saw them in. Later changes to the displays must not change a visit.
User's side
The two contexts look alike. The back link names the visit date and Saved stays selected, so the visitor knows which one they are in.
What the visitor can do next
Browse the works displayed in each room on that day, and save works missed then.
T4

A visit date when the saved works were not on display

Shown
"On this day" with the displays on the chosen date, and a warning that the saved works were not on display then. After the change, those works show "Not on display on this day".
Behaviour
The change is allowed, and the works stay in the visit.
Reason
Saved works are records the visitor took home, and the system does not remove them. If the exhibition data were wrong, blocking the change would leave no way to correct the visit.
User's side
The warning gives the visitor a chance to check the date, without deciding for them.
What the visitor can do next
Keep the date, or choose another.
T5

Two visits on the same day

Shown
"You already have a visit on this day", with the number of saved works in each visit and after combining, and "This cannot be undone." The button reads "Combine visits"; the link "Keep Wednesday 28 October 2026".
Behaviour
Waiting changes for the visit are sent first. The confirmation is tied to both visits as they were shown. If either changed in the meantime, nothing is combined, and the page shows the new numbers and asks again.
Reason
A visit is created on the day of its first save, so a work saved at home the next day from the current displays creates a second visit. Saving from a past visit adds to that visit instead. Combining cannot be undone, so the visitor sees exactly what will happen.
User's side
The page explains why the dates differ, so the visitor understands where the second visit came from.
What the visitor can do next
Combine the visits, or keep the date.

Languages and accessibility

A museum guide is read by visitors from many places, in a dark room, with one hand, sometimes with a screen reader. These rules apply across every page.

Languages

  • The guide opens in the device's language when it is one of the eight, and otherwise in English. Language can be changed from the Menu on any page; the Language row has a globe icon, which works without reading.
  • Each language is listed by its own name. For languages where some descriptions are only in English, the note in the list is written in that language, because it is for people who read it.
  • A field that is not translated is shown in English, with a grey notice in the interface language: in the Italian guide, "Questa descrizione è disponibile solo in inglese." The audio length reads "In inglese, 2 min 20 s", so the visitor knows before pressing play.
  • Text in another language than the interface carries its own language code, so screen readers pronounce it correctly.
  • Numbers, dates and floors follow the language: "81,6 × 93 cm" in Italian, and the second floor is "3階" in Japanese, because floors are stored as levels and named per language.
  • In Japanese, sentences are written in positive form, the ownership line follows Japanese label practice ("〜蔵"), and titles and artist names break between phrases, never in the middle of a word or a name.

Accessibility

  • State is never shown by colour alone. Section colours always come with the section name; errors use an icon and text as well as colour.
  • Every audio track has a transcript. Once opened, it stays open on that device for every work.
  • No page changes on its own: a complete label number does not open the work. Changes in a list, such as the number of matching works, are announced politely while focus stays in the field.
  • The floor plan is backed by a list of rooms with the same information.
  • Zooming in the image viewer works with single taps as well as two fingers.
  • Dialogs move focus to their heading and keep it inside while open. Closing without a change returns focus to the button that opened the dialog; after signing out, focus moves to the heading of the page that follows, "Saved works". Back to top moves focus to the first heading.
  • Text size follows the browser's zoom, and layouts hold at larger sizes.
  • Dark mode follows the device setting, with its own colour values checked for contrast.

The guide does not use location, so it cannot know whether the visitor is in the dark Room 5, which houses the Night section, or at home. Dark mode therefore follows the device, and nothing on the page changes by room.

User's side
A visitor who reads Italian should not discover halfway through a long English text, or after pressing play, that it is not in their language. Saying so before the text and on the play button respects their time.

API contract

The seven endpoints below are a draft contract, limited to what the screens need. Museum content (displays and works) is the same for every visitor and comes from /api/museums and /api/works. Visits and saves belong to the account and come from /api/me.

The front end first sets out what data each screen needs and when. The back end proposes what it can return, and the front end decides how to handle it. Each endpoint records that exchange.

Whether an image may be shown is decided by the server at the time of the request; the screen receives "shown" or "not shown" with a reason and the end of the period, and chooses the wording. Loan terms and copyright stay on the server, so a change to a loan does not need a new release of the guide. Text that is not translated comes back in English with its own language, dates are calendar dates in the museum's time zone, and times are UTC.

1What the front end asked for

2What the back end proposed

3What was decided

1. Get the displays on a date

GET /api/museums/northlight/displays?date=2026-10-27&lang=en
1

The start screen, works list, label number search, floor plan, the works list from a visit and the date preview all need the displays on one date, today or in the past, in the same shape. Label number search should work offline, so the whole list is needed at once.

2

Display versions are never changed once published, so the display arrangement on a date is fixed. Image state depends on the time of the request. A museum has a few dozen works on display, so one response stays small.

3

One endpoint with a date. date selects the display arrangement; image state is decided at the time of the request. The response can be cached, but never beyond the earliest shownUntil in it.

Response format
{
  "date": "2026-10-27",
  "floors": [{ "level": 2, "name": "Second floor", "short": "2" }],
  "displays": [
    {
      "type": "exhibition",
      "id": "under-changing-skies",
      "title": { "text": "Under Changing Skies", "lang": "en" },
      "from": "2026-09-12",
      "to": "2027-01-10",
      "rooms": [
        {
          "room": 1, "section": "dawn", "sectionName": "Dawn", "level": 2,
          "works": [
            {
              "workId": "w_monet_1897",
              "labelNumber": "105",
              "title": { "text": "Morning on the Seine near Giverny", "lang": "en" },
              "artist": "Claude Monet",
              "image": { "state": "shown", "thumbnail": "https://…", "shownUntil": "2027-01-10T23:00:00Z" }
            }
          ]
        }
      ]
    },
    { "type": "collection", "id": "prints-and-drawings", "rooms": [] }
  ]
}

After loading today's displays, the guide fetches the detail (2) and the reduced image of each work in the background. Offline use covers what has finished loading. Audio is not fetched in advance, and neither are the displays of past visits.

image.state is shown or not_shown. When not shown, reason is copyright, loan_period_ended or artist_wish, and the screen chooses the wording from it.

Label number search runs on this response on the device, so it works offline and needs no endpoint of its own.

A display version records the arrangement of an exhibition or collection display for a defined period: its works, room assignments, label numbers and order.

In each room entry, room is the physical room number, section is the thematic section identifier, sectionName is its display name, and level is the floor level. The name field on a floor entry remains the floor name.

2. Get a work

GET /api/works/w_monet_1897?lang=it&date=2026-10-27
1

Caption, description, audio, transcript and image, and where the work was on a given date. The Italian guide must know which fields are only in English. A saved work must still open after its visit date was changed to a day when it was not on display.

2

Text is stored per field and language; the placement comes from the display version valid on the date.

3

Every text field carries its lang. placement is null when the work was not on display on that date; the work's own information is still returned.

Response format
{
  "workId": "w_monet_1897",
  "title": { "text": "Mattino sulla Senna vicino a Giverny", "lang": "it" },
  "artist": "Claude Monet",
  "date": "1897",
  "medium": { "text": "Olio su tela", "lang": "it" },
  "dimensions": { "heightCm": 81.6, "widthCm": 93 },
  "credit": { "type": "loan", "text": "…", "lang": "it" },
  "placement": { "labelNumber": "105", "room": 1, "section": "dawn", "level": 2 },
  "image": { "state": "shown", "url": "https://…", "zoomUrl": "https://…", "shownUntil": "2027-01-10T23:00:00Z" },
  "description": { "text": "…", "lang": "en" },
  "audio": { "title": { "text": "…", "lang": "en" }, "url": "https://…", "seconds": 140 },
  "transcript": { "text": "…", "lang": "en" }
}

Dimensions are numbers; the screen formats them for the language (81,6 × 93 cm in Italian).

When placement is null, a visit shows the work as "Not on display on this day".

3. Send a code

POST /api/auth/codes

{ "email": "name@example.com" }
1

The same steps for new and returning visitors, without revealing whether an address has used the guide. When the hourly limit is reached, the screen must show when the next code can be requested.

2

A code can be sent to any address, and requests can be counted per address.

3

Always the same 202, whatever the address. Only the limit returns 429, with retryAt. A new code makes earlier codes invalid.

Response formats

202 — Sent

{ "result": "sent", "expiresAt": "2026-10-27T14:20:00Z" }

429 — Limit reached

{ "result": "rejected", "code": "CODE_LIMIT_REACHED", "retryAt": "2026-10-27T14:42:00Z" }

The screen shows retryAt in local time ("Try again at 15:42").

The news checkbox is not sent here; see 4.

4. Confirm the code, sign in and carry over saves

POST /api/auth/codes/verify

{
  "requestId": "c3a1…",
  "email": "name@example.com",
  "code": "482915",
  "news": false,
  "carryOver": [
    { "visitId": "v_7f3a", "museumId": "northlight", "date": "2026-10-27",
      "workIds": ["w_monet_1897", "w_hiroshige_1856", "w_whistler_1880"] }
  ]
}
1

After the code, the completion page has three cases. Works saved on the device must reach the account without being lost or added twice, also when the response never arrives.

2

Signing in and carrying over can run in one transaction, and the result of a request can be kept for the life of the code.

3

One request does both, so there is never a state where the visitor is signed in but the works were not carried over, and one response decides the completion page. The device creates requestId when the code is entered and reuses it when sending again. Within the code's 10 minutes, the same address, code and requestId return the first result without adding anything twice. The device keeps its saves until it has the response.

Response formats

200 — Signed in

{
  "result": "signed_in",
  "account": "existing",
  "carriedOver": 3,
  "visits": [{ "deviceVisitId": "v_7f3a", "visitId": "v_2c91", "combinedWithExisting": true }],
  "savedCount": 5
}

422 — Code does not match

{ "result": "rejected", "code": "CODE_MISMATCH", "attemptsLeft": 3 }

410 — Code expired, or replaced by a newer code

{ "result": "rejected", "code": "CODE_EXPIRED" }
{ "result": "rejected", "code": "CODE_REPLACED" }

429 — Too many attempts

{ "result": "rejected", "code": "TOO_MANY_ATTEMPTS" }

Completion page: account "new" leads to "Your saved works are kept", "existing" to "Welcome back", and combinedWithExisting true to works added to the existing visit of that day.

Only additions are carried over: the works currently saved on the device.

news true is recorded only here, after the address is confirmed, so nobody can subscribe another person's address. false never withdraws earlier consent. The checkbox stays on the email page; the device keeps its value until this request.

When no answer arrives, the code stays in the field and the page says the guide did not get an answer. Sending again uses the same requestId.

How the session is set (for example a secure cookie) is left to engineering.

5. Get visits

GET /api/me/visits?lang=en
1

For the visits list and visit detail: each visit's date, the displays on that day, the saved works with their image state, the count per visit, and the total for the navigation.

2

All visits can be returned with their works; a visitor has few visits.

3

One response serves the list and the detail. The rooms for "Find other works from this visit" come from 1 with the visit date.

Response format
{
  "savedCount": 5,
  "visits": [
    {
      "visitId": "v_2c91",
      "museumId": "northlight",
      "date": "2026-10-27",
      "displays": [{ "id": "under-changing-skies", "title": { "text": "Under Changing Skies", "lang": "en" }, "ended": true }],
      "works": [
        {
          "workId": "w_monet_1897",
          "displayId": "under-changing-skies",
          "onDisplayThatDay": true,
          "title": { "text": "Morning on the Seine near Giverny", "lang": "en" },
          "artist": "Claude Monet",
          "section": "dawn",
          "image": { "state": "not_shown", "reason": "loan_period_ended" }
        }
      ]
    }
  ]
}

onDisplayThatDay false shows "Not on display on this day" after a date change.

Works not yet sent are added by the device from its waiting changes, with "Not yet added to your account".

6. Send saves and removals

POST /api/me/operations

{
  "deviceId": "d_91c2",
  "operations": [
    {
      "opId": "5b0e…",
      "seq": 41,
      "createdAt": "2026-10-27T11:02:10Z",
      "action": "save",
      "workId": "w_whistler_1880",
      "visit": { "id": "v_7f3a", "museumId": "northlight", "date": "2026-10-27" }
    }
  ]
}
1

Saves and removals made offline must reach the account in the order they were made, never twice, and never undo a newer change. A visit can be created offline by its first save.

2

Every applied operation id can be recorded, and each saved state can keep the device, sequence number and time of the change that set it.

3

Operations are sent in batches. Within one device, operations are applied in seq order. Between devices, the later createdAt wins, with the device id as a tie-break. The device creates visit ids; if the account already has a visit for that museum and date, the server combines them and returns the id that remains. Each result also returns the work's saved state on the server after the batch, so the device can align what it shows.

Response formats

200 — Result per operation, with the state on the server

{
  "results": [
    { "opId": "5b0e…", "status": "applied", "visitId": "v_2c91", "workId": "w_whistler_1880", "saved": true },
    { "opId": "9d4a…", "status": "duplicate", "visitId": "v_2c91", "workId": "w_hiroshige_1856", "saved": true },
    { "opId": "e71f…", "status": "superseded", "visitId": "v_2c91", "workId": "w_monet_1897", "saved": false }
  ],
  "savedCount": 4
}

401 — Session expired

{ "result": "rejected", "code": "SESSION_EXPIRED" }

The device sets its stored state for each work to saved from the response and replaces device visit ids with the visitId that remains. It then applies again the operations it has not sent yet, or sent in a request still waiting for an answer, so actions made while the request was in transit are kept.

duplicate: already applied. superseded: a newer change from the same device or another device already set the state, and the work then shows as the server has it (for example, removed later on another device). Neither is an error, and no message is shown.

On 401, the device keeps the operations and sends them after signing in again to the same account.

7. Change a visit date

PATCH /api/me/visits/v_7f3a

{ "date": "2026-10-27" }

// After the visitor confirms the combine page
{ "date": "2026-10-27", "combine": { "confirmToken": "k8q2…" } }
1

A confirmation with the counts before two visits are combined, and never a combination the visitor did not see, even if another device changes either visit in the meantime.

2

Each visit has a version that changes with every change to the visit or its saved works. The server can check both visits at the moment of the change and combine them in one transaction, with the removed visit pointing to the remaining one.

3

The device first sends waiting changes for this visit (6). A change that would combine visits returns 409 with the counts and a confirmToken tied to both visits as they were. The combine page sends that token back. If either visit changed in between, nothing is combined: the server returns the new counts and a new token, and the page asks again.

Response formats

200 — Date changed

{ "result": "changed", "visitId": "v_7f3a", "date": "2026-10-26" }

200 — Combined

{ "result": "combined", "visitId": "v_2c91", "savedCount": 5 }

409 — Another visit exists on that date

{ "result": "conflict", "code": "COMBINE_REQUIRED", "existingVisitId": "v_2c91",
  "savedInThisVisit": 2, "savedInExisting": 3, "afterCombining": 5, "confirmToken": "k8q2…" }

409 — A visit changed after the combine page opened

{ "result": "conflict", "code": "COMBINE_CHANGED", "existingVisitId": "v_2c91",
  "savedInThisVisit": 2, "savedInExisting": 4, "afterCombining": 6, "confirmToken": "p3w7…" }

422 — Date in the future

{ "result": "rejected", "code": "DATE_IN_FUTURE" }

The "On this day" preview uses 1 for the chosen date and compares it with the works of this visit, so it needs no endpoint of its own. The server makes the final decision about combining.

On COMBINE_CHANGED, the combine page shows the new numbers with a short note that the visits changed since the page opened, and asks again. Nothing is combined until the visitor confirms what is on the screen.

Signing out

Signing out uses the standard function of the authentication service, so it has no endpoint of its own. The contract defines what happens around it:

  • On the device, the account's data, waiting changes and the session are removed at once, with or without a connection, after the check for unsent changes.
  • With a connection, the session on the server is ended as well.
  • Without a connection, the session can no longer be used from this device, because the device no longer holds it. On the server it ends with its own expiry.

What the specification leaves to engineers

This specification decides what the visitor sees in each state, which data is treated as correct, when an image may be shown, in what order saves and removals take effect, when waiting changes are sent and that retries wait longer each time, that the device keeps them in IndexedDB, and what the messages say.

How it is built is up to the engineers: how the guide is cached for offline use, the exact retry intervals, how the data in IndexedDB is organised, how the session is kept, which tool breaks Japanese text into phrases, and how components and state are organised.

Offline saving and syncing are often settled late, in the code, and then reach the screen as states no one designed. Agreeing first on the order of changes, what the visitor sees while a change waits, and which result wins lets engineers choose how to build behaviour that is already defined.

About this sample

The screens are designed in Figma: 44 screens in seven sections, a bottom navigation component, and colour variables with a light and a dark mode. English and Japanese each have their own typefaces and text styles, with more line space for Japanese body text.

The colours and type are set for this subject: works on paper, north light, and the sky at different times of day. The one strong element is the colour of each thematic section; everything else stays quiet.

The artworks are real works from public collections, shown with open-access images. The credits are below.

Image credits (23 works)
  • Utagawa Hiroshige, Dawn at Kanda Myōjin Shrine, 1857

    Art Institute of Chicago, 1939.1396. Frederick W. Gookin Collection. CC0

  • Camille Pissarro, The Garden of the Tuileries on a Spring Morning, 1899

    The Metropolitan Museum of Art, 1992.103.3. Gift of Mr. and Mrs. Douglas Dillon, 1992. CC0

  • J. M. W. Turner, Fluelen: Morning (Looking towards the Lake), 1845

    Yale Center for British Art, B1977.14.4715. Paul Mellon Collection. Public domain

  • Samuel Palmer, The Early Ploughman, 1861 or before

    National Gallery of Art, Washington, 1991.150.98. Courtesy National Gallery of Art, Washington

  • Claude Monet, Morning on the Seine near Giverny, 1897

    The Metropolitan Museum of Art, 56.135.4. Bequest of Julia W. Emmons, 1956. CC0 (file provided by the Met on Wikimedia Commons)

  • David Cox, Beach Scene – Sunrise, about 1820

    Yale Center for British Art, B1975.4.192. Paul Mellon Collection. Public domain

  • Utagawa Hiroshige, Mishima: Morning Mist, about 1833

    RISD Museum, 13.1057. Courtesy of the RISD Museum, Providence, RI. CC0

  • Attributed to Thomas Lindsay, Sky Study, No. 4

    Yale Center for British Art, B1975.4.65. Paul Mellon Collection. Public domain

  • Winslow Homer, Native hut at Nassau, 1885

    National Gallery of Art, Washington, 1994.59.20. Courtesy National Gallery of Art, Washington

  • Pierre-Henri de Valenciennes, Study of Clouds over the Roman Campagna, about 1782–1785

    National Gallery of Art, Washington, 1997.23.1. Courtesy National Gallery of Art, Washington

  • John Constable, Cloud Study, 1821

    Yale Center for British Art, B1981.25.156. Paul Mellon Collection. Public domain

  • Jacob van Ruisdael, View of Haarlem from the Northwest, with the Bleaching Fields in the Foreground

    Rijksmuseum, SK-A-351. Rijksmuseum, Amsterdam. Public domain

  • Eugène Boudin, Figures on the Beach, about 1867–1870

    National Gallery of Art, Washington, 1983.1.12. Courtesy National Gallery of Art, Washington

  • Utagawa Hiroshige, Yatsumi Bridge, 1856

    Art Institute of Chicago, 1925.3741. Clarence Buckingham Collection. CC0

  • Aelbert Cuyp, A Pier Overlooking Dordrecht, early 1640s

    National Gallery of Art, Washington, 2012.73.1. Courtesy National Gallery of Art, Washington

  • Utagawa Hiroshige, Sudden Shower over Shin Ohashi Bridge and Atake, 1857

    Art Institute of Chicago, 1925.3742. Clarence Buckingham Collection. CC0

  • Rembrandt van Rijn, The Three Trees, 1643

    National Gallery of Art, Washington, 1955.6.10. Courtesy National Gallery of Art, Washington

  • John Constable, A Cloud Study, Sunset, about 1821

    Yale Center for British Art, B1981.25.128. Paul Mellon Collection. Public domain

  • James McNeill Whistler, Nocturne: Palaces, 1879–1880

    RISD Museum, 84.198.24. Courtesy of the RISD Museum, Providence, RI. CC0

  • Utagawa Hiroshige, Fireworks at Ryōgoku Bridge, 1858

    The Metropolitan Museum of Art, JP642. Purchase, Joseph Pulitzer Bequest, 1918. CC0

  • Charles-François Daubigny, The Boat in Conflans, 1866

    The Cleveland Museum of Art, 1920.666. Gift of Ralph King, the Frederick Keppel Memorial. CC0

  • James McNeill Whistler, Black Lion Wharf, 1859

    National Gallery of Art, Washington, 1943.3.9104. Courtesy National Gallery of Art, Washington

  • Utagawa Hiroshige, The Plum Garden at Kameido (Famous Places in the Eastern Capital), about 1832–1838

    Art Institute of Chicago, 1925.3462. Clarence Buckingham Collection. CC0

See the design

Used on this page

React / TypeScript / Next.js / Tailwind CSS

Used for the design

Figma (variables with light and dark modes, components)