IFRC GO UI

IFRC GO UI is a React components library for the IFRC GO platform and its associated initiatives.

Built with

Installation

Install the @ifrc-go/ui package and its peer dependencies.

# using pnpm
pnpm install @ifrc-go/ui
# using npm
npm install @ifrc-go/ui

Usage

import { Button } from '@ifrc-go/ui';

function Example() {
    const handleButtonClick = () => {
        console.warn('button clicked');
    };

    return (
        <Button
            name="button"
            onClick={handleButtonClick}
            styleVariant="action"
        >
            Button
        </Button>
    );
}

Design System Philosophy

The layout system establishes a foundation for building interfaces that feel fluid, consistent, and naturally responsive. It minimizes repetitive styling decisions while maintaining precise spatial rhythm across the UI.

Tight, Opinionated Layouts

Ad‑hoc manual styling is discouraged. Layout components provide default spacing and alignment, ensuring design rhythm consistency.

Composition Over Customization

Use pre‑defined primitives (Container, InlineLayout, BlockView, etc.) instead of manual CSS tweaks.

Naturally Responsive Fluid Layouts

Every layout primitive flows naturally with available space. Components expand, shrink, and align seamlessly without relying on fixed widths or explicit breakpoints.

Responsiveness is inherent—inline flows align, block flows stack, and grids re‑flow automatically. Developers rarely need to write custom media queries.

Consistent Spacing System

All spacing uses a unified token scale, ensuring predictable rhythm and easy collaboration between design and development.

Optical Correction

Subtle optical adjustments compensate for line‑height inconsistencies (e.g., in ListView), producing visually balanced layouts.

UI Layout Concepts

ListView

ListView represents a layout structure designed to display multiple related items following a consistent spatial rhythm It abstracts repetitive spacing/alignment so each item can focus on content. It supports three predefined layout modes — inline, block, and grid — to cover a wide range of patterns without manual styling.

Design goals

• Unified rhythm: Centralizes spacing, dividers, and density across lists.
• Natural responsiveness: Lists adapt by wrapping, stacking, or re‑flowing columns.
• Optical balance: Subtle corrections (e.g., for text line-height) ensure rows look evenly spaced.
• Tight layouts: The list, not its items, manages spacing.

Visual mental models

Inline: one‑dimensional flow (chips/actions)

[Tag] [Tag] [Tag] [Tag]

Block: vertical reading flow (rows)

• Row A
• Row B
• Row C

Grid: two‑dimensional gallery (cards)

[Card][Card][Card]
[Card][Card][Card]

Conceptual behaviors by mode

Inline – flows left→right; supports wrapping or truncation.
Block – stacks vertically; uses consistent rhythm and dividers.
Grid – manages both target column count and minimum card width, reserving gutter space for balance.

Spacing and semantics

• The list owns its space; items avoid external margins.
• Spacing tokens ensure alignment across modes.
• Semantic structure uses proper list roles and preserves keyboard order.

Composition examples

• Settings panel → ListView(block) + inset dividers.
• Card gallery → ListView(grid) + cards using BlockView.
• Metadata chips → ListView(inline) with compact density.

InlineLayout

InlineLayout arranges elements horizontally in a single visual line. It’s designed for content with clear before and after anchors.

Structure

Before → Content → After

Before: leading visuals or icons.
Content: main label or text; expands to fill space.
After: trailing actions or indicators.

Key ideas

• Single-line composition — no wrapping.
• Uses spacing tokens for consistent horizontal rhythm.
• Vertical alignment via optical baseline, not bounding box.
• Overflow handled by truncation in content.

When to use

• Buttons or navigation items.
• List rows with icons/actions.
• Inputs with prefix/suffix.
• Any case needing stable inline alignment.

InlineView — Concept

InlineView adapts the InlineLayout model for constrained spaces. It keeps Before + Content on the same line and lets After lift above when width is limited.

Visual model

Normal width:

[●]  Title of the item                                  [⋯]

Constrained width:

                              [⋯]
[●]  Long content title that wraps

Principles

• Container-query driven: adapts to container width, not viewport breakpoints.
• Maintains stable reading order and focus.
• Token-based spacing; no ad‑hoc margins.
• Ensures optical alignment across lines.

Use cases

• List rows with actions that should stay visible.
• Settings lines with long labels.
• Headings with metadata that move above gracefully.

InlineLayout vs InlineView

• InlineLayout: fixed single-line pattern.
• InlineView: adaptive variant that wraps gracefully under constraint.

BlockView

BlockView defines vertical stacking for header–content–footer structures — cards, forms, panels, or page sections.

Mental model

┌──── BlockView ────┐
│ Header (optional) │
│ Content           │
│ Footer (optional) │
└───────────────────┘

Principles

• Encodes hierarchy through space, not borders.
• Uses spacing tokens to control vertical rhythm.
• Supports optional dividers (none / inset / full‑bleed).
• Applies optical compensation for mixed typography.

Composition

• Header → InlineLayout for titles/actions.
• Content → nested BlockViews or lists.
• Footer → actions or summaries.

Use cases

Cards, dashboards, forms, or document sections that need predictable vertical rhythm.

Container

Container is the universal section wrapper used across pages, cards, sidebars, and in‑page groups. It provides alignment, gutters, and visual context for nested layout primitives and is intended to cover most common layout use case scenarios throughout the system.

Mental model

Container (Section)
├─ Header / Toolbar
├─ Content (lists, grids, forms)
└─ Footer / Actions

Principles

• Acts as the boundary for each section or block.
• Supplies inner padding via spacing tokens; children don’t manage external margins.
• Optionally provides background, shadow, and padding based on the use case, along with overlay states (empty, loading, errored) while maintaining consistent rhythm.

Use cases

• Page sections and panels.
• Card bodies and dashboards.
• Sidebar link groups.
• Nested sub‑sections inside larger compositions.

Spacing System — Tokens & Scaling

The spacing system provides a shared vocabulary paddings and gaps across all layout primitives.

Principles

• Tokens (5xs → 5xl) define a modular scale.
• The useSpacingToken() hook resolves tokens to values.
• Shared across ListView, BlockView, Inline*, and Container.
• Adjusts for optical harmony and density presets (Compact ↔ Comfortable).
• Scales subtly with breakpoints for comfort and consistency.

useSpacingToken resolves semantic spacing tokens into usable CSS values for gaps, padding, or margins.

Design intent

Ensures the entire system speaks one spacing language, decoupling meaning from measurement for future‑proof, theme‑driven design.

• Keeps all components aligned to the same rhythm.
• Maps tokens to theme-aware, relative units (e.g., rem).
• Enables consistent density and scaling without hardcoded numbers.
• Tokens stay meaningful while values stay flexible.
• Components never multiply pixels; spacing math lives inside the resolver.
• Works across layout primitives to keep rhythm unified.

Changelog

The changelog file summarizes the changes made to the library across different releases. The changelog is regularly updated to reflect what's changed in each new release.

Contributing

See contribution guide →

License

MIT