npm package: @marcelinodzn/ds-react
Description: Jio Design System - React components for web
Author: Jio Design Team
Latest version: 1.0.6

# @jio/ds-react

React component library for the Jio Design System.

## Quick Start

### Installation

```bash
npm install @jio/ds-react @jio/ds-tokens
```

### Basic Setup

```tsx
import { DsProvider, Button } from '@jio/ds-react';

function App() {
  return (
    <DsProvider
      platform="Desktop (1440)"
      colorMode="Light"
      density="Default"
    >
      <Button appearance="primary">Get Started</Button>
    </DsProvider>
  );
}
```

### Required Provider

All components require the `DsProvider` wrapper:

```tsx
import { DsProvider } from '@jio/ds-react';

<DsProvider
  platform="Desktop (1440)"    // or "Mobile (390)", "Tablet (768)"
  colorMode="Light"             // or "Dark"
  density="Default"             // or "Compact", "Open"
>
  {/* Your app components */}
</DsProvider>
```

### Surface Management

Use `SurfaceProvider` for proper elevation and surface awareness:

```tsx
import { SurfaceProvider, Card } from '@jio/ds-react';

function Layout() {
  return (
    <SurfaceProvider level={0}>  {/* Page background */}
      <Card surface={1}>  {/* Elevated surface */}
        Content here
      </Card>
    </SurfaceProvider>
  );
}
```

---

## Component Usage

### Buttons

```tsx
import { Button, Icon } from '@jio/ds-react';
import IcDownload from '@jio/ds-react/components/Icon/icons/IcDownload';

// Primary button
<Button appearance="primary" size="M">
  Submit
</Button>

// Button with icon
<Button
  appearance="secondary"
  start={<Icon asset={<IcDownload />} size="S" />}
>
  Download
</Button>

// Icon-only button (requires aria-label)
<Button single aria-label="Close">
  <Icon asset={<IcClose />} size="M" />
</Button>
```

### Icons (IMPORTANT: Color Behavior)

**Icons are neutral gray by default. To make them colorful, add `appearance` prop:**

```tsx
import { Icon } from '@jio/ds-react';
import IcStar from '@jio/ds-react/components/Icon/icons/IcStar';

// ❌ Gray icon (no color)
<Icon asset={<IcStar />} size="M" />

// ✅ Colorful icon (brand color)
<Icon
  asset={<IcStar />}
  size="M"
  appearance="secondary"  // Brand color!
  tinted                  // Brand tinting
/>

// ✅ Semantic color (success green)
<Icon
  asset={<IcCheckCircle />}
  size="M"
  appearance="positive"
/>
```

**Key rule:** Without `appearance` prop, icons are **always gray**. Use `appearance` for colored icons.

### ListItem with Colored Icons

```tsx
import { ListItem, Icon } from '@jio/ds-react';
import IcHome from '@jio/ds-react/components/Icon/icons/IcHome';

// ✅ Colored icon in leading slot
<ListItem
  leading={
    <Icon
      asset={<IcHome />}
      size="M"
      appearance="secondary"  // Colored!
      attention="medium"
      tinted
    />
  }
  title="Home"
  subtitle="Navigate to homepage"
/>
```

### Cards

```tsx
import { Card, CardHeader, CardBody, CardFooter } from '@jio/ds-react';

<Card elevation={2} surface="minimal">
  <CardHeader>
    <Title level={4}>Card Title</Title>
  </CardHeader>
  <CardBody>
    <Text>Card content goes here</Text>
  </CardBody>
  <CardFooter>
    <Button appearance="primary">Action</Button>
  </CardFooter>
</Card>
```

**Note:** The `divider` prop on CardHeader/CardFooter is deprecated and has no effect.

### Inputs

```tsx
import { Input, Label, Icon } from '@jio/ds-react';
import IcSearch from '@jio/ds-react/components/Icon/icons/IcSearch';

<div>
  <Label htmlFor="email">Email</Label>
  <Input
    id="email"
    type="email"
    placeholder="Enter your email"
    start={<Icon asset={<IcSearch />} size="S" />}
  />
</div>
```

### Navigation

```tsx
import { HeaderNavigation, Logo } from '@jio/ds-react';

<HeaderNavigation
  type="homebar"
  title="Dashboard"
  logo={<Logo src="/JioLogo.svg" alt="Jio" size="XL" appearance="primary" />}
/>
```

---

## Troubleshooting

### Issue: Components not styled correctly

**Symptom:** Components render but look wrong or have no styling.

**Solution:** Ensure `DsProvider` wraps your app:

```tsx
// ❌ WRONG: No DsProvider
function App() {
  return <Button>Submit</Button>;
}

// ✅ CORRECT: DsProvider wraps app
function App() {
  return (
    <DsProvider platform="Desktop (1440)" colorMode="Light" density="Default">
      <Button>Submit</Button>
    </DsProvider>
  );
}
```

---

### Issue: Icons are gray instead of colorful

**Symptom:** Icons display but are neutral gray, not brand/semantic colors.

**Solution:** Add `appearance` prop to make icons colorful:

```tsx
// ❌ WRONG: No appearance = gray
<Icon asset={<IcStar />} size="M" />

// ✅ CORRECT: appearance prop = colorful
<Icon asset={<IcStar />} size="M" appearance="secondary" tinted />
```

