@khipu/design-system 0.1.0-alpha.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Khipu SpA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,296 @@
+# Khipu Design System
+
+A multi-platform design system for the Khipu payment platform.
+
+| Platform | Package | Registry |
+|----------|---------|----------|
+| **Web** (React/TypeScript) | `@khipu/design-system` | [npmjs.org](https://www.npmjs.com/package/@khipu/design-system) |
+| **Android** (Kotlin/Compose) | `com.khipu:design-system` | [Nexus](https://dev.khipu.com/nexus/content/repositories/design-system) |
+| **iOS** (Swift/SwiftUI) | `KhipuDesignSystem` | [CocoaPods](https://cocoapods.org/pods/KhipuDesignSystem) |
+
+**Storybook:** [design.khipu.com](https://design.khipu.com)
+
+## Installation
+
+### Web
+```bash
+npm install @khipu/design-system
+```
+
+### Android
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation("com.khipu:design-system:0.1.0-alpha.6")
+}
+```
+
+### iOS
+```ruby
+# Podfile
+pod 'KhipuDesignSystem'
+```
+
+## Prerequisites
+
+- Node.js >= 18.0.0
+- React >= 17.0.0
+
+## Quick Start
+
+### Import Components
+
+```tsx
+import { Button, TextField, Card } from '@khipu/design-system';
+
+function App() {
+  return (
+    <Card>
+      <TextField label="Email" placeholder="Enter your email" />
+      <Button variant="contained" color="primary">
+        Submit
+      </Button>
+    </Card>
+  );
+}
+```
+
+### Using Design Tokens
+
+Access design tokens for consistent styling:
+
+```tsx
+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)
+
+```tsx
+import '@khipu/design-system/css';
+```
+
+## Running the Project
+
+### Setup
+
+```bash
+# Clone the repository
+git clone git@github.com: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:**
+```bash
+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:
+
+```bash
+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/components/core` | Core UI components |
+| `@khipu/design-system/components/domain` | Domain-specific components |
+
+## Available Components
+
+### Core Components
+
+Foundational UI primitives:
+
+| Component | Description |
+|-----------|-------------|
+| `Button` | Action buttons with variants: `contained`, `outlined`, `text` |
+| `TextField` | Text input fields with validation support |
+| `Checkbox` | Checkbox input with multiple sizes and colors |
+| `Select` | Dropdown selection component |
+| `Modal` | Dialog/modal windows |
+| `Card` | Container with `CardHeader`, `CardContent`, `CardActions` |
+| `Spinner` | Loading indicator |
+
+### Domain Components
+
+Khipu-specific components for the payment platform:
+
+| Component | Description |
+|-----------|-------------|
+| `BankSelector` | Bank selection interface |
+| `PaymentStepper` | Multi-step payment flow indicator |
+| `MandateStatusBadge` | Status badge for payment mandates |
+| `PayoutSummaryCard` | Payout information display |
+| `EmptyState` | Empty state placeholder |
+
+## 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
+
+```bash
+# Generate to dist/DesignTokens.kt
+npm run generate:tokens
+
+# Generate directly to Android project
+npm run generate:tokens:android
+```
+
+### Using Tokens in Compose
+
+```kotlin
+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:
+
+```tsx
+import {
+  Button,
+  type ButtonProps,
+  type ButtonVariant,
+  type ButtonColor
+} from '@khipu/design-system';
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts              # Main entry point
+├── tokens/
+│   ├── index.ts          # Design tokens
+│   └── css-variables.css # CSS custom properties
+└── components/
+    ├── core/             # Core UI components
+    │   ├── Button/
+    │   ├── TextField/
+    │   ├── Checkbox/
+    │   ├── Select/
+    │   ├── Modal/
+    │   ├── Card/
+    │   └── Spinner/
+    └── domain/           # Domain-specific components
+        ├── BankSelector/
+        ├── PaymentStepper/
+        ├── MandateStatusBadge/
+        ├── PayoutSummaryCard/
+        └── EmptyState/
+```
+
+## License
+
+MIT