Jiwambe UI Components

A comprehensive design system with design tokens, UI components, hooks, and utilities. Built with TypeScript and designed for responsive, accessible applications.

📦 Installation

npm install jiwambe-ui-components
# or
yarn add jiwambe-ui-components
# or
pnpm add jiwambe-ui-components

🖼️ Logo Components

Brand logos are included as React components for easy integration:

import { LogoIcon, LogoFull, LogoFleet } from 'jiwambe-ui-components';

// Icon variant (circular)
<LogoIcon size={48} color="#131515" />

// Full logo with text
<LogoFull height={40} color="#131515" />

// Fleet variant
<LogoFleet height={40} color="#131515" />

Logo Variants:

• LogoIcon: Circular icon (850x850) for app icons, favicons, compact spaces
• LogoFull: Full horizontal logo (3293x850) for headers, footers
• LogoFleet: Fleet variant (4754x850) for fleet-specific branding

See LOGO_SETUP_GUIDE.md for complete usage and customization options.

🔘 Button Component

A comprehensive button component with multiple variants, sizes, and states extracted from Figma:

import { Button } from 'jiwambe-ui-components';

// Primary button (default)
<Button>Click me</Button>

// Secondary variant
<Button variant="secondary">Secondary</Button>

// Inverse variant (for dark backgrounds)
<Button variant="inverse">Inverse</Button>

// Ghost variant (transparent background)
<Button variant="ghost">Ghost</Button>

// Large size
<Button size="lg">Large Button</Button>

// With icons
<Button iconLeft={<Icon />}>With Icon</Button>
<Button iconRight={<ArrowIcon />}>Next</Button>

// Icon only
<Button iconOnly iconLeft={<Icon />} aria-label="Close" />

// States
<Button disabled>Disabled</Button>
<Button loading>Loading...</Button>

// Full width
<Button fullWidth>Full Width</Button>

Button Variants:

