<?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 Sebastian Balderas Espinosa on Medium]]></title>
        <description><![CDATA[Stories by Sebastian Balderas Espinosa on Medium]]></description>
        <link>https://medium.com/@sebastianbalderas?source=rss-5cb4627d7880------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*NulyiEDLuIdAMehfCfeqnQ.png</url>
            <title>Stories by Sebastian Balderas Espinosa on Medium</title>
            <link>https://medium.com/@sebastianbalderas?source=rss-5cb4627d7880------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 20:49:09 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@sebastianbalderas/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[Zero conversions on 63 clicks]]></title>
            <link>https://medium.com/@sebastianbalderas/zero-conversions-on-63-clicks-f1be35bc1077?source=rss-5cb4627d7880------2</link>
            <guid isPermaLink="false">https://medium.com/p/f1be35bc1077</guid>
            <category><![CDATA[ux-research]]></category>
            <category><![CDATA[engineering-design]]></category>
            <category><![CDATA[product-design]]></category>
            <category><![CDATA[product-strategy]]></category>
            <category><![CDATA[ux]]></category>
            <dc:creator><![CDATA[Sebastian Balderas Espinosa]]></dc:creator>
            <pubDate>Wed, 18 Nov 2026 17:49:00 GMT</pubDate>
            <atom:updated>2026-11-18T17:56:21.151Z</atom:updated>
            <content:encoded><![CDATA[<h3>In 2020, during my master’s, I tested a product idea with a landing page and five paid ads before building anything. The ads worked. The idea didn’t. It’s still the clearest lesson I have about deciding which product is the right one.</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*P1rcx2tU8M5HSrpAZn8Kpw.jpeg" /></figure><p>When people ask what a Design Engineer does that a full-stack engineer doesn’t, my short answer is: decide which product is the right one before shipping it. The code can be the same. The difference is the question you answer first.</p><p>The cheapest version of that question I’ve ever answered cost MXN 303.66, and the answer was no.</p><h3>The context</h3><p>Between 2018 and 2020 I did a weekend Master’s in Strategic Design &amp; Innovation at IBERO Puebla while working full-time. My thesis project was TLALLI, a tourism model for Miguel Hidalgo y Costilla, a town of 158 people on the slopes of Pico de Orizaba. The research had already reframed the town’s problem from basic services to isolation. Tourism was the proposed way to turn that isolation into income.</p><p>That gave me a product idea with a customer attached: people who practice outdoor and nature sports, looking for adrenaline and risk. Before designing anything further, I tested it, as part of a design project management course in spring 2020.</p><h3>The board, filled in before the test</h3><p>I used a validation board, and the order of the fields is the whole method:</p><ul><li><strong>Customer hypothesis:</strong> people who practice nature sports.</li><li><strong>Problem hypothesis:</strong> they’re looking for adrenaline and risk.</li><li><strong>Core assumptions:</strong> a change of environment, rough roads, untouched nature, getting lost in nature, finding teammates, the food of the villages, extreme weather.</li><li><strong>Riskiest assumption:</strong> extreme weather. My note at the time, translated: it could be the factor that creates the most uncertainty, because nature sports tend to be more dangerous, harder and less comfortable.</li><li><strong>Minimum success criterion:</strong> declared before running the experiment.</li></ul><p>The point isn’t to test everything. It’s to isolate the assumption that can kill the idea, and to write down in advance what result would count as a yes. If you define success after you see the data, you’ll find a way to call whatever happened a success.</p><h3>The minimum product</h3><p>I designed a landing page, ran minimum-viable-product interviews, and bought traffic: five Google Ads, each pointing to a different activity: canyoning, camping, hiking, cycling and horseback riding.</p><p>The numbers from the ad report:</p><ul><li>1,477 impressions</li><li>63 clicks</li><li>4.27% click-through rate</li><li>average cost per click: MXN 4.82</li><li>total cost: MXN 303.66</li><li><strong>conversions: 0</strong></li></ul><h3>The ad worked. The hypothesis didn’t.</h3><p>The click-through rate looks good, and that’s the trap. It isn’t the result of the experiment. The result is zero.</p><p>The search terms report explained why. The people clicking were searching for other destinations entirely: tours in Huasca de Ocampo in Hidalgo, Guadalajara to Chapala, cenotes in Mérida, Bacalar, trips to Cuba from Cancún, generic tour packages to Mexico. I was buying generic domestic tourism traffic, not people looking for nature sports on that volcano.</p><p>So the ad did its job. My customer hypothesis didn’t survive. For MXN 303.66, I learned that the customer wasn’t who I thought, before building anything for them.</p><p>I didn’t call it a partial validation, and I wouldn’t now. A negative result you document is as useful as a positive one. Softening it is how teams end up building for a customer that doesn’t exist. TLALLI continued; what was refuted was one assumption, in time.</p><h3>Why this is the same job I do now</h3><p>The tools changed. The question didn’t.</p><ul><li><strong>Isolate the riskiest assumption.</strong> On Strata, the equivalent was deciding where a model shouldn’t act. L2 shipped for bounded decisions; L3 was designed and deliberately held back until audit trails and permission scopes were ready. That’s the same move: test what can hurt you, don’t scale what you can’t verify.</li><li><strong>Declare what would refute you before you look.</strong> In my Storybook, a component’s “When not to use” sets in advance what counts as misuse, before anyone builds with it.</li><li><strong>Diagnose with evidence, not with opinion.</strong> The search terms report told me why. Today that’s a computed style, a screenshot at each width, or a diff, not a feeling that something looks right.</li><li><strong>Separate who you think uses the product from who actually moves it.</strong> That was the lesson of the ads, and it’s the same lesson as narrowing Strata’s 14 identified users to the three driving adoption.</li></ul><p>A design system in code is how I ship a product once it’s decided. This experiment is a reminder that deciding comes first, and that sometimes the right answer is not to build the thing.</p><p>What I deliver is a working product people use without friction. Not screens, and not the cycle of fixing them.</p><p><em>Note: this experiment was part of my Master’s in Strategic Design &amp; Innovation at IBERO Puebla (2020). The figures are from my own ad and search terms reports for that course project. Not client work.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f1be35bc1077" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Generative UI is a trust dial, not a feature]]></title>
            <link>https://medium.com/@sebastianbalderas/generative-ui-is-a-trust-dial-not-a-feature-08f82b37b727?source=rss-5cb4627d7880------2</link>
            <guid isPermaLink="false">https://medium.com/p/08f82b37b727</guid>
            <category><![CDATA[engineering-design]]></category>
            <category><![CDATA[conversational-ai]]></category>
            <category><![CDATA[generative-ui]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Sebastian Balderas Espinosa]]></dc:creator>
            <pubDate>Wed, 18 Nov 2026 17:47:20 GMT</pubDate>
            <atom:updated>2026-11-18T17:55:45.403Z</atom:updated>
            <content:encoded><![CDATA[<h3>Controlled, declarative or open: how much of the interface you let a model decide. I haven’t shipped generative UI. I have shipped the decisions it depends on, and they map onto that dial almost exactly.</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Zc78x_JK-KgLJ665bWc-IA.jpeg" /></figure><p>Let me be precise up front. I haven’t shipped generative UI to production. I’ve been studying it, the spectrum and the protocols around it, because it’s where conversational products are heading. This article is my point of view, not a case study.</p><p>What I have shipped are the decisions generative UI depends on: where a model is allowed to act on its own, what it must ask before doing, and which pieces of interface it’s allowed to use. Looking at the spectrum through that work, I think the most useful way to see generative UI is as a trust dial.</p><h3>The spectrum, briefly</h3><p>The question underneath is how much control you give the model over the interface. There are three broad levels.</p><ul><li><strong>Controlled.</strong> The team defines a closed catalog of components and actions in advance. The model can only choose and parameterize within it: which component, with which data, in which order. Maximum predictability.</li><li><strong>Declarative.</strong> The model emits a structured description of the interface (components, props, layout) and the client renders it with its own design system. The model decides the composition, but only from the components the system offers.</li><li><strong>Open-ended.</strong> The model generates interface freely, as arbitrary markup or code. Maximum flexibility, minimum control over security, consistency, accessibility and brand.</li></ul><p>Around that spectrum there’s a set of protocols I’ve been reading about. The simplest mental model I’ve found: MCP connects capabilities, A2UI describes the interface declaratively, and AG-UI moves the events between agent and front end while the work happens. MCP Apps extend MCP so a tool can return an interactive interface, not only data. A platform designer doesn’t pick one. They decide which layer each decision lives in.</p><h3>Where my shipped work sits on the dial</h3><p>Strata is an AI-native operations platform for contract office furniture. I inherited it as Orderbahn, with modules and a design system already in place, improved it, and designed new capability as it evolved into Strata. On it, I used a three-level frame for automation:</p><ul><li><strong>L1, workflow automation:</strong> fixed rules, no reasoning.</li><li><strong>L2, agentic integration:</strong> models interpret context and make bounded decisions within a step. This shipped to production, for bounded prioritization and routing.</li><li><strong>L3, adaptive agent loops:</strong> designed and deliberately held back, until audit trails and permission scopes were mature enough to remove human review safely.</li></ul><p>In a B2B2C flow I designed (wireframes and a working prototype, not a production integration), payment and legal confirmation stayed deterministic, at L1. No model in that path.</p><p>The other piece is the assistant on my own portfolio, which I designed and built. It uses retrieval routing, behavioral guardrails and allowlisted internal navigation. That last one is the controlled end of the dial in miniature: the assistant can send you somewhere on the site, but only to a destination on a list I wrote. It can’t invent a route.</p><p>None of that is generative UI. But it’s the same question asked of actions instead of pixels: how much do you let the model decide, and what has to be true before you let it decide more?</p><h3>The rule I’d carry over</h3><p><strong>The closer an action is to a user’s money or a commitment they can’t undo, the further toward controlled it belongs.</strong> The further away it is, the more declarative flexibility you can afford.</p><p>In practice I’d expect most of a serious product to live at the controlled end. Confirming a payment, showing a balance, asking for a missing detail: the model composes the conversation from approved pieces and never invents a payment screen. Declarative composition earns its place in summaries and contextual cards, where the model chooses what to show but the system decides how it looks. Open-ended generation can make sense on internal or exploratory surfaces, not in a user’s critical path.</p><p>That’s exactly how L2 and L3 were split on Strata. L2 shipped where the decision surface was narrow enough to trust. L3 waited, and holding it back was the decision, not a stage still pending.</p><h3>Why the design system becomes the contract</h3><p>When the interface is generated, the catalog, the schemas, the states and the composition rules are the design system. There’s nothing else for the model to draw from.</p><p>My own system already ships as code: tokens and components in a public Storybook, where the component pages carry Do and Don’t, when to use it, when not to, and implementation notes for AI tools. That’s the raw material a declarative catalog needs: components described as structured specifications something other than a person can instantiate. So the step from “components engineers instantiate” to “components an agent instantiates” is a change of consumer, not of discipline. Connecting that catalog to agents through MCP, a manifest and AGENTS.md is my direction for 2027, not work I’ve delivered.</p><p>Figma still has its job: exploring the vocabulary and checking it with stakeholders. But a model can’t compose from a frame. It composes from whatever the implemented system exposes, which is why I treat Storybook as the versioned, implemented contract for frontend and approved AI tooling to consume directly.</p><h3>What I’d ask a team starting with generative UI</h3><ul><li>Place every surface on the dial before choosing a protocol.</li><li>Keep anything touching money or irreversible commitments at the controlled end, and write down why.</li><li>Treat the component catalog as the model’s vocabulary: if a component has no “when not to use”, the model will use it everywhere.</li><li>Decide what the user sees while the agent works. That intermediate state is design work, not plumbing.</li><li>Hold back the next level until the audit trail exists. Restraint is a design decision.</li></ul><p>What I deliver is a working product people use without friction. Not screens, and not the cycle of fixing them.</p><p><em>Note: this is a point of view on concepts I’ve studied, not shipped work. Strata facts are limited to what my published case study states (L2 in production; L3 designed and held back). The portfolio assistant and Storybook are my own work. No client figures or usage data are claimed.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=08f82b37b727" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The component no page uses yet]]></title>
            <link>https://medium.com/@sebastianbalderas/the-component-no-page-uses-yet-868565fd76af?source=rss-5cb4627d7880------2</link>
            <guid isPermaLink="false">https://medium.com/p/868565fd76af</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[engineering-design]]></category>
            <category><![CDATA[storybook]]></category>
            <category><![CDATA[documentation]]></category>
            <dc:creator><![CDATA[Sebastian Balderas Espinosa]]></dc:creator>
            <pubDate>Wed, 18 Nov 2026 17:45:28 GMT</pubDate>
            <atom:updated>2026-11-18T17:55:03.772Z</atom:updated>
            <content:encoded><![CDATA[<h3>Error State is in my Storybook, documented and rendered, and nothing on my live site mounts it. The most useful line on its page is the one that says so, because a person would guess that and an agent wouldn’t.</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4PobtJVgELgv05clrWtjRQ.jpeg" /></figure><p>Most platforms today are built for humans, not for agents. I don’t mean the screens. I mean the documentation underneath them. It assumes a reader who brings context: someone who knows the codebase, asks a colleague, notices that a component looks newer than the rest, and adjusts.</p><p>An agent reading the same page brings none of that. It reads what’s written and builds from it. So when I document a component, I ask one extra question: what would a person infer here that a tool wouldn’t?</p><p>The clearest answer I have is a component called Error State.</p><h3>What it is</h3><p>Error State is a full-block state. It replaces an entire region of the page, like a list or a panel, when there’s nothing to show or the load failed. It’s deliberately distinct from Alerts. Alerts handle a transient, dismissible problem. A single field’s validation error belongs to Form Field’s status=&quot;error&quot;. Error State is for when the whole region has nothing to render.</p><p>Its API is small:</p><ul><li>tone?: &quot;empty&quot; | &quot;error&quot;, defaulting to &quot;empty&quot;</li><li>icon?, heading, description, and an optional action</li></ul><p>The two tones render the same layout with a different tint and different copy. The examples on the page show both: “No conversations yet” for empty, and “Couldn’t load this”, with “Something went wrong on our end. Try again in a moment.” and a Retry button, for error.</p><h3>The sentence a person wouldn’t need</h3><p>Here’s the part that matters. The page’s “What it is” section says this is a new shared component, and that no page in the app currently has an empty list or a failed panel that needs this layout. The site is mostly static case-study content. So the component was built the way an extraction candidate would be: ready for the first real need, not extracted from one.</p><p>Then the AI implementation notes say it again in operational terms: reuse storybook/src/components/shared/EmptyState.tsx for any whole-region empty or failed state, but it isn&#39;t a main-site file, so a real page would still need to wire the same layout itself.</p><p>A person browsing the Storybook might work that out. They’d notice there’s no screen on the site that shows this, maybe search the repo, and draw the right conclusion. An AI tool asked to “add an empty state using the design system” would find a documented, rendered, well-specified component and reasonably assume it can import it into a page. That assumption is wrong, and nothing in the props table would tell it so.</p><p>There’s a second, smaller version of the same gap. The page is titled Error State, the file is EmptyState.tsx, and the default tone is empty. A person reads past that. A tool searching by name might not connect them. The note puts the real path in writing, so neither has to guess.</p><h3>The rules that travel with it</h3><p>The rest of the page is ordinary, which is the point. The rules are written so either reader can follow them without context:</p><ul><li><strong>Anatomy:</strong> optional icon, tinted by tone, then heading, then description, then an optional action.</li><li><strong>Responsive behavior:</strong> the block centers its content and caps the description at 42ch regardless of container size, so the message stays readable in a wide region.</li><li><strong>Accessibility:</strong> the icon uses danger tokens for error and a muted neutral for empty, but the heading always states the outcome in words. Color is never the only signal.</li><li><strong>Don’t:</strong> don’t reuse it for a single field’s error.</li></ul><p>None of these rules depend on knowing the history of the codebase. That’s what makes them consumable by something that doesn’t have that history.</p><h3>Where Figma fits</h3><p>Figma is where I’d explore what an empty or failed region should look like and agree on it with stakeholders. But “this component exists and is not mounted anywhere” isn’t something a frame can say. It’s a fact about the implementation, and it has to sit next to the implementation. That’s why I treat Storybook as the versioned, implemented contract for frontend and approved AI tooling to consume directly.</p><p>Where this goes next is a direction, not something I’ve delivered: exposing that contract to tools through MCP, a manifest and an AGENTS.md file is how I see design systems working in 2027. The prerequisite is the same either way. The page has to say what’s true in words a tool can act on.</p><h3>What I’d ask of any component page</h3><ul><li>Say whether production uses the component, and where. “Documented” and “deployed” are different claims.</li><li>When a component is built ahead of need, say so in the first section, not in a commit message.</li><li>Put the real file path in the AI notes when the name on the page and the name in the code differ.</li><li>Write every rule so it holds for a reader with no context. If a rule needs tribal knowledge, it isn’t written yet.</li></ul><p>What I deliver is a working product people use without friction. Not screens, and not the cycle of fixing them.</p><p><em>Note: Error State is part of my own portfolio’s design system, documented in my public Storybook (Components → Error State). Not client code. As its page states, no page on the live site mounts it today. No usage data is claimed.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=868565fd76af" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The tooltip that isn’t allowed to hold anything you need]]></title>
            <link>https://www.designsystemscollective.com/the-tooltip-that-isnt-allowed-to-hold-anything-you-need-b4c69559d581?source=rss-5cb4627d7880------2</link>
            <guid isPermaLink="false">https://medium.com/p/b4c69559d581</guid>
            <category><![CDATA[frontend]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[storybook]]></category>
            <category><![CDATA[accessibility]]></category>
            <category><![CDATA[engineering-design]]></category>
            <dc:creator><![CDATA[Sebastian Balderas Espinosa]]></dc:creator>
            <pubDate>Wed, 18 Nov 2026 17:43:40 GMT</pubDate>
            <atom:updated>2026-11-19T16:15:10.582Z</atom:updated>
            <content:encoded><![CDATA[<h3>Don’t use a tooltip for anything the user needs to read to operate the control correctly. One rule on my Tooltip component shows what that looks like in the docs and in the code.</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*eu1ZrVBu0mAMfso3W26LHA.jpeg" /></figure><p>It’s the Tooltip in my portfolio’s design system, and the most important line on its documentation page isn’t about how it looks.</p><h3>The rule that is a product decision</h3><p>The page has a “When not to use” section, and it says:</p><p><strong>Don’t use a tooltip for anything the user needs to read to operate the control correctly.</strong> A tooltip isn’t perceivable on touch devices without a tap-and-hold, so required information belongs in visible text instead.</p><p>That rule isn’t a styling preference. It decides what the product is allowed to hide. Without it, a tooltip becomes the place where copy goes when there’s no room for it: the warning nobody wanted on screen, the condition that “only power users need”, the explanation of what a button really does. On a desktop with a mouse, that looks fine in review. On a phone, that information doesn’t exist for most people, and the interface quietly becomes a different product.</p><p>Writing that rule meant answering a question a component library can’t answer for you: who is this interface for, and on which devices? The answer is everyone who opens the site, including people on a phone. Once that’s decided, the tooltip’s job shrinks to one thing: a supplementary label for an icon-only control, or for a control whose short label needs one more word on demand.</p><p>A real case from the settings of the Order One platform shows where the line sits. A toggle there had an info button next to it, with a tooltip that explained a bit more about what the toggle could do. People read it once, and when they came back they already knew what the toggle was for. It could stay hidden because it was a one-time read: the toggle worked without it. If using the toggle correctly had depended on that text, it would have belonged on screen.</p><h3>What the component is</h3><p>It’s the real components/ui/tooltip.tsx, the same one that labels the voice-launcher button in my portfolio&#39;s chat with &quot;Talk with my assistant&quot;. It&#39;s built on Base UI&#39;s composable API: one TooltipProvider per app, wrapping Tooltip, TooltipTrigger and TooltipContent.</p><p>It has two states, closed and open, and it opens on hover or on keyboard focus. It has no visual variants. Position (side) is its only axis, and the page is explicit that it&#39;s a placement choice, not a style choice.</p><h3>Decided once, shipped as code</h3><p>The decision only holds if it lives where the code lives. So the rest of the page turns it into contracts:</p><ul><li><strong>One primitive.</strong> The AI implementation notes say to reuse @/components/ui/tooltip for any icon-only control&#39;s label, because it&#39;s the only tooltip primitive in the codebase. A second tooltip would be a second set of rules.</li><li><strong>One provider.</strong> Wrap the app in a single TooltipProvider. The real root layout already mounts it once.</li><li><strong>No </strong><strong>title attribute.</strong> The Don&#39;t says not to reach for title instead. It has neither keyboard dismissal nor Escape-to-close, which Base UI&#39;s tooltip provides natively.</li><li><strong>Placement is decided, not automatic.</strong> The real usage pins side=&quot;top&quot; because the trigger sits at the bottom of the composer and there&#39;s no room below it.</li><li><strong>Keyboard parity.</strong> The tooltip opens on focus as well as hover, so a keyboard-only user gets the same supplementary label a mouse user does, and can dismiss it with Escape.</li></ul><p>Each of those is small. Together they mean the next person who adds an icon button, or the next AI tool asked to add one, inherits the decision instead of re-making it.</p><h3>Where Figma fits</h3><p>Figma is where I’d explore how a tooltip looks and check the direction with stakeholders. But “never put required information here” isn’t a visual fact. It’s a decision about the product, and it needs to sit next to the implemented component, where it gets enforced. That’s why I treat Storybook as the versioned, implemented contract for frontend and approved AI tooling to consume directly.</p><h3>What I’d ask of any tooltip in any system</h3><ul><li>Write “When not to use” before “When to use”. The exclusions are where the product decisions are.</li><li>Test the content against touch. If a phone user can’t reach it, it can’t be required.</li><li>Keep one primitive, and say so in the docs.</li><li>Ban the shortcut (title) by name, with the reason.</li><li>Make keyboard focus open it, and Escape close it.</li></ul><p><em>Note: Tooltip is part of my own portfolio’s design system, documented in my public Storybook (Components → Tooltip). Not client code. No usage data is claimed.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b4c69559d581" width="1" height="1" alt=""><hr><p><a href="https://www.designsystemscollective.com/the-tooltip-that-isnt-allowed-to-hold-anything-you-need-b4c69559d581">The tooltip that isn’t allowed to hold anything you need</a> was originally published in <a href="https://www.designsystemscollective.com/">Design Systems Collective</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A warning you can’t reread is decoration]]></title>
            <link>https://medium.com/@sebastianbalderas/a-warning-you-cant-reread-is-decoration-f6acb8b41804?source=rss-5cb4627d7880------2</link>
            <guid isPermaLink="false">https://medium.com/p/f6acb8b41804</guid>
            <category><![CDATA[conversational-ai]]></category>
            <category><![CDATA[storybook]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[ux]]></category>
            <category><![CDATA[engineering-design]]></category>
            <dc:creator><![CDATA[Sebastian Balderas Espinosa]]></dc:creator>
            <pubDate>Wed, 11 Nov 2026 17:46:36 GMT</pubDate>
            <atom:updated>2026-11-11T17:58:37.666Z</atom:updated>
            <content:encoded><![CDATA[<h3>Return to latest message is the smallest control in my portfolio’s chat, and the only control there that exists as its own component. Documenting it meant listing every control the chat has, and two it doesn’t.</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Nm28Pln9NQPOWuJHTfWRCQ.jpeg" /></figure><p>In my Storybook, the AI layer of the portfolio’s chat is split into three small families: Control, Uncertainty and Provenance. Uncertainty holds the error and quota states. Provenance holds what the assistant knows and where it came from. Control holds the ways a person takes the interface back.</p><p>The component I’ll use here is the smallest one in Control: ConversationScrollButton, labelled &quot;Return to latest message&quot;. It lives in components/ai-elements/conversation.tsx and is mounted on both chat surfaces. It&#39;s an icon-only outline button. Readers of &quot;One border, five components&quot; may remember it: it was the control whose border had been overridden locally inside the chat widget.</p><h3>Why it exists</h3><p>While a response streams in, the chat sticks to the bottom. The moment someone scrolls up to reread, that auto-stick has to yield, or it pulls the text out from under them. This button is the way back.</p><p>It’s literally control over attention. The system stops deciding where you look and hands that decision back to you as an explicit action. The action is reversible: you scroll down, and you can scroll back up. No confirmation, no consequence.</p><h3>What it must not do</h3><p>The spec sheet’s “must not” section has three rules, and each one is a product decision, not a style:</p><ul><li><strong>Never force-scroll to the bottom</strong> when new content arrives and the person has scrolled up. That’s the exact antipattern the button exists to avoid.</li><li><strong>Never stay visible all the time.</strong> It renders only when the view isn’t at the bottom. A permanent “scroll down” button that does nothing teaches people to ignore controls.</li><li><strong>Never become a new-content notice.</strong> It has no counter and no dot. It says “you’re scrolled up”, not “you missed three messages”. A counter with no real signal behind it would be fabricated data.</li></ul><h3>Why a warning family needs it</h3><p>This is the part I didn’t expect when I started writing the page.</p><p>A warning can only be verified if you can reread what triggered it. A chat that pins you to the bottom and won’t let you go back shows each response once, and what you only see once can’t be checked. So the scroll button says nothing about content and can’t overclaim, but it’s what holds up the Uncertainty family. Without the ability to go back, the warning is decoration.</p><h3>The audit the page forced</h3><p>To document one control honestly, the page lists every control the chat has, and whether it’s a component:</p><ul><li>Return to latest message: this one. Own component: yes.</li><li>Dismiss a notice: onDismiss on the two voice banners. Own component: no, it’s a prop.</li><li>Retry a turn: onRetry → regenerate(). Own component: no, it’s a prop.</li><li>Interrupt the assistant: the whole voice pill in speaking. Own component: no, it’s a state.</li><li>Exit voice mode: ComposerAction, not exported. Own component: not documentable today.</li><li>Undo or retract a sent turn: doesn’t exist.</li><li>Stop a response mid-generation: Prompt Input supports it; the chat doesn’t expose it.</li></ul><p>The last two items are the gap, and the page says so. Warnings exist; a way to undo does not. I’d rather publish that than draw a Control family that looks complete.</p><p>Figma is a good place to explore what a Control family could be and to check that with stakeholders. But a frame of a stop button doesn’t tell you the chat never exposes one. The list above could only be written by reading where each control actually lives in the code.</p><h3>What I’d take to a team</h3><ul><li>When you document one control, list the whole family, including what’s a prop, what’s a state and what doesn’t exist.</li><li>Give people a way back before you add another warning.</li><li>Never let a control imply a signal the system doesn’t have, like an unread count.</li><li>Write the gaps on the page. A missing undo is a decision someone has to make, and it can’t be made if nobody wrote it down.</li></ul><p>What I deliver is a working product people use without friction. Not screens, and not the cycle of fixing them.</p><p><em>Note: this control is part of my own portfolio’s chat and is documented in my public Storybook (Control → Return to latest message). Not client code. The gaps listed are as documented on that page; no usage data is claimed.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f6acb8b41804" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Three widths, two identical screenshots]]></title>
            <link>https://www.designsystemscollective.com/three-widths-two-identical-screenshots-c4e09238bf3b?source=rss-5cb4627d7880------2</link>
            <guid isPermaLink="false">https://medium.com/p/c4e09238bf3b</guid>
            <category><![CDATA[responsive-design]]></category>
            <category><![CDATA[storybook]]></category>
            <category><![CDATA[frontend]]></category>
            <category><![CDATA[engineering-design]]></category>
            <category><![CDATA[design-systems]]></category>
            <dc:creator><![CDATA[Sebastian Balderas Espinosa]]></dc:creator>
            <pubDate>Wed, 11 Nov 2026 17:44:45 GMT</pubDate>
            <atom:updated>2026-11-12T15:34:10.536Z</atom:updated>
            <content:encoded><![CDATA[<h3>My Responsive Composition story pins one grid at 375, 768 and 1440 pixels. The first screenshots showed 768 and 1440 rendering the same layout. The story had been asserting something it wasn’t showing.</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4nMxQNVYHj6m0iE69VIX1g.jpeg" /></figure><p>Responsive behaviour is the easiest thing in a design system to describe and the easiest to get wrong without noticing. A docs page says “three columns on desktop, two on tablet, one on mobile”, a reviewer nods, and nobody checks whether the story actually renders three different layouts.</p><p>This is about one composition in my Storybook where I did check, and found it didn’t.</p><h3>What the composition is</h3><p>Responsive Composition documents the one responsive pattern my portfolio reuses across its real grids: services, testimonials and case studies. It’s a content grid that goes one column below 640px, two from 640px, and three from 1024px. Those are the same breakpoints the site’s sm: and lg: grids use. In this project sm: is the mobile boundary everywhere; there is no separate 430px breakpoint.</p><p>It’s built only from components that are already documented: Card, Badge and Link. The content is deliberately generic, so all three cards link to the same real page, sebastianbalderas.com/services. One shared real destination is more honest than three made-up ones, and the rule is that a link is never a dead href=&quot;#&quot;.</p><h3>Why three pinned widths, not one resizable story</h3><p>I could have left one story and let a reviewer drag the viewport. Instead the composition has three states pinned at 375px, 768px and 1440px.</p><p>The reason is verification. The artifact that proves this composition works is a fixed Playwright screenshot at each width, and a screenshot needs a distinct, reproducible width to be worth anything. “Resize it and see” isn’t a check anyone can repeat.</p><h3>The screenshots that didn’t change</h3><p>The states don’t use Storybook’s own viewport-simulation tool: that addon’s device frame had been disabled site-wide, as a separate fix. So each state got an explicit pixel-width wrapper instead.</p><p>That wasn’t enough. I screenshotted all three states with only the wrapper, and 768px and 1440px rendered identically.</p><p>The cause is how the breakpoints compile. sm: and lg: become viewport media queries. They read the real browser window, which Storybook&#39;s layout fixes, and they ignore the width of any wrapper inside it. So the story was labelled &quot;tablet&quot; and &quot;desktop&quot; while showing the same thing twice.</p><h3>The fix, kept local</h3><p>The demo grid now uses @container on the wrapper and container-query variants, @[640px]: and @[1024px]:, which respond to the wrapper&#39;s width. That&#39;s native in Tailwind v4, no plugin.</p><p>The important part is the scope. Production grids keep using sm: and lg: exactly as before. The container-query substitution is local to the demo, and the docs page says so under &quot;Implementation decision&quot;. A documentation fix that quietly changed production behaviour would be a second problem.</p><h3>What never changes across widths</h3><p>The column count changes; the reading order never does. The grid uses no order-* utilities, so DOM order and visual order stay identical at every width. That matters for keyboard users, and for screen-reader users who don&#39;t perceive the visual grid at all.</p><p>The docs also say what the composition is not. It’s a generic pattern demo, not a reproduction of any specific section of the live site. The real services and testimonials grids have their own components, and this doesn’t stand in for them.</p><h3>Where Figma fits</h3><p>In Figma, three frames at three widths are three drawings, and they’re useful for exploring the pattern and checking it with stakeholders. They can’t tell you whether the implemented grid responds to the width you think it does. That’s a property of how the CSS compiles, and only the rendered component, captured at a fixed width, can show it.</p><h3>What I’d ask of any responsive story</h3><ul><li>Pin each breakpoint as its own state, at an exact width, instead of asking reviewers to resize.</li><li>Treat a screenshot at each width as the verification, and look at them side by side.</li><li>If two widths look the same, suspect the harness before the component.</li><li>Keep any harness fix local to the story, and write down that production is unchanged.</li><li>Keep reading order identical at every width.</li></ul><p>A responsive story that hasn’t been screenshotted at each width is a claim, not a contract.</p><p>What I deliver is a working product people use without friction. Not screens, and not the cycle of fixing them.</p><p><em>Note: Responsive Composition is part of my own portfolio’s Storybook (Compositions → Responsive Composition). Not client code. No usage data is claimed.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c4e09238bf3b" width="1" height="1" alt=""><hr><p><a href="https://www.designsystemscollective.com/three-widths-two-identical-screenshots-c4e09238bf3b">Three widths, two identical screenshots</a> was originally published in <a href="https://www.designsystemscollective.com/">Design Systems Collective</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The textarea has to be a direct child]]></title>
            <link>https://medium.com/@sebastianbalderas/the-textarea-has-to-be-a-direct-child-38b8fbc0d3dc?source=rss-5cb4627d7880------2</link>
            <guid isPermaLink="false">https://medium.com/p/38b8fbc0d3dc</guid>
            <category><![CDATA[engineering-design]]></category>
            <category><![CDATA[storybook]]></category>
            <category><![CDATA[react]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Sebastian Balderas Espinosa]]></dc:creator>
            <pubDate>Wed, 11 Nov 2026 17:42:50 GMT</pubDate>
            <atom:updated>2026-11-11T17:55:12.505Z</atom:updated>
            <content:encoded><![CDATA[<h3>My chat composer, Prompt Input, has one rule that CSS enforces silently, and a note for AI tools that says which of its own exports production doesn’t use. Both are the kind of thing a props table never tells you.</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*VeaqjEwm57MMgWcMKd0i7A.jpeg" /></figure><p>Prompt Input is the only composer component in my portfolio’s codebase. It’s the box you type into on both chat surfaces of the site. If you look at it in Storybook, it’s unremarkable. A multi-line field, a submit button, four states.</p><p>Its documentation is where it gets interesting, because two of its entries say things the code can’t say about itself. One is a structural rule that breaks quietly if you ignore it. The other is an honest list of what production doesn’t use.</p><h3>What it is, and what was cut</h3><p>The component is the real components/ai-elements/prompt-input.tsx. PromptInput and PromptInputTextarea are the exact pieces the chat mounts.</p><p>It’s also a trim. The file started as the upstream ai-elements registry component, and I removed the attachment menu, screenshot capture and a few other pieces because they pulled in prop shapes that this project&#39;s Base UI primitives don&#39;t match. The file&#39;s own header comment explains that, and the docs page points to it.</p><p>I think that’s worth writing down in any system. When you adopt a component from a registry and cut it, the next person needs to know the cut was deliberate. Otherwise they’ll “restore” what’s missing.</p><h3>The rule CSS enforces silently</h3><p>PromptInput wraps its children directly in a real InputGroup. InputGroup has a CSS rule, has-[&gt;textarea]:h-auto, that lets it grow past its 32px single-line default only when a &lt;textarea&gt; is its literal DOM child.</p><p>So the contract on the page is one line: keep PromptInputTextarea a direct child of PromptInput. Don&#39;t wrap it in an extra div.</p><p>If you do, nothing errors. The types are fine, the lint is fine, the component renders. It just stops growing with its content: the group stays at its 32px single-line default while someone types a long question. That’s why the rule is written in the Do, repeated in the Don’t, and explained under Implementation contracts. A rule that fails silently has to be documented loudly.</p><h3>The note that tells a tool what not to assume</h3><p>The section I’d point a team to is the AI implementation notes. It says production does <strong>not</strong> use PromptInputFooter, PromptInputTools or PromptInputSubmit.</p><p>The real submit control in the chat is hand-built separately, as ComposerAction, because it also has to drive the voice-mode glyph, which is outside this file&#39;s job. The three unused pieces are real, unmodified exports of the same file. The page shows them so the component&#39;s full surface is documented, not only the slice production happens to use today.</p><p>Without that note, a person or an AI assistant reading the file would reasonably assume the exported submit button is the one on the live site, and build against it. The note turns “this exists” into “this exists, and this is what production actually wires”.</p><h3>States driven by real values</h3><p>The states are idle, submitted, streaming and error, and they’re driven entirely by the real status value, switchable in Controls. The submit icon follows it: a return arrow when idle, a spinner when submitted, a stop square while streaming, an X on error. There&#39;s no variant prop; all the variation comes from state.</p><p>The textarea uses field-sizing-content to grow with its content up to max-h-48, and never shrinks below min-h-16. That floor exists so the composer doesn&#39;t visibly resize on the first keystroke.</p><h3>Accessibility, written per component</h3><ul><li>Enter submits and Shift+Enter inserts a newline, the convention people already know from chat products.</li><li>The submit button’s aria-label switches between &quot;Submit&quot; and &quot;Stop&quot; with the status, so a screen-reader user gets the same distinction a sighted user reads from the icon.</li><li>The composer’s outline uses border-border-control, the same 3:1 control-boundary token as Input and Textarea.</li></ul><p>Figma is where I’d explore a composer and check direction with stakeholders. But “the textarea must be a direct child” and “production doesn’t wire this export” aren’t visual facts. They only exist next to the implemented component, which is why I treat Storybook as the versioned, implemented contract for frontend and approved AI tooling to consume directly.</p><h3>What I’d ask of any adopted component</h3><ul><li>Say where it came from and what was cut, and why.</li><li>Write every structural rule that fails silently, in Do, Don’t and contracts.</li><li>Say which exports production actually uses.</li><li>Tie the states to the real value that drives them, not to a decorative variant.</li></ul><p>Having Storybook as the place where I already delivered directly in code is where the +35% in design-system velocity I’ve reported came from. There’s no documented baseline, period or tool behind that number, so read it as my own assessment, not a measurement.</p><p>What I deliver is a working product people use without friction. Not screens, and not the cycle of fixing them.</p><p><em>Note: Prompt Input is part of my own portfolio, documented in my public Storybook (Components → Prompt Input). Not client code. No usage data is claimed.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=38b8fbc0d3dc" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The bars kept moving after the microphone closed]]></title>
            <link>https://medium.com/@sebastianbalderas/the-bars-kept-moving-after-the-microphone-closed-0080cbac2b8c?source=rss-5cb4627d7880------2</link>
            <guid isPermaLink="false">https://medium.com/p/0080cbac2b8c</guid>
            <category><![CDATA[engineering-design]]></category>
            <category><![CDATA[conversational-ai]]></category>
            <category><![CDATA[storybook]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[accessibility]]></category>
            <dc:creator><![CDATA[Sebastian Balderas Espinosa]]></dc:creator>
            <pubDate>Wed, 11 Nov 2026 17:41:11 GMT</pubDate>
            <atom:updated>2026-11-11T17:54:49.245Z</atom:updated>
            <content:encoded><![CDATA[<h3>Two voice components in my Storybook use the same four animated bars, and they disagree about what those bars mean. Writing their documentation, not using the site, is what found it.</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*BKixcku3r664RaiCpt_Nwg.jpeg" /></figure><p>The chat on my portfolio has a voice mode. When it’s on, two different components can show the same small graphic: four vertical bars that scale up and down.</p><p>One is VoiceStatus, the strip inside the open chat. The other is VoiceLauncherStatus, the pill you see before the chat opens. Same four bars, same tokens, same states. The pill was built later and correctly reused the open chat&#39;s vocabulary.</p><p>What it didn’t reuse was the rule that gives that vocabulary its meaning. That’s what this article is about, because it’s the kind of defect a design system can’t catch unless someone writes the documentation.</p><h3>A state graphic is a claim</h3><p>The bars exist because a text label alone can’t answer “can I speak yet?” at the speed that decision gets made. They’re not decoration. When they move in time with speech, they say: <em>I’m hearing you.</em></p><p>So the question for every state is whether that claim is true.</p><p>In the speaking state, the assistant is talking and the microphone is closed. The open chat handles this correctly. VoiceStatus hides the bars, and the reason is written in the code, in a comment: &quot;the microphone is CLOSED, so the level meter would be lying about listening.&quot;</p><p>The pill keeps the bars visible in the same state, with a --working modifier that makes them slower and dimmer. At a glance that reads as &quot;resting&quot;. By name, it sounds like &quot;resting&quot;.</p><h3>Measured, not inferred</h3><p>“Looks like it’s off” isn’t evidence, so I measured it.</p><p>In the stylesheet, .voice-bars--working changes one thing: animation-duration: 1.5s. The base animation on the bars, voice-bar 0.9s ease-in-out infinite, stays active. The 45% that makes them look quiet is the alpha of the background colour, not a pause.</p><p>Then I confirmed it in the browser on the real component in speaking: animation name voice-bar, duration 1.5s, play state running, and the transform moving from scaleY(0.94) to scaleY(0.57) over 300 ms.</p><p>The verdict on the Storybook page is short: the pill diverges, and VoiceStatus is the one that&#39;s right. An animation at 45% opacity claims exactly what one at 70% claims, just more quietly.</p><h3>Why nothing caught it</h3><p>This wasn’t a type error, a lint failure or a broken test. Using the site doesn’t reveal it either, because the label tells the truth while the graphic contradicts it. You only see it if you put the two components next to each other on purpose.</p><p>That’s exactly what writing the spec sheet did. Each entry in my Storybook’s Uncertainty family has the same four sections: why it is this way, what it must not do, what it must do, and how it reduces hallucination risk. Filling in “what it must not do” for the pill meant comparing it with the strip, and the comparison was the finding.</p><p>Figma has a job in this kind of work: exploring the vocabulary and checking it with stakeholders. But a frame shows four bars. It can’t show whether they’re still animating in a state where they shouldn’t be. The rendered component can, and the computed style can prove it.</p><h3>Fix the rule, not the component</h3><p>The fix I documented is at the system level: <strong>animated bars mean live audio input, and only that</strong>. Dimmed and static bars mean the capability is there but inactive. Dimming alone means nothing; the movement carries the meaning.</p><p>With that rule, the pill’s speaking state has two legitimate outcomes, and both are code changes to decide separately. Hide the bars, the way VoiceStatus does. Or freeze them with animation: none and leave them dimmed, as a signal that there&#39;s a session but nobody is listening. The second keeps the layout stable, which was the reason the pill didn&#39;t hide them in the first place.</p><p>As the Storybook page states, nothing on the live site has been changed yet; the documentation records the divergence and the decision is separate.</p><h3>The general rule</h3><p>I call this an interface hallucination, not a model one. There’s no prompt to review and no output to validate. The system is claiming a capability with pixels, and an animated graphic gets believed before a label does, because it looks like telemetry.</p><p>Three things I’d ask of any team that reuses a visual vocabulary:</p><ul><li>Never reuse a graphic without carrying its rule. Copying the bars copied a shape; the meaning lived in a comment in another file.</li><li>Never treat “slower and dimmer” as equivalent to “off”.</li><li>When two components answer the same question differently, mark one of them as the one that diverges, and write the rule where the vocabulary is borrowed, not only where it was invented.</li></ul><p>A design system with no written spec sheets has no way to catch this class of defect. That’s the reason mine has them.</p><p>What I deliver is a working product people use without friction. Not screens, and not the cycle of fixing them.</p><p><em>Note: both components are part of my own portfolio’s chat and are documented in my public Storybook (Uncertainty → Bar divergence). Not client code. The CSS values and browser readings are quoted from that page; no usage data is claimed.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=0080cbac2b8c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Spec tab: one brief for a person or a tool]]></title>
            <link>https://medium.com/@sebastianbalderas/the-spec-tab-one-brief-for-a-person-or-a-tool-1be321171a21?source=rss-5cb4627d7880------2</link>
            <guid isPermaLink="false">https://medium.com/p/1be321171a21</guid>
            <category><![CDATA[storybook]]></category>
            <category><![CDATA[engineering-design]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[figma]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Sebastian Balderas Espinosa]]></dc:creator>
            <pubDate>Thu, 05 Nov 2026 17:37:15 GMT</pubDate>
            <atom:updated>2026-11-05T18:02:17.709Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*V7OmzdB1KbH5PQ8vkB6ljA.jpeg" /></figure><h3>Every component in my Storybook has a Spec tab that turns its contract into one copyable brief. Here is what that looks like for one component, Alerts, and what writing it forces you to decide.</h3><p>Figma answers “what does it look like?” I use it to explore and to check direction with stakeholders, and it’s good at that. A story answers “what does it do?” The code answers “how does it work?”</p><p>None of them answers, in one place: what is this component, when should I use it, what must I never do with it, and which states and props does it have? That’s the brief someone needs before they use a component, whether that someone is a new engineer or an AI assistant generating a screen.</p><p>In my Portfolio UI System, that brief lives in a Spec tab on each component. The component I’ll use to show it is Alerts.</p><h3>What the Alerts entry contains</h3><p>The Alerts entry has a code selector with React, JSX, TypeScript, TSX, Python and NiceGUI. The Python version is real: the spec points to its NiceGUI source files, chat_banners.py and tokens.py.</p><p>The Spec tab turns the whole contract into one copyable file, spec-alerts.md: 231 lines, about 2,671 tokens, from build 12d6eff on 26 October 2026. Its sections are:</p><ul><li>What it is</li><li>When to use, and When not to use</li><li>Do, and Don’t</li><li>AI implementation notes</li><li>Props / API</li><li>States and Variants</li><li>Responsive behavior</li><li>Implementation contracts</li><li>Contrast &amp; accessibility</li><li>Environment</li><li>How it is built — the Python (NiceGUI) source</li></ul><h3>The first line decides who’s right</h3><p>The brief opens by addressing its reader directly: “You are an AI assistant building the Alerts of the Portfolio UI System… If this text and the source code ever disagree, the source code is right.”</p><p>That last sentence is the most important design decision in the file. A spec is documentation, and documentation drifts. Saying up front that the code wins means the spec can never become a second, competing source of truth. When they disagree, the fix is to update the text, not to “correct” the component to match it.</p><h3>The Don’t that prevents invention</h3><p>The line I’d point a team to is in the Don’t section. It tells the reader not to invent a warning tone: “this project has no ‘warning’ token and isn’t inventing one for this”.</p><p>An assistant asked to build an alert will reach for warning, because almost every system has one. A person will too. This line closes that door explicitly. The tones the system has are the tones it decided on, and anything else is a new decision for a person to make, not a gap for a tool to fill.</p><p>That’s the general value of writing a spec: every line you can’t write without guessing is a decision the system hasn’t made yet.</p><h3>Why one brief for both audiences</h3><p>I deliberately didn’t write one document for people and another for tools. Two documents drift. One brief that both read means a person reviewing a tool’s output can check it against the exact text the tool was given, including the contrast and accessibility section.</p><p>That’s the practical meaning of Storybook as the versioned, implemented contract for frontend and approved AI tooling to consume directly. Versioned, because the brief carries the build it came from. Implemented, because it describes what renders, and defers to the source when in doubt.</p><h3>Where this is going, labelled as direction</h3><p>This next part is a 2027 direction, not something I’ve delivered.</p><p>Today a person or an assistant copies the Spec tab. The obvious next step is for approved tools to read the same contract directly, through something like an MCP server, a component manifest and an AGENTS.md file in the repository that says which components exist and which rules apply. I think that’s where design systems are heading. I haven’t built it for a client.</p><p>What I can say from practice is that the hard part isn’t the protocol. It’s having a contract precise enough to be worth exposing.</p><h3>What I’d ask a team to try</h3><p>Pick one component. Write its brief as a single file: what it is, when to use and when not, Do and Don’t, props, states, variants, accessibility. Put the rule “the source code is right” at the top.</p><p>On my own system, having Storybook as the place where I already delivered directly in code is where the +35% in design-system velocity I’ve reported came from. I don’t have a documented baseline or period behind that number, so read it as my own assessment, not a controlled measurement.</p><p>What I deliver is a working product people use without friction. Not screens, and not the cycle of fixing them.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1be321171a21" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[When the status is “unknown”, name who knows]]></title>
            <link>https://medium.com/@sebastianbalderas/when-the-status-is-unknown-name-who-knows-68e3496436af?source=rss-5cb4627d7880------2</link>
            <guid isPermaLink="false">https://medium.com/p/68e3496436af</guid>
            <category><![CDATA[ux]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[product-design]]></category>
            <category><![CDATA[engineering-design]]></category>
            <category><![CDATA[accessibility]]></category>
            <dc:creator><![CDATA[Sebastian Balderas Espinosa]]></dc:creator>
            <pubDate>Thu, 05 Nov 2026 17:36:19 GMT</pubDate>
            <atom:updated>2026-11-05T18:01:27.339Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Rw6fKdM9HukfKdLxLIrL8A.jpeg" /></figure><h3>In Strata’s order line items table, some lines showed an “unknown” status because the order couldn’t be traced between manufacturer and carrier. The key decision was that “unknown” pointed to a human owner.</h3><p>In an earlier article about refining an inherited component, I described how the “unknown” status in Strata’s order line items table looked like a bug and turned out to be a real requirement. Some orders couldn’t be traced between the manufacturer and the carrier, so the table had to say so.</p><p>This piece is about what happens next: once you accept that “unknown” is true, how do you design it as a state in the system rather than a gap in the data?</p><p>Strata was a design system I inherited from Orderbahn and refined. It served contract office furniture, where manufacturers sell through dealers and no single participant sees the whole order. That context is why “unknown” exists at all.</p><h3>Why “unknown” isn’t empty, and isn’t an error</h3><p>Most status components are designed for the happy set: pending, in production, shipped, delivered. Everything else falls into two buckets the system already has. Empty, which means there’s nothing to show. Error, which means something broke.</p><p>“Unknown” is neither. The order exists. Nothing broke. The platform simply doesn’t know whether the line is with the manufacturer or with the carrier. If you render it as empty, people assume the data didn’t load. If you render it as an error, they assume someone made a mistake and start calling to find out whose.</p><p>So the first design decision is semantic: “unknown” is a status value with its own meaning, not the absence of one.</p><h3>What the state needs to carry</h3><p>A status that says “we don’t know” has to work harder than one that says “shipped”, because the person reading it needs to know what to do with it. In principle, an unknown state should carry:</p><ol><li>What is unknown. Here, specifically: whether the line is with the manufacturer or the carrier.</li><li>What is known. The rest of the line is still true: item, quantity, the order itself.</li><li>Who can find out. This is the part Strata got right, and the key point of this article.</li></ol><p>In Strata, the unknown status didn’t end in a dead end. It showed the person who knows that status, with their phone number to call or ask, plus an option to send them an email inside the platform. “Unknown” pointed to a human owner.</p><p>That matters because in a marketplace where several companies share an order, the missing information usually exists. It’s just in someone’s head, or on someone’s phone, at another company. A status that names that person turns “we don’t know” into “here’s who does”.</p><h3>The badge, as it was and as I’d build it today</h3><p>In Strata, the status badge was colour-based: for example, a red circle with an icon by error or notification type. It had no visible text; the text appeared on hover. In a dense table read by people who use it every day, that kept rows compact.</p><p>What I’d do today, from WCAG and my own practice since:</p><ul><li>Not colour alone (WCAG 1.4.1). The word “Unknown” visible in the cell, not only a colour and an icon.</li><li>Text that doesn’t depend on hover. Hover isn’t available on touch, and it isn’t the same as keyboard focus, so the meaning should be on screen or reachable both ways.</li><li>Contrast on the surface it sits on (1.4.3). A table row on a raised surface is a different background from the page; measure there.</li><li>Distinct from error. “Unknown” isn’t a failure, so it shouldn’t share error’s colour or icon.</li><li>The owner as part of the state. Keep what Strata already did: name, phone and in-platform email, reachable by keyboard.</li></ul><h3>Put it in Storybook as a story, not a footnote</h3><p>The reason this state felt like a bug at first is that nothing documented it. The fix for that is boring and effective: “unknown” gets its own story in the status component, with a docs line that explains when it appears and why it isn’t an error.</p><p>In Figma, the state is something to explore and check with stakeholders: does a dealer reading this understand it? In Storybook, it becomes part of the implemented, verifiable contract, with contrast checked on the rendered component. The next person who sees “unknown” in the product can find out in one click that it’s on purpose.</p><h3>The general rule</h3><p>Marketplaces where several companies share an order will always have gaps in what the platform knows. A design system that only models the happy path forces those gaps into “empty” or “error”, and both lie. Give “we don’t know” its own state, its own words, its own story, and a person who knows.</p><p>What I deliver is a working product people use without friction. Not screens, and not the cycle of fixing them.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=68e3496436af" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>