Diamond Stone Platform: Design

Scope note (11 November 2026): this document governs the staff app (and the driver's and logistics company's screens). The public website and the client portal have their own look, set out in docs/SITE-DESIGN.md. They share the brand (logo, colours, typefaces, words) but not the shell, glass, cards or pills.

Date: 2026-11-11. Revision 8. Status: draft for owner review. Companion to docs/PLAN.md and docs/SCREENS.md.

Revision 8: the Halo is one band at the very top of the screen, above the title; the drawer is that band grown downward; pulling the band down shows everything (section 7).

Revision 7: proportion and grouping fixed after the screens looked stretched; laws of UX applied; each screen reviewed (section 4, "Proportion and grouping").

Revision 6: every element made smaller, with two size sets and the pixel facts behind them (section 4, "Sizes"). Each role's screens are in docs/ROLES.md.

Revision 5: logo, colours, typefaces and wording now come from docs/BRAND.md, which takes precedence over sections 3, 5 and 12 here: Orbitron and Rajdhani replace Inter and Instrument Serif; teal #008A8A and graphite #525862 replace the earlier accent.

Revision 4: Halo on every signed-in screen, the drawer grows from its ring (section 7); the mistakes AI-designed interfaces make and the guard against each (section 15).

Revision 3: rules for condensing every screen (section 10): picture before shape before icon before words, three text levels, no question headings, a word budget per screen.

Revision 2: Halo, Halo drawer, Stream and Omnibar restored as one shell on every screen; cards designed from the person's question.

This document sets how the app looks, reads, moves and is checked. It is built on six research passes: Apple's Liquid Glass, the full Apple Human Interface Guidelines, published evidence on interface quality, evidence on visual-first design, typography and viewing research, and the earlier DiyaOS design work. Sources are listed in section 19.

A live sketch of everything here is in docs/ui-shell-mockup.html.

1. Basis

What the evidence says, in five lines

1. Simple and familiar wins. People judge a screen in a fraction of a second, and screens that are visually simple and conventionally laid out are rated far higher. Novelty belongs in the stone photography, colour and type, not in navigation, forms or tables.
2. Visual plus a few words, not visual instead of words. Icons with a short label, charts with a one-sentence headline, and exact figures for money are the forms that work. Lone icons, decoration and animated data are where visuals hurt.
3. Navigation must be visible. In one study, hidden navigation was used 57% of the time against 86% when visible, and tasks were slower.
4. Good looks buy patience, not usability. Polish matters most on the public site and a customer's first visit. For staff using it all day, speed and clarity come first.
5. Much popular design advice has no evidence behind it (thumb-zone maps, the 60-30-10 colour rule, the golden ratio). It is not used here as a rule.

The design language

The app follows the ideas behind Apple's Liquid Glass. Most of them are layout and behaviour rules that work on any phone, whatever the surface looks like:

1. Two layers: content underneath, a thin floating layer of controls above it.
2. Glass belongs only to the floating layer. Never in content, never glass on glass.
3. Content runs edge to edge beneath the controls and fades softly under them; no solid bars.
4. Controls are capsules. Nested shapes share a centre: inner radius = outer radius minus padding.
5. One tinted primary action per screen; every other control is neutral.
6. Colour lives in the content, not the controls.
7. Things open from their source: a sheet or menu grows out of the button that opened it.
8. Controls come alive only while touched.
9. Things appear by forming (scale and opacity together), not by a plain fade, and change state by morphing rather than cutting.
10. Titles are bold and start-aligned.
11. The person stays in charge of the effect: a solid option is always available.

What is not taken from Apple: the name "Liquid Glass", the San Francisco font, SF Symbols icons, and any Apple artwork. Those are licensed for Apple platforms only.

2. How people hold and see the phone

3. Type

Fonts

All three are open-licence. Samsung phones would otherwise fall back to Roboto.

Scale

• Three weights only: 400, 500, 600. Nothing lighter.
• Floors: 12 px (13 in Arabic). Anything needed to do the job is 14 px or more. Money is 16 px or more.
• Sizes are relative to the phone's text setting and survive 200% enlargement.

Numbers and money

• One format everywhere: 1,250.500 OMR, with the currency code smaller and muted.
• Other currencies use their own decimals: 3,250.00 USD. Every amount carries its code; staff see the rial value beneath a foreign amount, customers see only their own currency, and different currencies are never added (docs/CURRENCY.md section 9).
• Three decimals for OMR, always. Aligned figures, end-aligned in columns.
• Negatives use a true minus sign and colour together, never colour alone.
• Western digits (0 to 9) in every language. Left to its default, the Arabic setting for Oman produces Arabic-Indic digits, which would mix two systems across screens (decision 2).
• Amounts are never shortened with "…" and never rounded on ledgers, invoices or payslips.

