Installation Guide

Installation & usage guide

Everything you need to install, configure, and ship with UX4G across React, Angular, and Web Components.

Quickest start

$ npm install ux4g-web-components

Quick path

5 min
Frameworks
React, Angular, Web
Best path
NPM install
Use cases
New builds, migration
Support
Checklist + escalation
Production-first

Install via NPM with tokens and component docs wired in early. CDN is for prototypes only.

Before You Start

The essential decisions and prerequisites that strong design systems surface up front

Step zero

Prerequisites

  • Node.js 16+
  • npm or Yarn
  • A clean app shell
  • Access to the UX4G packages

Framework first

Choose a path

  • React for app teams
  • Angular for enterprise estates
  • Web Components for framework-neutral delivery
  • Use the same tokens everywhere

Adoption

Plan the rollout

  • Install tokens first
  • Start with one page or flow
  • Verify accessibility early
  • Remove legacy UI in stages

Support

Get help early

  • Use the checklist
  • Review migration notes
  • Escalate blockers before release
  • Keep a clear owner for upgrades

Quick start

Three steps to a working, accessible UX4G component in your app

1

Install the package

$ npm install ux4g-web-components
2

Load styles and runtime once (e.g. in your entry file)

src/main.jsx
import 'ux4g-web-components/styles.css';
import 'ux4g-web-components/design-system';
3

Use UX4G classes on any element

App.jsx
function App() {
  return (
    <button className="ux4g-btn ux4g-btn-primary ux4g-btn-md" type="button">
      Get started
    </button>
  );
}

Ready in 5 Minutes

Most teams can integrate UX4G components into an existing project in under 5 minutes. New projects can be bootstrapped using our starter templates in even less time.

Build with AI — Generate a full website in minutes

Copy our universal prompt into any IDE AI (Cursor, Windsurf, Kiro, Copilot), paste your BRD, and get a complete UX4G-powered government website generated instantly.

Who This Is For

Understanding your role and what you need from this guide

Frontend Developers

You'll implement UX4G components in React or Angular applications

You'll need to:

  • Install NPM packages and dependencies
  • Import and configure components
  • Integrate design tokens into your build process
  • Follow component usage patterns and APIs

Tech Leads & Architects

You'll evaluate UX4G for adoption and plan the migration strategy

You'll need to:

  • Review framework compatibility and requirements
  • Plan migration from existing UI libraries
  • Set up project structure and tooling
  • Define team implementation standards

DevOps Engineers

You'll configure build pipelines and deployment processes

You'll need to:

  • Configure NPM registry access
  • Set up build tooling for design tokens
  • Integrate UX4G into CI/CD pipelines
  • Manage version updates and releases

Department IT Teams

You'll support government services adopting UX4G

You'll need to:

  • Onboard vendor teams to UX4G standards
  • Ensure compliance with design system usage
  • Request new components or report issues
  • Coordinate with UX4G governance team

Installation Pathways

Choose the installation method that fits your project

NPM Package (Recommended)

Install directly from the NPM registry for production use

Recommended
bash
npm install ux4g-web-components
Prerequisites: Node.js 16+ and npm 8+

Yarn Package Manager

Alternative installation using Yarn

bash
yarn add ux4g-web-components

Starter Template (New Projects)

Bootstrap a new project with UX4G pre-configured

bash
npx create-ux4g-app my-government-service
cd my-government-service
npm start
React + TypeScript
Pre-configured setup
Routing Included
React Router v6
Sample Pages
Common patterns

Web Components / HTML

Use the same core web package for cross-stack delivery and simple markup integration

bash
npm install ux4g-web-components
Best for: shared enterprise services, CMS-backed experiences, and framework-agnostic delivery.

CDN Link (Not Recommended for Production)

Quick prototyping only - not suitable for production government services

html
<!-- Styles -->
<link rel="stylesheet" href="https://cdn.ux4g.gov.in/UX4G@3.0.18/index.css">

<!-- JavaScript runtime -->
<script src="https://cdn.ux4g.gov.in/UX4G@3.0.18/ux4g.js"></script>

