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.
Principles
Section titled “Principles”- 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
accentrole is the only brand colour.accent-secondaryappears 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
selectelement 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.
Colour
Section titled “Colour”The naming rule
Section titled “The naming rule”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.
How the roles work
Section titled “How the roles work”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.
Roles in use
Section titled “Roles in use”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
| Role | Light theme | Dark theme |
|---|---|---|
content-strong | oklch(21% 0.034 264.665) | #fff |
content-body | oklch(27.8% 0.033 256.848) | color-mix(in oklab, #fff 90%, transparent) |
content-secondary | oklch(37.3% 0.034 259.733) | color-mix(in oklab, #fff 80%, transparent) |
content-control | oklch(37.3% 0.034 259.733) | #fff |
content-muted | oklch(44.6% 0.03 256.802) | oklch(70.7% 0.022 261.325) |
content-subtle | oklch(55.1% 0.027 264.364) | color-mix(in oklab, #fff 50%, transparent) |
content-faint | oklch(70.7% 0.022 261.325) | color-mix(in oklab, #fff 40%, transparent) |
content-ghost | oklch(87.2% 0.01 258.338) | color-mix(in oklab, #fff 20%, transparent) |
content-inverse | #fff | oklch(21% 0.034 264.665) |
Surfaces: the page, cards, wells, menus, control fills and hovered or active fills
| Role | Light theme | Dark theme |
|---|---|---|
surface | #fff | #09090b |
surface-raised | #fff | #111113 |
surface-inset | oklch(98.5% 0.002 247.839) | #1a1a1e |
surface-overlay | #fff | #1a1a1e |
surface-glass | #fff | color-mix(in oklab, #fff 3%, transparent) |
surface-control | oklch(96.7% 0.003 264.542) | #27272a |
surface-selected | #fff | #27272a |
surface-active | oklch(92.8% 0.006 264.531) | #27272a |
surface-wash | oklch(96.7% 0.003 264.542) | color-mix(in oklab, #fff 5%, transparent) |
surface-wash-active | oklch(92.8% 0.006 264.531) | color-mix(in oklab, #fff 10%, transparent) |
surface-handle | oklch(70.7% 0.022 261.325) | color-mix(in oklab, #fff 40%, transparent) |
surface-sheen | color-mix(in oklab, #fff 5%, transparent) | color-mix(in oklab, #fff 5%, transparent) |
surface-sheen-faint | color-mix(in oklab, #fff 2%, transparent) | color-mix(in oklab, #fff 2%, transparent) |
surface-inverse | oklch(21% 0.034 264.665) | #fff |
surface-inverse-hover | oklch(37.3% 0.034 259.733) | oklch(92.8% 0.006 264.531) |
surface-tooltip | oklch(21% 0.034 264.665) | oklch(37.3% 0.034 259.733) |
surface-thumb | #fff | oklch(92.8% 0.006 264.531) |
surface-bright | oklch(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.
| Role | Light theme | Dark theme |
|---|---|---|
surface-backdrop | oklch(21% 0.034 264.665) | oklch(21% 0.034 264.665) |
Scrims
| Role | Light theme | Dark theme |
|---|---|---|
scrim-soft | color-mix(in oklab, #000 20%, transparent) | color-mix(in oklab, #000 40%, transparent) |
Borders
| Role | Light theme | Dark theme |
|---|---|---|
border | #e4e4e7 | rgba(255, 255, 255, 0.08) |
border-strong | oklch(92.8% 0.006 264.531) | #27272a |
border-subtle | oklch(92.8% 0.006 264.531) | color-mix(in oklab, #fff 10%, transparent) |
border-soft | oklch(87.2% 0.01 258.338) | color-mix(in oklab, #fff 10%, transparent) |
border-input | oklch(87.2% 0.01 258.338) | color-mix(in oklab, #fff 20%, transparent) |
border-input-hover | oklch(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
| Role | Light theme | Dark 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
| Role | Light theme | Dark theme |
|---|---|---|
danger | oklch(57.7% 0.245 27.325) | oklch(70.4% 0.191 22.216) |
danger-hover | oklch(63.7% 0.237 25.331) | oklch(70.4% 0.191 22.216) |
danger-strong | oklch(63.7% 0.237 25.331) | oklch(63.7% 0.237 25.331) |
danger-bright | oklch(70.4% 0.191 22.216) | oklch(70.4% 0.191 22.216) |
danger-soft | oklch(97.1% 0.013 17.38) | color-mix(in oklab, oklch(39.6% 0.141 25.723) 20%, transparent) |
Status: success
| Role | Light theme | Dark theme |
|---|---|---|
success | oklch(62.7% 0.194 149.214) | oklch(79.2% 0.209 151.711) |
success-strong | oklch(52.7% 0.154 150.069) | oklch(79.2% 0.209 151.711) |
success-bright | oklch(79.2% 0.209 151.711) | oklch(79.2% 0.209 151.711) |
success-soft | oklch(98.2% 0.018 155.826) | color-mix(in oklab, oklch(39.3% 0.095 152.535) 20%, transparent) |
Status: warning
| Role | Light theme | Dark theme |
|---|---|---|
warning | oklch(55.4% 0.135 66.442) | oklch(85.2% 0.199 91.936) |
warning-soft | oklch(98.7% 0.026 102.212) | color-mix(in oklab, oklch(79.5% 0.184 86.047) 5%, transparent) |
warning-edge | oklch(79.5% 0.184 86.047) | oklch(79.5% 0.184 86.047) |
Status: caution
| Role | Light theme | Dark theme |
|---|---|---|
caution | oklch(55.5% 0.163 48.998) | oklch(82.8% 0.189 84.429) |
caution-soft | oklch(98.7% 0.022 95.277) | color-mix(in oklab, oklch(41.4% 0.112 45.904) 20%, transparent) |
Glow and depth
Section titled “Glow and depth”--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
Light and dark
Section titled “Light and dark”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
themeScriptinpackages/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,darkorsystem) bypackages/ui/src/lib/contexts/ThemeContext.tsx.systemfollows theprefers-color-schemesetting. ThemeToggle(packages/ui/src/lib/components/ThemeToggle.tsx) is the control: one button flips light and dark, and one button turnssystemon or off.
The accent on this documentation site
Section titled “The accent on this documentation site”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 |
Typography
Section titled “Typography”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.
Weights
Section titled “Weights”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 and radius
Section titled “Spacing and radius”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.
Surfaces
Section titled “Surfaces”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 and shadows
Section titled “Borders and shadows”- Borders are one pixel. They are
border-border:#e4e4e7on the light theme and 8 percent white on the dark one. An accent border (border-accent/20to/40) marks hover and focus. - Shadows on light surfaces are Tailwind’s
shadow-smandshadow-lg. On dark surfaces depth comes from the surface step and from glow, not from black shadows. --shadow-elevatedis0 4px 24px rgba(0, 0, 0, 0.4).--shadow-glow-accentand--shadow-glow-accent-secondaryare0 0 20pxat 30 percent.--shadow-glow-accent-subtleis0 0 24pxat 8 percent.- Menus and popovers use
shadow-lg, aborder-borderborder, andbg-surfaceorbg-surface-overlay(ListEditor.tsx). - The sticky header is
bg-surface/80withbackdrop-blur-lg(16px) and a bottom border (Layout.tsx).
Gradient text
Section titled “Gradient text”.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.
Layers
Section titled “Layers”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
Section titled “Motion”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.
Reduced motion
Section titled “Reduced motion”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.
Iconography
Section titled “Iconography”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. spinturns 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.
Components and patterns
Section titled “Components and patterns”Never a native select
Section titled “Never a native select”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 inListEditor.tsxandStudioConfigurator.tsx.PopoverandDialogbuild larger pickers:NetworkSelect.tsxopens aDialogwith a search field and a virtual list of networks with their logos.Listboxis 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.jsforbids the JSXselectelement.yarn lintfails on it.packages/docs/scripts/check-no-select.tsruns after the site is built. It fails the build and names the page if any built page contains aselectelement.
Menu behaviour
Section titled “Menu behaviour”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"andaria-expanded. - The list has
role="menu". Items aremenuitem, ormenuitemradiowitharia-checkedwhen they set a choice. - Arrow keys move between items and wrap.
HomeandEndgo to the first and last item.Escapecloses 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.
Buttons
Section titled “Buttons”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.
Inputs
Section titled “Inputs”Fields are quiet. TokenSearch.tsx shows the pattern:
There are two patterns.
- A field.
NetworkSelect.tsxandpages/Docs.tsxusew-full rounded-lg border border-border bg-surface-inset py-2 text-smwith atext-content-strongtext role and aplaceholder:text-content-faintplaceholder. 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.tsxdraws the border on the row (border-b border-border-strong bg-surface-inset px-4 py-2) and puts a bareinputin it withbg-transparent text-smand aplaceholder:text-content-faintplaceholder.
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, panels and lists
Section titled “Dialogs, panels and lists”- Dialogs use Headless UI
Dialog,DialogPaneland a backdrop withbackdrop-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, orfocus:border-accent/40to/60on 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(seeLinkedCard.astroandThemeMenu.astro). - Never remove an outline without giving something else in its place. Bare inputs put the ring on the row around them (see Inputs).
Accessibility
Section titled “Accessibility”- 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#00dc82on#09090bis 10.95 to 1, and black on#00dc82is 11.56 to 1, so the primary button passes. Accent#00b368on#09090bis 7.25 to 1. - Accent text has its own roles. The raw accent does not reach 4.5 to 1 on white (
#00dc82is 1.82 to 1 and#00b368is 2.75 to 1), so it is for fills, borders and glows. Text and icons useaccent-content(#00703fon 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-hoverfor the hover colour andaccent-secondary-contentfor the blue accent (#0369a1on light, 5.93 to 1). A test indesign-tokens.test.tsholds 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, asbtn-primarydoes. 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
buttonandaelements. Do not put a click handler on adiv. - Names. An icon-only control needs
aria-labelortitle. Decoration, including icons and logos beside a name, isaria-hidden="true"with an emptyalt. - 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).