Exceptions are the interface
Screens answer "is anything wrong?" first. Nothing to do is a designed, confident state, not an empty one. Show changes, not levels.
Light theme · web and mobile · v1
The One Link design system
One Link runs a grain and fertilizer business: trades and mill coverage, weighbridge intake, stock, and farmer input finance, with a portal for counterparties and a field app for drivers. Every screen leads with what needs attention, and every figure is derived, never typed.
- White lifts, grey recedes
Cards, tickets and figure buttons are white on white, held apart by very soft shadows. Grey marks only what is secondary or switched off.
- Greys tinted navy, and see-through
Text and hairlines are navy-black at set opacities, so one token reads right on white and on grey. Each has a solid twin for use over photos.
- Two layers of colour
Components use semantic tokens only. Those point at 11-step palettes, so a palette change never touches a component.
- The commodity takes over
Blue is for links and entry points. Inside a commodity, its colour drives the share bars, chart lines and the trade ticket. Decisions stay primary dark.
- Physical feedback
Anything that commits sits on a 4px edge and sinks into it. Buttons scale to 0.97, motion settles on a spring, and every working button shows it is working.
Hover the card for the commodity wash. Press a figure to sink it. Switch commodity in the rail.
Rules
These come from how the business works, not from taste. Every component and screen obeys them.
Every figure is derived, and can show how
Balances, stock, exposure and margin are computed, never typed. A headline figure reveals the subtraction behind it in one interaction.
Provenance and confirmation never merge
How a weight was captured and whether the counterparty agrees are two separate chips, with two separate icons.
Absent is not zero
A figure withheld from a role is genuinely missing. It shows as a quaternary dash with eye-off, and never as K0, blank, loading or blurred.
Three outcomes, three looks
Within tolerance books. Held for review goes to the owner. A hard block, like tare above gross, never books and is shown calmly, not as an error flood.
Nothing is edited
Records are append-only. A correction is a compensating entry with a reason, an actor and a time, beside the original.
Freshness is visible, degraded modes are loud
A silent weighbridge feed makes the position look flat, so sync health is always shown, and silence is unmistakable. Offline is a state with a queue.
Every working button shows it is working
The label fades and scales to 0.8 while a spinner takes its place. The button keeps its size and stays busy until the action lands.
Status is always an icon and a word, never colour alone. Icons are Lucide only: no emoji, no Unicode symbols standing in for icons. Charts are TradingView Lightweight Charts.
Logo
One link with two loops, in One Link blue. In the product it is always the blue mark on a white surface. The white-on-blue tile exists only for the two places that must be a filled square: the app icon and the browser tab.
The mark: blue on white. Header, sidebar, collapsed rail, documents.
White on blue: only on a brand-blue surface, never on a commodity colour.
The tile: app icon and browser tab only, where a filled square is required.
Why blue on white, and why a tile at all
The mark is about 1.6 times wider than it is tall. Where there is room, which is everywhere inside the product, it sits on its own in One Link blue: the cleanest form of the brand. A phone's home screen and a browser tab are small, square and filled, and a wide mark alone in a square shrinks to a thin line. The tile gives it a square of its own, so it reads at 16 pixels and on any wallpaper.
The One Link mark
UAG's business is connection. It stands between Zambia's farmers and its mills, and between grain that arrives by sea and the mills that need it. Every tonne UAG handles is a link between someone who grows or ships it and someone who needs it.
The mark is two links joined into one. One side is the farmer, the other the mill. Where they meet, the overlap forms a single grain kernel. The grain sits at the exact point where the two join, because that is what UAG does: it sits in the middle and makes the connection work, one load at a time. It is also what One Link does, turning many spreadsheets, phone calls and workbooks into one record that everyone reads.
The shape is deliberately simple. It has to be recognisable on a farmer's phone screen in bright sun, on a clerk's screen at the weighbridge, and as a small icon in the app store. It uses One Link's own blue, and every commodity keeps its own colour inside the product, so the logo never competes with the wheat, maize, soya and fertiliser it serves.
The splash
The mark's one animation: the mark, there at once, with a light running round its loops while the app loads. It shows on every full page load and fades once the app is ready. With reduced motion it is the still. The full rules are on the Splash card.
Animated: one-link-splash.svg. Full page loads only, never a move inside the app.
Reduced motion: one-link-splash-still.svg, the same frame with no light.
Using it
- One colour: One Link blue #2563EB, or white on that blue. Never a commodity colour, a gradient or another blue.
- Keep clear space of half the mark's height on every side. The mark is never under 20 px high; the tile never under 16 px.
- Never stretch, rotate, outline, shadow or animate it (the splash is the one animation, and it has its own files), and never put letters inside it. Use the Logo component or the files in assets; never redraw it.
- The stores get one-link-app-icon.svg, full bleed; they round the corners themselves.
Colour
Two layers. Components use only the semantic tokens; the "Points to" column shows the palette step each one resolves to. Hover mixes 5% black into light fills and 10% white into filled buttons.
Surfaces
White does the lifting. Grey is kept for what recedes: search, unselected capsules, disabled fills, closed records.
| Token | Value | Points to |
|---|---|---|
--surfacePage ground |
#ffffff |
gray-50-solid |
--elevatedCards, figure buttons, quantity chips, tickets |
#ffffff |
gray-50-solid |
--groupedSecondary tiles, skeletons, row hover |
#f4f5f7 |
gray-100-solid |
--grouped-lightSearch, unselected capsules, disabled fills |
#00153f0b |
gray-100 |
--grouped-elevatedGrey tile inside a card |
#f4f5f7 |
gray-100-solid |
--invertedInverted chips, chart crosshair labels |
#23272d |
gray-900-solid |
--overlayDialog and sheet scrim |
#00000066 |
literal |
Content
Text and icons are navy-black at set opacities, so one token reads right on white and on grey.
| Token | Value | Points to |
|---|---|---|
--content-primaryTitles, figures, main text |
Aa#00050cdc |
gray-900 |
--content-secondaryMeta lines, units, secondary text |
Aa#000c1c94 |
gray-700 |
--content-tertiaryInactive tabs, captions. Never a figure |
Aa#000f2174 |
gray-600 |
--content-quaternaryChevrons, placeholders, the restricted dash |
Aa#00102a40 |
gray-400 |
--content-disabledDisabled labels |
Aa#00152e54 |
gray-500 |
--content-accent-brandLinks, active stepper value |
Aa#2563EB |
brand-500 |
--content-accent-upPositive delta text |
Aa#007e26 |
green-600 |
--content-accent-downNegative delta text |
Aa#df0c10 |
red-500 |
--accent-up-fillUp triangle, in-bars, live dot. Fills only, never text |
Aa#04af52 |
green-400 |
Solid twins
The same greys as solid colours, for text laid over a photo, where translucency would pick up the image.
| Token | Value | Points to |
|---|---|---|
--content-primary-solidPrimary text over photos |
Aa#23272d |
gray-900-solid |
--content-secondary-solidSecondary text over photos |
Aa#6b727b |
gray-700-solid |
--content-tertiary-solidCaptions over photos |
Aa#8b929b |
gray-600-solid |
--content-quaternary-solidChevrons over photos |
Aa#bfc3ca |
gray-400-solid |
Status
Subtle is the pale fill, strong is the text on it. Status is always an icon and a word, never colour alone.
| Token | Value | Points to |
|---|---|---|
--info-subtleInfo banner fill |
#f7fbfe |
brand-50 |
--info-strongInfo banner text |
Aa#0135aa |
brand-700 |
--success-subtleClean, within spec, confirmed |
#e4ffe9 |
green-50 |
--success-strongText on success |
Aa#006118 |
green-700 |
--warning-subtleAttention, amber band, held for review |
#fefce8 |
yellow-50 |
--warning-strongText on warning. #a16207 rather than #ca8a04, for AA |
Aa#a16207 |
yellow-700 |
--error-subtleBreach, red band, hard block, sync silent |
#fff6f2 |
red-50 |
--error-strongText on error |
Aa#bc0000 |
red-600 |
Lines and actions
Hairlines, the button fills, and the BETA badge.
| Token | Value | Points to |
|---|---|---|
--borderCard outlines, dividers, selected capsule border |
#00123719 |
gray-200 |
--border-light3D edge, table row dividers |
#0000000f |
literal |
--border-elevatedOutlines on elevated layers |
#00123719 |
gray-200 |
--buttons-primaryDecisions: Approve, Finalise, Resolve case |
#23272d |
gray-900-solid |
--buttons-brandEntry points: New trade, Raise GRN |
#2563EB |
brand-500 |
--buttons-criticalDecline, Void batch |
#df0c10 |
red-500 |
--buttons-labelLabels on filled buttons |
#ffffff |
gray-50-solid |
--hover-overlay-darkerSubtle button fill, keyboard hint |
#0000000d |
literal |
--beta-fillBETA badge |
#2563EB |
brand-500 |
--beta-labelBETA badge label |
#ffffff |
gray-50-solid |
Palettes
Eleven steps each. The brand ramp keeps the reference's lightness per step, with One Link blue at 500.
graySolid greys for use over images
50ffffff
100f4f5f7
200e6e8ec
300d4d7dc
400bfc3ca
500abb2bb
6008b929b
7006b727b
800454a52
90023272d
950000000
gray, translucentTranslucent navy greys, what the content tokens point at
50ffffff
10000153f0b
20000123719
3000014332b
40000102a40
50000152e54
600000f2174
700000c1c94
800000711ba
90000050cdc
950000000
brandOne Link blue, 500 is #2563EB
50f7fbfe
100cddffb
200a3c2f7
30079a4f4
4004e84f0
5002563EB
6000e4bd1
7000135aa
800002687
90000165c
950000734
greenUp, success
50e4ffe9
100cdf3d7
2008fe5a5
3003ad26d
40004af52
500009c39
600007e26
700006118
80000450a
900002a01
950001200
redDown, error
50fff6f2
100ffcfc6
200ffa597
300ff7464
400fe3d33
500df0c10
600bc0000
700930000
8006b0000
900460000
950240000
yellowWarning
50fefce8
100fef9c3
200fef08a
300fde047
400facc15
500eab308
600ca8a04
700a16207
800854d0e
900713f12
950422006
tealSupporting
50dfffff
1008ff1ff
2005cd8f9
3003bbcdd
40005a2c2
5000088a7
600006d89
70000546a
800003b4d
900002432
950000f18
purpleSupporting
50fff7ff
100ebd1ff
200d6a9ff
300c37eff
400aa5bf6
5008f3dd7
600781dbc
7006100a1
800460078
9002d0050
95015002c
Commodity colours
The deep shade carries a white label at AA or better. Underlines are 2px, washes are 9% in oklab, tiles 16%.
- White maize
- Wheat (local and import)
- Soya
- Soya meal
- Fertilizer
Type
Two families. Inter for everything you read. Instrument Sans condensed, always uppercase, for headline figures, commodity tabs and detail titles. Specs are size/line height · weight · tracking.
Regular is 480
A touch heavier than 400, which keeps small translucent text crisp on white. Strong body is 580, strong headings 600.
14px carries the product
body-3 is the workhorse for tables, meta lines and rows. Headings are rare; condensed figures do the shouting.
Every figure is tabular
Money, tonnes, percentages, refs and timestamps all use tabular numerals. Kwacha millions take M: K125M, K174,840.
Display
K125M
K190,790,400
Heading
Stock: Kafue Road, Lusaka
Credit book: Winter Wheat 2026
Credit book: Winter Wheat 2026
Needs you
Needs you
Coverage
Coverage
Body
Amount
Amount
ZAM4702 short 1,400t
ZAM4702 short 1,400t
Kafue Valley Milling · window closes in 12 days · 2d
Kafue Valley Milling · window closes in 12 days · 2d
folded from 41,882 movements · to 03 Aug 2026 · 07:10
folded from 41,882 movements · to 03 Aug 2026 · 07:10
Caption
Showing 4 of 72 trades · season 2026
Showing 4 of 72 trades · season 2026
Charts by TradingView
Charts by TradingView
Condensed · always uppercase
K125M
K11.8M
34,117
2,000 MT
ZAM4702 · Kafue Valley Milling
White maize Wheat (local) Soya
53%
01 Critical
Target
Beta
Shape
A radius scale with one odd step, 14px, used only on 48px buttons. On white, shadows do the separating that grey fills would do elsewhere.
--radius-5xs2pxsmall badges--radius-4xs4pxkeyboard hint, skeleton text, severity tag--radius-3xs6px--radius-2xs8pxquantity chips, selected segment--radius-xs10px32px buttons, stepper--radius-sm12px40px buttons, figure buttons, search, segmented track--radius-sm-h14px48px buttons--radius-md16pxhover rows, tiles, banners, popovers--radius-lg20pxcards, tickets, chart cards, dialogs--radius-xl24px--radius-2xl32px--radius-max999pxpills, capsules, avatarsElevation
Six exact shadow stacks.
--shadow-flatBorder only, no lift--shadow-minimalStepper, selected segment, carousel arrows--shadow-minimal-softCards, tickets, decision panels, chart cards--shadow-middleQuantity chips--shadow-strong48px actions, menus, popovers--shadow-dialogDialogs, bottom sheetsMotion
Springs are CSS linear() curves, so there is no animation library. Every animation has a reduced-motion fallback that keeps colour changes and drops scale, translate and ping.
--ease-springTab underline, label and spinner swaps, toggles · overshoots to 1.015--ease-expandAccordions, bottom sheets · no overshoot--ease-cardCard commodity wash · 400ms in, 160ms out
ease-spring
ease-expand
ease-card
150ms
--dur-defaultcolour + hover50ms
--dur-press-down3D press100ms
--dur-press-up180ms
--dur-capsuleweight swap300ms
--dur-underlinetab underline glide (spring)500ms
--dur-swaplabel / spinner swap (spring)400ms
--dur-card-in160ms
--dur-card-out300ms
--dur-sheetbottom sheet (expand)150ms
--dur-skeleton300ms
--dur-photo1.5s
--dur-ping0.8s
--dur-spin44s
--dur-marcha marching track, one full wrap250ms
--dur-splash-outthe splash fading away once the app is ready12s
--dur-splash-stuckthe splash says it is still loading1
--scale-press-button1
--scale-press-cardComponents
These are the real components from project/components, running live. Every one is interactive; the commodity switch in the rail recolours the ones that take a commodity.
Buttons
Brand for entry points, primary for decisions, critical for destructive, commodity only on the trade ticket. Every button that starts work has the loading state.
Press buttons
A face on a 4px edge. It sinks 4px in 50ms and returns in 100ms. Filled edges are the fill under 15% black.
Capsules, segmented, stepper, tabs, search
Selected capsules go white with a 1px ring and a 3px halo; the label weight settles over 180ms. Tab underlines glide on the spring.
Status, trust and sync
Status marks are an icon and a word. Provenance and confirmation are separate chips. Sync health is green while live and red, without a ping, when silent.
Cards, figures and rail rows
List items carry share bars in the commodity colour, quantity chips and figure buttons. Figures open their derivation.
Data table
Dense, tabular, with ref links, a restricted cell, a derived cell and a correction row. Tables scroll inside their own container on phones.
Charts
TradingView Lightweight Charts, styled to the system: dotted grid, magnet crosshair, end-of-line labels, dashed policy lines. The TradingView logo stays visible.
Trade ticket
The main action panel: side toggle, commodity tabs, amount, quick amounts and a full-width commit in the commodity colour.
- 1Header
28px commodity tile, context in body-3 secondary, subject in body-1 strong.
- 2Side toggle
Two-up 48px press buttons. The chosen side fills with the commodity colour.
- 3Amount
Label on the left, condensed figure on the right with a quaternary unit, quick amounts beneath.
- 4Commit
48px large press button with the strong shadow. It keeps its size and spins until the trade lands.
Reconcile, evidence and history
The goods-received reconcile in its three outcomes, evidence tiles, and an append-only timeline with a compensating entry.
Screens
Interactive UI kits built only from these components, with fictional sample data. The desktop app is drawn at 1440; the mobile app, partner portal and field app at 390.
Layout
A centred 1293px shell. List pages have a content column and a sticky "Needs you" rail; detail pages swap the rail for the 350px action panel. Phones get one column and a bottom tab bar.
Shell1293px max · 16px sides, 24px from 1024px
Two columnsFrom 1152px: rail 320px, 40px gap; below, the rail stacks
Wide railFrom 1280px: rail 358px
Action panel350px on detail pages · bottom sheet below 1024px
Header116px phone · 106px from 1024px · blurs on scroll
Mobile tab bar70px + safe area
Spacing4px unit · sections 24px, 32px from 1024px · cards 16px
ArtboardsDesktop 1440 · mobile 390
Cards
Every specimen card from the Claude Design export, each a standalone page. They are the source these pages are built from.
Components
- Actions · Buttons, capsules, segmented, stepperButton variants and sizes, 3D press buttons, capsules, segmented control, line stepper700×600
- Core · Icon, Text, Avatar, LogoLucide icon sizes, type primitive, avatars and commodity tiles, One Link lockup with BETA700×330
- Home · KPI tile, expanding table row (M5.DS.01)A Home's KPI tiles, each opening Calculation details, with Not set when the exchange rate is missing; a table row that expands to its contracts1000×900
- Data · Chart card (TradingView Lightweight Charts v5)Area (position), line with price line (commodity), baseline (LTV), histogram; loading, empty, error states700×760
- Data · Cards, rows, figures, chips, share bars, rail rowsTrade card with commodity hover, figure with derivation popover, quantity chips, rail rows700×720
- Data · QR codeTakes a boolean matrix and renders it: white ground, content-primary modules, four-module quiet zone. It never encodes700×420
- Data · Data tableRefs as links, right-aligned tabular figures, restricted cell, derived cell, correction row, pagination900×420
- Data · TickerBottom strip of live figures: pinned anchor, seamless -50% marquee, inverted top corners, paused and empty. Hover or focus stops it. Nothing below 768px1200×300
- Feedback · Assistant panel, launcher, citation chipThe in-app assistant: launcher pill, empty state on real help page titles, a turn with citations, the working state, and the phone sheet. A question is a pill, an answer is set text1240×820
- Feedback · Banners, status marks, trust chips, severity, empty, skeleton, dialogEvery status pairs an icon and a word; provenance and confirmation stay separate chips700×640
- Inputs · Search fieldDefault, hover and focus; keyboard hint700×120
- Navigation · Auth shellSigned-out frame: one centred column, at most 400px wide (lockup, heading, one sentence, the form, the ways back), and nothing else on the screen1200×760
- Navigation · Docs shellReading frame outside the app: sticky header (lockup, Help, search, the way back), topics rail, article; below 1024 the topics are a drawer1200×760
- Navigation · Mobile shell116px header (top row + sub-tabs), content, 70px bottom tab bar + safe area390×844
- Navigation · Header, tabs, commodity tabs, sync statusDesktop header with BETA badge, module tabs, condensed commodity tabs, live/stalled/offline pills1200×420
- Navigation · App shell, collapsedThe same frame with the sidebar collapsed to 64px of module icons: labels kept for a screen reader, counts as dots, and the active module’s sections in a flyout (hover or focus an icon). The toggle is the last row of the foot.1200×720
- Navigation · App shellSigned-in frame: 260px sidebar with grouped modules and the active module's sections, a foot of rail links and the collapse toggle, 56px toolbar with breadcrumb, search, sync, digest and the account menu (identity, items, Sign out). The page column ends with the full bleed ticker row, whose inverted corners meet the frame edges1200×720
- Field capture · Capture tile, PIN pad, phone frame (M4.DS.03)The UAG One Link app: a capture tile busy until synced and a damaged file, Pending sync never 0 while one waits, the PIN pad with the fingerprint switch and its lock after five wrong PINs, the phone frame with the back chevron and the field staff's own bar1000×1100
- Imports · Checkpoint timeline (M7.DS.01)An import truck leg's five checkpoints with status, date, recorded by and Source; a position the transporter reported is a labelled Source, never a badge and never Weighbridge; the phone's stacked list1000×1100
- Inbound · Running sum, three-way reconcile, decisions, transit residue (M4.DS.01)Inbound and stock: the lines' running sum, the three-way reconcile naming the pair that is out, decision actions as data, a transit residue with its write-off Pending approval1000×1100
- Records · Column mapping, version comparison, preview checks, counterparty overview (M3.DS.01)Templates, uploads and counterparties: the column mapping with read-only tier tags, two versions compared, the preview checks with their cells, the counterparty overview and the source line1000×1500
- Outbound · Load meter, count match, reconciles, proof of delivery (M4.DS.02)Outbound: a load against its limit with one boundary, the bag count against the count sheet, the delivery note's reconcile and weighbridge variance, and the proof of delivery in each of its states1000×1500
- Records · Action panels, reconcile, evidence, timelineNew trade ticket, approval decision (busy), dispute resolution, portal confirm; reconcile outcomes; evidence tiles; timeline1100×720
- Setup · Forms, refusal, reason dialog, record highlights, one-time code (M1.DS.01, M1.DS.02)Setup's pieces: fields with the error under them, radio rows with an unavailable alternative, refusal, the reason dialog, record highlights1000×1500
- States · The map's conventions (UX-09 to UX-31)The states the map's conventions need, on the current tokens: status, Restricted, Not set, commodity marker, condition banner, Reconcile card, Calculation details, import preview, capture status1000×1400
- Trading · Margin cell, permit headroom (M6.DS.01)Trading: a margin per leg and in total, negative as a signal, Not set when its transport rate is missing, Restricted without the contract tier; a mill's permit headroom moving as an allocation is typed, refused past the permit1000×1000
- Weighbridge · Readiness, evidence viewer, field check, exceptions (M2.DS.01)Weighbridge continuity: readiness apart from source, the slip photo with zoom and fingerprint, the field check, the second confirmation, the exceptions list, an exception's highlights with its linked record1000×1500
Brand
- One Link logo and lockupThe One Link mark: one link, two loops, blue on white · the tile for app icon and browser tab only · use, sizes and why700×1640
- One Link splashThe mark at once, with a light running round its loops while the app loads · the still for reduced motion · how an app shows and removes it700×980
Colors
- Accents & semantic pairsBrand blue for links and entry points; up/down for deltas; subtle/strong pairs for banners700×260
- Commodity coloursDeep shade carries white labels (AA+); 2px underlines; washes at 9% in oklab; tiles at 16%700×200
- Content (translucent navy)Text and hairlines are navy-black at set opacities so one token works on white and grey700×170
- Palettes (11 steps)Semantic tokens point at these; never put a palette hex on a component700×330
- Surfaces & greysWhite lifts, grey recedes: grey marks only what is secondary or switched off700×150
Icons
Shape
Type
- Instrument Sans condensed700 · font-stretch 75% · uppercase · 700×400
- Figures & formattingAll figures tabular. K125M · K174,840 · $1,663,250 · 28.20t · 9.4% · Tue 24 Jun · 07:02700×190
- Inter scale480 regular · 540 regular headings · 580 strong body · 600 strong headings · cv02 cv07 ss04 cv15 calt700×420
One Link
- Setup (admin workspace)Setup: settings and governance. Setup Home, Settings, Switches, Approval steps, Policy methods, Items to approve, Vehicles and transporters, Devices and Captures in review, Assistant settings and the daily summary times, Key uploads, Exception rules and Quality specifications1440×900
- ImportsImports (M7): the operations lead's Home with Cannot invoice yet, Uploads today and Waiting on partners; the port schedule preview; the import schedule by mill and by port with its invoicing column; a truck leg's checkpoints, port documents, Record offload and the Reconcile card; transport performance, shortage claims, allocation drawdown, contracted rhythm, tolerance agreements and unmatched offloads; the dispatch report preview; and the M7 states of Coverage, stock control's Home and the Managing Director's Home1440×900
- One Link desktop appInteractive click-through: Command Center, Trade Desk, Warehouse, Stock, Farmer Finance; the Clerk's inbound, outbound and stock control screens; transport planning; the Managing Director's Home, reports and Assistant; Trading's cover board, farm-direct operations and farmer finance; the M6 states of the trade board, approval, grading dispute, goods received note and stock board1440×900
- One Link mobile app390px artboards of every screen inside the mobile shell390×844
- Trading workspaceTrading workspace: the trade working view with live margin, contract terms, the monthly schedule, the price ladder, a shipment's allocations with permit headroom, long and short by origin and corridor, the trade record, closing a trade, generating contracts and signatures, amendments, quality specifications, lots, permits, diversions and the contract list, with the M6 states of the existing screens1440×900