Arabic

No letter spacing, no italics, no capitals; emphasis by weight 600 or colour. Numbers, record numbers and amounts stay left-to-right inside Arabic text.

Loading

Fonts are served from our own address and cached on the phone. Budget: 48 KB for English, 91 KB for Arabic, 21 KB more for the display face. Text shows at once in a matching fallback so nothing jumps when the font arrives.

4. Layout

Screen budget

Fixed controls never take more than a quarter of the screen. With the keyboard open the Omnibar hides, and the field, its label, any error and the action stay visible.

Sizes (revision 6: everything was too large)

The owner found every element oversized. Measuring the sketch confirmed it: avatars and icon circles were 52 px, list rows about 80 px, cards had 20 to 22 px corners with 16 px padding, and the fixed bars (status bar, top bar, Halo, Omnibar) took about a third of a record screen. The text sizes were roughly right; the containers were not.

Two separate causes.

1. The elements really were too big. Business apps used all day run denser than consumer apps. Design systems that publish both sets (SAP Fiori "cozy" and "compact", IBM Carbon, Salesforce) keep the text the same and shrink the controls and spacing.
2. A phone sketch on a monitor looks 30 to 50 % bigger than the phone. The Galaxy S25 packs about 139 CSS pixels into an inch; a monitor shows about 92 to 109. A 360 px frame is 66 mm wide on the S25 and 84 to 100 mm on a monitor. The sketch now has a True size control: hold the phone against the screen and adjust until the frames match. Sizes are judged on the phone or in True size, never at 100 % on a monitor.

The touch area and the visible element are different things. A finger needs about 9 mm (48 px). The thing drawn can be much smaller, with invisible padding making up the touch area. Google's own guidance draws a 24 px icon inside a 48 px target. The earlier sketch made the drawn element as big as the touch area; that is what made it look heavy.

Pixel facts for the two phones

If the A55 is 412 wide, everything is about 7 % physically smaller on it than on the S25, so the comfortable set is checked on the A55 first.

Two size sets, one design. Office roles get Compact. Roles that work standing, outdoors or with gloves (warehouse, drivers) get Comfortable. Any user can switch in Me → Appearance. Text size follows the phone's own font-size setting in both.

Rules

• Drawn size and touch area are set separately on every control. A test measures the touch area (section 15, row 6), not the drawing.
• Corners of 16 or less. Bigger corners force bigger padding to clear them, which is where much of the bulk came from.
• Fixed bars take at most 22 % of a record screen and 28 % of Home (Home carries the full Halo). On the S25 in Compact: status 30, top bar 48, compact Halo 32, Omnibar 56 with its margin.
• A record screen shows its picture, its figures and at least three reveal rows without scrolling. A list shows at least seven two-line rows.
• Rajdhani is narrow rather than small: its letters are about 7 % shorter than Inter's but 15 % narrower. One pixel more than an Inter size matches it. Nothing that must be read is under 13 px; 12 px only for one- or two-word captions.
• Orbitron is about a third wider than Rajdhani, so in the staff app it is used for the wordmark only. Screen titles are Rajdhani, bold, at 15 to 16 px.
• Space freed by smaller elements is used for content the person needs, not left empty and not filled with decoration.

What the change did in the sketch: content on a record screen starts 121 px from the top instead of 153; the order record shows four more rows; the owner's Home shows cash, receivables and payables, four promise rings and the month's figures above the first order card.

Not established: no published measurements were found for well-known apps' row heights; the claim that large elements "look cheap" is practitioner opinion, not a study. The size sets must be confirmed with the staff on their own phones (section 16).

Sources: Android accessibility guidance on touch targets (support.google.com/accessibility/android/answer/7101858); WCAG 2.2 target size (w3.org/WAI/WCAG22/Understanding/target-size-minimum); Nielsen Norman Group on touch targets and on content against chrome (nngroup.com/articles/touch-target-size, nngroup.com/articles/mobile-ux); Parhi, Karlson and Bederson 2006 on thumb targets; Material density (m2.material.io/blog/material-density-web); IBM Carbon button sizes; SAP Fiori cozy and compact; font metrics from the Capsize collection; Legge and Bigelow 2011 on legible letter size; device figures from yesviz.com.

