SKILL.md
Two-Factor Authentication
Two-factor authentication setup and verification
What it solves
Two-Factor Authentication (2FA) adds a second verification step after the user enters their password, requiring proof of something they have (a phone, security key, or authenticator app) in addition to something they know (their password). This dramatically reduces the risk of unauthorized access from stolen credentials. The 2FA pattern covers both the setup flow (enrolling a second factor) and the verification flow (entering a code or using a device during login).
When to use
Use Two-Factor Authentication to protect accounts with an additional verification layer beyond username and password. Common scenarios include:
- Financial applications, banking, and payment platforms
- Email services and communication platforms
- Admin dashboards and privileged user accounts
- Healthcare and legal applications with sensitive data
- Developer platforms with access to infrastructure and code repositories
When to avoid
- Low-risk applications where the cost of 2FA outweighs the security benefit
- Applications targeting users with limited technical proficiency (consider risk-based auth instead)
- When the friction of 2FA would significantly reduce adoption of a consumer product (make it optional)
- Kiosk or shared-device environments where device-based factors are impractical
Implementation workflow
- Confirm the pattern matches the problem and constraints before copying the example.
- Start from the anatomy and examples in
references/pattern.md, then choose the smallest viable variation. - Apply accessibility, performance, and interaction guardrails before layering visual polish.
- Use the testing guidance to verify behavior across keyboard, screen reader, responsive, and failure scenarios.
Accessibility guardrails
Do's ✅
- Use
inputmode="numeric"on the code input for the numeric keyboard on mobile - Use
autocomplete="one-time-code"so browsers and password managers can autofill SMS codes - Provide
alttext for the QR code image describing its purpose - Announce errors with
role="alert"when an invalid code is entered - Provide a text-based alternative to the QR code (manual entry of the secret key)
Don'ts ❌
- Don't make the QR code the only way to set up TOTP — always offer manual entry
- Don't use time pressure that penalizes users who need more time to enter codes
- Don't rely on color alone for success/error feedback on code entry
Performance guardrails
Target Metrics
- QR code generation: < 200ms server-side
- Code verification: < 300ms server-side
- SMS delivery: < 10 seconds
- Code input response: < 50ms keystroke-to-display
- Auto-submit: < 100ms from 6th digit to submission
Optimization Strategies
Client-Side QR Code Generation
const qrDataUrl = await QRCode.toDataURL(totpUri);Common mistakes
No Backup Code Recovery
The Problem: Users who lose their authenticator device have no way to access their account.
How to Fix It: Generate 8-10 one-time backup codes during 2FA setup. Clearly prompt users to save them. Provide a backup code entry option on the verification screen.
SMS as the Only 2FA Method
The Problem: SMS codes are vulnerable to SIM swapping, SS7 interception, and delivery delays.
How to Fix It: Offer TOTP (authenticator app) as the primary method. Use SMS only as a fallback. Consider supporting security keys for high-security accounts.
Time-Skew Rejection
The Problem: TOTP codes are rejected because the user's device clock is slightly out of sync with the server.
How to Fix It: Accept codes from the current time window plus one window before and after (±30 seconds). This is standard TOTP tolerance.
Related patterns
- https://uxpatterns.dev/patterns/authentication/account-settings
- https://uxpatterns.dev/patterns/authentication/login
- https://uxpatterns.dev/patterns/authentication/password-reset
- https://uxpatterns.dev/patterns/authentication/social-login
For full implementation detail, examples, and testing notes, see references/pattern.md.
Pattern page: https://uxpatterns.dev/patterns/authentication/two-factor