Jio Design System

React Aria-based, Token-Driven Component Library for Web & Native

Built with zero hard values, full accessibility, and platform parity between web and native.

Quick Start

For Developers (5 minutes)

Get started with your first component → GETTING_STARTED.md

Install, import, and build your first token-driven UI component in minutes.

For Teams

Set up the design system for your team → TEAM_QUICKSTART.md

Team installation, workspace configuration, and collaboration setup.

For AI Assistants

Generate production-ready code with AI → AGENT_START.md | AI_SKILLS.md

Learn how to correctly generate token-driven, accessible UI code using Design System components.

Core Principles

1. Token-Only Styling

Zero hard values. All visual properties (colors, spacing, typography, shadows) come from design tokens.

2. React Aria Foundation

Uses Adobe's React Aria hooks exactly as published for battle-tested accessibility (WCAG AA).

3. Surface-Aware Components

Components automatically adapt to elevation levels (0, 1, 2) for proper contrast and shadow.

4. Platform Parity

Identical API for web (React) and native (React Native) with shared accessibility contracts.

Documentation

Getting Started

• Developer Quick Start - Install and build your first component (5 min)
• Team Quick Start - Team setup and collaboration
• Component API Reference - Complete prop reference for all 26 components

For AI Development

• Agent Quick Start - How code agents should use the Design System
• Agent Skills & Constraints - What agents CAN and CANNOT do
• LLM Guide - Comprehensive LLM integration guide
• AI Quick Start - Quick reference for AI assistants

Architecture & Design

• Design System Architecture - System overview
• Token Architecture - Token system design
• LLM Infrastructure - AI orchestration
• Platform Parity - Web/Native comparison

Advanced Topics

• CLAUDE.md - AI orchestration rules and sub-agent specifications
• Component Schemas - JSON schema documentation
• Design System Reference - Comprehensive system reference

Implementation Status

• Component Documentation Status - Component doc compliance (15%)
• Documentation Audit - Complete documentation inventory (98 files)
• Schema Status - JSON schema validation report
• Implementation Status - Progress tracking

Guides

• Using with AI - Detailed AI usage guide
• Accessing from Other Projects - Integration guide
• Font & Icon Setup - Typography and iconography
• Using as Submodule - Git submodule guide

Troubleshooting

• Quick Fix Guide - Common issues and solutions
• Migration Guide - Version upgrades
• Storybook Fixes - Storybook-specific issues

Installation

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

Example

import { Button, SurfaceProvider } from '@jio/ds-react';

function App() {
  return (
    <SurfaceProvider level={0}>
      <Button
        size="L"
        attention="high"
        appearance="primary"
        onPress={() => console.log('Clicked!')}
      >
        Get Started
      </Button>
    </SurfaceProvider>
  );
}

Essence: "Primary buttons are always colourful, never white."

Available Components (26 Total)

Interactive: Button, Input, TextArea, Checkbox, Radio, Switch, Tabs, Stepper

Layout: Card, Divider, ListItem, HeaderNavigation, BottomNavigation

Display: Avatar, Badge, Icon (1,620 icons), Image, Logo, Text, Title, Display, Headline, Label

Feedback: Toast, CarouselIndicator

All components are WCAG AA compliant with full keyboard navigation and screen reader support.

→ Component API Reference for detailed prop documentation.

Packages

| Package | Description | Status | |---------|-------------|--------| | @jio/ds-tokens | Token resolver & Figma variables (4,182 tokens) | ✅ Complete | | @jio/ds-react | React components for web (26 components) | ✅ Stable | | @jio/ds-native | React Native components | 🚧 In Progress | | @jio/ds-docs | Storybook documentation | 🚧 Planned |

Quality Gates

All components must pass:

• ✅ No hard values (hex/px/ms/etc.)
• ✅ React Aria conformance (no behavior modifications)
• ✅ WCAG AA accessibility (automated tests)
• ✅ Tokens resolve (no unresolved references)
• ✅ Surface-aware (inherits surface context)
• ✅ Tests passing (>90% coverage)
• ✅ Platform parity (web and native APIs match)

Contributing

Component Development Workflow

1. Create Spec - specs/{component}.json
2. Implement Web - packages/ds-react/src/components/{Component}/
3. Write Tests - Unit + Accessibility tests
4. Implement Native - packages/ds-native/src/components/{Component}/
5. Add Stories - Storybook documentation
6. Run Agents - Validation and audits
7. Pass Gates - All quality checks must pass

Code Style:

• TypeScript (all code)
• No literals (all values from tokens)
• Surface-aware (use useSurfaceLevel())
• React Aria (never modify hook behavior)
• Tests (>90% coverage required)
• Accessibility (WCAG AA minimum)

Support

• GitHub Issues: Report bugs or request features
• Documentation: Browse /docs/ for comprehensive guides
• Component Docs: See individual component READMEs in packages/ds-react/src/components/

License

MIT © Jio Design Team

Built with precision, accessibility, and zero compromises.

→ Get Started | → Team Setup | → AI Quick Start