Khipu Design System

A multi-platform design system for the Khipu payment platform.

| Platform | Package | Registry | |----------|---------|----------| | Web (React/TypeScript) | @khipu/design-system | npmjs.org | | Android (Kotlin/Compose) | com.khipu:design-system | Nexus | | iOS (Swift/SwiftUI) | KhipuDesignSystem | CocoaPods |

Storybook: design.khipu.com

Installation

Web

npm install @khipu/design-system

Android

// build.gradle.kts
dependencies {
    implementation("com.khipu:design-system:0.1.0-alpha.44")
}

iOS

# Podfile
pod 'KhipuDesignSystem'

Prerequisites

• Node.js >= 20.0.0
• React >= 18.0.0
• TypeScript >= 5.0.0

Quick Start

Import Components

import { KdsButton, KdsTextField, KdsCard } from '@khipu/design-system';

function App() {
  return (
    <KdsCard>
      <KdsTextField label="Email" placeholder="Enter your email" />
      <KdsButton variant="contained" color="primary">
        Submit
      </KdsButton>
    </KdsCard>
  );
}

Using Design Tokens

Access design tokens for consistent styling:

import { tokens, colors, spacing, typography } from '@khipu/design-system';

const styles = {
  color: colors.primary.main,        // '#8347AD'
  padding: spacing[4],               // '16px'
  fontFamily: typography.body1.fontFamily,
};

Import CSS Variables (Optional)

import '@khipu/design-system/css';

Using BeerCSS Bundle (For Grails/Legacy Apps)

The design system includes a complete BeerCSS bundle with Material Design 3 components, ideal for Grails applications or projects that prefer utility-based CSS:

<!-- Via CDN -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@khipu/[email protected]/dist/beercss/khipu-beercss.min.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@khipu/[email protected]/dist/beercss/khipu-beercss.min.js"></script>

// Via npm
import '@khipu/design-system/beercss/css';
import '@khipu/design-system/beercss/js';

What's included:

• BeerCSS v4.0.1 (Material Design 3)
• Khipu design tokens (colors, spacing, typography)
• Custom Khipu components
• Vanilla JavaScript utilities (modals, snackbars, sidenav)

See: src/beercss/README.md for complete documentation

Running the Project

Setup

# Clone the repository
git clone [email protected]:khipu/design-system.git
cd design-system

# Install dependencies
npm install

Available Scripts

Development

| Command | Description | |---------|-------------| | npm run dev | Start development mode with watch | | npm run build | Build the library for production | | npm run storybook | Launch Storybook on port 6006 | | npm run build-storybook | Build static Storybook site | | npm run test | Run tests with Vitest | | npm run test:ui | Run tests with Vitest UI | | npm run typecheck | Run TypeScript type checking | | npm run lint | Lint source files | | npm run generate:tokens | Generate Kotlin tokens to dist/ | | npm run generate:tokens:android | Generate tokens to Android project |

Figma Synchronization

Sync design tokens from Figma to code:

| Command | Description | |---------|-------------| | npm run sync:figma | Extract all tokens (colors, typography, effects) | | npm run sync:figma:colors | Extract only color tokens | | npm run sync:figma:typography | Extract only typography styles | | npm run sync:figma:effects | Extract only effects (shadows) | | npm run sync:figma:dry-run | Preview extraction without changes |

Setup required:

export FIGMA_PERSONAL_ACCESS_TOKEN="your_token_here"
npm run sync:figma

See scripts/README.md for detailed documentation.

Storybook

View and interact with components in isolation:

npm run storybook

Open http://localhost:6006 in your browser to explore the component library.

Package Exports

| Export | Description | |--------|-------------| | @khipu/design-system | All components and tokens | | @khipu/design-system/tokens | Design tokens only | | @khipu/design-system/css | CSS variables | | @khipu/design-system/beercss | BeerCSS bundle (CSS + JS) | | @khipu/design-system/beercss/css | BeerCSS CSS only | | @khipu/design-system/beercss/js | BeerCSS JavaScript only | | @khipu/design-system/components/core | Core UI components | | @khipu/design-system/components/domain | Domain-specific components |

Available Components

Core Components (17)

Foundational UI primitives with Khipu theme:

