@jio/ds-react

React component library for the Jio Design System.

Quick Start

Installation

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

Basic Setup

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:

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:

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

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:

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

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

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

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

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:

// ❌ 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:

// ❌ 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:

// ❌ 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:

// ❌ 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:

// ❌ 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:

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:

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:

<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