DEV Community: Thomas Gossmann

Releasing Theemo v2

Thomas Gossmann — Tue, 23 Jan 2024 14:03:02 +0000

Theemo is an open source Design Token automation suite and consists of a Figma plugin, a Sync toolkit (with integrations to read from Figma and write to Style Dictionary), theme generation and framework adapters to load those to support the entire token pipeline end-to-end.

It started as a bunch of scripts and over time they grow together to form a unity. With all of its pieces working well in harmony now and the documentation being ready, I consider this to be the version 2 of Theemo.

Highlights:

Transforms for variables in Figma
Plugin system for tooling integrations
Variable export from Figma (wo/ enterprise plan)
Extended Style Dictionary support for Transforms and Modes
Developer support for working with tokens

All of this is covered in the documentation at theemo.io. Based on the research in Inside Design Token series, which made it to the website itself.

Transforms for Variables in Figma

Theemo Figma plugin started with support for referencing styles long before there were variables in Figma. Pretty soon after was able to run transforms on those reference (eg. manipulate saturation in a reference). Figma variables support those manipulations for prototype mode but not for colors or numbers (as we use them in Design Systems). The initial feature has been updated to support color transforms with variables:

Plugin System for Tooling Authors

The idea of Theemo is to provide a token pipeline and keep the machinery running. Users configure the behavior to match their system. To connect with third-party tools for exchanging tokens, the pipeline opened up with a plugin system for those integrations.

Tooling authors can write plugins and focus on the integration of their tools. If you are a tooling author, read on, things got interesting with version 2.

Integrate with Token Sync

Sync tokens from one tool to another is the heart of Theemo. Figma and Style Dictionary are supported out of the box. In version 1 this was built in and support ended here. Inspired by eslint’s flat config, in version 2 the entire sync pipeline changed to a plugin system and continuing support for reading from Figma and writing to Style Dictionary (now as plugins).

Need to support for Penpot or another integration? Learn how to write your own plugin.

Sync Support for Figma Plugins

Are you writing a Figma plugin? Then you realized, your plugin can store data in Figma and then read it through their REST API. Oh, that data is relevant when exporting tokens from Figma? Then Theemo got you covered as it allows to develop the reading counter part. The plugin system defines an interface with different data exchange points, support the ones relevant to you. Learn how to read from your Figma plugin.

Variables Export from Figma

Figma supports exporting variables through a special endpoint, well, at least when you are on an enterprise plan. There are a lot of reasons, why you want to use the enterprise plan, but solely for exporting variables? That’s not in everyone’s budget or a reason to increase the pricing plan for your organization.

The literally hidden feature of Figma Theemo plugin is to export variables. Thanks to the new plugin infrastructure, these variables are read with the Theemo plugin for syncing from Figma.

Extended Style Dictionary support for Transforms and Modes

Before working on version 2 of Theemo, I took the research from the past years and put it into the Inside Design Token series. I discussed features and how they are supported as through theming. While working on the series, Jacob Miller from Figma opened up the discussion at the DTCG asking for Native modes and theming support. I also shared my results and the discussion is still ongoing.

Theemo v2 implements my proposed solution. As part of sync you can configure your desired behavior and the Theemo integration for Style Dictionary provides the necessary extensions to understand the format and run the build (for the curious: it’s using the single-token method).

Remember the color transformation in the Figma plugin? They are piped all the way from Figma, into the JSON files and are handled by Style Dictionary now.

Developer Support for Working with Tokens

When working with tokens in code, especially with token values as Theemo does it, there wasn’t a good code package available. Now there is @theemo/tokens with rich Typescript types to cover token types, their value formats and extensions to run your own typing experimentation.

This package is heavily influenced rsp. based on these:

style-dictionary-utils by Lukas Oppermann – Can be used as substitute to and @theemo/style-dictionary when none of the Theemo features are used.
Design Token Tools by Knapsack – Very good to read and write tokens.

It’s a bit of bittersweet to have fragmented packages like these, but also it is vital in the current situation we are in. All of these packages are here to experiement with the DTCG token format to probe its boundaries and to form the direction forward. I think we all agree to take the best parts and merge them under the banner of DTCG at some point 🙂

Next Steps?

Version 2 unlocks new capabilities and I want to share next experiments I’m eyeing on; no timeline given though, feel free to be first :]

Transforms from Figma to CSS

Color palettes can be crafted with primitive transforms (such as HSL) or new color formats, such as HSB interpolations to highly sophisticated algorithms seen in ColorBox by Lyft, Leonardo by Adobe, or Prism by Github.

