# Gov Service Patterns

> Use when designing or building a citizen-facing government service flow — sign-in/OTP/Aadhaar authentication, consent and declaration, multi-step application submission, application/grievance status tracking, fee payment, service search and slot booking, citizen or officer dashboards, notifications, or feedback and grievance capture. Triggers include "government service flow", "citizen journey", Aadhaar/OTP auth screens, "track my application", "grievance", "e-district", "seva", DigiLocker-style consent, or any UX4G pattern.

- Skill: `yashraj00700/gov-service-patterns` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add yashraj00700/gov-service-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yashraj00700/gov-service-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Yashraj00700 (https://skillmd.com/u/yashraj00700)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yashraj00700/gov-service-patterns

---


# Government Service Patterns (UX4G)

## Overview

UX4G ships **78 documented patterns across 9 families, covering 209 distinct screen states**,
for Indian government citizen services. This is the part of UX4G worth the most, because
the hard problem in government UX is not the button — it is the **failure, expiry, lockout
and partial-completion states** that a citizen actually hits.

Extracted from `doc.ux4g.gov.in/web/llms/patterns/` on 30 Jul 2026. Every pattern document
carries full HTML, React JSX and Angular markup for every state.

**Core principle:** in a government service the citizen usually has no alternative provider
and often no second chance that day. **Design the unhappy path first.** These patterns are
valuable mainly as a checklist of states you would otherwise forget.

## The 9 families

| Family | Patterns | States | What it covers |
|---|---|---|---|
| **Identity & Access** | 9 | 61 | Sign in/up, OTP, Aadhaar auth, biometric, forgot/reset password, session timeout, operator-assisted verification |
| **Feedback & Communication** | 25 | 58 | Service feedback, grievance capture, contact/support, language switching, inline status communication |
| **Application & Submission** | 6 | 35 | Eligibility check, government forms, document upload, journey progress, save & resume, acknowledgement |
| **Consent & Declaration** | 6 | 13 | Data-sharing consent, declarations, consent history, withdrawal, managing consents |
| **Search & Discovery** | 12 | 12 | Global service discovery, autocomplete, results, no-results, service detail, slot booking, reschedule |
| **Payment & Transactions** | 7 | 8 | Payment method, redirect, success, failure, confirmation, fee waiver, pending tasks |
| **Notifications** | 4 | 12 | Notification centre, SMS & email notifications |
| **Dashboard & My Applications** | 5 | 6 | Overview, search & filter, batch actions, profile & preferences, empty state |
| **Status & Tracking** | 4 | 4 | Application tracker, grievance tracker, inspection & test slots |

Full per-pattern state lists → `pattern-catalog.md`

To get the markup for any pattern:
```
https://doc.ux4g.gov.in/web/llms/patterns/<file>.md
```
Each has three layouts: **Column**, **Full Screen**, and **Card**.

## The states people forget

This is the real payload. Taken from the documented state lists:

### Identity & Access
Aadhaar Authentication documents **11 states**, and the ones teams miss are all at the end:

- Face Authentication · Number Entry · OTP with **active timer**
- **Error — Authentication Failed**
- **Account Locked**
- **Operator-Assisted Authentication** — someone at a counter doing it for a citizen who can't
- **Session Expiring — Warning** → **Session Expiring Soon — Critical** → **Session Ended**
  (three distinct states, not one)

OTP Verification documents attempt-level granularity:
- **Error — Incorrect OTP (Attempt 1)** and **Error — Incorrect OTP (Last Attempt)** are
  *different screens*. Tell the citizen how many tries remain before the last one.
- **OTP Expired — Resend Available** is separate from an incorrect OTP.
- **Locked — Too Many Attempts** needs a route out, not a dead end.

### Application & Submission
- **Save & Resume** — 35 states across this family exist largely because government forms
  are long and sessions die. A citizen who loses a half-filled form loses a day.
- **Check Eligibility** before the form, not after — the largest document in the whole
  corpus (1.5 MB) is eligibility checking.
- **Submission Acknowledgement** must carry a reference number the citizen can quote.

### Payment & Transactions
- **Payment Redirect** and **Payment Failed** are mandatory states, not edge cases. Fee
  payment goes out to a PG and comes back; the citizen must never be left unsure whether
  money left their account.
- **Fee Waived** exists as a first-class state — many government services are free for
  some applicants.

### Status & Tracking
- Separate **Application Tracker** and **Grievance Tracker**. A grievance about a delayed
  application is a different object from the application.
- Pair with the `sla-progress-indicator` component — a government service usually promises
  a statutory deadline, and showing it is the point.

### Consent & Declaration
- **Consent History**, **Manage Data Sharing Consents** and **Withdraw Consent** are all
  documented. Consent that cannot be reviewed or withdrawn is not consent — and this is
  where DPDP Act expectations land.

## Accessibility obligations these flows trigger

Government service flows hit the WCAG criteria with real teeth in India. The ones that
bite specifically in *these* patterns:

| SC | Where it bites |
|---|---|
| **3.3.4** Error Prevention (Legal, Financial, Data) | AA. Any submission, payment or consent screen. Needs Reversible **or** Checked **or** Confirmed |
| **3.3.1 / 3.3.3** Error identification + suggestion | Every OTP error, form validation, failed payment |
| **4.1.3** Status Messages | The OTP timer, "Saved", upload progress. `role="status"`; errors `role="alert"` |
| **2.2.1** Timing Adjustable | **Session timeout and OTP timers.** The three-stage session-expiry pattern exists for this |
| **2.2.6** Timeout | AAA, but relevant: warn users of data loss from inactivity — the Save & Resume case |
| **1.4.10** Reflow | A sticky bottom "Submit" bar can fail at 400% zoom |
| **1.3.5** Identify Input Purpose | Autocomplete on name/address/phone in long forms |

An OTP screen with a countdown and no `role="status"`, no way to extend, and a hard lockout
fails 2.2.1, 4.1.3 and arguably 3.3.4 at once.

## India-specific components these patterns use

From `ux4g-design-system`:

`aadhaar-input` · `pan-card-input` · `otp-input` · `biometric-capture` ·
`sla-progress-indicator` · `status-pipeline` / `vertical-status-pipeline` ·
`draft-status-banner` · `time-slot` / `slot-grid` · `result-list-row` · `stepper` ·
`file-upload`

## Applying these well

1. **Start from the state list, not the happy path.** Open the pattern in
   `pattern-catalog.md`, take its documented states as your minimum screen inventory, and
   justify any you drop.
2. **Never machine-translate a legal declaration or consent text.** Get the authoritative
   translation, or show the source language and say so.
3. **Aadhaar data is sensitive.** Never log a full Aadhaar number, never put it in a URL or
   query string, mask on display, and prefer a virtual ID or token where the service allows
   it. Collect it only where there is statutory basis.
4. **Assume the citizen is on a slow phone**, possibly assisted by an operator at a CSC.
   The Operator-Assisted Authentication state exists because that is a real channel.
5. **Reference numbers everywhere.** Any acknowledgement, failure or grievance needs an ID
   the citizen can read out over a phone.
6. **The three-stage session expiry is the pattern to copy.** Warning → critical → ended,
   with a way to extend before the end.

## Common mistakes

| Mistake | Reality |
|---|---|
| One generic "error" screen for OTP | The corpus separates attempt-1, last-attempt, expired and locked. Each needs different copy |
| Treating payment failure as an edge case | It is a documented first-class state. Money ambiguity is the worst outcome in gov UX |
| No save & resume on a long form | Sessions die; government forms are long. This loses citizens a whole day |
| Consent with no withdrawal path | Consent History / Withdraw Consent are documented patterns for a reason |
| Countdown timer with no live region | Fails 4.1.3; a screen-reader user never learns the OTP expired |
| Hard lockout with no recovery route | Needs a documented way back — operator-assisted or account recovery |
| Copying the pattern markup unaudited | UX4G's own FAQ: using the design system does **not** make you WCAG/GIGW compliant. An audit is still required |
| Assuming eligibility is checked at submission | Check it first — that is why it's the largest pattern document |

## Related skills

- `ux4g-design-system` — the components and tokens these patterns are built from
- `dbim-brand-identity` — the GoI visual identity these flows must carry
- `indian-gov-web-ui` — GIGW 3.0 page requirements and India's WCAG legal exposure

## Reference files

- `pattern-catalog.md` — all 78 patterns, 209 states, grouped by family, with source filenames