| Component | Description | Storybook | |-----------|-------------|-----------| | KdsButton | Action buttons with variants: contained, outlined, text | ✅ | | KdsTextField | Text input fields with validation support | ✅ | | KdsCheckbox | Checkbox input with multiple sizes and colors | ✅ | | KdsRadioGroup | Radio button group component | ⚪ | | KdsSelect | Dropdown selection component | ⚪ | | KdsModal | Dialog/modal windows with sizes and transitions | ✅ | | KdsCard | Container with header, content, and actions | ✅ | | KdsSpinner | Loading indicator with multiple sizes | ✅ | | KdsLinearProgress | Progress bar indicator | ⚪ | | KdsAlert | Alert/notification messages | ⚪ | | KdsTypography | Text component with semantic variants | ✅ | | KdsTabs | Tab navigation component | ✅ | | KdsLogoHeader | Khipu branded header with logo | ✅ | | KdsChip | Compact element for tags/labels | ⚪ | | KdsSnackbar | Toast notifications | ⚪ | | KdsTooltip | Contextual help tooltips | ⚪ | | KdsAccordion | Expandable/collapsible panels | ⚪ |

Coverage: 9/17 components have Storybook stories (53%)

Domain Components

Planned for future releases - Domain-specific components for the payment platform will be added as the system matures.

Design Tokens

Comprehensive tokens extracted from Figma (Pagos Automáticos - MUI v610):

• Colors - Primary (purple #8347AD), secondary, semantic (success, warning, error, info)
• Typography - Font families (Public Sans, Roboto), sizes, weights, presets
• Spacing - Consistent spacing scale (4px base unit)
• Border Radius - From sm (4px) to full (pill shape)
• Shadows - MUI-compatible elevation system (elevation1-24)
• Transitions - Duration and easing values
• Breakpoints - Responsive design breakpoints (xs, sm, md, lg, xl)

Cross-Platform Token Sync (Android/Compose)

This design system supports exporting tokens to Android/Kotlin for use with Jetpack Compose, ensuring visual consistency across web and mobile platforms.

Single Source of Truth

Tokens are defined in src/tokens/tokens.json and can be exported to:

• TypeScript (web) - src/tokens/index.ts
• Kotlin (Android) - DesignTokens.kt

Generate Kotlin Tokens

# Generate to dist/DesignTokens.kt
npm run generate:tokens

# Generate directly to Android project
npm run generate:tokens:android

Using Tokens in Compose

import com.khipu.client.ui.theme.KdsColors
import com.khipu.client.ui.theme.KdsSpacing
import com.khipu.client.ui.theme.KdsBorderRadius

@Composable
fun PaymentCard() {
    Card(
        colors = CardDefaults.cardColors(
            containerColor = KdsColors.backgroundPaper
        ),
        shape = RoundedCornerShape(KdsBorderRadius.radiusCard),
        modifier = Modifier.padding(KdsSpacing.space4)
    ) {
        Text(
            text = "Payment",
            color = KdsColors.textPrimary
        )
        Button(
            colors = ButtonDefaults.buttonColors(
                containerColor = KdsColors.primaryMain
            )
        ) {
            Text("Pay Now")
        }
    }
}

Available Kotlin Objects

| Object | Contents | |--------|----------| | KdsColors | All color tokens (primary, secondary, semantic, text, background) | | KdsTypography | Font weights, sizes, line heights | | KdsSpacing | Spacing scale (0-24, in 4px increments) | | KdsBorderRadius | Border radius values | | KdsTransitions | Animation durations | | KdsBreakpoints | Responsive breakpoints |

Workflow

1. Update tokens in src/tokens/tokens.json
2. Run npm run generate:tokens:android
3. Commit both tokens.json and the generated DesignTokens.kt

TypeScript Support

All components are fully typed. Import types alongside components:

import {
  KdsButton,
  type KdsButtonProps,
  type KdsButtonVariant,
  type KdsButtonColor
} from '@khipu/design-system';

Project Structure

src/
├── index.ts              # Main entry point
├── tokens/
│   ├── index.ts          # Design tokens (source of truth)
│   ├── tokens.json       # Generated - JSON format
│   └── css-variables.css # Generated - CSS custom properties
├── theme/
│   ├── index.ts          # MUI theme configuration
│   └── ThemeProvider.tsx # Theme provider component
└── components/
    ├── core/             # 17 Core UI components (Kds* prefix)
    │   ├── KdsButton/
    │   ├── KdsTextField/
    │   ├── KdsCheckbox/
    │   ├── KdsRadioGroup/
    │   ├── KdsSelect/
    │   ├── KdsModal/
    │   ├── KdsCard/
    │   ├── KdsSpinner/
    │   ├── KdsLinearProgress/
    │   ├── KdsAlert/
    │   ├── KdsTypography/
    │   ├── KdsTabs/
    │   ├── KdsLogoHeader/
    │   ├── KdsChip/
    │   ├── KdsSnackbar/
    │   ├── KdsTooltip/
    │   └── KdsAccordion/
    └── domain/           # Future: Domain-specific components
        └── (empty)

License

MIT