<?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 Theophile Kalumbu on Medium]]></title>
        <description><![CDATA[Stories by Theophile Kalumbu on Medium]]></description>
        <link>https://medium.com/@kalu_theo?source=rss-4533951d8cbd------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*877s7_-6b8Y23zLGfgxNIg@2x.jpeg</url>
            <title>Stories by Theophile Kalumbu on Medium</title>
            <link>https://medium.com/@kalu_theo?source=rss-4533951d8cbd------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 02:54:20 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@kalu_theo/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[Keeping AI on Track: Lessons from Doctolib’s Oxygen Design System]]></title>
            <link>https://medium.com/doctolib/keeping-ai-on-track-lessons-from-doctolibs-oxygen-design-system-9be5f9f041e8?source=rss-4533951d8cbd------2</link>
            <guid isPermaLink="false">https://medium.com/p/9be5f9f041e8</guid>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[context-engineering]]></category>
            <dc:creator><![CDATA[Theophile Kalumbu]]></dc:creator>
            <pubDate>Tue, 15 Sep 2026 05:27:30 GMT</pubDate>
            <atom:updated>2026-09-15T13:22:25.556Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How we created the Claude Oxygen Plugin to turn AI-generated prototypes into Design System-compliant code, and why Design Systems are becoming the harness for frontend AI agents.</em></p><figure><img alt="Toy-train hero illustration (“AI” engine pulling Context/Harness/Eval cars, sign reading “AI Augmented Design System”)." src="https://cdn-images-1.medium.com/max/1024/1*lezaicNGNBPMbrfAFuVmGA.png" /></figure><p>AI can turn a prompt into frontend code in minutes. With the right harness around it, a designer or product manager can do that without an engineer sitting next to them. Whether the result is trustworthy depends on three things: the <strong>ground-truth context</strong> you give the model, the <strong>harness</strong> you enforce around it, and the <strong>evaluation loop</strong> that tells you whether it’s still working.</p><p>This article focuses on how we used Context and Harness to make AI-generated frontend code Design System–compliant, and trustworthy enough to scale across feature teams.</p><p>One afternoon, Jérôme, our Staff Designer, and I tried something on a hunch: could we go from a single prompt to a React-ready screen that matches our Design System without opening Figma?</p><p>We picked a feature that didn’t exist yet: a “nurse logbook.” Claude Design generated three UX proposals. We chose one, left a couple of comments to steer the layout, then a skill we’d built read the prototype, comments and conversation and generated React code entirely based on our Design System components.</p><p>Thirty minutes, start to finish.</p><p>All that was left was wiring up the backend.</p><p>It felt like magic, and also like something we couldn’t fully trust.</p><p>The real question wasn’t whether AI could generate the screen. It was two narrower ones: was the generated code actually Design System-compliant, and could that hold up at scale across feature teams with real use cases?</p><figure><img alt="Slack screenshot: Jérôme reacting to Claude Design generating 3 UX proposals and 100% DS-compliant code in 30 minutes.”" src="https://cdn-images-1.medium.com/max/1024/1*CAVeTyxfupKv7fifmRWYGQ.png" /></figure><h3>01 · The engine is fast. That’s the problem.</h3><p>Ask an LLM to build a UI and it will write code fast. It will also confidently invent a CSS variable, reimplement an existing component, or use a prop that isn’t in your API.</p><p>The output compiles. It often looks right. It’s still wrong.</p><p><a href="https://www.kaelig.fr/design-system-components-with-ai-agent-teams/">A widely shared write-up from designer/engineer Kaelig Deloumeau-Prigent</a> illustrates the problem well. In an 8-agent design-to-code pipeline, the system once invented 27 plausible-looking CSS custom properties that simply didn’t exist.</p><p>Every test passed. The component rendered with no styling.</p><p>The model was fluent, not accurate.</p><p>The mental model that I like to use is the railway: <strong>AI is the train engine. The Design System provides the rails.</strong></p><p>We think about solving this in three parts:</p><ul><li><strong>Context: verified information instead of guesses.</strong></li><li><strong>Harness: machinery that constrains what the model can do.</strong></li><li><strong>Eval: continuous measurement of whether the output stays good.</strong></li></ul><p>Context tells the agent where the tracks are. Harness keeps it on them. Eval tells us whether it stays on track over time.</p><p>We’ve deliberately invested first in Context and Harness because they’re relatively straightforward engineering problems: <strong>make the ground truth consumable, then enforce it with deterministic guardrails.</strong></p><p>Eval is harder. It requires us to define what “good” means, measure it consistently, and evolve that definition as the system itself changes.</p><p><strong>That’s the next challenge.</strong></p><figure><img alt="the Context→Harness→Eval layer diagram (03 Eval “next challenge”, 02 Harness “steers + enforces”, 01 Context “ground truth, not guesses”)." src="https://cdn-images-1.medium.com/max/1024/1*D2xuq4uuM8RBDBGESEgBDQ.png" /></figure><h3>02 · Context: lay the tracks first</h3><p>Before AI can consume a Design System, the Design System has to exist as structured data, not as a folder of components a senior engineer has memorized.</p><p>At the foundation are <strong>design tokens: named values that encode design decisions such as color, spacing, typography, or radius in a machine-readable form.</strong></p><p>Our tokens live in a <a href="https://www.designtokens.org/">DTCG-format JSON</a> source and flow through Style Dictionary into CSS custom properties, TypeScript exports, and other platform-specific formats.</p><p>But exposing every raw token to an agent isn’t the goal. <strong>Tokens are the foundations of the Design System, not the interface developers, or agents, should build with directly.</strong></p><p>As Brad Frost describes in his <a href="https://bradfrost.com/blog/post/the-many-faces-of-themeable-design-systems/">three-tier token architecture</a>, raw values flow into semantic tokens, then into component-specific tokens that ultimately power UI components.</p><p>That hierarchy becomes especially valuable with AI. Instead of letting the model choose freely from hundreds of colors, spacing values, and primitives, we narrow its vocabulary: <strong>use the right component first, and let the component carry the right tokens.</strong></p><p>In other words, we’re not teaching the AI how to design from primitives. We’re giving it the same paved path we want humans to follow, only in a form it can query and validate.</p><p>The other half is an MCP server exposing our live Storybook documentation: real component props, usage stories, written guidance, and the markdown that surrounds the code itself, guidelines and READMEs included, not just the component code.</p><p>Instead of recalling roughly what a component API should look like from training data, the model queries the API we actually have.</p><p>That removed one of our biggest sources of unusable generated code: hallucinated props and invented components.</p><h3>03 · Harness: where the rails become real</h3><p><strong>Ground truth tells the model what’s true. The harness turns that knowledge into consistent behavior.</strong></p><p>Our harness uses two complementary kinds of guardrails: <strong>instructions</strong> and <strong>hooks</strong>. They solve different problems, and we need both.</p><p><strong>Instructions guide how the model works:</strong></p><ul><li>Read and ensure sufficient context is provided before starting.</li><li>Build Storybook stories alongside visible UI.</li><li>Verify implementations visually against Figma.</li><li>Write accessibility tests as part of each feature.</li><li>Keep changes minimal and scoped.</li><li>Stop and ask rather than guess when requirements are unclear.</li></ul><p>These guardrails require judgment. You can’t deterministically check whether a requirement is ambiguous or whether an implementation looks right. The model needs context to make those calls. We typically define these instructions at the end of our skill Markdown files, where they act as behavioral guardrails for the model.</p><p><strong>Hooks enforce what must always be true:</strong></p><ul><li>Block raw Tailwind utility classes in components.</li><li>Require generated code to pass accessibility and visual checks before commit.</li><li>Require type checking and linting before code is accepted.</li></ul><p>Hooks don’t rely on the model remembering or following an instruction. They’re deterministic scripts, triggered automatically at specific points in the workflow, that can block an action when a rule is violated.</p><p>The distinction isn’t <strong>instructions vs. hooks</strong>. It’s about choosing the right mechanism for each constraint: use instructions where judgment is required; use hooks where a rule can be enforced deterministically.</p><blockquote><strong>Together, instructions steer the model toward the right implementation, while hooks enforce the boundaries it can’t cross. The harness brings both together and keeps the Design System from going off the rails when nobody’s watching.</strong></blockquote><h3>A pipeline, not a prompt</h3><p>The most concrete artifact we’ve built is a skill inside our internal Claude Design System plugin. It turns a Claude Design prototype into React code against Oxygen.</p><p>It runs as a pipeline:</p><ol><li>Fetch the design bundle.</li><li>Read its notes and conversation to recover design intent.</li><li>Parse the HTML/CSS to identify the actual UI elements.</li><li>Map each element to a verified Design System component through our documentation server.</li><li>Plan forms and layout using our standard primitives.</li><li>Generate component code and scoped styles.</li><li>Self-review against a fixed Design System checklist.</li><li>Run typecheck and a production build, and only report success if both pass.</li></ol><p>“Generate the code” is one step out of eight.</p><p>Our self-review isn’t a vague “check your work” prompt either. It runs against a checklist versioned in the plugin itself, covering five categories:</p><ul><li>Tailwind style</li><li>Component overrides</li><li>Token hierarchy</li><li>Component API</li><li>Composition</li></ul><p>Each finding gets one of three severity levels:</p><ul><li>Error: a wrong import path, an invented token, a className override, or a missing accessibility prop</li><li>Warning: a v1 component used where v2 exists, or a primitive token used where a semantic one exists</li><li>Suggestion: a redundant wrapper, or a Tailwind class that could become a prop</li></ul><p>A sibling checklist turns the same idea into a weighted score: Score = max(0, 100 − (weighted penalty / total surface) × 100), where an error costs 5 points, a warning 3, and a suggestion 1. That’s where “compliant” gets a number instead of a feeling.</p><h3>How we reached 97% DS Compliant code</h3><p>The real unlock wasn’t a smarter prompt. It came from sitting with the team that would actually use the tool.</p><p>The team “BEES” (Better care through Enrichment &amp; Structuration), owns the structured medical-history and codification layer of the EHR: conditions, diagnoses, observations, Health View Their first ticket through our pipeline, asked for a ModelCard component to browse a patient’s medical history (allergies, conditions) in the new patient file’s Health View.</p><p>Nicolas, one of our own DS engineers, worked directly inside their codebase and managed to reach 97% DS compliance* on the generated code for the ModelCard component.</p><p>Getting there required two important changes.</p><p>First, we replaced our monolithic code-review agent with an <strong>orchestrator and focused sub-agents</strong>, each responsible for a specific part of the review and loading only the rules it needed. This moved compliance from <strong>65% to 87%</strong> and made this approach the foundation for our other AI workflows.</p><p>Second, testing against a real product showed us that <strong>not every deviation from the Design System means the same thing</strong>. We found three distinct cases:</p><ul><li><strong>Missing AI Context:</strong> the right DS capability existed, but the agent couldn’t discover it.</li><li><strong>Missing DS capability:</strong> the product exposed a legitimate, reusable need that Oxygen didn’t support yet.</li><li><strong>Legitimate custom UI:</strong> the need was product-specific and didn’t belong in the Design System in the first place.</li></ul><p>This also explains why <strong>100% isn’t necessarily the goal</strong>. What matters is that deviations are intentional: use the Design System when the right solution exists, improve it when a reusable capability is missing, and go custom when the need genuinely belongs to the product.</p><blockquote><strong>The lesson: better results didn’t come from better prompting. They came from better architecture, better Context, and testing against real product work, where compliance means making the right choice, not blindly chasing 100%.</strong></blockquote><p><em>* That number needs a caveat. It’s one measured run, not a running average. It measures compliance at generation time, not whether that compliance survives weeks of subsequent changes.</em></p><h3>From prototype to tool</h3><p>We then added a second entry point for teams starting in Figma, using its MCP integration, REST API, or, as a last resort, a screenshot. This isn’t a fallback path. Figma remains the default starting point for most design handoffs today, and Figma-to-code drift, especially designs that reference components that don’t yet exist in Storybook, remains the most frequently cited frustration in our designer interviews. Prompt-to-code is gaining ground, but it hasn’t replaced Figma as the source of truth.</p><p>Different starting points, same rails: verified component mapping, token resolution, and enforcement gates.</p><blockquote><strong>The next test is adoption. We’re starting to put the workflow in front of the people it was built for: designers, software engineers, and PMs. The question is no longer whether the pipeline works, but whether it becomes part of how teams actually build.</strong></blockquote><h3>04 · What we’d tell another Design System team</h3><p>The most reusable thing we’ve learned isn’t a particular Claude command or MCP server. It’s the <strong>Context → Harness → Eval</strong> model.</p><p><strong>Build Context first.</strong> Turn your Design System into structured, queryable ground truth: if a human can only understand it by reading source code and tribal knowledge, an agent will struggle just as much.</p><p><strong>Invest heavily in Harness.</strong> Don’t rely on the model remembering your rules: put the constraints that actually matter into hooks, lint rules, type systems, builds, and branch protection.</p><p><strong>Don’t skip eval, and don’t fake it.</strong> A great demo, or even a 97% result, tells you what happened once. Only a system that keeps checking tells you whether it’s still trustworthy.</p><p>That’s our next step, and we plan to wire it through evaluation tools such as Braintrust instead of building our own scoring harness from scratch.</p><p>AI gives you the engine.</p><p><strong>Your Design System gives it the rails.</strong></p><p>Want to help build the rails? We’re hiring across Design System and Frontend engineering: see our <a href="https://careers.doctolib.com/jobs/">open roles here</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9be5f9f041e8" width="1" height="1" alt=""><hr><p><a href="https://medium.com/doctolib/keeping-ai-on-track-lessons-from-doctolibs-oxygen-design-system-9be5f9f041e8">Keeping AI on Track: Lessons from Doctolib’s Oxygen Design System</a> was originally published in <a href="https://medium.com/doctolib">Doctolib</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[From Stories to Software: Enhancing Communication with Domain Storytelling (Part 1)]]></title>
            <link>https://medium.com/@kalu_theo/from-stories-to-software-enhancing-communication-with-domain-storytelling-part-1-fac6594ad6ac?source=rss-4533951d8cbd------2</link>
            <guid isPermaLink="false">https://medium.com/p/fac6594ad6ac</guid>
            <category><![CDATA[domain-driven-design]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[domain-storytelling]]></category>
            <dc:creator><![CDATA[Theophile Kalumbu]]></dc:creator>
            <pubDate>Tue, 05 Mar 2024 22:57:42 GMT</pubDate>
            <atom:updated>2024-03-09T10:39:36.548Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="African Griot telling story to an audience (image generated by Author with AI)" src="https://cdn-images-1.medium.com/max/1024/1*GaxO-6Lvv_5kHNx9WtVoeA.png" /><figcaption>African Griot telling stories to his fellows ( image generated with AI by the Author)</figcaption></figure><p>This is the first article in a three-part series that delves into the concept of Domain Storytelling. This series will guide you through the process of using Domain Storytelling as a tool to simplify complex systems into relatable narratives. In the upcoming articles, we will explore how to use Domain Storytelling to identify bounded contexts in Domain-Driven Design (DDD), a crucial step in creating well structured software systems. Lastly, we will discuss how to create live documentation using Domain Storytelling, enhancing communication, collaboration, and knowledge sharing among stakeholders. Stay tuned as we unfold the power of storytelling in the realm of software development.</p><h3>Introduction</h3><p>Throughout history, the art of storytelling has played a pivotal role in shaping cultures around the world, serving not just as a vessel for entertainment but as a crucial means of education and the preservation of collective memory and values. This tradition, epitomized by the<a href="https://en.wikipedia.org/wiki/Griot"> African griots</a> whose narratives have breathed life into the histories and wisdom of their communities for centuries, demonstrates the profound impact of storytelling in connecting individuals across time and space. In the domain of software development, however, the challenge of conveying complex concepts effectively has often led to misunderstandings and the derailment of projects, with a notable portion succumbing to the pitfalls of miscommunication. While traditional methodologies like <a href="https://en.wikipedia.org/wiki/Unified_Modeling_Language">Unified Modeling Language (UML) </a>and<a href="https://www.bpmn.org/"> Business Process Modeling and Notation (BPMN) </a>have been staples in the documentation of systems and business processes , their capacity to fully bridge the communicative divide between diverse project stakeholders has shown some limitations.</p><p>Acknowledging the existing gap, D<a href="https://domainstorytelling.org/">omain Storytelling</a> has surfaced as a reliable alternative. It looks to pivot towards a narrative-focused viewpoint that puts user experience first. This article delves into the advantages of domain storytelling, suggesting it as a game-changing tool. This approach aims to boost comprehension and teamwork within the intricate world of software development.</p><h3>From UML to Domain Storytelling</h3><p>When asked to model system designs, software engineers are mainly relying on Unified Modeling Language (UML), which is a powerful and mature tool that offers a standardized way to visualize the design and architecture of software systems. More surprisingly, UML can also be used to model business process through the lenses of behavioral diagrams such as the <a href="https://en.wikipedia.org/wiki/Activity_diagram">Activity Diagram</a>, or <a href="https://en.wikipedia.org/wiki/Sequence_diagram">Sequences Diagrams</a> which focuses on the dynamic aspects of a system.</p><p>Let’s explore Activity Diagrams. These diagrams can sequentially and concurrently represent activities, detail the objects an activity consumes, uses, or creates, and pinpoint who is responsible for each activity (see Figure 1). They also depict the relationships and dependencies among activities. With these features, they serve as great tools for business process modeling.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/538/1*d7gvcSciO72kv7qvR5TlWg.png" /><figcaption>Figure 1: Activity use case of money withdrawal and deposit (Done by Author with PlanText UML Editor)</figcaption></figure><p>Although versatile and highly potent, this kind of representation can be difficult for business stakeholders to comprehend. For example, the Activity Diagram incorporates over ten concepts, including the Initial Node, Decision, Guard Condition, Fork, Join, and others (see Figure 2). While these notations may be clear to engineers, they might not be as understandable for non-technical individuals.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/600/1*OlGFDYS9kyga9vedW5pDug.png" /><figcaption>Figure 2: Activity Diagram list of concepts (image courtesy of <a href="https://www.edrawsoft.com/">Edrawsoft</a>.)</figcaption></figure><p>This complexity can create a barrier to effective communication between the technical and business teams. When this communication is not seamless and clear, it often leads down a path resulting in the implementation of software that does not fully meet the intended goals or the needs of the end-users.</p><h3>Domain Storytelling: A Different Approach</h3><p>Domain storytelling is a technique developed by Stefan Hofer and Henning Schwentner in 2016. It is deeply rooted in the principles of Domain-Driven Design (DDD). This method simplifies complex business processes and software systems by using the universally understood language of storytelling. It encourages all project stakeholders to use a shared language.</p><p>This method values real-world examples and user experiences, transforming intricate concepts into simple narratives. It allows all stakeholders, even those without a technical background, to easily understand the complexities of a system or process, effectively bridging the gap between technical and non-technical team members.</p><p>Moreover, integrating domain storytelling with DDD initiates a significant shift in software development. DDD, a design philosophy, emphasizes focusing on the core domain and domain logic, with complex designs based on a model of the domain. This combination with domain storytelling ensures the software design aligns closely with business needs, helping to avoid potential misunderstandings that could hinder a project.</p><p>Lastly, domain storytelling introduces just four concepts, making it easier to understand, which we will explore later on.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/692/1*--A-f3-YsHRUZ2Rfs2tWzA.png" /><figcaption>Figure 3: Simplified Domain Storytelling for a travel booking process</figcaption></figure><p>By stringing together these elements in a logical sequence, a domain story effectively illustrates the flow and relationships of a system or process. It provides a holistic view that goes beyond the technical details, revealing the underlying motivations and goals of the actors, and showcasing the real-life impact and implications of the system or process.</p><h3>Anatomy of Domain Storytelling</h3><p>Domain stories are made up of several key elements that together form a comprehensive and coherent narrative:</p><ul><li><strong>Actors</strong>: These are the individuals, systems, or entities that perform actions within the domain. They play crucial roles in the story and are typically represented by pictograms or symbols. Their actions and interactions form the backbone of the narrative, making them integral to the overall story.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/380/1*tSz7gPWIVo34rSE9FNA_3A.png" /></figure><ul><li><strong>Work Objects</strong>: These are the items or entities that the actors interact with throughout the story. They could be physical objects, information, or even other actors. Understanding the work objects is key as they often represent the tangible outcomes or products of the actors’ actions.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/334/1*JjGAHmninAXwHYk1jIISzg.png" /></figure><ul><li><strong>Activities</strong>: These are the actions performed by the actors on the work objects. Activities are usually represented as verbs and form the core of the narrative. They define the tasks or operations that the actors carry out and contribute to the progression of the story.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/484/1*ZZLe3W03XlDe-8t3SDHW7Q.png" /></figure><ul><li><strong>Annotations</strong>: These provide additional context or specific details about the activities, actors, or work objects. Annotations can help to clarify the story, elaborate on the significance of certain actions, or provide additional insights that add depth to the narrative.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/348/1*kBrZy6q_okdxsGK2sPdk6A.png" /></figure><p>By understanding and effectively utilizing these components, one can create a domain story that is not only relatable and easy to understand but also comprehensive and rich in detail. This can significantly enhance communication and understanding among all stakeholders, fostering a more collaborative and efficient software development environment.</p><p>One of the most powerful advantages of domain storytelling is its accessibility, as stories are presented in plain English. This makes it a highly intuitive method for conveying complex concepts and processes.</p><p>For example , the story shown in Figure 3 can be read loud like that :</p><blockquote>“The Traveler books a ticket from the Travel Company”</blockquote><blockquote>“ The Travel Company issues a ticket to the Traveler”</blockquote><p>By transforming abstract system designs and business processes into easy-to-understand narratives, domain storytelling allows stakeholders from all backgrounds to grasp the intricacies of a system or process without needing specialized technical knowledge.</p><p>This approach also encourages a more collaborative environment, as everyone can actively participate in the discussion and contribute their unique insights. Furthermore, by putting the user experience at the forefront, domain storytelling ensures that the end product is closely aligned with the needs and expectations of the end-users, leading to more successful and user-friendly software solutions.</p><h3>Limitations</h3><p>Domain storytelling has its advantages, but it’s not without drawbacks. Its simplicity, while beneficial, can sometimes skip over complex details like conditional statements or interactions, possibly missing out on showing different outcomes in one scenario.</p><p>It might also simplify scenarios too much, ignoring edge cases that, although less common, are crucial for understanding a system’s full scope and potential issues. This method tends to focus on the ‘happy flow’ — situations where everything works as planned, covering about 80% of cases. This focus can overlook the importance of less ideal scenarios, such as errors or exceptions, leading to a partial view of how the system operates under various conditions and potentially overlooking key design or implementation aspects.</p><p>One way to address these shortcomings is to create storytelling diagrams with varying levels of detail. For instance, in a travel booking process, we could create a detailed diagram focusing on booking cancelation. This would highlight how a last minute cancelation could affect the refunding of the client. Alternatively, these diagrams could be supplemented with traditional UML representations. There’s no restriction on combining activity diagrams for details and domain storytelling for an overview.</p><h3>Conclusion</h3><p>Effective communication is vital in software development. Domain storytelling has become an innovative method that bridges the gap between technical and non-technical stakeholders. It turns complex systems into relatable narratives, enhancing understanding, promoting collaboration, and helping prevent software failures often caused by communication gaps.</p><p>This method transforms insights into visual representations in technical documentation, giving software engineers a comprehensive understanding of the system’s functionality.</p><p>For developers and tech leaders, it’s beneficial to incorporate storytelling into your work and engage stakeholders in this process. Using domain storytelling can improve team communication, collaboration, and knowledge sharing. This method simplifies development processes and creates software solutions that align with end-users’ needs. It’s similar to how African griots’ narratives reflected their communities’ needs and values. In our next article, we’ll discuss how Domain Storytelling diagrams can identify bounded contexts, a crucial concept in software architecture. Understanding bounded contexts can lead to more efficient and robust software systems, further emphasizing the importance of effective storytelling in technical environments.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fac6594ad6ac" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Announcing Elm UI Explorer 2.0]]></title>
            <link>https://medium.com/@kalu_theo/announcing-elm-ui-explorer-2-0-7e6db140d66?source=rss-4533951d8cbd------2</link>
            <guid isPermaLink="false">https://medium.com/p/7e6db140d66</guid>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[elm]]></category>
            <category><![CDATA[web-development]]></category>
            <dc:creator><![CDATA[Theophile Kalumbu]]></dc:creator>
            <pubDate>Thu, 30 May 2019 19:49:33 GMT</pubDate>
            <atom:updated>2019-05-30T19:52:43.938Z</atom:updated>
            <content:encoded><![CDATA[<h4>A tool for browsing and documenting your Elm views in an isolated development environment.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/414/1*4elY0BegZ7CRpDzBfpZlHw.png" /></figure><p>Today, I am excited to announce the publication of <a href="https://package.elm-lang.org/packages/kalutheo/elm-ui-explorer/latest">Elm UI Explorer 2.0</a>! This is a major release that includes:</p><ul><li>🔌 <strong>Simplified API: </strong>for an easier usage</li><li>⚙️<strong> New plugins system: </strong>for extending the tool</li><li>🖍 <strong>Customization: </strong>to match your brand identity</li><li>🎨 <strong>Complete redesign: </strong>fresh and minimalist</li></ul><h3>A little bit of history</h3><p>Elm is, in my opinion, the best frontend language to build reliable web applications. The <a href="https://guide.elm-lang.org/types/">type safety</a> it guarantees and it’s <a href="https://guide.elm-lang.org/architecture/">built in architecture</a> makes working with it an absolute joy.</p><blockquote>However, tools for quickly building &amp; browsing UI elements in isolation sadly lack in Elm.</blockquote><p>If like me, you are a developer coming from the JavaScript world, then I am sure that you already came across <a href="https://storybook.js.org/">Storybook</a>.</p><p>This tool has revolutionized the way we approach UI development. In fact, it provides a great development environment that allows you to develop, test, and document your UI elements seamlessly.</p><p>I always dreamt about this kind of tool for the Elm eco-system, and that is why 2 years ago, I decided to create <a href="https://github.com/kalutheo/elm-ui-explorer">Elm UI Explorer</a> for Elm 0.18. A library that deals with browsing and documenting your Elm views in an isolated environment just like Storybook.</p><p>This project was a real success as it allows :</p><ul><li><strong>Increased productivity:</strong> Just combine live reloading or hot reloading with Elm UI Explorer and enjoy building your views without opening your App;</li><li><strong>Better communication:</strong> Provides a way to lay down all your views and their states in one place. It acts as a single source of truth, which facilitates collaboration with other developers or even designers.</li></ul><blockquote>Now It‘s time to bring Elm UI Explorer to Elm 0.19 with version 2.0.</blockquote><h3>A <strong>Simplified API</strong></h3><p>Suppose that you have built this simple Elm view:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/2e0abb554c8919663cfaed14c278e05a/href">https://medium.com/media/2e0abb554c8919663cfaed14c278e05a/href</a></iframe><p>If you need to explore possible states of this button in Elm UI Explorer, just run the following snippet:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/f02c6a45ef17d2477111f53eb2c88891/href">https://medium.com/media/f02c6a45ef17d2477111f53eb2c88891/href</a></iframe><figure><img alt="" src="https://cdn-images-1.medium.com/max/948/1*Zu3POnEtBTbsazvKhb3A-A.gif" /><figcaption>Here is the result on UI Explorer</figcaption></figure><h3>Extensible with plugins</h3><p>Elm UI Explorer 2.0 version has been developed with extensibility in mind.<br>This new version comes with some built-in plugins such as the <a href="https://package.elm-lang.org/packages/kalutheo/elm-ui-explorer/latest/UIExplorer-Plugins-Note">Notes Plugin</a>.</p><p>This Plugin allows you to add markdown notes to your stories like that:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/387ce88864e8b60c91d50cd0e44d4402/href">https://medium.com/media/387ce88864e8b60c91d50cd0e44d4402/href</a></iframe><p>Then you should see some rich HTML content below your story:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-rC--8d49CA3auNnwoHX0g.png" /></figure><p>This is perfect for enriching the documentation of your views.</p><h3>Customizable</h3><p>The new configuration type allows you to change the look and feel of the header.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/0c786d921f29119f7178bc6315d041a7/href">https://medium.com/media/0c786d921f29119f7178bc6315d041a7/href</a></iframe><p>You can customize the title, logo, and even the colors to make the explorer match your brand identity.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1ZLg5gvNNlceOcscxggtUA.png" /><figcaption>Before customization</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NEHveTrHZVCH7AEdjnKBdA.png" /><figcaption>After customization</figcaption></figure><h3>A brand new design</h3><p>A more subtle and minimalist design has been integrated to Elm UI Explorer. This allows us to focus more on your visual content and reduces noise.</p><p>Example of a <a href="http://atomicdesign.bradfrost.com/chapter-1/">Design System</a> built with UI Explorer:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qR2l3zP66GUDjLVU-nmuvA.png" /><figcaption>The Design Home Page using Markdown</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9jvPjFTdENeirAEL0UEPOg.png" /><figcaption>The Design System Color Palette</figcaption></figure><h3><strong>Check it out!</strong></h3><p>I invite you to <a href="https://github.com/kalutheo/elm-ui-explorer">try it </a>and check out the examples where you will find some useful codes samples to get you started. Feedbacks and PR are always welcome!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7e6db140d66" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Say Yo ! Or how to kickstart your Elm Spa in a snap]]></title>
            <link>https://medium.com/@kalu_theo/say-yo-or-how-to-kickstart-your-elm-spa-in-a-snap-4a2d7f649e37?source=rss-4533951d8cbd------2</link>
            <guid isPermaLink="false">https://medium.com/p/4a2d7f649e37</guid>
            <dc:creator><![CDATA[Theophile Kalumbu]]></dc:creator>
            <pubDate>Tue, 20 Nov 2018 11:30:20 GMT</pubDate>
            <atom:updated>2019-02-27T09:54:54.679Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/304/1*IP-lmHnYpt7K3irBowHKvA.jpeg" /></figure><p>Lately I was animating an Elm Workshop at work. One of my teammates who was attending the session asked me the following question :</p><blockquote>How do you create a multipage application with Elm ?</blockquote><p>When I introduce Elm to beginners, I always recommend for them to go and read the official <a href="https://guide.elm-lang.org/">Elm Guide</a>. It’s an awesome resource with very simple examples to get them started.</p><p>So i sent her the <a href="https://guide.elm-lang.org/webapps/navigation.html">navigation chapter of the guide</a> that shows how to build an SPA (<a href="https://en.wikipedia.org/wiki/Single-page_application">Single Page Application</a>) with Elm. I asked her to read it and follow the tutorial to build her program.</p><p>The code provided in the guide is very straightforward:</p><pre>import Browser<br>import Browser.Navigation as Nav<br>import Html exposing (..)<br>import Html.Attributes exposing (..)<br>import Url<br><br><br><br>-- MAIN<br><br><br>main : Program () Model Msg<br>main =<br>  Browser.application<br>    { init = init<br>    , view = view<br>    , update = update<br>    , subscriptions = subscriptions<br>    , onUrlChange = UrlChanged<br>    , onUrlRequest = LinkClicked<br>    }<br><br><br><br>-- MODEL<br><br><br>type alias Model =<br>  { key : Nav.Key<br>  , url : Url.Url<br>  }<br><br><br>init : () -&gt; Url.Url -&gt; Nav.Key -&gt; ( Model, Cmd Msg )<br>init flags url key =<br>  ( Model key url, Cmd.none )<br><br><br><br>-- UPDATE<br><br><br>type Msg<br>  = LinkClicked Browser.UrlRequest<br>  | UrlChanged Url.Url<br><br><br>update : Msg -&gt; Model -&gt; ( Model, Cmd Msg )<br>update msg model =<br>  case msg of<br>    LinkClicked urlRequest -&gt;<br>      case urlRequest of<br>        Browser.Internal url -&gt;<br>          ( model, Nav.pushUrl model.key (Url.toString url) )<br><br>        Browser.External href -&gt;<br>          ( model, Nav.load href )<br><br>    UrlChanged url -&gt;<br>      ( { model | url = url }<br>      , Cmd.none<br>      )<br><br><br><br>-- SUBSCRIPTIONS<br><br><br>subscriptions : Model -&gt; Sub Msg<br>subscriptions _ =<br>  Sub.none<br><br><br><br>-- VIEW<br><br><br>view : Model -&gt; Browser.Document Msg<br>view model =<br>  { title = &quot;URL Interceptor&quot;<br>  , body =<br>      [ text &quot;The current URL is: &quot;<br>      , b [] [ text (Url.toString model.url) ]<br>      , ul []<br>          [ viewLink &quot;/home&quot;<br>          , viewLink &quot;/profile&quot;<br>          , viewLink &quot;/reviews/the-century-of-the-self&quot;<br>          , viewLink &quot;/reviews/public-opinion&quot;<br>          , viewLink &quot;/reviews/shah-of-shahs&quot;<br>          ]<br>      ]<br>  }<br><br><br>viewLink : String -&gt; Html msg<br>viewLink path =<br>  li [] [ a [ href path ] [ text path ] ]</pre><p>We won’t go into the details of this snippet (The Elm guide gives great explanations), but as you can see, it’s kind of a lot of boilerplate to write !</p><p>From here I realized that every time someone needs to create a small App in Elm, he will have to:</p><ol><li>Visit the Guide;</li><li>Find this snippet;</li><li>Copy and paste this code into his editor;</li><li>Install dependencies;</li><li>Run the App.</li></ol><p>Come one! There should be a better way to do that!</p><h3>Just use a boilerplate</h3><p>Many people have already come across this question.</p><blockquote>How can I get started quickly when building a new Elm App ?</blockquote><p>The obvious answer is to use a “Boilerplate”.<br>In Elm here are the most famous ones:</p><ul><li><a href="https://github.com/halfzebra/create-elm-app">Create Elm App</a></li><li><a href="https://github.com/rogeriochaves/spades">Elm spades</a></li></ul><p>Although these are awesome projects that can help you get productive very quickly, they suffer from the same drawbacks: They come with a bunch of tools that you may not need at the beginning and especially when you are just learning Elm.</p><blockquote>Webpack, Service Worker, Live reloading, Server Side Rendering etc…. These are great tools that come out of the box with such boilerplates, but they add some complexity</blockquote><h3>Just say Yo !</h3><p>Then I remembered this project I heard about those days, when I was doing some angular JS: <a href="http://yeoman.io/">Yeoman</a></p><blockquote>Yeoman helps you to kickstart new projects, prescribing best practices and tools to help you stay productive.</blockquote><blockquote>To do so, we provide a generator ecosystem. A generator is basically a plugin that can be run with the ‘yo’ command to scaffold complete projects or useful parts.</blockquote><blockquote>(Official Yeoman Documentation)</blockquote><p>This is exactly what we need. Just say ‘yo’ and it generates an Elm app for you.</p><h3>Here comes Elm Starter Kit Generator</h3><p>So i created a simple Yeoman Generator called <a href="https://github.com/kalutheo/generator-elm-starter-kit">Elm-starter-kit</a>.<br>The goal of this command is to help you create and bootstrap a minimalist Elm Application. No webpack, no modules, just a single Main.elm file with a minimal amount of code to run your application.</p><p>Just to be clear, it’s not meant to replace boilerplates, but it can be used at first before moving to them once your project becomes more complex.</p><p>Let me show you how it works:</p><p>Just open a new folder and run the following commands</p><ol><li>npm i -g yo &amp;&amp; npm i -g generator-elm-starter-kit;</li><li>yo elm-starter-kit;</li><li>Enter the name of your project;</li><li>Select the type of the application (sandbox, application etc….)</li><li>After the installation is complete, your app is running on htttp://localhost:8000.</li></ol><p>Starting your project like this comes with the following advantages:</p><ul><li>No need to copy and paste some code manually. It’s fast and direct.</li><li>The code fits in a single Main.elm file. It’s a known best practice to start your application small and add modules only when your app starts to be big and hard to reason about (<a href="https://www.youtube.com/watch?v=XpDsk374LDE&amp;feature=youtu.be">see the Life of a File by Evan Czaplicki</a>)</li></ul><h3>Conclusion</h3><p>I find that sometimes it’s very difficult for people learning a new language to find good examples to get started. Elm maintainers did a great job with the documentation, Elm Guide etc…. But still, people want to get productive very quickly.</p><p>Boilerplates are great for that, but they can come with a high cost in complexity.</p><p>In this article we have seen that Elm Starter kit is just another tool that can be added to your toolbox if you want to start your Elm journey in a fast and simple way.</p><p>And you? What tool do you use when you have a new Elm app to create?</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4a2d7f649e37" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>