Tutorials on Design Tokens

In this post, we'll keep it short and sweet and make a sort of "hello world" implementation. This should get you a good sense of how things work when starting from scratch. Let's recap very briefly what we know about design systems, design tokens and Figmagic: Start Figma. Create a new design file by clicking New in the upper right corner and selecting Design file . In the left panel, click Page 1 and rename it to Design tokens . Figmagic picks up on a certain set of given page names, so it's vital that your naming is in line with what Figmagic expects. In that regard, Figmagic does not do any kind of intelligent inferring of data from a document other than matching its processing with named pages. On the blank new page, we need to create a frame. Press F and drag one out. Rename the frame Colors . On the design tokens page, the same principle goes for naming: Figmagic assumes that frames use a set of correct names that specify what type of entity they contain. I recommend having a high degree of hygiene when creating pages for design system usage since, while Figmagic is a tool that does not care about your internal layout, your teammates very surely will if it's all in shambles. Into the frame, add a few rectangles; I'll go with three rectangles. Change the fills of each to a unique color. I'm thinking red, green, and blue to make very distinct colors. Then, rename their layers to their color ( Red , Green , Blue in my case). Note that the names you give the layers will be what these colors are called in the token files that will be produced shortly. In this lesson, we will use our component library codebase , which includes Figmagic. Clone or download it, then install dependencies with npm install , and then finally navigate into it. To successfully run Figmagic, it needs to have a Figma URL (or document/file ID) and a Figma API token. Open up Figma. Click the Figma icon in the upper left corner. Click Help and account > Account settings . Scroll almost all the way down until you see Personal access tokens . Add a token description and press enter/return. You'll be presented a token, which will have a format like 83715-e8346292-bf3v-88s1-n932-j364ge9h687e . Copy it. Keep this token a secret, and don't check this into your code! If you do happen to leak it, just revoke the old one and get a new token. To get the file ID, right-click the heading of the file and click Copy Link , paste the link in a text editor, and copy the bit immediately after the /file/ section. The best way to handle these "secrets" is by placing them into an environment file, which, by convention, is called .env . Create it at the root of the project. Place the ID and token values into the file, like this: Figmagic will pick up that these values are present. No further configuration is technically needed. Now, to run Figmagic, you just do: Please refer to Figmagic's documentation to get a deeper understanding of what the default values are. There's going to be a bit of feedback on-screen. When it's done pulling the data from your document and processing it, you should be seeing a tokens folder at the root of your project. Inspect tokens/colors.ts : TypeScript output is the default for tokens, but we can change this with either configuration or in the actual command. Now try: Vóila—it's a plain old JavaScript file, perfect for our current tooling! You'll perhaps agree that using Figmagic is—if not magic—then at least is not very hard. It will, however, require a structured approach to how we work inside Figma, something we will look at more in my next post. We're working on a new course, The newline Guide to React Component Design Systems with Figmagic, where we go deep into a design-driven workflow giving you all the pieces—from code to know-how—to implement a design system and make it operational for web-based development. If you're looking to improve your whole team's way of working with releasing and designing continuously with a shared basis in a design system, The newline Guide to React Component Design Systems with Figmagic is the course that puts together the entire picture, from theory, to process, to practical setup.

