In che modo un bot di revisione di Modern Web Guidance aiuta MetaMask a fornire un'UI moderna e accessibile

Gilberto Cocchi

Rick Viscomi

Data di pubblicazione: 10 novembre 2026

MetaMask è una piattaforma finanziaria con custodia autonoma con oltre 100 milioni di download in circa 190 paesi. La sua estensione del browser è sviluppata in modo aperto, quindi un flusso costante di richieste di pull proviene da collaboratori interni ed esterni all'azienda.

Lo specialista UX di MetaMask Francis Nepomuceno ha esaminato molte di queste richieste di pull e voleva un modo coerente per aiutare i collaboratori ad applicare le best practice di accessibilità e a utilizzare le funzionalità web moderne. Nel suo editor, ha già utilizzato Modern Web Guidance di Chrome, un insieme di competenze che fornisce agli agenti di programmazione le best practice della piattaforma web e i dati di compatibilità del browser. Per fornire le stesse indicazioni ad altri collaboratori, ha configurato un bot per esaminare ogni richiesta di pull nel repository open source di MetaMask, indipendentemente dagli strumenti utilizzati dall'autore.

La sfida: stare al passo con le funzionalità web moderne

HTML e CSS moderni continuano ad aggiungere funzionalità che migliorano l'accessibilità e l'esperienza utente, ma è difficile monitorare quali funzionano su tutti i browser. Con molti collaboratori, queste conoscenze devono raggiungere tutti coloro che aprono una richiesta di pull.

La sicurezza aggiunge un altro motivo di interesse: MetaMask esegue il sandboxing di ogni dipendenza di terze parti per impostazione predefinita, il che rende l'adozione di una funzionalità nativa del browser più economica rispetto a un'alternativa di libreria. Come ha affermato Nepomuceno, "avere accesso a queste API moderne, come la possibilità di utilizzare finestre di dialogo e menu a discesa senza JavaScript, è stato un grande vantaggio".

La soluzione: Modern Web Guidance esamina ogni richiesta di pull

Il 16 settembre 2026, una richiesta di pull a MetaMask/metamask-extension ha aggiunto una pagina "Come funziona" con una sezione Domande frequenti creata come la maggior parte delle sezioni Domande frequenti di React:

// Before: Custom React state (removes content from DOM)
const [expanded, setExpanded] = useState(false);
<button type="button" aria-expanded={expanded} onClick={() => setExpanded(c => !c)}>
  <Text>{question}</Text>
</button>
{expanded ? <Text>{answer}</Text> : null}

Circa cinque minuti dopo, il bot ha commentato. Citando la guida di search-hidden-content, ha sottolineato tre punti:

• Il rendering condizionale di ogni risposta la rimuove dal DOM, quindi il testo compresso non può essere trovato con la funzione di ricerca in-page del browser ed è più difficile da rilevare per le tecnologie per la disabilità.
• Una divulgazione nativa <details>/<summary> (Baseline dal 2020) mantiene i contenuti nel DOM con la semantica corretta. Per i riquadri che si escludono a vicenda, un attributo name condiviso (Baseline, disponibile dal 2024) chiude automaticamente gli altri; per una sezione di domande frequenti con più riquadri aperti, omettilo.
• Se il team preferiva il componente Disclosure esistente, avrebbe dovuto almeno mantenere le risposte nel DOM con hidden="until-found" e un listener beforematch che sincronizza aria-expanded e lo stato dell'icona.

// After: Native <details> / <summary> disclosure (findable with find-in-page)
<details>
  <summary>
    <Text>{question}</Text>
  </summary>
  <Text>{answer}</Text>
</details>

Tredici minuti dopo, l'autore ha pubblicato una correzione. Il componente è diventato un elemento di divulgazione nativo <details>/<summary>, le risposte compresse sono rimaste nel DOM per la ricerca in-page e due pulsanti di navigazione sono diventati link.

Questo bot è un Cursor Automation che esegue Modern Web Guidance e Nepomuceno lo ha configurato con un prompt di tre righe. Entro il 21 ottobre 2026, cinque settimane dopo:

• Il bot era stato eseguito su circa 480 richieste di pull e aveva commentato 64 di queste (57 richieste di pull di funzionalità e correzioni, più 7 richieste di pull di rilascio e sincronizzazione automatiche) di 26 autori.
• Nelle richieste di pull di funzionalità e correzioni, gli ingegneri hanno corretto 43 dei risultati e ne hanno corrette parzialmente altre 3, in 22 richieste di pull.
• Gli ingegneri hanno agito rapidamente: delle 38 correzioni con un commit identificabile, 19 sono state applicate entro 15 minuti e 26 entro un'ora, con una mediana di 15,2 minuti dal commento alla correzione.

Ecco come MetaMask ha configurato il bot, cosa ha rilevato e dove ha generato rumore.

La configurazione è un prompt di tre righe

Alla domanda su come è configurata l'automazione, Nepomuceno ha risposto: "Certo, non c'è nulla di speciale nella nostra configurazione. Ci limitiamo a mantenerlo conciso e mirato." L'intera istruzione:

- Run /modern-web-guidance for any client-facing changes
- Run /chrome-extensions for any relevant extension changes
- Comment on the PR only when there are issues to address. Keep the comment focused on actionable items

Come funziona in pratica:

• È consultivo: nei primi due giorni, il bot ha pubblicato recensioni di "richiesta di modifiche " (e un'approvazione), che gli autori hanno ignorato una volta risolte; dal 18 settembre, ogni recensione è un commento. Non blocca un'unione, quindi gli autori hanno l'ultima parola su ogni suggerimento.
• Cita guide e file specifici nel repository: nelle 64 richieste di pull su cui ha commentato, il bot ha sollevato 122 risultati. Delle 102 richieste di pull per funzionalità e correzioni, 63 indicano la guida specifica di Modern Web Guidance che stanno applicando, ad esempio search-hidden-content, state-aware-sticky-headers o sms-otp-form, e rimandano a un file esistente nel repository quando utilizza già il pattern consigliato.
• Rimane inattivo a meno che una richiesta di pull non tocchi l'interfaccia utente: delle circa 480 richieste di pull in queste cinque settimane, almeno 100 hanno toccato l'interfaccia utente o il codice client e il bot ha rilevato in media circa due risultati per ogni richiesta di pull su cui ha commentato. I team con repository prevalentemente frontend possono aspettarsi che i commenti riguardino una quota maggiore.

Il prompt stesso funziona con qualsiasi agent runner; Modern Web Guidance si installa come skill o plug-in per Cursor, Claude Code, Codex, GitHub Copilot, Antigravity e altri agenti di programmazione. Quando un agente esegue la skill, cerca le guide corrispondenti in un indice locale senza bisogno di chiavi API e confronta le differenze con queste, utilizzando il modello già fornito dall'esecutore dell'agente del team.

Cosa ha rilevato Modern Web Guidance che i linter non hanno rilevato

Un linter statico può segnalare un attributo mancante su un singolo elemento, ma i risultati che seguono si sono ridotti al comportamento di interazione, alla semantica HTML e al modo in cui i componenti si integrano tra i file.

Un campo della commissione di transazione che sembrava modificabile, ma ignorava l'input senza avvisare

Nelle impostazioni avanzate delle commissioni di transazione di MetaMask, il campo del limite di gas (che limita la commissione di rete che una transazione può consumare) sembrava modificabile, ma ignorava silenziosamente l'input degli utenti. Questo accadeva quando una stima della tariffa era ancora in fase di caricamento o non era andata a buon fine. Nel frattempo, il pulsante Salva è stato disattivato, senza alcuna spiegazione che le tecnologie per la disabilità potessero leggere.

Citando la guida ai moduli, il bot ha segnalato tre correzioni:

• Disattiva il campo del limite di gas quando non è disponibile alcuna stima e collega il testo dello stato visibile al campo in modo che le tecnologie per la disabilità leggano la spiegazione.
• Collega il pulsante Salva disattivato allo stesso testo di stato in modo che gli screen reader sappiano perché è disattivato.
• Imposta il campo sulla modalità di immissione numerica in modo che gli utenti di dispositivi mobili visualizzino un tastierino numerico.

L'autore ha applicato tutte e tre le correzioni in entrambe le finestre modali delle impostazioni e le ha consolidate in un unico componente.

Pulsanti del banner che nascondevano i relativi URL

In un banner di stato per una delle funzionalità di trading di MetaMask, le azioni in linea "FAQ " e"Contatta l'assistenza MetaMask" sono state create come pulsanti che aprivano una nuova scheda con JavaScript anziché come link. Entro tre minuti, il bot, citando le guide HTML e di accessibilità, ha segnalato che gli screen reader li annunciano come pulsanti e che gli utenti perdono le affordance dei link, come la copia dell'URL o l'apertura in una nuova scheda dal menu contestuale. Inoltre, indicava un componente banner esistente nel codebase di MetaMask che visualizza già queste azioni come link reali.

Dodici minuti dopo, l'autore ha sostituito entrambe le azioni con dei link. "Trovo molto utile che, una volta adottata una guida, le recensioni future la menzionino come esempio di riferimento", ha affermato Nepomuceno.

Input di verifica le cui etichette si trovavano altrove

La capacità del bot di leggere più file è stata utile anche per un modulo in più passaggi. Un linter statico vede solo un campo di testo con testo segnaposto all'interno di ogni passaggio e non può sapere che l'intestazione e le istruzioni visibili si trovano in un componente di layout principale. Citando le guide sui moduli e sull'accessibilità, il bot ha rilevato che il segnaposto era l'unica etichetta del campo, che il titolo del passaggio e le istruzioni nel layout principale non erano associati all'input e che i messaggi di errore e"codice inviato di nuovo" non venivano annunciati agli screen reader. Quindici minuti dopo, tutti e tre i problemi erano stati risolti e il cablaggio di accessibilità è rimasto intatto quando una richiesta di pull successiva ha modificato lo stile dell'input del codice in sei caselle visive per le cifre.

Altre cose rilevate dal bot

Ecco altri cinque risultati della stessa campagna di cinque settimane:

• Un dettaglio CSS che l'ingegnere dietro al bot ha trascurato: la richiesta di pull di Nepomuceno per le schede home fisse ha nidificato le query CSS scroll-state senza assegnare un nome ai relativi container e ha attivato/disattivato un bordo in modo da spostare il layout a metà dello scorrimento. Il bot ha citato la guida alle intestazioni fisse sensibili allo stato e lui ha risolto entrambi i problemi. Ha trovato le recensioni utili per il posizionamento degli ancoraggi e le query sullo stato di scorrimento.
• Slippage limitato a metà digitazione: gli input di slippage personalizzati (la variazione di prezzo che un utente tollera su un'operazione) limitavano i valori superiori al 100% a ogni digitazione, trasformando 101 in 100 mentre l'utente stava ancora digitando. Seguendo la guida ai moduli, la correzione ha spostato la convalida nel momento in cui il campo perde lo stato attivo e ha aggiunto un banner di avviso visibile.
• Un indicatore di caricamento che gli screen reader non potevano utilizzare: uno scheletro di caricamento dell'elenco di token ha inserito l'etichetta "caricamento" su un elemento generico senza ruolo, il che è vietato da ARIA. Il bot ha indicato due componenti nel codebase che utilizzavano già il pattern solo per screen reader di MetaMask (entrambi aggiornati dopo una revisione di Modern Web Guidance sei giorni prima) e l'autore ha allineato lo scheletro con quel pattern otto minuti dopo.
• Azione asincrona non protetta: un pulsante asincrono "Visualizza sul provider" non aveva una protezione in corso, quindi un doppio clic poteva aprire schede duplicate e watcher in background. L'autore ha aggiunto una protezione meno di quattro minuti dopo il commento.
• Convalida della pressione dei tasti senza un modulo: una pagina di importazione di NFT veniva convalidata a ogni pressione di un tasto e non aveva un elemento <form> per la semantica di invio. Entrambi sono stati corretti 19 minuti dopo la revisione.

Ogni recensione è pubblica. I commenti completi del bot si trovano in ogni richiesta di pull collegata e puoi sfogliarli tutti su GitHub.

Cosa non ha risolto e quanto è rumoroso

Non tutti i risultati sono stati pubblicati. La tabella seguente mostra come MetaMask ha conteggiato i 102 risultati sulle richieste di pull di funzionalità e correzioni (altri 20 sono stati trovati su 7 richieste di pull di release e sincronizzazione, in cui non è previsto che una revisione modifichi il codice):

Suddivisi per tema in tutti i 122 risultati (compresi i 20 relativi alle richieste di pull di release e sincronizzazione):

Ecco alcuni pattern in questi numeri:

• Le correzioni che rimangono all'interno di un componente vengono applicate molto più spesso rispetto alle modifiche di accessibilità trasversali. Le correzioni dei moduli e dell'HTML rimangono all'interno del componente in fase di revisione, quindi gli autori di solito le applicano immediatamente (19 su 31 corrette). L'accessibilità ha avuto il maggior numero di risultati (38), ma solo 12 sono stati corretti, di solito perché la correzione non rientrava nell'ambito della richiesta di pull o richiedeva un componente del sistema di progettazione condiviso che non esisteva ancora.
• "Altro" è il caso in cui si discosta dalle indicazioni della piattaforma web. Sedici risultati riguardavano la coerenza del sistema di progettazione, i bug logici, il testo, la qualità dei test, la modalità Buio e l'igiene del codice; tre sono stati presi in considerazione, uno dei quali era una vera e propria regressione (una modifica all'elenco di rete che ha interrotto la precompilazione del modulo). La maggior parte di questi 16 problemi era facile da ignorare, ma l'individuazione di questa regressione ha reso utile una rapida occhiata.
• I falsi positivi erano dovuti al modo in cui l'agente applicava le guide e la maggior parte del rumore può essere risolta nella configurazione. Poiché il bot di revisione è un agente che legge un diff anziché un linter statico, i suoi falsi positivi derivavano da una lettura errata del codice circostante o dall'applicazione di una regola in modo più rigoroso rispetto alla guida collegata. I prossimi aggiustamenti ovvi sono saltare i branch di release e sincronizzazione e restringere il prompt in modo che l'agente si attenga alle regole indicate esplicitamente in una guida.

Nepomuceno descrive l'effetto più ampio sul team e sui tempi di revisione:

Anche David Murdoch, ingegnere di MetaMask, ha contribuito alla guida stessa: quando la guida al layout CSS presentava un errore in uno dei suoi esempi, ha segnalato un problema e il team di Modern Web Guidance ha unito una correzione due giorni dopo.

Cosa direbbe MetaMask a un team che sta valutando di utilizzarlo

• Leggi le indicazioni prima di scrivere qualsiasi cosa. Esegui npx modern-web-guidance@latest search "accordion find in page" per vedere quali guide recupererebbe un agente per un'attività. Puoi anche consultare l'insieme completo di guide di Modern Web Guidance.
• Inizia con il prompt di tre righe e l'agente che hai già eseguito. Installa la skill (npx modern-web-guidance@latest install o il comando del plug-in di un agente), indirizza tutto ciò che può essere eseguito sulle richieste di pull e chiedi di commentare solo quando c'è qualcosa di attuabile e di attenersi alle regole esplicitamente indicate in una guida. Mantenere il bot silenzioso quando non ci sono problemi è il motivo per cui gli ingegneri di MetaMask continuano a leggere i suoi commenti.
• Aspettati che alcuni risultati non vengano affrontati. Su 102 risultati relativi alle richieste di pull di funzionalità e correzioni, 43 sono stati corretti e 36 sono stati rifiutati o non sono stati risolti. Questo rapporto funziona bene per un bot di revisione consultiva, mentre sarebbe dannoso come controllo di blocco.
• Mantieni la revisione umana. Il bot è bravo con la semantica della piattaforma web, il CSS moderno e i pattern di interazione, ma non conosce il prodotto.

C'è anche ciò che MetaMask non ha ancora misurato: dopo cinque settimane, il team non ha monitorato il costo per richiesta di pull, il runtime, i confronti dei modelli o il comportamento del bot di revisione al di fuori di un codebase React.

Con tre righe di configurazione, MetaMask ha ottenuto un bot di revisione che cita una guida specifica per la maggior parte dei risultati (e un esempio esistente nel repository, se presente). I suggerimenti accettati vengono generalmente corretti entro un'ora.