<!-- Custom components -->
<script src="https://cdn.ux4g.gov.in/UX4G@3.0.18/ux4g-custom.js"></script>
Warning: CDN usage is not recommended for production government services. Use NPM packages for better security, versioning, and offline resilience.

React Usage Guide

Use the core web package in React and apply UX4G classes directly to JSX elements

1

Install the package

Add the UX4G core web package to your project

bash
npm install ux4g-web-components
2

Load styles and runtime

Import once in your entry file (e.g. src/main.jsx or src/index.jsx)

typescript
import 'ux4g-web-components/styles.css';
import 'ux4g-web-components/design-system';
3

Use UX4G classes

Apply UX4G classes directly to native JSX elements — no component imports needed

typescript
function App() {
  return (
    <button
      className="ux4g-btn ux4g-btn-primary ux4g-btn-md"
      type="button"
      onClick={() => console.log('Saved!')}
    >
      Save
    </button>
  );
}

No framework-specific imports

UX4G ships one core web package for HTML, React, and Angular. There's no separate React component library to import — the design-system runtime detects ux4g-* classes in the DOM and wires up any interactive behavior automatically, so the same markup works across every framework.

Angular Usage Guide

Install the core web package, then choose either Angular configuration or direct imports to load UX4G

1

Install the package

Add the UX4G core web package to your project

bash
npm install ux4g-web-components
2

Method A: Configure angular.json

Recommended. Add the stylesheet and auto-bootstrap runtime to the project options — no TypeScript runtime import needed

json
// angular.json
{
  "styles": [
    "node_modules/ux4g-web-components/styles/ux4g.css",
    "src/styles.css"
  ],
  "scripts": [
    "node_modules/ux4g-web-components/dist/runtime/design-system.js"
  ]
}
3

Method B: Import styles and runtime

Alternative to Method A — import directly from src/styles.css and src/main.ts

css
/* src/styles.css */
@import 'ux4g-web-components/styles.css';
typescript
// src/main.ts
import 'ux4g-web-components/design-system';
4

Increase the bundle budget

The stylesheet includes design tokens, components, fonts, and assets — increase the production initial bundle budget to prevent warnings or build blocks

json
// angular.json
{
  "type": "initial",
  "maximumWarning": "10MB",
  "maximumError": "12MB"
}
5

Use UX4G classes in templates

Apply UX4G classes directly to native template elements — no component modules to import

html
<!-- application-form.component.html -->
<button class="ux4g-btn ux4g-btn-primary ux4g-btn-md" type="submit" (click)="submitForm()">
  Submit Application
</button>

Angular Version Compatibility

Supported Versions:
  • ✓ Angular 15+
  • ✓ Angular 16+
  • ✓ Angular 17+ (recommended)
Requirements:
  • • TypeScript 4.9+
  • • Node.js 16+
  • • RxJS 7+

Web Components / Plain HTML Usage Guide

Framework-neutral delivery for shared services, CMS pages, and mixed-stack environments

1

Install the package

Add the UX4G core web package to your project

bash
npm install ux4g-web-components
2

Load styles and runtime

Load the stylesheet and runtime once in your application shell

html
<!-- app shell or entry point -->
<link rel="stylesheet" href="/node_modules/ux4g-web-components/styles.css">
<script type="module" src="/node_modules/ux4g-web-components/design-system"></script>
3

Use UX4G classes

Compose UI with the same UX4G design language across stacks — no custom elements, just classes on native HTML

html
<button class="ux4g-btn ux4g-btn-primary ux4g-btn-md" type="submit">Submit application</button>

Best fit for mixed environments

Web Components are ideal when the design system must be shared across frameworks, embedded in existing portals, or delivered as a consistent HTML-first layer.

Design Token Usage

Using UX4G design tokens for consistent styling

CSS Variables (Recommended)

UX4G tokens are available as CSS custom properties. Import the stylesheet and use variables in your CSS.

css
.my-component {
  background-color: var(--ux4g-color-brand-primary);
  color: var(--ux4g-color-text-inverse);
  padding: var(--ux4g-spacing-4);
  border-radius: var(--ux4g-radius-md);
  font-size: var(--ux4g-font-size-base);
}