Working effectively with Figmagic means understanding how and what it actually parses from a document. In this post, we will demystify exactly how a Figmagic-compliant Figma file needs to look for it to work as intended. On a high level, there are three page names that Figmagic looks for: These correspond to what type of thing Figmagic should process them as. You can certainly have any number of pages with other names than those within the same document. However, Figmagic itself will only process pages with the names I just listed. You do not need all of those pages—use the ones you need! Let's recap how we correctly outline our design tokens. Rename the current page to Design tokens . Next, create a frame, and into it, create a rectangle. Rename the frame Colors because we will use this frame to contain our colors. Make the rectangle a solid color, and then rename the rectangle into the name of my color. What we have done is create the basic structure required for Figmagic to create design tokens from our color swatches. Colors are a typical first use-case and are easily demonstrable, but there are many more types of tokens we can use. At the time of making this course, they are: The basic idea is the same for all of these, and they follow the pattern we have used a couple of times now for the colors: Go ahead and open up the Figmagic Design System template so that we can look at some other examples. The approach used in Figmagic is to express values as "uni-dimensional," which in common parlance just means that every item (or design token) expresses only a single detail. The effect of this is that we get a very granular design system, but collecting tokens or details together—for example, assembling a more complex design—is something that we have to do in code from the individual tokens. The opposite approach could be something like a text string that has advanced formatting, with a custom font, some particular size, some font variant, some color, some special kerning setting... and then we would need to either use all of those details together, or we somehow still need to disassemble each detail from this set of details. Some of the token types follow a very straightforward format. For example, Radii will pick up on the assigned Corner radius value. Here, we use 0, 4, 8, and 100 (for a full circle). Border widths is the same story. The stroke width is what gets picked up here: 1, 2, 4, or 8 pixels. For the animation-specific ones, it's a bit different. Instead, these directly specify a value as you can see with 0.15s or the cubic bezier functions. Since these values cannot be represented in another way, these are somewhat unique in the overall scope of how Figmagic works. Z indices also follow that pattern. Spacing and Media queries are specified by using rectangles that express the width of the token value. The exact height of these objects does not affect anything. Then for the typography tokens. This is where we need to remember and understand the uni-dimensional tokens. To chisel out our typography, we need to do it methodically. In the template, we can see Font Weights that correspond to all the allowed weights. In this case, you'll perhaps notice that the Font Families are copies, but that's just how it happens to be in this project. Overall, all of the font token frames specify their own respective aspect: weight, family, size, letter spacings... In practice, then, to get them to work together in a useable way, my recommendation is to add a dedicated Fonts frame and create Figma styles from those so that you have a reusable font style as you design within Figma . That frame will not be caught by Figmagic. Jump over to the Graphics page. Notice how Graphics do not need frames. Instead, they need to be packed into Figma components. Other than that, there's not much to say about graphics. You make them with the provided vector tools, bundle them into a component (with CMD + OPT + K ), and then tell Figmagic—through CLI or configuration—that you also want graphics to be handled. More on that later. Last but not least, open the Elements page. To properly generate elements requires close adherence to how Figmagic will parse groups and layers and their names. This complex topic deserves deeper attention, but I'll give you a brief lightning tour right here! The red lines (courtesy of the Redlines plugin ) are not required. I am using them here as a visual aid and developer guidance. An "element" is the Figmagic term for what could be called components. The rationale for calling them elements is that Figmagic elements should correspond closely to HTML elements, thus being relatively basic and not deeply nested. They should thereby also correspond to HTML primitives that already exist, like button and input . You'll see that the elements are divided into two categories: flat and nested. Flat elements, like the Select , have a shallow model: in this case, it only has a Normal state with its text and layout. Nested elements, like the Button , have one additional level of depth, here using the CSS placeholder syntax to enrich the Normal state with a :disabled level. It also uses more variants ( Warning and Error ). These elements are not generated by default, like the graphics were, so they need to be activated in configuration or in the CLI. Generated elements do not strictly, technically, need to correspond to anything that's set up in the tokens. You would, however, get a warning stating that value so-and-so was hard-coded since it could not be inferred from the tokens. In reality, you'd, of course, want to design these elements from the atomic design tokens as far as possible. Figmagic won't be your blocker, though, if you need to go out of bounds for a bit! By now, you should be able to create a Figma document that can be used together with Figmagic. You've also seen all three types of objects you can generate with it and how you need to approach each one of them. Figmagic makes Figma, an already amazing tool, even better for design-oriented development teams. Use it for simple tokens, or operationalize fully across tokens, graphics output and component generation: it's in your hands. We're working on a new course, The newline Guide to React Component Design Systems with Figmagic, where we go deep into a design-driven workflow giving you all the pieces—from code to know-how—to implement a design system and make it operational for web-based development. If you're looking to improve your whole team's way of working with releasing and designing continuously with a shared basis in a design system, The newline Guide to React Component Design Systems with Figmagic is the course that puts together the entire picture, from theory, to process, to practical setup.

