<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Brandon S. on Medium]]></title>
        <description><![CDATA[Stories by Brandon S. on Medium]]></description>
        <link>https://medium.com/@brandonscript?source=rss-16b233cf1ec5------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*lFWeP74DXhSXDf6Qpph2bQ@2x.jpeg</url>
            <title>Stories by Brandon S. on Medium</title>
            <link>https://medium.com/@brandonscript?source=rss-16b233cf1ec5------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 06:15:26 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@brandonscript/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[The space between things]]></title>
            <link>https://brandonscript.design/the-space-between-things-834ff5796405?source=rss-16b233cf1ec5------2</link>
            <guid isPermaLink="false">https://medium.com/p/834ff5796405</guid>
            <category><![CDATA[dopamine]]></category>
            <category><![CDATA[design]]></category>
            <category><![CDATA[negative-space]]></category>
            <category><![CDATA[neuroscience]]></category>
            <category><![CDATA[music]]></category>
            <dc:creator><![CDATA[Brandon S.]]></dc:creator>
            <pubDate>Sat, 30 May 2026 04:46:46 GMT</pubDate>
            <atom:updated>2026-05-30T20:12:09.823Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*K4jUnSYRbufcrkx8CQQRRQ.png" /></figure><h4>Some of the most emotionally powerful experiences in design emerge not from what is added, but from what is intentionally withheld.</h4><p>It’s creativity by omission.</p><p>Part of this is deeply rooted in how human perception works. We do not experience objects in isolation; we experience them relative to contrast, context, spacing, and expectation. A black cat in a dark room is nearly invisible, but place him on a white chaise lounge beside a bright window and the brain immediately recognizes the cat. Even if you’re not consciously aware of it, the surrounding space becomes part of the perception itself.</p><p>This principle sits at the core of Gestalt psychology, which describes how human brains are constantly trying to simplify and organize visual information into patterns and relationships in order to make sense of what we see. Research in visual perception, cognitive science, and neuroarchitecture suggests that visually coherent environments reduce cognitive strain by making those patterns easier to organize and predict.</p><p>Negative space — one of the most powerful tools in minimalist design — supports this process by creating definition between elements and reducing visual noise. Consider these incredible examples fom the design world:</p><figure><img alt="A collection of negative space artworks demonstrating how the deliberate use of empty space can create hidden images, visual ambiguity, and deeper meaning by inviting the viewer to complete the picture themselves." src="https://cdn-images-1.medium.com/max/1024/1*OUhvSzZdEeb3FaXS7bFuAg.png" /></figure><p>Instead of forcing the brain to continuously parse competing signals, the negative space creates structure through absence, which may explain why minimalist composition and sparse environments often feel calm, elegant, and emotionally intentional—not merely because they contain fewer objects, but because the brain can parse them more efficiently and predict their structure more easily.</p><p>A sparse layout gives objects and relationships room to breathe, encouraging the viewer to mentally fill in the gaps.</p><p>But negative space does more than just reduce visual stress — it can also <em>create</em> tension.</p><h4>Music works this way too.</h4><p>Music creates emotional tension not only through melody and harmony, but through omission, silence, delayed emphasis, and unresolved expectation.</p><p>A pause before a chorus lands. A beat that never arrives where you expected it to. A chord that feels emotionally unfinished for just a moment too long.</p><p>A <em>rest</em> is the most obvious form of musical negative space. The silence itself becomes part of the rhythm and structure, giving the surrounding notes more weight and definition. If you’re not musically inclined, rests look like these:</p><figure><img alt="Several musical rests on a staff" src="https://cdn-images-1.medium.com/max/1024/1*Uxy19hYNZgAkZZpjKKv-Rw.png" /></figure><p>While rests are among the simplest concepts in music theory, they are foundational to music itself. They shape emotion through absence. If you’re familiar with the <em>Jaws</em> theme—or motif—the legendary two-note E to F <em>“bah-dum”, “bah-dum”</em>, imagine this without any negative space: it would just be the two notes repeating endlessly, with no buildup, tension, or release. The space between those notes is what makes the listener emotionally invested.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FkHwyIUMnrw0%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DkHwyIUMnrw0&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FkHwyIUMnrw0%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/588abe1927da38f6fb4733f9522625f7/href">https://medium.com/media/588abe1927da38f6fb4733f9522625f7/href</a></iframe><p>The rests in the <em>Jaws</em> motif are straightforward: the silence occurs pretty much exactly where you expect it to. Try it with me out loud (or <em>sotto voce</em>)…</p><p><em>“Bah-dum {rest} {rest}”</em> ···· <em>“Bah-dum {rest} {rest}” </em>···· <em>“Bah-dum, bah-dum” </em>····</p><p>The pulse (the beat) is steady and predictable. You can count and tap along to it (<em>1, 2, 3, 4</em>). Even when there aren’t notes for some of the beats, it’s easy for your brain to follow and fill in those gaps.</p><p>There is still some satisfaction in that consistency and predictability, but because it’s overtly giving your brain exactly what it expected, it’s about as emotionally satisfying as successfully walking in a straight line. Syncopation works differently. Where the silence in the <em>Jaws</em> motif is careful to not obfuscate the beat, syncopation disrupts that stability by withholding emphasis where you subconsciously expect it to land.</p><p>A simple way to feel this is to tap steadily on every beat in an easy ⁴⁄₄ time:</p><p>“<em>One, two, three, four | one, two, three, four | one, two, three, four”</em></p><p>Now try tapping only on the second and fourth (omitting the dominant one and three):</p><p><em>“ {rest}, two, {rest}, four | {rest}, two, {rest}, four | {rest}, two, {rest}, four”</em></p><p>It’s a small change—and we’re not <em>adding</em> anything at all, we’re <em>taking away</em>—yet the rhythm feels more alive and energetic than it did before. Notice that the beat itself never actually disappears? Your brain continued following it internally even when the rhythm stopped marking it directly; and in successfully predicting that missing pulse, the brain derives a sense of satisfaction and reward.</p><p>This becomes even more emotionally engaging when you withhold emphasis in less predictable ways. Try it again, but this time with twice the number of taps in the same ⁴⁄₄ time. First, practice this steady rhythm using the “ands” (&amp;) between each beat:</p><p><em>“One &amp; two &amp; three &amp; four &amp; | one &amp; two &amp; three &amp; four &amp;”</em></p><p>Now keep the pulse steady, but only tap on the “one” and the “&amp;”s, letting the remaining number be silent:</p><p><em>“One &amp; ___ &amp; ___ &amp; ___ &amp; | one &amp; ___ &amp; ___ &amp; ___ &amp;”</em></p><p>The rhythm now feels far less stable, even though the underlying pulse never actually changed. Your brain is still tracking the missing beats internally, trying to predict where the rhythm should reconnect with the pulse — but now there’s uncertainty. The pulse has become ambiguous—implied rather than explicit—and your brain becomes an active participant in reconstructing it, just like it does with negative space in visual design.</p><p>A great demonstration of syncopation is Stevie Wonder’s <em>Superstition</em>. It starts out with an easy-to-follow 1, 2, 3, 4 beat by the drummer, then layers on new levels of syncopated instrumental parts and, eventually, vocals.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FRNLDnSr7ThI%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DRNLDnSr7ThI&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FRNLDnSr7ThI%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="640" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/4e032c9e809bd3e393ea6765ba390431/href">https://medium.com/media/4e032c9e809bd3e393ea6765ba390431/href</a></iframe><p>Rhythm is not the only way music can create tension through omission.</p><h4>It can exist in musical harmony as well</h4><p><em>What notes</em> you play are just as important as <em>when</em> you play them.</p><p>A suspension occurs when a note from one chord lingers briefly into the next. For a moment, you’re no longer sure if it belongs. You can <em>feel</em> that something wants to resolve, even if you can’t consciously explain why. The note isn’t wrong. It’s simply arriving at its destination later than your brain expected.</p><p>Where suspensions cling to the past, anticipations reach into the future. A note from the destination chord arrives early, hinting at where the harmony is about to go before the rest of the progression catches up.</p><p>Music is brilliantly mathematical, and chords often share notes with one another. As the harmony changes, a note can linger between those chords without sounding completely out of place.</p><p>In fact, suspended and anticipated notes often belong to both chords. Some of the most satisfying suspensions occur when the movement between chords is as small as possible, often with common notes held over while the harmony shifts beneath it. The effect is remarkably delicate, creating just enough tension for the brain to notice before it finally resolves.</p><blockquote>If you don’t read music, don’t worry. But to make things easier from here on out, it’ll be helpful that you know that each line and space on the music staff represents a different note. Here’s a simple C major scale to get you started:</blockquote><figure><img alt="An ascending C-major scale on a musical staff" src="https://cdn-images-1.medium.com/max/1024/1*CYrbSYW8vqOJRp3h3QOzFQ.png" /></figure><p>One of my favorite examples of harmony comes from <em>Somewhere Over the Rainbow</em>. Much of what takes you on such an emotional journey is the way its notes move between chords. Rather than leaping around dramatically, most move only slightly—elegantly and delicately—as the harmony shifts beneath them.</p><p>Some notes are held to create brief moments of suspension, while entire chords linger with only a note or two changed, <em>anticipating</em> the next harmony. Nothing is wrong. Nothing is missing. The music is simply inviting your brain to participate in the journey. Your brain can hear the unresolved tension and the implied destination, and the eventual resolution becomes part of the reward.</p><p>Here’s a simplified view of <em>Somewhere Over the Rainbow’s</em> chord progression underneath the melody:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/737/1*_U1V-KvkTQ_jjTbcW6BIig@2x.png" /></figure><p>If you connect the notes with lines, the progression almost looks like waves on the ocean:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ubkpB3_uhOSLK5OawrPE4Q.png" /></figure><p>Notice how little most of the notes actually move? Many stay exactly where they are, while others shift by only a single step. The harmony changes, and the chord roots change significantly, but the movement is remarkably restrained. Much like negative space in design, the emotional effect comes not from dramatic complexity, but from subtle relationships and carefully controlled tension.</p><p>As you listen, pay attention not only to what’s there, but also to what isn’t. Notice the space between expectation and resolution, where your mind fills in the gaps. Pay attention to your breath, the beat of your heart, and the subtle ebb and flow of the music and your attention — like waves on the ocean.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FV1bFr2SWP1I%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DV1bFr2SWP1I&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FV1bFr2SWP1I%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="640" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/23f47fba8edfc4f4486bda7ca5a36e1f/href">https://medium.com/media/23f47fba8edfc4f4486bda7ca5a36e1f/href</a></iframe><h4>The shape of attention and the emotional gravity of restraint</h4><p>Once you start noticing this pattern in music, it becomes even more difficult to unsee it in design — or ignore the discomfort of design that leaves no room for absence.</p><p>A sparse layout is not identical to a rest, a suspension, or a syncopated rhythm, but it creates a profoundly similar kind of perceptual experience. In each case, something expected is withheld, and that anticipation itself becomes part of the reward.</p><p>In design, this might be the space around a headline, the distance between two objects, an asymmetrical composition, or using negative space to infer shape and substance. The absence is not passive. It creates hierarchy, pacing, and expectation, and it allows your brain to breathe and absorb information without becoming overwhelmed.</p><p>Just as music alternates between sound and silence, good design alternates between information and space. The pauses matter as much as the notes. Without them, you never have a chance to focus because everything is competing for your attention.</p><p>But if there were no value in nothingness beyond calm, it wouldn’t explain why it can also make things more compelling…</p><h4>The reward of prediction</h4><p>Just as music can use harmony and rhythm to evoke a sense of zen, it can also create tension and excitement. We heard it in Superstition, where the rhythm felt alive precisely because it refused to land where we expected.</p><p>Storytelling works much the same way.</p><p>No one wants to read a mystery novel where the ending is obvious from the beginning. The fun is in the clues, the uncertainty, the wrong turns, and the slow realization that the answer was there all along.</p><p>A whodunnit, a syncopated rhythm, and a minimalist composition all exploit the same instinct: the brain’s drive to predict incomplete patterns before they resolve. Foreshadowing, suspense, harmonic tension, and negative space all work because the brain is not merely reacting to information, but actively trying to imagine what comes next — and that’s honestly fun as hell, according to your <em>nucleus accumbens</em>.</p><h4>The space between things</h4><p>Negative space isn’t just a visual principle; it’s part of a broader cognitive phenomenon shaping how humans subconsciously experience uncertainty and resolution.</p><p>Across design, music, storytelling, architecture, and even conversation, some of the most emotionally powerful moments emerge not from what is revealed, but from what is intentionally withheld. Long before it was appreciating arrows in FedEx logos, Billie Jean, or Agatha Christie, it evolved to anticipate patterns, recognize danger, and imagine possible futures. It still does. Every day, in every conversation, song, and composition, it searches for meaning in the spaces between things.</p><p>Neuroscientists increasingly describe the brain not as a passive receiver of information, but as a prediction engine. It continuously generates expectations about the world around it, compares those expectations against reality, and updates its understanding accordingly. Many researchers believe this process is closely tied to the brain’s reward systems, including those involving dopamine, which appears to play an important role in anticipation, motivation, learning, and the satisfaction of successful prediction.</p><p>Perhaps this helps explain why a syncopated rhythm can feel more alive than a predictable one, why a suspension can make a resolution feel beautiful, why a mystery is often more enjoyable than its ending, and why negative space in design creates such a disproportionately powerful reaction: the tension—the journey—between what the brain predicts and what eventually arrives is itself part of the reward.</p><p>What appears to be empty space is rarely empty at all.</p><p>The best experiences aren’t the ones that give us all the answers. They’re the ones that invite us to discover them.</p><p><em>fin<br></em> — B</p><blockquote><em>read more long-form at </em><a href="https://brandonscript.design/"><em>brandonscript.design</em></a><em><br>or follow me on</em></blockquote><blockquote><em>🐘 </em><a href="https://appdot.net/"><em>Mastodon</em></a><em><br>💼 </em><a href="https://linkedin.com/in/brandonscript"><em>LinkedIn</em></a><em><br>🐙 </em><a href="https://github.com/brandonscript"><em>GitHub</em></a></blockquote><h4>References:</h4><ul><li><em>Sweet Anticipation: Music and the Psychology of Expectation<br></em><a href="https://www.researchgate.net/publication/209436188_Sweet_Anticipation_Music_and_the_Psychology_of_Expectation">https://www.researchgate.net/publication/209436188_Sweet_Anticipation_Music_and_the_Psychology_of_Expectation</a></li><li><em>Predictions and the brain: how musical sounds become rewarding</em><br><a href="https://www.sciencedirect.com/science/article/pii/S1364661314002538">https://www.sciencedirect.com/science/article/pii/S1364661314002538</a></li><li><em>How music resonates in the brain</em><br> <a href="https://magazine.hms.harvard.edu/articles/how-music-resonates-brain">https://magazine.hms.harvard.edu/articles/how-music-resonates-brain</a></li><li><em>Building the anticipation: variation in tension and release in electronic music<br></em><a href="https://online.ucpress.edu/mp/article/42/3/256/204039/Building-the-AnticipationHow-Variation-in-Tension">https://online.ucpress.edu/mp/article/42/3/256/204039/Building-the-AnticipationHow-Variation-in-Tension</a></li><li><em>The affect of dopamine release on saliency and attention</em><br><a href="https://pmc.ncbi.nlm.nih.gov/articles/PMC9084920/"> </a><a href="https://pmc.ncbi.nlm.nih.gov/articles/PMC9084920/">https://pmc.ncbi.nlm.nih.gov/articles/PMC9084920/</a></li><li><em>Neuroarchitecture / emotional response to space</em><br><a href="https://www.mdpi.com/2079-7737/13/4/220">https://www.mdpi.com/2079-7737/13/4/220</a></li><li><em>Negative space in visual communication/design</em><br><a href="https://ijcrt.org/papers/IJCRT2508672.pdf">https://ijcrt.org/papers/IJCRT2508672.pdf</a></li><li>Gestalt psychology overview<br><a href="https://www.interaction-design.org/literature/topics/gestalt-principles">https://www.interaction-design.org/literature/topics/gestalt-principles</a></li><li>Cognitive load theory overview<br><a href="https://www.nngroup.com/articles/cognitive-load/">https://www.nngroup.com/articles/cognitive-load/</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=834ff5796405" width="1" height="1" alt=""><hr><p><a href="https://brandonscript.design/the-space-between-things-834ff5796405">The space between things</a> was originally published in <a href="https://brandonscript.design/">UX &amp; Code | opinions &amp; scribbles</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Are we creating artifacts for clarity, or just better-looking uncertainty?]]></title>
            <link>https://brandonscript.design/are-we-creating-artifacts-for-clarity-or-just-better-looking-uncertainty-78bc924891fa?source=rss-16b233cf1ec5------2</link>
            <guid isPermaLink="false">https://medium.com/p/78bc924891fa</guid>
            <category><![CDATA[product-management]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[product-design]]></category>
            <category><![CDATA[startup]]></category>
            <dc:creator><![CDATA[Brandon S.]]></dc:creator>
            <pubDate>Thu, 14 May 2026 12:46:00 GMT</pubDate>
            <atom:updated>2026-05-14T15:10:05.834Z</atom:updated>
            <content:encoded><![CDATA[<h4>As AI helps us communicate ideas faster, it can also help us mistake momentum for understanding.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XnXrg7yNIZbdqbkpd35KlQ.png" /></figure><p>A stakeholder asks to see “something more concrete.” Because the idea still feels slippery. The team’s been discussing it for a few weeks, but there are some unresolved product decisions, unanswered questions, and a creeping suspicion that everyone in the room is imagining something slightly different.</p><p>Everyone is trying to reduce uncertainty the best way they know how, within the bounds of their role, expertise, and corporate traditions.</p><p>So the team does what software teams usually do. Product writes a document. Everyone reads it (right? 🙃). Design turns the conversation into artifacts. It’s a comfortable process, everyone’s used to it. Eventually, someone hands Engineering something concrete enough to build from.</p><p>Often, that artifact is high fidelity—like a Figma mockup or prototype. <em>Sometimes</em>, that artifact is even exactly what was needed.</p><h4>Artifacts don’t just inform decisions—they influence them.</h4><p>They clarify some things while obscuring others. They focus attention in one direction while quietly pulling it away from another. They encourage certain conversations, assumptions, and decisions simply by how they frame the problem. What did the artifact clarify? What did it obscure? What assumptions did people walk away treating as facts?</p><ul><li>A requirements doc can force people to think deeper and turn vague intent into defined work. But they have to be read and understood (and someone always phones it in, right?). And they can easily disguise confident assumptions as facts or decisions.</li><li>A whiteboard can be perfect when you want to explore and ideate. You can also end up with illegible chicken scratch that leaves five people with six different interpretations.</li><li>Pencil sketches and low-fidelity wireframes are quick to make and easy to throw away. But when people can’t mentally fill in the gaps, they often mistake low-<em>fidelity</em> for low <em>quality</em>.</li><li>A Slack thread and a conversation can be good. Except when clarity and decisions are lost and forgotten about in the hubbub.</li><li>A strategy deck with an inspiring elevator pitch can sound polished and coherent. But it doesn’t clarify the actual problem, why it matters, what’s at stake, or how difficult it will be to build.</li><li>A roadmap can make a plan feel certain long before the underlying decisions deserve that confidence. Especially when they reflect shareholder promises instead of reality.</li><li>A Figma prototype can make a solution feel concrete enough to build. It can also make concepts look like decisions and spark debates before the team has agreed on the actual problem.</li></ul><p>Artifacts are powerful because they shape understanding. They are dangerous for exactly the same reason.</p><p>It comes down to whether it <em>reduces uncertainty</em>. Does it help people understand the problem? The scope? The tradeoffs? The stakes? When an artifact fails at that, the downstream cost is high: ambiguity, rework, premature commitment, and nitpicky debates driven by false confidence.</p><p>And then the <em>process</em> tends to feed itself. Product tightens the requirements while Design turns the conversation into screens, then Product clarifies something that changes the flow, so Design updates the screens, then Engineering asks whether one of the interactions is actually required, so Product revisits the original goal, so Design tweaks the prototype again, then someone asks whether the whole thing can be “a little more concrete,” and a few days later everyone is reviewing a polished artifact that works great as long as you stay on the intended path.</p><p>*breathes*</p><p>Not to say that refinement and iteration are avoidable—they aren’t, and they shouldn’t be. But the secret is not spending maximum effort. It’s getting the maximum understanding for the effort you spend.</p><figure><img alt="Hand-drawn chart showing effort increasing from left to right and understanding rising, peaking, then declining. A highlighted sweet spot shows where moderate effort creates the most understanding, while too little effort leaves things vague and too much effort creates diminishing returns, complexity, over-explaining, and decision paralysis." src="https://cdn-images-1.medium.com/max/1024/1*dwk3e2BYsYD1q7S_Mzbc0g.png" /></figure><h4>High-fidelity prototypes create a very specific kind of failure mode.</h4><p>They create the comforting illusion that something is becoming real. They sit in an uncanny valley between concept and reality: polished enough to feel real, but incomplete enough that the moment you step outside the happy path, the illusion starts to wobble.</p><p>This can be incredibly distracting if you’re not a professional telepath who can read the minds of your designers. (We’ve all been there when that one person starts nitpicking spacing, copy, fonts, colors, <em>that border radius</em>, or whether an animation feels off).</p><p>And now the conversation is no longer about the uncertainty the prototype was supposed to clarify.</p><p>The artifact has <em>become the discussion</em>.</p><figure><img alt="The “Boardroom Meeting Suggestion” meme, where some sensible questions are being asked, but the one guy asks if the button can be blue and gets thrown out the window for it." src="https://cdn-images-1.medium.com/max/1024/1*hVgZxiPrcabqTbRVKQYvcw.png" /></figure><p>This is why choosing the right artifact for the uncertainty in front of you is such an important part of building software well. And the longer I do this, the more I appreciate how difficult that is.</p><p>Which is probably why AI tools feel so compelling right now. Because they make hard things easier. Right?</p><h4>As much as it is a boon, AI dramatically lowers the cost of creating better-looking uncertainty.</h4><p>For most of the history of software development, there has been a meaningful gap between having an idea and being able to express it clearly enough for other people to react to.</p><p>That gap shaped almost everything about how modern product teams evolved. Most folks specialize. Product managers, designers, and engineers each reduce uncertainty from different perspectives, using different tools and kinds of expertise. Artifacts became the translation layer between those perspectives, turning an idea from one person’s head into something other people could inspect, challenge, improve, reject, or build.</p><p>This is still a very necessary thing. But AI is dramatically changing the economics of that translation work. Some tasks become faster. Some become cheaper. Some simply shift where the time and cost live. Some of us are vibe-coding and “token maxxing” (🤮), while others are curmudgeoning (old-man-yells-at-cloud.gif). And in the process, long-established product, design, and engineering workflows—<em>and people—</em>are being turned completely on their heads.</p><p>Yet it’s a bit fantastic, if I’m being honest. I’m cautiously loving how a PM can turn a rough workflow into something an engineer can build from, a designer can explore and ideate by making changes to the actual codebase, and an engineer can spin up a fully-functional app while everyone’s reading the PRD.</p><p>But there is a lot of risk here, too. If AI completely democratizes the ability to create polished artifacts, we begin mistaking expression and opinion for understanding. We lose the healthy uncertainty that forces us to slow down and think critically. You learn to skip over the details without engaging your prefrontal cortex at all.</p><p>Worse, AI tools are optimized for inertia. They’re designed to complete the pattern. To continue the narrative. They validate your bias, pat you on the back, and agree with your assumptions. Incredibly useful when you’re exploring or trying to overcome blank-page paralysis. But they’ll happily help you accelerate nonsense into a polished 💩 if you’re not thinking.</p><h4>This is why critical thinking matters.</h4><p>AI models don’t (yet…) understand your business, customers, team dynamics, architecture, or tradeoffs deeply enough to reliably decide how intent, uncertainty, or decisions should be communicated.</p><p>And increasingly, communication is no longer just human-to-human. Sometimes it’s human-to-machine. Sometimes it’s machine-to-machine with a human trying to sanity-check the output before something catches fire in production.</p><p>Healthy friction still matters. People—the fleshy kind—need to challenge assumptions. They need to expose ambiguity instead of hiding it behind polished artifacts. They need to ask <em>better questions</em> before generating <em>more</em> <em>output</em>.</p><p><strong>What uncertainty are we actually reducing?</strong></p><p><strong>What decision are we trying to make?</strong></p><p><strong>What matters most</strong> — and what does not?</p><p><strong>Is this artifact helping us understand that more clearly?</strong> If not, what is the simplest thing we could do that creates the clearest shared understanding? Not the most impressive thing. Not the most polished thing. Not the thing that took 7 team syncs and 3 design reviews to refine.</p><p>If a whiteboard sketch communicates the idea, use the whiteboard sketch. If a pencil drawing gets everyone aligned, take the win. If a Balsamiq prototype answers the question the same as a polished mockup would have, but in half the time, do that. If a Slack message is enough, please, for the love of all that is good and kind in this universe, do not create a 17-page requirements document unless everyone needs a nap.</p><p>We overproduce artifacts because they feel like tangible progress. They are comforting illusions. Just because AI is making it easier to create them faster, or make them shinier and more complex, doesn’t mean we should.</p><p>Otherwise, we’re just creating better-looking uncertainty.</p><p><em>fin<br></em> — B</p><blockquote><em>read more long-form at </em><a href="https://brandonscript.design/"><em>brandonscript.design</em></a><em><br>or follow me on</em></blockquote><blockquote><em>🐘 </em><a href="https://appdot.net/"><em>Mastodon</em></a><em><br>💼 </em><a href="https://linkedin.com/in/brandonscript"><em>LinkedIn</em></a><em><br>🐙 </em><a href="https://github.com/brandonscript"><em>GitHub</em></a></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=78bc924891fa" width="1" height="1" alt=""><hr><p><a href="https://brandonscript.design/are-we-creating-artifacts-for-clarity-or-just-better-looking-uncertainty-78bc924891fa">Are we creating artifacts for clarity, or just better-looking uncertainty?</a> was originally published in <a href="https://brandonscript.design/">UX &amp; Code | opinions &amp; scribbles</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[When the stakes aren’t clear, nothing else works]]></title>
            <link>https://brandonscript.design/when-the-stakes-arent-clear-nothing-else-works-f0fcb4cb68ac?source=rss-16b233cf1ec5------2</link>
            <guid isPermaLink="false">https://medium.com/p/f0fcb4cb68ac</guid>
            <category><![CDATA[storytelling]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[product-development]]></category>
            <category><![CDATA[startup-lessons]]></category>
            <dc:creator><![CDATA[Brandon S.]]></dc:creator>
            <pubDate>Sat, 25 Apr 2026 13:46:01 GMT</pubDate>
            <atom:updated>2026-04-27T16:40:37.877Z</atom:updated>
            <cc:license>https://creativecommons.org/licenses/by-nd/4.0/</cc:license>
            <content:encoded><![CDATA[<figure><img alt="A LEGO USS Voyager, NCC-74656, poorly assembled, on a TOS-style space matte." src="https://cdn-images-1.medium.com/max/1024/1*01XxRCPvCWNsRthJpIJVOg.png" /><figcaption>“Captain’s log, supplemental: someone forgot the instruction manual in one of the plasma manifolds.”</figcaption></figure><p>I’ve been listening to <a href="https://thedeltaflyers.org/">The Delta Flyers</a> podcast recently — which is unusual for me (I’m not much of a podcast person). I tend to default to fiction, especially in audiobook format, both because I’m a dreamer and an escapist at heart, and because let’s be honest *gestures at everything* it’s kind of a lot right now? But I love Trek, and I’m enjoying it tremendously.</p><p>One theme keeps coming up in Robbie and Garret’s conversations that I haven’t been able to shake. So often when they revisit an episode that didn’t quite land, it traces back to the same issue:</p><p><strong>The stakes don’t work.</strong></p><p>Not necessarily because they’re too low, or wrong, and not because the “mission of the week” doesn’t resonate with an audience, but because the stakes are unclear.</p><p>Sometimes the audience doesn’t understand what’s at risk. Sometimes the actors don’t have enough context to play the scene with conviction. Maybe the director doesn’t know the characters or the worldbuilding of Star Trek well enough to craft the right message. Sometimes the writing itself hasn’t fully committed to what the story is actually about.</p><p>And sometimes, through some combination of all of that, it’s not even clear <em>who</em> the story is about.</p><p>When that happens, everything starts to drift. The pacing feels off. The performances flatten out. The resolution — when it comes — feels arbitrary and unconvincing, rather than inevitable and satisfying. How can you be invested in the outcome if you don’t understand why it matters? How can you care about the characters if you don’t understand what they’re thinking or why?</p><p>Star Trek is at its best when it leaves you with something — a message, a lesson — and lingers in your head. It doesn’t have to be a happy outcome. It can leave a bad taste in your mouth. But that should be intentional, to make you think and to grow — not the result of execution falling short.</p><p>And to be clear, this isn’t just a Trek or a sci-fi problem. It’s foundational to storytelling in general — one of the core pillars of the <a href="https://en.wikipedia.org/wiki/Hero%27s_journey"><em>hero’s journey</em></a>, and one that’s often overlooked, leaving the story itself feeling underwhelming.</p><p>A lot of big-budget, high-ego films fall into this trap, where everything is urgent, but nothing feels important — because <em>urgency</em> isn’t the same thing as <em>stakes</em>. We see extremely melodramatic characters, but without believable motivation (because we don’t understand them)—like purple Josh Brolin, or the billionaire vigilante with PTSD running around in a mask and cape.</p><p>If the audience doesn’t understand <em>why</em> something matters — or to whom — then increasing the scale of the production just adds noise.</p><figure><img alt="A comic of a mostly empty theatre, the few people there are snoring or asleep. On the screen is a nonsensical explosion with two characters on a bad green-screen scene jumping away from an explosion." src="https://cdn-images-1.medium.com/max/1024/1*G0GP7dBNHRY-dSOHjNPTOQ.png" /><figcaption>Surgeon General’s warning: sleeping in a theatre is hazardous to your health. Those seats are sticky.</figcaption></figure><p>On the other hand, you can have stories where the stakes are objectively small — a relationship, a single decision, a contained conflict — but feel incredibly compelling. Because the story pulls the audience in, showing them exactly what’s at risk, so they can understand why it matters.</p><p>So that every important moment carries weight.</p><p>It took me a beat, but it clicked when I realized this pattern exists everywhere outside of storytelling, too.</p><p><strong>Personally</strong>, as someone who has struggled with motivation, as a parent trying to be better, and as a human who continues to make mistakes.</p><p><strong>Professionally</strong>, as someone who loves building things, who should be better at listening, and who thrives under pressure.</p><p>We tend to assume that if we have the right people (strong engineers, designers, product owners), then good decisions will follow. But like fiction, that assumption quietly depends on how well you collectively understand what’s at stake.</p><p>You and your team are like the audience when you find yourself asking:</p><ul><li>What actually matters here?</li><li>What happens if we get this wrong?</li><li>Why does this decision exist?</li><li>Are we building for the right people?</li><li>What is the impact of my choices?</li></ul><p>Without stakes, you’re not really making decisions — you’re making approximations based on incomplete context under the illusion of certainty.</p><p>And that’s where things break down. Like in film and TV, when everyone on set is working hard and believes they’re making something great, but no one shares the same understanding of what the story is — or why it matters.</p><h4>It’s Monday</h4><p>Your team is deciding between two features. On paper, both seem reasonable. Both have user value. Both loosely align with the roadmap.</p><p>But without clear stakes, the discussion drifts toward surface-level arguments:</p><ul><li>Which one is easier to build?</li><li>Which one has a more visible impact?</li><li>Which one can we ship faster?</li></ul><p>These aren’t <em>wrong</em>, but they’re not grounded in what actually matters, so whatever decision you make feels… arbitrary.</p><figure><img alt="A comic-style whiteboard full of conflicting arrows / ideas, some circular, some leading nowhere, one leading to a surprisingly good whiteboard marker drawing of a cat." src="https://cdn-images-1.medium.com/max/1024/1*qHM-i1DioFoRT9G3u6zPyg.png" /><figcaption>Meow</figcaption></figure><h4>It’s the same Monday, in an alternate universe</h4><p>And the stakes are clear.</p><p>You know one feature directly impacts retention in a fragile part of the funnel. The team knows this — because leadership has communicated what matters, and why. You may not know if it’s the perfect solution — but everyone is aligned on what problem needs solving.</p><p>There’s no debate about which needle matters.</p><p>Motivation shifts, too.</p><p>When people don’t understand the stakes, it’s hard to feel ownership. The work becomes abstract. Tasks still get completed, but there’s no real sense of <em>consequence</em> or <em>value </em>attached to them.</p><h4>It’s Friday, and that loud customer is in your inbox</h4><p>We’ve all been there — they keep pulling you into expensive one-off work. When stakes are unclear, these get dismissed as “nice-to-haves” — or they get over-prioritized based on guesswork, and you end up working through the weekend.</p><p>But when the stakes are clear, the decision becomes clear, too: if that workflow is mission-critical for a key group of users — something tied to trust, value, or growth — then it’s not an edge case anymore.</p><p>It’s the product.</p><p>And when you get <em>why it matters</em>, you’re no longer frustrated by weekend work, you’re excited, motivated, and passionate.</p><p>On reflecting, I deeply understand why my time at Google often felt hollow. Besides the reality that a lot of work was optimized for effort or perf (instead of impact or value), there was no shared understanding of:</p><ul><li>Is this good enough?</li><li>Do we need to handle this case now?</li><li>Is this the most important thing I should be doing?</li><li>How is this going to make a difference for the people using it?</li></ul><p><em>(And my personal favorite, let’s take bets on how soon it’ll be </em><a href="https://killedbygoogle.com/"><em>killedbygoogle.com</em></a><em>)</em></p><p>There’s a tendency to treat “alignment” as the solution. But alignment without stakes is shallow. A team can agree on <em>what</em> they’re building and still disagree on <em>how,</em> <em>why</em> and <em>for whom — </em>because each person carries a different mental model of what matters. And that inconsistency shows up everywhere:</p><ul><li>In the trade-offs that don’t make sense</li><li>Under- or over-engineered (me!) solutions</li><li>A product that feels incoherent</li></ul><p>You end up with a group of people building different interpretations of the same thing. Each person is capable, focused, and doing good work — but they’re all following slightly different instructions. And the result is exactly what you’d expect: a pile of well-made pieces that never quite fit together.</p><figure><img alt="A box/promo image for a hodge podge lego set built out of different sets and different eras, that looks like it might work, but we’re not really sure how?" src="https://cdn-images-1.medium.com/max/1024/1*4DAmiaGyjrP6fxcQ-O8bNw.png" /><figcaption>Maybe it works? (probably not)</figcaption></figure><p>Principles can help — some of my personal favorites:</p><ul><li>Perfect is the enemy of done.</li><li>If you’ve spent more than an hour stuck on a problem, ask for help.</li><li>A returning user is more valuable than a paying customer.</li><li>Don’t follow a process just because <em>it’s the process</em> — find the most efficient path and take it.</li><li>If you can’t agree, find someone else to make the decision and move on.</li><li>Optimize for <strong>small effort × big impact</strong> — not big effort × big impact or small effort × small impact.</li><li>If we’re not sure why this matters, we’re probably not ready to build it.</li><li>It’s okay to go with your gut when confidence is low — just be honest about it, and be willing to be wrong.</li><li>If it costs less than a developer-hour, it’s not worth debating.</li><li>If everything’s important, nothing is — and the stakes probably aren’t clear.</li></ul><p>…but only if they’re grounded in something real. Otherwise, they’re just preferences. What gives them weight is an understanding of consequence.</p><p>In other words: <em>stakes</em>.</p><p>One of my most beloved quotes, from <a href="https://tv.apple.com/movie/spirited/umc.cmc.3lp7wqowerzdbej98tveildi3">Spirited (2022)</a>:</p><blockquote>“Your sacrifice would have no meaning if it had no consequence.”</blockquote><figure><img alt="Marley looking at Clint Briggs from Spirited (2022)" src="https://cdn-images-1.medium.com/max/1024/1*-PRxfJ5a2T6UJmmGKcxktg.png" /></figure><p>That’s what <em>stakes</em> are. They define consequence.</p><p>It’s one of the reasons I love working with startups. At their best, they operate with a much clearer sense of what matters — what failure looks like, who it affects, and why we should all care.</p><p>But that clarity doesn’t come for free. It’s <em>incredibly</em> hard to develop — and even harder to maintain. It requires decision makers who can hold that context, communicate it clearly and consistently, and lead in a way that reinforces it.</p><p>If that isn’t clear, each person fills in the gaps by building their own idea of what’s important. It doesn’t matter how fast you move, or how talented your team is — you’ll end up with something that feels disjointed: polished in places, incoherent in others, complex where it shouldn’t be, shallow where it matters.</p><p>In storytelling, stakes keep the audience engaged and make the story worth following.</p><p>In product teams, they make the work worth doing, the decisions worth making, and inform answers to questions like:</p><ul><li>What happens if we fail?</li><li>What happens if we’re wrong?</li><li>What happens if we’re right?</li><li>How do we know we’re building for the right people?</li><li>Do we need this now, or can we learn first?</li><li>What are we not thinking about?</li><li>What are we willing to compromise on?</li></ul><p>In both, stakes do the same thing: they make the outcome matter — and give everyone involved a reason to care.</p><p>Which is what makes the story work.</p><p>And what makes the team effective.</p><p>None of this is particularly novel. I think this concept is probably as old as storytelling itself. But it’s easy to understate how foundational it is. To get caught up in a task, to be so focused on what’s in front of you — on the <em>tree</em> instead of the forest. Sometimes it’s hard even to recognize that things don’t feel right, let alone <em>why.</em></p><p>We spend so much time trying to improve our decision-making and collective efficiency with better processes, frameworks, and tools.</p><p>But decision quality is downstream of understanding. And understanding is downstream of stakes.</p><p>If the stakes aren’t clear, you can’t know what matters or why — and no amount of “process optimization” can fix that.</p><p>You’ll just get more consistent mediocrity.</p><p><em>fin<br></em> — B</p><blockquote><em>read more long-form at </em><a href="https://brandonscript.design/"><em>brandonscript.design</em></a><em><br>or follow me on</em></blockquote><blockquote><em>🐘 </em><a href="https://appdot.net/"><em>Mastodon</em></a><em><br>💼 </em><a href="https://linkedin.com/in/brandonscript"><em>LinkedIn</em></a><em><br>🐙 </em><a href="https://github.com/brandonscript"><em>GitHub</em></a></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f0fcb4cb68ac" width="1" height="1" alt=""><hr><p><a href="https://brandonscript.design/when-the-stakes-arent-clear-nothing-else-works-f0fcb4cb68ac">When the stakes aren’t clear, nothing else works</a> was originally published in <a href="https://brandonscript.design/">UX &amp; Code | opinions &amp; scribbles</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Making NVM work with Fish shell in 2023]]></title>
            <link>https://brandonscript.design/making-nvm-work-with-fish-shell-in-2023-f4a7990ac12c?source=rss-16b233cf1ec5------2</link>
            <guid isPermaLink="false">https://medium.com/p/f4a7990ac12c</guid>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[nodejs]]></category>
            <category><![CDATA[terminal]]></category>
            <category><![CDATA[mac]]></category>
            <category><![CDATA[shell]]></category>
            <dc:creator><![CDATA[Brandon S.]]></dc:creator>
            <pubDate>Fri, 07 Jul 2023 17:34:46 GMT</pubDate>
            <atom:updated>2023-07-19T16:03:16.420Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jnRBR0g2fVtwFfK30ITy7A.png" /><figcaption>Fish + NVM: A Salty Tale</figcaption></figure><p>In the vast sea of shell options, <a href="https://fishshell.com/">Fish</a> stands out with its user-friendly autocomplete, elegant syntax, portable functions, and pretty colors. It’s one of my personal favorites—I’ve been using it for years. Why, you ask, don’t I use zsh or bash? Well, because, I’m different. And I like it that way, I suppose.</p><p>But being different sometimes makes me salty. Like when Fish doesn’t let me use $ for variables (so I can’t copy shell commands from docs), or when I’m trying to get <a href="https://github.com/pyenv/pyenv">pyenv</a> installed. But on today’s menu, I’m exhausted by having to figure out how get <a href="https://github.com/nvm-sh/nvm">NVM</a> (Node Version Manager) to work with Fish—again. Every time I go to install it, what used to work no longer does, and there are so many tall tales out there that <em>don’t</em> work anymore that my head is swimming 😵‍💫</p><p>But fear not, I have solved this problem once again. Here we be navigating the depths of shell configuration together so you don’t implode from all the pressure and stress!</p><h4><strong>Step 1:</strong> Install Fish Shell</h4><p>To start, if you want to use Fish but you haven’t installed it already, you need to start there. This should really be step 0, honestly.</p><p>On macOS, you can use Homebrew with the following command:</p><pre>brew install fish</pre><p>For Linux users, consult your package manager to install Fish Shell, but it’s probably:</p><pre>sudo apt install fish<br># or<br>sudo apt-get) install fish</pre><p>If Fish isn’t already your default shell, you can change it with the chsh command:</p><pre>sudo chsh -s /usr/local/bin/fish<br># or if for some reason your path to fish is different:<br>sudo chsh -s (which fish)</pre><h4>Step 2: Install NVM</h4><p>Next, if you haven’t already, install NVM (Node Version Manager). Using Homebrew:</p><pre>brew install nvm</pre><p>Or on Linux (but: you’re best to check the <a href="https://github.com/nvm-sh/nvm#installing-and-updating">docs</a> in case the version in this post is out of date)</p><pre>curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash<br># or <br>wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash</pre><h4>Step 3: Install Oh-My-Fish (OMF)</h4><p>Oh-My-Fish is a delightful framework for managing Fish Shell configurations. It supports plugins and makes it really easy to do hard things, kind of like using a lure on a fishing pole instead of hopes and dreams.</p><p>Install it using the following command:</p><pre>curl -L https://get.oh-my.fish | fish</pre><h4>Step 4: Install the NVM plugin for Fish</h4><p>Now, since we’re using OMF, we can use the NVM plugin — which takes care of much of the heavy lifting and complicated path stuff that you’d otherwise have to do by hand. I’ve had to do this before, and it turned me into a crabby, crusty, crustacean.</p><p>Now we can just run:</p><pre>omf install nvm</pre><h4>Step 5: Set the NVM Directory</h4><p>You’ll need to set the NVM_DIR environment variable so NVM knows where to look for Node.js versions. This magic step allows NVM to automatically update your $PATH with the when the active Node version changes. If you don’t do this, you’ll get fish: Unknown command: nodewhen trying to run it.</p><p>On Mac, if you’re using Homebrew, this is pretty straightforward:</p><pre>set -gx NVM_DIR (brew --prefix nvm)</pre><p>But if you’re not using Homebrew, or you’re on Linux, this can get pretty tricky — you’ll have to find out where your NVM root path is. It might be $HOME/.nvm, but if not, you’ll have to read the docs for your platform:</p><pre>set -gx NVM_DIR $HOME/.nvm</pre><h4>Step 6: Install Fisher</h4><p>Fisher is a plugin manager for Fish Shell that simplifies the installation of additional plugins. Why, you ask, do we need another plugin manager if OMF already does plugins, <em>and</em> we installed the NVM plugin with OMF?</p><p>The answer you seek is at the bottom of the sea. I do not know it, I cannot see it, and I cannot tell you what secrets it holds.</p><p>Install Fisher using Homebrew:</p><pre>brew install fisher</pre><p>Or manually:</p><pre>curl -sL https://raw.githubusercontent.com/jorgebucaran/fisher/main/functions/fisher.fish | source &amp;&amp; fisher install jorgebucaran/fisher</pre><h4>Step 7: Install the NVM plugin for Fisher</h4><p>This one’s a breeze:</p><pre>fisher install jorgebucaran/nvm.fish</pre><h4>Step 8: Install and use a Node version</h4><p>With NVM and Fish integrated, you can install and manage as many Node.js versions as you want, as easy as putting bread in the toaster. It’s like you get to be a captain of a whole fleet of Nodes!</p><p>For example, to install Node.js version 18, run:</p><pre>nvm install 18</pre><p>(Here you can just replace 18 with the desired version number, or lts to get the latest).</p><p>To use it, do:</p><pre>nvm use 18</pre><p>(If you’re familiar with NVM, this is the same thing you’ve always done). There’s just one more gotcha with Fish that we need to take care of: saving the default version for new shells.</p><h4>Step 9: Set the default Node version</h4><p>If you want a specific Node.js version to be the default, you may think you’re clever and can use the command from NVM docs, nvm alias default—but you cannot! It will <em>not</em> persist across Terminal sessions, and you will be sad and frustrated. Instead, use the following command:</p><pre>set --universal nvm_default_version 18</pre><p>(Remember to restart your Fish shell or open a new Terminal session for the changes to take effect).</p><p>And if you’re building with another application like VS Code that maintains its own $PATH variables inside its integrated terminal, you may find that it still does not respect the correct Node version. To work around that, you can check for other conflicting Node versions:</p><pre>which -a node</pre><p>…and when you find one (maybe at /usr/local/bin/node) you can remove them with:</p><pre>rm -rf /usr/local/bin/node</pre><h4>Well, that wasn’t so bad, right?</h4><p>You’ve successfully set up NVM to work with Fish on your Mac (or your Linux) system. May your coding adventures be smooth sailing, and may I be able to come back to this blog post for some good copypasta the next time I forget how to do it.</p><p><em>fin<br></em> — B</p><blockquote><em>read more long-form at </em><a href="https://brandonscript.design/"><em>brandonscript.design</em></a><em><br>or follow me on</em></blockquote><blockquote><em>🐘 </em><a href="https://appdot.net/"><em>Mastodon</em></a><em><br>💼 </em><a href="https://linkedin.com/in/brandonscript"><em>LinkedIn</em></a><em><br>🐙 </em><a href="https://github.com/brandonscript"><em>GitHub</em></a><em><br>🪺 </em><a href="https://twitter.com/brandonscript"><em>Twitter</em></a></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f4a7990ac12c" width="1" height="1" alt=""><hr><p><a href="https://brandonscript.design/making-nvm-work-with-fish-shell-in-2023-f4a7990ac12c">Making NVM work with Fish shell in 2023</a> was originally published in <a href="https://brandonscript.design/">UX &amp; Code | opinions &amp; scribbles</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building high-performing, cross-functional design teams with real-time designer × developer pairing]]></title>
            <link>https://brandonscript.design/building-high-performing-cross-functional-design-teams-with-real-time-designer-developer-pairing-3450838f52af?source=rss-16b233cf1ec5------2</link>
            <guid isPermaLink="false">https://medium.com/p/3450838f52af</guid>
            <category><![CDATA[design-process]]></category>
            <category><![CDATA[design-thinking-culture]]></category>
            <category><![CDATA[team-collaboration]]></category>
            <category><![CDATA[pair-design]]></category>
            <category><![CDATA[pair-programming]]></category>
            <dc:creator><![CDATA[Brandon S.]]></dc:creator>
            <pubDate>Sat, 11 Feb 2023 19:05:02 GMT</pubDate>
            <atom:updated>2023-02-11T19:20:55.926Z</atom:updated>
            <content:encoded><![CDATA[<h3>How real-time designer × developer pairing can build high-performing, cross-functional design teams</h3><h3>Preface</h3><p>I’ve been interviewing for <em>a lot</em> of teams lately, and when talking about design roles, questions like “tell us about your design process?”, “how do you work with cross-functional teams?”, and “tell us about your design hand-off and review process?” seem to come up a lot.</p><p>The answer I usually give has raised more than a few eyebrows, so I’ve taken some time to write about my staunch belief that high-performing design teams don’t necessarily need a formal process or sequence of steps in order to be successful. In my experience, what they <em>do</em> need is ongoing communication, trust, and an environment that encourages <em>pairing</em>, or frequent, lightweight collaboration—getting the right people across functions working together to solve problems in real-time—in order to get the most out of their collective knowledge, skills, diverse perspectives, and experience.</p><p>Before we jump into cross-functional pairing, we should start at the beginning with pair-programming.</p><h3>What is pair-programming?</h3><p>Pair-programming is a pretty-well-established software development practice (it’s been around since c. 2000 AD) where two programmers work together on the same problem or feature, sitting together at a single computer. While one person “drives” (writes the code), the other person watches and observes. The observer can watch for mistakes, suggests ideas, and most of all—with the full context of the code and the problem in front of them—can be a great sounding board for discussion and troubleshooting.</p><p>Today, we are very privileged to have some great remote pairing apps like <a href="https://tuple.app/">Tuple</a> and <a href="https://pop.com/">Pop</a> that allow us to pair with anyone in the world in an instant—empowering developers to collaborate in real time like Figma has done for designers. Not only does that free us up to work with different team members whenever it makes sense, it makes switching pairs instantaneous. (Plus, let’s be honest, two people at one desk can get kind of claustrophobic and oxygen-deprived anyway?)</p><p>If you’ve never done this before, and you might be a skeptic, pair programming has been shown to increase productivity, reduce bugs, and improve code quality. And not just a little bit either — measurably. Our friends over at Tuple have done all the tl;dr legwork for us to <a href="https://tuple.app/pair-programming-guide/scientific-research-into-pair-programming">gather evidence</a>, but most notably:</p><blockquote><em>Jensen, R. W. (1996)<br></em>Regarding the performance of pairs vs individuals:</blockquote><blockquote><em>Final project results were outstanding. Total productivity was 175 lines per person-month (lppm) compared to a documented average individual productivity of only 77 llpm.</em></blockquote><blockquote><em>The error rate […] was three orders of magnitude lower than the organization’s norm.</em></blockquote><blockquote>(Pairs had a defect rate <em>one thousandth</em> of individuals’. Holy crap!)</blockquote><p>Indeed.</p><figure><img alt="A comic / drawing showing two awesome pair-programmers working at a computer at night time." src="https://cdn-images-1.medium.com/max/1024/1*Q7fQry2WtwyIJTc4ohUkDQ.jpeg" /></figure><h3>This same concept can be adapted to design teams</h3><p>Consider a typical agile workflow. Where an engineer would pull a user story or bug ticket down and work through it, if that ticket would (should) normally require some design input, have a designer and frontend developer pair together and work through the entire solution lifecycle (conception, understanding, design, prototyping, testing, refinement, launch to production, and measure its impact).</p><p>In practice, we often don’t staff our teams with a 1:1 designer-to-developer ratio, but we can be pragmatic and adjust the principles here to suit our needs and team structure:</p><ul><li>By taking advantage of screen pairing apps, a designer can pair with a couple of engineers who are already working together, or</li><li>Have designers float between engineers or tickets, wherever they can have the most impact.</li></ul><p>This might require a certain amount of hands-on attention if you’re new to the concept—at least daily check-ins to make sure the right people are paired up in the most effective way. But once you get the hang of it, you might be surprised to find your more technically-inclined designers can add tremendous value even to backend and architectural design work, and your design-inspired engineers have excellent design input.</p><h3>Why the benefits outweigh the cost</h3><p>By pairing together, the designer, with their deep understanding of users and behaviours, can communicate intent, identify common pitfalls, and explore user journeys. They’ll also lean on their design thinking skills to find creative ways to work through problems, refine ideas, and build shared context.</p><p>And the developer, with their strong technical knowledge of the codebase and ability to estimate engineering effort &amp; complexity, can offer immediate feedback and can challenge the designer to think orthogonally. They’ll also be able to contribute their own ideas, lend their perspective, and ask questions in real-time —producing a less ambiguous, better-engineered result.</p><p>Over time, as they work closely with each other, the designer develops a technical awareness that helps them make well-rounded design decisions and articulate their design ideas with just the right amount of fidelity, and the engineer becomes more thoughtful and sensitive to design-centric principles, which become an automatic and subconscious part of writing code.</p><p>Despite the additional cost on paper of the increased person-hours, teams that practice pairing demonstrate higher levels of collaboration and understanding—leading to many tactical benefits:</p><ul><li>Increased confidence in the solution, its scope, and the effort involved.</li><li>Faster turnaround time for design (or eliminates this overhead entirely).</li><li>Reduced waste from scope creep and solution oversights.</li><li>Little or no ambiguity when interpreting solutions (because confusion and questions are resolved in real-time).</li><li>More consistency across products, features, and pages/views.</li><li>Synchronous planning/cadence between design &amp; engineering teams (your engineering managers will thank you).</li><li>Stronger working relationships and better communication velocity.</li></ul><p>This concept—its principles and its benefits — scales strategically, too. Sustaining a real-time, cross-functional collaboration strategy at every level throughout a project’s lifecycle has a measurable effect on output. Over time, teams develop:</p><ul><li>A broader understanding of cross-functional constraints and challenges.</li><li>Shared empathy and compassion for how other disciplines think and work, and what their day-to-day job requires.</li><li>A strengthening of self-awareness and critical thinking skills as teams learn from each other’s unique approaches to solving problems — like design-thinking idea generation, and rubber-duck debugging.</li><li>The confidence and safety to challenge ideas, offer (and take) criticism, and resolve conflict — with respect.</li><li>A common taxonomy around design concepts, constructs, and principles — which makes it easier to work with our design system and patterns, explore and understand behaviors, and build accessible products.</li><li>Organizational (read: leadership) trust in the team, which leads to team autonomy, ownership of projects &amp;decisions, and individual accountability.</li><li>A much broader understanding of all the nuances, complexity, and tradeoffs that would normally be left to product owners / PMs or a program manager to oversee.</li></ul><p>This increased effectiveness leads to higher-quality output and promotes great working relationships. Armed with trust, awareness, and a communication precedent, you now have people who can make informed decisions quickly and autonomously, which, *checks notes*, ultimately leads to better products.</p><h3>On culture &amp; strategic design</h3><p>I’m pretty passionate and outspoken about my opinion that <em>design is a culture, not a process</em>.</p><p>This is a bit of an over-generalization, but the point is that when we rigidly follow a process without applying critical thinking, we risk spending a lot of time ticking boxes instead of delivering value. This is often a symptom (especially in larger organizations) of a lack of trust and autocratic, or absent, leadership — where someone wants their hand on the cookie jar at all times but doesn’t actually spend time in the kitchen doing the baking.</p><p>For cross-functional pairing to be organizationally successful, it takes work and top-down commitment. Still, if you can shift toward a culture of real-time dialogue and autonomy, everyone can start to flex their critical thinking muscles. With practice, they can anticipate each other’s questions, objections, and expectations, and they’ll spend less time circling the drain with unproductive, process-heavy overhead:</p><ul><li>Designers can tailor the way they approach and solve problems (depending on the outcomes they want and the different perspectives their pairs bring), instead of following a canned design process; they can become strong collaborators and contributors, rather than awkward roadblocks.</li><li>Engineers can be more thoughtful without sacrificing speed, becoming more empathic problem solvers and lending their technical perspective to the design process <em>[alright, I concede, it’s still a process, it’s just not a rigid, one-size-fits-all process]</em>.</li></ul><p>And this doesn’t only apply to designers working with developers, either. It works <em>between</em> designers, and it works for anyone who is involved in the product lifecycle — product managers, content writers, DevOps, QA engineers, customer success, et al.</p><p>So how can we get there organizationally?</p><p>The first step is understanding the value. If you’ve gotten this far, you’re either <a href="https://xkcd.com/386/">polarizingly upset</a>, or you’re quietly thinking “please I want to ship better quality products, features, code, and designs, faster thanks.”</p><p>The next step is recognizing that it takes a lot of hard work to steer a ship, and then doing it anyway.</p><ul><li>Executives need to believe the investment in time and tools is worth it, and commit.</li><li>Managers need to lead by example, build trust, and look for ways to enable more effective collaboration</li><li>And it’s a team effort to embrace these new principles and give them a fair shot.</li></ul><p>The most difficult part here — apart from the arduous task of shifting culture — is making sure that everybody buys into the idea of critical thinking. It’s dangerous to conflate this <em>autonomy </em>and <em>shared understanding </em>with the notion that every decision should be democratic. On the contrary, applying critical thinking means that the people doing the work should decide what’s best at any given moment, but they also need confidence and transparency to know whether they’re the <em>right</em> people, too.</p><p>For leaders, this means setting boundaries and communicating your expectations often; sometimes it means making sure you’re in the room, and other times it means delegating and trusting your team.</p><p>For team managers, it means coaching, mentoring, coordinating pairs, and prioritizing work; it means unblocking and supporting your team, and insulating them from process overhead and churn. When you’re an escalation point, you’ll need to be self-aware enough to recognize when you, a single point of failure, are blocking velocity.</p><p>For ICs, remember that the “I” in <em>individual contributor</em> isn’t about ego or self-importance. It’s about playing to your strengths — taking responsibility for thinking critically, trusting yourself to make the right decisions, and learning to recognize whether the right people are in the room. And it’s about being humble enough to lean on your peers — to learn from them, and to embrace the discomfort and ambiguity that comes from stepping outside your area of expertise.</p><p>For everyone, this takes a conscious effort and a willingness to learn from our failures and mistakes, and continuously refine our approach so we can focus on optimizing our output — our products, systems, and designs — and delivering value.</p><h3>Cutting down on communication burnout and the design review revolution</h3><p>At this point, it’s important to emphasize that I’m not suggesting eliminating “process” altogether; yes, many processes are in place for a good reason. What I’m advocating for is to use common sense to look for ways to reduce friction, and to think critically before blindly following suffocating, <em>flawed</em> processes.</p><p>Cross-functional pairing allows teams to keep everyone on the same page in near real-time. Validations become much more lightweight because they happen often, without the back-and-forth of email-tag (or Slack-tag, or one-of-Google’s-14-messaging-apps-tag) or lengthy, confusing, bloated, frustrating discussions that delay progress and drain your burnout-o-meter.</p><p>When everyone is connecting seamlessly and organically, creativity opens up, and ideas flow more freely. When those ideas are amplified, there’s an unquantifiable happiness <em>(read: dopamine)</em> factor that motivates and lifts everyone up. People feel more included. They feel like their work matters — that it’s more meaningful and more valuable — because they see their impact move up and to the right as a direct result of their effort and contributions.</p><p>Applied to time-consuming design hand-offs, where designers often work in isolation on a problem for days or weeks before delivering a mostly-baked solution to an unsuspecting engineering team, pairing virtually eliminates the “hand-off” between designers and engineers. Development can start as soon as the pair is ready, and they can easily revise and adjust on the go as a pair.</p><p>Applied to the dreaded <em>design review — </em>where the designer in the room, having invested considerable time and effort into a solution, tries to convince their cross-functional peers and stakeholders to buy into their proposal only to find the room squirrelling off on a dozen different tangents—</p><figure><img alt="A comic about a design-o-saur review, in which the stakeholder without enough context to really know what’s going on is making everyone in the room, especially the designer who is presenting, extremely uncomfortable." src="https://cdn-images-1.medium.com/max/1024/1*kTxrQFy7N_3PjpqyCctycA.jpeg" /><figcaption>Designosaur review</figcaption></figure><p>…we find pairing leads to a room of smart folks with a common understanding and well-rounded context that can be pushed as a team uphill to stakeholders.</p><p>Done right, design review becomes nothing more than a formality.</p><p>In fact, I would challenge you that these coveted processes are actually evidence of a <em>broken </em>system. When your teams are working too asynchronously, communication breaks down, critical context is lost (or more aptly, never found), and the adage “we don’t know what we don’t know” lurks in the shadows. Yes, there are exceptions to this rule—but just make sure these formal processes are actually adding value or protecting the business. Otherwise, they are just <a href="http://www.expensivemeeting.com/">really expensive meetings</a>.</p><h3>Commence micro-management</h3><p>Real-time cross-functional collaboration can go a long way toward aligning the <em>team</em>, which makes convincing stakeholders to buy into a solution less difficult. But this can’t take you all the way: the other side of the coin is having stakeholders who actively engage in the daily conversation (when appropriate), or who trust their team and delegate decisions. When they play both sides with one foot out of the water, no matter how aligned the team is, time is inevitably wasted (re-)explaining context, the nuances of a problem, and justifying solutions.</p><p>In many organizations, this is impractical or impossible to change, especially from the bottom up. Sometimes it’s just a byproduct of a workforce stretched too thin, but it can also be symptomatic of toxic leadership: poor top-down communication skills, lack of trust, inability to delegate, or an irrational need for control.</p><p>This is why when we talk about the <em>how, </em>cross-functional pairing can’t just be a process; it must be a culture that comes as much from the top as it does from the bottom. Without leaders willing to trust, delegate, and empower, you end up pointing your ship upwind without any sails. Working against that kind of organizational friction is a lot of work and emotionally draining.</p><figure><img alt="A micro-manager robot made out of LEGO, from the LEGO movie. Famously quoted for saying “commence micro-management”." src="https://cdn-images-1.medium.com/max/421/0*budNT3Wr8W9ZZKJj.png" /><figcaption>Commence micro-management!</figcaption></figure><h3>Your engineering managers will thank you</h3><p>If you’ve been an engineering manager, or even if you just play one after you put pants on in the morning, you’ve probably worked with <em>that designer </em>— you know, the one who is always hitting the breaks and speaking up with the excuse <em>well, because design</em>.</p><p>So often this happens simply because of org structure: a design team reports to a design manager, who reports to a design director, who reports to a VP of, well, something (probably product or engineering), while engineering teams report up to a different tree entirely. On top of conflicting organizational/team OKRs, everyone has their own principles and priorities. It is laborious and exhausting if your team members have to constantly justify their points of view and explain their opinions to each other; sometimes it’s easier to just go with <em>well, because design </em>or <em>well, because code</em>.</p><p>(There are certainly other reasons why both designers and engineers become gatekeepers, not the least of which is hubris, but gatekeeping is gatekeeping, and the <em>why</em> doesn’t change how it affects the team.)</p><p>Encouraging your teams to pair together lets designers and engineers share the same workflows, principles, and planning tools. You save time by having both teams operating on the same cadence, keeping your backlog—velocity and progress—in sync. Your eng (or program) managers no longer have to balance the ledger between their project planning tool and whatever the design team uses. No one is chasing after status updates for days. And when someone does need to hit the brakes, the reasons are clear and articulate.</p><h3>The thoughtful navigator</h3><p>Pairing designers with developers yields an inspired and productive team that leads to faster, higher-quality work. We get benefits like:</p><ul><li>Faster turnaround time for design output</li><li>Improved code quality, implementation, and usability</li><li>Empathy, compassion, and communication skills across functions</li><li>Stronger problem-solving &amp; design-thinking skills</li><li>Reduced waste from mistakes and misunderstandings</li><li>Teams who respect, trust, and depend on one another</li></ul><p>But as outspoken as I am about cross-functional pairing, I should call out the false dilemma in this: just as you should apply critical thinking when you are working on <em>work</em>, you should also think critically when thinking about <em>how</em> <em>to work</em>. Don’t let the pendulum swing too far in the other direction: you don’t need to (and shouldn’t) immediately flip your organization upside down and force this mentality onto your people.</p><p>It’s not a race. Go slow, be patient, and remember — <em>everything in moderation</em>. Not every task requires pairing. A design sprint around a clearly defined design problem can just as easily waste engineering time by involving them as it might by excluding them. And having designers in the room while engineers are working through a technical spike may not, in fact, be the most effective use of their time. Embrace as much flexibility as you can handle, and trust your people to decide for each situation whether working together or independently is the most valuable use of their time.</p><p>This culture of cross-functional pairing (and the wisdom to sail cautiously toward it) requires trust, and it takes time to develop the necessary level of decision-making maturity within your teams.</p><p>And it demands that you, as the thoughtful navigator, have one hand on the pulse of your crew, and the other firmly on the helm.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pFeaDY_alZQsQ5v2nAWcgQ.jpeg" /></figure><p><em>fin<br></em> — B</p><blockquote><em>read more long-form at </em><a href="https://brandonscript.design/"><em>brandonscript.design</em></a><em> <br>or follow me on</em></blockquote><blockquote><em>🐘 </em><a href="https://appdot.net/"><em>Mastodon</em></a><em><br>💼 </em><a href="https://linkedin.com/in/brandonscript"><em>LinkedIn</em></a><em><br>🐙 </em><a href="https://github.com/brandonscript"><em>GitHub</em></a><em><br>🪺 </em><a href="https://twitter.com/brandonscript"><em>Twitter</em></a></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3450838f52af" width="1" height="1" alt=""><hr><p><a href="https://brandonscript.design/building-high-performing-cross-functional-design-teams-with-real-time-designer-developer-pairing-3450838f52af">Building high-performing, cross-functional design teams with real-time designer × developer pairing</a> was originally published in <a href="https://brandonscript.design/">UX &amp; Code | opinions &amp; scribbles</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[An interactice React state & memoization sandbox]]></title>
            <link>https://brandonscript.design/react-state-memoization-a2e7df922cc2?source=rss-16b233cf1ec5------2</link>
            <guid isPermaLink="false">https://medium.com/p/a2e7df922cc2</guid>
            <category><![CDATA[react]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[memoization]]></category>
            <category><![CDATA[typescript]]></category>
            <dc:creator><![CDATA[Brandon S.]]></dc:creator>
            <pubDate>Fri, 13 Jan 2023 21:00:39 GMT</pubDate>
            <atom:updated>2023-02-16T01:05:39.244Z</atom:updated>
            <content:encoded><![CDATA[<h4>Demystifying how and when React decides to (re-)render components</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/692/1*9UZhstNehsW2jTYPBlTOsw.jpeg" /></figure><p><em>tl;dr? Check out the project here </em>👉 <a href="https://react-memo-sandbox.vercel.app/"><em>https://react-memo-sandbox.vercel.app</em></a></p><p>We’ve been hard at work at <a href="https://delving.com/">Delving</a> building some incredibly cool software for people who <strong>love</strong> spreadsheets, but who are struggling with the onerous and frustrating workflows around them—people who lay awake at night worrying about how to keep track of all of their spreadsheet versions, or dreading the next time they’ll have to look for mistakes in a 10,000 line Excel file.</p><p>We built Delving’s front-end on React / Next.js / Vercel, which I <em>love</em>.<em> </em>But I also won’t miss an opportunity to point out that:</p><blockquote>React makes the hard things in JavaScript easy, and the easy things in JavaScript hard. <em><br>— (me, I said that)</em></blockquote><p>One of the hardest things about working with React if you’re building on top of complex data models and APIs, is the amount of data flowing through the app (and its components) that causes DOM elements to re-render.</p><p>The solution is <em>memoization</em>, but it’s not as simple as just saying “oh just memoize everything”. At this point, Alice probably needs something a little stronger in her coffee.</p><figure><img alt="Alice sitting at a table drinking a coffee. She is a rockstar software developer but she has been fighting with React state all day and needs something stronger in her coffee." src="https://cdn-images-1.medium.com/max/1024/1*rBKWJIpIxBM0I0RK9_27Uw.jpeg" /></figure><p>To understand just how deep down the rabbit hole this goes, we built an interactive article that not only explains with words why things are the way they are, but uses interactive examples to demonstrate it.</p><p>Come try it out! 👇</p><h4><a href="https://react-memo-sandbox.vercel.app/">https://react-memo-sandbox.vercel.app</a></h4><p>Special thanks to <a href="https://linkedin.com/in/serge-mugisha">Serge Mugisha</a> and <a href="https://www.linkedin.com/in/dina-buric">Dina Buric</a> who helped me put this together; and as always, feedback is welcome and appreciated.</p><p><em>fin<br></em> — B</p><blockquote>read more long-form at <a href="https://brandonscript.design/">brandonscript.design</a><br>follow me on <a href="https://twitter.com/brandonscript">Twitter</a>, <a href="https://appdot.net/@brandonscript">Mastodon</a>, <a href="https://polywork.com/brandonscript">Polywork</a>, or <a href="https://linkedin.com/in/brandonscript">LinkedIn</a><br>work with me at <a href="https://pacificaviator.co/">pacificaviator.co</a></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a2e7df922cc2" width="1" height="1" alt=""><hr><p><a href="https://brandonscript.design/react-state-memoization-a2e7df922cc2">An interactice React state &amp; memoization sandbox</a> was originally published in <a href="https://brandonscript.design/">UX &amp; Code | opinions &amp; scribbles</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Creating a custom icon generator for MUI]]></title>
            <link>https://brandonscript.design/creating-a-custom-icon-generator-for-mui-d0e388d93feb?source=rss-16b233cf1ec5------2</link>
            <guid isPermaLink="false">https://medium.com/p/d0e388d93feb</guid>
            <category><![CDATA[icons]]></category>
            <category><![CDATA[react]]></category>
            <category><![CDATA[mui]]></category>
            <category><![CDATA[javascript]]></category>
            <dc:creator><![CDATA[Brandon S.]]></dc:creator>
            <pubDate>Sat, 12 Feb 2022 03:23:03 GMT</pubDate>
            <atom:updated>2023-02-09T01:53:31.948Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="A snippet of code from the MUI icon generated by this project." src="https://cdn-images-1.medium.com/max/792/1*HNDBp3nDMNgM2IyhBKd8_A.png" /></figure><h3>MUI &amp; the library of Material Design icons</h3><p>Recently, I’ve begun to know and love <a href="https://mui.com/">MUI</a> — the UI component library for React based on (but not affiliated with) Material Design.</p><p>While its out-of-the-box appearance is very Googley, it’s super easy to customize to make it look and feel like your own—as evidenced by their own home-page showcase of the “MUI” theme. It’s brilliant not necessarily because of its style or appearance, but because of its robust, flexible component library that makes building apps in React really fast!</p><figure><img alt="MUI — the component library for React based on Material Design." src="https://cdn-images-1.medium.com/max/1024/1*jsST00XAw5mnTdMqIBIBrg.png" /></figure><p>Huge respect, too, for the <a href="https://mui.com/components/material-icons/">1,900+</a> Material Design icons in the library. As far as usability and visual accessibility is concerned, some of the best in existence. But if we’re trying to create a unique look and feel for a product, the distinctly Material Design look &amp; feel of the iconography lingers — and there’s no easy fix for it.</p><figure><img alt="MUI icons from https://mui.com/components/material-icons/" src="https://cdn-images-1.medium.com/max/1024/1*aQl7p434GeC-CAt3pdHQ7A.png" /></figure><h3>By which we need some custom icons</h3><p>Because after all, we want to be unique and feel special! (Or at least, we want our products to feel that way).</p><p>To do that, one needs a good icon library of SVG icons. There are a few out there like <a href="https://fontawesome.com/">Font Awesome</a> who have a ready-to-go React library, but you’ll again have the problem of looking like everyone else. The only other choice is to design (and maintain, it’s a zero-sum game) set of icons, or purchase a library/icon set. Of course, whichever you choose, you’ll just end up with bunch of SVG files in a folder. And you’ll see quite soon why that’s not quite going to cut it in React.</p><p>The structure and anatomy of an SVG is pretty straightforward, unless you’ve never looked at an SVG, and then you might want to cry a little. The short explanation is that SVG is a markup language, like HTML, that describes paths, lines, and shapes — and their various fill colours, if applicable, in a document. Here’s one of the icons from <a href="https://streamlinehq.com/">Streamline HQ</a> that I love:</p><pre>&lt;svg xmlns=&quot;http://www.w3.org/2000/svg&quot; viewBox=&quot;0 0 24 24&quot;&gt;<br>  &lt;defs&gt;<br>    &lt;style&gt;.a{fill:none;stroke:currentColor;stroke-linecap:round;stroke-linejoin:round;stroke-width:1.5px;}&lt;/style&gt;<br>  &lt;/defs&gt;<br>  &lt;title&gt;bin&lt;/title&gt;<br>  &lt;path class=&quot;a&quot; d=&quot;M17.25,21H6.75a1.5,1.5,0,0,1-1.5-1.5V6h13.5V19.5A1.5,1.5,0,0,1,17.25,21Z&quot;/&gt;<br>  &lt;line class=&quot;a&quot; x1=&quot;9.75&quot; y1=&quot;16.5&quot; x2=&quot;9.75&quot; y2=&quot;10.5&quot;/&gt;&lt;line class=&quot;a&quot; x1=&quot;14.25&quot; y1=&quot;16.5&quot; x2=&quot;14.25&quot; y2=&quot;10.5&quot;/&gt;&lt;line class=&quot;a&quot; x1=&quot;2.25&quot; y1=&quot;6&quot; x2=&quot;21.75&quot; y2=&quot;6&quot;/&gt;<br>  &lt;path class=&quot;a&quot; d=&quot;M14.25,3H9.75a1.5,1.5,0,0,0-1.5,1.5V6h7.5V4.5A1.5,1.5,0,0,0,14.25,3Z&quot;/&gt;<br>&lt;/svg&gt;</pre><figure><img alt="A trash can icon" src="https://cdn-images-1.medium.com/max/1024/1*rMe5Pqzk2bHXIWkm0Ciu1Q.png" /><figcaption>Une poubelle, a bin, a trash can</figcaption></figure><p>So what happens if we just tried to use it directly in React + MUI? We’d need to import the SVG, render it into a component, and it would come out on the page looking like…</p><figure><img alt="The trash can but without any CSS to make it behave itself on the page." src="https://cdn-images-1.medium.com/max/1024/1*0P8bDciBZxnfn6PJH6ctlg.png" /></figure><p>Uh oh, that’s, uh, awkward. We could of course wrap this icon inside a &lt;div&gt; and give it some css, and eventually make it behave itself. Though we’d have to do this for every icon we add? <em>And</em> what if we wanted to use some of the 🌶️ sx syntax that MUI v5 supports? And maybe the icons should be resizable, and respond to MUI’s important props like color?</p><blockquote>(Aside: you can read about sx here: <a href="https://mui.com/system/the-sx-prop/">https://mui.com/system/the-sx-prop/</a> and <a href="https://emotion.sh/">Emotion</a>, which it is built on, but I digress).</blockquote><p>You will quickly realize that manually wrapping these icons to behave like MUI icons is a lot of work, and not much fun. Doing it manually for <em>every</em> icon you add, remove, or change in your project is torture, and probably a full-time job. But we’re more clever than that, right?</p><h4>Generating React icons automagically using SVGR</h4><p>With everything in my life, I always assume there’s a better way of doing something. It might be the reason I spend hundreds of hours automating simple tasks that take 2 minutes to complete… 👀</p><p>But in this case, I wanted a foolproof, reliable way of ensuring that when icons are added to a project (or changed), they come out looking crisp and perfect—every time. Enter <a href="https://react-svgr.com/">SVGR</a>. It’s a powerful and very customizable tool that can automate the ingesting of SVG icons and spitting out of React components. Sounds like exactly what we’re looking for! There are four different implementations you can take advantage of: <strong>webpack</strong>, <strong>Next.js</strong>, <strong>Node</strong>, and even just a <strong>CLI</strong> (command line) tool. This means it can be bundled with just about any modern web project, either as part of the build process, or as a separate process.</p><p>Of course, the only challenge here is that it’s not really designed for MUI. But let’s not get ahead of ourselves.</p><p>For my purposes, I’m hoping to gatekeep the iconography of this project a lil bit to ensure some strictness around quality. There’s also value in being a minimalist about your project’s bundle size. Adding icon source images and icons that aren’t actively being used is just a waste of precious compute resources. With that in mind, I’m going to use the <a href="https://react-svgr.com/docs/cli/">CLI</a> tool so that I can have complete control over when and how icons happen. It works like this:</p><pre>npx @svgr/cli -- my-icon.svg</pre><blockquote>(If you’re following along, you’ll need to <a href="https://react-svgr.com/docs/cli/">install the SVGR CLI</a> first. You’ll also need an SVG icon to test this with).</blockquote><p>It spits out something that looks like this:</p><pre>import * as React from &quot;react&quot;;<br><br>const SvgBin = (props) =&gt; (<br>  &lt;svg <br>    xmlns=&quot;http://www.w3.org/2000/svg&quot; <br>    viewBox=&quot;0 0 24 24&quot; <br>    {...props}<br>  &gt;<br>    &lt;path d=&quot;M19.452 7.5H4.547a.5.5 0 0 0-.5...&quot; /&gt;<br>  &lt;/svg&gt;<br>);<br><br>export default SvgBin;</pre><p><em>Ohh yeah. </em>Well, I mean, this gets us part of the way there. But it doesn’t know anything about MUI, and it doesn’t respect any of MUI’s system/common styles, so the icons on the page still end up looking like Clifford the big red dog.</p><h4>The MUI-ification of S.V.G.</h4><p>I picked apart the @mui/icons-material project to look at the source of an icon—Delete.js (and its TypeScript counterpart Delete.d.ts) to see if I could figure out the de-facto way of making icons for MUI that behave themselves. But I discovered there’s a stark difference in implementation in the MUI library’s icons compared to what SVGR outputs: MUI is using native JavaScript to render the icon as <a href="https://facebook.github.io/jsx/">JSX</a>.</p><pre>&quot;use strict&quot;;<br><br>var _interopRequireDefault = require(&quot;@babel/runtime/helpers/interopRequireDefault&quot;);<br><br>Object.defineProperty(exports, &quot;__esModule&quot;, {<br>  value: true<br>});<br>exports.default = void 0;<br><br>var _createSvgIcon = _interopRequireDefault(require(&quot;./utils/createSvgIcon&quot;));<br><br>var _jsxRuntime = require(&quot;react/jsx-runtime&quot;);<br><br>var _default = (0, _createSvgIcon.default)( /*#__PURE__*/(0, _jsxRuntime.jsx)(&quot;path&quot;, {<br>  d: &quot;M6 19c0 1.1.9 2 2 2h8c1.1 0 2-.9 2-2V7H6v12zM19 4h-3.5l-1-1h-5l-1 1H5v2h14V4z&quot;<br>}), &#39;Delete&#39;);<br><br>exports.default = _default;</pre><p>That’s not really going to work very well for us. SVGR generates JSX from a template, and figuring out how to generate plain JavaScript from the SVGR template just to render JSX feels like an extra step (and challenge) nobody wants. One key thing I did notice in looking at the MUI icons is that the JSX it generates uses the &lt;SvgIcon&gt; component. That means in practice, what gets rendered shouldn’t be a whole lot different from our raw SVG. It looks like just the SVG dipped in some extra JavaScript/JSX sauce.</p><p>With a little luck, I was able to hand-craft a MUI-equivalent:</p><pre>import * as React from &quot;react&quot;;<br>import { SvgIcon, SvgIconProps } from &quot;@mui/material&quot;;<br>import { memo } from &quot;react&quot;;<br>const SvgBin = (props: SvgIconProps) =&gt; {<br>  const { sx, ...other } = props;<br>  return (<br>    &lt;SvgIcon <br>      xmlns=&quot;http://www.w3.org/2000/svg&quot;<br>      viewBox=&quot;0 0 24 24&quot;<br>      preservespectRatio=&quot;xMidYMid meet&quot; <br>      style={{<br>        fill: &quot;none&quot;,<br>      }}<br>      sx={sx}<br>      {...other}<br>    &gt;<br>      &lt;path d=&quot;...&quot; /&gt;<br>    &lt;/SvgIcon&gt;<br>  );<br>};<br>const Memo = memo(SvgBin);<br>export default Memo;</pre><p>We’ve got React and component imports, an &lt;SvgIcon&gt; component in place of &lt;svg&gt;, and some javascript destructuring/spread operator ({ ...}) props.</p><p>It works, but it’s a lot of work to write it by hand. Maybe there’s a better way?</p><p>SVGR uses templates—a bit of sorcery that uses a Babel plugin to read the SVG file and generate some JSX code—to determine what the output should look like. That means we should be able to pass the CLI tool a <a href="https://react-svgr.com/docs/custom-templates/#custom-component-template">custom template</a>, like this:</p><pre>npx @svgr/cli --template template.js -- my-icon.svg</pre><p>…and provided we can figure out how to customize it, we should be able to automate generating our MUI-compatible icon components.</p><p>The default SVGR output we saw earlier (generated using the default template) looks like this:</p><pre>const template = (variables, { tpl }) =&gt; {<br>  return tpl`<br>${variables.imports};<br><br>${variables.interfaces};<br><br>const ${variables.componentName} = (${variables.props}) =&gt; (<br>  ${variables.jsx}<br>);<br> <br>${variables.exports};<br>`<br>}<br><br>module.exports = template</pre><p>We’re missing some imports, a bunch of styling, and some MUI-specific props, but we’ve got a starting point at least, so buckle up…</p><h4>It’s time to make some templates</h4><p>And I do mean buckle up. The code I had to write to make this work seems hacky and a bit 🤮, but with little or no documentation (that I could find), I have no baseline to know what “the right way” to do this might have been.</p><blockquote>Shoutout to GitHub Copilot: one of the comments I wrote ACTUALLY OUTPUT THE EXACT SOLUTION I NEEDED. Saved my 🥓, it did.</blockquote><p>The first basic thing we want to do is replace the &lt;svg&gt; tag with &lt;SvgIcon&gt;.</p><blockquote>Apparently there’s an SVGR Babel plugin to do this (<a href="https://github.com/gregberge/svgr/blob/main/packages/babel-plugin-replace-jsx-attribute-value/README.md">@svgr/babel-plugin-replace-jsx-attribute-value</a>) but I couldn’t for the life of me figure out how to get this plugin to work with the CLI that wasn’t part of an existing Babel-based build chain. Instead, I took the dirty approach of inspecting the inbound JSX object and changing or adding values wherever I needed them.</blockquote><p>Inside my custom template, (don’t ask me how many times I had to console.dir(variables.jsx) to understand its schema) I tried setting the opening and closing elements’ name.name to SvgIcon and it worked! Instead of &lt;svg&gt;...&lt;/svg&gt;, we get &lt;SvgIcon&gt;...&lt;/SvgIcon&gt;.</p><pre>// Change the svg container to MUI&#39;s SvgIcon  variables.jsx.openingElement.name.name = &quot;SvgIcon&quot;;  variables.jsx.closingElement.name.name = &quot;SvgIcon&quot;;</pre><p>Next, while there’s a way to add attributes using the CLI tool (according to the documentation), it only seemed to work when I wasn’t loading a template. Instead, I just injected the attribute into the JSX object:</p><pre>// Add preserveAspectRatio=&quot;xMidYMid meet&quot; to the svg container  variables.jsx.openingElement.attributes.push({    <br>  type: &quot;JSXAttribute&quot;,    <br>  name: { type: &quot;JSXIdentifier&quot;, name: &quot;preserveAspectRatio&quot; },<br>  value: { type: &quot;StringLiteral&quot;, value: &quot;xMidYMid meet&quot; },  <br>});</pre><p>That works too! Nice, we’re on a roll.</p><p>Now I need to force some padding into the output for these particular icons, because the SVGs don’t have any top/bottom margin (unlike Material icons). To do that the MUI way in my hand-crafted example, I used the sx prop. We could just add in the changes we want to make…</p><pre>&lt;SvgIcon<br>  <em>xmlns=&quot;</em><a href="http://www.w3.org/2000/svg"><em>http://www.w3.org/2000/svg</em></a><em>&quot;<br>  viewBox=&quot;0 0 24 24&quot;<br>  preserveAspectRatio=&quot;xMidYMid meet&quot;</em><br>  <strong>sx={{ padding: &quot;2px&quot; }}</strong><br>&gt;</pre><p>But we actually want the developer using them to be able to pass in their own props and any other style attributes as well. To do that, we actually need to get clever with JavaScript’s spread operator—destructuring and restructuring props:</p><pre>const { sx, ...other } = props;<br>  return (<br>    &lt;SvgIcon<br>      <em>xmlns=&quot;</em><a href="http://www.w3.org/2000/svg"><em>http://www.w3.org/2000/svg</em></a><em>&quot;<br>      viewBox=&quot;0 0 24 24&quot;<br>      preserveAspectRatio=&quot;xMidYMid meet&quot;</em><br>      <strong>sx={{ ...sx, padding: &quot;2px&quot; }}<br>      {...other}</strong><br>    &gt;<br>    ...</pre><p>(This looks like a lot to digest if you’re not familiar with spread operators—we’re expanding <em>and</em> merging in both the incoming sx prop and any other props <em>into</em> the SvgIcon component).</p><p>One design decision I made here was to put the padding on the right, which means padding set by someone using the component will be overwritten by our <em>2px</em> version. That’s fine, I think, but if it became a problem we could always reverse them ({{ padding: &quot;2px&quot;, ...sx}}) later.</p><p>Now that we know what we want, how on earth are we going to get this into our JSX generator object?! It’s not like we can just add that as plain text (trust me, I tried). It actually has to be added as a subcomponent element, and it is UGLY. I tried everything to get this to work, looked for documentation, scoured Stack Overflow, but to no avail. In the end, Copilot magic got it to work (I’m still in awe) using a simple comment:</p><pre>// Append sx={{ ...sx, padding: &#39;2px&#39; }} to the JSXOpeningElement&#39;s attributes</pre><p>It didn’t actually get the whole thing, but it managed to get the padding completely right, so that was a great start:</p><pre>// Append sx={{ ...sx, padding: &#39;2px&#39; }} to the JSXOpeningElement&#39;s<br>// attributes<br> <br>variables.jsx.openingElement.attributes.push({<br>  type: &quot;JSXAttribute&quot;,<br>  name: { type: &quot;JSXIdentifier&quot;, name: &quot;sx&quot; },<br>  value: {<br>    type: &quot;JSXExpressionContainer&quot;,<br>    expression: {<br>      type: &quot;ObjectExpression&quot;,<br>      properties: [{<br>        type: &quot;ObjectProperty&quot;,<br>        key: { type: &quot;Identifier&quot;, name: &quot;padding&quot; },<br>        value: { type: &quot;StringLiteral&quot;, value: &quot;2px&quot; },<br>      }],<br>    },<br>  },<br>});</pre><p>Amazing! At least now I know how Objects can get added. Next I had to figure out the spread operator for ...other props anyway, so I tried:</p><pre>// Append a {...other} to the opening element&#39;s attributes</pre><p>And it gave me:</p><pre>variables.jsx.openingElement.attributes.push({<br>  type: &quot;JSXSpreadAttribute&quot;,<br>  argument: {<br>    type: &quot;Identifier&quot;,<br>    name: &quot;other&quot;,<br>  },<br>});</pre><p>😍 I can’t believe my eyes. It worked! Five 👏s for Copilot. I was now able to retrofit this into my previoussx object, too, with one minor tweak (I did find some Babel docs on SpreadElement):</p><pre>// Append sx={{ ...sx, padding: &#39;2px&#39; }} to the JSXOpeningElement&#39;s // attributes<br>variables.jsx.openingElement.attributes.push({<br>  type: &quot;JSXAttribute&quot;,<br>  name: { type: &quot;JSXIdentifier&quot;, name: &quot;sx&quot; },<br>  value: {<br>    type: &quot;JSXExpressionContainer&quot;,<br>    expression: {<br>      type: &quot;ObjectExpression&quot;,<br>      properties: [<br>        {<br>          type: &quot;SpreadElement&quot;,<br>          argument: {<br>            type: &quot;Identifier&quot;,<br>            name: &quot;sx&quot;,<br>          },<br>        },<br>        // ^ new block<br>        {<br>          type: &quot;ObjectProperty&quot;,<br>          key: { type: &quot;Identifier&quot;, name: &quot;padding&quot; },<br>          value: { type: &quot;StringLiteral&quot;, value: &quot;2px&quot; },<br>        },<br>      ],<br>    },<br>  },<br>});</pre><p>It looks pretty rough? I feel dirty writing it? Maybe I threw up a little in my mouth? But it works, and since it’s a manual process to run it, if it ever broke, at least it wouldn’t be on a production server somewhere and causing a catastrophic outage.</p><p>All together now, I can craft the template with my updated variables.jsx:</p><pre>return tpl`<br>// template: streamline-solid<br>import * as React from &quot;react&quot;;<br>import { SvgIcon, SvgIconProps } from &quot;@mui/material&quot;;<br>import { memo } from &quot;react&quot;;<br>const ${variables.componentName} = (props: SvgIconProps) =&gt; {<br>  const { sx, ...other } = props;<br>  return (<br>    ${variables.jsx}<br>  );<br>};<br> <br>${variables.exports};<br>`;<br>}</pre><p>Awesome!</p><h4>What about fancy SVG properties though, like stroke width and stuff?</h4><p>One final task I wanted to figure out is how I could handle multiple icon sets, one of which was a set of outline icons. SVGs can use a stroke width property to give outline icons a thickness:</p><pre>&lt;defs&gt;<br>  &lt;style&gt;<br>    {<br>      &quot;.bin_svg__a{fill:none;stroke:currentColor;stroke-linecap:round;stroke-linejoin:round;stroke-width:1.5px}&quot;<br>    }<br>  &lt;/style&gt;<br>&lt;/defs&gt;</pre><p>The stroke value I need to change is at the end: I want that 1.5px to be 2px! Easy enough? Uh, no. If I thought the previous code I had written was dirty, the hack for this made me feel like I needed a sonic shower at the highest setting.</p><p>The style child lives deeply in the JSX template object (and a bunch of children in children arrays). Not only do I not trust the path that it currently exists at, I especially don’t trust the syntax of the style string. It’s pretty obvious that these are semi-colon-separated key:value pairs, but who knows whether some might have a space in between, or some other junk… Rather than writing a parser (which is professionally the correct way to do this), I resorted to the infamy of regular expressions to solve my problem (now I have two problems?)</p><p>It works though, so bite me! 💀</p><blockquote>(I’m terribly sorry for formatting the nested objects like this, but the path is pure insanity, and Medium doesn’t make code blocks wide, so you get a very long block of code.)</blockquote><p>Pay close attention to my ? optional chaining usage here — this is a new (<em>finally!</em>) helper in JavaScript that lets us check the properties of an object deeply whose properties may or may not exist, without throwing Uncaught ReferenceError: _ is not defined everywhere.</p><pre>if (<br>  variables<br>  .jsx<br>  .children?.[0]<br>  .children?.[0]<br>  .openingElement<br>  .name<br>  .name === &quot;style&quot; &amp;&amp;<br>  variables<br>  .jsx<br>  .children?.[0]<br>  .children?.[0]<br>  .children?.[0]<br>  .expression?.value.length &gt; 0<br>) {<br>  // Replace &#39;stroke-width:__px&#39; with &#39;stroke-width:2px&#39;<br>  variables<br>  .jsx<br>  .children[0]<br>  .children[0]<br>  .children[0]<br>  .expression.value =<br>    variables<br>    .jsx<br>    .children[0]<br>    .children[0]<br>    .children[0]<br>    .expression<br>    .value.replace(<br>      /stroke-width:\s?[\d.]+px/g,<br>      &quot;stroke-width:2px&quot;<br>    );<br>}</pre><p>Seriously, get a load of those paths! Grateful for optional-chaining. And you’ll notice the crux of this is merely to replace stroke-width:2px:</p><pre>.value.replace(<br>  /stroke-width:\s?[\d.]+px/g, // That&#39;s a regex, folks<br>  &quot;stroke-width:2px&quot;<br>);</pre><p>Did it work? Yes, yes it did. Would I do it again? Yes, yes I would 🤔</p><h4>Try it out!</h4><p>If you enjoyed this journey, and you don’t like hard things and would rather someone did all the work making custom MUI icons for you (I kid, I kid), I put this all together on GitHub for you!</p><p>👉 <a href="https://github.com/brandonscript/mui-custom-svg-icons">https://github.com/brandonscript/mui-custom-svg-icons</a></p><p>And also, if you have a better way to do this, have thoughts, ideas, or <a href="https://stackoverflow.com/questions/71056440/using-svgr-cli-with-a-template-example-is-throwing-syntaxerror-cannot-use-imp">can make it work with ES6 </a><a href="https://stackoverflow.com/questions/71056440/using-svgr-cli-with-a-template-example-is-throwing-syntaxerror-cannot-use-imp">import and </a><a href="https://stackoverflow.com/questions/71056440/using-svgr-cli-with-a-template-example-is-throwing-syntaxerror-cannot-use-imp">export</a>, drop me a PR in the repo!</p><p><em>fin<br></em> — B</p><blockquote><em>read more long-form at </em><a href="https://brandonscript.design/"><em>brandonscript.design</em></a><em><br>follow me on </em><a href="https://twitter.com/brandonscript"><em>Twitter</em></a><em>, </em><a href="https://polywork.com/brandonscript"><em>Polywork</em></a><em>, or </em><a href="https://linkedin.com/in/brandonscript"><em>LinkedIn</em></a></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d0e388d93feb" width="1" height="1" alt=""><hr><p><a href="https://brandonscript.design/creating-a-custom-icon-generator-for-mui-d0e388d93feb">Creating a custom icon generator for MUI</a> was originally published in <a href="https://brandonscript.design/">UX &amp; Code | opinions &amp; scribbles</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[It’s not enough to know what the future ​is, you have to know what it means ]]></title>
            <link>https://brandonscript.design/its-not-enough-to-know-what-the-future-is-you-have-to-know-what-it-means-c96ceeb57eec?source=rss-16b233cf1ec5------2</link>
            <guid isPermaLink="false">https://medium.com/p/c96ceeb57eec</guid>
            <category><![CDATA[design]]></category>
            <category><![CDATA[new-job]]></category>
            <category><![CDATA[ux]]></category>
            <dc:creator><![CDATA[Brandon S.]]></dc:creator>
            <pubDate>Sun, 30 Jan 2022 05:42:56 GMT</pubDate>
            <atom:updated>2022-01-30T05:42:56.714Z</atom:updated>
            <content:encoded><![CDATA[<p>And of course, all good things must come to an end. After more than 8 years tackling APIs and digital transformation at Apigee + Google, Friday, January 28th 2022 marked my last day. To my friends I’ve said goodbye to: I’ll always be an Apigeek at heart; we’ve built some amazing things together, and I’ll be rooting for you from the sidelines!</p><p>I’m so excited to announce that I’ll be joining a brand new shiny startup, <a href="http://delving.com/">Delving</a>, in February. I’ll be tackling some super cool new product challenges, and while I can’t say much yet (we’re in a very early stealthy discovery phase), I can say that I am <em>stoked</em> for what we’re working on! Stay tuned, and if you love spreadsheets, come say hello 👋</p><p>—B</p><p><em>follow me on </em><a href="https://twitter.com/brandonscript"><em>Twitter</em></a><em>, </em><a href="https://polywork.com/brandonscript"><em>Polywork</em></a><em>, or </em><a href="https://linkedin.com/in/brandonscript"><em>LinkedIn</em></a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-nXG8sMs8-3NIHfiVkzUBQ.jpeg" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c96ceeb57eec" width="1" height="1" alt=""><hr><p><a href="https://brandonscript.design/its-not-enough-to-know-what-the-future-is-you-have-to-know-what-it-means-c96ceeb57eec">It’s not enough to know what the future ​is, you have to know what it means 🚀</a> was originally published in <a href="https://brandonscript.design/">UX &amp; Code | opinions &amp; scribbles</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The mysterious case of the disappearance of MUI’s makeStyles()]]></title>
            <link>https://brandonscript.design/the-mysterious-case-of-the-disappearance-of-muis-makestyles-9515a58eb9f8?source=rss-16b233cf1ec5------2</link>
            <guid isPermaLink="false">https://medium.com/p/9515a58eb9f8</guid>
            <category><![CDATA[react]]></category>
            <category><![CDATA[ux]]></category>
            <category><![CDATA[css]]></category>
            <category><![CDATA[design]]></category>
            <category><![CDATA[material-ui]]></category>
            <dc:creator><![CDATA[Brandon S.]]></dc:creator>
            <pubDate>Mon, 15 Nov 2021 21:25:42 GMT</pubDate>
            <atom:updated>2023-02-08T21:05:42.366Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="A Material UI whodunnit, a la Knives Out" src="https://cdn-images-1.medium.com/max/683/1*F3h_6v5WSrE86xqsH1IEPQ.png" /></figure><p>A tale of intrigue, CSS, and suspense — a sensational uncovering of a legacy deprecation that will keep you on the edge of your seat.</p><h3>Prologue</h3><p>If you’re like me, you might be a tired and old <a href="https://twitter.com/tartanllama/status/1459212193375870976?s=21">web2 boomer</a> who doesn’t want to make new design systems or component libraries for every new project anymore. It is with this in mind that I find myself truly appreciating the power and effort behind general use component/style libraries, and it is through my use of a recent major update of one in particular that prompted some reflection and critical thinking into how it could be improved even further.</p><p>(If you’re not like me, and you really like rolling your own CSS or you like the pedantry that is <a href="https://tailwindcss.com/">Tailwind CSS</a>, then perhaps you will read about this with less enthusiasm than I would otherwise command).</p><p><em>Also, if you’re like me, and you both ❤️ tl;dr and want to start at the end, </em><a href="#ae79"><em>skip to Act III</em></a><em> for some ideas for the MUI team.</em></p><p><em>Update: This is now a GitHub issue. </em><a href="https://github.com/mui-org/material-ui/issues/29816"><em>Head over there</em></a><em> if you have an opinion you want to share.</em></p><p><em>Yet another update, circa 2023: MUI v5 now supports </em><em>unstable_sx directly in </em><em>styled()! There is now a short story at the end of this one to show you how to use it. Head down to the </em><a href="#1d87"><em>Epilogue</em></a><em>!</em></p><h3>Act I — A murder</h3><p><a href="https://material.io/">Material Design</a>, Google’s famed design system, has a very well-built React implementation called <em>Material UI</em>, or <a href="https://mui.com/"><em>MUI</em></a> for short. It self proclaims itself to be “The React UI library you always wanted”. This is, in fact true. In its latest version, <a href="https://mui.com/blog/mui-core-v5/">5.0</a>, we have been gifted a beautifully flexible component library with great style and design principles out-of-the-box. It is dead simple to customize, and is built upon some well-designed APIs that encourage clear, concise, semantic declarations of style. Not only is it powerful, but it’s opinionated—in a good way—and ridiculously easy to use.</p><p>All except, of course, makeStyles(). And that, I suppose, is why makeStyles() found itself the victim of <a href="https://mui.com/styles/basics/#hook-api">murder</a>. Not the sort of <a href="https://killedbygoogle.com/">murder you’d expect from Google</a> mind you, because MUI is neither a Google product, nor is it endorsed by them, but nevertheless, we find makeStyles() has been deadprecated.</p><p>To understand this murder and the motive, we should probably start at the beginning.</p><p>makeStyles() is (was?) the principal means of styling components in a reusable way, just like CSS classes do. Like CSS, it allows you to create named classes that can be assigned to React JSX components, just as one would do for plain HTML. It uses a syntax called <em>CSS-in-JS</em> (or <a href="https://cssinjs.org/?v=v10.8.2">JSS</a>) which is just a JavaScript-friendly way of writing styles that compile into actual browser-readable CSS.</p><p>Though deprecated, you can still use makeStyles() in MUI 5, but we expect it (to be removed in v6, but hence my confusion between past and present tense).</p><p>Consider a plain CSS/HTML example:</p><pre>&lt;style&gt;<br>.box {<br>  display: flex;<br>  flex-direction: row; <br>  flex-basis: min-content;<br>}<br>&lt;/style&gt;<br><br>&lt;div class=&quot;box&quot;&gt;<br>  &lt;p&gt;You are very amiable, no doubt, but you would be charming if you would only depart.&lt;/p&gt;<br>  &lt;p&gt;Love is the most selfish of all the passions.&lt;/p&gt;<br>  &lt;a href=&quot;https://www.goodreads.com/work/quotes/1263212-les-trois-mousquetaires&quot;&gt;Source&lt;/a&gt;<br>&lt;/div&gt;</pre><p>If we wrote this as a React component using MUI’s makeStyles(), we’d make it more/less like this:</p><pre>// A React component styled with MUI<br><br>import { styled, Theme, createStyles } from &#39;@mui/material/styles&#39;<br>import { makeStyles } from &#39;@mui/styles&#39;<br>import { Box, Typography, Button } from &#39;@mui/material&#39;<br><br>// Style<br>const useStyles: any = makeStyles((theme: Theme) =&gt;<br>  createStyles({<br>    box: {<br>      // ^ Here&#39;s the CSS class name-we&#39;re writing CSS-in-JS<br>      display: &#39;flex&#39;,<br>      flexDirection: &#39;row&#39;,<br>      // ^ Notice the camelCase and &#39;&#39;? This is a .js object.<br>      flexBasis: &#39;min-content&#39;,<br>    },<br>  })<br>)<br><br>// Component<br>export default function Quotes() {<br>  return (<br>    &lt;Box className=&quot;box&quot;&gt;<br>      {/* ^ Here&#39;s where we apply our class */}<br>      &lt;Typography&gt;<br>        You are very amiable, no doubt, but you would be charming if you would<br>        only depart.<br>      &lt;/Typography&gt;<br>      &lt;Typography&gt;Love is the most selfish of all the passions.&lt;/Typography&gt;<br>      &lt;Button href=&quot;https://www.goodreads.com/work/quotes/1263212-les-trois-mousquetaires&quot;&gt;<br>        Source<br>      &lt;/Button&gt;<br>    &lt;/Box&gt;<br>  )<br>}</pre><p>If you’re familiar with React and <a href="https://reactjs.org/docs/introducing-jsx.html">JSX</a>, this should look straightforward. (If you’re not, uh, well, maybe you should pause reading here because you might get a little lost?)</p><p>But for a reason that I’m sure exists and is good and I’m just not aware of, MUI decided to remove its dependency on JSS, and therefore will no longer support the makeStyles() way of styling components. Thankfully MUI 5 has introduced a couple of crafty ways of getting the job done. In particular, the shorthand syntax for writing inline styles is really easy to write <em>and</em> read.</p><p>Enter <a href="https://mui.com/system/styled/">styled()</a> and my coveted new love interest, <a href="https://mui.com/system/the-sx-prop/">the sx prop</a>.</p><h3>Act II — An heir to the throne</h3><p>Let’s take a look at the cool things we can do with styled() and sx. To start with, we can now apply inline styles to any MUI component we want, on the fly, with sx. Under the hood, it’s even theme-aware, so we can use shorthand notation to grab anything we want from our theme. Keep in mind that styled&#39;s shorthand syntax is a superset of CSS, which means that any standard CSS property still works, the shorthand is just an optional, more concise way of declaring styles.</p><blockquote><em>Did you know? </em>The default style library used for generating CSS styles for MUI components is <a href="https://github.com/emotion-js/emotion">emotion</a>. All of the MUI components rely on the styled() API to inject CSS into the page. This API is supported by multiple popular styling libraries, which makes it possible to switch between them in MUI. <a href="https://mui.com/guides/styled-engine/">More…</a></blockquote><h4>The sx prop</h4><p>If you’re not familiar with how sx works, you might check out the basics doc first, because I might be speeding off ahead and this could get very confusing! 👉 <a href="https://mui.com/system/basics/#all-inclusive">https://mui.com/system/basics/#all-inclusive</a></p><p>Here’s a super basic example of how we can use sx to add inline styles to our components. Pretty powerful stuff!</p><pre>// A basic example of using the sx prop for inline styles<br><br>import { Box, Typography, Button } from &#39;@mui/material&#39;<br><br>export default function Quotes() {<br>  return (<br>    &lt;Box sx={{<br>        display: &#39;flex&#39;,<br>        flexDirection: &#39;row&#39;,<br>        flexBasis: &#39;min-content&#39;,<br>        padding: 2,<br>            { /* ^ Yep! That&#39;s theme-aware shorthand for theme.spacing(2) */}<br>      }}&gt;<br>      {/* ^ Here&#39;s where we apply our class */}<br>      &lt;Typography sx={{color: &#39;text.primary&#39;}}&gt;<br>                           {/* ^ Let&#39;s use a theme color! */}<br>        You are very amiable, no doubt, but you would be charming if you would<br>        only depart.<br>      &lt;/Typography&gt;<br>      &lt;Typography&gt;Love is the most selfish of all the passions.&lt;/Typography&gt;<br>      &lt;Button<br>        sx={{paddingX: 2}}<br>           {/* ^ Neato, that&#39;s theme-aware and does padding on both sides */}<br>        href=&quot;https://www.goodreads.com/work/quotes/1263212-les-trois-mousquetaires&quot;&gt;<br>        Source<br>      &lt;/Button&gt;<br>    &lt;/Box&gt;<br>  )<br>}</pre><p>You can also do some really awesome responsive stuff with sx that was difficult to read and write with makeStyles():</p><pre>// Before — with makeStyles<br>const useStyles: any = makeStyles((theme: Theme) =&gt;<br>  createStyles({<br>    content: {<br>      [theme.breakpoints.up(&#39;sm&#39;)]: {<br>        marginLeft: theme.spacing(4), // Yikes, that&#39;s some syntax.<br>      },<br>      [theme.breakpoints.only(&#39;sx&#39;)]: {<br>        marginLeft: theme.spacing(2),<br>      },<br>    },<br>  })<br>);<br><br>// After — with sx, amazing!<br>export default function Words() {<br>  return (<br>    &lt;Box sx={{ <br>        marginLeft: { <br>          xs: 2, <br>          sm: 4 <br>        }<br>      {/* ^ Whoa! check out those breakpoints. The smallest size takes precedence,<br>          so &#39;sm&#39; implies all sm and larger screens. */}<br> }}&gt;<br>      &lt;Typography&gt;Hello words.&lt;/Typography&gt;<br>    &lt;/Box&gt;<br>  )<br>}</pre><p>If that excites you, as it does me, you can go read about all the cool theme-aware props and shorthand for sx <a href="https://mui.com/system/the-sx-prop/">here</a>.</p><h4>Theming</h4><p>Now of course, that’s cool and all, but um, we don’t all want to use inline styles all the time, right 👀? The entire purpose of CSS is that it is <em>cascading—</em>written generally and reusable at the top, then refined toward <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity">specificity</a> for exceptions.</p><p>For truly global styling and theming, we can (and should) define these things at the <a href="https://mui.com/customization/theming/">theme</a> level (where you would ideally define your design tokens). Do all your buttons have rounded corners? What is your color palette? To customize these, you’d do something like this:</p><pre>// Creating a theme<br><br>import { createTheme } from &#39;@mui/material/styles&#39;<br><br>const baseTheme = createTheme({<br>  palette: {<br>    primary: {<br>      main: &#39;#0052cc&#39;,<br>    },<br>    secondary: {<br>      main: &#39;#edf2ff&#39;,<br>    },<br>  },<br>})<br><br>// We can nest themes to layer them or use base theme styles<br>const theme = createTheme(baseTheme, <br>  palette: {<br>    info: {<br>      main: baseTheme.palette.secondary.main,<br>    },<br>  },<br>})</pre><p>You might also want to add a custom variant to an existing MUI component class. (<em>Note</em>: this example is for Typescript, so it includes some extra .ts stuff):</p><pre>// Adding a new variant to the MuiButton class using <br>// Typescript, and passing a global theme object to a child<br><br>import { createTheme, Theme } from &#39;@mui/material/styles&#39;<br>import { alpha } from &#39;@mui/material/styles&#39;<br><br>declare module &#39;@mui/material/Button&#39; {<br>  interface ButtonPropsVariantOverrides {<br>    light: true<br>    // ^ Here we have to declare the variant as an override<br>  }<br>}<br><br>// To make things a little cleaner and reusable, we can <br>// make a base theme object<br>const baseTheme: Theme = createTheme({<br>  palette: {<br>    primary: {<br>      main: &#39;#313131&#39;,<br>      light: &#39;#ffffff&#39;,<br>      // ^ We add a new color palette for &#39;light&#39;<br>    },<br>    secondary: {<br>      main: &#39;#dfa888&#39;,<br>      light: &#39;#ffffff&#39;,<br>    },<br>  },<br>})<br><br>// Then we can splice in our global theme and export the composite<br>export const theme: Theme = createTheme({<br>  palette: baseTheme.palette,<br>  typography: {<br>    fontFamily: &#39;Lato&#39;,<br>  },<br>  components: {<br>    MuiButton: {<br>      variants: [<br>        {<br>          // And declare our new variant and its unique styles<br>          props: { variant: &#39;light&#39;, color: &#39;primary&#39; },<br>          style: {<br>            backgroundColor: baseTheme.palette.primary.light,<br>            color: baseTheme.palette.primary.main,<br>            &#39;&amp;:hover&#39;: {<br>              backgroundColor: alpha(baseTheme.palette.primary.light, 0.74),<br>              &#39;&amp;:active&#39;: {<br>                backgroundColor: alpha(baseTheme.palette.primary.light, 0.62),<br>              },<br>            },<br>          },<br>        },<br>      ],<br>    },<br>  },<br>})</pre><p>To use these globally, you would just wrap your app or a generic page layout container with &lt;ThemeProvider&gt; and magically all your app’s components will use your theme’s styles. You can also take advantage of theuseTheme() hook (make sure it is exported from @mui/material) in any React functional component.</p><p>To be fair, none of this is dramatically different in MUI 5 compared to v4, but if you’re new to the framework it’s important to understand how theming works.</p><h4>What lies in the shadows between “theme” and “sx”?</h4><p>Indeed, there are some gaps in my coverage here that you probably already noticed, and have patiently been waiting for me to get on with it.</p><ul><li><strong>How do we create reusable components with portable styles and props? </strong>We used to do this with makeStyles() but now we can’t/shouldn’t?</li><li><strong>Where do we define other non-theme global styles?</strong> Maybe some utility classes like text or flexbox alignment, or reusable styles you want to be present throughout your app?</li><li><strong>How do we create reusable styles within a component?</strong> sx is cool, but no one wants to copy and paste a bunch of inline styles all over the place, right?</li></ul><p>The new MUI 5 way of accomplishing most of these is by using styled() to wrap reusable components. (<em>Note</em>: there are a bunch of other props you can define on a styled component, but I’ve kept these examples simple to make them easy to read. If you’re keen, you can read all about them in the <a href="https://mui.com/system/styled/">MUI docs</a>.)</p><p>styled() works by passing a component and a style as arguments, which then returns a styled version of that component. In this example, I’m passing a Slider MUI component, but you could also pass in a string like &#39;div&#39; to use any HTML entity.</p><p>There two ways you can do this: though it’s a little cumbersome, you can pass a multi-line string as an argument…</p><pre>import * as React from &#39;react&#39;<br>import Slider from &#39;@mui/material/Slider&#39;<br>import { styled } from &#39;@mui/material/styles&#39;<br><br>const CustomizedSlider = styled(Slider)`<br>  color: #20b2aa;<br>  fontSize: 500,<br>  :hover { <br>    color: #2e8b57; <br>  }<br>`<br><br>const function MySlider() {<br>  return &lt;CustomizedSlider defaultValue={30} /&gt;<br>}<br><br>export default MySlider</pre><p>Or you can pass in a theme object as an argument. This one’s slightly easier to write vs. the multi-line string method, but it does involve a few more nested brackets:</p><pre>// App.ts (or your main app component)<br>import * as React from &#39;react&#39;<br>import { ThemeProvider } from &#39;@mui/system&#39;<br>import { theme } from &#39;styles/customTheme.ts&#39;<br><br>export default function MyApp() {<br>  return (<br>    &lt;ThemeProvider theme={customTheme}&gt;<br>      &lt;MyThemeComponent&gt;Styled Box with theme&lt;/MyThemeComponent&gt;<br>    &lt;/ThemeProvider&gt;<br>  )<br>}<br><br>// MyStyledBox.tsx<br>import * as React from &#39;react&#39;<br>import { Box, styled } from &#39;@mui/material&#39;<br><br>export const MyStyledBox = styled(Box)(({ theme }) =&gt; ({<br>  color: theme.palette.primary.contrastText,<br>  backgroundColor: theme.palette.primary.main,<br>  padding: theme.spacing(1),<br>  borderRadius: theme.shape.borderRadius,<br>}));</pre><p>Neither of these are as syntactically elegant as sx though—we really start to feel the loss of its power, fidelity, and brevity. Now we have to remember to load the right theme, call things like theme.spacing() instead of just passing a number, and we lose the ability to define breakpoints like we can with sx. (And to make matters worse, it seems the compiler doesn’t catch it as an error if you try to write sx syntax, it just fails silently).</p><p><strong>But why </strong>should we use styled() in place of just directly using sx everywhere? Emotion will create a single class for all instances of the styled() component, instead of a separate class for each instance. This can make a big difference in terms of stylesheet optimization. So there is a definite trade-off.</p><p>There’s also the context switching — if you’re writing both theme styles and inline sx styles, you’re going to have trouble remembering which syntax to use where, and that will inevitably lead to mistakes (ask me how I know).</p><blockquote>Author’s note: the following suggestions are outdated as of 2023 — since writing this, the sx style engine has been exposed through the theme provider and styled(), so now we get the best of both worlds! Skip to the next section for details.</blockquote><p>And we also still have the problem of style reusability? What if I wanted some global app-level utility styles? Or even to reuse the same style on different components as I did previously with makeStyles() and the className prop?</p><p>This was a hot problem for me to figure out. There are three ways I’ve ended up doing it, but I can in no way promise that these are right, recommended, or performant. So take this with a grain of 🧂.</p><p><strong>Option 1</strong>: Add a custom style property to a theme object and using the spread operator (...), mix it into the rest of your style. I don’t mind this, but it doesn’t quite <em>feel</em> the same as adding a class to your component, because we never use the className prop. It also doesn’t know anything about the class name you’ve given it, so the generated HTML on the page never includes it in the class tag. (To be fair, naming things is hard, and the MUI docs cite this as one of the reasons to do away with using named classes). There is a secret way to do this using the name and slot props, but it feels like an afterthought—it’s barely a footnote in the MUI docs.</p><p>You also have to <a href="https://medium.com/@kevinlai76/the-spread-operator-deep-and-shallow-copies-d193ac9b58bf">be careful with the spread operator and deep copies</a>. Depending on what you’re doing, you might be better off using deepmerge here instead: import { deepmerge } from &#39;@mui/utils&#39;.</p><p>And… for what it’s worth, even though spread/deepmerge are functionally fine, they’re not very idiomatic.</p><pre>// Option 1: A reusable theme object mixed in via the spread operator<br><br>import * as React from &#39;react&#39;<br>import { styled, createTheme, ThemeProvider } from &#39;@mui/system&#39;<br>import { Box } from &#39;@mui/material&#39;<br><br>const customTheme = createTheme({<br>  palette: {<br>    primary: {<br>      main: &#39;#1976d2&#39;,<br>      contrastText: &#39;white&#39;,<br>    },<br>  },<br>  styles: {<br>  // Keep in mind that TypeScript will be mad at you <br>  // for extending the Theme interface, though.<br>    flexCenter: {<br>      display: &#39;flex&#39;,<br>      alignItems: &#39;center&#39;, <br>      justifyContent: &#39;center&#39;,<br>      flexBasis: &#39;fit-content&#39;,<br>    }<br>  }<br>})<br><br>const MyThemeComponent = styled(Box)(({ theme }) =&gt; ({<br>  ...theme.flexCenter,<br>  // ^ Using a spread operator is a neat trick.<br>  color: theme.palette.primary.contrastText,<br>  backgroundColor: theme.palette.primary.main,<br>  padding: theme.spacing(1),<br>  borderRadius: theme.shape.borderRadius,<br>}))<br><br>export default function ThemeUsage() {<br>  return (<br>    &lt;ThemeProvider theme={customTheme}&gt;<br>      &lt;MyThemeComponent&gt;Styled Box with theme&lt;/MyThemeComponent&gt;<br>    &lt;/ThemeProvider&gt;<br>  )<br>}</pre><p><strong>Option 2</strong>: Create a higher scoped variable and reference it from the sx property . The upside to this is it’s fast and we can use the power of sx again (🥳), but the downsides are that we can’t do it globally—it only works in your local component file (unless we made a separate module… maybe?), and the generated code will make a copy of the style for each of the sx references.</p><pre>// Option 2: Defining sx in a variable<br><br>import * as React from &#39;react&#39;<br>import { styled, createTheme, ThemeProvider } from &#39;@mui/system&#39;<br>import { Box } from &#39;@mui/material&#39;<br><br>const customTheme = createTheme({ /* ... */ })<br><br>const flexCenter = {<br>  display: &#39;flex&#39;,<br>  alignItems: &#39;center&#39;, <br>  justifyContent: &#39;center&#39;,<br>}<br><br>const MyThemeComponent = styled(Box)(({ theme }) =&gt; ({ /* ... */ }))<br><br>export default function ThemeUsage() {<br>  return (<br>    &lt;ThemeProvider theme={customTheme}&gt;<br>      &lt;MyThemeComponent <br>        sx={{...flexCenter}}&gt;Styled Box with theme<br>        {/*    ^ this is bad for many reasons: not<br>                 only can it end up causing re-renders<br>                (if you declare it inside a component),<br>                but we end up with a new CSS class for<br>                each instance anyway.<br>        /*}<br>      &lt;/MyThemeComponent&gt;<br>    &lt;/ThemeProvider&gt;<br>  )<br>}</pre><p><strong>Option 3</strong>: Use an <a href="https://mui.com/guides/interoperability/#plain-css">external CSS file</a>. You just do an import &#39;./MyCustomStyles.css&#39; as you would any other React component, then use your component with className as you did with makeStyles(). I’m not sure I like this, though:</p><ul><li>Adding an external stylesheet means you (probably) end up with a separate build step to manage your plain CSS. You might lose TypeScript validation checking fidelity here (e.g., a typo in your .css file might appear to be valid in your React component’s className prop), and more moving parts means more things that could go wrong.</li><li>You break the opinionated model of React components and the MUI system, which could lead to a bunch of weird problems that are difficult to troubleshoot. External styles <a href="https://mui.com/guides/interoperability/#css-injection-order-3">load in a different order</a>, so you’ll spend your time wondering why styles aren’t applying, or why others are clobbering things you didn’t intend them to. There’s also the namespace conflict and collision risk.</li><li>Styling the component HTML for MUI components is tough. They often contain multiple nested elements, with weird names like .MuiSlider-thumb, and you’ll have to figure out what they all are. Difficult to maintain, difficult to write.</li></ul><p><strong>Option ?</strong>: MUI’s style system is based on <a href="https://emotion.sh/docs/styled">Emotion</a>, so it’s entirely possible that I’ve overlooked a better way of doing this. But I don’t know Emotion very well, and I haven’t dug into the MUI code to understand just how styled() wraps around it, so I’m at a disadvantage. Know something I don’t? Is there a golden-ticket way of doing this? <a href="https://twitter.com/brandonscript">Tweet at me</a> or leave a comment! <em>(Update, 2023: I know a lot more about Emotion and MUI now, so check out the epilogue. Also, it’s 2023, do not tweet — </em><a href="https://appdot.net/@brandonscript">toot</a><em> instead.)</em></p><h3>Act III — A new hope</h3><p>From the ashes of the dead, would a new (stylish) hero rise up and destroy the scourge of ambiguity? That hero of our journey could besx! What if there were a way to use thesx syntax everywhere? Of course, its API would have to make logical sense alongside the rest of the MUI platform, and it would have to scale well, and be performant. Bonus points if we supported class names through name and slot (albeit this nomenclature is particularly off-putting).</p><p>Why?</p><ul><li>sx is awesome, and I love it.</li><li>I don’t want to context switch. I want to know that whatever styles I’m writing are all using the same superset of CSS so that there’s no chance of getting confused.</li><li>I want linting to work everywhere. If I write an sx style block in a theme declaration, the system should be able to tell me if I made a mistake. (Maybe less relevant for .js, but definitely for .ts).</li><li>Naming things doesn’t always matter, but it’s often helpful for debugging styles, and coming from a plain HTML/CSS background, not using identifiable class names feels like a loss?</li><li>MUI is opinionated about a lot of things, but how to declare global styles and utility classes doesn’t seem to be one of them. We should fix that.</li><li>I don’t understand the performance implications of the myriad ways of putting styles into an app. Are some better than others? Probably—and I’d rather the system just told me what to do, rather than me having to think about it.</li></ul><p>I have three ideas of what this might look like, though I offer them up with a caveat: because I’m not very familiar with the MUI project or its working group, I may be wildly out to lunch. But that’s OK. If nothing else, you, the real hero of this story, will understand this pain, too.</p><p>If these can spark a discussion that informs some changes, then I’ll be happy!</p><h4>Idea 1</h4><p>A new hook like makeStyles() that uses the sx superset.</p><pre>// Idea 1: A New Hope<br><br>import * as React from &#39;react&#39;<br>import { styled } from &#39;@mui/system&#39;<br><br>const useStyles = styled.sx({<br>  flexCenter: {<br>    display: &#39;flex&#39;,<br>    alignItems: &#39;center&#39;, <br>    justifyContent: &#39;center&#39;,<br>    flexBasis: &#39;fit-content&#39;,<br>    flexDirection: {<br>      xs: &#39;column&#39;,<br>      sm: &#39;row&#39;,<br>    }<br>  }<br>})<br><br>export default function MyComponent(props) {<br>  const classes = useStyles(props)<br>  return &lt;div className={classes.flexCenter} /&gt;<br>}</pre><h4>Idea 2</h4><p>Support all of the sx superset in theme objects.</p><pre>// Idea 2: The Empire Styles Back<br><br>import * as React from &#39;react&#39;<br>import { styled, createTheme, ThemeProvider } from &#39;@mui/system&#39;<br><br>const MyThemeComponent = styled(&#39;div&#39;)(({ theme }) =&gt; ({<br>  color: &#39;primary.contrastText&#39;,<br>  backgroundColor: &#39;primary.main&#39;,<br>  paddingX: { <br>    xs: 1,<br>    sm: 2,<br>    md: 3,<br>  },<br>  borderRadius: theme.shape.borderRadius,<br>}))<br><br>export default function ThemeUsage() {<br>  return (<br>    &lt;ThemeProvider theme={customTheme}&gt;<br>      &lt;MyThemeComponent&gt;Styled div with theme&lt;/MyThemeComponent&gt;<br>    &lt;/ThemeProvider&gt;<br>  )<br>}</pre><h4><strong>Idea 3</strong></h4><p>Create a wrapper or dedicated section in a theme to support utility or global classes.</p><pre>// Idea 3: Return of the sx<br><br>import { createTheme, styled } from &#39;@mui/material/styles&#39;<br><br>let theme = createTheme({<br>  shape: {<br>    borderRadius: 4,<br>  },<br>})<br><br>theme = createTheme(theme, {<br>  classes: styled.sx({<br>    flexCenter: {<br>      display: &#39;flex&#39;,<br>      alignItems: &#39;center&#39;,<br>      justifyContent: &#39;center&#39;,<br>      flexBasis: &#39;fit-content&#39;,<br>      flexDirection: {<br>        xs: &#39;column&#39;,<br>        sm: &#39;row&#39;,<br>      }<br>    },<br>    makeItRound: {<br>      borderRadius: theme.shape.borderRadius,<br>    })<br>  },<br>})</pre><h3>Epilogue</h3><p>Thanks for unboxing this murder mystery with me. It’s been a lot of fun exploring MUI 5’s changes over the last little while, and all in all, I think the direction the framework is taking is <em>great! </em>Despite my criticisms, I think moving away from makeStyles() was the right call. But now I just want sx to be everywhere, because I love it! And more than anything, the ambiguity of how to write styles in all sorts of different ways is what gets me. For a library that is opinionated in all the right ways, it should be here, too.</p><p>And I’ll leave you with an [action requested]: maybe you’ve got an idea too? If so, toss it my way — I’d love to chat about it more.</p><figure><img alt="An illustration of R2D2, the real hero of Star Wars." src="https://cdn-images-1.medium.com/max/256/1*yYnlIaICZSZCJT-Yw7GFrw.png" /><figcaption>R2D2, the real hero of the story</figcaption></figure><p>The year is 2023, and we now have a great way to use the power of sx with the reusability of styled(), thanks to the hardworking MUI team. You can just call the unstable_sx() method directly from the exposed theme prop:</p><pre>const PageLoadOverlay = styled(FlexBox, {<br>  shouldForwardProp: (prop) =&gt; ![&quot;opacity&quot;].includes(prop as string),<br>})&lt;PageLoadOverlayProps&gt;(({ theme, opacity = 1 }) =&gt;<br>  theme.unstable_sx({<br>    position: &quot;fixed&quot;,<br>    top: 0,<br>    left: 0,<br>    right: 0,<br>    bottom: 0,<br>    zIndex: 1300,<br>    backgroundColor: &quot;white&quot;,<br>    opacity,<br>    transition: theme.transitions.create(&quot;opacity&quot;, {<br>      duration: theme.transitions.duration.standard,<br>    }),<br>  })<br>);<br><br>const DenseAccordionDetails = styled(AccordionDetails)(({ theme }) =&gt;<br>  theme.unstable_sx({<br>    &quot;&amp;.MuiAccordionDetails-root&quot;: {<br>    // ^ We can even use the &amp; extender key now to auto-inherit classes!<br>      padding: 0,<br>      mb: 0.5, // &lt;- That uses theme.spacing() automatically, so == 8px<br>    },<br>  })<br>);<br><br>const DenseList = styled(List)(({ theme }) =&gt; ({<br>  padding: 0,<br>  &quot;&amp;.MuiList-root&quot;: {<br>  // ^ It works without unstable_sx, too.<br>    padding: 0,<br>  },<br>}));</pre><p><em>fin<br></em> — B</p><blockquote><em>read more long-form at </em><a href="https://brandonscript.design/"><em>brandonscript.design</em></a><em><br>follow me on </em><a href="https://appdot.net/@brandonscript"><em>Mastodon</em></a><em> or </em><a href="https://linkedin.com/in/brandonscript"><em>LinkedIn</em></a><em><br>work with me at </em><a href="https://pacificaviator.co/"><em>pacificaviator.co</em></a></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9515a58eb9f8" width="1" height="1" alt=""><hr><p><a href="https://brandonscript.design/the-mysterious-case-of-the-disappearance-of-muis-makestyles-9515a58eb9f8">The mysterious case of the disappearance of MUI’s makeStyles()</a> was originally published in <a href="https://brandonscript.design/">UX &amp; Code | opinions &amp; scribbles</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[What if Figma adopted flexbox & CSS grid in auto-layout?]]></title>
            <link>https://brandonscript.design/what-if-figma-adopted-flexbox-css-grid-in-auto-layout-be6621e7af75?source=rss-16b233cf1ec5------2</link>
            <guid isPermaLink="false">https://medium.com/p/be6621e7af75</guid>
            <category><![CDATA[ux]]></category>
            <category><![CDATA[css-grid]]></category>
            <category><![CDATA[ux-design]]></category>
            <category><![CDATA[css]]></category>
            <category><![CDATA[figma]]></category>
            <dc:creator><![CDATA[Brandon S.]]></dc:creator>
            <pubDate>Wed, 03 Nov 2021 17:09:29 GMT</pubDate>
            <atom:updated>2021-11-20T13:32:54.421Z</atom:updated>
            <content:encoded><![CDATA[<h3>The frustration, a.k.a. user “pain”</h3><p><em>Love this feature idea but don’t like reading lots of words? Voting is now closed, but if you know someone at Figma who would champion the idea, let them know! (Here’s the original forum </em><a href="https://forum.figma.com/t/adopting-css-grid-and-flexbox-in-auto-layout/9167"><em>post</em></a><em>).</em></p><p>A short while ago I was trying to create some table rows with centered icons (and maybe some horizontal padding) in <a href="https://figma.com/">Figma</a>. Then I wanted the text to flex-grow to fit the available space, aligned left, so that this “column” would be as wide as the cell with the longest text. Of course, this came out looking something like this:</p><figure><img alt="An example of auto-layout funkiness in Figma." src="https://cdn-images-1.medium.com/max/690/1*5PsJWlpsi8WGSvFHJGCdMg.jpeg" /></figure><p>Part of the reason I had this problem is how the library I was using built its components—the creator wanted scalable icons, meaning there was no way to center them in my table row without at least creating a parent frame. It also was designed to support flexible text lengths <em>and </em>screen resolutions, so it couldn’t just set a column width statically.</p><p>I started thinking… I knew I could do this quite simply with flexbox or CSS grid — I could align objects in a frame, agnostic of the component, and give them padding/margin (flexible or otherwise). I could also control it at the root level instead of having to add individual constraints to the child elements. In CSS, it might look like this:</p><pre>.cell {<br>  display: flex;<br>  align-items: center;<br>  justify-content: center;<br>}</pre><pre>.cell i.icon {<br>  max-width: 18pt;<br>  max-height: 18pt;<br>}</pre><p>But we can’t do that in Figma, of course!</p><p>Instead, I had to create nested frames each with their own auto-layout parameters. I set the nested frame’s horizontal auto-layout to ‘hug contents’, which I guess because the constraints are ambiguous, it forces the inner components to fixed width? I can’t change it back. Here’s what happens:</p><figure><img alt="A .gif visually explaining how in certain situations, where the auto-layout parameters are ambiguous, Figma forces a frame to be fixed-width instead of fill container or hug contents." src="https://cdn-images-1.medium.com/max/800/1*aO730tKVZV5vGWLewP3cYA.gif" /></figure><p>If this isn’t an actual bug, it’s at least a very unexpected and unexplainable behaviour.</p><h3><strong><em>Flexbox / CSS grid-like controls could greatly improve how Figma exposes auto-layout</em></strong></h3><p>Defining a flexible column/row layout on a parent element allows you to add an arbitrary number of child elements into a frame without having to re-define auto-layout settings. You could have them wrap, grow, shrink, and flow without having to set any auto-layout properties on the children. Why is that valuable?</p><ul><li>If you’re using someone else’s components, you don’t have to worry about how they’ve built them.</li><li>If you change things later, you just need to change it once at the parent level instead of each individual element. You can define all of the layout behaviours of each row/column in one central place, and it “just works”, instead of having to adjust each row or column manually and individually.</li><li>If I wanted a table of mixed content, say a header with some sort icons, and a footer, or if I wanted to span two cells, I’d have to set individual auto-layout properties for each of these, and change them by hand every time I changed a column’s width.</li></ul><p>Which leads us to what I think is the biggest missing piece of Figma’s auto-layout:</p><ul><li>Even if I created a component or a parent frame, the child elements only know about the one parent frame. There’s no way to create flexible-width columns this way, and there’s no way to change them globally. Fixed column widths would be tolerable if you only had to change them in one place, but the way it’s built today, you have to manually change <em>every</em> cell in every distinct row.</li></ul><h3>As evidenced by</h3><p>Here are a series of attempts of me trying to work around this limitation. I started from an empty canvas with a few manually positioned elements, and tried and create a flexible grid layout. I had to do <em>a lot</em> of fiddling.</p><h4><strong>Basic frame, statically positioned (no auto-layout)</strong></h4><p>In this non-auto-layout example, If I make one change to this, I have to manually reposition <em>everything</em>. Simple, but doesn’t scale well.</p><figure><img alt="The desired state of my layout, but this one is manually laid out." src="https://cdn-images-1.medium.com/max/690/1*Z7FRKEqOTNMEQbC2nzG9BA.png" /></figure><h4><strong>Let’s try Auto Layout!</strong></h4><p>Oh no… (It’s actually fine, because I haven’t told auto-layout what it should be doing, and there are no child frames to group the rows).</p><figure><img alt="Auto-layout broke all the things, oh noes." src="https://cdn-images-1.medium.com/max/661/0*I_x2Cs3S4MMGE3O1.png" /></figure><h4><strong>So I need to create frames for each of the rows</strong></h4><p>Let’s add some frames by selecting the elements in each row, and using ⌥ + ⌘ + G (or <strong>Object &gt; Frame Selection</strong>).</p><figure><img alt="Demonstrating how adding frames to child elements in Figma can get us a little closer to our auto-layout goal." src="https://cdn-images-1.medium.com/max/652/0*LlcyQ_0x45UnGlxt.png" /></figure><h4><strong>I wanted some padding around the icons, and the rows to be a certain height</strong></h4><p>Off to do this manually for each row! (I actually started doing it per-cell before I remember I could do it per-row). Still, that was a lot of work for 4 rows. Imagine 400! <em>Yes, I could and should make this a component, but what if I didn’t own the component? What if I wanted a series of different elements in each row? What if I wanted more than one variable-width text columns?</em></p><p>Now with auto-layout on the rows, we at least get the added benefit of cell sizing and positioning affecting the entire grid — I can define alignment properties at the row level, and things are starting to look a little better. I am still, however, nowhere closer to my goal of variable width columns, or linked fixed-width columns.</p><figure><img alt="Everything is aligned all over the place here, it’s a huge mess. Text in columns isn’t wrapping properly, buttons aren’t aligned to the right of my table rows… ugh." src="https://cdn-images-1.medium.com/max/690/0*xmEgSzdoDTLBZwJc.png" /></figure><figure><img alt="This one, too, is a huge mess of alignment issues. It’s worse than the previous image." src="https://cdn-images-1.medium.com/max/690/0*fByD059S_mopIXar.png" /></figure><p>Even with a component, if all my rows are they were all identical, I’m stuck using fixed-width columns for my text. This means that for every resolution iteration, I have to adjust the column widths (all of them) and every time I want to change the text, I have to manually increase or decrease the column widths to fit the largest text string.</p><h3><strong><em>What if instead, I could just add all my elements into a single frame, and control everything from there?</em></strong></h3><p>Pure, unfiltered joy.</p><blockquote><strong><em>🥰</em></strong></blockquote><p>Here, we’ve got just one parent frame set in “grid” mode. I define the number of rows and columns I want (or an arbitrary number is fine) and on each, I can control the specific layout properties. I can set my first column to a fixed width, tell it to center its content, then make the next two either fixed-width, variable width (stretch), or proportional (stretch equally). Then the last two columns are of course fixed again.</p><p>I can also define unique rows for my header, perhaps some spanned content, and a footer.</p><figure><img alt="A robust set of controls to give grid-like qualities to Figma frames, like defining number of rows and columns, unique layout properties for each column or row, all from the parent frame." src="https://cdn-images-1.medium.com/max/1024/1*-osp7TecHEKewJXAK2r1kA.png" /></figure><p>There are some other super cool things this allows, too — CSS grid allows you to create cells that span columns, wrap around left to right or top to bottom, it has special flags for right-to-left layouts, and can cool things like auto-placement…</p><figure><img alt="An example of CSS-grid auto-placement from Mozilla Developer Network." src="https://cdn-images-1.medium.com/max/1024/1*jckxg42BtTMb5dsK3hPIaA.png" /><figcaption>Source: auto-placement from <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/Auto-placement_in_CSS_Grid_Layout">Mozilla’s MDN Web Docs</a></figcaption></figure><p>and <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-flow">grid-auto-flow</a>. These would be welcome additions to Figma!</p><p>Are you sold? Do you love this idea? I borrowed from my original Figma forum post to write this article (though this one is considerably more polished and refined); the best way to get it noticed is by <strong>voting</strong> and <strong>sharing</strong> with your Figma friends:</p><blockquote><a href="https://forum.figma.com/t/adopting-css-grid-and-flexbox-in-auto-layout/9167">https://forum.figma.com/t/adopting-css-grid-and-flexbox-in-auto-layout/9167</a></blockquote><h3>Interested in learning more about CSS grid and flexbox?</h3><p>If you haven’t spent time with these new and incredibly powerful additions to CSS, check out the <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/Relationship_of_Grid_Layout">Mozilla docs</a>. They’re pretty technical, but highly informative.</p><p>There’s also a ton of great content on <a href="https://css-tricks.com/">CSS-Tricks</a> like <a href="https://css-tricks.com/snippets/css/a-guide-to-flexbox/">this cheat-sheet</a>:</p><figure><img alt="A flexbox alignment tutorial from CSS Tricks." src="https://cdn-images-1.medium.com/max/1024/1*ApnqhqSCaiD1vw82uSjZ_A.png" /></figure><p><em>fin<br></em>— B</p><blockquote>read more long-form at <a href="https://brandonscript.design/">brandonscript.design</a><br>follow me on <a href="https://twitter.com/brandonscript">Twitter</a>, <a href="https://polywork.com/brandonscript">Polywork</a>, or <a href="https://linkedin.com/in/brandonscript">LinkedIn</a><br>work with me at <a href="https://pacificaviator.co/">pacificaviator.co</a></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=be6621e7af75" width="1" height="1" alt=""><hr><p><a href="https://brandonscript.design/what-if-figma-adopted-flexbox-css-grid-in-auto-layout-be6621e7af75">What if Figma adopted flexbox &amp; CSS grid in auto-layout?</a> was originally published in <a href="https://brandonscript.design/">UX &amp; Code | opinions &amp; scribbles</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>