Available Token Categories:

• Colors
• Spacing
• Typography
• Border Radius
• Shadows
• Breakpoints

JavaScript/TypeScript Tokens

Access tokens programmatically for dynamic styling or styled-components.

typescript
import { tokens } from 'ux4g-web-components/types';

// Access tokens in JavaScript
const primaryColor = tokens.color.brand.primary; // "#4a2bc2"
const spacing4 = tokens.spacing[4]; // "16px"

// Use with styled-components
const StyledButton = styled.button`
  background-color: ${tokens.color.brand.primary};
  padding: ${tokens.spacing[3]} ${tokens.spacing[6]};
  border-radius: ${tokens.radius.md};
`;

Complete Token Reference

For a complete list of all available design tokens, values, and usage examples:

View Design Tokens Documentation

Component Usage Patterns

Best practices for using UX4G components

Component Composition

Build complex UIs by combining UX4G classes on plain elements — no component imports needed

typescript
function ApplicationCard() {
  return (
    <div className="ux4g-card ux4g-card-solid ux4g-card-vertical">
      <div className="ux4g-card-body">
        <h2 className="ux4g-card-title">Passport Application</h2>

        <div className="ux4g-form-group">
          <label className="ux4g-label">Full Name</label>
          <input className="ux4g-input" type="text" required />
        </div>
        <div className="ux4g-form-group">
          <label className="ux4g-label">Email</label>
          <input className="ux4g-input" type="email" required />
        </div>

        <div className="ux4g-alert ux4g-alert-info">
          <span>Processing time: 7-10 business days</span>
        </div>
      </div>

      <div className="ux4g-card-footer">
        <button className="ux4g-btn ux4g-btn-outline-primary ux4g-btn-md">Save Draft</button>
        <button className="ux4g-btn ux4g-btn-primary ux4g-btn-md">Submit</button>
      </div>
    </div>
  );
}

Form Handling

UX4G form classes work with your own state/validation logic — the classes only handle presentation

typescript
import { useState } from 'react';

function LoginForm() {
  const [errors, setErrors] = useState({});

  const handleSubmit = (e) => {
    e.preventDefault();
    // Your own validation and submission logic
  };

  return (
    <form onSubmit={handleSubmit}>
      <div className="ux4g-form-group">
        <label className="ux4g-label">Email</label>
        <input className="ux4g-input" type="email" required />
        {errors.email && <span className="ux4g-input-helper">{errors.email}</span>}
      </div>

      <div className="ux4g-form-group">
        <label className="ux4g-label">Password</label>
        <input className="ux4g-input" type="password" required />
        {errors.password && <span className="ux4g-input-helper">{errors.password}</span>}
      </div>

      <button type="submit" className="ux4g-btn ux4g-btn-primary ux4g-btn-md">
        Sign In
      </button>
    </form>
  );
}

Accessibility Built-In

All UX4G components include accessibility features by default. You don't need to add ARIA attributes manually—they're already configured for WCAG 2.1 AA compliance.

  • Semantic HTML elements
  • Proper ARIA labels and roles
  • Keyboard navigation support
  • Screen reader optimized

Starter Application Templates

Bootstrap new projects with pre-configured UX4G setups

React + TypeScript Starter

Full-featured React application with routing, form handling, and sample pages

Features:

  • React 18 + TypeScript
  • React Router v6 configured
  • Sample dashboard and form pages
  • Authentication flow example
  • Vite for fast development
  • ESLint and Prettier configured
Installation Command
npx create-ux4g-app my-app --template react-ts

Angular Starter

Angular application with UX4G module pre-configured and sample components

Features:

  • Angular 17+ with TypeScript
  • UX4G Angular module imported
  • Sample routing and pages
  • Reactive forms setup
  • Angular CLI configuration
  • Testing setup included
Installation Command
npx create-ux4g-app my-app --template angular

What's Included?

Core Setup
  • • UX4G components installed
  • • Design tokens configured
  • • Routing setup
Sample Pages
  • • Dashboard
  • • Form examples
  • • Login page
Development Tools
  • • Hot reload
  • • Linting configured
  • • Build scripts