Proportion and grouping (revision 7: everything looked stretched)

After the sizes were reduced the owner found the screens stretched and unfriendly. The elements had shrunk but were still laid out for the full width, so small things floated far apart. Each screen was inspected at full size and judged as a layout designer, a typographer and an interface designer would. What was wrong, the principle it breaks and the fix:

Layout rules added

1. Space inside a group is at most half the space between groups: 2 to 4 px label to value, 8 px related items, 10 to 12 px between groups in a surface, 16 px or more between surfaces.
2. One left edge per surface. Nothing is centred except a single icon in a circle, an empty state, or a sign-in screen.
3. Left and right ends of a row are used only when the right-hand item is a number column, a status or a chevron.
4. A control is as wide as its content. One full-width button per screen at most: the Omnibar action.
5. A list of like things is a list: one surface, hairlines, no gaps. A card is for a single subject, and never sits inside another card.
6. At most two levels: the page, and a surface on it.
7. Content starts at the top. Space left at the bottom stays empty; nothing is stretched to fill it.
8. The squint test: with eyes half closed, a screen shows three or four groups, not a ladder of equal boxes.

The laws of UX, as applied here

Evidence is strong for Fitts, proximity, similarity, common region, Von Restorff and serial position. Hick, Jakob, Tesler, Occam and Pareto are working rules of thumb rather than measured laws.

Typeface decision (owner, 11 November 2026): keep Rajdhani for all text. Both brand typefaces were designed as display faces, and a separate text face for small labels and data was offered and declined. Rajdhani therefore carries body, labels and tables. Because it was not drawn for small sizes: nothing that must be read is under 13 px, captions use weight 500, and its legibility in long tables and outdoors on the A55 is a named check in section 16.

Each screen, reviewed

Still weak, not yet fixed: many screens are short and leave the lower half empty, which is correct but shows there is room for the next most useful content on several (for example recent activity on a customer). The sign-in and help screens have had the least design attention. Dark mode, Arabic and the A55 have still not been reviewed.

Sources: lawsofux.com; Nielsen Norman Group on proximity, common region, form spacing, cards, the F-pattern and layer-cake scanning (nngroup.com/articles/gestalt-proximity, /common-region, /form-design-white-space, /cards-component); Richard Rutter on table typography (alistapart.com/article/web-typography-tables); Refactoring UI, "Labels are a last resort"; Butterick's Practical Typography on letterspacing, figures and line length; Steven Hoober on how people hold phones (uxmatters.com, 2013 and 2017); the Orbitron and Rajdhani project descriptions (github.com/theleagueof/orbitron, github.com/itfoundry/rajdhani).

Cards and images

• A card holds at most three lines of text, one line of detail, one main figure and one action.
• Stone photographs: 3:2 for a full slab, 1:1 for texture and list thumbnails, 4:5 for the public hero. Supplied at three sizes, sharp on a 3x screen, with space reserved so nothing jumps.

5. Colour

Ninety per cent neutral, one accent, four status colours. The stone photography carries the colour.

Rules:

• A calm screen shows no red, amber or badges. Colour appears only for exceptions.
• One meaning per colour. The accent never marks static text.
• Every status is colour plus a distinct icon shape plus a word.
• The app follows the phone's light or dark setting. There is no separate theme switch.
• Dark mode uses near-black, not pure black, which smears on these screens when scrolling.
• Contrast: 4.5:1 for text, 3:1 for icons and control edges, 7:1 for key figures and anything read outdoors.

6. Surfaces and glass

Where glass goes

Only on the floating layer: the Omnibar, sheet tops, and the Halo strip once content scrolls under it. Cards, lists, tables and forms are solid.

How it is drawn

Quality levels

Set per device by the test described in docs/PLAN.md section 7.

Layout, sizes and behaviour are identical at every level. The light-bending effect works only in Chrome-family browsers and has not been tested by anyone on Android phones, so it is verified on the real S25 before it is relied on.

7. Shell

One shell on every staff screen. (The website and the client portal have no Halo, Stream or Omnibar: docs/SITE-DESIGN.md section 13.) Halo at the top, Stream in the middle, Omnibar at the bottom. This is the owner's design from the DiyaOS work, kept consistent everywhere and slimmed to what a trading company needs. No screen builds its own header, footer or navigation.

The rule that ties them together: the top is for looking, the bottom is for doing. The Halo and its drawer never contain a form field or a signing step; they hand the action down to the Omnibar.

