Jedna CSS premenná, päť kôl revízie a Swift toolchain, ktorý klamal

„Sprav overlay priehľadným" je typ úlohy, ktorá znie ako posuvník a CSS vlastnosť opacity. GeekBye v2.0.7 dodal presne tento výsledok viditeľný pre používateľa — jediný nastaviteľný „svetlý režim", ktorý ti umožní vidieť cez panely asistenta na čokoľvek, čo je za nimi. Ale zaujímavá časť tohto vydania nie je tá funkcia. Je to päť kôl revízie, ktoré si vyžiadalo, aby to bolo správne, a vojnová historka o skompilovanej binárke, ktorá zmenila veľkosť, pretože naša vlastná dokumentácia klamala recenzentovi.

Správny spôsob, ako spraviť celé UI priehľadným

Naivná verzia tohto je posypať hodnotu nepriehľadnosti naprieč každým panelovým komponentom a považovať to za hotové. To je pasca na údržbu: tucet natvrdo zakódovaných hodnôt, ktoré sa rozídu v okamihu, keď sa niekto dotkne jednej z nich.

Namiesto toho v2.0.7 používa jednu zdieľanú CSS pomôcku a token pre jednotlivé povrchy. Existuje jediná trieda overlay-surface, ktorá vypočíta pozadie panelu z dvoch custom properties: základnej nepriehľadnosti, ktorú si každý povrch deklaruje sám za seba (ovládacia lišta, chat, bubliny prepisu, bloky kódu a tak ďalej si každý vyberá tú svoju), a globálneho násobiteľa alfa, ktorý sedí na koreni overlayu a reprezentuje nastavenie posuvníka používateľa. Každý povrch číta ten istý násobiteľ; každý si zachováva svoj vlastný charakter. Rozhodujúce je, že škáluje sa iba pozadie panelu — text, ikony a backdrop-blur zostávajú plne vykreslené, takže „priehľadný" nikdy neznamená „nečitateľný".

Dve rozhodnutia v tomto dizajne stoja za zmienku, pretože sú rozdielom medzi funkciou, ktorá pomáha, a takou, ktorá generuje tikety podpory:

• Predvolená hodnota je plne nepriehľadná. Nastavenie nepriehľadnosti sa dodáva na 100 % — bez efektu. Nikomu sa overlay pri aktualizácii zrazu nestal priehľadným; priehľadnosť je tam, keď po nej siahneš, a neviditeľná dovtedy.
• Nastavenie je validované defenzívne. Existuje jeden zdroj pravdy pre minimum, maximum, predvolenú hodnotu a krok, a normalizátor, ktorý stráži prázdny/chýbajúci prípad. To je dôležité kvôli jednej pasci v JavaScripte: Number(null) je 0, takže chýbajúce nastavenie naivne pretypované by uzamklo overlay do jeho najpriehľadnejšieho stavu namiesto predvoleného. Normalizátor to zachytí skôr, než sa to môže stať.

Potiahni posuvník a celý overlay sa prefarbí naživo, uprostred nahrávania, pretože každý povrch je prihlásený na odber toho istého nastavenia. Žiadny reštart, žiadne opätovné načítanie.

Čo odhalila revízia (a test na jednom monitore by nikdy neodhalil)

Tu prestala byť „jedna CSS premenná" jednoduchá. V revízii vyplávali tri chyby a dve z nich sú tá istá lekcia v inom klobúku.

Panel, ktorý nechcel zmiznúť. Overlay klávesových skratiek zostal tvrdohlavo plný, zatiaľ čo všetko ostatné sa stalo priehľadným. Príčina: vykresľuje sa mimo podstromu DOM, ktorý nesie premennú nepriehľadnosti, takže nikdy nezdedil hodnotu kaskádujúcu nadol z koreňa overlayu. CSS custom properties sa dedia cez strom DOM — a ak nejaký uzol nie je skutočne potomkom miesta, kde premennú nastavíš, ticho nedostane nič. Oprava spočívala v tom, že sa premenná nastavila lokálne aj na tomto paneli.

Hover odtieň, ktorý zmizol. Tlačidlá Fn/Assist stratili svoju azúrovú hover žiaru. Pomôcka priehľadnosti nastavovala pozadie cez !important (musí zvíťaziť nad predvolenými hodnotami povrchov) a to prevalcovalo hover: odtieň pozadia na tom istom elemente. Kolízia špecifickosti. Oprava spočívala v tom, že sa hover odtieň spravil rovnako dôrazným, aby mohol pri hoveri získať prevahu späť.

Oba tieto prípady sú tá istá základná pravda: kaskáda CSS premennej je skutočná hranica správnosti, nie detail štýlovania. Dedičnosť a špecifickosť rozhodujú o tom, či sa tvoja hodnota vôbec dostane k elementu, a ani jedno sa neukáže na snímke obrazovky, kým to nie je zle.

Rovnaká nepriehľadnosť, iný vzhľad. Ten najjemnejší: nahrávacia lišta a nečinná lišta boli nastavené na identickú základnú nepriehľadnosť a napriek tomu vyzerali viditeľne inak. Prečo? Nahrávacia pilulka používala silnejší backdrop-blur a silné rozmazanie nad tmavým pozadím sa priemeruje smerom k tmavšiemu výsledku — takže rovnaká alfa vyprodukovala nerovnaký vzhľad. Mala tiež slabé orámovanie tam, kde nečinná lišta mala jasnú hranu s gradientovým prstencom. Oprava zladila úroveň rozmazania a prstenec. Lekcia sa vryla: rovnaká alfa nie je rovnaký vzhľad, hneď ako do hry vstúpi rozmazanie. Priehľadnosť je systém interagujúcich efektov, nie jediné číslo.

Binárka, ktorá zmenila veľkosť, pretože dokumentácia klamala

Teraz tá vojnová historka a je to môj obľúbený druh — ten, kde sa nástroje a dokumentácia nezhodujú a dôkladný recenzent sa dostane do krížovej paľby.

GeekBye dodáva niekoľko predkompilovaných Swift binárok (natívne pomocníky pre veci ako detekcia stretnutí). Pretože skompilovaná binárka je commitnutá do repozitára, každý vývojár ju musí skompilovať s presne rovnakou verziou Swift — rôzne toolchainy produkujú z identického zdroja rôzne bajty, a to by znamenalo fantómový git konflikt zakaždým, keď niekto prebuduje. Preto existuje skript, ktorý vynucuje jednu konkrétnu verziu: Swift 6.3.x, kontrolovanú pri zostavovaní.

Počas revízie tohto vydania recenzent upozornil, že by sa binárka mala prebudovať tak, aby zodpovedala „toolchainu nariadenému repozitárom". Vývojár spravil presne to — a veľkosť binárky sa zmenila z 89,184 bajtov na 88,512. Správa commitu dokonca hovorila, že „obnovuje bajtovo stabilný výstup" prebudovaním so Swift 6.2.1, „toolchainom nariadeným repozitárom".

Až na to, že 6.2.1 bola nesprávna verzia. Skript vynucovania zostavenia vyžadoval 6.3.x. Problém bol, že prozaická dokumentácia — README a príručka pre prispievateľov — na pár miestach stále uvádzala 6.2.1. Takže svedomitý recenzent a svedomitý vývojár, obaja snažiaci sa spraviť správnu vec, nasledovali dokumentáciu rovno k commitnutiu presne toho artefaktu, ktorý skript vynucovania existuje na to, aby odmietol. Binárka 6.2.1 v repozitári 6.3.x je presne ten posun, ktorý by pokazil čistý prebuild každému inému vývojárovi.

Nasledujúci commit to opravil — a tá oprava je pointa. Nielenže prebudoval binárku späť do jej podoby 6.3.x (veľkosť obnovená na 89,184, presne tam, kde začala). Zároveň napravil zastarané odkazy na „6.2.1" v dokumentácii, aby sa pasca nedala spustiť znova. Binárka sa hompáľala o 672 bajtov a späť naprieč dvomi commitmi a tá skutočná chyba nikdy nebola binárka. Bolo to tým, že dva zdroje pravdy — skript vynucovania a písaná dokumentácia — sa nezhodovali a človek dôveroval tomu nesprávnemu.

Tri veci, ktoré ma toto vydanie naučilo

1. Kaskáda CSS premennej je hranica správnosti. Dve z troch chýb z revízie sa scvrkli na premennú, ktorá sa nededila, a !important, ktorý prevalcoval hover stav. Ak sa hodnota musí dostať k elementu cez dedičnosť alebo zvíťaziť cez špecifickosť, tá cesta je logika — over ju ako logiku, nie ako štýlovanie.
2. Rovnaké parametre môžu vyprodukovať nerovnaké výsledky. Nahrávacia lišta a nečinná lišta zdieľali nepriehľadnosť a napriek tomu vyzerali inak, pretože iné rozmazanie zmenilo výsledok. Keď zjednotíš vizuálny systém na jednom čísle, skontroluj, či ostatné premenné okolo každého povrchu ticho nemenia to, čo to číslo znamená.
3. Keď sa dokumentácia a vynucovanie nezhodujú, oprav ten nesúlad — nielen symptóm. Chyba nebola zlá binárka; bola to dokumentácia, ktorá uvádzala nesprávny toolchain, a skript vynucovania, ktorý tvrdil opak. Prebudovanie binárky lieči symptóm. Zladenie každého zdroja pravdy je skutočná oprava, pretože ďalší recenzent bude tiež dôverovať dokumentácii.

GeekBye v2.0.7 dodal jednotnú priehľadnosť, so všetkými hraničnými prípadmi zrevidovanými a dokumentáciou toolchainu uvedenou na pravú mieru. Je to posledné z vydaní „tichého remesla" pred sprintom spoľahlivosti, ktorý nasledoval. Pre základ pod tým si pozri čo si vydanie druhej verzie naozaj vyžaduje (v2.0.0); pre súrodenecké vydanie leštenia pokojný softvér: oprava blikania a čip režimu odpovede (v2.0.3 + v2.0.5); a pre to, ako overlay zostáva skrytý počas hovoru, ako zostať neviditeľný počas zdieľania obrazovky.