Forem: David Sancho

Don't use Tailwind for your Design System

David Sancho — Sat, 06 Mar 2021 15:37:19 +0000

Don't use Tailwind for your Design System or your "UI Framework" or component system, call it whatever you prefer. What I meant is Tailwind isn't component-driven, which they claim to be, and you might struggle making a Design system with it.

Recently I read a lot of opinions about Tailwind (mxstbr's thoughts, jaredcwhite's opinion, Tailwind versus BEM) and nevertheless I agree with most of the points there I got a different perspective.

I will try to explain which are the drawbacks to make a Design system in Tailwind, focusing in the technical part of the components. Here I'm assuming that the reader is familiar with Design systems. Otherwise, can read more about in here or here.

A little bit about my experience

Currently I'm working at Draftbit, and our frontend is build on top of ReasonReact uses Tailwind, it's about ~500 components and the main page, called the builder looks like this:

We have a design system on top of Tailwind (we might Open Source it at some point) and I contributed in a few Design Systems in my career, I even write my own.

I'm obsessed with the conjunction of design with functional programming and how those enable writing modular UIs.

But now, let's talk about Tailwind.

First, the good parts

The reason why I think Tailwind is amazing have nothing to do with their utility classes. Those utility classes have been around the Frontend community for a long time - tachyons has been created around 2016. Even some people found them pleasant to use I personally prefer to write directly CSS.

The reasons why I think Tailwind shines are:

Theme with strong defaults, beautiful and scalar. The config generates all the values needed to produce a scaled system based on all those tokens. For example, spacing. The defaultConfig will generate spacing based on a scale from 0 to 96 that goes from 0px until 24rems. defaultConfig
Extendability, being able to extend those values in the config brings the possibility to represent any design and being propagated to the right CSS properties. Ex, spacing would generate the values for margin, padding, width, min-height, min-height, etc.
It's just CSS. It's not an abstraction, or coupled to any framework. ****Anyone can use it with minimal setup: all IDE would have support for it, all frontend framework can use it, there's ton of build tools to optimise their performance and long etcetera.

How is used in React

I use the example of React since I'm familiar with it, but I believe everything in this post applies to other frontend libs.