**Key points:**
- Default behavior: Icons are gray
- `attention` controls opacity, NOT color
- `appearance` controls actual color (primary, secondary, positive, negative, etc.)
- Use `tinted` for brand tinting on colored surfaces

---

### Issue: Logo not loading / showing placeholder

**Symptom:** Logo shows a placeholder icon or "!" instead of actual logo.

**Solution:** Place logo in `public/` folder and reference with absolute path:

```tsx
// ❌ WRONG: Relative path or missing leading slash
<Logo src="logo.svg" alt="Brand" />
<Logo src="../assets/logo.svg" alt="Brand" />

// ✅ CORRECT: Absolute path from public folder
<Logo src="/logo.svg" alt="Brand" />
<Logo src="/assets/brand-logo.svg" alt="Brand" />
```

**File structure:**
```
your-project/
├── public/
│   ├── logo.svg              ✅ Place logo here
│   └── JioLogo.svg           ✅ Or here
└── src/
    └── App.tsx
```

**Check console for helpful error messages if logo fails to load.**

---

### Issue: Cannot find icon module

**Symptom:** Import error when trying to use an icon.

**Solution:** Use correct import path with full path to icon file:

```tsx
// ❌ WRONG: Trying to import from barrel export
import { IcSearch } from '@jio/ds-react';

// ✅ CORRECT: Import from specific icon file
import IcSearch from '@jio/ds-react/components/Icon/icons/IcSearch';
```

**Available icons:** 1,620 icons in `/components/Icon/icons/` directory.
See `icon-catalog.json` for complete list.

---

### Issue: Card divider not showing

**Symptom:** Added `divider` prop to CardHeader or CardFooter but no divider appears.

**Explanation:** The `divider` prop is **deprecated** and intentionally disabled.

**Solution:** Use surface variants for visual differentiation instead:

```tsx
// ❌ DEPRECATED: divider prop has no effect
<Card>
  <CardHeader divider>...</CardHeader>
</Card>

// ✅ CORRECT: Use surface prop for differentiation
<Card surface="minimal">
  <CardHeader>...</CardHeader>
</Card>
```

---

### Issue: TypeScript errors with component props

**Symptom:** TypeScript errors about missing or incorrect props.

**Solution:** Import types when needed:

```tsx
import type { ButtonProps, IconProps } from '@jio/ds-react';
```

**Check component README files** in `/src/components/[ComponentName]/README.md` for complete prop documentation.

---

### Issue: Build errors about missing dependencies

**Symptom:** Build fails with errors about `@jio/ds-tokens` or React Aria.

**Solution:** Install all required dependencies:

```bash
npm install @jio/ds-react @jio/ds-tokens
npm install react react-dom  # If not already installed
```

**Peer dependencies:**
- React 18+
- React DOM 18+
- @jio/ds-tokens

---

### Issue: Dark mode not working

**Symptom:** Components don't respond to dark mode changes.

**Solution:** Set `colorMode` prop on DsProvider:

```tsx
<DsProvider
  platform="Desktop (1440)"
  colorMode="Dark"  // Change to "Dark"
  density="Default"
>
  {/* Components will use dark mode */}
</DsProvider>
```

---

### Issue: Components look different than Storybook

**Symptom:** Components in your app don't match Storybook examples.

**Checklist:**
1. ✅ DsProvider configured correctly?
2. ✅ Using same prop values as Storybook?
3. ✅ Surface context matches (SurfaceProvider)?
4. ✅ Icons have `appearance` prop for color?
5. ✅ No conflicting CSS from other libraries?

---

## Getting Help

### Component Documentation

Each component has detailed documentation:
- **Component README:** `/src/components/[ComponentName]/README.md`
- **Type definitions:** `/src/components/[ComponentName]/[ComponentName].types.ts`
- **Examples:** Component README files include usage examples

### Design System Documentation

- **GETTING_STARTED.md** - User-facing setup guide
- **AI_QUICK_START.md** - AI assistant guide for token usage
- **TOKEN_PATTERNS.md** - Complete token naming reference
- **CLAUDE.md** - Design system architecture and rules

### Common Resources

- **Icon Catalog:** `/src/components/Icon/icon-catalog.json`
- **Token Catalog:** `/packages/ds-tokens/catalogs/token-catalog.json`
- **Component List:** See `/src/index.ts` for all exported components

---

## Available Components

- Avatar
- Badge
- Button
- Card (CardHeader, CardBody, CardFooter)
- CarouselIndicator
- Checkbox
- CheckboxField
- Chip
- Divider
- HeaderNavigation
- Icon (1,620 icons available)
- Input
- Label
- Link
- ListItem
- Logo
- Popover
- RadioButton
- RadioField
- SearchField
- Select
- Switch
- SwitchField
- Text
- Title
- Tooltip

See individual component READMEs for detailed usage.

---

## Contributing

This is the Jio Design System component library. Follow these rules:

1. **Token-only styling** - No hard values (no hex colors, no px values)
2. **React Aria foundation** - Use React Aria hooks for accessibility
3. **Surface awareness** - Components must be surface-aware
4. **TypeScript** - All components are fully typed

See **CLAUDE.md** for complete design system rules.

---

**Package:** @jio/ds-react
**Version:** See package.json
**License:** See LICENSE file
**Last Updated:** 2025-11-18