Replanned on 11 November 2026 in docs/SHELL.md (drawn in docs/shell-map.html): four kinds of ring; kept and live places; adding, removing and reordering by the person; putting off and handing over; nine Omnibar modes; and 44 problems with their answers. Where the text below differs, docs/SHELL.md is the plan.

Omnibar

One capsule, always in the same place, on every screen.

At rest it holds four things:

The original design had Add, Camera and Voice, with navigation inside the Add sheet. Two changes, both for evidence: navigation is made visible as the Place part, because hidden navigation is used far less; and Search replaces Voice, because voice is unreliable at yard noise levels. Voice notes on a record can be added later.

With a card selected or a record open, the same capsule becomes that item's action: a More button for secondary actions, and one accent button naming exactly what it does ("Approve 1,260.000"). Cards and records carry no action buttons of their own; choosing one arms the Omnibar.

After an action, the capsule shows the result and "Undo …" naming what it undoes. The card folds to a one-line receipt, and the next item waiting becomes current. Undo stays until the next action or until the person leaves; there is no countdown.

Rules:

• The main action is never destructive. Delete and cancel sit under More, in red, with a confirmation.
• Money, payroll and period-close actions ask for a fingerprint or PIN and are reversed by a new entry, not undone.
• Actions that are risky get a firmer step automatically: above the person's limit, below the margin floor, or a new bank account goes to approval instead of completing.
• The capsule rises above the keyboard, and never hides the form's own action.
• Settings, areas, add and search all open as sheets from the Omnibar, one at a time.

Halo

Where it sits (revision 8). The Halo is the first thing on the screen: one band fixed to the very top, reaching up under the status bar, with rounded lower corners and a small handle at its lower edge. The screen's title, and on Home the greeting, sit below it. Nothing is ever placed above the Halo. (Before this revision the title sat above it; the owner asked for the Halo to lead.)

The band has three positions, and it is the same surface in all three:

• Closing is the reverse: push the band up, tap the handle, tap the dimmed screen, or Back.
• Swiping sideways with a ring open moves to the next ring; the marker moves with it.
• Pulling down further from "one ring open" goes to "pulled down".
• While the band is open in either way, the content beneath steps back under a dim layer and cannot be tapped. The Omnibar stays usable.
• The pull starts on the band itself, below the phone's status bar. A swipe that starts at the very top edge of the glass still opens Android's notification shade, as it must. The two are told apart by where the finger lands; this is tried on the S25 and A55 before it is built, with one-handed use and with Samsung's own gesture settings. If they prove confusable, the handle and "+N" remain as the tap routes.

• Pulling the band is separate from pulling a list to refresh it: the band does not scroll with the content.

• Ring 1 is always "You". It is protected and cannot be removed. It opens your day: what is waiting, your quiet-hours switch, and the role you are viewing as.

• Then up to four rings for what most needs this person, and a "+N" ring when there are more. No sideways scrolling.
• Rings are grouped by customer, supplier or area, and ranked the same way every time: urgent first, then waiting on me, then deadline, then amount, then age.
• The strip is 76 px tall and shrinks to 46 px as the stream scrolls. (Sizes superseded by section 4, "Sizes".)
• A calm day shows "All caught up". That line appears only when the data is fresh.

Each ring has an icon or initials, a short word, and a spoken description. Level shows in the ring's shape as well as its colour.

Halo drawer

Tapping a ring opens the Halo drawer. It is not a card and it does not float. It is the Halo band itself, grown downward: the same fill, no gap, no border between band and drawer, and the rounded lower corners and handle move down to the drawer's lower edge. The open ring keeps its place and gains a ring of the action colour, with a small marker beneath it pointing into the drawer. The ring is the drawer's header, so the drawer does not repeat the face or icon.

• It is open or closed; there are no half positions. It grows to fit its content up to about 450 px, always leaving the Omnibar visible and usable.
• While it is open, only the Halo and the Omnibar stay sharp. The stream behind steps back under a solid dim layer and cannot be tapped.
• Close it with the close button, a swipe up, a tap on the dimmed stream, or Back. Opening the camera or any Omnibar sheet closes it; opening it closes any Omnibar sheet.
• Opening a ring to read it does nothing else. Nothing is armed until the main button is pressed.
• A step is marked done only when the server confirms it, and is unmarked if the action is undone.
• A ring that is fully done seals with a tick, closes up, and can be restored with Undo.

