Skip to content

Design language

This page describes how the Gib interface looks and behaves. Gib is the open-source engine. gib.show is the public instance that runs it, and the interface you see there is the one described here.

Every value on this page comes from the code. Each section names the file it comes from. If the code and this page disagree, the code is right: fix the page.

Where the code falls short of its own rules, this page says so. Those gaps are marked as Known gap.

  • Dark first, light equal. The interface has two full themes. Neither is an afterthought. Every surface, border and text colour has a light value and a dark value.
  • One accent. The accent role is the only brand colour. accent-secondary appears only as a second stop in gradients and glows.
  • Quiet surfaces, bright edges. Surfaces are near-black or near-white. Borders are thin. Colour and glow are kept for the one thing that matters on the screen.
  • Show the product. Token and network logos are the content. They are drawn on plain, round or square chips so any logo looks right.
  • Native where it helps, never where it does not. Links, buttons and inputs are native elements. A choice from a list is a menu. A native select element is not allowed.
  • Fast and calm. Motion is short and small. It never carries meaning on its own, and people who ask for less motion get less.

Name a colour by its role, never by its value. A name that carries a value turns false when a theme changes the value. --color-cyan-500 is wrong: under another theme it may not be cyan. --color-accent-secondary is right: it stays true whatever colour fills the role.

  • A token name never holds a hue (cyan, green, gray, red), a mode word (light, dark) or a number from a colour scale (500).
  • A name never ends in a number. A number tells near duplicates apart, and a near duplicate belongs in the role that does its job. A test fails on a role name that ends in a number.
  • A token holds one value per theme. It is not two tokens, one for each theme.

Two checks hold the rule. The design/no-raw-palette-classes lint rule in packages/ui/eslint.config.js fails the build on a raw palette class such as text-gray-400 or bg-red-50. A test in packages/ui/src/design-tokens.test.ts fails on a token in app.css whose name holds a hue, a mode word or a scale number. white, black and transparent are not hues and stay allowed where a fill does not change with the theme, for example text-white on a dark tooltip.

packages/ui/src/app.css defines each role as a custom property named --ui-<role>. The light value is under :root and the dark value is under .dark. A @theme inline block hands each property to Tailwind 4, which turns --color-<role> into the utility classes bg-<role>, text-<role> and border-<role>. One class is enough. The old pair text-gray-600 dark:text-gray-400 is the single class text-content-muted, and the theme picks the value.

An alpha modifier works on a role as on any colour: bg-accent/10, bg-surface-active/80.

Values refer to Tailwind’s palette (var(--color-gray-900)). The tables below resolve them, so they show the colour a reader sees.

The tables are read from app.css when this site is built, so they always match the interface. The set is small on purpose. Each role is one job. When two places need almost the same colour, they use the same role.

Text, from strongest to faintest

