onecart-ui
Version:
Cross-platform React and React Native component library with white-label support
415 lines (336 loc) • 10.8 kB
Markdown
# Getting Started with onecart-ui
[](https://www.npmjs.com/package/onecart-ui)
Welcome to onecart-ui – a comprehensive cross-platform system built for React and React Native applications. This component library is powered by Figma Design Tokens and provides a consistent component experience across platforms.
## Installation
```bash
# Using npm
npm install onecart-ui react react-native react-native-web
# Using yarn
yarn add onecart-ui react react-native react-native-web
```
## Basic Setup
First, wrap your application with the `ThemeProvider`:
```tsx
import React from "react";
import { ThemeProvider } from "onecart-ui";
function App() {
return <ThemeProvider>{/* Your app content */}</ThemeProvider>;
}
export default App;
```
This will provide the default theme to all components in the library.
## Component Overview
### The Typography System
The typography system consists of four specialized components:
1. **Display**: For large, impactful text like hero headlines
2. **Heading**: For section titles and subtitles
3. **Body**: For paragraph text and general content
4. **Utility**: For specialized text like buttons, links, and captions
3. **Heading**: Semantic headings with subtitle support
4. **Paragraph**: Rich text blocks with spacing and formatting options
## Practical Examples
### Creating a Landing Page Header
```tsx
import { Heading, Text, Paragraph } from "onecart-ui";
function LandingPageHeader() {
return (
<div>
<Heading level="h1">Transform Your Design System</Heading>
<Text variant="labelLg" color="#666666">
Powered by Figma Design Tokens
</Text>
<Paragraph spacing="lg">
Build consistent, accessible interfaces across React and React Native
with our comprehensive typography system.
</Paragraph>
</div>
);
}
```
### Interactive Form with Typography
```tsx
import { Heading, Text, Paragraph } from "onecart-ui";
import { View, TextInput, Button } from "react-native";
function SignupForm() {
return (
<View style={{ maxWidth: 400, padding: 24 }}>
<Heading level="h2">Create Account</Heading>
<Paragraph spacing="lg">
Join thousands of developers building cross-platform apps.
</Paragraph>
<View style={{ marginBottom: 16 }}>
<Text variant="labelMd" style={{ marginBottom: 4 }}>
Email Address
</Text>
<TextInput
style={{
borderWidth: 1,
borderColor: "#ccc",
padding: 8,
borderRadius: 4,
}}
placeholder="you@example.com"
/>
</View>
<View style={{ marginBottom: 24 }}>
<Text variant="labelMd" style={{ marginBottom: 4 }}>
Password
</Text>
<TextInput
style={{
borderWidth: 1,
borderColor: "#ccc",
padding: 8,
borderRadius: 4,
}}
placeholder="••••••••"
secureTextEntry
/>
<Text variant="bodyXs" color="#666666" style={{ marginTop: 4 }}>
Must be at least 8 characters
</Text>
</View>
<Button title="Sign Up" onPress={() => {}} />
</View>
);
}
```
### Typography Components in Detail
The typography system has been separated into distinct components for better modularity:
```tsx
import { Display, Heading, Body, Utility } from "onecart-ui";
function TypographyExamples() {
return (
<>
<Display size="2xl">Large Display Text</Display>
<Heading size="lg">Section Heading</Heading>
<Body size="md">Regular paragraph text for content.</Body>
<Utility variant="button">Button Label</Utility>
<Utility variant="link" element="a" href="#">Link Text</Utility>
<Utility variant="caption">Small caption text</Utility>
</>
);
}
```
### Text
Enhanced text component with decorations and link support:
```tsx
import { Text } from "onecart-ui";
function TextExamples() {
return (
<>
<Text>Regular text</Text>
<Text underline>Underlined text</Text>
<Text strikethrough>Strikethrough text</Text>
<Text italic>Italic text</Text>
<Text weight="bold">Bold text</Text>
<Text underline italic>
Underlined italic text
</Text>
<Text link onLinkPress={() => console.log("Link clicked")}>
This is a link
</Text>
</>
);
}
```
### Heading
Semantic heading component for page and section titles:
```tsx
import { Heading } from 'onecart-ui';
function HeadingExamples() {
return (
<>
<Heading level="h1">Page Title</Heading>
<Heading level="h2" subtitle="More information about this section">
Section Title
</Heading>
<Heading level="h3" align="center" color="#0066CC">
Centered Blue Heading
</Heading>
Section Title
</Heading>
<Heading
level="h3"
align="center"
color="#0066CC"
>
Customized Heading
</Heading>
</>
);
}
```
### Paragraph
Rich text paragraphs with formatting options:
```tsx
import { Paragraph, Text } from "onecart-ui";
function Example() {
return (
<>
<Paragraph>Regular paragraph with default spacing.</Paragraph>
<Paragraph size="lg" spacing="xl">
Large paragraph text with extra large bottom spacing.
</Paragraph>
<Paragraph firstLineIndent={true}>
This paragraph has its first line indented, which is common in printed
books and formal documents.
</Paragraph>
<Paragraph>
You can also include <Text weight="bold">formatted text</Text> within
paragraphs for <Text italic>rich content</Text>.
</Paragraph>
</>
);
}
```
## Custom Theming
You can customize the theme to match your brand:
```tsx
import { ThemeProvider } from "onecart-ui";
// Define custom theme
const brandTheme = {
colors: {
primary: "#8E24AA",
text: {
primary: "#212121",
secondary: "#616161",
header: "#000000",
},
},
typography: {
fontFamily: {
base: "Roboto",
heading: "Roboto Condensed",
},
},
};
function App() {
return (
<ThemeProvider theme={brandTheme}>
{/* Your themed app content */}
</ThemeProvider>
);
}
```
## Complete Application Example
Here's a complete example of a simple article page using all typography components:
```tsx
import React from "react";
import { View, ScrollView } from "react-native";
import { ThemeProvider, Heading, Text, Paragraph } from "onecart-ui";
function ArticlePage() {
return (
<ThemeProvider>
<ScrollView style={{ padding: 16, maxWidth: 800, margin: "0 auto" }}>
<Heading level="h1">Typography System in Design</Heading>
<Text
variant="labelMd"
color="textSecondary"
style={{ marginBottom: 24 }}
>
Posted by Sarah Chen • June 2, 2025 • 5 min read
</Text>
<Paragraph spacing="lg">
Typography is the foundation of any good design system. It establishes
hierarchy, improves readability, and creates visual harmony across
your interfaces.
</Paragraph>
<Heading level="h2">The Importance of Consistency</Heading>
<Paragraph>
When designing cross-platform applications, maintaining consistency
becomes even more crucial. Users expect a cohesive experience
regardless of whether they're using your web app or mobile app.
</Paragraph>
<Paragraph spacing="lg">
The <Text weight="bold">onecart-ui</Text> library solves this by
providing a comprehensive typography system that works seamlessly
across React and React Native, all powered by{" "}
<Text italic>Figma Design Tokens</Text>.
</Paragraph>
<View
style={{
padding: 16,
backgroundColor: "#f5f5f5",
borderRadius: 8,
marginBottom: 24,
}}
>
<Heading level="h3" style={{ marginTop: 0 }}>
Key Benefits
</Heading>
<Paragraph>
• <Text weight="bold">Cross-platform consistency</Text>
</Paragraph>
<Paragraph>
• <Text weight="bold">Semantic markup</Text> for accessibility
</Paragraph>
<Paragraph>
• <Text weight="bold">Token-based styling</Text> for themability
</Paragraph>
<Paragraph>
• <Text weight="bold">Responsive</Text> out of the box
</Paragraph>
</View>
<Heading level="h2">Getting Started</Heading>
<Paragraph spacing="lg">
To implement this typography system in your project, simply install
the package and wrap your application with the{" "}
<Text weight="semibold">ThemeProvider</Text>. Then, you can start
using the various typography components throughout your app.
</Paragraph>
<Paragraph>
For more information, visit our <Text link>documentation site</Text>{" "}
or check out our <Text link>Storybook examples</Text>.
</Paragraph>
</ScrollView>
</ThemeProvider>
);
}
```
## NPM Package
The onecart-ui package is available on npm. It can be installed using:
```bash
npm install onecart-ui
# or
yarn add onecart-ui
```
This package includes all the components, tokens, and utilities needed to build consistent UIs across React and React Native applications.
### React Version Compatibility
This package is compatible with React versions from 16.8.0 through 18.x.
### React Native Compatibility
This library is designed to work with React Native versions from 0.60.0 through 0.73.0 that are compatible with React 18.x. When using with React Native, make sure to follow these steps:
1. Install the required dependencies:
```bash
npm install onecart-ui react-native-web
```
2. For Expo projects, no additional configuration is needed.
3. For bare React Native projects, ensure your Metro config includes the package:
```javascript
// metro.config.js
module.exports = {
resolver: {
extraNodeModules: {
'onecart-ui': path.resolve(__dirname, 'node_modules/onecart-ui'),
},
},
};
```
### Usage in Your Project
After installation, you can import components and use them in your application:
```jsx
import { ThemeProvider, Button, Text } from 'onecart-ui';
function App() {
return (
<ThemeProvider>
<Button variant="primary" onPress={() => console.log('Button clicked')}>
<Text>Click Me</Text>
</Button>
</ThemeProvider>
);
}
```
## License
MIT
export default ArticlePage;
```