Choosing how a surface looks
In the portal: Settings, then Surfaces.
What this page is for
The previous page gives you a playground: move one control, watch the surface redraw. That answers "what does this setting do".
Most people arrive with the opposite question. They have a picture in their head of how they want the screen to feel, and they need to know which settings get them there. This page answers that one. It shows ten surfaces. Every one holds the same three items, and the settings that produced each are printed underneath.
Find the one that looks like what you want. Then type its values into yours.
Reading it
Start from the shape, not from the settings. A list and a shelf are the first choice, and everything else is detail. A list is for things that need reading down. A shelf is for things you browse across, and the half card at the right edge is what tells a participant there is more.
A picture costs height. A list with the picture on the left fits three items on screen. The same list with the picture above fits one and a half. This is the choice people get wrong most often. The picture-led look is the one people like when they see it, and it is the one that puts the fewest items in front of a participant.
The three you will actually decide
Ten looks is more than anyone needs. In practice three settings do most of the work.
| Decision | The setting | What tips it |
|---|---|---|
| List or shelf | maxRows, shown as Rows in the picture | 0 is a list, for reading down. 1 to 4 is a shelf, for browsing across. |
| Where the picture sits | imagePosition, shown as Picture | Left is compact and gets three items on screen. Top and background are stronger and cost height. You cannot turn the picture off here, because whether an item has one is decided by the content. |
| Whether a tick shows | showCompletionState, shown as Show completion | On for things a participant does. Off for things they read, because a tick on an article implies homework. |
imagePosition takes left, right, top or background, and nothing else.
What to do next
Change one setting at a time and look at the result on a real phone. Two of them catch
people out. showCompletionState decides whether an item reads as a task or as
something on offer. imagePosition decides how much of the screen the surface takes
up.
The seven surfaces every tenancy starts with are on The seven standard surfaces, and complete home screens built out of several surfaces are on Home architectures.