FWIW is to support primitive transforms (HSL, HSB, etc.) from within Figma, export these theme internals to CSS, and write a little “Styling UI overlay”, in which you select a couple of hues to change the color of the App in realtime.

Making use of new relative colors in CSS color level 5 features while keeping an eye on value transform worklets for Houdini (to support HSB). The information are already available, thanks to Theemo. This would target special transforms for Style Dictionary to do the job.

Validations for Design Tokens

I mentioned linting to be one of the challenges for tokens. Figma introduced scopes for variables to help with that regard. These scopes are already exported with Theemo and are available to Sync. A potential integration to discover is stylelint-csstree-validator to be the counterpart to Figma scopes. If so, this can be the next integration into Sync. The idea is to get helpful support to the fingertips of engineers to give them confidence about proper token usage. But this is me fishing in the dark, so I’m more than happy to receive feedback on this.

Get Involved

Happy to receive feedback, help or contributions. Best place is to open up an issue over at Github or start a conversation in the Design Systems Slack, where you can find me as @gossi.

That’s it folks

– gossi

The Hidden Skill and Art of Naming Things

Thomas Gossmann — Fri, 27 Aug 2021 11:45:51 +0000

The two hardest problems in programming are cache invalidation, naming things and off-by-one. You learn a lot about algorithms while studying computer science to find clever solutions for the problem at hand - but for naming things?

For me undoubtedly this is the hardest problem. In fact, this issue exists in almost every discipline, whether you are pioneering a field and are the first one to name your discovered thing(s) or on a daily basis when communicating with your co-workers. As developers, we face this when communicating with our PM on our specs or with designers on sketches, mockups, or components.

While studying sports science it is common (and required) to start with a definition first and then use it along the way. In computer science, this of course happens for the technical terms but isn't considered for actually writing software to solve a problem in a certain domain. During my software engineer apprenticeship, I remember in some situations getting tips and discuss naming things on the spot for domain-related terminology. In university, for the handful of computer science courses I had, nothing - this was left out. I can't remember a linguistic course for this, that I think would come closest for teaching this.

Discussing naming things at work is often seen as unnecessary and considered a waste of time preventing you from getting the job done. There might be some truth to it, as it wouldn't necessarily matter for the current task you might be working on, but the pain becomes "visible" when the next person has to deal with your (improper) naming. When the naming doesn't click immediately or doesn't do what the name suggests, it gets hairy and the problem is passed on to the following person (that might even be your future you). Sometimes, it's wise to take a shortcut when the context is not known well enough to give it a proper name (note to developers: please put a comment in your code).

What Makes a Good Naming?

A good naming is already encoded in the term ubiquitous language and it's enough to describe it in two points:

A non-technical/industry language eliminating inaccuracies understandable by a multi-disciplined team
No ambiguity!

You could say there are some people who spent more time on naming things than others. I've realized there is some mastery level to naming things, roughly:

Level 0 - Just name it with the first thing that comes to mind
Level 1 - Your naming suggest what it does properly
Level 2 - With your naming a consumer can no longer use your thing the wrong way
Level 3 - Your name is a beauty and makes the consumer smile, it leads to a positive emotional benefit. This is where you begin to imagineer and reach for art (this is the bonus level - hardly reached).

Important Note: This is not really a mastery level, like you shall NOT say: "I'm at naming things level 2". It's only a short, quick, and non-exhaustive scale for use within this article!

Ambiguity is clearly the enemy of good and clear naming and it almost ever happens unintentionally. I consider this problem solved, when reaching level 2 with your naming, the gap from level 1 to 2 is the hardest to jump.

Naming things as a skill will unfortunately often go unnoticed, rarely praised and honored. Instead, it will most often be recognized when it's done (completely) wrong.

Test Yourself with an Example

Let's use this wireframe (below) as an example. Imagine you are about to develop this screen which contains three sets of information. The application in which this is going to be used, is an international app and the contents for the text are stored in locale files, your job is to give these variables proper names. Easy huh?

There is a straight forward way to name these three variables:

Headline
Tagline
Text

Boom! you would think, you found three variable names that get the job done quickly and can move on. But later your brain starts to think: is it really a headline? What about heading or header? What even is the difference between the three? As web-developers, we can at least relate header to an equivalent <header> element that is there to structure the document into semantic sections. That's the first relief here, disconnecting header from headline and heading. Identifying header as a structural thing allows for more connections to related concepts.

