Lomalo Design System

A design system for Lomalo — the Citizen Wallet of the Republic of the Marshall Islands — and its companion marketing site at lomalo.app. Lomalo is run by Lomalo Labs (a unit of M1 Global) in partnership with the RMI government.

The product in one line: a free mobile wallet that holds USDM1 (a sovereign-backed digital instrument secured by U.S. Treasuries, issued by the RMI) and lets citizens receive ENRA individual support distributions and transfer funds instantly across every atoll in the country.

This repo is the design-agent-facing version of the live system. It mirrors the tokens and voice rules used by the real lomalo.app codebase so any generated artifact — slide, mock, prototype, production HTML — is on-brand by default.

Install & use (React kit)

As of v0.2.0 the package ships a React 18 component kit alongside the raw tokens. It builds with Vite and is consumable as a Figma Make kit (see below).

npm install @m1global/lomalo-design-system

import { Button, Hero, Card, tokens } from '@m1global/lomalo-design-system';
import '@m1global/lomalo-design-system/styles.css'; // once, at app root — fonts + tokens + component CSS

Components: Button, Container, SectionLabel, Icon, Card (+ CardIcon/CardTitle/CardBody), Badge, Input, NavBar, Hero, Footer. Tokens: tokens (and named colors, fonts, space, radius, shadow, motion, text). React and react-dom are peer deps (18+); lucide-react powers Icon.

CSS-only consumers can still import just the tokens: @m1global/lomalo-design-system/tokens.css.

Figma Make kit

This package is structured to drop into Figma Make as a design-system kit (Create a kit → npm packages), so Make generates on-brand UI from the real components. Requirements it satisfies: React 18, builds with Vite, only public deps, and a GUIDELINES.md for Make to read. See GUIDELINES.md for the component/token usage rules and brand voice.

Build the library locally with npm run build (emits dist/). It's published to the public npm registry so Make can install it on any paid plan (Professional included) — see PUBLISHING.md for the runbook and prerequisites.

Source material

Everything here is derived from the m1global/lomalo-site private repo (branch main). Specifically:

| Source file | Lives here as | |-------------|---------------| | design/lomalo-tokens.css | colors_and_type.css (direct port + semantic aliases) | | design/DESIGN.md | summarised in this README | | design/lomalo-ia-v2.md | summarised under Products & Surfaces below | | prompts/_template.md, prompts/help.md, prompts/terms.md, prompts/privacy.md | distilled into CONTENT FUNDAMENTALS below | | scripts/terminology-check.sh | prohibited-term list is reproduced in CONTENT FUNDAMENTALS | | site/index.html | reference palette check for the UI kit | | site/assets/ | empty in the upstream repo — the folder contains only a README describing which files should land there. No logos, photos, icons, or PDFs exist yet. |

Products & surfaces

Lomalo is a funnel — a small set of surfaces, each with a clear audience:

1. lomalo.app marketing site (this design system's main target). 15 pages, Cash-App-light, citizen-first. Information architecture in lomalo-ia-v2.md.
2. Citizen Wallet — the mobile app that actually holds USDM1. Not in this repo; the site design system references it but the app's screens are owned by a separate Figma component library (v2.0) and mobile codebase.
3. Enterprise Wallets — merchant-side tools (Bodega Wallet, Grocery Store Wallet). Surfaced on /enterprise as a splash page; no public product UI on the site.
4. USDM1 due-diligence surface — /usdm1 page and downloadable whitepaper/indenture PDFs for government, investors, regulators.

The marketing site is the only product this design system currently builds UI kits for. The mobile app gets token support and voice rules but no screens (flagged below).

Index

| File | Purpose | |------|---------| | README.md | this file — high-level context, content + visual foundations, iconography | | package.json | npm package manifest — installable as @m1global/lomalo-design-system | | GUIDELINES.md | usage rules + brand voice for the React kit (read by Figma Make) | | PUBLISHING.md | how to publish to public npm for use as a Figma Make kit | | src/ | React 18 component kit + typed tokens (built to dist/) | | components.css / styles.css | component styles; styles.css bundles tokens + components + fonts | | vite.config.ts / tsconfig.json | library build config | | colors_and_type.css | single source of truth for colors, type, spacing, radii, shadows, motion | | fonts/README.md | font delivery notes (all three families are Google-hosted) | | assets/README.md | inventory of brand assets — and the ones that are missing | | assets/ | logos, icons, placeholder imagery (see caveats) | | preview/ | design-system-tab cards (tokens, palette, type specimens, components) | | ui_kits/website/ | pixel-level recreation of the lomalo.app marketing site |

CONTENT FUNDAMENTALS

Lomalo writes for citizens of the Marshall Islands first, institutional audiences second. The house voice is Cash App-light, warm, trust-forward. Tone shifts by page; rules below are the constants.

Voice registers

The IA assigns one of five voice registers to each page. A single design almost never mixes registers.

| Register | Used on | Feels like | |----------|---------|------------| | Citizen | /, /how-it-works/*, /get-lomalo, /help, /community | Friendly, simple, encouraging. Second-person "you". Short sentences. Assumes mobile screen and intermittent 3G. | | Merchant | /enterprise | Practical, benefit-focused. Names the real job to be done ("accept USDM1 transfers", "see transactions in real time"). | | Institutional / Government | /usdm1 (top half) | Formal, specific, restrained. Names partners and legal frameworks. | | Investor | /usdm1 (bottom half) | Precise, quantitative. "Three-frame market position", "Brady-bond lineage". | | Professional | /about, /about/press, /about/contact | Grounded, neutral, press-ready. |

Case, person, punctuation

• Headings use sentence case. "How can we help?" not "How Can We Help?".
• Buttons use title case — but the CTA is nearly always the canonical "Get Lomalo". Other buttons: "Send Question", "Download whitepaper".
• You, not we. "Set up your wallet in minutes." The site is talking to one person.
• No exclamation marks on product copy. Warmth comes from word choice, not punctuation.
• No em-dash-heavy, Claude-voiced prose. Periods. Short lines.
• No emoji in copy. They appear only as list glyphs on the contact section (✉, 📘) and nowhere else.

Prohibited terms (enforced by terminology-check.sh)

A CI script blocks these words from shipping. The design system must follow the same rules — including in placeholder copy, lorem replacement, and speaker notes.

| Never say | Say instead | Why | |-----------|-------------|-----| | UBI, Universal Basic Income | ENRA, individual support distribution | Legal/regulatory — ENRA is the RMI-defined program name | | stablecoin | sovereign-backed digital instrument | Positioning — USDM1 is a sovereign instrument, not a crypto product | | digital dollar | sovereign-backed digital instrument | Same | | CBDC | sovereign-backed digital instrument | Same | | payment instrument | sovereign settlement instrument | Regulatory | | currency (standalone) | sovereign-backed digital instrument | Regulatory | | Outer Islands | specific atoll names, or "across the Marshall Islands" | Cultural respect — the term is colonial and non-specific | | pay (for merchant transactions) | use in stores, transfer funds | Regulatory — USDM1 is not framed as a payment | | money | funds | Regulatory |

USDM1 canonical first-mention (required on any page that names USDM1): "USDM1, a sovereign-backed digital instrument secured by U.S. Treasuries."

Example copy (lifted, unedited, from the real site)

• Hero-grade: "Lomalo is the Citizen Wallet of the Marshall Islands — a free app that lets you send and receive funds instantly across every atoll."
• Plain reassurance: "Your funds are your property — even if the app goes offline, your USDM1 remains safe and redeemable."
• Merchant transaction flow: "Open the app, select 'Send,' enter the merchant's Lomalo ID or scan their QR code, and confirm the amount."
• Zero-fees pitch: "Yes. There are zero fees for citizens to download, register, receive ENRA distributions, or transfer funds to other Lomalo users."

Content don'ts

• No "coming soon" or roadmap hints. If a corridor/feature isn't live, the page doesn't exist. The IA has parked slots for remittance and diaspora — they stay parked until launch.
• No comparison tables until there's a real corridor to compare against.
• No placeholder lorem ipsum in shipped work; mocks should use plausible citizen-voice copy.
• No Marshallese copy until a native-speaker review pipeline exists. Language toggle slot is reserved in the footer but unused.

VISUAL FOUNDATIONS

The aesthetic is warm, trust-forward, Cash-App-light. Think Majuro lagoon at morning light — not crypto-dark, not bank-beige. Every choice below is literally in design/lomalo-tokens.css or the Figma component library v2.0.

Palette

13 unique hex values, 15 named roles. The palette is locked as of 2026-03-09 — new brand work does not add colors; tints are derived with opacity.

• Primary: Lagoon #008DE0. Every CTA, every link, every focus ring. Bright but not neon.
• Secondary: Storm #274E69. Dark surfaces, institutional sections, formal headers.
• Sovereignty: Smalt #003893. Pulled from the RMI flag. Only used in the government/sovereignty narrative — never decoratively.
• Merchant / operator accent: Pizazz #FF9300. Flag orange. Marks enterprise/bodega sections and merchant-facing UI.
• Warm accent: Sunshine #FCAB3D. Softer orange for earthy palettes and informal highlights.
• Warm neutral: Stick Chart #CEC6B6. Named after Marshallese navigation charts. Used for section labels and decorative text.
• Canvas: Warm White #F9F8F6. The default page background — never pure white at page level.
• Card: White #FFFFFF. Cards and modals sit on the warm canvas.
• Text: Black #1A1A1A for primary, Boulder #767676 for secondary (WCAG AA on white).
• Status: Success #008A00, Warning #F19120, Error #AE1100. All status backgrounds are the same hex at 8% opacity.

Typography

Three families, strict roles. Never substitute one for another inside a single surface.

• Poppins — headings. Geometric, slightly tall, friendly. 600/700.
• Inter — body copy and numerical data. 400/500/600/700. Tight tracking on body (-0.43px).
• DM Sans — UI chrome (buttons, badges, nav, captions). 400/500/600. Slightly wider than Inter; reads as "product UI" instead of "article".

The mobile scale is tuned for 375px; the web scale ramps to a 56/40/28/20 heading cadence at 1440px. Full list in colors_and_type.css.

Spacing

4dp base grid, with a named scale (xxxs 2 / xxs 4 / xs 8 / s 16 / s-plus 24 / m 32 / l 40 / xl 64 / xxl 80) plus the full multiples of 4 up to 80. Web layouts add --web-section-gap: 96px between major page sections and a --web-content-max: 1200px centered wrapper with --web-text-max: 680px for body columns.

Radii

• Badges: 4px.
• Default card: 8px.
• Wallet cards / pills: 12px.
• Elevated section: 16px.
• Hero feature cards: 24px.
• Full pill / avatar: 999px.

Nothing hand-tweaked. If a corner doesn't fit this list, change the component, not the value.

Shadows

A four-rung elevation system, all off black at low opacity:

• shadow-card — resting cards. 0 1px 3px at 8%.
• shadow-card-hover — hover. 0 4px 12px at 12%.
• shadow-elevated — feature tiles and app-badge rows. 0 8px 32px at 8%.
• shadow-modal — modals and drawers. 0 16px 48px at 16%.

No inner shadows. No colored shadows.

Backgrounds and imagery

• The canvas is Warm White, always. Dark sections are rare and use Storm or Lagoon.
• Imagery is real photography — Majuro market, atoll landscapes, merchant portraits, citizens using the app. Photos lean warm, natural light, grounded. No stock photography. No crypto screens with floating coins.
• Heroes use real images, not decorative gradients.
• Gradients are avoided. Where color needs to span a section, use a flat brand fill (Lagoon, Storm) with full-bleed photography composited behind at reduced opacity.
• No repeating patterns, no abstract illustration sets. The one decorative motif that is on-brand is the stick chart — the traditional Marshallese navigation chart — referenced in the --stick-chart color name and (optionally) as a subtle SVG texture in institutional surfaces. Not yet drawn in this system; flagged as a future asset.

Borders, transparency, blur

• Borders use Black at 10% (--border-light) for hairlines, 20% (--border) for stronger separators. No colored borders.
• Transparency shows up only in derived tokens (tints, status backgrounds). We do not layer translucent glass.
• Backdrop blur is not used. The aesthetic is flat/earthy, not iOS glass.

Motion

• --duration-fast: 150ms, --duration-normal: 250ms, --duration-slow: 400ms.
• One easing curve: cubic-bezier(0.4, 0, 0.2, 1).
• Hover: opacity drop to ~0.85 on primary buttons (taken straight from site/index.html); subtle shadow-card → shadow-card-hover lift on cards. No scale transforms on hover.
• Press: no scale. Active state darkens fill slightly.
• No bounces, no springs, no parallax. The site has to work on 3G — movement is incidental, never load-bearing.

Layout rules

• Persistent, non-sticky header across every page. Logo left, five nav items center/right, "Get Lomalo" CTA button always visible on mobile.
• Footer has three columns (Product / Learn / Company), app-store badge row, social link, legal links, partner endorsements.
• Max content width 1200px, centered. Body text columns clamp at 680px.
• Mobile container pad: 24px. Desktop: 64px.
• Sections separated by 96px on desktop, 64px on mobile; no visible rules between them — the palette shift does the work.

Cards

Default card: white fill, 8px radius, 1px --border-light, 24px padding, --shadow-card. Hover: --shadow-card-hover. Hero cards (feature tiles on the homepage): same fill, 24px radius, 32px padding, --shadow-elevated, usually with an icon or badge in the top-left.

ICONOGRAPHY

The upstream repo's site/assets/ folder is currently empty — only a README listing which logos, icons, badges, seals, and photos to collect. None of the actual files exist in git yet.

So this design system's assets/ folder contains:

• Real brand wordmarks — lomalo-wordmark-lagoon.png (primary), -black.png, -white.png (with baked-in drop-shadow), and lomalo-app-tile.png (260×260 stacked app tile). All provided by the brand team. the real SVG lands.
• The app tile doubles as favicon and QR-code centerpiece in app-badge contexts.
• Stick-chart motifs — real PNG assets in two crops: stick-chart-banner.png (wide, for right-anchored section backdrops) and stick-chart-square.png (404×404, for cards). The traditional Marshallese navigation-chart pattern, drawn in Stick Chart (#CEC6B6) on transparency.
• Per-feature icons imported from Lucide via CDN. The upstream repo's design guide specifies "consistent stroke weight, single color" for icons; Lucide's 1.5px outlined style is the closest publicly-available match and is the stated substitution until a bespoke Lomalo icon set ships.
• No App Store / Google Play badges in the repo — when needed we render the official badges via their CDN URLs or fall back to text buttons.

Substitutions flagged for the user to replace:

1. Feature icons — currently loaded from https://unpkg.com/lucide-static/icons/*. Swap for the bespoke set once the brand team produces one.
2. RMI government seal (rmi-seal.svg), SDF logo (sdf-logo.svg), MISSA / MoF marks — not present. Trust-signals sections in the UI kit show the text partner name only, with a dashed outline box where the seal would go.
3. Hero photography — not present. Hero blocks in the UI kit render a warm gradient sketch with the caption "real photography goes here" overlaid.

Emoji: not used in product copy. Two exceptions, both in the help page's contact block, taken verbatim from the Stitch prompt: ✉ for email, 📘 for Facebook. Nowhere else.

Unicode as icons: used sparingly. Right-arrow → appears on card CTAs and on the "Get Lomalo →" nav button. Everything else is an SVG.

How to use this folder

1. Include colors_and_type.css at the top of any HTML artifact — Google Fonts import is inside it.
2. Set class="lomalo" on the root of your markup to pick up the semantic element defaults (h1–h4, p, label, caption).
3. Pull UI patterns from ui_kits/website/ (open index.html for a live demo of the marketing site).
4. For icons, either embed Lucide SVG via CDN or read assets/README.md for the placeholder inventory.
5. Before delivery, mentally run terminology-check.sh — no "pay", "UBI", "stablecoin", "currency", "money", "Outer Islands".