feat: add BalanceEmptyState component

[georgewrmarshall]

Description

This PR introduces a new BalanceEmptyState component to improve the user experience when users have zero balance in their wallet. The component encourages users to add funds with a clear call-to-action and provides visual guidance through an engaging UI.

The component includes:

• Visual bank transfer icon to represent funding actions
• Clear messaging with i18n support for "Fund your wallet" and "Get your wallet ready to use web3"
• Integration with the existing ramps system for buying crypto
• Comprehensive MetaMetrics tracking for user interactions
• Full test coverage and Storybook documentation

Changelog

CHANGELOG entry: Added BalanceEmptyState component to guide users with zero balance to add funds

Related issues

Fixes:

Manual testing steps

1. Ensure you have a wallet with zero balance across all tokens
2. Navigate to the tokens/balance view where the empty state should appear
3. Verify the component displays with proper styling and messaging
4. Click the "Add funds" button and verify it opens the buy crypto flow
5. Check that MetaMetrics events are properly tracked
6. Test in different locales to verify i18n strings work correctly

Screenshots/Recordings

Before

After

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Extension Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[metamaskbot]

📊 Page Load Benchmark Results

Current Commit: d1d50f4 | Date: 10/17/2025

📄 Localhost MetaMask Test Dapp

Samples: 100

Summary

• pageLoadTime-> current mean value: 1.05s (±100ms) 🟡 | historical mean value: 1.04s ⬆️ (historical data)
• domContentLoaded-> current mean value: 740ms (±98ms) 🟢 | historical mean value: 734ms ⬆️ (historical data)
• firstContentfulPaint-> current mean value: 83ms (±60ms) 🟢 | historical mean value: 77ms ⬆️ (historical data)

📈 Detailed Results

Metric	Mean	Std Dev	Min	Max	P95	P99
pageLoadTime	1.05s	100ms	1.00s	1.78s	1.24s	1.78s
domContentLoaded	740ms	98ms	699ms	1.45s	931ms	1.45s
firstPaint	83ms	60ms	60ms	676ms	88ms	676ms
firstContentfulPaint	83ms	60ms	60ms	676ms	88ms	676ms
largestContentfulPaint	0ms	0ms	0ms	0ms	0ms	0ms

---

Results generated automatically by MetaMask CI

[metamaskbot]

Builds ready [d1d50f4]

• builds: chrome, firefox
• builds (beta): chrome, firefox
• builds (flask): chrome, firefox
• builds (test): chrome, firefox
• builds (test-flask): chrome, firefox
• build viz: Build System
• bundle size: Bundle Size Stats
• user-actions-benchmark: User Actions Stats
• storybook: Storybook
• typescript migration: Dashboard
• all artifacts
• bundle viz:

  • background: 0, 1, 2, 3, 4, 5, 6, 7, 8
  • common: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13
  • ui: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
  • content-script: 0
  • offscreen: 0

UI Startup Metrics (1238 ± 65 ms)

Platform	BuildType	Page	Metric	Mean (ms)	Min (ms)	Max (ms)	Std Dev (ms)	P 75 (ms)	P 95 (ms)
Chrome	Browserify	Home	uiStartup	1238	1104	1436	65	1286	1344
			load	1068	962	1265	61	1113	1179
			domContentLoaded	1062	954	1233	59	1108	1165
			domInteractive	18	13	140	13	17	34
			firstPaint	646	146	1241	432	1074	1158
			backgroundConnect	251	238	280	6	255	263
			firstReactRender	26	18	56	7	28	41
			getState	15	5	101	11	17	29
			initialActions	5	0	40	7	5	15
			loadScripts	816	712	983	59	859	917
			setupStore	10	6	23	3	11	15
	Webpack	Home	uiStartup	824	708	1160	75	837	983
			load	622	573	894	63	627	809
			domContentLoaded	614	568	885	62	621	792
			domInteractive	15	11	54	7	13	34
			firstPaint	196	57	821	175	195	593
			backgroundConnect	21	10	44	7	26	33
			firstReactRender	29	17	254	24	31	34
			getState	9	4	22	3	11	15
			initialActions	3	0	11	2	4	7
			loadScripts	612	566	875	60	619	782
			setupStore	9	5	24	3	11	13
Firefox	Browserify	Home	uiStartup	1427	1219	1859	115	1471	1665
			load	1221	1046	1532	87	1274	1379
			domContentLoaded	1221	1046	1532	87	1274	1378
			domInteractive	119	34	472	62	129	263
			firstPaint	NaN	NaN	NaN	NaN	NaN	NaN
			backgroundConnect	33	18	114	16	36	65
			firstReactRender	24	20	44	4	25	36
			getState	8	4	51	6	7	16
			initialActions	4	1	36	4	3	13
			loadScripts	1199	1030	1512	83	1257	1332
			setupStore	11	5	83	10	10	31
	Webpack	Home	uiStartup	1611	1439	2050	111	1647	1889
			load	1376	1206	1563	79	1433	1522
			domContentLoaded	1376	1206	1563	79	1433	1522
			domInteractive	111	33	375	64	111	327
			firstPaint	NaN	NaN	NaN	NaN	NaN	NaN
			backgroundConnect	40	22	122	17	43	75
			firstReactRender	31	23	76	12	32	73
			getState	9	4	129	12	9	16
			initialActions	4	2	97	10	3	10
			loadScripts	1349	1190	1534	78	1397	1503
			setupStore	11	5	98	11	10	31