Pulled down, the band shows everything in three groups: what needs this person, what they are watching, and the Places their role has. It gives a second, visible route to every area. It opens by pulling the band or handle down, by tapping the handle, or by tapping "+N" (see "Where it sits" above for how this stays clear of Android's own pull-down).

Left out of the original: the jiggle (reordering itself is now planned, with a button for every move: docs/SHELL.md section 4), the broadcast composer, the industry-pack picker, prayer and driving modes, and blur behind the drawer.

Stream

The stream is the same component on every screen. It takes one of four forms:

• A feed card holds at most one headline, three lines, one main figure and four facts.
• A selected card gets an accent edge while the others dim slightly.
• Three to five cards are visible at once in a feed; a full record card takes more room and shows one and a half.

The shell on each kind of screen

The Halo is on every signed-in screen of the staff app, the driver and the logistics company. Drivers and carriers get a short Halo of two to five rings, each one a thing they can act on. Customers have no Halo (changed 11 November 2026): the client portal shows a line of words with counts and its own bar (docs/SITE-DESIGN.md section 13; docs/SHELL.md, "Customers"). To test with people (section 16): whether customers who visit rarely understand that line without help.

Consistency rules

• One shell component. Every screen is built inside it; none draws its own bars.
• One set of tokens for colour, type, spacing, corners and timing (sections 3 to 6 and 11).
• One card component per record type, used everywhere that record appears (docs/SCREENS.md).
• The same ring order, the same Omnibar positions and the same close gestures on every screen.
• Automatic checks on every build compare screenshots of each screen type against the shell.

Home by role

Heavy screens on a phone

8. Elements

Every screen is built from these and nothing else. The full plan, 96 components each with its parts, kinds, switchable features, states and movement, is in docs/COMPONENTS.md (drawn in docs/component-map.html); the list below is the summary it grew from.

9. Icons

• One open-licence outline set (Lucide) with about 20 custom icons drawn to match: slab, tile, sample box, lot, finishes, thickness, container, inspection. About 90 in all.
• One icon, one meaning. Icon positions never move, because people learn the place as much as the picture.
• Every icon that does something has a visible word, except Back, Close, Search and Add.
• Staff may switch labels off for themselves once they know the icons. The main action and all navigation keep their words regardless. Press and hold shows any icon's name.
• Customers always see the words.
• Sizes: 20 px in rows and chips, 24 px standard, 28 px in the Omnibar, 40 px in Halo rings, 64 px for empty states. One stroke weight, matched to the text.
• Every icon has a spoken name in English and Arabic. Arrows and anything showing direction mirror in Arabic; ticks, clocks, logos and photos do not.

Animated icons play once, on an event. Evidence says animation helps only for actions that are hard to picture, so the list is short:

Recognition test: each new icon is shown without its word to at least ten staff across the language groups, who say what it means in their own words. Under two-thirds correct, the word becomes permanent; the aim is 85%.

10. Showing information visually

Which visual for which information

On a 360 px screen:

Cards answer a person's question

Every card is designed from what the person looking at it needs to know, in the order they need it. This is checked for each card before it is built.

1. Write down who looks at the card and why.
2. List the questions they have, most important first.
3. Give each question the most direct visual answer: a face or logo for "who", the stone's photograph for "what", stage icons for "where is it", a date for "when", stars for a rating.
4. Put codes and record numbers last and small. Nobody thinks of a customer as "SO-0142".
5. Remove anything that answers no question.

The order card, as the worked example:

Rules that keep picture-led cards readable:

• Text never sits directly on a photograph. The photograph is a band across the top; words go on the solid surface below, and a chip on the photograph has its own solid background.
• A long list uses a compact form: a square stone thumbnail with the customer's circle on its corner, two lines of text, and the status.
• A card shows one customer circle, one photograph, one caption line of details and one next step.
• Stars are for a customer's rating only. Measured properties of a stone use the property scale.
• Each kind of record gets its own card designed this way: enquiry, quote, order, shipment, supplier order, invoice, payment, claim, sample, staff request.

Condensing: say it with the fewest words

The questions above are how a screen is designed. They are never printed on the screen. A screen that reads "Where is it? Now: Hatta border. Arrives: 14 Nov. Last seen: 12 min ago" has turned the method into text. The same answer is one route line with a truck on it.

Each piece of information takes the first form in this list that works:

1. A picture of the thing: stone photograph, face, logo, map, route line.
2. A shape that carries the value: ring, bar, stage dots, stars, calendar strip, scale marker.
3. An icon with a figure: a clock and "12 d", a truck and "14 Nov".
4. A figure with a caption of one or two words.
5. A sentence. Only for something a person wrote, or a decision that needs explaining.

Three levels of text, and no others, on any screen:

Rules:

• No section headings inside a record. The picture, icon or figure says what the block is.
• An icon replaces a label wherever the icon is in the tested set (section 9). The label stays as the accessible name and shows on long press.
• A caption is at most two words. "to pay", "days left", "on time". Never a sentence.
• A block of facts is one strip of up to three cells: a visual on top, a caption below. Never three stacked lines of "label: value".
• Movement between two places is a route line: start, end, a marker where it is now, arrival date at the end. Never separate "now", "arrives" and "last seen" tiles.
• Progress through steps is stage dots. A share of a whole is a ring or bar. A rating is stars. A date range is a calendar strip.
• Stone, finish, thickness and quantity are one caption line ("Honed · 20 mm · 86.4 m²"), not a row of tags.
• One status chip per screen, top right, icon and one or two words, coloured only when attention is needed.
• Everything else sits behind a reveal row: icon, one word, a one-figure summary, a chevron.
• The Omnibar action is a verb and at most one noun: "Approve", "Message Ahmed".
• Exact figures are never dropped to save space. Money always shows in full with its currency.
• If a first-time user cannot say what a visual means in three seconds, it gets its caption back. Condensing never beats being understood (tested in section 16).

Budget for one phone screen (360 × 780): at most one title, one status chip, one main picture, three strips or figures, four reveal rows and one main action. A record screen should come to about 40 words or fewer before anything is opened.

Before and after, from the shipment screen:

Chart rules

1. Compare with length and position (bars, dots). Never with area, angle or icon size.
2. Bars start at zero. No broken scales.
3. At most two lines per line chart and twelve bars per bar chart. Beyond that, small charts side by side, or a top list.
4. At most five colours in a chart, from a colour-blind-safe set, each also marked by shape or label.
5. Every chart has a one-sentence headline stating what it shows, and labels its key values directly. No separate legend for three series or fewer.
6. A small chart opens a larger one in the same style. Tapping is never required to see a critical figure.
7. Every chart has a text description and a "view as table" option.
8. Exact numbers sit beside charts on any money screen: the figure for reading, the bar for comparing.
9. Charts do not animate, except a single change being pointed out.
10. Labels inside charts are 12 px or more and are real text, never part of an image.

Stone and trade visuals

• The real photograph is the hero. Never a stock image. Dry and wet shots, a scale reference, zoom, and the note "Colours vary by screen; see the stone in daylight."
• No photo yet: a plain grey panel with a "Take photo" button.
• Lot card: photo, lot number, finish and thickness, quantity, where it is, hold status.
• Stone datasheet: each property (density, water absorption, strength, slip rating) as a property scale. This is the centre of the specifier pack.
• Container fill: a drawing of the container filling, with weight and floor-space bars that turn amber at 95% and stop at 100%.
• Margin light for sales staff: green, amber or red with a word ("Healthy", "Thin", "Needs approval"); no percentage shown.
• Held material: a full-width bar, "Held for Al Noor until 4 pm tomorrow."

11. Motion

How each movement is coded, the springs, and what each does to the person are in docs/FRONTEND.md, with live samples in docs/ui-build.html. An evaluation of this section found 26 gaps; the completed specification is docs/MOTION.md, and where it differs from the tables below, it is the plan (one set of times, curves and springs; distance and stagger tokens; interruption; drag numbers; a motion ladder; waiting; testing).

Principles

Motion explains what happened, never makes anyone wait, starts from its source, moves one thing at a time, and is still at rest.

Timing

Leaving is faster than arriving. Timing is in real time, so it is the same on a 60 Hz and a 120 Hz screen.

Small movements

Between screens

Customer moments

The range approved, the quote accepted, the layout approved, delivery confirmed. On staff screens each gets the stage tracker advancing and one tick, under 600 ms. No confetti, no sound. In the portal these moments follow docs/SITE-MOTION.md.

Rules

• Only position, scale and opacity are animated. Blur strength is never animated.
• First response to a touch within 100 ms.
• At most one looping animation on screen, and only while work is in progress.
• Direction mirrors in Arabic.
• Reduced motion: every movement becomes a 120 ms fade, no bounce, no forming effects.
• Every animation holds 60 frames a second on the Galaxy A55 5G, or it is simplified.

12. Words

• Plain, direct and brief. "You", never "the user". No jargon, no "oops".
• Buttons are verbs that say what happens: "Send quote", "Record payment". Never "OK" for a real action.
• Sentence case throughout.
• An error sits beside the problem and says how to fix it: "Enter an amount above zero."
• An empty screen says what to do next and offers the button.
• A confirmation names the thing and the amount: "Post invoice for 12,400.000 OMR?"
• Notifications never contain amounts or other confidential details.

13. Forms and money entry

1. One column. A label above every field, always visible.
2. Choose rather than type wherever possible. Pre-fill from the last record, the scan or the role.
3. The right keyboard for each field; amounts get the decimal keypad.
4. A field is checked when the person leaves it, never while they type. The error clears the moment it is fixed.
5. Entered amounts are echoed back formatted, with the currency.
6. Every posting has a review step showing formatted totals. The button disables after one tap.
7. Nothing is silently "corrected". A malformed entry is refused with a reason.
8. Ask permission for the camera, location or notifications only when first needed, with a one-sentence reason.

14. Behaviour

15. Quality bar

Every screen is checked against this before it is accepted.

Look and layout 1. One accent action, visually dominant. 2. One accent colour, neutrals, four status colours. Nothing else. 3. Only the corner and spacing values in section 4. 4. Glance test: a new person can name the screen's purpose and main action after five seconds. 5. Navigation, forms and lists follow the conventional pattern. 6. Fixed controls take no more than a quarter of the screen.

Type 7. Body 16 px; nothing under 12 px (13 in Arabic); money 16 px or more. 8. At most three weights; none lighter than 400. 9. Every amount uses the one format and is never cut short.

Colour and contrast 10. Text 4.5:1; icons and control edges 3:1; key figures 7:1. 11. Nothing is shown by colour alone. 12. Text on glass keeps its contrast over the brightest and darkest content.

Touch and navigation 13. Every target 48 px or more, 8 px apart; 56 px at edges. 14. Navigation is visible; every navigation icon has a word. 15. Every swipe or drag has a tap alternative. 16. A destructive action is never beside the main one. 17. Nothing tappable in the upper right edge strip.

Forms and money 18. One column; visible labels; the right keyboard. 19. Errors on leaving the field, saying how to fix it. 20. A review step before every posting. 21. Undo names what it undoes; a confirmation names the thing and amount. 22. Every record shows its status, who changed it last and when, and who acts next.

Visuals 23. Every action icon has a word, or has passed the recognition test. 24. Every chart has a headline, starts at zero, and has a text description. 25. Photographs are real, sharp and sized, with space reserved. 25a. The screen answers the person's questions in order; every figure opens what it is made of; other detail is one tap away.

States, motion, speed 26. Empty, loading, error and offline states are all designed. 27. Response within 100 ms; a progress indicator after 1 second. 28. Motion uses the five tokens and respects reduced motion. 29. On the Galaxy A55 5G: first screen in 2.5 seconds, 60 frames a second.

Two languages and access 30. Passes in Arabic: mirrored layout and arrows, numbers kept left-to-right, nothing clipped. 31. Works at 200% text and 320 px wide, with zoom allowed. 32. No automatic accessibility errors; every icon button has a spoken name.

Mistakes AI-designed interfaces make, and the guard against each

This app's screens are drawn and coded largely by AI models. Published evaluations and audits show the same faults again and again in such work. Each has a guard here that does not depend on the model's own opinion of its work. Evidence is strongest for accessibility, security and duplicated code (measured studies); the rest comes from practitioner reports that agree with each other.

What this means for the current sketch. docs/ui-shell-mockup.html was drawn by an AI model and has so far been checked only by that model, in light mode, in English, at Galaxy S25 size, with tidy sample data. By rows 7, 8, 9, 15 and 16 above it is a direction to react to, not an approved design. Still to do before any screen is built: the eight states, the stress content, dark mode, Arabic, the A55, and review by a person.

16. Testing with people

• Customers first. Before the portal is accepted, three real customers each open a quote, accept it and find a document, on their own phone, from a WhatsApp link.
• Staff. Five people per round across the roles and language groups. With a team this small, that is nearly everyone.
• Tasks. Six real tasks, unaided, on their own phones. Record whether each succeeded and how long it took.
• Scores. After each task, one question: how easy was that, 1 to 7. After each round, the ten-question System Usability Scale. The average app scores 68; the target is 80.
• Icons. The recognition test in section 9.
• Motion. After an action: "what just happened?"
• Looks. A five-second glance test on each key screen.
• Conditions. English and Arabic, light and dark, indoors and in sunlight.
• Devices. Galaxy S25 and A55 5G, in Chrome and Samsung Internet, installed and in a tab; one iPhone for the portal and site.
• Automatic checks on every build. Contrast, target size, enlarged text, and screenshots compared in English, Arabic, light and dark.
• Fix the top three problems each round, then test again.

17. Where there is no evidence

These are decided by our own tests, not by assumption:

• Whether charts should run right-to-left in Arabic.
• Colour and gesture meanings for Gulf and South Asian users.
• Whether illustrations on empty screens help.
• Whether a shipment map adds anything to a stage list.
• How much order tracking reduces "where is my order" calls. Published figures come only from vendors; we measure our own before and after.
• Which glass level each phone holds at full frame rate.

18. Decisions to confirm

19. Sources

• Apple: Human Interface Guidelines, 166 pages read from Apple's published data (November 2026), including Materials, Color, Typography, Layout, Motion, Tab bars, Toolbars, Sheets, Alerts, Charting data, Undo and redo, Writing, Right to left, Accessibility; WWDC 2025 sessions 219, 323 and 356; iOS 26.1 to 27 release notes.
• First impressions and simplicity: Lindgaard et al. 2006; Tuch et al. 2012; Reinecke et al. 2013.
• Navigation, icons, glass: Nielsen Norman Group studies on hidden navigation (179 people), icon usability, and Liquid Glass (2025); Wiedenbeck 1999.
• Charts: Cleveland and McGill 1984; Heer and Bostock 2010; Skau and Kosara 2016; Blascheck et al. 2019 and 2023; Brehmer et al. 2019 and 2020; Stokes et al. 2022; Lundgard and Satyanarayan 2022.
• Reading and type: Legge and Bigelow 2011; Piepenbrock et al. 2013; Dobres et al. 2016 to 2018; Bababekova et al. 2011; Boccardo 2021; W3C Arabic and Persian Layout Requirements 2025.
• Forms and money: Bargas-Avila et al. 2007; Seckler et al. 2014; Vessey 1991; Jerez-Fernandez et al. 2014.
• Touch: Parhi, Karlson and Bederson 2006; Hoober 2013 and 2017; WCAG 2.2.
• Perceived quality: Pracejus, Olsen and O'Guinn 2006; Sevilla and Townsend 2016; Buell and Norton 2011.
• Performance of blur: a published measurement on a Galaxy A15 (2026); Chromium and WebKit issue trackers.
• Earlier DiyaOS work: the design-law summary, the data-presentation research and the stone trader experience studies in C:\vaiprojects\helmdor\docs.

Some findings were checked only against summaries rather than the full papers, and a few recent Apple and Samsung details come from press coverage. Anything the plan depends on is re-checked on the real phones in Stage 0.

AI-designed interfaces (added in revision 4)

• Nielsen Norman Group, evaluation of AI prototyping tools (hierarchy, spacing, generic look): https://www.nngroup.com/articles/ai-prototyping/
• A. Krebs, automated scoring of 1,590 AI-built pages for repeated patterns: https://adriankrebs.ch/blog/design-slop/
• Anthropic, why models converge on one look and how to prevent it: https://claude.com/blog/improving-frontend-design-through-skills
• Vercel, web interface guidelines (targets, safe areas, states, undo): https://github.com/vercel-labs/web-interface-guidelines
• Accessibility of model-written interfaces: https://arxiv.org/html/2503.15885v1 , https://arxiv.org/html/2501.03572v1 , https://tommasocalo.github.io/papers/semacces
• WebAIM Million 2025 (contrast failures): https://webaim.org/projects/million/2025
• GitClear, duplicated code in AI-assisted work: https://www.gitclear.com/write_only_mode_ai_research
• Veracode, security flaws in AI-written code: https://www.veracode.com/press-release/ai-generated-code-poses-major-security-risks-in-nearly-half-of-all-development-tasks-veracode-research-reveals/
• Invented package names: https://socket.dev/blog/slopsquatting-how-ai-hallucinations-are-fueling-a-new-class-of-supply-chain-attacks
• Models favour their own output: https://arxiv.org/abs/2404.13076v1

No measured study was found on missing states or phone-specific faults in AI-built interfaces; rows 7 to 11 of the table rest on practitioner reports and general mobile-web guidance.

Scope: one desk layout (added 12 November 2026)

This document governs the staff app, which is phone only, except the Money area, which also has a desk layout built from the same tokens and the same Halo and command ideas: docs/MONEY-DESK.md.