Radically Straightforward · CSS

Installation

$ npm install --save-dev @radically-straightforward/css

Note: We recommend installing @radically-straightforward/css as a development dependency because @radically-straightforward/build can build the css`___` tagged templates away on the server and bundle the CSS framework on the browser.

Note: We recommend the following tools:

Prettier: A code formatter that supports CSS in tagged templates.

Prettier - Code formatter: A Visual Studio Code extension to use Prettier more ergonomically.

Usage

import css, { CSS } from "@radically-straightforward/css";

`CSS`

export type CSS = string;

A type alias to make your type annotations more specific.

`css()`

export default function css(
  templateStrings: TemplateStringsArray,
  ...substitutions: (CSS | CSS[])[]
): CSS;

A tagged template for CSS:

css`
  body {
    background-color: ${"red"};
  }
`;

Note: CSS is represented as strings and this tagged template works by performing string interpolation. This is conceptually simple and fast. To extract and process the CSS refer to @radically-straightforward/build.

Interpolated arrays are joined:

css`
  ${["red", "green", "blue"].map(
    (color) => css`
      .text--${color} {
        color: ${color};
      }
    `,
  )}
`;

CSS Framework

Beyond the tagged template to define CSS in JavaScript, @radically-straightforward/css also includes a CSS framework featuring a CSS reset, a design system, and helper classes.

To use this framework:

Use HTML 5 and include a <meta name="viewport" /> meta tag:
```
<!doctype html>
<html>
  <head>
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1, maximum-scale=1"
    />
    
  </head>
  <body>
    
  </body>
</html>
```
Note: Unfortunately there isn’t a way to set properties about the viewport from CSS, which is why the <meta name="viewport" /> meta tag is necessary.

Note: maximum-scale=1 prevents iOS from zooming into the viewport when a form field is active. People on the internet have written that this could be an accessibility issue because it would prevent users from zooming in with a pinch gesture, but our tests reveal that this is not the case.
Include @radically-straightforward/css/static/index.css at the top of your CSS:
```
@import "@radically-straightforward/css/static/index.css";
/* ... */
```
Note: @radically-straightforward/javascript already includes this file. If you’re importing @radically-straightforward/javascript/static/index.css you don’t need to import @radically-straightforward/css/static/index.css as well.
Learn about the framework, particularly the design system, by reading the the source.
(Optional but recommended) Transpile for broader browser support and bundle your CSS. This framework uses modern CSS features, for example, CSS Nesting and properties that need to be prefixed. We recommend @radically-straightforward/build.

Related Work

Tailwind

@radically-straightforward/css follows some of the ideas popularized by Tailwind:

Colocate HTML and its corresponding CSS.
Include few opinions on style, so that every design looks unique.
Include a design system with a selection of spaces, colors, fonts, and so forth.

Note: To learn more about how to use a design system, we recommend Refactoring UI and Practical Typography.

But @radically-straightforward/css is different from Tailwind in how it solves some issues:

Designing with constraints. The design systems in Tailwind and @radically-straightforward/css are largely identical, because we ported Tailwind’s design system. But Tailwind presents its design system as classes, and @radically-straightforward/css presents its design system as CSS variables.

The class names in Tailwind are an extra layer of indirection that you need to learn about: at some point you will have to translate the CSS you find in MDN, blog posts, and so forth, into Tailwind class names. Copying-and-pasting doesn’t work anymore, and using third-party libraries may be awkward.

In the best of cases the layer of indirection is small, for example, the class .float-right corresponds to the CSS float: right;. In these cases the class names simply add noise over the CSS that you would write normally.

In the worst of cases the layer of indirection is more confusing, for example, the class .m-2 corresponds to the CSS margin: 0.5rem;. In Tailwind’s defense, abbreviations like these are used only on the most common properties, and they’re for the most part tasteful. But they’re still one extra layer of indirection, and they can be disorienting, especially to beginners, and especially when they pile up.

In addition, customizing the design system in Tailwind involves learning about a whole customization system.

The CSS variables in @radically-straightforward/css, on the other hand, integrate seamlessly with the CSS you already know and write, including CSS imported from third-party libraries. Copying-and-pasting snippets from the internet just works and goes well with the rest of the style in the codebase. And customizing is a matter of setting new CSS variables.
Responsive design and Hover, focus, and other states. Media queries, pseudo-elements, children, and so forth, are supported in @radically-straightforward/css paired with @radically-straightforward/build, all while still colocating HTML and its corresponding CSS—you can think of it as inline styles infused with the power of nesting.

Note: Another small quality-of-life gain of @radically-straightforward/build over Tailwind: Prettier formats CSS in tagged templates over multiple lines, making the code more readable than the long lines of classes in Tailwind.

Note: Tailwind’s documentation is fantastic and worth the read. It’s a great supplement to MDN, full of examples, and concentrates the most useful CSS properties all in one place. And it includes the CSS version of everything, so you can skip over the Tailwind classes and still benefit from the documentation.

It’s a design system similar in spirit to the one included in @radically-straightforward/css, in the sense that it’s also presented a CSS variables. Open Props takes the approach of normalizing CSS across browsers, instead of resetting browser styles; it comes with more transitions and animations, and fewer sizes. It also comes with an approach of fixed breakpoints, while in @radically-straightforward/css’s style we prefer to use breakpoints case-by-case.