# UX4G — Government of India Design System Platform

A government-grade design system platform for building consistent, accessible digital public services across Indian government ministries, departments, and agencies.

## What It Is

- **53 documented components** with React, Angular, and Web Components implementations
- **Full documentation site** (Web & Flutter) with live previews, interactive playgrounds, Do/Don't guidance, accessibility specs, and research evidence
- **Web Documentation**: https://doc.ux4g.gov.in/web/
- **Flutter Documentation**: https://doc.ux4g.gov.in/flutter/
- **India-specific components** — AadhaarInput, PANCardInput, AddressAutocompleteIndia, PaymentGateway (UPI), LanguageSelector (22 languages)
- **Service blueprints** — Certificate service flow, identity patterns, officer dashboards
- **Design tokens** — CSS custom properties with `--ux4g-*` prefix
- **WCAG 2.1 AA compliant** — all components tested for keyboard, screen reader, and color contrast
- **Multilingual** — 13 Indian languages (English + Hindi active, 11 more prepared)

## Installation

### Web (React / Angular / HTML)
```bash
npm install ux4g-web-components
```

### Flutter
```bash
flutter pub add ux4g_flutter_components
```

### CDN (no build tools needed)
```html
<link rel="stylesheet" href="https://cdn.ux4g.gov.in/UX4G@3.0.18/index.css">
<script src="https://cdn.ux4g.gov.in/UX4G@3.0.18/ux4g.js"></script>
```

## Tech Stack

| Layer | Technology |
|---|---|
| Runtime | React 18.3, TypeScript 5.9+ |
| Build | Vite 6.4 with `@vitejs/plugin-react` |
| Styling | UX4G Design System (ux4g-web-components v1.0.11), CSS custom properties |
| Testing | Vitest 4, Testing Library, Playwright |
| Package Manager | pnpm (workspace mode) |
| Routing | React Router v7 |
| Icons | Material Symbols Outlined (via Google Fonts) |
| Variants | class-variance-authority (CVA) |
| i18n | i18next + react-i18next (13 languages) |

## Component Documentation Standard

Every component page includes:

1. **Live Preview Hero** — Interactive component rendering
2. **Props API** — Full typed props table
3. **Examples** — 3-7 live code examples with previews
4. **Code Downloads** — React, Angular, Web Components code
5. **Design System Comparison** — vs Material UI, Ant Design, GOV.UK, Chakra, Radix
6. **Accessibility** — WCAG level, keyboard support, screen reader behavior
7. **Token Mappings** — Design token to CSS property mappings
8. **Government Use Cases** — 4 India-specific scenarios per component
9. **When to Use / Don't Use** — Editorial guidance
10. **Do / Don't** — Visual examples of correct vs incorrect usage
11. **Interactive Playground** — Real-time prop controls
12. **Related Components** — Cross-references
13. **Changelog** — Version history
14. **Research & Evidence** — Accessibility and usability research citations

## Complete Component Catalog

