Ux4g Design System

---
name: ux4g-design-system
description: Use when building or reviewing UI with UX4G — India's official government design system (ux4g.gov.in, cdn.ux4g.gov.in, ux4g-web-components). Covers the v3.0.18 token API, the 52 components, install paths for HTML/React/Angular/Flutter, and the interop hazards. Triggers include "UX4G", "ux4g-web-components", "cdn.ux4g.gov.in", `--ux4g-*` custom properties, `.ux4g-*` classes, AadhaarInput/PANCardInput/OTP components, or a government project told to adopt UX4G in its SoW/TOR.
---

# UX4G Design System (v3.0.18)

## Overview

UX4G is the Government of India's design system, published by NeGD/DIC under MeitY.
It ships design tokens, ~2,700 CSS classes, 52 components, 16 service patterns and a
Flutter package.

**All values in this skill were extracted from the shipped CSS on 30 Jul 2026**, not
recalled. Reference files carry the full machine-extracted inventory.

**Core principle:** UX4G is a *CSS class library with a two-layer token system*. There is
no official React component package — `ux4g-web-components` is a CSS bundle plus a small
runtime, not a set of React components.

## ⚠️ The single most important thing: UX4G's own AI docs are wrong about token names

`https://ux4g.gov.in/llms-full.txt` documents a token API that **does not exist in the
shipped CSS**. Verified by grepping all 145 CSS files at `cdn.ux4g.gov.in/UX4G@3.0.18/`:

| Documented in `llms-full.txt` | Reality |
|---|---|
| `--ux4g-space-xs/sm/md/lg/xl/4xl` | **0 occurrences.** Does not exist |
| `--ux4g-shadow-sm/md/lg/xl/2xl` | **0 occurrences.** Does not exist |
| `--ux4g-color-primary`, `--ux4g-color-surface`, `--ux4g-color-on-surface`, `--ux4g-color-error` | **0 occurrences.** Does not exist |
| `--ux4g-font-family-sans`, `--ux4g-font-size-sm/base/lg` | **0 occurrences.** Does not exist |
| `--ux4g-radius-sm/md/lg/xl/full` | ✅ Real — these five *do* exist, in the semantic layer |

19 of the 24 token names in their AI documentation are fictional. CSS custom properties
fail **silently** — `padding: var(--ux4g-space-md)` produces no padding and no error.

**Never take a `--ux4g-*` name from llms.txt/llms-full.txt. Use `tokens.md` in this skill,
or grep the CDN.**

## The real token API

Two layers. **Write application code against the semantic layer.**

```
tokens/    355 primitives — numeric names   --ux4g-space-7, --ux4g-size-16, --ux4g-radius-3
semantic/  361 aliases    — intent names    --ux4g-padding-l, --ux4g-fs-16, --ux4g-bg-primary
```

### Spacing is an inline / stack / section model, not one t-shirt scale

```css
--ux4g-inline-{none,2xs,xs,s,m,l,xl}    /* horizontal rhythm */
--ux4g-stack-{none,2xs,xs,s,m,l,xl}     /* vertical rhythm */
--ux4g-padding-{none,3xs,2xs,xs,s,m,l,xl,2xl,3xl,4xl}
--ux4g-margin-{none,3xs,2xs,xs,s,m,l,xl,2xl}
--ux4g-section-{none,xs,s,m,l,xl,2xl}   /* page bands */
```

Primitive scale is deliberately irregular:
`--ux4g-space-1…16` = **2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64, 80, 120, 360px**
(note the 6px and 20px steps, and the 360px top).

### Everything else, at a glance

| Concern | Real token shape |
|---|---|
| Font size | `--ux4g-fs-{8,11,12,14,16,18,20,24,28,32,36,40,48,52,60}` |
| Line height | `--ux4g-lh-{14,16,18,20,24,28,32,36,44,52,72,80}` |
| Font weight | `--ux4g-fw-{regular,medium,semibold,bold}` |
| Font family | `--ux4g-ff` (Noto Sans), `--ux4g-ff-display` |
| Elevation | `--ux4g-shadow-{l0,l1,l2,l3,l4}` + `--ux4g-shadow-focus-{ring,inset,border}` |
| Radius | `--ux4g-radius-{none,xs,sm,md,lg,xl,2xl,full}` → 0,2,4,8,12,16,24,999px |
| Background | `--ux4g-bg-{primary,secondary,tertiary,neutral,success,warning,error,info}-*` |
| Text | `--ux4g-text-{neutral,brand,link,status,error,success,warning,info}-*` |
| Border | `--ux4g-border-color-*` (21), `--ux4g-border-width-*` (5) |

Breakpoints **576 / 768 / 992 / 1200 / 1400px** · containers **540 / 720 / 960 / 1140 / 1320px** ·
z-index dropdown 1000 → toast 1090.

