<?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 Sasha Zinchuk on Medium]]></title>
        <description><![CDATA[Stories by Sasha Zinchuk on Medium]]></description>
        <link>https://medium.com/@a.zinchuk.a?source=rss-7b7a33654f75------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*Zh0u8m_Si4goAnHjTL3qLQ.jpeg</url>
            <title>Stories by Sasha Zinchuk on Medium</title>
            <link>https://medium.com/@a.zinchuk.a?source=rss-7b7a33654f75------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 11:34:52 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@a.zinchuk.a/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[Flo design system: Part 2]]></title>
            <link>https://medium.com/flo-health/flo-design-system-part-2-0848c4623081?source=rss-7b7a33654f75------2</link>
            <guid isPermaLink="false">https://medium.com/p/0848c4623081</guid>
            <category><![CDATA[product-management]]></category>
            <category><![CDATA[design]]></category>
            <category><![CDATA[mobile-app-development]]></category>
            <category><![CDATA[engineering]]></category>
            <category><![CDATA[design-systems]]></category>
            <dc:creator><![CDATA[Sasha Zinchuk]]></dc:creator>
            <pubDate>Mon, 06 Jan 2025 16:19:01 GMT</pubDate>
            <atom:updated>2025-01-06T16:27:11.616Z</atom:updated>
            <content:encoded><![CDATA[<h3>Flo design system: Part 2. Time to automate!</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*KtLOCtSPDdMkpgifAMf2uA.png" /></figure><p><a href="https://medium.com/flo-health/flo-design-system-part-1-1eb8b731a48c">In the first part</a> of the article, we dived into <strong>Flo Design System (DS)</strong> history, and described improvements we made in Figma files structure to use it as a source. This part is slightly more technical and focuses on automated token export.</p><h3>Picking a solution for DS export</h3><p>We made our Figma files look good and organized all styles and components, so what options did we have for exporting design tokens from Figma to code?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*g6oIxrd_wjtTaDCYn1vmPw.png" /></figure><p>After reading DS-related articles, attending <a href="https://www.intodesignsystems.com/">conferences</a>, and reviewing product websites, we came up with the following comparison table.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bQ4W9Uhbf42dyymp68dpPQ.png" /></figure><p>As you can see, we were choosing between external DS platforms and building our own DS pipeline on top of <a href="https://styledictionary.com/">Style Dictionary</a>.</p><p>Establishing design tokens requires significant upfront investment. However, once implemented, they require minimal, infrequent maintenance. This might suggest that specialized tooling for design token management is unnecessary.</p><p>After comparing costs and benefits, we chose to build a pipeline on top of Style Dictionary, bearing in mind that later on we could easily adopt a Figma plugin or an external DS platform because all these tools are compatible with Style Dictionary and <a href="https://design-tokens.github.io/community-group/format/">W3C Design Token Format</a>.</p><h3>Style Dictionary basics</h3><p><a href="https://styledictionary.com/">Style Dictionary</a> is a build system that helps manage design tokens in a <strong>platform-agnostic</strong> way.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hlbuP8PKRa7bb3SZM2l4mQ.png" /><figcaption>Illustration by Graham Annable (<a href="https://www.instagram.com/p/C9m8itPKe3m">@grickle14</a>), shared with the author’s permission</figcaption></figure><p>The core concept is defining design tokens in a <strong>single source of truth</strong> (usually JSON or YAML file) and then transforming them into formats that different platforms can consume. You can define any token structure or use the following proposed <a href="https://styledictionary.com/info/tokens#category--type--item">Category / Type / Item</a> one:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RkNVXVWLZjrtfgzWik3SYQ.png" /></figure><p>Style Dictionary also supports <strong>aliases — references to other tokens</strong>, allowing you to create relationships and reuse values, which increases flexibility and adds semantics:</p><pre>{<br>  &quot;size&quot;: {<br>    &quot;font&quot;: {<br>      &quot;small&quot;: { &quot;value&quot;: &quot;12px&quot; },<br>      &quot;medium&quot;: { &quot;value&quot;: &quot;16px&quot; },<br>      &quot;large&quot;: { &quot;value&quot;: &quot;24px&quot; },<br>      &quot;base&quot;: {<br>        &quot;value&quot;: &quot;{size.font.medium.value}&quot;,<br>        &quot;comment&quot;: &quot;Default value if not set&quot;<br>      }<br>    }<br>  }<br>}</pre><p>In the example above, there are:</p><ul><li>4 token <strong>names</strong> (“small”, “medium”, “large”, “base”)</li><li>with <strong>values</strong> (“12px”, “16px”, “24px”, “16px”)</li><li>value of the “base” token is <strong>referencing</strong> the “medium” one using its <strong>path</strong>: “size.font.medium.value” resulting in “16px”</li><li>The “comment” <strong>attribute</strong> (or any other attribute) can be used as metadata for different outputs, for example a help text</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jRRQIMCaXYNYAf9a8he5PA.png" /></figure><p>The build system <strong>transforms</strong> these tokens into platform-specific formats according to built-in or custom rules. Transforms can modify a token’s name, value, or attributes — enabling each platform to use the design token in different ways. A simple example is changing pixel values to point values for iOS and dp or sp for Android.</p><h3>Building token export pipeline</h3><p>In a nutshell, our task was to get styles from Figma through API, save these styles as tokens in the Style Dictionary repository, and define token transformation rules for each platform.</p><h4>Pipeline sequence</h4><p>Here is a DS automation we came up with after agreeing on all formats: styles are fetched from Figma, saved into Git repository as tokens, then another pipeline generates platform-specific variables, and finally tokens are published to S3 storage to style our <a href="https://medium.com/flo-health/backend-driven-ui-at-flo-health-3b38ae8534b0">backend-driven UI</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*KPKZbsrisCuFzLqYuWRPtQ.png" /></figure><p>We also set up automatic <strong>notifications to DS Slack channel</strong> on each stage, so that we can timely respond to issues or important updates.</p><p>And finally all changes need to be reviewed in an automatically created <strong>pull-request</strong> by the design and dev team. We agreed to use the <strong>YAML format for tokens</strong> instead of JSON because of its better readability and compactness.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MCHChTKtKwbA4E0wOxxyng.png" /></figure><h4>Pipeline trigger</h4><p>But wait, who and how starts the whole DS export process? Making designers go to Bitbucket and start a pipeline from there seemed inconvenient, so we wrote a small plugin that does the job.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cEMaZAueRp5SlCyTSHJC_Q.png" /></figure><p>Finally, the workflow for designers looked like this:</p><ol><li>Make changes in DS tokens Figma file branch and pass internal review.</li><li>Open the DS export plugin to start the tokens export process.</li><li>Wait for a Slack notification</li><li>Go to pull request and review it</li></ol><h4>Why do we need a Git repository for tokens?</h4><p>Using a Git repository for design tokens brings several key advantages to DS workflow. Git automatically tracks every modification, creating a complete history of changes. Nothing gets lost or overwritten without being recorded — every color change, spacing adjustment, or typography update is preserved in the <strong>version history</strong>. Through pull requests, team members can <strong>review token modifications</strong> before they’re merged into the main branch. These pull requests can trigger <strong>automated checks</strong> that validate token syntax, generate visual previews of affected components, and run compatibility tests.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*g8aBeaGXVO1SNsSw8N1rzg.png" /></figure><p>It is quite useful to adopt <a href="https://www.figma.com/best-practices/branching-in-figma/">Figma branching</a> for any DS changes on the design stage, though it cannot fully substitute pull requests in Bitbucket/GitHub: no automatic checks and actions, changes not related to DS are shown as well.</p><p>Designers fill in a <strong>new semantic DS version number</strong> (major.minor.patch) and text description. When tokens are imported from Figma, we parse this information from Figma API and detect new version information. It is stored in Git commit as a version-x.x.x tag and an explicit “version” token. When creating platform-specific code, we can include a version token that helps track the design system’s current version. This makes it easy to match assets or communicate with APIs using the exact design version.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*nSI5IqmBL3tvmbFbQYmnsA.png" /></figure><h4>Color token export example</h4><p>Let’s finalize the whole process on a real example of two color tokens: <strong>color.border.primary</strong> and <strong>color.border.secondary</strong>. The picture below shows their Figma and Style Dictionary formats for dark and light themes. We are using references to the Core Color values to be more flexible: <strong>{color.white.base}</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ArEOGs9IEdde0WmZUPPzBQ.png" /></figure><p>The following picture shows the same tokens further transformed into iOS and Android variables and styles.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4Kk67iy3g89E9fgx2m3N-w.png" /></figure><h3>Migration to tokens in code</h3><p>Having an automated token export is not enough — we also spent quite some time <strong>detecting hardcoded styles</strong> (for example, raw color hex values), finding obsolete tokens, and setting new tokens instead. This work required frequent ad-hoc consultations with designers and adding or editing tokens because the app is huge, and not all cases were covered by the initial token set.</p><p>We also set automatic checks to detect and prohibit hard-coded styles in the future and communicated to other teams to use new guidelines.</p><h3>Integrating DS into Contentful CMS</h3><p>After finishing with token usage in the app code, the next move was to integrate DS into our content.</p><p>Here, you can read about how we use Contentful for onboarding and articles:</p><ul><li><a href="https://medium.com/flo-health/mobile-onboarding-evolution-part-2-d7c324c348fe">Mobile onboarding evolution: Part 2</a></li><li><a href="https://medium.com/flo-health/the-evolution-of-the-content-library-an-engineering-story-850b2bc53bb2">The Evolution of the Content Library: An Engineering Story</a></li></ul><p>Previously, there were content types with various fields defining their styles: color pickers, numbers for sizes, and dropdowns with values.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6jjFBcJHh_c7mdQh9GlO3g.png" /></figure><p>We added tokens instead of raw values so that we don’t need to edit each content piece when a token value changes.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*WZiB4ov39EsVhCXBv9A6CA.png" /></figure><p>Here is an example of a DS <strong>button element</strong> in Contentful Live Preview where design tokens are synchronized through the S3 bucket (one of the outputs of the tokens export pipeline).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_mM6gsaMo6R-6AgXEt6oVQ.gif" /></figure><p>As you can see, all button parameters are semantic, there are no raw values, and in case of any DS updates, the latest styles will be synced automatically in minutes.</p><h3>Results</h3><p>Building Flo’s automated design system has brought clear improvements, though it wasn’t without effort. Here’s what got better:</p><ul><li><strong>Saved time and reduced errors</strong>: Automation streamlined updates across platforms, cutting down manual work and mistakes.</li><li><strong>Consistent design everywhere</strong>: A central source of truth ensures UI consistency across iOS, Android, and web.</li><li><strong>Better collaboration</strong>: Designers and developers now work together more smoothly, speaking the same “language” through design tokens and components.</li><li><strong>Future-ready tools</strong>: Using tools like Style Dictionary means we’re ready to adapt as technology changes.</li></ul><p>We get it — skeptics may ask, “Was all this effort worth it?” or “What’s the ROI?” While we can’t pinpoint an exact dollar figure, the payoff is evident in faster feature delivery, fewer design inconsistencies, and scalability. Yes, it took time to set up the pipeline, reorganize files, and get the team on board. But the foundation we’ve built will save time and headaches in the long run.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GJUaUPMasnMT2rrRCxIuvA.png" /><figcaption>Figma can count only components re-usage, not styles.</figcaption></figure><h3>Next steps</h3><p>This is just the start. Here’s what’s next:</p><ol><li>Expand token coverage and add more components to cover all design use cases.</li><li>Align with new standards like the <a href="https://design-tokens.github.io/community-group/format/">Design Token Community Group spec</a> to stay future-proof.</li><li>Automate more for web platforms and content tools to bring the same consistency everywhere.</li><li>Keep educating the team so everyone gets the most out of the system.</li><li>Migrate to <a href="https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma">Figma variables</a> to simplify token referencing and theme switching.</li></ol><p>While we were writing this article, our colleagues already did a POC with tokens as variables, so it is time for us to catch up and share our knowledge after migration is completed.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*iIyiiWhXi8p2O3c6i4bKjw.gif" /><figcaption>Figma variables make mode switching so comfortable!</figcaption></figure><p>Building a design system isn’t a one-and-done project. It’s a continuous process, and there’s still work to do. But we’re excited about the progress and confident it’s making a real difference.</p><h3>P.S.</h3><p>Last time, to check who read our <a href="https://medium.com/flo-health/mobile-onboarding-evolution-part-2-d7c324c348fe">Onboarding article</a> till the end, we shared a Medium secret that you can clap up to 50 times for a single article or comment.</p><p>This time, those who bravely read till the end, please post your idea for the<strong> Flo design system name</strong> in the comments.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5dVRxwVow5xibDJjqomFYw.png" /></figure><blockquote>Written by <a href="https://www.linkedin.com/in/sasha-zinchuk/">Sasha Zinchuk</a> with a little help from my friends and ChatGPT.<br>Based on a tech <a href="https://www.linkedin.com/events/7001537311331000320/">presentation</a> by <a href="https://www.linkedin.com/in/vladimirburylov/">Uladzimir Burylau</a>.<br>Design review by <a href="https://www.linkedin.com/in/aldr-gavrilenko/">Alexander Gavrilenko</a>.</blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=0848c4623081" width="1" height="1" alt=""><hr><p><a href="https://medium.com/flo-health/flo-design-system-part-2-0848c4623081">Flo design system: Part 2</a> was originally published in <a href="https://medium.com/flo-health">Flo Health UK</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Flo design system: Part 1]]></title>
            <link>https://medium.com/flo-health/flo-design-system-part-1-1eb8b731a48c?source=rss-7b7a33654f75------2</link>
            <guid isPermaLink="false">https://medium.com/p/1eb8b731a48c</guid>
            <category><![CDATA[design]]></category>
            <category><![CDATA[mobile-app-development]]></category>
            <category><![CDATA[product-management]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[engineering]]></category>
            <dc:creator><![CDATA[Sasha Zinchuk]]></dc:creator>
            <pubDate>Mon, 06 Jan 2025 16:17:55 GMT</pubDate>
            <atom:updated>2025-01-06T16:25:51.522Z</atom:updated>
            <content:encoded><![CDATA[<h3>Flo design system: Part 1. Stepping stone</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*oWTmUJTcBSKdfuRdfrgOdQ.png" /></figure><blockquote><strong>Product Manager</strong>: “What is the progress with the new Privacy menu?”<br><strong>iOS <em>engineer</em></strong>: “We need to sync with the designer to refine margins: 16 or 24px.”<br><strong>Android <em>engineer</em></strong>: “We use 12dp defaults.”</blockquote><blockquote>—Design System joins the chat —</blockquote><p>Every article on the <strong>Design System (DS)</strong> topic starts with its own definition of DS and why it is needed. Let’s try to formulate a simple one:</p><p>DS is a set of tools and processes that enables non-designers to create a consistent UI that aligns with the product’s style.</p><h3>Five whys about design systems</h3><h4>Why you should read this article</h4><p>It describes two efforts to create a DS at Flo and their outcomes. We are sharing our findings, tools, and plans so you can save time while starting your own design system. Other articles on the same subject often contain either information about structuring design tokens or instructions for building DS pipelines. Here, we tried to paint the whole picture and show our DS workflow end-to-end with real, simple examples.</p><p>It is more about the DS foundations — <strong>design tokens</strong> — but there are also examples of some components.</p><h4>Why designers like to have a design system</h4><p>DS introduces a set of standards to <strong>manage design at scale</strong> by reducing repetitive work. Designers can leverage <strong>shared language</strong> to achieve visual consistency for their product, regardless of the platform (mobile, web, desktop) and channel (email, ad).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*b6flEzWugFVe3RDotBHb5Q.png" /><figcaption>Ok, my call-to-action text should definitely use the {color.text.brand} token.</figcaption></figure><h4>Why developers like to have a design system</h4><p>Developers always strive for minimum waste and appreciate the following perks of having a DS:</p><ul><li>Set of components already implemented and ready for reuse</li><li>Separating view layout and logic from visual style details</li><li>Static safety and auto-completion.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*he7kSXwKc1mK6bPIRnIYMw.png" /><figcaption>No need to ask additional questions — just use DS styles from the mockup in the code.</figcaption></figure><h4>Why managers like to have a design system</h4><p>They believe that fewer designers and developers are needed to deliver the same value. There are even some <a href="https://www.knapsack.cloud/calculator">ROI calculators</a> for DS; we hope they are built on accurate data.</p><h4>Why everyone is procrastinating</h4><p>There’s an elephant in the room, yet we continue with business as usual. Why?</p><p><strong>Employees</strong>: “Like any set of standards, a DS restricts our ideas and imagination to an extent. Even if we decide to build a DS — it is a huge task, and it is hard to define first tangible steps and deliveries.”</p><p><strong>Business</strong>: “DS needs investment, especially from the start. You need buy-in from stakeholders and c-level, show them expected ROI, describe pain points and problems for scaling.”</p><p>Therefore, you need to start with forming a group of enthusiasts who can persuade stakeholders, show DS value in small but substantial steps, and break barriers between designers and developers.</p><h3>Design System v1.0</h3><p>For this article, we did some archeological exercises: we installed the first Flo app versions on a real device, unarchived old documentation, and interviewed day-one employees.</p><p>Here is how it started.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1Gz8oAKJT7Ud3jgW_hb7sQ.png" /></figure><p>And below are the same app screens eight years later, after the design language was refined through thousands of experiments and user research sessions.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pfxwfxFvZxGo641EHCZInw.png" /></figure><h4>How and when it appeared</h4><p>Like any startup, Flo had no formal DS from the start. The earliest documented evidence of design tokens and components dates back to late 2018. It was the 4th year in business: after a couple of closed investment rounds, we doubled our design organization (hired the second designer!), and the brand became recognizable.</p><p>When all these conditions were met, we naturally started building the 1st design system to keep the development pace and break silos inside the organization.</p><p>This is how Flo DS v1.0 first looked like in a nutshell:</p><ul><li>Documentation in Confluence and Figma</li><li>Manual implementation in code, according to documentation. Separate module for DS.</li><li>A pretty wide array of tokens, from colors and spacings to toolbars and input fields.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zHsPDQhqMkdXrQCn2iDvHw.png" /></figure><p>This move added more clarity and allowed us to scale our teams, but it had its drawbacks.</p><h3>What went wrong</h3><p>There was no synchronization between Figma and code — only manual updates by chance. Some automation appeared later in the form of Figma export scripts for particular modules, but it was still disorganized. Manual support of the source in two places (Figma and Confluence) resulted in missing updates.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HqhCWcgdEvyZagux78GNjA.png" /></figure><p>Constant ‘small’ overrides here and there (both in design and code) were breeding new undocumented styles each time; later we found hundreds of such cases in code.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Mj8vK4Eao6uLmuPc7tkfKg.png" /><figcaption>“Let’s change this default style; it is only for one critical case.”</figcaption></figure><p>And finally, the main pain point was the absence of dedicated designers and developers to support and evolve the DS. Everyone was busy with new features and experiments, a natural state for any startup.</p><h3>Let’s fix it in v2.0!</h3><p>The next significant transformation occurred in 2021–2022, following a new investment round and driven by the need to accelerate growth and value delivery.</p><h4>New DS goal</h4><p>This time, the main idea was to push design token changes from Figma to any platform with minimal manual effort and without developers’ help.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QiWQM29j7-cfh3Ce-roQ3A.png" /></figure><h4>Difference from v1.0</h4><p>This time, after reviewing our first design system, we came up with the following improvements and agreements:</p><ul><li>Dedicated designer and dev team capacity to work specifically on the DS backlog</li><li>No constant small overrides of DS neither by designers nor by developers</li><li>The only source for DS is Figma</li></ul><p>While changes were made in Figma first, we needed to export them into some token storage that supports versioning before conversion to platform-specific formats. The aim was to reduce vendor lock: not so long ago, Sketch and InVision were at their zenith, and then Figma replaced them — we need to be ready for such a scenario.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Tr3-r1TscneAlBX1mEIjKA.png" /></figure><p>Another approach involves designers editing tokens in JSON format and creating pull requests in Git. Changes from Git need to be made manually or through API in Figma. Lukas Oppermann <a href="https://uxdesign.cc/the-ultimate-design-token-setup-cdf50dc841c8">recommends this approach in his article</a> and explains its benefits.</p><p>We decided to go with the “Figma first” approach because we love our designers 🙂, so they keep working in Figma and only review pull requests.</p><h3>Re-organizing Figma</h3><p>“Figma first” implies having a structured and convenient set of Figma files and libraries. So we sat with client devs and designers to find out each other’s workflows and pains and establish new practices that fit both parties. As a result, we re-organized our libraries and got 3 main files:</p><ul><li>Core Colors</li><li>Product Tokens</li><li>UI Kit</li></ul><p>Let’s quickly dive into their content — so that you have an overview of what we’re going to export to code afterward.</p><h4>Core Colors</h4><p>Because our design team consists of illustrators and product designers, we agreed to create a <strong>Core Colors</strong> palette that both teams can use. Illustrations need way more colors than our app UI, but a common color library definitely contributes to overall consistency.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*seVP1mfeKBrrOQxGN4RAUw.png" /><figcaption>Part of the Core Colors library</figcaption></figure><p>We took inspiration from the <a href="https://m2.material.io/design/color/the-color-system.html">Material Design color system</a>, but at the same time, we tried to have fewer tints for each color because too many options can harm productivity.</p><h4>Product Tokens</h4><p>Then, we created a separate Figma file for all styles and named it <strong>Product Tokens</strong>. It contains local styles arranged into a reusable library and their visual application on the canvas for better readability.</p><p>Naming and organizing these tokens was a tough process, and after multiple iterations, we came up with a hybrid of <strong>semantic</strong> and <strong>component-based</strong> approaches. Some examples of our tokens:</p><pre>color.button.accent<br>color.banner.success<br>typography.body.semibold<br>effect.shadow.level-2</pre><p>The concrete value of each token is picked depending on the device type, system theme, screen size, and so on.</p><h4>Color</h4><p>Each color token in our system has two values — for the <strong>Light and Dark mode</strong> respectively. Color values are taken from the Core Colors file. We had to create a special script which validates that token values correspond to the core palette (Figma variables weren’t a thing at that time).</p><p>Here is a visual example of color tokens on Figma canvas.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TpYn9binMiieiXABSgLjlQ.png" /></figure><p>And the same information but in the Properties panel, displaying local styles and their hierarchy.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HhP_TiOs0nJxvE7RAVbBXg.png" /></figure><h4>Typography</h4><p>Organizing typography tokens was not rocket science: We picked separate fonts for each mobile platform, <strong>SF Pro</strong> for iOS and <strong>Roboto</strong> for Android, and derived a set of 14 styles for different use cases.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SFzn0hKzuYuejWBT9gGTJw.png" /></figure><p>But hold on, it wasn’t actually so simple as it seemed at the beginning. It turned out that line height in Figma and on Android/iOS devices was calculated and rendered differently. To tweak all parameters, we added real typography samples into our app’s debug menu. This menu helped to make sure that all typography styles looked as expected and matched the source design.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-nZawrlnJ1KAz-OvTG_u-A.png" /><figcaption>Line height is highlighted with a red background.</figcaption></figure><p>We also experimented with adding our custom font for both platforms, but this story deserves a separate article. In a few words, it is technically doable but requires huge investments and business reasons.</p><h4>Icons</h4><p>There are hundreds of icons in the Flo app, their number is constantly growing as we are adding symptoms, modes, surveys, and whatnot. Therefore, all icons need to be categorized and standardized.</p><p>We agreed on a name convention for icons:</p><pre>{size}_{name} / {shape}</pre><p>Some examples of icon names:</p><pre>medium_star / stroke<br>large_event_mood_sad / color</pre><p>The following set of icon <strong>sizes</strong> seemed enough for us.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lbBD3OYrjvOcV4COpIbN4w.png" /></figure><p>For each size we defined <strong>types</strong>: circle, square, horizontal, vertical. The <strong>shape</strong> marker is used to group icons and differentiate them by the style of drawing.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*iveV6K4ScHRqWxfDTWzeUQ.png" /></figure><p>Here is an example of a reusable icon component in the Figma file.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RQouOFKOS9iuNhjWItX9MQ.png" /></figure><h4>Other tokens</h4><p>We will not describe all other tokens as they do not change that much and represent just named numbers like screen size, borders, etc.</p><h4>UI kit (Components)</h4><p>You cannot build interfaces only on tokens (<a href="https://bradfrost.com/blog/post/extending-atomic-design/">particles</a>); with time, you start using components (atoms) and nested components (molecules, organisms, etc.) to save effort.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lQQ_lSQiuod9RDIIXDdc0A.png" /></figure><p>In this article, we focus on exporting only design tokens, but we will also include an example of a button component exported to different platforms.</p><h3>What’s next?</h3><p>In this part we gave you an overview of our Figma changes and the reasons behind them. Now you can grab a coffee and proceed to the next part which describes automations we built to make our lives easier.</p><p><a href="https://medium.com/flo-health/flo-design-system-part-2-0848c4623081">Flo design system: Part 2</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*nOfG9UQM13nPRcoaIe9iXw.png" /></figure><blockquote>Written by <a href="https://www.linkedin.com/in/sasha-zinchuk/">Sasha Zinchuk</a> with a little help from my friends and ChatGPT.<br>Based on a tech <a href="https://www.linkedin.com/events/7001537311331000320/">presentation</a> by <a href="https://www.linkedin.com/in/vladimirburylov/">Uladzimir Burylau</a>.<br>Design review by <a href="https://www.linkedin.com/in/aldr-gavrilenko/">Alexander Gavrilenko</a>.</blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1eb8b731a48c" width="1" height="1" alt=""><hr><p><a href="https://medium.com/flo-health/flo-design-system-part-1-1eb8b731a48c">Flo design system: Part 1</a> was originally published in <a href="https://medium.com/flo-health">Flo Health UK</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Mobile onboarding evolution: Part 2]]></title>
            <link>https://medium.com/flo-health/mobile-onboarding-evolution-part-2-d7c324c348fe?source=rss-7b7a33654f75------2</link>
            <guid isPermaLink="false">https://medium.com/p/d7c324c348fe</guid>
            <category><![CDATA[server-driven-ui]]></category>
            <category><![CDATA[onboarding]]></category>
            <category><![CDATA[mobile-app-development]]></category>
            <category><![CDATA[experimentation]]></category>
            <category><![CDATA[engineering]]></category>
            <dc:creator><![CDATA[Sasha Zinchuk]]></dc:creator>
            <pubDate>Tue, 03 Sep 2024 06:48:04 GMT</pubDate>
            <atom:updated>2024-09-10T07:12:10.292Z</atom:updated>
            <content:encoded><![CDATA[<h3>Mobile onboarding evolution: Part 2. Contentful era</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fOhSRsmbAT8s9gC09vZvJg.png" /><figcaption>By <a href="https://www.linkedin.com/in/sasha-zinchuk/">Sasha Zinchuk</a>, Product Manager, and <a href="https://www.linkedin.com/in/aliaksei-talankou/">Aliaksei Talankou</a>, Software Engineer</figcaption></figure><p>In the <a href="https://medium.com/flo-health/mobile-onboarding-evolution-part-1-cfc9702835ce">first part of the series</a>, we described the problems of app-embedded onboarding and shared our experience with transferring it to the server. Although we had solved the main problem of slow onboarding updates, their creation remained complex and time-consuming.</p><p>To democratize experimentation in onboarding flows and other in-app surveys, we identified <strong>transitioning from Git JSONs to a codeless online flow editor</strong> as the most impactful next step.</p><h3>Choosing a new onboarding editor</h3><h4>Third-party turnkey solutions</h4><p>To enhance the onboarding creation experience and enable a no/low-code approach, our team initially explored third-party options, such as Onboarding.online, Pendo, and Chameleon.</p><p><strong>Pros</strong>: Intuitive visual flow and screen editors.</p><p><strong>Cons</strong>: Not all platforms are supported. There are additional integration costs, new vendor onboarding efforts, and extra pricing for the paywall builder and analytics system Flo already had in-house.</p><h4>Figma or Miro plug-ins</h4><p>We also considered creating Miro or Figma plug-ins to turn diagrams into executable flows. These tools are perfect for online collaboration and displaying large graphs. Still, they are not the best onboarding source because they don’t have built-in concepts of environments, localizable fields, backups, content types, publish statuses, and validation.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*stBEaYrH4PWWihz_zcpwFg.gif" /><figcaption>Keeping all onboardings on one Miro board can be messy</figcaption></figure><p>It doesn’t mean you cannot have Miro or Figma as your onboarding editor — of course, they are viable options. You just need to adapt your processes, create custom validation, and export tools, which can eventually be costly but still fragile.</p><h4>Contentful CMS</h4><p>After comparing with all other options, we chose to use the <a href="https://medium.com/u/5a131a53c7b2">Contentful</a> CMS for storing and editing Flo onboardings because of these advantages:</p><ul><li>Localization support and integration with Phrase, Smartcat, and other TMSs</li><li>Automatic asset management and distribution through CDN</li><li>Most Flo services already <a href="https://www.contentful.com/case-studies/flo-health/">stored content in Contentful</a></li><li>Ability to enhance functionality by writing <a href="https://www.contentful.com/developers/docs/extensibility/app-framework/">custom apps</a> (UI and backend plug-ins)</li></ul><p>Here is a high-level overview of the Contentful-based solution our team came up with.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Ucwx4Dcd9eMz1JjKBpmjww.png" /><figcaption>Main idea: minimize time from creation to delivery and reduce errors</figcaption></figure><p>The right part — “Using survey” — was already in place after migration to server-driven onboarding, so we needed to build the left part — “<strong>Creating survey</strong>” — by setting up the Contentful model, building a flow editor, and finally importing existing onboardings into Contentful.</p><p>The onboarding creation flow was planned to have the following steps:</p><ol><li><strong>Set up an experiment</strong> using our internal A/B testing tool, <a href="https://medium.com/flo-health/how-flo-conducts-experiments-5ee35fc3327f">Unified Experiment Service</a>.</li><li><strong>Create a survey</strong> in Contentful and include it in the A/B test.</li><li>Send a survey for <strong>localization </strong>and check translations using the <a href="https://medium.com/flo-health/localization-matrix-app-straightforward-content-localization-for-20-locales-81443e063d57">Localization Matrix</a> app.</li><li><strong>Publish to production</strong>: Survey Engine service reads and validates surveys stored in S3.</li></ol><p>Delivery to the end user remained the same: Flo app downloads server onboardings during initial animation. This article is focused on survey creation and new tooling around it because all other systems were already in place.</p><h3>Creating data model in Contentful</h3><p>How do you start creating onboardings in Contentful? First, of course, describe their structure and relations, and only then create actual content.</p><p>We started by setting up a data model compatible with onboarding JSON configurations from the <a href="https://medium.com/flo-health/mobile-onboarding-evolution-part-1-cfc9702835ce">first article</a>. The<strong> Survey</strong> became an aggregated content type that consisted of multiple <strong>Transitions</strong>. Each <strong>Transition</strong> connects two <strong>Steps</strong> and may have a <strong>Condition</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Mt7Aaym_Oz_Zz-4W75sZBA.png" /><figcaption>“Lost in transitions”</figcaption></figure><p>The first model version seemed a little bit complicated, and later, you’ll find out its weak points. Now, let’s dive deeper into the main elements of the Survey.</p><h4>Step types</h4><p>The most challenging task was to decide what to do with the <strong>25+ onboarding step types</strong> inherited from previous app-embedded onboardings. Our goal was to give users rich editing forms where they could control every aspect of the onboarding steps. To achieve this, we analyzed step usage and layout change frequency, which led us to split the step types into two groups: the most popular and all others.</p><p>Our team created separate content types for <strong>the three most popular</strong> step types, allowing detailed customization with built-in validation.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kOd0npcKI08u3s2yfuZl1Q.png" /><figcaption>Media and Feature Card could have been one content type</figcaption></figure><p>For all other screens with practically unchangeable designs — such as calendars, login pages, symptom pickers, and weight/height entries — we reserved a <strong>Generic Step</strong> with a JSON field to house their contents.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SehRzSiUp2Q9gPsIu3FDvg.png" /><figcaption>These screens don’t change for years until stakeholders have a new bright hypothesis</figcaption></figure><p>We also agreed to use this Generic Step for all new use cases because creating a content type for each new design was a dead end and led to maintenance hell. The goal was to eventually create a flexible unified step consisting of reusable building blocks: buttons, texts, and images.</p><p>Translation management systems cannot effectively operate with raw JSONs because it’s hard to precisely distinguish metainformation from the localizable text. To resolve this problem and explicitly mark localizable content, we introduced <strong>Text</strong> and <strong>Asset Placeholders</strong>. Placeholder keys are wrapped into the <strong><em>${}</em></strong> construction in JSON, for example, <em>${title_text}</em>. Survey Engine backend replaces placeholder keys with their values after content publishing.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vSKBNUamQhI6a40wa18qyw.png" /><figcaption>Generic Step with placeholders and static preview in Contentful</figcaption></figure><p>Editing JSONs could be challenging and error-prone, so we enhanced the editor with validation and auto-completion using <a href="https://json-schema.org/overview/what-is-jsonschema">JSON schema</a>. Such an approach allowed us to move faster and postpone UX improvements until the migration to Contentful was done.</p><p>After setting up step types, it was time to gather them into an executable flow (survey).</p><h4>Survey types</h4><p>We also enriched the initial onboarding model and distinguished three types of Surveys:</p><ul><li><strong>Root</strong> Survey: an aggregated survey available for downloading from the server</li><li><strong>Sub</strong> Survey: a reusable group of steps inside a Root survey, which hides the cognitive complexity of long onboardings by expanding/collapsing its content</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vgIb_w_YD7YZnVef_RxBpg.png" /><figcaption>Root survey with three Sub Surveys</figcaption></figure><ul><li><strong>Experimental</strong> Survey: a survey branch intended for a particular user segment and connected to any place in the Root survey flow. The backend service attaches Experiments to their Root before sending the whole survey only if the current user meets all required criteria (for example, age &gt; 18 and in a test group of some experiment).</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cVkxb_xp4tkRkTeflareTQ.png" /><figcaption>Root survey with two Experimental surveys attached</figcaption></figure><p>Such an experiment concept allowed us to do <strong>isolated parallel editing</strong> without merge conflicts and to <strong>avoid content duplication</strong>. When an experiment fails (approximately 9 cases out of 10), LiveOps just archives it without any changes to the Root survey. If an experiment succeeds, its branch is simply merged into the Root.</p><p>All these survey types were not just our guesses — they were based on actual use cases. Onboarding <strong>product managers combined similar workflows and branches in Miro</strong> while designing experiments. We tried to keep the same experience but in Contentful so that these diagrams could be created, validated, localized, and published to mobile devices from one source.</p><p>Our team drew surveys on a whiteboard during the concept brainstorming and dreamed of having something like this for actual Contentful surveys…</p><h3>Adding flow visualization using a custom app</h3><p>The standard Contentful list interface would be sufficient if Flo’s onboarding process had a linear flow without any branching logic based on user answers. But even with one fork, the list of transitions becomes inconvenient for human perception.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*dLUFkb4zQ9f5ZbgzXs8dug.png" /><figcaption>Which visualization looks clearer?</figcaption></figure><p>In reality, our onboarding has a lot of forks, such as user goal, age, experiment, system version, and so on. Displaying such complex onboarding as a list is not usable at all. So, we added a new type of visualization that did not exist in Contentful out of the box — a custom <strong>Survey Graph </strong>application.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*BQz4JQry5OnJiz3TqRITDg.png" /><figcaption>Graph view is understandable without any prior training</figcaption></figure><p>We identified the main functions of the app and added them one by one:</p><ul><li>Visualizing entries as a graph with steps, transitions, and conditions</li><li>Creating steps or reusing existing ones</li><li>Searching steps and conditions (a lifesaver for huge graphs)</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gR1ewEFUp1Lp4UFP9TunMg.gif" /></figure><ul><li>Expanding/collapsing of sub-surveys</li><li>Previewing all experiment branches connected to a root survey</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*les1-xpYvZQUzuzHLgCBpQ.gif" /></figure><ul><li>Survey validation (previously done only on the backend after publishing)</li><li>Merging experiment to its root</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6BHUQ0ZWwOzKKG2fSFWyVg.gif" /></figure><p>At first, the Graph App was just a read-only graph visualizer built with the <a href="https://reactflow.dev/">React Flow</a> library, and we were adding more and more capabilities and custom views to speed up survey creation and reduce the number of human errors.</p><p>The visual tool, equipped with drag-and-drop functionality, enabled LiveOps (citizen developers, content ops) to implement onboarding flows autonomously. Developers could finally concentrate on innovative user experiences.</p><h3>Survey selection mechanism</h3><p>With a visual workflow creation tool, our users could create many surveys for onboarding and other app features. But how could we distinguish onboardings and show them only to relevant users?</p><p>Flo teams use a special filter to match the right piece of content with a particular group of users. This filter works on <em>SQL-like </em>expressions whose final result can be either <em>true</em> or <em>false</em>. Our LiveOps set these expressions to choose the audience they want to reach with a specific survey. This approach doesn’t require any programming knowledge, just a basic understanding of how SQL WHERE statements work, and is widely used within the company.</p><pre>platform = &#39;iOS&#39; AND app_version &gt;= 9.5.1<br>AND lang IN (&#39;de&#39;, &#39;es&#39;, &#39;fr&#39;)<br>AND (my_experiment = &#39;test1&#39; OR my_experiment = &#39;test2&#39;)</pre><p>Moreover, experiments utilize the same logic but have one more filtering layer — they should be attached to the Root survey.</p><blockquote>Thus, each user may receive a <strong>unique, tailored onboarding</strong>!</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*UdACiGcjhekA9h4ZIA5zsQ.png" /><figcaption>Surveys for different audiences</figcaption></figure><h3>New testing tools and process</h3><p>So our users had a straightforward mechanism to pick relevant onboardings for different user segments, and on Production, these onboardings do not interfere with each other — some are for Android Spanish locale, others for iOS Vietnamese. But what about the Test environment? There are always some draft experiments or fixes. How can a QA or LiveOps person test a particular survey without interfering with other team members’ experiments? The solution is a special <strong>onboarding debug menu</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xPRcvgXCzI5EM4id-oqWNQ.gif" /><figcaption>Launching any onboarding from the debug menu</figcaption></figure><p>This menu significantly reduced onboarding testing efforts by:</p><ul><li>Testing a specific survey or an experiment without matching its filter conditions (like a cheat code in a game)</li><li>Logging out of the current user account and resetting all app data (to emulate a fresh app install)</li><li>Teleporting to any survey step (start on step #100 and save tons of clicks and nerves)</li><li>Displaying client errors on UI (fewer requests from LiveOps to engineers)</li></ul><p>However, users were still typing all the debug parameters, which could have been very long. So, we added the possibility of opening a survey via a deeplink.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*dRONBWJrZf9_aYHfi5m0FA.gif" /><figcaption>Scan &amp; go!</figcaption></figure><h3>Migration from Bitbucket to Contentful</h3><p>Finally, after designing the Contentful data model, building the flow editor, and introducing new testing tools, it was time to migrate existing onboardings from repository-based JSONs to Contentful. Our final goal was to use <strong>Contentful as the only source</strong> for all onboardings, with <strong>LiveOps as our target users</strong>.</p><h4>Migration</h4><p>To quickly transfer the existing mobile onboardings from Git to Contentful, we decided to automate this process by writing a script utilizing the rich <a href="https://www.contentful.com/developers/docs/references/content-management-api/">Contentful Management API</a>. The script collects JSON configurations from iOS and Android app repositories, transforms them into the Contentful entries format, saves them, and publishes. Our team had to run, test, and fix it many times, and as a result, it saved us many days of manual repetitive work.</p><p>Because the source of configurations shifted from mobile clients to Contentful, we had to ensure that the Flo application always had a <strong>local onboarding backup </strong>to use in case of missing internet (up to 10% of all app installs!). Therefore, the platform team set up a pipeline for mobile repositories, which copies Contentful onboarding JSONs and assets from the backend into the app bundle.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*S7Vk0zJEh3gyele7melEjA.png" /><figcaption>Can a backup be broken? No, our QAs test it offline before each release</figcaption></figure><p>After completing all manual and automated checks, we started migrating onboardings platform by platform, tier by tier. Each onboarding flow was rolled out under an experiment in which analysts compared the tech and business metrics of Git-based onboarding vs. Contentful-based onboarding. Next, it was time to analyze the first results.</p><h4>Facing the results</h4><p>Unlike most product experiments that aim for positive change, migration experiments succeed when analysts can’t prove a significant difference in any of the metrics. This means there’s no statistically significant impact on the measured aspects after the migration. Here are some examples of conducted experiments.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*F-2oAUPScmGG6-rEOchcOA.png" /><figcaption>If an experiment fails, just run it again, just to be sure</figcaption></figure><p>One of the experiments failed because it showed −<strong>3.74% in subscription conversion</strong>, which was statistically significant! We had no idea why it happened because all manual and automatic checks indicated that all user groups got the same content on their devices. There were only two hypotheses left:</p><ul><li>Either it was a case when p-value = 5% was not enough (random coincidence).</li><li>Some other teams used onboarding step IDs (which were modified in Contentful to guarantee uniqueness) in their experiments.</li></ul><p>There were no active experiments that could use onboarding step IDs, so our analyst proposed to run the experiment again for 20% of users to be on the safe side and hold it for more than two weeks.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uhnkINflVzGO_BHRN1xaBA.png" /><figcaption>A picture you can hear</figcaption></figure><p>And it helped — the new experiment had no statistically significant differences in metrics!</p><p>What is the conclusion in this case? Trust your experiment data, but always remember that <strong>A/B testing operates only with probabilities</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*obzU-LhdkVnGoQdxx5VD-g.png" /><figcaption>Hope to see the same chart after Flo goes public!</figcaption></figure><p>All migrations, from the <a href="https://medium.com/flo-health/mobile-onboarding-evolution-part-1-cfc9702835ce#58ce">first server-driven onboarding experiment</a> to the last Contentful-as-a-source one, took us <strong>around seven months</strong>.</p><blockquote>The biggest challenge was not to interrupt the ongoing onboarding releases and experiments, as onboarding is the biggest revenue channel.</blockquote><h3>Monitoring enhancements</h3><p>Our internal users immediately observed the fragility of Contentful-based surveys: any careless unpublishing of transitions or assets could break the whole survey. Although the backend doesn’t update valid content with an invalid updated version, a simple service restart could have broken content serving. LiveOps needed to see the current state of all surveys in real time, and we built an advanced Grafana dashboard with different states of surveys. Guess which colors mean what?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fs4WEjXO3Z_HbCwlcMZlng.gif" /><figcaption>The on-call engineer’s life</figcaption></figure><p>Having nice green squares and end-user traffic for surveys in place was half of the deal, but our operations wanted to react quickly if there was a risk of not serving onboardings to users, so we configured alerts in case surveys suddenly got broken.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SaANoJobTgnCuZRbZQXbMA.png" /><figcaption>LiveOops, I did it again…</figcaption></figure><p>Later, our engineers added one more layer of safety by saving surveys on the S3 after each publish from Contentful together with a built-in rollback mechanism.</p><h3>Lessons Learned</h3><p>Our team successfully avoided incidents or downtimes during and after migration to Contentful. However, not all our decisions were optimal. Let’s review the most interesting issues and their resolutions.</p><h4>Separating the Graph structure from the content</h4><p>Our decision to store graph transitions and conditions as separate content types turned out to be ineffective because huge production surveys immediately hit Contentful API limits:</p><ul><li>The References view became practically unusable.</li><li>The Localization connector refused to export a large number of linked entries with deep nesting.</li><li>The export from Contentful to the S3 was also unstable due to the number of entries and the excessive bundle size.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QpUd0nCbVUPc0hqKufEeZQ.png" /><figcaption>A survey with 1516 references doesn’t want to display all its structure</figcaption></figure><p>To address this issue, we modified the data model by relocating Transitions and Conditions from separate content types to a new JSON field inside the Survey.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-v32RKBPZk_fIyGoBrnNdQ.png" /><figcaption>Fewer content types, fewer problems</figcaption></figure><p>As a result, we achieved faster survey data exporting, boosted the Graph App’s performance, bypassed API limits for the localization connector, and enhanced the user experience when editing transitions.</p><blockquote><em>Do not use Contentful purely as a relational database — separate content from its metadata.</em></blockquote><h4>Nuances with remote images</h4><p>Before migration, all onboarding images were stored within the app and instantly displayed at each step. The new approach involves storing the images in Contentful and distributing them via our CDN. Upon receiving the onboarding configuration, the client app initiates the background download of remote images and animations as the user progresses through the onboarding process.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jpCWZ681I4x14orWeDgb3g.gif" /><figcaption>The first impression can be spoiled quite easily</figcaption></figure><p>At the start of the flow, remote assets may initially have low successful download stats (as low as 50% in some cases). However, this issue can be simply resolved by placing them after a couple of textual questions. There’s a wide range of optimizations available here:</p><ul><li>Prioritizing the assets downloading queue</li><li>Embedding the first images into the app build</li><li>Showing placeholder images or low-resolution copies</li></ul><blockquote><em>Find the balance between local and remote assets, as not all users have good internet.</em></blockquote><h4>Static Step Preview is not enough</h4><p>In the beginning, users uploaded step screenshots from Figma or real devices, which was an effective and cheap way to improve flow readability. However, everyone on the team quickly realized that only <a href="https://www.contentful.com/developers/docs/tutorials/general/live-preview/">Live Preview</a> can guarantee good UX and development speed through live content updates and Inspector mode.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gEmH2nwquRyxCXLwxVG6pw.gif" /><figcaption>No need to publish and test on a real device</figcaption></figure><p>In the long term, there is a plan to integrate <a href="https://www.contentful.com/products/studio/">Contentful Studio</a> or develop a separate WYSIWYG Step Editor with a drag-and-drop element builder, conditional fields, etc. But this is another story for a separate article.</p><blockquote><em>Immediate content preview is crucial for time to market and quality.</em></blockquote><h3>Conclusion</h3><p>It took us a couple of sprints to teach the onboarding team to use new tools and adapt their testing, localization, and experimentation processes. We received tons of helpful feedback and started polishing our solution to reduce human errors and automate common use cases.</p><p>The onboarding product team has significantly increased its autonomy, with <strong>QAs and LiveOps now independently resolving 80% of issues</strong> rather than relying solely on the platform team. Communication and collaboration have improved as the team effectively uses the Survey Graph app, reducing the need for direct involvement of the backend team except in critical cases.</p><p>Our gains so far:</p><ul><li>One LiveOps can perform like two mobile Engineers before.</li><li>Concurrent experiments: 45 now (and constantly growing) vs. 10 before.</li><li>Time to detect an error in an experiment: 15 minutes vs. one day before.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-JB6Ki4fMvx85kdf9JAFlg.png" /><figcaption>By <a href="https://www.linkedin.com/in/sasha-zinchuk/">Sasha Zinchuk</a>, Product Manager, and <a href="https://www.linkedin.com/in/aliaksei-talankou/">Aliaksei Talankou</a>, Software Engineer</figcaption></figure><h3>👐 P.S.</h3><p>Did you know you can <strong>clap up to 50 times</strong> on each Medium article or comment?</p><p>Waiting for your feedback and questions!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d7c324c348fe" width="1" height="1" alt=""><hr><p><a href="https://medium.com/flo-health/mobile-onboarding-evolution-part-2-d7c324c348fe">Mobile onboarding evolution: Part 2</a> was originally published in <a href="https://medium.com/flo-health">Flo Health UK</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Mobile onboarding evolution: Part 1]]></title>
            <link>https://medium.com/flo-health/mobile-onboarding-evolution-part-1-cfc9702835ce?source=rss-7b7a33654f75------2</link>
            <guid isPermaLink="false">https://medium.com/p/cfc9702835ce</guid>
            <category><![CDATA[experimentation]]></category>
            <category><![CDATA[engineering]]></category>
            <category><![CDATA[onboarding]]></category>
            <category><![CDATA[mobile-app-development]]></category>
            <category><![CDATA[server-driven-ui]]></category>
            <dc:creator><![CDATA[Sasha Zinchuk]]></dc:creator>
            <pubDate>Mon, 17 Jun 2024 07:50:33 GMT</pubDate>
            <atom:updated>2024-09-10T08:22:37.824Z</atom:updated>
            <content:encoded><![CDATA[<h3>Mobile onboarding evolution: Part 1. From app-embedded to backend-driven</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QaD9J-XUJLOXMP6GTw_99g.png" /><figcaption>By <a href="https://www.linkedin.com/in/sasha-zinchuk/">Sasha Zinchuk</a>, Product Manager, and <a href="https://medium.com/@aliaksei.talankou">Aliaksei Talankou</a>, Software Engineer.</figcaption></figure><blockquote>UPDATE: <a href="https://medium.com/flo-health/mobile-onboarding-evolution-part-2-d7c324c348fe">part 2 is here</a>!</blockquote><h3>Introduction</h3><p>Before diving deep into details, we want to give you an overview of Flo’s domain, scale, and challenges. This information can help you understand why our onboarding is so complex and diverse.</p><p>Flo is a super app with various user segments: cycle tracking, getting pregnant, pregnancy tracking, sex life, socializing in secret chats, and many more. Moreover, we recently launched a <a href="https://flo.health/product-tour/flo-for-partners">Flo for Partners</a> feature with 1+ million MAU in 2024, meaning we are no longer only a female health app.</p><figure><img alt="MAU: 60+ mln, 40% revenue from onboarding" src="https://cdn-images-1.medium.com/max/1024/1*LtQ4INStb_rWVh2ed8xlew.png" /><figcaption>The scale of onboardings at Flo</figcaption></figure><p>Due to user preferences regarding data privacy, only 20% to 30% of users opt to share activity data with third-party services. This often limits our insights into new Flo app users, such as understanding their experience with the app. Is it a <strong>new user</strong> or a user with previous experience of using the app? So many questions to ask, and of course all these user segments react and convert differently to the same series of onboarding screens.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4EkePauUnB1uWxKOyE-fJQ.png" /><figcaption>User segmentation during onboarding</figcaption></figure><p>That’s why our onboarding has a lot of branches, depending on the main user goal and subgoals, with the <strong>total number of screens up to 400</strong>. Our product team is constantly experimenting (~5 hypotheses per 2-week sprint), which adds even more complexity to the onboarding content and logic.</p><p>Historically, Flo onboardings have different flows depending on the following attributes:</p><ul><li><strong>Platform</strong>: <em>Android, iOS, Web</em>. The last one is server-driven by nature, so it’s not the focus of this article.</li><li><strong>Locale</strong>: <em>EN, top 5, other 15</em>. Experiments are primarily conducted in English, then localized and tested for success in other regions.</li><li><strong>Source</strong>: <em>from app stores, from web to app, goal switching</em></li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jyGrzJ4PpYqtVbcW67nvpw.gif" /><figcaption>Flo onboarding experience</figcaption></figure><p>Initially, our application’s onboarding process was implemented using a <strong>series of hardcoded screens</strong>. The simplicity of this approach came at the cost of slow iteration and limited experimentation.</p><p>To enhance flexibility, we developed a <strong>domain-specific language for describing onboarding screens</strong>, which were integrated directly into the app. Though this embedded solution effectively addressed templated screen creation, it also introduced several issues we will explore in the following section.</p><h3>Problems with app-embedded onboarding</h3><p>Developers added new code and configurations to mobile repositories to deliver a new onboarding screen, experiment, or branch. Each sprint (two weeks), we released a new app version containing all these onboarding changes. Sounds normal, right? So, which problems pushed us toward server-driven onboarding?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-waieBeoSWYy2kxC916UDQ.png" /><figcaption>Mobile app release cycle</figcaption></figure><ul><li><strong>Release-dependent</strong> experiments and fixes in onboarding.<br>The mobile release cycle is too long, and product managers need to be able to react quickly (e.g., verify a fresh hypothesis, fix wording because of localization or other issues).</li><li><strong>Time to detect an error in experiment</strong> configuration &gt; 1 day.<br>Analytical systems are not real-time, new build reviews and rollouts can take days, and in cases of misconfiguration, you can only figure out that users are not attributed to all experiment groups the next day or even later.</li><li><strong>iOS and Android engineers</strong> were bored by editing huge JSON configs.<br>Mobile engineers wanted to solve interesting problems and build new experiences, not spend every sprint configuring flows with template steps.</li><li><strong>Cognitive complexity</strong> — iOS onboarding had more than 350 steps and 500 transitions.<br>Some developers used different ad hoc tools to visualize onboarding graphs on their local environments, but no generic solution existed. Product managers and quality assurance used a Miro board to keep track of all onboardings and avoid getting lost.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uOdXXslcygGWD8cczjbKXQ.png" /><figcaption>Just a fragment of the iOS onboarding</figcaption></figure><p>To solve these problems, we decided to try to move our onboardings to the server, especially given that we have a <a href="https://medium.com/flo-health/backend-driven-ui-at-flo-health-3b38ae8534b0">similar approach</a> in other parts of our app, and to add a visual editor afterward.</p><h3>Transition to backend-driven JSONs</h3><p>As a foundation, we agreed on a common contract with a dictionary of <strong>steps</strong> and an array of <strong>transitions</strong> with <strong>conditions</strong>. This simple data model allows you to build a graph view using ReactFlow, mxGraph, D3.js, and other visualization libraries.</p><pre>{<br>  &quot;steps&quot;: {<br>    &quot;initial&quot;: {&quot;type&quot;: &quot;initial&quot;},<br>    &quot;step1&quot;: {&quot;type&quot;: &quot;feature_card&quot;, ...},<br>    &quot;step2&quot;: {&quot;type&quot;: &quot;question&quot;, ...},<br>    ...<br>  },<br>  &quot;transitions&quot;: [<br>    {&quot;in&quot;: &quot;initial&quot;, &quot;out&quot;: &quot;step1&quot;, &quot;condition&quot;: []},<br>    {&quot;in&quot;: &quot;step1&quot;, &quot;out&quot;: &quot;step2&quot;, &quot;condition&quot;: [&quot;tag1&quot;, &quot;tag2&quot;]},<br>    ...<br>  ]<br>}</pre><p>The JSON files held information about different step types (such as questions, feature cards, authentication, age input, etc.), step layout, and transition logic. Android and iOS apps contained an engine that could read such files, validate them, and display a series of app screens depending on valid conditions.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*B0wt6LV2n6TFnyR0Gzf7RA.png" /><figcaption>Onboarding screens as a directed graph</figcaption></figure><p>After we implemented the contract, it was time to pick how the client would receive onboarding from the server.</p><h4>Download modes</h4><p>We discovered that onboarding configs were quite huge (up to 10,000 rows in JSON) and considered three options for downloading them:</p><ul><li>Download the whole JSON <strong>at once</strong>. This was the simplest and cheapest option because there was only one request to the server per user. The size of the JSON file was the only concern, as it impacted download times.</li><li>Download <strong>in chunks</strong>, like in a <a href="https://help.flo.health/hc/en-us/articles/360052676191-How-do-I-chat-with-Flo-Health-Assistant">chat</a>. A more sophisticated solution, with higher infrastructure costs and complex logic.</li><li><strong>Use a hybrid approach</strong>. Download the most important or popular flow upon app start-up and others on demand.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*q4AQgNOqAfgVXog91H0cVA.png" /><figcaption>Hybrid downloading mode</figcaption></figure><p>We followed the Lean methodology and chose the first option: download the entire onboarding configuration at once and address any issues as they arise.</p><p>So, <strong>what happens on the first app start</strong>? We decided to:</p><ul><li>Start downloading the onboarding during the initial animation</li><li>Stop waiting for a response when the user hits <em>Next</em> after accepting all policies</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*yYgQYUeKQO3AOQvfJr7NNg.gif" /><figcaption>Downloading of onboarding (in debug build)</figcaption></figure><p>Therefore, our users have roughly eight seconds to download onboarding from the server, and if there is no response or internet connection, the embedded onboarding is applied as it used to be.</p><h4>Survey Engine as onboarding backend</h4><p>To manage onboarding configs on the backend, we bootstrapped a new service called <strong>Survey Engine</strong>. Its purpose was to hide all the complexity of onboardings from the client and serve them via REST API. We decided not to limit ourselves to the onboarding domain name, as we planned to broaden its scope of responsibility, incorporating in-app quizzes, polls, and more.</p><p>During the initial phase, we stored JSON files directly in the repository code, organized them in folders based on the app version, platform, and locale, and moved a call to the <a href="https://medium.com/flo-health/experimentation-2-0-navigating-the-upgrades-at-flo-health-376c609f6a85">Experiment service</a> from the app code to this new service.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*nDzlLpH3hdDkfGjjUbqx9g.png" /><figcaption>Interaction with the backend</figcaption></figure><p>The overall workflow looked like this:</p><ol><li>The client calls the Survey Engine service.</li><li>Survey Engine gets all valid experiments for this particular user.</li><li>Survey Engine finds onboardings that match user attributes and experiments.</li><li>Survey Engine sends a response with onboarding JSON and all experiment details to the app.</li></ol><h4>Server validation</h4><p>To ensure that our users receive accurate data, we implemented a list of validations, such as:</p><ul><li>Ensuring that steps and transitions are unique in a graph</li><li>Verifying that there are no cycles</li><li>Matching a list of steps with a list of transitions</li><li>Confirming that all steps in a graph are connected</li></ul><p>Our backend service was designed to catch and highlight all potential errors in one pass, ensuring that any issues with the configuration are clear and easy for users to understand. Eventually, if there are any errors detected, we will not release the configuration to the users.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gemcVEn98wbqnvBjfPZW3Q.png" /><figcaption>Informative error message with root causes</figcaption></figure><p>With automated validation of onboardings in place, our next step was to release them for users carefully.</p><h4>Launch through an experiment</h4><p>Like any other feature at Flo, we launched the server-driven onboarding under a feature flag, gradually rolling it out first on the Android English version: 5%, 10%, 50%, and 100%.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zKiZ9YbSLEnO1ugneS4Dag.png" /><figcaption>First rollout notification</figcaption></figure><p>We tracked all the <strong>tech metrics</strong> and the main onboarding <strong>business metrics</strong>: conversion to subscription, number of trials, progress on key funnel points, and number of registrations.</p><p>This experiment was different because success would mean that <strong>none</strong> of the metrics showed a <strong>significant statistical difference</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QX0axe6Ssz1fwYuNzP500w.png" /><figcaption>Example of a “successful” experiment — no statistically significant changes detected</figcaption></figure><p>After the rollout on Android was successful, we extended it to all other locales and repeated the same actions on iOS.</p><h4>Client analytics: Local vs. remote onboardings</h4><p>Since server onboardings contain the latest updates and A/B tests, we wanted most users to receive them. To measure our success rate, we added a new analytical event with the following parameters:</p><ul><li><strong>Onboarding type</strong>: remote or local</li><li><strong>Return journey</strong>: false (first launch) or true (second+ launch)</li></ul><p>Based on this event, we built a dashboard showing the total number of onboardings and the percentage of remote ones for the first launches and return journeys.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NyRoqCq1wTvUo445HFIj6A.png" /><figcaption>Onboarding analytics dashboard</figcaption></figure><p>Our findings so far:</p><ul><li>On app start, <strong>5% to 10% of users are offline or have a very slow internet connection</strong>. These numbers correlate with the measurements of other teams and domains.</li><li>Onboarding JSON size (gzipped) up to 300kb (10,000 lines) doesn’t influence the download success rate much.</li><li>Users with a short initial animation (2 seconds) have a similar percentage of downloaded remote onboardings as the other segments with a long animation (8 seconds).</li></ul><p>In addition to these analytics, we wanted to ensure that our server-side onboarding was running smoothly and effectively, so we added real-time tech metrics.</p><h4>Observability on server side</h4><p>From the beginning, we leveraged Grafana to monitor what was happening with our onboardings. We tracked standard <strong>RED metrics</strong> (rate, errors, and duration) and set <strong>alerts</strong> for spikes:</p><ul><li><strong>Total number of requests</strong></li><li>Number of successful <strong>200 </strong>and failed <strong>4xx</strong> and <strong>5xx</strong> responses</li><li><strong>Requests and responses by app version</strong>. It was very useful to understand how many old versions we need to support and how quickly onboarding users got the new version.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ipzK0ZI_0J_mwcxdEdLUbg.png" /><figcaption>Requested onboardings traffic</figcaption></figure><p>The charts above show that iOS users started getting the new app version within hours. For Android, it was about a week due to a gradual rollout. On both platforms, it makes sense to<strong> support the two latest app versions</strong>. The share of users with older app versions is insignificant, and they can use the embedded onboarding instead.</p><h4>Continuous onboarding development</h4><p>We quickly realized a problem with frequent changes to JSON files in our mobile clients’ repositories. To prevent delays for the onboarding product teams during our migration, we decided to make the mobile repositories the single source of truth for configurations. Initially, we manually copied the updated JSONs to the backend repository, but the changes were happening so often that we couldn’t keep up. We created scripts to compare our server JSON files with those in the mobile repositories to solve this. If any differences were found, the scripts automatically generated a pull request.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Uoe0FgE-qsYYK_srEKFhfg.png" /><figcaption>Pull requests created by the script</figcaption></figure><p>As a result, we achieved a constant delivery of all onboarding updates to users without interruptions for the product team.</p><h3>Results</h3><h4>Problems solved ✅</h4><ul><li>Mobile teams can focus on developing new features and not edit boring JSONs. Now, any changes to onboardings can be immediately delivered to the client.</li><li>We’ve proved the concept of server-driven onboardings and gained valuable experience and insights into metrics, usage patterns, new version releases, and old version decommissioning.</li></ul><h4>Left to do 🚧</h4><ul><li>Visualize onboarding flows</li><li>Delegate onboardings and experiments setup from developers to business users</li><li>Add real-time experiment traffic monitoring</li></ul><h3>In the next series</h3><p>We uncover the <strong>migration of onboardings to Contentful,</strong> which made their creation smoother and less stressful.</p><p><a href="https://medium.com/flo-health/mobile-onboarding-evolution-part-2-d7c324c348fe">Mobile onboarding evolution: Part 2</a></p><p>Waiting for your feedback in the comments!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Tquo8h8isg5bVh4q27Usdg.png" /><figcaption><em>By </em><a href="https://www.linkedin.com/in/sasha-zinchuk/"><em>Sasha Zinchuk</em></a><em>, Product Manager, and </em><a href="https://medium.com/@aliaksei.talankou"><em>Aliaksei Talankou</em></a><em>, Software Engineer.</em></figcaption></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=cfc9702835ce" width="1" height="1" alt=""><hr><p><a href="https://medium.com/flo-health/mobile-onboarding-evolution-part-1-cfc9702835ce">Mobile onboarding evolution: Part 1</a> was originally published in <a href="https://medium.com/flo-health">Flo Health UK</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>