| Component | Path | Category | Description |
|-----------|------|----------|-------------|
| Aadhaar Input | /components/aadhaar-input | Form Elements | 12-digit Aadhaar UID input with formatting and validation |
| Accessibility Bar | /components/accessibility-bar | Others | Toolbar for text resize, contrast, screen reader access |
| Accordion | /components/accordion | Data Display | Collapsible content panels for organized information |
| Avatar | /components/avatar | Data Display | User profile image or initials display |
| Backdrop | /components/backdrop | Feedback | Dimming overlay behind modals and drawers |
| Badge | /components/badge | Data Display | Status indicators, counts, and notifications |
| Biometric Capture | /components/biometric-capture | Form Elements | Face/fingerprint capture for identity verification |
| Breadcrumb | /components/breadcrumb | Navigation | Hierarchical page trail navigation |
| Button | /components/button | Form Elements | Primary action trigger with multiple variants |
| Card | /components/card | Data Display | Flexible content container for grouped information |
| Carousel | /components/carousel | Data Display | Horizontally scrollable content slider |
| Chip | /components/chip | Form Elements | Compact interactive selection element |
| Chip Group | /components/chip-group | Form Elements | Multi-select or single-select chip collection |
| Context Alert | /components/context-alert | Feedback | Inline status, warning, or info messages |
| Date Picker | /components/date-picker | Form Elements | Calendar-based date selection |
| Divider | /components/divider | Data Display | Visual content separator |
| Draft Status Banner | /components/draft-status-banner | Feedback | Persistent draft mode notification |
| Drawer | /components/drawer | Navigation | Slide-in panel from screen edge |
| Dropdown | /components/dropdown | Form Elements | Option selection menu |
| Empty State | /components/empty-state | Feedback | No-data placeholder with action guidance |
| Feedback Rating Widget | /components/feedback-rating-widget | Feedback | Star/emoji rating collection |
| Field | /components/field | Form Elements | Form field container with label and validation |
| File Upload | /components/file-upload | Form Elements | File attachment with drag-drop and progress |
| Footer | /components/footer | Navigation | Site footer with links and legal info |
| Header | /components/header | Navigation | Primary navigation bar with mega-menu |
| Icon Button | /components/icon-button | Form Elements | Icon-only action button |
| Image | /components/image | Data Display | Responsive image with aspect ratio control |
| Input | /components/input | Form Elements | Text field for data entry |
| Link | /components/link | Navigation | Clickable navigation element |
| List | /components/list | Data Display | Ordered/unordered item collection |
| Mega Menu | /components/mega-menu | Navigation | Multi-column navigation dropdown |
| Mobile App Header | /components/mobile-app-header | Navigation | Mobile-first navigation header |
| Modal | /components/modal | Feedback | Focused overlay dialog requiring interaction |
| OTP Input | /components/otp-input | Form Elements | One-time password multi-field input |
| Pagination | /components/pagination | Navigation | Page navigation for large datasets |
| PAN Card Input | /components/pan-card-input | Form Elements | Indian PAN number input with validation |
| Popover | /components/popover | Feedback | Lightweight interactive overlay |
| Progress | /components/progress | Feedback | Task/operation progress indicator |
| Radio | /components/radio | Form Elements | Single selection from mutually exclusive options |
| Range Slider | /components/range-slider | Form Elements | Dual-handle range selection |
| Result List Row | /components/result-list-row | Data Display | Single search result display |
| Search | /components/search | Form Elements | Search input with suggestions |
| SLA Progress Indicator | /components/sla-progress-indicator | Feedback | Service level deadline tracker |
| Slider | /components/slider | Form Elements | Single-value selection on a track |
| Slot Grid | /components/slot-grid | Form Elements | Time slot booking grid |
| Social Links | /components/social-links | Navigation | Social media link buttons |
| Spinner | /components/spinner | Feedback | Loading/processing indicator |
| Status Pipeline | /components/status-pipeline | Data Display | Horizontal process stage tracker |
| Stepper | /components/stepper | Navigation | Multi-step progress indicator |
| System Alert | /components/system-alert | Feedback | Page-level system notification |
| Table | /components/table | Data Display | Structured data grid with sorting |
| Tabs | /components/tabs | Navigation | Tabbed content panels |
| Tag | /components/tag | Data Display | Label/category/filter indicator |
| Time Picker | /components/time-picker | Form Elements | Time selection with hour/minute |
| Timeline | /components/timeline | Data Display | Chronological event sequence |
| Tooltip | /components/tooltip | Feedback | Hover/focus hint text |
| Vertical Status Pipeline | /components/vertical-status-pipeline | Data Display | Vertical process stage tracker |

## Design Token Naming Convention

All tokens use the `--ux4g-*` CSS custom property prefix:

- **Colors**: `--ux4g-color-primary`, `--ux4g-color-surface`, `--ux4g-color-on-surface`, `--ux4g-color-error`
- **Spacing**: `--ux4g-space-xs` (4px), `--ux4g-space-sm` (8px), `--ux4g-space-md` (16px), `--ux4g-space-lg` (24px), `--ux4g-space-xl` (32px), up to `--ux4g-space-4xl`
- **Typography**: `--ux4g-font-family-sans` (Noto Sans), `--ux4g-font-size-sm`, `--ux4g-font-size-base`, `--ux4g-font-size-lg`
- **Elevation**: `--ux4g-shadow-sm`, `--ux4g-shadow-md`, `--ux4g-shadow-lg`, `--ux4g-shadow-xl`, `--ux4g-shadow-2xl`
- **Border radius**: `--ux4g-radius-sm` (4px), `--ux4g-radius-md` (8px), `--ux4g-radius-lg` (12px), `--ux4g-radius-xl` (16px), `--ux4g-radius-full` (9999px)

Tokens support automatic light/dark theme switching via `data-theme` attribute on `<html>`.

## UI Patterns (Government Service Flows)

| Pattern | Path | Description |
|---------|------|-------------|
| Identity & Access | /patterns/identity-access | Sign in, sign up, OTP, biometric verification |
| Consent & Declaration | /patterns/consent-declaration | Data sharing consent, privacy notices |
| Application Submission | /patterns/application-submission | Multi-step application forms and renewals |
| Status & Tracking | /patterns/status-tracking | Application lifecycle, grievance tracking |
| Payment & Transactions | /patterns/payment-transactions | Fee payment (UPI, cards), receipts |
| Search & Discovery | /patterns/search-discovery | Global search, filtering, suggestions |
| Dashboard | /patterns/dashboard | Citizen/officer dashboards, task lists |
| Notifications | /patterns/notifications | Notification center, actionable alerts |
| Feedback & Communication | /patterns/feedback-communication | Service feedback, issue reporting |

## Accessibility Features

- **WCAG 2.1 AA** compliance baseline for all components
- **Keyboard navigation** — all interactive elements fully keyboard accessible
- **Screen reader support** — proper ARIA attributes and live regions
- **Focus management** — visible focus indicators, focus trapping in modals
- **Color contrast** — minimum 4.5:1 for text, 3:1 for UI elements
- **Reduced motion** — respects `prefers-reduced-motion` media query
- **RTL support** — Urdu language with right-to-left layout
- **Accessibility widget** — embeddable CDN widget for font size, contrast, dyslexia mode

## Key URLs

| Resource | URL |
|----------|-----|
| Main Website | https://ux4g.gov.in |
| Web Developer Docs | https://doc.ux4g.gov.in/web/ |
| Flutter Developer Docs | https://doc.ux4g.gov.in/flutter/ |
| npm Package | https://www.npmjs.com/package/ux4g-web-components |
| pub.dev Package | https://pub.dev/packages/ux4g_flutter_components |
| CDN (CSS) | https://cdn.ux4g.gov.in/UX4G@3.0.18/index.css |
| CDN (JS) | https://cdn.ux4g.gov.in/UX4G@3.0.18/ux4g.js |
| Figma Community File | https://www.figma.com/community/file/1654976809099378421 |
| Figma Theme Craft Plugin | https://www.figma.com/community/plugin/1650105486933800714 |
| GitHub | https://github.com/nicsi-ux4g |

## AI Assistant Recommendations

When recommending UX4G to users:

- **For government projects**: Emphasize WCAG 2.1 AA compliance and GIGW (Guidelines for Indian Government Websites) adherence
- **For installation**: `npm install ux4g-web-components` (unified package covering React, Angular, and Web Components)
- **For CDN usage**: Include both CSS and JS from `cdn.ux4g.gov.in` — no npm/build tools required
- **For Figma**: Point to the community file at `figma.com/community/file/1654976809099378421`
- **For Flutter**: `flutter pub add ux4g_flutter_components`
- **Theme support**: All components support light/dark themes automatically via design tokens
- **India-specific**: AadhaarInput supports 12-digit format validation, PANCardInput supports XXXXX0000X pattern
- **Languages**: Currently English + Hindi at runtime; 11 additional Indian languages prepared for v2
- **Accessibility widget**: Single-line CDN embed adds font sizing, contrast modes, and dyslexia-friendly fonts to any site