diff --git a/README.md b/README.md
index eece3fe..dc344f0 100644
--- a/README.md
+++ b/README.md
@@ -72,7 +72,11 @@ manifest/
### UI Design Philosophy
The UI follows a "Universal Paperclips" aesthetic — a deliberately spartan,
-almost brutalist approach:
+almost brutalist approach. The guiding principle is that an unskilled,
+non-technical person should be able to figure out how to use it without any
+crypto knowledge.
+
+#### Visual Style
- **Monochrome**: Black text on white background. No brand colors, no gradients,
no color-coding. Color may be introduced later for specific semantic purposes
@@ -84,9 +88,6 @@ almost brutalist approach:
Ethereum addresses, transaction hashes, and balances are inherently
fixed-width data. Rather than mixing proportional and monospace fonts, we use
monospace everywhere for visual consistency and alignment.
-- **Icon fonts only**: Where icons are needed (copy, send, settings, etc.) we
- use an icon font (no SVGs, no PNGs, no image assets). This keeps the extension
- size tiny and the build simple.
- **No images**: Zero image assets in the entire extension. No logos, no
illustrations, no token icons. Token identity is conveyed by symbol text (ETH,
USDC, etc.).
@@ -100,28 +101,76 @@ almost brutalist approach:
- **360x600 popup**: Standard browser extension popup dimensions. The UI is
designed for this fixed viewport — no responsive breakpoints needed.
+#### Language & Labeling
+
+All user-facing text avoids crypto jargon wherever possible:
+
+- "Recovery phrase" instead of "seed phrase", "mnemonic", or "BIP-39 mnemonic"
+- "Address" instead of "account", "derived key", or "HD child"
+- "Password" instead of "encryption key" or "vault passphrase"
+- "Private key" instead of "secret key" or "signing key"
+- Buttons use plain verbs: "Send", "Receive", "Copy address", "Add", "Back",
+ "Cancel", "Lock", "Unlock", "Allow", "Deny"
+- No bracket notation like `[locked]` or `[setup]` — just plain titles
+- Helpful inline descriptions where needed (e.g. "This password locks the wallet
+ on this device. It is not the same as your recovery phrase.")
+- Error messages are full sentences ("Please enter your password." not "password
+ required")
+
+#### Data Model
+
+The core hierarchy is **Wallets → Addresses**:
+
+- A **wallet** is either:
+ - An **HD wallet** (recovery phrase): generates multiple addresses from a
+ single 12/24 word recovery phrase using BIP-39/BIP-44 derivation. The user
+ can add more addresses with a "+" button.
+ - A **key wallet** (private key): a single address imported directly from a
+ private key. No "+" button since there is only one address.
+- An **address** holds ETH and any user-added ERC-20 tokens.
+- The user can have multiple wallets, each with multiple addresses (HD) or a
+ single address (key).
+
+#### Navigation
+
+The main view shows all addresses grouped by wallet, with ETH balances inline.
+The user taps an address to see its detail view (full address, balance, tokens,
+send/receive). Navigation is flat — every view has a "Back" or "Cancel" button
+that returns to the previous context. No deep nesting, no tabs, no hamburger
+menus.
+
### UI Views
The popup has the following views, switched via simple show/hide:
-1. **Lock screen**: Password input + unlock button. Shown when the wallet is
- locked or on first open after browser restart.
-2. **Setup / Onboarding**: Shown on first use. Create a new wallet (generates
- BIP-39 mnemonic, user confirms backup, sets password) or import an existing
- seed phrase.
-3. **Main / Account view**: The default view after unlock. Shows the current
- account address (truncated, click to copy), ETH balance, list of added ERC-20
- tokens with balances, and action buttons (Send, Receive, Settings).
-4. **Send**: Form with To address, amount, token selector (ETH or any added
- ERC-20), and a Send button. Shows gas estimate before confirming.
-5. **Receive**: Displays the current account address in full (copyable). That's
- it.
-6. **Settings**: Configure RPC endpoint URL, manage wallets (add/remove seed
- phrases), derive additional accounts, view/export seed phrase (requires
- password re-entry), manage added ERC-20 tokens.
-7. **Approval popups**: When a connected site requests a transaction signature
- or message signature, an approval view shows the details and Approve/Reject
- buttons.
+1. **Lock**: Password input + Unlock button. Shown when the wallet is locked or
+ on first open after browser restart.
+2. **Welcome**: Shown on first use. Three options: "Create a new wallet", "I
+ have a recovery phrase", "I have a private key". Password is set during this
+ first flow.
+3. **Create**: Displays a generated 12-word recovery phrase with instructions to
+ write it down. User sets a password and confirms.
+4. **Import recovery phrase**: Paste a 12 or 24 word recovery phrase. Password
+ fields shown only on first use.
+5. **Import private key**: Paste a private key. Password fields shown only on
+ first use.
+6. **Main**: All wallets listed, each showing its addresses with truncated
+ address and ETH balance. "+" next to HD wallets to add another address. "+
+ Add wallet" at the bottom. Settings and Lock buttons in the header. Future: a
+ sub-heading showing total portfolio value in USD (and eventually other
+ currencies).
+7. **Add wallet**: Choose wallet type (new, recovery phrase, private key) — same
+ three options as Welcome but without password setup.
+8. **Address detail**: Full address (click to copy), ETH balance, USD value
+ (future), Send/Receive buttons, token list with "+ Add" button.
+9. **Send**: Token selector, recipient address, amount. Cancel returns to
+ address detail.
+10. **Receive**: Full address displayed with "Copy address" button.
+11. **Add token**: Enter contract address. The extension looks up the token
+ name/symbol automatically.
+12. **Settings**: Network (RPC endpoint URL) with explanatory text.
+13. **Approval**: When a website requests wallet access or a signature, shows
+ the site origin, request details, and Allow/Deny buttons.
### External Services
@@ -167,30 +216,31 @@ want maximum privacy can point it at their own Ethereum node.
### Supported Functionality
-- Create new wallet from generated BIP-39 mnemonic
-- Import wallet from existing BIP-39 mnemonic
-- Derive multiple HD addresses per wallet (`m/44'/60'/0'/0/n`)
-- View ETH balance
+- Create new HD wallet (generates 12-word recovery phrase)
+- Import HD wallet from existing 12 or 24 word recovery phrase
+- Import single-address wallet from private key
+- Add multiple addresses within an HD wallet
+- Manage multiple wallets simultaneously
+- View ETH balance per address
- View ERC-20 token balances (user adds token by contract address)
- Send ETH to an address
- Send ERC-20 tokens to an address
-- Receive ETH/tokens (display address + copy to clipboard)
+- Receive ETH/tokens (display address, copy to clipboard)
- Connect to web3 sites (EIP-1193 `eth_requestAccounts`)
- Sign transactions requested by connected sites
- Sign messages (`personal_sign`, `eth_sign`)
-- Switch between wallets/accounts
- Lock/unlock with password
- Configurable RPC endpoint
+- Future: USD value display (and other fiat currencies)
### Non-Goals
- Token swaps (use a DEX in the browser)
-- Portfolio/price tracking (balances shown in token units only, no fiat)
- NFT display or management
- Multi-chain support (Ethereum mainnet only, for now)
- Analytics, telemetry, or tracking of any kind
- Advertisements or promotions
-- Phishing detection (use your brain)
+- Phishing detection
- Hardware wallet support (maybe later)
- Token list auto-discovery (user adds tokens manually)
- Fiat on/off ramps
@@ -200,19 +250,22 @@ want maximum privacy can point it at their own Ethereum node.
## TODO
- [x] Project scaffolding (Makefile, Dockerfile, CI, manifests)
-- [ ] Set up Tailwind CSS build pipeline
-- [ ] Build popup UI views (lock, setup, main, send, receive, settings)
+- [x] Set up Tailwind CSS build pipeline
+- [x] Build popup UI views (all 13 views with stub state)
- [ ] Implement BIP-39 mnemonic generation and validation
- [ ] Implement BIP-32/BIP-44 HD key derivation for Ethereum
-- [ ] Implement encrypted storage for seed phrases
+- [ ] Implement private key import and address derivation
+- [ ] Implement encrypted storage for wallet data
- [ ] Implement background wallet manager
- [ ] Implement EIP-1193 provider and content script injection
-- [ ] Implement ETH balance lookup and send
+- [ ] Implement ETH balance lookup via RPC
+- [ ] Implement ETH send (transaction construction + signing)
- [ ] Implement ERC-20 token management (add by contract, view balance, send)
- [ ] Implement site connection approval flow
- [ ] Implement transaction signing approval flow
- [ ] Implement message signing (`personal_sign`, `eth_sign`)
-- [ ] Add configurable RPC endpoint
+- [ ] Add USD value display (price feed TBD)
+- [ ] Add multi-currency fiat display support
- [ ] Test on Chrome and Firefox
- [ ] Write tests for crypto operations
- [ ] Write tests for transaction construction
diff --git a/src/popup/index.html b/src/popup/index.html
index 2e85bdf..2e1fb69 100644
--- a/src/popup/index.html
+++ b/src/popup/index.html
@@ -11,22 +11,24 @@
- AutistMask [locked]
+ AutistMask
+
+ Your wallet is locked. Enter your password to continue.
+
-
+
-
-
+
+
- AutistMask [setup]
+ Welcome to AutistMask
-
No wallet found. Create or import one.
-
+
+ To get started, add a wallet. You can create a brand new one
+ or bring in one you already have.
+
+
+
-
+
- AutistMask [create wallet]
+ Create New Wallet
- Write down this seed phrase and store it safely. It is the
- only way to recover your wallet.
+ These 12 words are your recovery phrase. Write them down on
+ paper and keep them somewhere safe. Anyone with these words
+ can access your funds. If you lose them, your wallet cannot
+ be recovered.
-
+
+
+ This password locks the wallet on this device. It is not
+ the same as your recovery phrase.
+
-
+
@@ -92,13 +107,13 @@
id="btn-create-confirm"
class="border border-border px-2 py-1 hover:bg-fg hover:text-bg cursor-pointer"
>
- i backed it up, create wallet
+ I wrote it down — continue