Where else is structuring used to section documents? For me, I have explored this in LaTeX and HTML, each of these technologies comes with mechanics to provide structure.

HTML: Mainly <article>, <section>, <header> and <footer> as well as <h1> to <h6>
LaTeX: Most of \\part, \\chapter, \\title, \\heading, \\subheading etc.

The name of these mechanics can also help us create a guided structure for naming our variables in an entire project. These names are good candidates to prefix and structure our locales. An important learning from that little exaggeration is that the name of the variables are sourced from the technical implementation (if applicable). This is good knowledge to assist your naming and maybe come up with some guidance on semantics. It's not yet enough to land on the final design for the naming but a little success and very good input.

Left is the unclarity between headline and heading. I am not a native English speaker and I don't know the nuances between them linguistically, which is a problem we see occur quite often (as English is the language of international teams as well as development often happens in English, too). A possible explanation, I came up for myself, is that it depends on the context/discipline we are in. From a marketing perspective, this would perhaps tend to be more of a headline, which is important to attract the interest of a possible reader. On the other side, in scientific writing, a heading is quite fine to summarize the following section or it might be a required field for the article format/magazine you are publishing for.

Discussion

Even with what seems to be a simple example there is a lot to learn and explore around, which gives more context to land on a proper naming. The example shown is one I haven't solved for myself yet, but it's good practice to explain the levels I described earlier:

Level 0 - Take the first naming
Level 1 - With a bit more investigation, come to a solution that feels has more of a proper naming
Level 2 - The naming resolves in a convention of what words to use for what purpose. At this point, you can't get the naming of your variables wrong anymore, and you also know how to implement them.
Level 3 - Perhaps not reachable at all for this situation (but that's ok, not every situation has a bonus level)

Level 0 and 1 do have a trap for the uncanny valley of naming things, they may seem right and obviously are not at the same time. What exploring of level 1 unlocks is a mystified view of what's slumbering in the topic and to see the possibility of reaching level 2.

What was the level you felt comfortable with? Did you drop at some point? Are you fine with just the first three variable names and called it a day? Have I just caught your interest and you are about to dig deeper and solve the mystery? Have you maybe already solved that one?

Naming Things in Product Development

For product development domain-driven design (DDD) is a good method to aim for a ubiquitous language. Reaching there requires a conversation between stakeholders from multiple disciplines to grasp all perspectives and land on a shared language to eliminate the mental burden in your team's daily conversations and to quickly reach the point of discussion.

From the perspective of the role of a developer, there are a couple of things you want to look for when having conversations with people from other disciplines, with yourself or peer developers. The best resource to consult are domain experts and they are likely to speak a completely different language than developers are used to. This is already the first point of friction as I've realized that developers tend to name things as they appear technically. It requires time and effort to shift your mind and allow other naming methods, such as domain-driven design. In the end, we want the code to speak the ubiquitous language and not let the domain adopt a technical language.

Important for naming are objects and actions. These names are taken from the OOUX naming convention for things (nouns) and activities (verbs). While OOUX is great and I admire it for what it offers, it is not a gold standard. If you've already settled on terms for your own team, that's great. Yet for the rest of the section, I'm going to use objects and actions as described here:

… objects (nouns) are entites/aggregates, locations (business verticals), areas (on the screen), elements/components, etc.
… actions (verbs) are activities a stakeholder can perform directly related to an object

Unveiling, identifying, and characterizing them is a not-so-easy job. Landing at a vocabulary that is used in the specs (product), in graphic editor (design), and finally in code (development) is the goal.

Here are a couple of ideas to improve your naming game:

Talk and listen to designers, you may want to ask the reasons or background for something. You can also testify your assumptions, such as “do we do that, so the customer can get xyz?”. During a refinement, train yourself to understand the cues that will draw your attention. Often, there are phrases like “we do a list here, so the customer receives an explanation for xyz”. The “receives an explanation for xyz” part answers the question of what something is meant for. By doing these things you not only get a better feeling to arrive at a proper naming. A very nice side-effect is the better understanding for design and especially the design creation process.
Talk to P*-title positions (PM/PO/P*), to understand the different ways in which the app stakeholders manipulate these objects, their relationship to others, and which actions they are supposed to perform. P*-title positions are a great resource to understand these nuances as they know, define and understand the product.This is done as part of the ORCA process and the part described here might also be done by designers (or in combination with P*-level).
Full-stack pairing between FE and BE developers, to consult on objects and their technical characteristics. FE developers mostly work with a subset of the whole objects as defined in the backend or even on the database level. It is a very welcoming discussion to see how objects are represented in BE, then filtered to be transferred over the wire, consumed and processed by FE developers. Often a pairing session between BE and FE developers is fruitful to better understand the technical picture and to learn what matters on the FE and BE respectively, the what and how about the (technical) relationship.
Imagine a real-life situation, sometimes it’s very helpful to think of an imaginary situation, where the work of your product is done by a human. Let's say a consulting situation, where the consultant and a customer are sitting in a room together. No digital devices, everything in paper in front of them on a table.This little simulation game is very helpful to draw actions from. Especially in a non-digital situation, there is no click, no tap, no swipe a customer or consultant can do. You can directly eliminate this way of thinking. Examples:
- The consultant would have a folder with recommendations, that can be opened.
- The customer takes a pencil and signs a contract.
- The customer will choose between offers lying in front of them.
Beyond Tellerrand, a thought experiment taking a couple of minutes, where you are exceeding the scope on purpose, pushing the boundary far further than it should be. This helps to explore the space around the actual context, will help fine-tune what is the boundary and more important, what your name WILL NOT BE. It's a way to see a sharper image of the scenery you are looking at.
Event storm, with your multi-disciplined team (invite domain experts!) about the subject from multiple perspectives to reach a clear picture, understand the other perspectives and be further able to share empathy with them and embody their perspective (to take a stance against yourself?).
Event storm with yourself, This is actually a misconception in itself but when event storming as a team is too much/not affordable, this might come in handy. When doing this on your own, you have to virtually embody other perspectives and try to understand their situation when looking at the how-to-call-it. Take it with a grain of salt.
Name storm (ok, I made up that one). When you understand the scenery and the only thing left is to land on a final name and you have too many candidates, throw a name storm session to decide on a final name.

With all these methods you should maintain a document about your domain terminology. Refine this document over time with even preciser descriptions and wording.

Writing specifications with this terminology will become utterly easy. Even the best specifications are not prevented from becoming outdated and the code remains a single source of truth. The holy grail a developer can reach for is to assure the code reads as the spec. Consider every location where the naming of code units does not conform to your terminology as tech debt.

Testify your existing code by reversing the approach from above. Deducting objects and actions from your code and how they are connected together, is it possible to reverse engineer the specification (for a non-developer)? Does the name of the function properly describe what it is doing or is it required to read the implementation details of it? Does the name properly express (for) what it is doing?

Grow your Repertoire

Becoming talented at naming things means you will have a big repertoire and be able to faster discard options, that you already know will not help you achieve what you are looking for. This is common amongst all talents in various disciplines. In order to stay or be talented, growing a repertoire is essential; so you can faster reach for level 2 on naming. That's why it is never a waste to pursue an idea even if it turns out to be a bad option. Following that path already has grown your repertoire over another person who took a shortcut. Don't forget to stay curious and keep up the hunger to really get to the bottom of a problem as this is the motivation for going on such a journey.

Apply Naming Things for the Biggest Impact

Naming things often requires research, failing attempts, try and error, and overall is a costly voyage. It's wise to funnel this process to control the impact.

First of all, identify people who have an interest in naming things properly and will do the required steps to land there. This is not something binary but on a scale, you can draw people towards one or the other end of the spectrum, much related is also the concept of macro and micro thinkers. I would say a person who is having a strong tendency to nail naming things is also a macro thinker. In terms of development, a macro thinker leans more on the side of architecture, developer experience, or tooling. On the other hand, micro thinkers learn more on the side of feature implementation, I have also heard the term makers for them. The team you work with clearly needs both and both need to be rewarded for what they are good at. At best, the macro thinkers supply the micro thinkers with tools and guides so they can get the work done quickly.

After identifying the right people, and knowing who belongs to the different group of thinkers, macro thinkers should be tasked with getting the naming right. There are technical things, such as namings in your tooling (design system is probably the best to name here) as well as namings in your product/domain. The former is more on a building blocks/foundation/tooling level whereas the latter is more on a conceptual level and when both are defined and their characteristics are worked out, development can happen at a fast pace as these are big piles of mental burdens keeping productivity low. Having them defined will make product development and engineering a joy to do.

I hope this article helps you understand the value and skill of naming things and hopefully you can form new strategies with your team to naming things.

Special thanks to Gabriela Ospina for editing this article and nerding out with me about naming things!

-gossi