<?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 Kim Hart on Medium]]></title>
        <description><![CDATA[Stories by Kim Hart on Medium]]></description>
        <link>https://medium.com/@kim_hart?source=rss-3660f6373fbb------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*i2Oa4h6MgQI_IxCk8qQq4g.jpeg</url>
            <title>Stories by Kim Hart on Medium</title>
            <link>https://medium.com/@kim_hart?source=rss-3660f6373fbb------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 05:51:05 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@kim_hart/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[Streamlining the Design x Engineering Partnership]]></title>
            <link>https://medium.com/jw-player-engineering/streamlining-the-design-x-engineering-partnership-9d2328cfff4f?source=rss-3660f6373fbb------2</link>
            <guid isPermaLink="false">https://medium.com/p/9d2328cfff4f</guid>
            <category><![CDATA[frontend]]></category>
            <category><![CDATA[design]]></category>
            <category><![CDATA[qa]]></category>
            <category><![CDATA[web-components]]></category>
            <category><![CDATA[design-systems]]></category>
            <dc:creator><![CDATA[Kim Hart]]></dc:creator>
            <pubDate>Wed, 25 Nov 2020 15:03:03 GMT</pubDate>
            <atom:updated>2020-11-25T16:32:09.019Z</atom:updated>
            <content:encoded><![CDATA[<h4>A real-life roadmap for building a design system — Pt III</h4><p>In parts <a href="https://medium.com/jw-player-engineering/a-real-life-roadmap-for-building-a-design-system-pt-i-a805d81bd90">one</a> and <a href="https://medium.com/jw-player-engineering/a-real-life-roadmap-for-building-a-design-system-pt-ii-c4c2490875fe">two</a> of this series, we took a deep-dive into the benefits of building and scaling a custom design library (Hook) and web component library (WUI &amp; Atlas). This final chapter outlines how we’ve used these tools to improve design handoff and forge a strong partnership between designers and engineers as we roll out a new architecture for our enterprise dashboard.</p><h3>Removing the Guesswork 🕵️‍♀️</h3><p>A common pain point during a feature’s lifecycle often surfaces when the handoff of a design spec breeds assumptions from the designer and engineer alike. Design assumptions about feasibility or complexity can lead to questioning, debates, and overall time lost. Engineering assumptions <em>about</em> a design can lead to bugs, UX inconsistencies, tech debt-incurring workarounds. Fortunately, the introduction of Hook and WUI has alleviated a lot of the guesswork in both the design and engineering workflows.</p><p>Designers are now empowered to design with specific components in mind without worrying if the technical aspects are achievable or not. Loading, error, empty, and focus states are largely handled out of the box and just need to be wired up appropriately. Each state might not need to be detailed in a flowchart—a huge timesaver—because our components’ behaviors are consistent.</p><p>Here’s an example of how a traditionally tricky key-value input list handles itself in the context of a robust video detail page:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*OjDoOqLS10iHXBdAaoxn2g.png" /><figcaption>Feature vs component design specs</figcaption></figure><p>These reliable patterns reduce the cognitive load for all involved: both for the designer creating the spec and the engineer coding it into reality. Designs require less explanation, contain fewer holes &amp; extraneous details, and are easier to defend. When a developer doesn’t require clarification on the little things, it leaves space and time to discuss the <em>big</em> things as a team — allowing us to build more intuitive products and reach smarter solutions for the more precarious user flows.</p><h3>Forging a Partnership 🤝</h3><p>Because the creation of Hook and WUI was born out of the needs of two different teams, a natural collaboration formed as the libraries grew and evolved into what they are today.</p><p>While the team that previously owned the dashboard mostly comprised full-stack-types whose prowess leaned toward backend API design rather than UI-building, our new dashboard coalition contains designers and frontend, backend, and test engineers. The squad approach—complete with brains from all areas of expertise—has allowed us to solve problems faster, create more complete roadmaps of features end-to-end, and have a more holistic understanding of the services we’re delivering.</p><p>Visual bugs have also largely met their match with the addition of a <strong>Visual Quality Assurance (VQA)</strong> step in our JIRA workflow. After code review and before (full) QA, each ticket’s work is deployed to a staging environment and passed back to a designer to review and confirm that their spec is matched appropriately.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*O8Q9mNlR7_DEGrpQ1oekBg.png" /><figcaption>Design-centric feature lifecycle</figcaption></figure><p>While the engineering team responsible for building our new dashboard UI also leans full-stack, the distinct passion and accountability for design and modern frontend technology is a noteworthy asset to the product as a whole.</p><h3>Test Engineers Need Love Too 💘</h3><p>Before WUI components and the new dashboard took flight, test engineering and the QA process largely took place in its own silo. Now, test engineers have a seat at the table in product strategy, design kickoffs, and ticket grooming. Thankfully, the design system has also introduced a dramatic improvement to our collaboration and engineer-to-QA handoff.</p><h4>Challenges &amp; Opportunity</h4><p>Our old method of testing relied on targeting an element by its CSS class name or text in the element itself—a common yet cumbersome approach that would need bulldozing as we rewrote the dashboard and introduced components.</p><p>Here’s an example of a locator used to identify a nested and conditionally-rendered “Contact Us” link using the old process in the Angular dashboard:</p><figure><img alt="Old test target for “Contact Us” link" src="https://cdn-images-1.medium.com/max/1024/1*W_ZasTTmmfjBiqiefeEETQ.png" /></figure><p>Yikes. This isn’t just hard on the eyes; it’s also incredibly brittle. If we changed the HTML structure or the class .section-description, this test would break. This approach compounded across the entire dashboard lead to fragile tests and hesitation toward any form of design iteration.</p><p>With a clean slate ahead of us, we jumped at the opportunity to introduce new best practices for reliable targets in the form of unique, action-oriented IDs.</p><h4>Test IDs as Data Attributes</h4><p>Dashboard engineers are now responsible for applying these IDs in the form of data-test attributes on all interactive and non-static elements, including but not limited to:</p><ul><li>Buttons &amp; links</li><li>Form fields</li><li>Any element that renders data received from an API or text that changes based on user input</li></ul><p>With a test ID, targeting our “Contact Us” link above can be as simple as:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tg2__dr3TNqTG66nH5Nc0g.png" /></figure><p>To ensure that our new ID names don’t become just as messy as custom classes, we employ a <strong>kebab-case, verb-first, REST-like </strong>structure.</p><p><strong>✅ </strong>We<strong> do</strong> want to provide unique &amp; descriptive names:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*iGIGLTcStYItLP9c_ariRA.png" /><figcaption>Example test IDs on various elements</figcaption></figure><p><strong>🚫 </strong>We <strong>don’t</strong> want to apply vague IDs that match the text content or provide no further insight into the element’s action or data:</p><figure><img alt="Example of a bad test ID application" src="https://cdn-images-1.medium.com/max/1024/1*xwWkI0p-YP6HqaumWcOPug.png" /><figcaption>This doesn’t help anyone!</figcaption></figure><h4>Test IDs in the Wild</h4><p>In the spirit of enhancing the QA process as a whole and making these IDs easier to find, I was inspired to build a Chrome extension called <em>Scout</em> that locates &amp; highlights them at the flip of a switch:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*w7hOsSfhgAZ0GC6CvlRnGw.png" /><figcaption>Scout Chrome Extension</figcaption></figure><p>We’ve also created a custom eslint plugin that identifies missingdata-test attributes for each commit, and added a data-test PR checklist line item to ensure this step is covered by the time the work hits QA.</p><p>Overall, the restructuring of our process and introduction of test IDs have reduced frustration, improved code readability, increased test stability, and spawned a tighter collaboration with our test engineers.</p><h3>Looking Ahead ☀️</h3><p>The future is bright for the JW Player dashboard as it continues to grow and evolve into a modularized, component-based system driven by a design-focused squad. Shared ownership combined with a solid and iterative source of truth ensures that we can deliver high-quality features in a fraction of the time and measure them more effectively. Additional health check tools like automated Lighthouse performance audits are also on the horizon.</p><p>Our Hook design library, WUI component library, an API companion library (more on that someday!) has created a home for front-end excellence at JW Player and dramatically improved the designer, developer, and user experiences alike.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9d2328cfff4f" width="1" height="1" alt=""><hr><p><a href="https://medium.com/jw-player-engineering/streamlining-the-design-x-engineering-partnership-9d2328cfff4f">Streamlining the Design x Engineering Partnership</a> was originally published in <a href="https://medium.com/jw-player-engineering">JWX Product &amp; Engineering</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A real-life roadmap for building a design system—Pt II]]></title>
            <link>https://medium.com/jw-player-engineering/a-real-life-roadmap-for-building-a-design-system-pt-ii-c4c2490875fe?source=rss-3660f6373fbb------2</link>
            <guid isPermaLink="false">https://medium.com/p/c4c2490875fe</guid>
            <category><![CDATA[design]]></category>
            <category><![CDATA[front-end-development]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[typescript]]></category>
            <dc:creator><![CDATA[Kim Hart]]></dc:creator>
            <pubDate>Wed, 16 Sep 2020 14:44:27 GMT</pubDate>
            <atom:updated>2020-11-25T16:50:37.896Z</atom:updated>
            <content:encoded><![CDATA[<h3>Creating a Custom Web Component Library</h3><h4>A real-life roadmap for building a design system — Pt II</h4><p>In case you missed it, be sure to check out P<a href="https://medium.com/jw-player-engineering/a-real-life-roadmap-for-building-a-design-system-pt-i-a805d81bd90">art I: Translating design principles into scalable code</a>. Here we’ll take a look at how we built a custom web component library that powers our content management application and supports React, Angular, and framework-free projects.</p><h3>The Challenge 🍝</h3><p>The JW Player enterprise dashboard is a robust product that many of our users rely on for their daily workflows. It provides a GUI for our APIs, allows customers to manage their tools and content throughout every stage of our platform — video players, ad schedules, live stream events, etc — it operates conditionally based on user entitlements, and handles sensitive billing and account data.</p><p>UI execution for all these complex workflows hasn’t always been lean. Inputs, buttons, checkboxes, toggles, loading spinners, tables, modals… nearly everything<em> </em>has been rewritten, restyled, and functionally wired-up from scratch.</p><p>Engineers dreaded UI-heavy tickets and focused more on backend work, it was common to find visual bugs in production, and our QA team’s job got incrementally harder.</p><p>Our design and front-end contributors determined that the best way to tackle our growing nightmare of spaghetti-UI was to implement a library of <strong>reusable components.</strong></p><h3>The Solution 💫</h3><p>If you’ve worked with any number of modern Javascript tools, you’re probably familiar with the concept of components: collections of HTML, JS &amp; CSS that define modular pieces of UI and UX.</p><p>We built ours around these golden rules:</p><ul><li>A UI component is always <strong>product-agnostic</strong></li><li>A UI component is always <strong>framework-agnostic</strong></li><li>A UI component is <strong>reusable</strong></li></ul><p>Our enterprise dashboard runs on Angular and a range of other projects are built in React, so our first goal became creating a system that could support both. The first iteration began with <a href="https://storybook.js.org/">Storybook</a>.</p><h3>A Tale of 2 Storybooks 📕</h3><p>Storybook is a platform that allows you to develop components in isolated environments without the need for a complex dev stack, database connections, or the need to dig through browser dev tools to force an element into a specific state.</p><p>A component can be developed, debugged, tested, and documented with a range of “stories” that demonstrate its functionality and limitations. This format is very helpful for demoing interaction design and things like loading, disabled and error states.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NSg9acuAbzhQtyG0QGk0yg.png" /><figcaption>Storybook interfaces for date-picker, loading spinner &amp; select input</figcaption></figure><p>Users can then use the Storybook interface to toggle props on/off and enter test data with “knobs”. There’s also an “actions” tab that logs events (click, focus, etc.), and a README.md for detailing usage guidelines.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AFn0s30z0iLQleMampNT5g.png" /><figcaption>Event logs for buttons and tags</figcaption></figure><h4>Scalability Roadblocks</h4><p>The heaviest burden of this first iteration became the requirement to develop and maintain <strong>two concurrent builds of Storybook:</strong> one for Angular and one for React. The React side experienced some neglect as time-sensitive Angular dashboard tickets took precedence, and it was a challenge to keep releases coordinated.</p><p>As the number of components grew, it became difficult to categorize them in a clear and searchable way. Keeping them hidden behind collapsed categories meant that engineers often couldn’t find what they needed.</p><p>We went back to the drawing board to assess how we could support all projects — with better docs — and without the duplicated effort and cognitive load of developing in more than one framework.</p><h3>The Case for Web Components 🕸</h3><p>We were 2/3 on our golden rules — we had achieved <strong>reusable</strong> and <strong>product-agnostic</strong> — but to be truly <strong>framework agnostic</strong>, we also had to support the projects that use no framework at all. Web components to the rescue!</p><p><a href="https://developer.mozilla.org/en-US/docs/Web/Web_Components">Web components</a> allow developers to write more semantic (and therefore more accessible) HTML in a reusable way that is easy to maintain and compatible across all browsers. They’re ideal for UI components that can be used in framework-free environments.</p><h4>Building with Stencil</h4><p>Our research on web component implementation led us to <a href="https://stenciljs.com/docs/introduction">Stencil</a>, a system that combines the best concepts of the most popular front-end frameworks into a <strong>compile-time rather than runtime tool</strong>. It takes TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, an asynchronous rendering pipeline (similar to React Fiber), and lazy-loading out of the box, and it generates 100% standards-based web components that run in any browser supporting the Custom Elements v1 spec.</p><p>Bindings make it possible to build your component <strong>once</strong> as a web-component, then Stencil wraps it appropriately and emits libraries in the framework of your choice (in our case, Angular &amp; React). Then you can build and deploy it as necessary for different use-cases.</p><p>Using Stencil to build our new <strong>Web UI Components (WUI) </strong>removed the need to develop for multiple frameworks and also gave us the flexibility to support projects written in vanilla JS.</p><h3>Using WUI 🔧</h3><p>Like Hook, WUI is consumable by CDN or our internal npm registry, so it’s easily accessible for all teams in our organization.</p><p>Using WUI in a vanilla project is as easy as adding the following CDN-hosted scripts to your document:</p><pre>&lt;script type=&quot;module&quot; src=&quot;https://wui.jwplayer.com/v/[version]/dist/wui/wui.esm.js&quot;&gt;&lt;/script&gt; &lt;script nomodule src=&quot;https://wui.jwplayer.com/v/[version]/dist/wui/wui.js&quot;&gt;&lt;/script&gt;</pre><p>…and then referencing the components in HTML:</p><pre>&lt;wui-button type=&quot;tertiary&quot; label=&quot;Play&quot; icon=&quot;play&quot; /&gt;</pre><p>Alternatively, a React developer would pull in this package via npm:</p><figure><img alt="Importing components from WUI in React" src="https://cdn-images-1.medium.com/max/1024/1*33N0KFs9hqCW7_0Ki5O7jg.png" /><figcaption>Importing WUI components in React</figcaption></figure><p>Here’s where Typescript shines. It helps prevent type coercion and bugs on the component-development side, but it also provides excellent autocomplete support in IDEs like VS Code on the UI-development side.</p><p>Strictly typing our components means that their names and props are always consistent and enforced, and therefore less prone to breakage. It also reduces strain on developers who use WUI by removing the need to memorize props and their potential values, meaning the components are rarely misused.</p><p>Here’s an example of Typescript autocomplete in action for a play icon component in a React context:</p><figure><img alt="Code examples of Typescript autocomplete features" src="https://cdn-images-1.medium.com/max/923/1*xYeploXmGNmz32L2wbpbiw.png" /><figcaption>Autocomplete support in VS Code</figcaption></figure><h3>Creating an Intuitive API 🧠</h3><p>WUI is built by engineers, for engineers. To be intuitive, consistent, and performant, its API must stay as close to the existing DOM API as possible. For example, wui-check-input accepts the propsdisabled and checked—both valid HTML attributes—which can be passed directly to our inner input element without extra configuration or translation.</p><p>This concept is also useful when handling events; we don’t need to add custom @Event properties to our components when there’s already an HTML event that we can rely on. A wui-input is constructed by wrapping a standard HTML input element and adding our styles and markup around it. Then, when a user types in the input element, it emits the input and change events. Because these events bubble up, we don&#39;t need to account for them separately.</p><h4>Custom Props &amp; Children</h4><p>To discourage developers from passing incompatible child elements to any given component, we restrict the contents with strictly-typed props and construct the resulting HTML accordingly. Here’s an example of how we use a string label prop to guard against rogue child elements and remove the guesswork of populating a wui-button:</p><figure><img alt="Code examples for right and wrong button implementation" src="https://cdn-images-1.medium.com/max/964/1*SbWTO1Eckk_WHOZODqGRJQ.png" /></figure><p>For components that require children that can’t be strictly typed, we can still ensure that the contents end up in the right place with the right styles by placing them in a &lt;slot&gt;&lt;/slot&gt;, seen here with a wui-modal body &amp; footer:</p><figure><img alt="Code detailing how to use &lt;slot&gt; syntax for dynamic child elements" src="https://cdn-images-1.medium.com/max/1024/1*sbXPhV0oZbBKgFbUkqkJtA.png" /><figcaption>&lt;slot&gt; usage for dynamic child elements</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jcRzdmS9DtYD4F4JvBhATA.png" /><figcaption>Modal example</figcaption></figure><p>Now our new web components and their updated APIs needed a home for their documentation. Our front-end lead, <a href="https://github.com/pajter">Pieter Janssen</a>, took WUI to the next level with an imaginative take on a custom docs site called <strong>Atlas</strong>.</p><h3>Introducing Atlas 🗺</h3><p>Atlas became everything we couldn’t pull off in Storybook at the time: a <strong>single, highly dynamic hub</strong> that showcases all of our available components more visually, with interactive documentation and changelogs for each release. It’s built with React &amp; SCSS and is tested with Jest and Puppeteer.</p><p>Running Stencil’s component server alongside the Atlas server results in a super-fast, hot-reloading environment where we can develop components and Atlas UI (documentation) in one fell swoop.</p><p>The browse page alphabetically lists dynamic (functional!) previews of each component. Because these aren’t static images, they can’t get stale — ensuring that they’ll always reflect the accurate design of each component.</p><figure><img alt="WUI Atlas browse page" src="https://cdn-images-1.medium.com/max/1024/1*7l8xeInC3cFN0x9Qr2mFgg.png" /></figure><p>The dynamic preview panes and real-time code samples are made possible by our use of <a href="https://mdxjs.com/"><strong>MDX</strong></a><strong> </strong>(markdown that renders JSX), which allows us to weave interactive components straight into the documentation itself.</p><p>Let’s take a look at an wui-alert page with a preview of several use-cases. We can toggle the built-in code editor, see how they’re built, and even update the code to see immediate results in the previews above. This section also features an action log and a theme toggler to view how the components adjust to dark and light backgrounds.</p><figure><img alt="Example of an Alert component documentation" src="https://cdn-images-1.medium.com/max/1024/1*WeWc2T0nHLSNYK6CEUhsMQ.png" /><figcaption>WUI Alert previews</figcaption></figure><p>The true beauty of theses docs lie in their <strong>autogeneration</strong>: the Props, Events &amp; Methods markdown categories are automatically populated from the component’s prop type definitions. This ensures that our docs always match the code and that we don’t spend time rewriting them from scratch.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jfgwVd8ucCUAIMwS4x4bOQ.png" /></figure><p>Atlas also features a <strong>playground</strong> mode, where you can freely edit a code example with any valid JSX and then share the link with anyone who has access to Atlas:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SQ9RjDA7-HxF8cUshYD0HQ.png" /><figcaption>Atlas playground example</figcaption></figure><p>Because the code remains editable and the output is fully interactive, this feature has become incredibly helpful for sharing quick samples and debugging faulty implementation.</p><p>Its easy-to-scan design coupled with flexible docs has made Atlas a tool that’s as beautiful as it is functional. It has become indispensable to JW Player engineers who work on front-end projects.</p><h3>The Payoff 🎉</h3><p>At the time of writing this, WUI is at v7.3.0 and steadily growing. The Stencil-based web components approach has proven to be a great improvement on past iterations and has integrated seamlessly into our major codebases.</p><p>The combination of a consumable design library like Hook and a highly flexible component library like WUI has saved countless developer hours, allowed us to remove duplicated code, made our UI more beautiful and consistent, improved our QA testing process, and has encouraged our teams to forge ahead on UI-heavy projects with confidence.</p><h3>Next Up… 🧚‍♀️</h3><p>In <a href="https://medium.com/jw-player-engineering/streamlining-the-design-x-engineering-partnership-9d2328cfff4f">part 3</a>, we’ll investigate how we use Hook, WUI, and other internal tools to improve design handoff and forge a stronger partnership between designers and engineers.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c4c2490875fe" width="1" height="1" alt=""><hr><p><a href="https://medium.com/jw-player-engineering/a-real-life-roadmap-for-building-a-design-system-pt-ii-c4c2490875fe">A real-life roadmap for building a design system—Pt II</a> was originally published in <a href="https://medium.com/jw-player-engineering">JWX Product &amp; Engineering</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A real-life roadmap for building a design system—Pt I]]></title>
            <link>https://medium.com/jw-player-engineering/a-real-life-roadmap-for-building-a-design-system-pt-i-a805d81bd90?source=rss-3660f6373fbb------2</link>
            <guid isPermaLink="false">https://medium.com/p/a805d81bd90</guid>
            <category><![CDATA[design]]></category>
            <category><![CDATA[frontend]]></category>
            <category><![CDATA[ui]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[engineering]]></category>
            <dc:creator><![CDATA[Kim Hart]]></dc:creator>
            <pubDate>Mon, 31 Aug 2020 16:41:06 GMT</pubDate>
            <atom:updated>2020-11-23T19:56:25.017Z</atom:updated>
            <content:encoded><![CDATA[<h3>Translating Design Principles into Scalable Code</h3><h4>A real-life roadmap for building a design system — Pt I</h4><p>Welcome to the first installment of a 3-part series outlining how JW Player’s small team of front-end &amp; design nerds leveraged a homegrown design system and web component library to modernize our suite of products.</p><p>If you’re new to this realm, I encourage you to start with some prerequisite material like Emma Bostian’s <a href="https://dev.to/emmabostian/design-systems-part-i-foundations-45hd">Design Systems Foundations</a> to get up-to-speed.</p><p>The goal of this series is not to provide design philosophy or help you integrate with giants like <a href="https://material.io/design">Material Design</a>, <a href="https://www.carbondesignsystem.com/">IBM Carbon</a> or <a href="https://airbnb.design/building-a-visual-language/">AirBnb</a>, though they were each considered in our research. Instead, we’ll dig into the strategies, pitfalls and successes of our small-but-mighty custom solution.</p><h3>The Challenge 💡</h3><p>In our earlier days, design implementation on the front-end of our products wasn’t all that strong. Our CSS files were massive, variables were defined in every corner of every project, and there wasn’t a central home for patterns and assets that engineers rely on to deliver high-quality UI.</p><p>While this situation isn’t uncommon, it’s also a guaranteed path to incurring UX inconsistencies and a lot of tech debt. As our many engineering teams continued to scale, undoing this tangle and creating a single source of truth became our #1 priority.</p><h3>Creating Neverland ✨</h3><p>Our designers had already established a set of design principles and patterns within Sketch—the trick was making those patterns accessible for engineers.</p><p>Thanks to a lightweight documentation-site generator called <a href="https://docsify.js.org/#/?id=docsify">docsify</a>, we quickly spun up a home for our new design ecosystem with just a handful of markdown files, an index.html and some minimal CSS. It contains visual representations of our assets, overall usage guidelines, and links to our master Sketch files.</p><p>The JW Player Design Team ran with the Peter Pan theme after launching two internal prototyping tools called Smee and Tinker Bell, so it was only natural that our design system became known as <strong>Neverland</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_hmXP7tFds8oAX0lOmOpDQ.png" /><figcaption>Brand colors and iconography docs in Neverland</figcaption></figure><p>Because Neverland is built from markdown files and doesn’t rely on complex source code, its contents are easily managed by the designers—freeing up engineering resources and helping to maintain the source of truth.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*R5ooD0hEUVXNsgUEUZ1_bA.png" /><figcaption>Data color schemes in Neverland</figcaption></figure><h3>Introducing Hook ⚓️</h3><p>In order to make Neverland more than just a set of fancy docs, we built <strong>Hook</strong>: a design library consumable from all projects that outputs our foundational assets and values. It includes:</p><ul><li><strong>Brand, system, and data colors: </strong>all AA-complaint and based on WCAG 2.0 standards</li><li><strong>Iconography:</strong> individual SVGs and product-specific sprites</li><li><strong>Typography: </strong>font families, weights, sizes</li></ul><p>Hook is available via CDN or as a yarn or npm package. Most projects use it by installing the package from our private registry:</p><pre>yarn add @design/jw-design-library</pre><p>and importing the required files ad-hoc:</p><pre>@import &quot;@design/jw-design-library/dist/less/brand-colors.less&quot;<br>@import &quot;@design/jw-design-library/dist/less/system-colors.less&quot;<br>@import &quot;@design/jw-design-library/dist/less/fonts.less</pre><pre>.my-cool-icon {<br>    fill: @ds-color-brand-midnight;<br>}</pre><pre>.my-cool-error-message {<br>    color: @ds-color-system-red;<br>    font-family: @ds-global-font-family-custom;<br>}</pre><p>Simple vanilla JS projects can use it by importing the relevant CDN link in their document &lt;head&gt;:</p><pre>&lt;link href=&quot;https://hook.jwplayer.com/jw-design-library/{version}/css/fonts.css&quot; rel=&quot;stylesheet&quot; /&gt;</pre><p>Hook is tagged &amp; versioned on GitHub and published via npm and our internal CDN route, allowing users to target a specific versions of Hook and have total control over when and how they update.</p><pre>// package.json</pre><pre>&quot;dependencies&quot;: {<br>    &quot;@design/jw-design-library&quot;: &quot;5.3.0&quot;<br>}</pre><h4>Defining Design Tokens</h4><p>Hook’s lean output is part of what makes it universally-accessible: in other words, it doesn’t weigh down the performance of a project that uses it. Instead of hosting CSS declarations and mixins — anything that needs compiling—Hook is configured with <a href="https://github.com/amzn/style-dictionary/">Amazon’s Style Dictionary</a>, which parses semantic design tokens (key-value pairs) and outputs <strong>only variables.</strong></p><p>Aside from performance wins, the extra beauty of this approach lies in the completely customizable yaml config files.</p><p>To understand how all of this ties together, first let’s take a look at the four main categories of our project.</p><ol><li><strong>/assets — </strong>.tff font files, individual SVGs for icons &amp; logos</li><li><strong>/properties</strong> — yaml definitions &amp; values for fonts, colors, icons</li><li><strong>/config</strong> — yaml files that handle name-spacing &amp; output locations</li><li><strong>/dist </strong>— Output containing .woff font files, sprites &amp; SVGs, and variables (we support CSS, Less, SCSS and Javascript formats)</li></ol><h4>Naming Variables</h4><p>Constructing your variable names based on a style dictionary like ours can be tedious, but the consistency it enforces is well worth the upfront effort. We’ve built our configs to output long, yet predictable, names that almost read like sentences. We’re of the mindset that long + verbose is better than short + obscure, especially because engineers have access to autocomplete packages like <a href="https://marketplace.visualstudio.com/items?itemName=mrmlnc.vscode-scss">SCSS IntelliSense</a> to help with typing longer values.</p><p>Each variable is prefixed with ds- (<em>design system</em>) so we can easily tell them apart from other project-specific variables at a glance.</p><p>Here’s a simplified example of how we’ve named our colors:</p><pre>$ds-color-brand-dahlia;<br>$ds-color-brand-dahlia-dark;<br>$ds-color-brand-dahlia-darker;<br>$ds-color-brand-dahlia-fade;</pre><pre>$ds-color-system-red;<br>$ds-color-system-green;<br>$ds-color-system-blue;</pre><p>…and fonts:</p><pre>// Typefaces</pre><pre>$ds-global-font-family-custom;<br>$ds-global-font-family-code;<br>$ds-global-font-family-system;<br>$ds-global-font-family-data;</pre><pre>// Weights</pre><pre>$ds-global-font-weight-custom-regular;<br>$ds-global-font-weight-custom-semibold;</pre><h4>Generating Color Variables</h4><p>Let’s take a high-level look at how we actually end up with these scss variables for our brand colors.</p><ol><li>We define our names &amp; values in the brand colors file</li><li>We tell style dictionary what format to use, what to call the files, and where to put them</li><li>The build script does some magic under the hood and creates a consumable file in the/dist folder with all our new variables</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7-O9oLk40xxySiuSd1am0Q.png" /></figure><h4>Generating Icons</h4><p>Icons don’t require variable names, but they easily fit into the style dictionary paradigm. Our configs export both individual icons and combined SVG sprites: one for the video player and one for the dashboard.</p><p>Let’s use these three icons called “play”, “preview” and publish” to see how they get processed into the overall <strong>dashboard</strong> sprite.</p><figure><img alt="Icon examples" src="https://cdn-images-1.medium.com/max/385/1*9JEWrqHhdOK8o3xej7LB-A.png" /></figure><ol><li>Store single SVGs for each icon in our assets folder</li><li>Define tokens per icon. In this case, its name and path to the local SVG file</li><li>Define our sprite config: necessary formatting, names and destinations</li><li>The build script runs each matched icon through <a href="https://github.com/svg/svgo">SVGO</a>, then converts the SVG into a &lt;symbol&gt;. After all icons in the group are optimized, a wrapper is added and the file is output as a sprite</li></ol><figure><img alt="Icon sprite generation example" src="https://cdn-images-1.medium.com/max/1024/1*788JWk4gaNf4ujeoFmYiiw.png" /></figure><h4>Using Icons</h4><p>We can now reference these icons in a few ways. Our <strong>web component library</strong> (more on that to come!) imports each icon individually and processes them into a flexible Typescript-friendly component that handles the correct image via a name prop/attribute.</p><p>Alternatively, you can include the sprite in your project and reference individual pieces of it with use href syntax. The contents of the sprite need to be included somewhere in the body, just once:</p><pre>&lt;svg xmlns=&quot;http://www.w3.org/2000/svg&quot; id=&quot;ds-sprites-dashboard&quot; style=&quot;display:none&quot;&gt;<br>  &lt;symbol viewBox=&quot;0 0 24 24&quot; id=&quot;ds-icon-dashboard-play&quot;&gt;&lt;path d=&quot;M20.11 10.34l-12-8A2 2 0 0 0 5 4v16a2 2 0 0 0 3.11 1.66l12-8a2 2 0 0 0 0-3.32z&quot;/&gt;&lt;/symbol&gt;<br>  &lt;!-- more &lt;symbols&gt;... --&gt;<br>&lt;/svg&gt;</pre><p>… and then you can reference individual icons by id like so:</p><pre>&lt;svg class=&quot;my-cool-icon&quot;&gt;&lt;use href=&quot;#ds-icon-dashboard-play&quot; /&gt;&lt;/svg&gt;</pre><h4>Extending Hook</h4><p>The examples I’ve provided here only scratch the surface of what Hook supports; we’ve also built in layout values for our 8px grid and linked extension projects that handle D3 color interpolation, custom docsify themes, and pre-baked Pendo templates.</p><h3><strong>The Payoff </strong>🎉</h3><p>We’ve experienced measurable improvements since the implementation of Neverland + Hook — including faster speeds, fewer visual bugs, and an overall decrease in tech debt and engineer headaches.</p><p>It’s especially powerful to leverage a framework-agnostic system that supports everything from our core products, to marketing demos, to internal hack week projects.</p><h3>Next Up… 🧚‍♀️</h3><p>Tune in for an in-depth look at how we’ve improved our dashboard by combining Hook—our extensible design library—with a custom Typescript-based web component library that serves vanilla JS, React, and Angular projects.</p><p><a href="https://medium.com/jw-player-engineering/a-real-life-roadmap-for-building-a-design-system-pt-ii-c4c2490875fe">Part II</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a805d81bd90" width="1" height="1" alt=""><hr><p><a href="https://medium.com/jw-player-engineering/a-real-life-roadmap-for-building-a-design-system-pt-i-a805d81bd90">A real-life roadmap for building a design system—Pt I</a> was originally published in <a href="https://medium.com/jw-player-engineering">JWX Product &amp; Engineering</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>