Diamond Stone: components

Date: 2026-11-11. Revision 1. Drawn in docs/component-map.html.

Every component of the shared interface package (packages/ui): its parts, its kinds, the optional features it can switch on, its states and its movement. It expands docs/DESIGN.md section 8 (a list of 27 elements with one line each) and the "Components" layer of docs/FRONTEND.md section 1. Movement tokens are in docs/MOTION.md; sizes in docs/DESIGN.md section 4.

Nothing is built. Names are proposals. The numbers at the start of each row are only for reference.

1. Why this is needed

The mockup draws 176 screens with 81 separate drawing functions, written one at a time as each screen needed something. Nine of them draw a row in a list. Five draw a card. Built that way, the real app would have the same component nine times, each slightly different, and each needing its own states, Arabic layout, screen reader names and tests.

This plan does the opposite: few components, each with named parts and switchable features. The 81 functions become 96 planned components, most of which the mockup never drew because they are behaviour (a field, a dialog, a list that only draws what is visible). The nine rows become one Row.

2. How a component is put together

Five things describe every component.

Rules that keep it small.

1. A part, not a new component. If two things differ only in what sits in one place, it is one component with a part.
2. A feature, not a kind. If the difference is something it can do (be selected, be swiped, hide its amount), it is a feature, shared with every other component that can do the same.
3. A kind only for a different purpose. At most five kinds per component. A sixth means it is two components.
4. No look from outside. A screen cannot pass a colour, a size or a timing to a component. It passes meaning: tone, emphasis, size set.
5. Three sizes at most: the two size sets (Compact, Comfortable) come from the person's setting, not the screen. A component may also have a "small" form for use inside another.
6. Tones are five and shared: neutral, accent, good, warning, bad. Each is always colour plus icon or word.
7. Every component is complete alone: all states, both directions, both themes, every surface level, enlarged text, a screen reader name, and its placeholder shape.

3. Features shared by all components

Each is written once, as a primitive or a small helper, and switched on per use.

4. The components

Kinds are separated by "·". Features lists only those beyond Permission, Direction, Tone and Loading shape, which apply to all.

Primitives (behaviour only, no look): 12

Actions: 10

Inputs: 21

Showing: 26

Telling: 9

Overlays: 6

Shell and patterns: 12

Total: 96. Twelve primitives, 84 components and patterns. The Halo band, Halo ring and Omnibar are broken into 24 named parts in docs/SHELL.md section 8.

5. States every component has

6. From the mockup's functions to components

The rest of the 81 are icons, layout and the phone frame.

7. How they are coded

8. Order of building

1. Tokens, and the checks that enforce them.
2. Primitives 1 to 12, each with a test page. The owner tries Surface, Pressable and Draggable on both phones.
3. The shell: Halo band and ring, Omnibar, Top bar, Sheet.
4. The eight most used: Button, Chip, Row, List, Card, Field, Money, Status chip. With these, about half the screens can be put together.
5. Inputs, then the rest of Showing and Telling.
6. Heavy ones last: Chart, Map, Camera, Scanner, Signature, Document.

A component is finished when its page in the workshop shows every kind, feature and state, in both directions, both themes, every surface level and both size sets, and all of those pass the picture comparison, the accessibility check and its size budget.

9. Decisions

1. The names in section 4, before anything is coded against them.
2. Whether the Slider and Rating are needed at all in the first build. Proposed: Rating yes (delivery feedback), Slider no.
3. Charts: three kinds only (bars, line, stacked bars). Proposed: yes; no pies.
4. Whether a component may ever be restyled by a screen. Proposed: never.

The website and portal have their own parts (added 11 November 2026)

The 96 components here are the staff app's. The public website and the client portal use a separate, much smaller set (header, link row, menu, opening, stone figure, word list, figures, specification, reading text, timeline, field, progress line, action bar, footer), listed in docs/SITE-DESIGN.md sections 4 and 16. The two sets share tokens for brand colour and typeface only.

Components 97 to 112: the Money desk (added 12 November 2026)

Sixteen more, in docs/MONEY-DESK.md section 7: table, tree, calendar and period grid, board, split panes, document viewer, rail, command field, bulk bar, file drop, column mapper, entry grid, date range, side panel, print view, shortcut sheet. Table, tree, calendar and board were already used by phone screens and were missing from this list.

After the critique (12 November 2026)

From docs/CRITIQUE.md section 2. Added or changed: