All documents

Start here

You are looking at the 8020IQ design system, extracted whole from a running product so it can be applied to another app. It is not a theme and not a suggestion: it is the components, the tokens, the fonts, the logos, and the decisions behind them.

The one rule

Everything is identical across our apps except two things: the ACCENT COLOUR and the LOGO. Surfaces, ink, light and dark, the type ramp, the spacing scale, the two radii, the icon set, icon sizes, hit targets, the shell, the table, the admin patterns — all the same, everywhere, in all three brands.

Branddata-brandAccentWho it is
8020IQ
iq
Emerald #10B981
Parent, the platform
8020REI
rei
Sky #0495FE
Real-estate vertical
8020Roof
roof
Orange #FF6723
Roofing vertical

If a change you are about to make would look different in the other two brands for any reason other than the accent, it is wrong.

Read in this order

#FileWhat it settles
01
01-brand-and-color.md
The three brands, light and dark, every token
02
02-typography.md
Three families, seven tiers, when each is used
03
03-icons-spacing-radius-shadow.md
Icon set and sizes, the 4px scale, two radii
04
04-buttons-and-controls.md
Buttons, inputs, selects, switches, toggles
05
05-sidebar-and-shell.md
The rail, the header, the switcher, the account menu
06
06-admin-and-permissions.md
Roles, gates, draft-and-publish, optimistic writes
07
07-tables-and-data.md
The table, figures, sticky headers, pinned columns
08
08-page-anatomy.md
Screen, PageHeader, Panel, the two page rhythms
09
09-states-and-feedback.md
Empty, loading, error, disabled, pending
10
10-rules.md
The never list and the always list
11
11-traps.md
Failures already paid for. Read before debugging
12
12-apply-checklist.md
How to install it and how to know you are done
13
13-contrast.md
Every ratio, computed, and the two known gaps
14
14-measurements.md
Every box, font, padding and colour, measured in a browser
15
15-content-and-reading.md
Markdown pages, the measure, Reading vs Source
16
16-entry-screens.md
The hub, sign-in, and the 404
17
17-overlays-and-the-rest.md
Dialog, sheet, tabs, and every remaining primitive
18
18-maps-and-scope.md
The choropleth, why colour is its only config, the scope control
19
19-elevation-and-depth.md
The z ladder, the three elevation tiers, inset-shadow borders
20
20-component-index.md
Every exported symbol, generated — nothing hides
21
21-token-reference.md
Every CSS custom property with its value and scope
23
23-charts.md
The four chart types and the five derived series colours
22
22-dashboard-structure.md
The composition every screen follows: the five boxes, the five gaps, the three grids
24
24-feedback-and-triage.md
Shift+Click to report it: the capture, the queue, the agent that drains it

Before you write any code, ask these

Do not guess. The answers change the work, and the person you are working with knows them.

  1. Which brand is this app? iq, rei or roof. It sets one attribute and one constant, and it is the only per-app visual decision.
  2. Is this a new surface, or are you re-skinning an existing one? If re-skinning: is a token-and-primitive swap acceptable, or must existing markup stay byte-for-byte and only the CSS change?
  3. Does it have sign-in and roles? If yes, who is an admin, and is there anywhere that WRITES? That decides whether you need 06-admin-and-permissions or can skip it.
  4. Light, dark, or both? Both is the default and costs nothing — every token already flips. Say so if a surface must be locked to one.
  5. What are its tools/sections? They become one PRODUCTS list. If there is only one section, say so — the rail then carries no switcher.
  6. Is it data-heavy or reading-heavy? Tables and figures, or prose and documents. It decides Screen fill vs Screen, and the density.
  7. What cannot change? Charts, maps, an embedded third-party widget, a marketing page that is not ours. Name it now, colour it with tokens, and leave its behaviour alone.
  8. Where does the app live and how does it deploy? Only so you do not break a build with a font path or an asset that never got copied.

What you must not do

  • Do not invent a colour. Every value you need has a token. If you cannot find one, the answer is in 01, not in a hex you pick.
  • Do not add a fourth button variant, a third radius, a fourth font, or a second icon library. Each of those is a decision this system has already made and written down with its reason.
  • Do not re-generate the shadcn primitives with the CLI. The copies here are patched; regenerating silently reverts the patches (11-traps.md).
  • Do not put navigation in the account menu, and do not put a second copy of the tool list anywhere (05-sidebar-and-shell.md).
  • Do not use emoji as icons, gradients as decoration, or a coloured left border as emphasis (10-rules.md).