onecart-ui
Version:
OneCart UI: Cross-platform design tokens + React & React Native components
396 lines (301 loc) • 8.58 kB
Markdown
# OneCart UI
Cross-platform design system with React & React Native components and design tokens.
## Installation
```bash
npm install onecart-ui
```
## Usage
### For Web Projects (React)
```typescript
// Import components
import { Display, Heading, Body, Utility } from 'onecart-ui';
// Import icons
import { Home, Search, ShoppingCart, Menu } from 'onecart-ui/icons';
// Import tokens
import { tokens } from 'onecart-ui/tokens';
function App() {
return (
<div>
<div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
<Home size={32} color="#2ecc71" />
<Heading size="xl">Welcome</Heading>
</div>
<Body size="lg">This is a web component</Body>
<Display size="2xl">$49.99</Display>
<Utility variant="caption">All components working</Utility>
</div>
);
}
```
### For Mobile Projects (React Native)
```typescript
// Import mobile components
import { Display, Heading, Body, Utility } from 'onecart-ui/mobile';
// Import icons
import { Home, Search, ShoppingCart, Menu } from 'onecart-ui/icons';
// Import tokens
import { tokens } from 'onecart-ui/tokens';
function App() {
return (
<View>
<View style={{ flexDirection: 'row', alignItems: 'center', gap: 8 }}>
<Home size={32} color="#2ecc71" />
<Heading size="xl">Welcome</Heading>
</View>
<Body size="lg">This is a mobile component</Body>
<Display size="2xl">$49.99</Display>
<Utility variant="caption">All components working</Utility>
</View>
);
}
```
### Design Tokens
```typescript
// Web tokens
import { tokens } from "onecart-ui/tokens/web";
// Mobile tokens
import { tokens } from "onecart-ui/tokens/mobile";
// Use tokens in your styles
const styles = {
color: tokens.NEUTRAL_80,
fontSize: tokens.BODY_MD_FONT_SIZE,
};
```
### Icons
```typescript
// Import specific icons
import { Home, Search, ShoppingCart } from 'onecart-ui/icons';
function MyComponent() {
return (
<div>
{/* Default size (24px) */}
<Home size={24} />
{/* Different sizes - use numeric values */}
<Search size={16} /> {/* Small */}
<Search size={20} /> {/* Medium-small */}
<Search size={24} /> {/* Default */}
<Search size={32} /> {/* Large */}
<Search size={40} /> {/* Extra large */}
<Search size={48} /> {/* Custom size */}
{/* With color */}
<ShoppingCart size={24} color="#FF5733" />
{/* With className and style (web only) */}
<Home
size={32}
color="blue"
className="my-icon"
style={{ marginRight: 8 }}
/>
</div>
);
}
```
## Components
### Typography Components
Typography components are available for both web and mobile platforms:
**Web (React):**
```typescript
import { Display, Heading, Body, Utility } from "onecart-ui";
```
**Mobile (React Native):**
```typescript
import { Display, Heading, Body, Utility } from "onecart-ui/mobile";
```
#### Display Component
- **Sizes**: `2xl`, `xl`
- **Usage**: Large hero text and prominent headings
```typescript
<Display size="2xl">Large Display Text</Display>
<Display size="xl">Smaller Display</Display>
```
#### Heading Component
- **Sizes**: `xl`, `lg`, `md`, `sm`, `xs`, `2xs`
- **Usage**: Section titles and semantic headings
```typescript
<Heading size="xl">Extra Large Heading</Heading>
<Heading size="lg">Large Heading</Heading>
<Heading size="md">Medium Heading</Heading>
<Heading size="sm">Small Heading</Heading>
<Heading size="xs">Extra Small Heading</Heading>
<Heading size="2xs">Tiny Heading</Heading>
```
#### Body Component
- **Sizes**: `xl`, `lg`, `md`, `sm`
- **Usage**: Paragraph text and content
```typescript
<Body size="xl">Emphasized content text</Body>
<Body size="lg">Introduction text</Body>
<Body size="md">Standard paragraph text</Body>
<Body size="sm">Caption or secondary text</Body>
```
#### Utility Component
- **Variants**: `button`, `link`, `caption`
- **Usage**: UI labels and metadata
```typescript
<Utility variant="button">BUTTON TEXT</Utility>
<Utility variant="link">Link Text</Utility>
<Utility variant="caption">Caption text</Utility>
```
### Icons
```typescript
import {
Home,
Search,
ShoppingCart,
Menu,
Notifications,
Add,
Remove,
} from "onecart-ui/icons";
```
- **Sizes**: Numeric values (16, 20, 24, 28, 32, 40, 48, etc.)
- **Colors**: Any valid color string
```typescript
<Home size={24} color="#2ecc71" />
<Search size={20} color="#3498db" />
<ShoppingCart size={32} color="#FF5733" />
```
## 📱 Complete Mobile Example
```typescript
import React from 'react';
import { View, ScrollView, StyleSheet } from 'react-native';
import { Display, Heading, Body, Utility } from 'onecart-ui/mobile';
import { Home, ShoppingCart } from 'onecart-ui/icons';
function ProductCard() {
return (
<View style={styles.card}>
<View style={styles.header}>
<ShoppingCart size={32} color="#2ecc71" />
<Heading size="xl">Product Card</Heading>
</View>
<Display size="xl">$49.99</Display>
<Utility variant="caption">Free shipping</Utility>
<Body size="lg">Premium Wireless Headphones</Body>
<Body size="md">
Crystal-clear audio with active noise cancellation and 30-hour battery life.
</Body>
</View>
);
}
const styles = StyleSheet.create({
card: {
backgroundColor: 'white',
borderRadius: 12,
padding: 16,
},
header: {
flexDirection: 'row',
alignItems: 'center',
gap: 8,
},
});
```
## ⚙️ React Native Setup
### Dependencies
```json
{
"dependencies": {
"onecart-ui": "^0.2.4",
"react": "19.2.0",
"react-native": "0.83.1",
"react-native-svg": "^15.15.1"
}
}
```
### Installation
```bash
npm install onecart-ui react-native-svg
```
### iOS Setup
```bash
cd ios && pod install
```
### Metro Config
Add the following to `metro.config.js` to ensure proper React resolution:
```javascript
const path = require("path");
const config = {
resolver: {
extraNodeModules: {
react: path.resolve(__dirname, "node_modules/react"),
"react-native": path.resolve(__dirname, "node_modules/react-native"),
},
},
};
module.exports = config;
```
## Development
This is a monorepo managed with npm workspaces and Turbo.
```bash
# Install dependencies
npm install
# Build all packages
npm run build
# Run development mode
npm run dev
# Generate design tokens
npm run generate-tokens
```
## Package Structure
```
onecart-ui/
dist/ # Built components (web & mobile)
tokens/ # Design tokens (CSS, JS)
icons/ # Icon components
packages/
tokens/ # Token source & generator
components/ # Component source
icons/ # Icon source & generator
apps/
docs/ # Storybook documentation
```
## Development Workflow
### Building the Design System
```bash
# Build all packages (optimized - uses cached SVGs)
npm run build
# Build with watch mode for development
npm run dev
# Build specific packages
cd packages/components && npm run build
cd packages/tokens && npm run build
cd packages/icons && npm run build
```
**Note:** The build process is optimized to be fast. Icon SVG files are committed to the repository, so builds don't require Figma API access or downloading assets.
### Syncing Icons from Figma
When icons are updated in Figma or new icons are added:
```bash
# In packages/icons directory
cd packages/icons
npm run sync:icons
```
This will:
1. Fetch the latest icons from Figma
2. Download SVG files to `packages/icons/svg/`
3. Generate React components for both web and React Native
4. Update the icon metadata
**After syncing, commit the updated SVG files:**
```bash
git add packages/icons/svg/ packages/icons/icons-metadata.json
git commit -m "chore: sync icons from Figma"
```
**Requirements for icon sync:**
- `.env` file with `FIGMA_PERSONAL_ACCESS_TOKEN` and `FILE_ID`
- The Figma file must have an "Icon" page with icon components
### Working with Design Tokens
```bash
# Sync tokens from Figma (requires Tokens Studio plugin)
npm run generate-tokens
```
## Next Steps
See bottom of generated setup output for roadmap suggestions.
## Token Sync (Figma / Tokens Studio)
The tokens pipeline supports pulling design tokens from a Figma file using `figma-token-engine`.
1. Copy `.env.example` to `.env` at repo root.
2. Fill in:
- `FIGMA_PERSONAL_ACCESS_TOKEN`
- `FIGMA_FILE_ID`
3. Generate tokens:
```bash
npm run generate-tokens
```