React uses JSX via Babel or any transpiler to transform JSX to function calls, and some props/attributes renames on the process, such as classNames to class(since it's a reserved keyword in JavaScript).

className is used to apply CSS classes to React Elements, which at the end will be DOM Elements.

This is the defacto method to use Tailwind with React, you will often will see:

<div className="flex md:block w-32 h-full" />

What's wrong with className

Hard to maintain

It's error prone to remove one of the classNames from the list, is a similar situation when you want to remove an unused CSS class in an append only stylesheet.

Aside from hard to remove, it's hard to change. Adding those classes might seem simple and fast while creating those components, but it will slow you down when modify or refactor them.

It is optimised for writing, but not for reading

When reading JSX, I feel confortable to imagine a 1-to-1 match with the UI. I can easily navigate thought the component tree and map with the reality.

Even that this snapshot of code-UI is doable in Tailwind, at some level of those components you will find a layer with a bunch of classNames that you need to parse in your head in order to imagine the UI.

There's a famous quote floating around...
"Best code isn't optimised to be written, instead, it's optimised to be read".

Fail at dynamic styling

Dynamic Styling: Style your components with a global theme or based on runtime states.

Having a component API coherent, versatile and scoped is relatively hard by itself. Doing so, requires a good understanding of the problems that the component is trying to solve. Using Tailwind it's very tempting to use the same utility classes on that API.

There's a definite disconnect between a CSS API and a component API. For a design system, I care more about getting the component one right - @sarah_federman

For example, having a <Link /> component with color="text-mono-100". At the beginning it would make sense since text-mono-100 represents the desired color. Maybe later, appears a need to style the link with a different color on hover. You would add another prop called hoverColor="text-mono-200" and call it a day.

The fact that color is represented in another format it's a nightmare, often UIs derive styles from props. In the example above, you could have a color be their hexadecimal representation color="#b54c4c" and derive the hoverColor with a library.

The Tailwind language is nice to avoid typing CSS but isn't made for component APIs that use any sort of dynamic theme, making impossible (or very hard) to accomplish generative UI.

As an example https://hihayk.github.io/shaper

Breaks style encapsulation

I consider harmful allowing className as a prop on the component's API. This is often made to have flexibility from the outside to enable any sort of customisation to your component.

const Button = ({ ...props, className }) => (
  <button className={"flex text-mono-100 p-4 " + className} />
)

It's a trap, designing a closed API for those customisations would battle-test your component and force you to decide on an API that have some boundaries, which is the initial goal of making a component.

Tailwind doesn't have any opinion on this, but it's very tempting to allow any sort of className from the outside in your classNames, given that you need customisation from the outside.

Stack: Example of variants

There're a lot of implementations of Stack. That's a screenshot of mine.

Stack places a list of elements on the Y axis, one on top of the other. Adds consistent spacing between and moves them horizontally or vertically. It's an abstraction on top of flexbox, but limited. Those constraints are defined mostly by the designer, having a Component that enforces the number of variants it's generally a good think.

Composing at the wrong layer

The key feature of React is composition of components. Composition here means the possibility to plug those components like a lego which enables create more complex components based on more simple ones.

Composition is a concept that more or less you might feel familiar with it, which applies to many areas of Software development.

I see those "Components" are a set of rules that React forces on top of just functions. The rules are simple and allow the React library to perform many benefits that we take for granted. Those rules, are better explained by Dan Abramov in one of his posts, Writing resilent components.

As I mentioned before, appending strings to style your component feels like a step backwards. Composing components that are made to solve one thing, It's the pattern that I trend to prefer.

The composition of components allows React components, to benefit from

Declarative representation of the UI. Create complex pieces of UI based on smaller ones.
Decoupled: Isolate UI problems into black boxes that doesn't know anything about it's context.
Variants Implement variants of the same component, without he need to re-implement different versions.

Example of component composition over Tailwind

Re-implementation of Charkra's UI Box component into a pseudo design-system and Tailwind.

Here you can see the different approaches to the same UI

<Box padding={5} width="320px" border="sm">
  <Stack gap={2}>
    <Image borderRadius="md" src="https://bit.ly/2k1H1t6" />
    <Row gap={2}>
      <Badge color="#702459">Plus</Badge>
      <Spacer left={2}>
        <Text
          size="sm"
          weight="bold"
          color="#702459"
        >
          VERIFIED &bull; CAPE TOWN
        </Text>
      </Spacer>
    </Row>
    <Text size="xl" weight="semibold">
      Modern, Chic Penthouse with Mountain, City & Sea Views
    </Text>
    <Text>$119/night</Text>
    <Row gap={1}>
      <Icon src={MdStar} color="#ED8936" />
      <Text size="sm">
        <Text size="sm" weight="bold">4.84</Text> (190)
      </Text>
    </Row>
  </Stack>
</Box>

<div className="p-5 w-32 rounded">
  <div className="flex">
    <img className="rounded w-full" src="https://bit.ly/2k1H1t6" />
    <div className="flex flex-row mt-2">
      <div className="rounded py-2 px-4 bg-mono-400">
        <div className="text-mono-100">Plus</div>
      </div>
      <div className="text-sm font-bold text-pale-100">
        VERIFIED &bull; CAPE TOWN
      </div>
    </div>
    <span className="text-xl font-semibold">
      Modern, Chic Penthouse with Mountain, City & Sea Views
    </span>
    <span className="text-xl font-semibold">$119/night</span>
    <div className="flex flex-row items-center">
      <Icon src={MdStar} color="#ED8936" />
      <span className="text-sm">
        <span className="font-bold">4.84</span>
        (190)
      </span>
    </div>
  </div>
</div>

A mention to `@apply`

@apply is the directive that Tailwind recommend to extract repeated utility patterns. I don't want to get into muchs details about it, but it does fail at the same problems as traditional CSS. Using apply it feel like just writting plain CSS, which in some of the cases it's amazing, but for a larger app it's a drawback.

When I would use Tailwind again then?

Document-like websites, styling content that is structured as a big chunk. Using Tailwind Typography it does come with good defaults for raw content like a blog or a newsletter.
Prototyping, creating a UI that visually doesn't need to be high quality or needs a unique style.

What should I use instead of Tailwind for my design system?

Not all the teams can have the possibility to invest time on building tooling and systems to give super-powers to the rest of the engineering team. In fact, create a Design system it's a full-time job.

But, there's a bunch of people who spend a lot of time thinking about those problems and tried to create a few abstractions that you could benefit from.

If you still like what Tailwind offers, I recommend a similar approach that we do at Draftbit. Create a tiny layer on top of it: Treat all the Tailwind tokens as code and maintain Tailwind scoped inside those components. Abstract those utility components that you found repeated in your code into a more strict version, and minimise Tailwind for your app.

How do I try to do it

Mentioned before that I made my own Design system, which is a set of components that only cares about layout disposition, doesn't contain any opinions about cosmetics and allows to compose those elegantly. It's called taco.

It's currently still a work in progress, since there's a lot of patterns that aren't solved yet. But I have been using them for all my projects.
Even that is public, isn't for consumption. I didn't write all of this for a plot-twist to sell my library, but you can use it as an example for inspiration.

Storybook and repository https://github.com/davesnx/taco.

I hope this post doesn't get in the wrong form, any tool is perfect and using those to solve problems is part of who we are.

query-json: A story of cross-compilation with Reason

David Sancho — Mon, 12 Oct 2020 17:49:06 +0000

What's query-json

query-json is a faster and simpler re-implementation of jq's language in Reason.

It's a CLI to run small programs against JSON, the same idea as sed but for JSON files. As a web engineer is an essential tool while developing APIs.

Started with the goal to create something useful and learn during the process. Was very interested in learning about how to write parsers and compilers using the OCaml stack: menhir and sedlex, compile it to any architecture and try to compile it to JavaScript.

This post explains the project, how it was made and which decisions were followed and some reflections.

Why learning parsers/compilers

I had a little idea about the theory, but very vague and useless and was the righ time to learn more since I created styled-ppx which is a
ppx (Pre*Processor Ex*tension) that allows CSS-in-Reason/OCaml. Needs to parse the CSS and have a backend that compiles to bs-emotion.

I asked for some help to @EduardoRFS about writing a CSS Parser that supports the entire CSS3 specification which I will want to understand, improve and maintain over time.

How it works

query-json ".store.books | filter(.price > 10)" stores.json

This reads stores.json and access to "store" field, access to "books" field (since it's an array) it will run a filter on each item and filter each item by it's "price" that's larger than 10 and finally, print the resultant list.

[
  {
    "title": "War and Peace",
    "author": "Leo Tolstoy",
    "price": 12.0
  },
  {
    "title": "Lolita",
    "author": "Vladimir Nabokov",
    "price": 13.0
  }
]

The first argument is called query and it's a jq expression. The second one is called json or payload, and it's a valid JSON file.

The semantics of jq consist of a set of piped operations, where each output is connected to an input where the first input it's the JSON itself. Some pseudo-code to illustate:

{ /* json */ } | filter | transform | count

In order to transform the query to a set of operations that run against a JSON, we will divide the problem into 3 steps: parse, compile and run.

Parsing

Responsible for transforming a string into an AST(Abstract Syntax Tree) and provide a good error message when the input is malformed.

One of the beauties of jq is that all the expressions are piped by default, so .store | .books is equivalent to .store.books. I designed the AST to represent the pipe structure in its nature. If you want to know more about jq's language, check their wiki.

Let's dive into an example. When the parser recieves .store.books will return:

Pipe(
    Key("store"),
    Key("books")
)

All the operations are transformed into these constructors from above (Pipe, Key). Those constructors are called Variants.

Variants models values that may assume one of many known variations. This feature is similar to enums in other languages, but each variant may optionally contain data that is carried inside. Variants belong to a large group of types called ADTs.

The entire query-json program representation it's one big recursive Variant.

Following with a more complex example, let's parse .store.books | filter(.price > 10):

Pipe(
    Pipe(
        Key("store"),
        Key("books")
    ),
    Filter(
        Pipe(
            Key("price"),
            Literal(Number(10.))
        )
    )
)

You can see more examples in the parsing tests

Compiling

The compilation step recieves the AST expression and transforms it to code. It's a big recursive pattern match, which is another great feature of Reason and looks something like this:

let rec compile = (expression, json) => {
  switch (expression) {
  | Empty => empty
  | Keys => keys(json)
  | Key(key, opt) => member(key, opt, json)
  | Index(idx) => index(idx, json)
  | Head => head(json)
  | Tail => tail(json)
  | Length => length(json)
  /* [...] */
}

On the left side are defined all the possible Variants and on the right side the operations. Those operations transforms the JSON. Here is where map, filter, reduce, index, etc... are implemented.

Running

The easier part, the compile step give us back a curried function that expects a json as the only argument, we just apply the function to this JSON and print the result.

This example only describes the happy path, in reality, the parsing and compilation steps return a Result type which allows handling errors more composable.

Distribution

Now we already covered how it works internally and a little overview of the architecture. Now let's dive on how developers can use it in their machines.

But first, let's recap on what's what.

OCaml is a programing language from the family of ML ("Meta Language") and is best known for their static type system and type-inference.
OCaml allows to compile to binary code which are often compared to C/C++ performance.

BuckleScript is a compiler (a fork of the OCaml compiler) that outputs JavaScript code, instead of binary. BuckleScript supports OCaml syntax and Reason syntax.

Reason is a language that can be compiled with the OCaml compiler or BuckleScript.

How to cross-compilation to binary

All of the build process and their tests runs on our CI in Github Actions, which allows running Mac, Windows and Linux images. Each build compiles with the OCaml compiler to each architecture.

Once the build and test succeeds it pushes the binary into Github Releases and npm registry.

How to compile to the Web

The compilation to JavaScript is the sweet section of this blog post since we are using OCaml (under the hood while writing Reason), and it allows us to compile directly to JavaScript using js_of_ocaml.

js_of_ocaml is a compiler that can be plugged to the OCaml's one and It makes it possible to run pure OCaml programs into JavaScript.
As you can see, query-json uses menhir, sedlex and yojson

In order to use it in esy, the package manager, I only needed to add:

esy add js_of_ocaml
esy add js_of_ocaml-compiler

and modify it's dune file, the build system:

(executable
 (name Js)
 (modes js)
 (libraries console.lib source yojson js_of_ocaml)
)

After running the build, it generates a bundle.js!

Made query-json's playground

After having a JavaScript artefact I was able to run it as a playground in the browser. To teach people how to use it without the binary install or to test new versions on each pull request, well, the possibilities of the web are endless!

I build a website using Reason and BuckleScript which uses query-json JavaScript's artefact to run it, you can try it yourself here:

https://query-json.netlify.app

The query-json computation runs synchronous since it's able to run on each key-stroke. Comparing this playground with jqplay.org that needs to hit a backend and respond with the result.

Having a playground as a serverless frontend app It's a massive improvement over backend-dependant ones. Actually, most of the REPL's from Reason, OCaml, Flow, ReScript uses js_of_ocaml.

Benefits

This allows any OCaml backend being able to run in a browser without much hassle, sharing code between backend and frontend has been a dream for a lot of Engineering teams.

But not only share logic matters, here's a list of other upsides:

Portability, moving code from server to client or viceversa, sharing marshal/unmarshal code, easier contract testing.
Familiarity: Writing the same patterns would benefit new comers that need to learn less platform-specific rules.
Usage of OCaml's ecosystem: Access to many libraries and ppxs and latest ocaml's features.
Features that weren't possible: Some apps might benefit from Server-side rendering, others might benefit from moving stuff to offline, and many app-specific designs that are unblocked by this.

Challenges

This solution has downsides as well, js_of_ocaml isn't the tool that solves all of your problems, actually, there's no such tool.

Bundlesize

It's quite big compared to regular JavaScript applications.

The entire playground is about 660kb. Includes the Monaco Editor (~356kb) and the rest is query-json and js_of_ocaml runtime (300kb).

js_of_ocaml wasn't created with the same mentality as most Frontend developers solve their problems today and was born 10 years ago to run some OCaml into a browser.

Documentation

One of my biggest complains about the OCaml community is the lack of quality documentation.

Coming from the JavaScript community (which have more than 9 million devs) there's plenty of tutorials, examples, manuals, many StackOverflow resolved questions and this culture of the copy-paste driven development.

That gives all sort of problems, but lowers the barrier to the language and the usage of many dependencies for new comers or not so passionate FP developers.

It's a non-sense compare OCaml and JavaScript, but one of the biggest missing pieces is good documentation at all levels.

Bridge between BuckleScript/Reason and js_of_ocaml

Js_of_ocaml lacks some of the basics to enable compatibility with JavaScript codebases, modern build systems such as webpack and many bindings to other libraries. So to build the online playground, I used BuckleScript for the UI and js_of_ocaml for the query-json browser build, and this required having to make them communicate to each other.

This isn't particular to js_of_ocaml, is more related to the mix of js_of_ocaml and BuckleScript. In order to run the js_of_ocaml artefact into the BuckleScript/Reason codebase, I needed to write bindings for it.

[@bs.module "../../_build/default/js/Js.bc.js"]
external queryJson: (string, string) => result(string, string) = "run";

Using the Result from OCaml in the query-json's JavaScript entry-point and the Result from BuckleScript in the Reason code I needed to write an unsafe bridge which transforms OCaml result to the internal representation of BuckleScript variant.

There're probably better ways of achieving it since I made the implementation very unsafe davesnx/query-json/js/Js.re.

It's a tradeoff, as always...

You can't really compare BuckleScript/rescript with js_of_ocaml, since both tools try to solve the same problem in a very different fashion.

If you are writing an OCaml backend and your team is familiar with it. Your project would benefit from sharing code, don't require a hard need on a lower bundlesize and want to carry all OCaml dependencies, ppx and patterns, js_of_ocaml it's the best option.

Since most modern build tools such as Webpack or Rollup allows to lazy import chunks of your app, you might find no-issue with the big bundle, since most shared logic doesn't require to be present during load-time.

You won't have the facility to write frontend code with React, but I'm sure it will change soon since there's a current implementation of React in jsso jsoo-react.

For now, writing a website in ReasonReact and BuckleScript it's the most robust experience. You can find a lot of bindings to JavaScript libraries, there's a lot of usage in production, plenty of examples.

I truly believe that ReScript it's such a great project to target JavaScript developers that found TypeScript slow and liar or Flow abandoned. It improves the status quo for many issues regarding the Reason Community and keeps delivering in a fast pace the best tooling.

It makes me very sad that ReScript will diverge at some point from the OCaml ecosystem and won't spend time to build a cross-platform language with the advantatges of cross-compilation and future features from OCaml.

Future

The future of query-json is to provide a better experience in running operations on top of JSON.

Providing better error messages and better performance has been the goal.

Currently jq has an issue, it's very powerful but confusing. The amount of questions of StackOverflow proves that there's a lot of problems without a solution on the language/compiler.

The other mission of query-json is to push performance forward, now we are implementing most of the missing functionality since I first release it and next is to explore performance optimizations, such as:

Replacing menhir with a written parser/lexer
Using OCaml multicore
Partial JSON parsing, only parse the needed parts of a json based on the user's query

Final

Hope you liked the project and the story, let me know if you are interested in those topics I'm always happy to chat and help. I answer to all the DMs on Twitter.

See you next time 👋

Thanks everyone how reviewed this blog post, Javi, Enric and Gerard