<?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 Georgy Malanichev on Medium]]></title>
        <description><![CDATA[Stories by Georgy Malanichev on Medium]]></description>
        <link>https://medium.com/@gmlnchv?source=rss-98865a211a4c------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*z6GpzrTnamcvAaC1CKwu8Q.jpeg</url>
            <title>Stories by Georgy Malanichev on Medium</title>
            <link>https://medium.com/@gmlnchv?source=rss-98865a211a4c------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 21:12:32 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@gmlnchv/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[Documentation Primitives]]></title>
            <link>https://medium.com/dan-stories/documentation-primitives-ff76736fad5e?source=rss-98865a211a4c------2</link>
            <guid isPermaLink="false">https://medium.com/p/ff76736fad5e</guid>
            <category><![CDATA[storybook]]></category>
            <category><![CDATA[documentation]]></category>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[component-libraries]]></category>
            <dc:creator><![CDATA[Georgy Malanichev]]></dc:creator>
            <pubDate>Thu, 30 Jul 2020 03:26:06 GMT</pubDate>
            <atom:updated>2020-07-30T04:12:18.532Z</atom:updated>
            <content:encoded><![CDATA[<p>Accessible, best practice docs for Storybook</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vcQXRoS51TSehlOBWGndpg.png" /><figcaption>Documentation Primitives for Storybook</figcaption></figure><p>Good documentation — <em>accessible</em>, <em>extensive,</em> and <em>up-to-date</em> — is crucial to building trust and driving the adoption of any software product, including design systems.</p><p>Producing and maintaining documentation is never the responsibility of any single discipline. As <a href="https://product.hubspot.com/blog/how-to-gain-widespread-adoption-of-your-design-system">this HubSpot article</a> points out, the task is <em>co-owned</em> by designers and developers. Each discipline can then contribute its skills, context, and the unique perspective towards this challenge.</p><p>How do we make working on documentation easy for both designers and developers?</p><p>This is an interesting challenge for the design system infrastructure. Is there a platform that helps each discipline fulfill their documentation goals while enabling collaboration in a seamless and transparent way?</p><p>Can it be solved without investing in a fully custom solution (not every organisation has a budget for it, or scale large enough to justify the need), or having to maintain multiple platforms which inevitably go out-of-sync (a common scenario is using <a href="https://storybook.js.org/">Storybook</a> for components and <a href="https://www.zeroheight.com/">zeroheight</a> for documentation)?</p><p>At <a href="https://www.dan.co.nz/">Digital Arts Network</a> we experiment with <a href="https://storybook.js.org/">Storybook</a> a lot and believe it could be the ultimate shared resource for both component code <em>and</em> documentation. Teams already use it to build, test, and catalog components. With the latest version of the <a href="https://github.com/storybookjs/storybook/tree/master/addons/docs">Docs Add-on</a>, we can author long-form documentation that doesn’t have to be strictly text-based. Powered by <a href="https://mdxjs.com/">MDX</a> (allows to embed components into Markdown pages), documentation can be composed out of smaller DocBlocks — think UI components, but for <em>narrative</em>. This makes perfect sense, we are already building apps using components — we can document them in much the same way.</p><p>With Storybook, Docs Add-on, and MDX, we have a robust foundation for writing documentation that can successfully mix text, component examples (“stories” in Storybook terms), and DocBlocks. DocBlocks is what makes documentation more expressive and engaging while keeping the entry barrier low for non-technical contributors. Effectively, anyone with a GitHub (or GitLab, or BitBucket) account (web editing interfaces are perfect for this — no need to keep a local copy of the project) can start contributing to documentation.</p><p>This is an example of what an MDX-enhanced narrative looks like:</p><pre># Our brand colours</pre><pre>Our colors are optimized to meet WCAG 2.0 Level AA Accessibility Guidelines.</pre><pre>&lt;Usage&gt;<br>  &lt;Correct&gt;Use &quot;Red 500&quot; for validation error text.&lt;/Correct&gt;<br>  &lt;Incorrect&gt;<br>    Don’t combine color values in ways that do not meet minimum<br>    accessibility contrast requirements.<br>  &lt;/Incorrect&gt;<br>&lt;/Usage&gt;</pre><p>Notice how we are still mostly writing text, while the <em>&lt;Correct&gt;</em> and <em>&lt;Incorrect&gt;</em> tags, wrapped in a <em>&lt;Usage&gt;</em>, handle all the markup and styling required to render a “Do / Do Not” section, similar to those used by <a href="https://polaris.shopify.com/">Polaris</a> and <a href="https://www.carbondesignsystem.com/">Carbon</a> design systems.</p><p>We don’t have to rely on 3rd party platforms for customisation options or to be able to insert a certain type of content— we can achieve that with custom components. Storybook ships with a selection of ready-to-use DocBlocks. More custom DocBlocks are being built by the Storybook community. One of these packages is our own <strong>Documentation Primitives</strong> library.</p><h4>Introducing Documentation Primitives</h4><p><a href="https://github.com/DAN-AKL/storybook-documentation-primitives">Documentation Primitives</a> is a collection of simple, low-level building blocks — <em>primitives</em> — for building design system documentation in Storybook. At the moment, it includes colour swatches, usage blocks (“Do / Do not”), note and warning panels, spacing scale tables, and other smaller utilities. These reusable blocks complement and extend the Storybook built-in documentation capabilities.</p><p>The blocks are low-level by design which means they can be adopted by design system teams with very different needs.</p><p>👉️ <a href="https://github.com/DAN-AKL/storybook-documentation-primitives"><strong>Documentation Primitives on GitHub</strong></a>.</p><p>Great documentation is within reach for teams of any size. Auto-generated by Storybook, enhanced and extended by custom MDX components, it stays up-to-date with the components and allows non-technical team members to contribute.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ff76736fad5e" width="1" height="1" alt=""><hr><p><a href="https://medium.com/dan-stories/documentation-primitives-ff76736fad5e">Documentation Primitives</a> was originally published in <a href="https://medium.com/dan-stories">DAN Stories</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[From variables to tokens — a few tips to get you started]]></title>
            <link>https://medium.com/dan-stories/from-variables-to-tokens-a-few-tips-to-get-you-started-552eeeb10672?source=rss-98865a211a4c------2</link>
            <guid isPermaLink="false">https://medium.com/p/552eeeb10672</guid>
            <category><![CDATA[design-systems]]></category>
            <dc:creator><![CDATA[Georgy Malanichev]]></dc:creator>
            <pubDate>Tue, 11 Feb 2020 23:07:10 GMT</pubDate>
            <atom:updated>2020-02-11T23:20:36.144Z</atom:updated>
            <content:encoded><![CDATA[<h3>From variables to tokens — a few tips to get you started</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*T1KlQ8hAtH7I_XdF" /><figcaption>Photo by <a href="https://unsplash.com/@delilaziebart?utm_source=medium&amp;utm_medium=referral">Delila Ziebart</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>A common challenge when implementing a token-based design language is deciding what values need to be tokenised. Drawing the line between what goes into tokens and what is defined by the component’s own styles can be hard.</p><p>The challenge is not entirely new to developers. To solve it we can apply similar heuristics we use when setting traditional (S)CSS variables.</p><p><em>These recommendations are largely based on the insights shared by Zak Brown, a co-creator of </em><a href="https://diez.org/"><em>Diez</em></a><em>, on the </em><a href="https://design.systems/slack/"><em>Design Systems Slack</em></a><em>.</em></p><h4>Reusable values</h4><p>Design tokens are shared between multiple platforms and languages, therefore, you could start with tokenising values that you expect to be reused across applications. Not every design system is created from scratch and starting from an existing implementation and hoisting values up into a shared layer is a common scenario for many teams.</p><h4>Brand values</h4><p>A common use case for design tokens is capturing the elements of a brand identity or design language. The use of brand colours and typography usually follows strict guidelines and building a repository of tokens to distribute and enforce these rules is a good starting point.</p><p>Of course, there are no hard-and-fast rules and most teams will find themselves using some combination of the above methods.</p><p>Leveraging modern design token tooling (<a href="https://amzn.github.io/style-dictionary/#/">Style Dictionary</a> and <a href="https://diez.org/">Diez</a> are both extremely powerful tools) offers a few more use cases.</p><h4>Calculated values</h4><p>Consider generating accessible contrast or complementary colours for a given background colour. This is often done as part of an implementation (using colour functions in SCSS, for example). Alternatively, you may choose to ship curated groups of colours that “work together” as part of your token library.</p><p>If we look beyond <em>colour</em>, <em>typography</em>, and <em>spacing</em>, we’ll find that <em>images</em> (both raster and vector — think logos, SVG icons, background patterns) can be optimised, converted, resized, and stored using the token infrastructure.</p><p>In these scenarios, we are not only abstracting values but also the corresponding processing logic. Moving it away from actual implementations could also make your component codebases leaner and more portable.</p><h4>Theming values</h4><p>Colour values could be composed in ways that enable themes, for example, “light” and “dark” modes. If your products require theming support, generating themed colour palettes is best done at the token level.</p><p>Design tokens are an <a href="https://medium.com/dan-stories/design-tokens-the-promise-of-a-single-source-of-truth-cfab82638808">emerging concept</a> and best practices are still developing. It might be tempting to go all-in and start making corresponding tokens for each of the component’s properties. However, just like not every component <a href="https://medium.com/eightshapes-llc/i-made-this-does-it-go-in-the-system-3b67b9894531">belongs in the system</a>, not every property will benefit from being translated into tokens. In fact, starting with only a sub-set of tokenised values and gradually evolving your library is a perfectly fine strategy. New use cases will always arise as design systems grow and scale.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=552eeeb10672" width="1" height="1" alt=""><hr><p><a href="https://medium.com/dan-stories/from-variables-to-tokens-a-few-tips-to-get-you-started-552eeeb10672">From variables to tokens — a few tips to get you started</a> was originally published in <a href="https://medium.com/dan-stories">DAN Stories</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Design Tokens: The promise of a single source of truth]]></title>
            <link>https://medium.com/dan-stories/design-tokens-the-promise-of-a-single-source-of-truth-cfab82638808?source=rss-98865a211a4c------2</link>
            <guid isPermaLink="false">https://medium.com/p/cfab82638808</guid>
            <category><![CDATA[design-systems]]></category>
            <category><![CDATA[token-design]]></category>
            <dc:creator><![CDATA[Georgy Malanichev]]></dc:creator>
            <pubDate>Sun, 02 Feb 2020 21:49:59 GMT</pubDate>
            <atom:updated>2020-02-02T22:18:48.857Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_A3C3Miv8SmpQV-xTucKSA.png" /><figcaption>Design Tokens Branding by <a href="https://dribbble.com/maxvoltar">Tim Van Damme</a></figcaption></figure><p>Design tokens were a hot topic of 2019. Helped by the need to scale design systems across multiple platforms and languages, design tokens — <em>design decisions stored as key/value pairs</em> — are increasingly becoming a key element of modern design systems.</p><p>Design tokens potential to become the much sought-after “single source of truth” has seen a number of tools created to help author, manage and publish design tokens. However, not unlike the home automation market, each tool formats the design token data in its own way.</p><p>Design tokens are meant to be tech-agnostic but yet their naming and structure depend on the specific tool.</p><p>Transforming style properties from JSON to (S)CSS variables using a tool like Style Dictionary works really well — as long as it’s the only direction you are going. However, integrating other parts of the design workflow is where it gets tricky. Being able to reliably convert design data between multiple tools requires a lot of effort and custom scripting, an approach unlikely to scale beyond your immediate team.</p><p>Imagine if there was a way to seamlessly share design token data between applications and tools. Between visual tools and code. Across teams and organisations. Even beyond your own codebase, taking your design language to cloud apps. Improved interoperability would unlock a number of exciting integration opportunities for design system teams and go a long way towards closing the gap between design and engineering.</p><p>What can be done? The good news is a coordinated effort towards a universal format for design tokens got off the ground in 2019 and we are expecting to see first tools implementing the standard in 2020. Individual attempts at standardisation have been made before but now we are seeing a wider representation from vendors and system teams. There is a lot of decisions to be made as the group works its way through the spec which makes it an exciting place to watch. You can follow the progress and contribute <a href="https://www.w3.org/community/design-tokens/">here</a>.</p><p>A universal format for design tokens is a promising concept that is still in development phase but new opportunities will also mean changes to your design workflow.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=cfab82638808" width="1" height="1" alt=""><hr><p><a href="https://medium.com/dan-stories/design-tokens-the-promise-of-a-single-source-of-truth-cfab82638808">Design Tokens: The promise of a single source of truth</a> was originally published in <a href="https://medium.com/dan-stories">DAN Stories</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>