One magic, simple concept (design tokens) and a one-stop shop (Figmagic) to contain our design make one hell of a powerhouse. Let's learn what design tokens are and how you can work with a “structured design” approach using Figmagic, a command-line interface tool that extends what we can do with Figma. Figmagic lets us do three things: pull design tokens, extract graphics, and generate React components. In this post, we will discuss the core concept "design tokens". Tokens offer a form of “contract” between a designer’s intent and its fulfillment by developers. This means that both sides agree to treat the individual parts of a complete design through the tokens that represent those values. As a format, they are super easy to read, understand, and adapt for consumption by many types of systems or applications. That’s very important as you start doing cross-platform apps and anything similarly complex. Tokens ensure that values are not magic numbers or ”just picked at random.” This makes communication precise and effortless. Creating actual code for components, even complex ones also becomes a lot less of a bore since what you are doing is just pointing stuff like padding, Z indices, and anything else to their token representations. For instance, we need to add margins to a box. Let's see what we have available: Given the above, the small spacing is the single spacing you can use for your margins, paddings, or other sizes. For sure, you sometimes need to hardcode new unique values, but that should happen in a very small number of instances. I call this approach "structured design"—no need to make it a big concept—but it's an approach in which we leave as little as possible to chance. As far as possible, we use the tokens instead of hard-coding any values. With a single spacing it does, however, seem reasonable to believe that it's time to add some more to cater to more dynamic, realistic needs, so let's evolve the model a tiny bit: We now have two possibilities, and both are perfectly valid choices. The evolution process should be done in collaboration between the designers and developers. So, where do these tokens come from? The token has to be communicated and stored somewhere and then exported to a useful format—like our example JSON file. The exported token files themselves do not, therefore, usually constitute "the truth" as such but act only as a kind of transport artifact for the truth: Figma. The implication of this is that they only fill the role of moving a value from one system (Figma) to a variety of others (anything that accepts JSON, for example). The designer, in turn, needs to ensure correspondence between Figma styles and design tokens on their end. The rest of the tooling just happens to be things I feel are very good and happen to work well together. It's really smart to work in a structured way by assembling design systems from design tokens. Using tokens, we can shape simple elements, which can then be ordered into components and then into compositions and views from those. Design tokens fairly directly tend to create a form of taxonomy of what things exist and in which relations. So, your color "green" will be a very flat and direct way of saying what they are, but it won't say anything about where they are used. That information can be handled in other ways—though you can also use aliases to set a value like "orange" to an auxiliary value like "color-accent," thus naming by purpose : What makes sense for you to use is often use case-dependent. This can also, given the right tooling, provide the side effect of making updates to token values magically update the actual code. Bigger updates, like changing from a token X to token Y , will still require a code change, but the effort is practically negligible. By their nature, design tokens enforce the standards you have set up. Some advice for the road, as you start using design tokens in actual projects: Using design tokens as a part of your workflow will most likely make it easier to communicate the design, faster to work with coding a design, and less susceptible to breaking between UI expectations and how the design is actually coded. We're working on a new course, The newline Guide to React Component Design Systems with Figmagic, where we go deep into a design-driven workflow giving you all the pieces—from code to know-how—to implement a design system and make it operational for web-based development. If you're looking to improve your whole team's way of working with releasing and designing continuously with a shared basis in a design system, The newline Guide to React Component Design Systems with Figmagic is the course that puts together the entire picture, from theory, to process, to practical setup.