Én CSS-variabel, fem runder med kodegjennomgang, og en Swift-verktøykjede som løy

"Gjør overlegget gjennomskinnelig" er den typen oppgave som høres ut som en glidebryter og en CSS-egenskap opacity. GeekBye v2.0.7 leverte akkurat det utfallet for brukeren — én enkelt justerbar "lys modus" som lar deg se gjennom assistentens paneler til det som ligger bak dem. Men det interessante med denne utgivelsen er ikke funksjonen. Det er de fem rundene med gjennomgang det tok å få den riktig, og en krigshistorie om en kompilert binærfil som endret størrelse fordi vår egen dokumentasjon løy til en anmelder.

Den riktige måten å gjøre et helt grensesnitt gjennomskinnelig

Den naive versjonen av dette er å strø en gjennomsiktighetsverdi utover hver eneste panelkomponent og kalle det ferdig. Det er en vedlikeholdsfelle: et dusin hardkodede verdier som driver fra hverandre i det øyeblikket noen rører én av dem.

I stedet bruker v2.0.7 ett delt CSS-hjelpeverktøy og en token per flate. Det finnes én enkelt klasse overlay-surface som beregner et panels bakgrunn ut fra to egendefinerte egenskaper: en grunnleggende gjennomsiktighet som hver flate selv erklærer (kontrollinjen, chatten, transkripsjonsboblene, kodeblokkene og så videre velger hver sin egen), og en global alfamultiplikator som ligger på overleggsroten og representerer brukerens innstilling på glidebryteren. Hver flate leser den samme multiplikatoren; hver beholder sin egen karakter. Avgjørende er det at kun panelbakgrunnen skaleres — tekst, ikoner og backdrop-blur forblir fullt gjengitt, så "gjennomskinnelig" betyr aldri "uleselig".

To beslutninger i den designen er verdt å trekke frem, fordi de er forskjellen mellom en funksjon som hjelper og en som genererer supporthenvendelser:

• Standarden er helt ugjennomsiktig. Gjennomsiktighetsinnstillingen leveres på 100 % — en ikke-operasjon. Ingens overlegg ble plutselig gjennomsiktig ved oppdatering; gjennomsiktigheten er der når du strekker deg etter den, og usynlig inntil da.
• Innstillingen valideres defensivt. Det finnes én sannhetskilde for minimum, maksimum, standard og steg, og en normalisator som vokter tilfellet der verdien er tom eller mangler. Det betyr noe på grunn av en JavaScript-felle: Number(null) er 0, så en manglende innstilling som naivt tvinges til et tall ville snappet overlegget til sin mest gjennomsiktige tilstand i stedet for standarden. Normalisatoren fanger det før det kan skje.

Dra i glidebryteren, og hele overlegget tones om i sanntid, midt i et opptak, fordi hver flate abonnerer på den samme innstillingen. Ingen omstart, ingen ny innlasting.

Hva gjennomgangen fanget (og en test på én skjerm aldri ville)

Her sluttet "én CSS-variabel" å være enkel. Tre feil dukket opp i gjennomgangen, og to av dem er den samme lærdommen med ulike hatter på.

Et panel som ikke ville tone ut. Overlegget for tastatursnarveier forble sta og massivt mens alt annet ble gjennomskinnelig. Årsaken: det gjengis utenfor DOM-deltreet som bærer gjennomsiktighetsvariabelen, så det arvet aldri verdien som kaskaderer nedover fra overleggsroten. CSS' egendefinerte egenskaper arves gjennom DOM-treet — og hvis en node faktisk ikke er en etterkommer av der du setter variabelen, får den stille ingenting. Løsningen var å sette variabelen lokalt på det panelet også.

En hover-tone som forsvant. Fn/Assist-knappene mistet sitt cyanfargede hover-glød. Gjennomsiktighetshjelpeverktøyet satte bakgrunnen med !important (det må vinne over flatenes standardverdier), og det valset over hover:-bakgrunnstonen på samme element. Spesifisitetskollisjon. Løsningen var å gjøre hover-tonen like ettertrykkelig, slik at den kunne vinne tilbake ved hover.

Begge disse er den samme underliggende sannheten: en CSS-variabelkaskade er en reell korrekthetsgrense, ikke en stildetalj. Arv og spesifisitet avgjør om verdien din i det hele tatt når frem til elementet, og ingen av delene viser seg i et skjermbilde før det er feil.

Samme gjennomsiktighet, ulikt utseende. Den mest subtile: opptakslinjen og hvilelinjen ble satt til identisk grunnleggende gjennomsiktighet, og så likevel synlig forskjellige ut. Hvorfor? Opptakspillen brukte en kraftigere backdrop-blur, og en sterk blur over en mørk bakgrunn snitter mot et mørkere resultat — så lik alfaverdi ga ulikt utseende. Den hadde også en svak kantlinje der hvilelinjen hadde en lys gradientring-kant. Løsningen matchet blur-nivået og ringen. Lærdommen satt: lik alfaverdi er ikke lik utseende når blur kommer inn i bildet. Gjennomsiktighet er et system av effekter som spiller sammen, ikke ett enkelt tall.

Binærfilen som endret størrelse fordi dokumentasjonen løy

Nå til krigshistorien, og det er min favorittsort — den der verktøyet og dokumentasjonen er uenige, og en samvittighetsfull anmelder havner i kryssilden.

GeekBye leverer noen ferdigkompilerte Swift-binærfiler (native hjelpere for ting som møtedeteksjon). Fordi en kompilert binærfil er sjekket inn i repoet, må hver utvikler kompilere den med nøyaktig samme Swift-versjon — ulike verktøykjeder produserer ulike byte fra identisk kildekode, og det ville betydd en spøkelses-git-konflikt hver gang noen bygger på nytt. Så det finnes et skript som håndhever én bestemt versjon: Swift 6.3.x, sjekket ved byggetidspunkt.

Under gjennomgangen av denne utgivelsen flagget en anmelder at en binærfil burde bygges på nytt for å samsvare med "verktøykjeden repoet krever". Utvikleren gjorde nettopp det — og binærfilens størrelse endret seg fra 89,184 byte til 88,512. Commit-meldingen sa til og med at den "gjenopprettet byte-stabil utdata" ved å bygge på nytt med Swift 6.2.1, "verktøykjeden repoet krever".

Bortsett fra at 6.2.1 var feil versjon. Bygg-håndhevingsskriptet krevde 6.3.x. Problemet var at prosa-dokumentasjonen — README-filen og bidragsyterveiledningen — fortsatt sa 6.2.1 et par steder. Så en pliktoppfyllende anmelder og en pliktoppfyllende utvikler, begge i forsøk på å gjøre det rette, fulgte dokumentasjonen rett inn i å committe nettopp det artefaktet håndhevingsskriptet eksisterer for å avvise. En 6.2.1-binærfil i et 6.3.x-repo er nøyaktig den driften som ville brutt hver annen utviklers rene ombygging.

Den neste commiten rettet det — og rettelsen er poenget. Den bygde ikke bare binærfilen tilbake til sin 6.3.x-form (størrelse gjenopprettet til 89,184, akkurat der den startet). Den korrigerte også de utdaterte "6.2.1"-referansene i dokumentasjonen slik at fellen ikke kunne utløses igjen. Binærfilen vaklet 672 byte og tilbake over to commits, og den egentlige feilen var aldri binærfilen. Det var at to sannhetskilder — håndhevingsskriptet og den skriftlige dokumentasjonen — var uenige, og et menneske stolte på den gale.

Tre ting denne utgivelsen lærte oss

1. En CSS-variabelkaskade er en korrekthetsgrense. To av tre feil fra gjennomgangen kokte ned til en variabel som ikke ble arvet og et !important som overkjørte en hover-tilstand. Hvis en verdi må nå et element gjennom arv eller vinne gjennom spesifisitet, er den veien logikk — verifiser den som logikk, ikke som styling.
2. Like parametere kan gi ulike resultater. Opptakslinjen og hvilelinjen delte en gjennomsiktighet og så likevel forskjellige ut fordi en annen blur endret utfallet. Når du forener et visuelt system på ett tall, sjekk at de andre variablene rundt hver flate ikke stille endrer hva det tallet betyr.
3. Når dokumentasjon og håndheving er uenige, fiks uenigheten — ikke bare symptomet. Feilen var ikke en dårlig binærfil; det var en dokumentasjon som navnga feil verktøykjede og et håndhevingsskript som sa noe annet. Å bygge binærfilen på nytt behandler symptomet. Å få hver sannhetskilde til å stemme overens er den faktiske løsningen, for den neste anmelderen vil også stole på dokumentasjonen.

GeekBye v2.0.7 leverte den ensartede gjennomsiktigheten, med alle grensetilfeller gjennomgått og verktøykjede-dokumentasjonen rettet opp. Det er den siste av "stille håndverk"-utgivelsene før pålitelighetssprinten som fulgte. For fundamentet under den, se hva en versjon 2 faktisk krever (v2.0.0); for søsken-poleringsutgivelsen, rolig programvare: flimmerfiksen og svarmodus-brikken (v2.0.3 + v2.0.5); og for hvordan overlegget holder seg skjult under en samtale, hvordan forbli usynlig under skjermdeling.