• Primary: Green background (#005748), white text - for main actions
• Secondary: Light gray background (#f5f6f6), dark text - for secondary actions
• Inverse: White background, dark text - for use on dark surfaces
• Ghost: 75% white opacity background - for subtle actions

Sizes:

• sm (default): 40px height, 16px text
• lg: 48px height, 18px text

Features:

• ✅ All states: default, hover, pressed, focus, disabled
• ✅ Icon support (left, right, or icon-only)
• ✅ Loading state
• ✅ Full width option
• ✅ Accessible (focus rings, ARIA support)
• ✅ TypeScript types included

🔗 Link Component

A comprehensive link component with multiple variants and states for both standalone and in-text links:

import { Link } from 'jiwambe-ui-components';

// Regular standalone link (bold, green)
<Link variant="regular" href="/about">About Us</Link>

// In-text link - primary (default, dark text → green on hover)
<p>
  Read our <Link href="/terms">terms and conditions</Link>
</p>

// In-text link - secondary (gray text → green on hover)
<Link variant="in-text-secondary" href="/help">Learn more</Link>

// In-text link - inverse (for dark backgrounds)
<Link variant="in-text-inverse" href="/contact">Contact</Link>

// External link (opens in new tab)
<Link external href="https://example.com">External Site</Link>

// Different sizes
<Link size="sm" href="/small">Small Link</Link>
<Link size="lg" href="/large">Large Link</Link>

// States
<Link disabled>Disabled Link</Link>
<Link noUnderline href="/no-underline">No Underline</Link>

Link Variants:

• regular: Standalone link - Instrument Sans SemiBold, green color (#005748)
• in-text-primary (default): For use in paragraphs - starts dark (#131515), turns green on hover
• in-text-secondary: Lighter gray (#4b5353) → green on hover
• in-text-inverse: White text for dark backgrounds

Features:

• ✅ All states: default, hover, active, focus, disabled
• ✅ Focus rings for accessibility
• ✅ External link support (target="_blank")
• ✅ Responsive typography
• ✅ Customizable underline
• ✅ TypeScript types included

🎨 Design Tokens

This design system provides a complete set of design tokens extracted from Figma, including:

Colors

import { colors, semanticColors } from 'jiwambe-ui-components';

// Base colors
colors.neutral[950]  // #131515
colors.green[900]    // #005646
colors.red[800]      // #bf2516
colors.yellow[800]   // #9c660c

// Semantic colors
semanticColors.text.primary
semanticColors.action.destructive
semanticColors.status.success

Color Palettes:

• Neutral: 12 shades (0, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950)
• Green: 11 shades (50-950)
• Red: 11 shades (50-950)
• Yellow: 11 shades (50-950)

Typography

import { typography, fontFamilies } from 'jiwambe-ui-components';

// Font families
fontFamilies.heading  // "Instrument Sans"
fontFamilies.body     // "Inter"

// Typography styles (responsive)
typography.title.xl.small    // For small screens
typography.title.xl.large    // For large screens (≥1024px)
typography.body.md.small
typography.button.md.large

Typography System:

• Titles: xl, lg, md, sm (using Instrument Sans)
• Body: md, sm, xs (regular and medium weights, using Inter)
• Links: Regular and medium weights
• Buttons: md, sm
• Labels: md, xs

Spacing

import { spacing, spacingAliases } from 'jiwambe-ui-components';

// Base spacing scale
spacing[0]    // 0px
spacing[8]    // 8px
spacing[16]   // 16px
spacing[24]   // 24px
spacing[128]  // 128px

// Semantic aliases
spacingAliases.xs    // 4px
spacingAliases.sm    // 8px
spacingAliases.md    // 16px
spacingAliases.lg    // 24px
spacingAliases.xl    // 32px

Border Radius

import { radius, componentRadius } from 'jiwambe-ui-components';

// Base radius scale
radius.none       // 0px
radius.sm         // 12px
radius.md         // 16px
radius.lg         // 20px
radius.rounded    // 1000px (fully rounded)

// Component-specific
componentRadius.button
componentRadius.card
componentRadius.input

Shadows & Elevation

import { shadows, elevation } from 'jiwambe-ui-components';

// Base shadows
shadows.sm    // Subtle shadow
shadows.md    // Medium shadow (from Figma)
shadows.lg    // Large shadow

// Component elevation
elevation.card.default
elevation.modal.default
elevation.dropdown.default

Breakpoints

import { breakpoints, mediaQueries } from 'jiwambe-ui-components';

// Breakpoint values
breakpoints.xs    // 320px
breakpoints.sm    // 640px (small screens)
breakpoints.md    // 768px
breakpoints.lg    // 1024px (large screens)
breakpoints.xl    // 1280px

// Media queries
mediaQueries.sm   // (min-width: 640px)
mediaQueries.lg   // (min-width: 1024px)

// Helper functions
isSmallScreen()   // < 1024px
isLargeScreen()   // ≥ 1024px

🚀 Usage Examples

Using with CSS-in-JS

import { colors, spacing, typography, shadows } from 'jiwambe-ui-components';

const styles = {
  container: {
    backgroundColor: colors.neutral[0],
    padding: spacing[24],
    borderRadius: radius.md,
    boxShadow: shadows.md,
    ...typography.title.lg.small,
  },
};

Using with Tailwind CSS

You can reference the tokens in your Tailwind config:

// tailwind.config.js
import { colors, spacing, breakpoints } from 'jiwambe-ui-components';

export default {
  theme: {
    colors: {
      neutral: colors.neutral,
      green: colors.green,
      // ... more colors
    },
    spacing,
    screens: {
      sm: `${breakpoints.sm}px`,
      md: `${breakpoints.md}px`,
      lg: `${breakpoints.lg}px`,
      // ... more breakpoints
    },
  },
};

Responsive Typography

import { getTypography, isLargeScreen } from 'jiwambe-ui-components';

const screenSize = isLargeScreen() ? 'large' : 'small';
const titleStyle = getTypography('title', 'xl', screenSize);

// Or use both
const styles = {
  heading: {
    ...typography.title.xl.small,
    '@media (min-width: 1024px)': {
      ...typography.title.xl.large,
    },
  },
};

📱 Responsive Design

The design system is built with a mobile-first approach and includes:

• Small screens (< 1024px): Optimized for mobile and tablet
• Large screens (≥ 1024px): Optimized for desktop and larger displays

import { mediaQueriesRange } from 'jiwambe-ui-components';

const styles = `
  @media ${mediaQueriesRange.smallScreens} {
    /* Mobile/tablet styles */
  }
  
  @media ${mediaQueriesRange.largeScreens} {
    /* Desktop styles */
  }
`;

🎯 Type Safety

All tokens are fully typed with TypeScript for autocomplete and type checking:

import type { 
  ColorPalette, 
  SpacingKey, 
  TypographyVariant,
  BreakpointKey 
} from 'jiwambe-ui-components';

🔧 Development

# Install dependencies
npm install

# Build the package
npm run build

# Watch mode (development)
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint

# Format code
npm run format

📂 Project Structure

jiwambe-ui-components/
├── src/
│   ├── tokens/
│   │   ├── colors.ts         # Color tokens
│   │   ├── typography.ts     # Typography tokens
│   │   ├── spacing.ts        # Spacing tokens
│   │   ├── radius.ts         # Border radius tokens
│   │   ├── border.ts         # Border tokens
│   │   ├── shadows.ts        # Shadow/elevation tokens
│   │   ├── breakpoints.ts    # Responsive breakpoints
│   │   └── index.ts          # Central export
│   ├── components/           # UI components (coming soon)
│   ├── hooks/                # React hooks (coming soon)
│   ├── utils/                # Utility functions (coming soon)
│   └── index.ts              # Main entry point
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── README.md

🎨 Design System Details

Font Families

• Heading: Instrument Sans (Bold, SemiBold)
• Body: Inter (Regular, Medium, SemiBold)

Color Strategy

• Semantic naming: Use semanticColors for UI elements
• Base palette: Use colors for custom implementations
• Accessibility: Helper functions for contrast checking

Spacing Scale

Based on an 8px grid system with values from 0px to 128px

Shadow System

Progressive elevation levels using neutral-900 (#303635) with varying opacity

📄 License

ISC

🤝 Contributing

Contributions are welcome! Please read the contributing guidelines before submitting PRs.

📞 Support

For issues, questions, or suggestions, please open an issue on GitHub.

Built with ❤️ for responsive, accessible web applications.