### Grid gutters

`:root` default is **12px** (`--ux4g-gutter-x/y: var(--ux4g-space-5, 12px)`), with a modifier
scale on `.ux4g-row`:

| Class | Gutter |
|---|---|
| `.ux4g-gutter-none` | 0 |
| `.ux4g-gutter-xs` | 8px |
| `.ux4g-gutter-s` | 12px |
| `.ux4g-gutter-m` | 16px |
| `.ux4g-gutter-l` | 24px |
| `.ux4g-gutter-xl` | 40px |

⚠️ `.ux4g-row` itself is written `var(--ux4g-gutter-x, var(--ux4g-space-6))` — a **16px**
fallback that disagrees with the 12px `:root` default. It only fires if you load
`layout/` without `tokens/`, in which case rows silently gain 16px gutters. Load the
`index.css` manifest, not individual layer files.

Full tables, including the dark theme overrides → `tokens.md`

## ⚠️ Three interop hazards before you `@import` anything

1. **A bare, unscoped `:focus` rule.** `components/button.css:46` contains:
   ```css
   :focus { position: var(--ux4g-pos-relative);
            outline: var(--ux4g-border-width-md) solid var(--ux4g-border-color-primary-strong);
            outline-offset: 2px; }
   ```
   Not `.ux4g-btn:focus` — bare `:focus`. It restyles focus on **every focusable element on
   the page**, including your own components. It is not inside `:where()`, so it beats
   element selectors.

2. **The reset touches every element on the page.** `reset/reset.css` uses
   `:where(*, *::before, *::after) { margin:0; padding:0; border:0; outline:0 }`. Zero
   specificity, so it is easy to override — but it *is* global, not scoped to `.ux4g-*`.
   `:where(body)`, `:where(a)`, `:where(ul)`, `:where(img)`, `:where(button)` are also reset.

3. **The CDN build is `@layer`-wrapped; the npm build is not.** The CDN entry declares
   `@layer ux4g-tokens, ux4g-reset, ux4g-foundations, ux4g-layout, ux4g-components,
   ux4g-patterns, ux4g-utilities`, so it loses to any unlayered CSS of yours. The npm
   `styles/ux4g.css` is a single **8,000,505-byte** file with no layers — it competes on
   raw source order.

UX4G's own FAQ on mixing frameworks: *"It's technically possible, but not recommended."*

## Installing

### CDN — no build step. Three files, and you need all three.
```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>
<script src="https://cdn.ux4g.gov.in/UX4G@3.0.18/ux4g-custom.js"></script>
```
`index.css` is an 877-byte `@import` manifest that pulls 145 files (~6.4 MB uncompressed).
It is a **runtime third-party CDN dependency** — needs a CSP allowance and sits awkwardly
against India-hosting/CERT-In posture. Self-host for production government work.

### npm
```bash
npm install ux4g-web-components   # latest is 1.0.2
```
```js
import 'ux4g-web-components/styles.css';
import 'ux4g-web-components/design-system';
```
⚠️ **`1.0.2` is a packaging version, not the design-system version — it ships v3.** Exports
are `./design-system`, `./runtime`, `./runtime/bootstrap`, `./styles.css`, `./types`.
18 files, 10.4 MB unpacked, and `styles/ux4g.css` alone is 8 MB with base64 font blobs.

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

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

**There is no official React component package.** `ux4g-react`, `@hopline/ux4g-react` and
`ux4g-ui` on npm are third-party and unaffiliated. In React you import the CSS and write
`className="ux4g-btn ux4g-btn-primary"`.

## The 52 components

India-specific ones you will not find in any other design system:

| Component | Why it exists |
|---|---|
| `aadhaar-input` | 12-digit UID, grouped 4-4-4, with validation |
| `pan-card-input` | PAN pattern `XXXXX0000X` |
| `otp-input` | Multi-box OTP entry |
| `biometric-capture` | Face/fingerprint for identity verification |
| `sla-progress-indicator` | Service-level deadline tracker — a government service promises a date |
| `status-pipeline` / `vertical-status-pipeline` | Application lifecycle stages |
| `draft-status-banner` | Persistent "this is a draft" notice on long forms |
| `accessibility-bar` | The `A− A A+` / contrast strip Indian gov sites are expected to carry |
| `time-slot` / `slot-grid` | Appointment booking |
| `result-list-row` | Search-result row for service discovery |

Remaining 42 are conventional (button, card, modal, table, tabs, drawer, stepper…).
Full per-component class inventory → `components.md`
Patterns and the 28 utility modules → `patterns-utilities.md`

## Naming traps

