npm package: @marcelinodzn/jio-design-system
Description: Jio Design System - Design tokens, schemas, and AI-ready documentation for building accessible UIs
Author: Jio Design Team
Latest version: 1.0.1

# Jio Design System

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

[![GitHub](https://img.shields.io/badge/GitHub-marcelinodzn%2Fjio--design--system-181717?logo=github)](https://github.com/marcelinodzn/jio-design-system)
[![WCAG AA](https://img.shields.io/badge/WCAG-AA-blue.svg)](https://www.w3.org/WAI/WCAG21/quickref/)
[![React Aria](https://img.shields.io/badge/React%20Aria-✓-success.svg)](https://react-spectrum.adobe.com/react-aria/)
[![Token-Only](https://img.shields.io/badge/Token--Only-No%20Literals-orange.svg)](#core-principles)

> 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](./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_QUICKSTART.md)**

Team installation, workspace configuration, and collaboration setup.

### For AI Assistants
**Generate production-ready code with AI**
→ **[AGENT_START.md](./AGENT_START.md)** | **[AI_SKILLS.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](./GETTING_STARTED.md)** - Install and build your first component (5 min)
- **[Team Quick Start](./TEAM_QUICKSTART.md)** - Team setup and collaboration
- **[Component API Reference](./COMPONENT_API_REFERENCE.md)** - Complete prop reference for all 26 components

### For AI Development
- **[Agent Quick Start](./AGENT_START.md)** - How code agents should use the Design System
- **[Agent Skills & Constraints](./AI_SKILLS.md)** - What agents CAN and CANNOT do
- **[LLM Guide](./docs/LLM_GUIDE.md)** - Comprehensive LLM integration guide
- **[AI Quick Start](./docs/guides/AI_QUICK_START.md)** - Quick reference for AI assistants

### Architecture & Design
- **[Design System Architecture](./docs/architecture/DESIGN_SYSTEM_ARCHITECTURE.md)** - System overview
- **[Token Architecture](./docs/architecture/token-architecture-summary.md)** - Token system design
- **[LLM Infrastructure](./docs/architecture/LLM_INFRASTRUCTURE.md)** - AI orchestration
- **[Platform Parity](./PLATFORM_PARITY.md)** - Web/Native comparison

### Advanced Topics
- **[CLAUDE.md](./CLAUDE.md)** - AI orchestration rules and sub-agent specifications
- **[Component Schemas](./COMPONENT_SCHEMAS.md)** - JSON schema documentation
- **[Design System Reference](./DESIGN_SYSTEM_REFERENCE.md)** - Comprehensive system reference

### Implementation Status
- **[Component Documentation Status](./COMPONENT_DOCS_STATUS.md)** - Component doc compliance (15%)
- **[Documentation Audit](./AUDIT.md)** - Complete documentation inventory (98 files)
- **[Schema Status](./reference/SCHEMA_STATUS.md)** - JSON schema validation report
- **[Implementation Status](./docs/implementation/IMPLEMENTATION_STATUS.md)** - Progress tracking

### Guides
- **[Using with AI](./docs/guides/HOW_TO_USE_WITH_AI.md)** - Detailed AI usage guide
- **[Accessing from Other Projects](./docs/guides/ACCESSING_FROM_OTHER_PROJECTS.md)** - Integration guide
- **[Font & Icon Setup](./docs/guides/FONT_AND_ICONS_SETUP.md)** - Typography and iconography
- **[Using as Submodule](./docs/guides/SUBMODULE_EXPLANATION.md)** - Git submodule guide

### Troubleshooting
- **[Quick Fix Guide](./docs/troubleshooting/QUICK_FIX_GUIDE.md)** - Common issues and solutions
- **[Migration Guide](./docs/troubleshooting/MIGRATION.md)** - Version upgrades
- **[Storybook Fixes](./docs/troubleshooting/STORYBOOK_FIX.md)** - Storybook-specific issues

---

## Installation

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

## Example

```tsx
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](./COMPONENT_API_REFERENCE.md)** 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](https://github.com/marcelinodzn/jio-design-system/issues)
- **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](./GETTING_STARTED.md)** | **→ [Team Setup](./TEAM_QUICKSTART.md)** | **→ [AI Quick Start](./AGENT_START.md)**