Agent index: https://ethux.design/llms.txt

EthUX Design

UX patterns and implementation guidance for Ethereum dApps, sourced from 32,000+ community reports of real user pain points.

Base URL: https://ethux.design
Local path: skills/ (relative to this file)

All skill paths below are given relative to this file's location. If fetching from the web, prepend https://ethux.design/. If reading locally, use the path as-is.

---

Skills

Skill	Path	Use when building...
Token Approvals	`skills/approvals/SKILL.md`	ERC-20 approve flows, Permit2 gasless signatures, EIP-5792 batched approve+action, approval display, revocation UI
Transaction Signing	`skills/signing/SKILL.md`	EIP-712 typed data, human-readable tx summaries, simulation/preview, multi-step progress, SIWE (EIP-4361)
Gas & Fees	`skills/gas/SKILL.md`	Fee display in fiat, paymaster sponsorship (ERC-7677), ERC-20 gas payment, L1/L2 fee breakdowns, high-gas warnings
Multi-Chain	`skills/multichain/SKILL.md`	Cross-chain balances, automatic network switching, chain-aware address validation, ERC-7683 intents, CREATE2 addresses
Onboarding	`skills/onboarding/SKILL.md`	First-run experience, delayed recovery backup, jargon replacement, simple/advanced modes, i18n
Wallet Connection	`skills/wallets/SKILL.md`	EIP-6963 discovery, mobile deep linking, session persistence, embedded/smart wallets, WalletConnect v2
Safety & Security	`skills/safety/SKILL.md`	Risk-tiered warnings, ENS resolution, ERC-55 checksum validation, spam token filtering, safe send-max

---

Routing Guide

Start here. Match your task to a skill, then read that skill's SKILL.md for patterns, code, and decision trees.

By user action

• User connects wallet → Wallet Connection
• User sees balances across chains → Multi-Chain
• User approves token spending → Token Approvals
• User signs or sends a transaction → Transaction Signing
• User sees fees or gas costs → Gas & Fees
• User encounters a warning or enters an address → Safety & Security
• User is new, first-run flow, or needs accessible UI → Onboarding

By EIP/standard

Standard	Skill
EIP-5792 (wallet_sendCalls)	Approvals, Gas
EIP-6963 (wallet discovery)	Wallets
EIP-712 (typed data signing)	Signing
EIP-4361 / SIWE	Signing
EIP-7702 (batch/delegation)	Signing, Wallets
ERC-7677 (paymaster)	Gas
ERC-7683 (cross-chain intents)	Multi-Chain
ERC-7930 (chain-specific addresses)	Multi-Chain
Permit2 / EIP-2612	Approvals
ENS (EIP-137)	Safety
ERC-55 (checksum)	Safety
BIP-39	Onboarding

Shared reference files (load only when needed)

These live under `skills/shared/references/` and are pointed to by the skills that need them:

Reference	Path	Needed for
EIP-5792 Capability Detection	`skills/shared/references/eip5792.md`	Any wallet_sendCalls or batching flow
Stuck Transactions	`skills/shared/references/stuck-transactions.md`	Pending transaction status UI
Irreversibility Framing	`skills/shared/references/irreversibility.md`	Value-transfer or approval confirmation screens

---

Shared UX Patterns

These patterns apply across all skill files. Only non-obvious, Ethereum-specific patterns are included here. Standard UX practices (skeleton loading, empty states, accessibility, responsive design) are assumed knowledge.

Loading Labels

Disable buttons and replace labels with context text during async operations:

• "Checking permissions..." (allowance lookup)
• "Estimating fee..." (gas estimation in progress)
• "Waiting for signature..." (wallet popup is open)
• "Confirming..." (transaction submitted, waiting for block inclusion)

NEVER show "$0.00" or "0" while calculating derived values (fiat conversion, swap output, gas estimates). Show "Estimating..." instead.

---

Post-Action Confirmation

After every signature or transaction submission, show a confirmation state. NEVER move immediately to the next step or show nothing.

For on-chain transactions:

Transaction submitted. Waiting for confirmation...
Estimated wait: ~[X] seconds
[Transaction hash as truncated link to block explorer] [Copy button]

For off-chain signatures:

Signed successfully. [Next step description or completion message]

After transaction confirmation:

Show the actual fee paid alongside the estimate: "Fee: $0.08 (estimated $0.12)." This builds trust.

Rules:

• NEVER show a "success" state for a submitted-but-unconfirmed transaction. "Submitted" and "confirmed" are different states. Show "Processing..." until the transaction is included in a block.
• NEVER auto-redirect the user away from a confirmation screen. Let them stay until they choose to navigate away.
• NEVER describe a signature as "free" without qualification. Off-chain signatures are gasless but they DO authorize actions. Say "No network fee" instead of "Free."

---

Error Message Formatting

Use three-tier progressive disclosure for all errors:

1. First layer (always visible): Plain-language summary. No jargon.
2. Second layer (expandable): More context and suggested action.
3. Third layer (copy-able): Full technical error, transaction hash, and raw message for support.

Error Jargon Translation Table

Apply this translation to every RPC or contract error before displaying to users:

Technical error	User-facing message
Execution reverted	Transaction failed.
Insufficient output amount	Price changed too much. Try increasing your price tolerance.
Nonce too low	This transaction was already processed. Refresh and try again.
Insufficient funds for gas	You don't have enough [native token] to cover the network fee.
User rejected transaction / User rejected	You cancelled the transaction.
Out of gas	The transaction ran out of processing power. Try again.
Contract execution error	Something went wrong with this operation.
Transfer from failed	The token transfer was rejected. Check your balance and permissions.
Overflow / Underflow	The amount is outside the allowed range. Try a smaller value.

Rules:

• NEVER show raw Solidity error strings to end users in the primary display.
• NEVER show gas cost in scientific notation or with more than 6 decimal places. Format for readability: "$0.12" or "0.00004 ETH", never "4.2e-5 ETH".
• NEVER show "Fee: $0.00" for sponsored transactions without the "(sponsored)" label.

---

Address Display Standards

• Truncation: 0x1234...5678 (first 6 + last 4 after 0x) for non-critical contexts. Show full address on send confirmations and approval targets.
• ENS: Show ENS name as primary, truncated address as secondary: vitalik.eth (0xd8dA...6045). Use useEnsName (wagmi) or getEnsName (viem). Also resolve avatar.
• Interactive: Every displayed address must be copyable (click/tap) with "Copied!" feedback, and linked to the relevant block explorer.