Bundle size diffs [🚨 Warning! Bundle size has increased!]

• background: -46.52 KiB (-1.02%)
• ui: 10.47 KiB (0.16%)
• common: 61.71 KiB (0.74%)

[metamaskbot]

📊 Page Load Benchmark Results

Current Commit: 5c4b9b0 | Date: 10/18/2025

📄 Localhost MetaMask Test Dapp

Samples: 100

Summary

• pageLoadTime-> current mean value: 1.08s (±76ms) 🟡 | historical mean value: 1.04s ⬆️ (historical data)
• domContentLoaded-> current mean value: 759ms (±74ms) 🟢 | historical mean value: 733ms ⬆️ (historical data)
• firstContentfulPaint-> current mean value: 81ms (±12ms) 🟢 | historical mean value: 77ms ⬆️ (historical data)

📈 Detailed Results

Metric	Mean	Std Dev	Min	Max	P95	P99
pageLoadTime	1.08s	76ms	1.03s	1.37s	1.32s	1.37s
domContentLoaded	759ms	74ms	715ms	1.05s	984ms	1.05s
firstPaint	81ms	12ms	64ms	180ms	96ms	180ms
firstContentfulPaint	81ms	12ms	64ms	180ms	96ms	180ms
largestContentfulPaint	0ms	0ms	0ms	0ms	0ms	0ms

---

Results generated automatically by MetaMask CI

[metamaskbot]

Builds ready [5c4b9b0]

• builds: chrome, firefox
• builds (beta): chrome, firefox
• builds (flask): chrome, firefox
• builds (test): chrome, firefox
• builds (test-flask): chrome, firefox
• build viz: Build System
• bundle size: Bundle Size Stats
• user-actions-benchmark: User Actions Stats
• storybook: Storybook
• typescript migration: Dashboard
• all artifacts
• bundle viz:

  • background: 0, 1, 2, 3, 4, 5, 6, 7, 8
  • common: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13
  • ui: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
  • content-script: 0
  • offscreen: 0

UI Startup Metrics (1227 ± 70 ms)

Platform	BuildType	Page	Metric	Mean (ms)	Min (ms)	Max (ms)	Std Dev (ms)	P 75 (ms)	P 95 (ms)
Chrome	Browserify	Home	uiStartup	1227	1100	1457	70	1271	1360
			load	1057	951	1227	64	1091	1189
			domContentLoaded	1051	943	1222	64	1081	1183
			domInteractive	17	12	123	11	16	26
			firstPaint	664	72	1224	427	1059	1145
			backgroundConnect	251	236	281	8	254	266
			firstReactRender	24	17	57	6	25	40
			getState	16	5	87	10	19	34
			initialActions	6	0	74	10	5	15
			loadScripts	806	708	972	62	835	943
			setupStore	9	6	24	3	10	14
	Webpack	Home	uiStartup	836	711	1082	88	847	1056
			load	629	575	914	79	628	899
			domContentLoaded	621	571	903	78	623	889
			domInteractive	15	11	57	8	14	35
			firstPaint	182	54	909	177	193	585
			backgroundConnect	21	10	39	7	25	34
			firstReactRender	29	16	235	23	32	59
			getState	9	3	19	3	11	12
			initialActions	3	0	8	2	4	6
			loadScripts	618	569	892	76	621	879
			setupStore	10	5	27	3	11	13
Firefox	Browserify	Home	uiStartup	1324	1181	1575	84	1368	1527
			load	1142	1025	1390	70	1183	1249
			domContentLoaded	1142	1025	1390	70	1183	1249
			domInteractive	97	34	253	42	107	197
			firstPaint	NaN	NaN	NaN	NaN	NaN	NaN
			backgroundConnect	31	21	121	13	35	51
			firstReactRender	22	18	33	3	23	27
			getState	7	4	25	3	7	12
			initialActions	3	1	9	1	3	4
			loadScripts	1121	1008	1372	69	1160	1233
			setupStore	9	5	44	5	9	14
	Webpack	Home	uiStartup	1546	1367	1885	115	1577	1802
			load	1334	1194	1600	90	1390	1510
			domContentLoaded	1334	1193	1600	90	1390	1510
			domInteractive	109	30	375	73	106	350
			firstPaint	NaN	NaN	NaN	NaN	NaN	NaN
			backgroundConnect	33	19	92	10	39	46
			firstReactRender	28	22	74	7	29	40
			getState	8	5	67	7	8	13
			initialActions	5	1	90	10	3	14
			loadScripts	1312	1177	1573	88	1361	1480
			setupStore	12	5	91	15	10	36

Bundle size diffs [🚨 Warning! Bundle size has increased!]

• background: 58 Bytes (0%)
• ui: 0 Bytes (0%)
• common: 322 Bytes (0%)