Humo UI

React component library and design system for Humo.

Ready-to-use, fully typed and styled components for building Humo interfaces — with a unified design-token system, theming via CSS variables, and live documentation in Storybook.

Table of Contents

• Features
• Installation
• Quick Start
• Components
• Icons
• Design Tokens & Theming
• Development
• Build & Publishing
• Tech Stack
• Project Structure
• Code Style

Features

• 🎨 Unified design system — colors, spacing, and semantic tokens exposed as CSS variables.
• 🧩 22+ components — from buttons and inputs to ready-made credit and deposit calculators.
• 🪙 SVG icons as React components — with controllable width, height, and fill.
• 🔡 Fully typed — every component ships with .d.ts declarations.
• 📦 ESM + CJS — dual build compatible with any bundler.
• 📚 Storybook — live documentation and a development playground.

Installation

npm install humo-ui
# or
yarn add humo-ui

react and react-dom (18 or 19) are peer dependencies — make sure they are installed in your project.

Quick Start

Import the styles once at the root of your app (they include the design tokens and base styles):

// main.tsx / App.tsx
import 'humo-ui/dist/esm/index.css';

Then use the components:

import { Button, Input } from 'humo-ui';

export function Example() {
  return (
    <form>
      <Input label="Amount" appearance="currency" />
      <Button appearance="primary" size="m">
        Submit
      </Button>
    </form>
  );
}

Example: Button

<Button
  appearance="primary"   // 'primary' | 'secondary' | 'transparent'
  size="m"               // 's' | 'm' | 'l'
  isLoading={false}
  isDisabled={false}
  beforeIcon={<Icon />}
  onClick={() => {}}
>
  Buy
</Button>

Components

| Component | Purpose | | -------------------- | -------------------------------------------------------- | | Accordion | Collapsible sections | | Banner | Informational banners | | Breadcrumbs | Navigation breadcrumbs | | Button | Buttons (3 appearances, 3 sizes, loading/disabled state) | | Card | Content cards | | Carousel | Carousel / slider | | Chips | Chips / tags | | Dropdown | Dropdown list | | Footer | Site footer | | Header | Site header | | Input | Text input (incl. currency mode, errors, hints) | | Link | Styled links | | Loader | Loading indicator | | Pagination | Page navigation | | Popover | Tooltips / floating menus | | Radio | Radio buttons and groups | | SelectInput | Select with search and options | | Stepper | Step indicator | | Tabs | Tabs | | CreditCalculator | Credit calculator | | DepositCalculator | Deposit calculator | | IslamicCalculator | Islamic financing calculator |

The full prop reference and interactive examples are available in Storybook (npm run storybook).

Icons

A set of SVG icons is implemented as React components in src/icons and accepts width, height, and fill:

<ChevronRight width="16px" height="16px" fill="#F76835" />

Available: AppGallery, AppStore, GooglePlay, ChevroneLeft, ChevronRight, RightArrow, Facebook, Instagram, Telegram.

⚠️ Icons are not yet re-exported from the package entry point (src/index.ts only exports components). To make them available via import { ChevronRight } from 'humo-ui', add export * from './icons'; to src/index.ts.

Design Tokens & Theming

Design tokens are defined as CSS variables across three layers:

• color-tokens.css — primitives (--neutral-0, --accent-400, --red-500, …).
• semantic-tokens.css — semantic roles (--bg-base-default, --fg-base-default, --border-error, …).
• spacing.css — spacing and sizing.

Components rely only on semantic tokens, so the look can be customized without rebuilding — just override the variables you need:

:root {
  --bg-base-default: var(--neutral-0);
  --fg-base-default: var(--neutral-900);
}

Only a light theme ships out of the box. Since everything is built on CSS variables, you can add an alternative theme by overriding the semantic tokens in your own selector (e.g. [data-theme='dark']).

Development

# Install dependencies
npm install

# Run Storybook (localhost:6006)
npm run storybook

# Lint and format
npm run lint
npm run format

Component structure

Each component is a self-contained folder with a predictable layout:

src/components/Button/
├── Button.tsx            # implementation
├── styles.module.scss    # styles (SCSS Modules)
├── Button.stories.tsx    # Storybook documentation
└── index.tsx             # re-export

Styles are wired up via SCSS Modules and the customClsx utility (a small in-house clsx implementation).

Build & Publishing

# Build the package (ESM + CJS + types) into dist/
npm run build

# Build a static Storybook
npm run build-storybook

# Deploy Storybook to GitHub Pages
npm run deploy-storybook

The Rollup build runs in two passes:

1. JS bundles — dist/esm and dist/cjs (with minification and autoprefixing for styles).
2. Types — dist/index.d.ts via rollup-plugin-dts.

Tech Stack

• React 18 / 19 (peer dependency)
• TypeScript 5
• Rollup — builds ESM + CJS + .d.ts
• SCSS Modules + CSS variables (design tokens)
• Storybook 10 — documentation and development
• ESLint 9 + Prettier — code quality and consistent style

Project Structure

src/
├── components/   # UI components
├── icons/        # SVG icons as React components
├── tokens/       # design tokens (color / semantic / spacing)
├── utils/        # helpers (customClsx, calculator logic)
├── types/        # shared types
├── images/       # raster assets
├── styles.css    # base styles
└── index.ts      # package entry point

Code Style

For VS Code, it's recommended to enable format-on-save and ESLint auto-fix on save (Cmd/Ctrl + Shift + P → Preferences: Open User Settings (JSON)):

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "always"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "[typescript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[typescriptreact]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
  "[scss]": { "editor.defaultFormatter": "esbenp.prettier-vscode" }
}