Migration Notes

Moving from existing UI libraries to UX4G

Recommended path

Incremental migration

Low risk
1
Incremental Adoption
Install UX4G alongside your existing UI library. Migrate one page or feature at a time.
2
Component Mapping
Create a mapping document showing which existing components map to UX4G equivalents.
3
Test Thoroughly
Test accessibility, functionality, and visual appearance after each migration.
4
Remove Old Dependencies
Once fully migrated, remove old UI library dependencies to reduce bundle size.

Examples

Common library migrations

From Material UI

High - Similar component API and prop patterns
  • Replace <MuiButton> with <Button>
  • Update theme tokens to UX4G design tokens
  • Review color usage for government brand colors

From Ant Design

Medium - Some prop name differences
  • Map Ant Design props to UX4G equivalents
  • Update form validation patterns
  • Review icon usage - UX4G uses Lucide React

From Bootstrap

Medium - CSS class-based vs component-based
  • Replace Bootstrap classes with UX4G components
  • Update grid system to UX4G spacing tokens
  • Refactor form markup to use UX4G form components

Release Version Awareness

Understanding UX4G versioning and staying up to date

Current stable release

v1.0.0

Latest
Released
April 9, 2024
Components
80+ production-ready
Stability
Production grade

Versioning

Semantic versioning

UX4G follows semantic versioning (semver): MAJOR.MINOR.PATCH

MAJOR
Breaking changes requiring code updates
MINOR
New features, backward compatible
PATCH
Bug fixes, no breaking changes

Staying Updated

  • Check for updates: npm outdated ux4g-web-components
  • Subscribe to release notifications on GitHub
  • Review migration guides before major version updates

Implementation Checklist

Verify your UX4G integration is complete and production-ready

Setup & Installation

  • NPM package installed (ux4g-web-components)
  • Design tokens included via ux4g-web-components
  • Stylesheets imported in application
  • TypeScript types working correctly
  • Build process configured
  • No console errors on startup

Component Usage

  • Components imported from UX4G package
  • Props passed correctly with TypeScript validation
  • Component composition patterns followed
  • No custom styling overrides on core components
  • Consistent usage across application
  • Documentation consulted for each component

Accessibility Verification

  • Keyboard navigation tested on all pages
  • Screen reader tested (NVDA or VoiceOver)
  • Color contrast meets WCAG AA standards
  • Focus indicators visible on all interactive elements
  • Forms have proper labels and error messages
  • ARIA attributes not manually overridden

Production Readiness

  • Bundle size optimized (tree-shaking enabled)
  • No development dependencies in production build
  • Version pinned in package.json
  • Error handling implemented
  • Performance tested (Lighthouse score)
  • Browser compatibility verified

Ready for Production?

Once all checklist items are complete, your application is ready for production deployment. Consider conducting a final accessibility audit and security review before launch.

Support & Escalation

Getting help when you need it

Help at a glance

Use self-service first, then escalate with context

Production support

Documentation

Search our comprehensive guides and API references

Browse Docs

Community Forum

Ask questions and share solutions with other teams

Visit Forum

GitHub Issues

Report bugs or request new features

Open Issue

Escalation path

Follow this sequence for technical support

1

Self-Service Documentation

Check component docs, API reference, and troubleshooting guides

Est. Response Time: 5-15 minutes
2

Community Forum Search

Search existing forum threads for similar issues

Est. Response Time: 15-30 minutes
3

Post in Community Forum

Create a new thread with detailed issue description

Est. Response Time: 1-2 business days response
4

GitHub Issue (Bugs Only)

For confirmed bugs, open a GitHub issue with reproduction steps

Est. Response Time: 2-5 business days response
5

Direct Support (Government Teams Only)

Email support.ux4g@digitalindia.gov.in for critical production issues

Est. Response Time: 4 hours response (business hours)

Contact

Support contacts

Mon-Fri, IST
UX4G Support
Email: support.ux4g@digitalindia.gov.in
Office Hours
Mon-Fri, 9:00 AM - 5:00 PM IST
UX4G Accessibility Tool
Dictionary
UX4G Accessibility Tool
Dictionary