RoleLight themeDark theme
content-strongoklch(21% 0.034 264.665)#fff
content-bodyoklch(27.8% 0.033 256.848)color-mix(in oklab, #fff 90%, transparent)
content-secondaryoklch(37.3% 0.034 259.733)color-mix(in oklab, #fff 80%, transparent)
content-controloklch(37.3% 0.034 259.733)#fff
content-mutedoklch(44.6% 0.03 256.802)oklch(70.7% 0.022 261.325)
content-subtleoklch(55.1% 0.027 264.364)color-mix(in oklab, #fff 50%, transparent)
content-faintoklch(70.7% 0.022 261.325)color-mix(in oklab, #fff 40%, transparent)
content-ghostoklch(87.2% 0.01 258.338)color-mix(in oklab, #fff 20%, transparent)
content-inverse#fffoklch(21% 0.034 264.665)

Surfaces: the page, cards, wells, menus, control fills and hovered or active fills

RoleLight themeDark theme
surface#fff#09090b
surface-raised#fff#111113
surface-insetoklch(98.5% 0.002 247.839)#1a1a1e
surface-overlay#fff#1a1a1e
surface-glass#fffcolor-mix(in oklab, #fff 3%, transparent)
surface-controloklch(96.7% 0.003 264.542)#27272a
surface-selected#fff#27272a
surface-activeoklch(92.8% 0.006 264.531)#27272a
surface-washoklch(96.7% 0.003 264.542)color-mix(in oklab, #fff 5%, transparent)
surface-wash-activeoklch(92.8% 0.006 264.531)color-mix(in oklab, #fff 10%, transparent)
surface-handleoklch(70.7% 0.022 261.325)color-mix(in oklab, #fff 40%, transparent)
surface-sheencolor-mix(in oklab, #fff 5%, transparent)color-mix(in oklab, #fff 5%, transparent)
surface-sheen-faintcolor-mix(in oklab, #fff 2%, transparent)color-mix(in oklab, #fff 2%, transparent)
surface-inverseoklch(21% 0.034 264.665)#fff
surface-inverse-hoveroklch(37.3% 0.034 259.733)oklch(92.8% 0.006 264.531)
surface-tooltipoklch(21% 0.034 264.665)oklch(37.3% 0.034 259.733)
surface-thumb#fffoklch(92.8% 0.006 264.531)
surface-brightoklch(92.8% 0.006 264.531)oklch(92.8% 0.006 264.531)

The same dark in both themes: logos are shown here to test how they read on a dark page.

RoleLight themeDark theme
surface-backdropoklch(21% 0.034 264.665)oklch(21% 0.034 264.665)

Scrims

RoleLight themeDark theme
scrim-softcolor-mix(in oklab, #000 20%, transparent)color-mix(in oklab, #000 40%, transparent)

Borders

RoleLight themeDark theme
border#e4e4e7rgba(255, 255, 255, 0.08)
border-strongoklch(92.8% 0.006 264.531)#27272a
border-subtleoklch(92.8% 0.006 264.531)color-mix(in oklab, #fff 10%, transparent)
border-softoklch(87.2% 0.01 258.338)color-mix(in oklab, #fff 10%, transparent)
border-inputoklch(87.2% 0.01 258.338)color-mix(in oklab, #fff 20%, transparent)
border-input-hoveroklch(70.7% 0.022 261.325)color-mix(in oklab, #fff 30%, transparent)
border-overlap#1a1a1e#1a1a1e

Accent: fills and borders are the same in both themes; the content roles are for accent-coloured text and icons

RoleLight themeDark theme
accent#00dc82#00dc82
accent-strong#00b368#00b368
accent-soft#33e69b#33e69b
accent-secondary#0ea5e9#0ea5e9
accent-content#00703f#00dc82
accent-content-hover#00623a#33e69b
accent-secondary-content#0369a1#0ea5e9

Status: danger

RoleLight themeDark theme
dangeroklch(57.7% 0.245 27.325)oklch(70.4% 0.191 22.216)
danger-hoveroklch(63.7% 0.237 25.331)oklch(70.4% 0.191 22.216)
danger-strongoklch(63.7% 0.237 25.331)oklch(63.7% 0.237 25.331)
danger-brightoklch(70.4% 0.191 22.216)oklch(70.4% 0.191 22.216)
danger-softoklch(97.1% 0.013 17.38)color-mix(in oklab, oklch(39.6% 0.141 25.723) 20%, transparent)

Status: success

RoleLight themeDark theme
successoklch(62.7% 0.194 149.214)oklch(79.2% 0.209 151.711)
success-strongoklch(52.7% 0.154 150.069)oklch(79.2% 0.209 151.711)
success-brightoklch(79.2% 0.209 151.711)oklch(79.2% 0.209 151.711)
success-softoklch(98.2% 0.018 155.826)color-mix(in oklab, oklch(39.3% 0.095 152.535) 20%, transparent)

Status: warning

RoleLight themeDark theme
warningoklch(55.4% 0.135 66.442)oklch(85.2% 0.199 91.936)
warning-softoklch(98.7% 0.026 102.212)color-mix(in oklab, oklch(79.5% 0.184 86.047) 5%, transparent)
warning-edgeoklch(79.5% 0.184 86.047)oklch(79.5% 0.184 86.047)

Status: caution

RoleLight themeDark theme
cautionoklch(55.5% 0.163 48.998)oklch(82.8% 0.189 84.429)
caution-softoklch(98.7% 0.022 95.277)color-mix(in oklab, oklch(41.4% 0.112 45.904) 20%, transparent)
  • --shadow-glow-accentrgba(0, 220, 130, 0.3)Glow colour, 20px blur
  • --shadow-glow-accent-secondaryrgba(14, 165, 233, 0.3)Glow colour, 20px blur
  • --shadow-glow-accent-subtlergba(0, 220, 130, 0.08)Glow colour, 24px blur
  • --shadow-elevatedrgba(0, 0, 0, 0.4)Shadow colour, 24px blur, 4px down

The @custom-variant dark line in app.css sets the rule: a dark class on the html element turns the dark theme on, and dark: utilities apply under it.

  • The class is set before the first paint by themeScript in packages/ui/src/prerender/pre-paint.ts. Without it the page would paint light and then flip.
  • The reader’s choice is stored under theme-mode (light, dark or system) by packages/ui/src/lib/contexts/ThemeContext.tsx. system follows the prefers-color-scheme setting.
  • ThemeToggle (packages/ui/src/lib/components/ThemeToggle.tsx) is the control: one button flips light and dark, and one button turns system on or off.

This site is built with Starlight. packages/docs/src/styles/theme.css gives it the same green and changes nothing else:

Token Dark theme Light theme
--sl-color-accent-low #003d24 #c9f5e0
--sl-color-accent #00b368 #008a50
--sl-color-accent-high #33e69b #00623a

Three families, all with the SIL Open Font License 1.1. They are self-hosted as Latin-subset woff2 files by packages/ui/src/fonts.css, from the @fontsource packages. The family names in fonts.css must match the --font-* tokens in app.css.

Role Token Stack Files loaded
Headings --font-heading 'Space Grotesk', system-ui, sans-serif weights 600 and 700
Body --font-body 'Inter', system-ui, sans-serif weights 400, 500, 600 and 700
Code and addresses --font-mono 'JetBrains Mono', monospace weight 400

The body element uses font-body. Headings and large numbers add font-heading. Token addresses, code and numbers in tables use font-mono. Every face sets font-display: swap, so text shows at once in the fallback font.

Components use font-bold (700) on Inter text, so fonts.css loads Inter 700. Load a weight in fonts.css before you use it: a browser that lacks the file draws a false bold.

The interface uses Tailwind’s default type scale. These are the sizes in use, with how often they appear in packages/ui/src (tests excluded):

Class Size Uses
text-xs 0.75rem 78
text-sm 0.875rem 67
text-base 1rem 4
text-lg 1.125rem 12
text-xl 1.25rem 4
text-2xl 1.5rem 8
text-3xl 1.875rem 3
text-4xl to text-7xl 2.25rem to 4.5rem 6

text-xs and text-sm carry most of the interface: labels, menu items, panel text, navigation and buttons.

The home page h1 is font-heading text-6xl font-bold tracking-tight md:text-7xl (Home.tsx). Section h2 elements are font-heading text-3xl font-bold. tracking-tight is -0.025em.

font-medium (500) is the most common weight, at 56 uses. It marks buttons, navigation and labels. font-bold (700) is for headings. font-semibold (600) is for the primary button and strong labels. Body text is the normal weight (400).

Spacing is Tailwind’s single step: --spacing: 0.25rem. Every gap and padding is a multiple of it.

Use Classes
Gap between small items gap-1, gap-1.5, gap-2 (0.25, 0.375 and 0.5rem)
Gap between rows and groups gap-3, gap-4, gap-6 (0.75, 1 and 1.5rem)
Panel padding p-4, px-4 py-3
Control padding px-3 py-1.5 (compact), px-4 py-2.5 (field), px-5 py-2.5 (button)
Page width container mx-auto px-4

Radius is a small set. rounded-lg (0.5rem) is the default for cards, buttons and fields, with 66 uses. Use rounded-md (0.375rem) for items inside a menu, so they sit inside the menu’s own rounded-lg corner. Use rounded-full for logos, badges and pills.

Class Value Uses
rounded-lg 0.5rem 66
rounded-full 9999px 49
rounded 0.25rem 32
rounded-md 0.375rem 29
rounded-2xl 1rem 1

The breakpoints are Tailwind’s defaults: sm 40rem, md 48rem, lg 64rem and xl 80rem. The interface is built mobile first and adds layout at sm and md.

Three card classes are defined in packages/ui/src/app.css. All use rounded-lg and a one-pixel border.

Class Light theme Dark theme Use
.glass-card bg-surface-glass (white), border-border, backdrop-blur-xl (24px) bg-surface-glass (3 percent white, so the page shows through it), border-border The default card.
.elevated-card bg-surface-raised, border-border, shadow-sm bg-surface-raised, border-border, shadow-elevated A card that sits above the page.
.glow-card bg-surface-raised, border-accent/20, shadow-sm bg-surface-raised, border-accent/20, shadow-glow-accent-subtle The one card that needs attention. Use it rarely.
  • Borders are one pixel. They are border-border: #e4e4e7 on the light theme and 8 percent white on the dark one. An accent border (border-accent/20 to /40) marks hover and focus.
  • Shadows on light surfaces are Tailwind’s shadow-sm and shadow-lg. On dark surfaces depth comes from the surface step and from glow, not from black shadows.
  • --shadow-elevated is 0 4px 24px rgba(0, 0, 0, 0.4).
  • --shadow-glow-accent and --shadow-glow-accent-secondary are 0 0 20px at 30 percent. --shadow-glow-accent-subtle is 0 0 24px at 8 percent.
  • Menus and popovers use shadow-lg, a border-border border, and bg-surface or bg-surface-overlay (ListEditor.tsx).
  • The sticky header is bg-surface/80 with backdrop-blur-lg (16px) and a bottom border (Layout.tsx).

.text-gradient-brand runs from accent to accent-secondary: the bright brand fills, kept on purpose. It appears only on large bold display text (the logo, the home and docs headings, the 404), where WCAG asks for 3:1 rather than 4.5:1. .text-gradient-accent runs from accent-content to accent-content-hover, the text roles, so it stays readable at any size on the light theme. Use either for one short phrase, never for body text, and never use the brand gradient on small text.

Menus, dialogs and the header sit on z-50 (14 uses). z-10 orders content inside a page or a panel. Do not add other values without a reason.

Motion is short, and it eases out of the way.

Kind Value Source
Colour and opacity changes 150 milliseconds, cubic-bezier(0.4, 0, 0.2, 1) Tailwind’s default (--default-transition-duration)
Hover and state changes on controls duration-150 (8 uses), duration-200 (12 uses) Components
Large movements duration-300 (2 uses) Components
Button hover scale(1.02) in 150 milliseconds .btn-primary in app.css
Icon strip scroll-left, linear, repeats .animate-scroll in app.css
Spinner one turn every 2 seconds, linear .icon-spin in app.css
Loading placeholder animate-pulse, still under reduced motion Tailwind

Use transition-colors for colour changes (51 uses) and transition-all only when size or shadow changes too.

app.css has a prefers-reduced-motion: reduce rule for .animate-scroll and for .icon-spin. Both stop. PhysicsCanvas.tsx draws one still frame when the reader asks for less motion. The loading screen in packages/ui/src/prerender/route-loader.ts stops its animation too.

A global rule at the end of app.css stops animate-pulse and makes every transition instant. A hover that grows an element (hover:scale-*) also carries motion-reduce:hover:scale-100, because a transform that only stops animating would still jump. A new animation must come with its own rule.

Icons are Font Awesome Free glyphs (the solid and brand sets, version 7), drawn as inline SVG by packages/ui/src/lib/components/Icon.tsx. Import each glyph by name, for example faChevronDown, so the build keeps only the glyphs in use.

  • A glyph is one em tall and takes its colour from the text around it. Size and tint it with text-* classes.
  • The glyph is decoration. It carries aria-hidden="true". The element that holds it carries the accessible name.
  • spin turns the glyph with .icon-spin.
  • Token and network logos are not icons. They are images from the service, for example /image/1/<address> and /image/<chain id>, drawn on round chips.

Do not add another icon library: use Font Awesome glyphs through Icon.

A choice from a list is a menu. Do not use the native select element, in the interface or on this site.

Why: a native select cannot be styled to the design, it looks different on every system, it cannot show logos, and its open list is drawn by the system and ignores both themes.

What to use instead:

  • In the interface: Headless UI. Menu (MenuButton, MenuItems, MenuItem) is used in ListEditor.tsx and StudioConfigurator.tsx. Popover and Dialog build larger pickers: NetworkSelect.tsx opens a Dialog with a search field and a virtual list of networks with their logos. Listbox is the Headless UI part for a single choice that stays visible as the field’s value. Use it when a menu does not fit.
  • On this documentation site: the theme menu, packages/docs/src/components/ThemeMenu.astro. It replaces the select that Starlight draws for the theme.

How the rule is enforced:

  • packages/ui/eslint.config.js forbids the JSX select element. yarn lint fails on it.
  • packages/docs/scripts/check-no-select.ts runs after the site is built. It fails the build and names the page if any built page contains a select element.

A menu follows the WAI-ARIA menu button pattern. Headless UI does this for you. If you build one by hand, as the theme menu does, it needs all of this:

  • The button has aria-haspopup="menu" and aria-expanded.
  • The list has role="menu". Items are menuitem, or menuitemradio with aria-checked when they set a choice.
  • Arrow keys move between items and wrap. Home and End go to the first and last item. Escape closes the menu and returns focus to the button. A click outside closes it.
  • The current choice has a check mark and a different colour. Colour alone is not enough.

Three button classes are defined in app.css. All use rounded-lg, px-5 py-2.5 and transition-all duration-150.

Class Look Use
.btn-primary Accent gradient (accent to accent-strong), black text, semibold, shadow-glow-accent, grows to 1.02 on hover The one main action on a screen
.btn-secondary Quiet fill (surface-wash), one-pixel border-subtle border, medium weight Other actions
.btn-ghost Transparent, accent text, border-accent/30, accent/5 fill on hover Quiet actions beside a primary

Compact controls inside panels do not use these classes. They use utility classes: rounded-lg px-3 py-1.5 text-xs font-medium transition-colors (see the Publish button in ListEditor.tsx). Icon-only buttons are h-8 w-8 or h-9 w-9, round to rounded-lg, and need an accessible name from title or aria-label.

Fields are quiet. TokenSearch.tsx shows the pattern:

There are two patterns.

  • A field. NetworkSelect.tsx and pages/Docs.tsx use w-full rounded-lg border border-border bg-surface-inset py-2 text-sm with a text-content-strong text role and a placeholder:text-content-faint placeholder. The roles switch with the theme, so a field has one set of classes. A leading search icon sits inside the field, so the field has extra left padding.
  • A search row. TokenSearch.tsx draws the border on the row (border-b border-border-strong bg-surface-inset px-4 py-2) and puts a bare input in it with bg-transparent text-sm and a placeholder:text-content-faint placeholder.

A bare input that removes its own outline must give the row around it a ring: TokenSearch.tsx, NumberStepper.tsx and the list filter in TokenListFilter.tsx use focus-within:ring-2 focus-within:ring-accent/50 on the row. The list name field in ListEditor.tsx has no row, so it uses focus-visible:ring-2 focus-visible:ring-accent/50 on the input.

  • Dialogs use Headless UI Dialog, DialogPanel and a backdrop with backdrop-blur-sm (NetworkSelect.tsx, TokenDetailModal.tsx).
  • Collapsible panels use Disclosure.
  • Long lists use a virtual list (@tanstack/react-virtual) so only visible rows exist.

Every control that takes input must show where focus is.

  • On the interface, focus uses the accent: focus:ring-2 focus:ring-accent/50, or focus:border-accent/40 to /60 on fields. focus-visible: is used where a mouse click must not show a ring.
  • On this site, controls use outline: 2px solid var(--sl-color-accent) with a 2 pixel offset, on :focus-visible (see LinkedCard.astro and ThemeMenu.astro).
  • Never remove an outline without giving something else in its place. Bare inputs put the ring on the row around them (see Inputs).
  • Contrast. Body text (content-strong) is a near-black on white and a near-white on #09090b. These ratios use the standard relative luminance formula: accent #00dc82 on #09090b is 10.95 to 1, and black on #00dc82 is 11.56 to 1, so the primary button passes. Accent #00b368 on #09090b is 7.25 to 1.
  • Accent text has its own roles. The raw accent does not reach 4.5 to 1 on white (#00dc82 is 1.82 to 1 and #00b368 is 2.75 to 1), so it is for fills, borders and glows. Text and icons use accent-content (#00703f on light, 6.20 to 1 on white and 5.56 to 1 on the accent tint behind it; the accent itself on dark, 9.55 to 1 or better), accent-content-hover for the hover colour and accent-secondary-content for the blue accent (#0369a1 on light, 5.93 to 1). A test in design-tokens.test.ts holds all three at 4.5 to 1 or better on every background they sit on. Never put white text on an accent fill: it is 1.82 to 1. Use black, as btn-primary does. A visible hover or focus colour is only a hint: the link must also be readable, by position, an underline or an icon.
  • Keyboard. Everything that works with a mouse works with a keyboard. Use native button and a elements. Do not put a click handler on a div.
  • Names. An icon-only control needs aria-label or title. Decoration, including icons and logos beside a name, is aria-hidden="true" with an empty alt.
  • Motion. Follow the reduced-motion rules above.
  • Not by colour alone. State is shown with text, an icon or a check mark as well as colour.
  • Language. The page sets lang="en" (packages/ui/index.html).