| You'd expect | Actual |
|---|---|
| `.ux4g-button` | `.ux4g-btn`, `.ux4g-btn-primary`, `.ux4g-btn-outline-primary` |
| `button.md` in docs | The doc file is `buttons.md` (plural); Storybook title is `Buttons` |
| A saffron or navy default | UX4G's default primary is **purple `#4a2bc2`** (`--ux4g-color-primary-600`) |
| One system | v2.0.8 (a Bootstrap 5 fork, unprefixed classes) is **still live on the CDN**. v2 and v3 are architecturally unrelated. Establish which one someone means. |

### Re-theming: override the ramp, not the semantic tokens

Colour resolves in three hops — `.ux4g-btn-primary` → `--ux4g-bg-primary-strong` →
`--ux4g-color-primary-600`. **The theming hook is the primitive ramp.** There are 15 ramps
and 167 colour tokens; `primary`, `secondary` and `tertiary` are the themeable ones, each
an 11-step `50…950` scale.

```css
:root {                                   /* re-theme to DBIM Deep Blue */
  --ux4g-color-primary-600: #1D0A69;      /* default fill  (was #4a2bc2) */
  --ux4g-color-primary-700: #180854;      /* hover                       */
  --ux4g-color-primary-800: #130640;      /* active                      */
}
```

Overriding `--ux4g-bg-primary-strong` instead works but only repaints backgrounds —
text, borders and icons read from the same ramp through different semantic tokens and
will drift out of sync.

⚠️ `--ux4g-color-brand-primary` is **not** a CDN token. It appears inline on
`ux4g.gov.in`'s own `<html style="…">` as that site's runtime theming. Copying it into a
stylesheet does nothing.

## UX4G is advisory — it carries no legal force

From UX4G's own FAQ, verbatim: *"Does using the Design System make my site WCAG/GIGW
compliant automatically? **No.** … A final accessibility and quality audit is required."*

It binds **only** when a department writes it into the SoW/TOR. So adopting UX4G is a
**procurement** question, not a legal-exposure one. The legal exposure is WCAG — see the
`indian-gov-web-ui` skill.

Note what their FAQ *does* affirm, though: asked whether accessibility compliance is
mandatory for Indian government websites, the answer is **"Yes. It's required under GIGW
guidelines and the Rights of Persons with Disabilities (RPWD) Act, 2016."** The obligation
is real; UX4G just isn't the thing that discharges it.

## Official resources and services

| Resource | Where |
|---|---|
| Web docs (Storybook) | `doc.ux4g.gov.in/web/` — 402 stories, 137 component/pattern docs |
| Flutter docs | `doc.ux4g.gov.in/flutter/` |
| Machine-readable catalogue | `doc.ux4g.gov.in/web/catalog.json` |
| Per-topic LLM docs | `doc.ux4g.gov.in/web/llms/{tokens,utilities,layout,components,patterns}/…` |
| Figma community file | `figma.com/community/file/1654976809099378421` |
| **Theme Craft 2.0** Figma plugin | The official way to build and apply a department theme |
| Self-assessment | `ux4g.gov.in/resources/ux-self-health-check` |
| Accessibility audit tool | `audit360.ux4g.gov.in` |
| Free UX audit for ministries | `support.ux4g@digitalindia.gov.in` |

⚠️ **The accessibility-widget embed link is issued per registered domain.** A subdomain
needs its own registration at `ux4g.gov.in/resources/accessibility-widget` — reusing the
parent domain's link will not work. Plan this before launch if you serve a
`department.state.gov.in` style hostname.

⚠️ The widget does **not** confer compliance either. Their FAQ: *"full WCAG compliance
requires the website itself to be designed and developed according to accessibility
standards."*

## Do not do these

| Mistake | Why |
|---|---|
| Copying token names from `llms-full.txt` | 19 of 24 are fictional; they fail silently |
| `npm i ux4g-react` | Third-party impostor; no official React package exists |
| Loading UX4G beside Bootstrap/Tailwind unaudited | Global reset + bare `:focus` will reach your components |
| Shipping the 8 MB npm CSS to citizens | Subset it, or use the layered CDN build and self-host |
| Treating the accessibility widget as compliance | It is a widget, not an audit — and see the two defects noted in `indian-gov-web-ui` |
| Assuming v2 class names work in v3 | v2 is bare Bootstrap (`.btn`), v3 is namespaced (`.ux4g-btn`) |

## Related skills

- `dbim-brand-identity` — the mandatory GoI visual identity UX4G is meant to express
- `gov-service-patterns` — the 9 citizen service flows built from these components
- `indian-gov-web-ui` — GIGW 3.0, the WCAG criteria with legal teeth in India, Devanagari

## Reference files

- `tokens.md` — all 870 tokens by layer, with values, plus dark theme
- `components.md` — 52 components, every `.ux4g-*` class in each
- `patterns-utilities.md` — 16 pattern stylesheets, 28 utility modules, layout/grid classes