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-componentsQuick path
5 minInstall 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
Install the package
$ npm install ux4g-web-componentsLoad styles and runtime once (e.g. in your entry file)
import 'ux4g-web-components/styles.css';
import 'ux4g-web-components/design-system';Use UX4G classes on any element
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
npm install ux4g-web-componentsYarn Package Manager
Alternative installation using Yarn
yarn add ux4g-web-componentsStarter Template (New Projects)
Bootstrap a new project with UX4G pre-configured
npx create-ux4g-app my-government-service
cd my-government-service
npm startWeb Components / HTML
Use the same core web package for cross-stack delivery and simple markup integration
npm install ux4g-web-componentsCDN Link (Not Recommended for Production)
Quick prototyping only - not suitable for production government services
<!-- 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>React Usage Guide
Use the core web package in React and apply UX4G classes directly to JSX elements
Install the package
Add the UX4G core web package to your project
npm install ux4g-web-componentsLoad styles and runtime
Import once in your entry file (e.g. src/main.jsx or src/index.jsx)
import 'ux4g-web-components/styles.css';
import 'ux4g-web-components/design-system';Use UX4G classes
Apply UX4G classes directly to native JSX elements — no component imports needed
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
Install the package
Add the UX4G core web package to your project
npm install ux4g-web-componentsMethod A: Configure angular.json
Recommended. Add the stylesheet and auto-bootstrap runtime to the project options — no TypeScript runtime import needed
// 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"
]
}Method B: Import styles and runtime
Alternative to Method A — import directly from src/styles.css and src/main.ts
/* src/styles.css */
@import 'ux4g-web-components/styles.css';// src/main.ts
import 'ux4g-web-components/design-system';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
// angular.json
{
"type": "initial",
"maximumWarning": "10MB",
"maximumError": "12MB"
}Use UX4G classes in templates
Apply UX4G classes directly to native template elements — no component modules to import
<!-- application-form.component.html -->
<button class="ux4g-btn ux4g-btn-primary ux4g-btn-md" type="submit" (click)="submitForm()">
Submit Application
</button>Angular Version Compatibility
- ✓ Angular 15+
- ✓ Angular 16+
- ✓ Angular 17+ (recommended)
- • 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
Install the package
Add the UX4G core web package to your project
npm install ux4g-web-componentsLoad styles and runtime
Load the stylesheet and runtime once in your application shell
<!-- 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>Use UX4G classes
Compose UI with the same UX4G design language across stacks — no custom elements, just classes on native 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.
.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:
JavaScript/TypeScript Tokens
Access tokens programmatically for dynamic styling or styled-components.
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 DocumentationComponent Usage Patterns
Best practices for using UX4G components
Component Composition
Build complex UIs by combining UX4G classes on plain elements — no component imports needed
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
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
npx create-ux4g-app my-app --template react-tsAngular 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
npx create-ux4g-app my-app --template angularWhat's Included?
- • UX4G components installed
- • Design tokens configured
- • Routing setup
- • Dashboard
- • Form examples
- • Login page
- • Hot reload
- • Linting configured
- • Build scripts
Migration Notes
Moving from existing UI libraries to UX4G
Recommended path
Incremental migration
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
Versioning
Semantic versioning
UX4G follows semantic versioning (semver): MAJOR.MINOR.PATCH
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
Escalation path
Follow this sequence for technical support
Self-Service Documentation
Check component docs, API reference, and troubleshooting guides
Community Forum Search
Search existing forum threads for similar issues
Post in Community Forum
Create a new thread with detailed issue description
GitHub Issue (Bugs Only)
For confirmed bugs, open a GitHub issue with reproduction steps
Direct Support (Government Teams Only)
Email support.ux4g@digitalindia.gov.in for critical production issues
Contact
