DEV Community: Zander Martineau

Styling React 2023 edition

Zander Martineau — Thu, 02 Nov 2023 16:50:29 +0000

My approach for using PostCSS, Tailwind, cva and a few others tools to style react apps and components

Over the past few years, I've worked with React apps utilising various CSS-in-JS libraries, starting with styled-components, transitioning through emotion, Theme UI, and finally Stitches. I've also integrated MUI, Mantine, and Chakra in numerous client projects.

While I didn't always opt for CSS-in-JS, I frequently chose it for its ubiquity — everyone was using it, and I was aboard the hype train 🚂. I knew there was an performance overhead when compared to vanilla CSS however, I was oblivious to how detrimental its impact on performance was until I read Sam Magura's article, "Why We're Breaking Up with CSS-in-JS". This piece prompted me to search for a new standard in styling React apps. I believe I've found it, not in a single tool, but in a harmonious blend of various utilities.

TLDR; these are the tools I use to style React apps:

PostCSS (or Sass)
Tailwind
CVA (class-variance-authority)
Utopia
Open Props
clsx & tailwind-merge

Tools

PostCSS

I use PostCSS to extend CSS’s features and to add a few things that make writing styles a little more convenient, but it could easily be swapped for another preprocessor like Sass or vanilla CSS. It’s up to you. You can view my PostCSS config here.

Typically styles are colocated with the components or pages that they concern, but I also include a base line of styles that are used across the app. I use a global.css file to import these files, which is then imported into the main app entrypoint.

Tailwind

I find Tailwind useful when used sparingly, it is perfect for allowing me to append certain styles to an element on an ad-hoc basis. For example, I like to use it to add classes to elements to add some margin or to make a flex container when I don’t want to make a new bespoke class declaration. I got the idea from Andy Bell’s "Be the browser’s mentor, not its micromanager" talk from All Day Hey 2022.

You can view my Tailwind config here, it is a little different to the default config, I have extended the spacing and font-size scales, added a few extra colours and some other bits and bobs.

CVA

CVA or class-variance-authority is a excellent package that makes it easy to create style variants for components. I do not use CVA for all components, only the ones that need different variants, e.g. buttons and other UI primitives.

Utopia

Utopia is not a product, a plugin, or a framework. It’s a memorable/pretentious word we use to refer to a way of thinking about fluid responsive design.

Using the various tools on Utopia’s website, you can copy the CSS custom properties that are output and add them to your styles. These properties are responsive, which means the values scale based on the viewport size. Follow this link for an example font-size scale.

Open Props

Open Props adds to the set by providing extra custom properties for things like easing functions or animations.

clsx and tailwind-merge

clsx is a tiny utility for constructing className strings conditionally, I use it in conjunction with tailwind-merge which merges Tailwind CSS classes without style conflicts.

I use a cn() function that was ripped from shadcn/ui, it is a simple utility that conditionally joins classnames together.

import { type ClassValue, clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Examples

1. Basic component

For a simple component, I import a CSS file (TheComponent.css) into the component file (TheComponent.jsx).

// TheComponent.css
.component-wrapper {
  background-color: var(--color-primary);
}

// TheComponent.jsx
import './TheComponent.css';

export const TheComponent = ({ children }) => {
  return <div className="component-wrapper">{children}</div>;
};

2. Component without variants

In this slightly more complex example the cn function is used to merge a specific class with the classes passed to the component.

import { ReactNode, ComponentPropsWithoutRef } from 'react';
import { cn } from '@/src/utils/classnames';
import './TheComponent.css';

interface TheComponentProps extends ComponentPropsWithoutRef<'div'> {
  children?: ReactNode;
  isActive?: boolean;
}

export const TheComponent = ({
  className,
  children,
  isActive,
  ...rest
}: TheComponentProps) => {
  const thecomponentClass = cn(
    className,
    { active: isActive },
    'component-wrapper',
  );

  return (
    <div className={thecomponentClass} {...rest}>
      {children}
    </div>
  );
};

3. Component with variants

As mentioned above, when using variants, I use CVA. The way that the Props TypeScript types are setup ensure that the cva variants are included in the component's props.

import { cn } from '@/src/utils/classnames';
import { VariantProps, cva } from 'class-variance-authority';
import { ComponentPropsWithoutRef, ReactNode } from 'react';

import './Button.css';

export const buttonVariants = cva('button-base', {
  variants: {
    variant: {
      primary: 'button-primary',
      secondary: 'button-secondary',
    },
    size: {
      s: 'button-s',
      m: 'button-m',
      l: 'button-l',
    },
  },
  defaultVariants: {
    variant: 'primary',
    size: 'm',
  },
});

interface Props
  extends ComponentPropsWithoutRef<'button'>,
    VariantProps<typeof buttonVariants> {
  children?: ReactNode;
}

export const Button = ({
  className,
  variant,
  size,
  children,
  ...rest
}: Props) => {
  return (
    <button
      className={cn(buttonVariants({ variant, size, className }))}
      {...rest}
    >
      {children}
    </button>
  );
};

and used like this:

<Button variant="primary" size="l">
  Hello
</Button>

or you can use the buttonVariants helper to create a link that looks like a button:

<a className={buttonVariants({ variant: 'secondary' })}>Click here</a>

shadcn/ui served as an excellent source of inspiration for this approach to styling React apps. It leans more heavily on Tailwind, so if that's your thing, I recommend checking it out.

The great thing about this approach is that it is flexible, you can use as much or as little of it as you like and without much modification, it can be used in an Astro, Svelte or Vue app. I've found that it works well for me, and I hope it works well for you too.

You can see methods from this post used in practice for , my personal bookmarking app side-project.

This was originally posted on my blog at https://zander.wtf/blog/styling-react

Avoid being tracked on the web

Zander Martineau — Sun, 08 Sep 2019 06:27:55 +0000

A few tips to keep you a bit more invisible

So, you don't want to be tracked online 🙅 by advertisers & analytics scripts etc? What do you do? You need to block them. There are many different ways to achieve this, but I use a few different tools and services to block all these guys.

➡️ Visit github.com/StevenBlack/hosts#list-of-all-hosts-file-variants and find the "hosts" recipe that you'd like. The "Unified hosts = (adware + malware)" should be sufficient, but you can also find ones that block porn and/or gambling content.

If you're on a Mac, download Gas Mask (free) from clockwise.ee. If you're on Windows, you can try Unified Hosts AutoUpdate from github.com/ScriptTiger/Unified-Hosts-AutoUpdate. Both will allow you to select one of the hosts lists (mentioned above) and have it auto-update at regular intervals.

⚠️ Gas Mask can reference remotely hosted files, but only if they're not https, so use the "Non Github mirror" links from github.com/StevenBlack/hosts#list-of-all-hosts-file-variants, like this one: sbc.io/hosts/hosts.

With this setup, visit an ad-riddled site like theverge.com or mashable.com and see that there are no ads anymore.

By the way, these hosts files don't just block ads, but also trackers, malware, fake news and more that are otherwise hidden to you and other users.

You may find that it isn't working, so have a look at these instructions to find out if you need to reset a few things on your computer: github.com/StevenBlack/hosts#reloading-hosts-file.

If you want to go one step further, you can setup a Pi-hole. Its a network-level blocking application that runs on a Raspberry Pi or similar device. Any device (smartphone or laptop) on your network is protected without installing apps etc like I outlined in the thread above.

Find out about Pi-hole at pi-hole.net

And if you don't want to setup a Pi-hole, give nextdns.io a try. I've been using it for a couple of months now and love it.

NextDNS can be used on both your smartphone and your PC and has many different configurations. Some of the rules are based on the StevenBlack rules (from above), but there is so much more to it. It is my recommended solution.

If you want to level-up even further, I suggest using a VPN like NordVPN. NordVPN is very cheap, does not keep logs of your activity (this is crucial), and is extremely privacy focused.

If you're looking to keep more of your online self private, I suggest you visit privacytools.io to find many other tools.

👨‍💻 The source for this post was originally one of my Twitter threads: twitter.com/MrMartineau/status/1128578179730423808

This post was originally published on my blog

My command line reference

Zander Martineau — Sun, 08 Sep 2019 06:25:13 +0000

A mixture of my favourite CLI tools and things that I usually forget

Disclaimer: If you don't use fish-shell, some of the packages might not work. There will be alternatives for each of them for your own shell.

Keyboard shortcuts

ctrl-r

Search previously used commands

ctrl-t

Invoke FZF fuzzy file finder (see below)

ctrl-l

Clear the terminal screen

ctrl-k

Clears the terminal screen but no-scroll back. Basically wipes the

ctrl-w

Cut one word backwards using white space as delimiter

esc-t

Swap the last two words before the cursor

Commands

cal

Show a calendar

❯ cal  
   September 2019  
Su Mo Tu We Th Fr Sa  
 1  2  3  4  5  6 |7|  
 8  9 10 11 12 13 14  
15 16 17 18 19 20 21  
22 23 24 25 26 27 28  
29 30

date

Show the date

❯ date  
Sat  7 Sep 2019 09:22:28 BST

tree

Show directory contents as a tree

❯ tree -L 1  
.  
├── README.md  
├── components  
├── designsystem  
├── layouts  
├── next.config.js  
├── node_modules  
├── now.json  
├── package.json  
├── pages  
├── redirects.js  
├── scripts  
├── server.js  
├── static  
├── utils  
└── yarn.lock

List global packages

# with yarn  
❯ yarn global list  
yarn global v1.17.3  
info "canvas-sketch-cli@1.4.2" has binaries:  
   - canvas-sketch  
   - canvas-sketch-cli  
   - canvas-sketch-gif  
   - canvas-sketch-mp4  
info "create-react-app@2.1.2" has binaries:  
   - create-react-app  
info "docusaurus-init@1.0.1" has binaries:  
   - docusaurus-init  
info "emma-cli@2.0.1" has binaries:  
   - emma  
   - ema  
info "emoj@2.0.0" has binaries:  
   - emoj  
info "fx@10.0.0" has binaries:  
   - fx  
info "ibrew@1.1.1" has binaries:  
   - ibrew  
info "jscodeshift@0.6.2" has binaries:  
   - jscodeshift  
info "lighthouse@5.0.0" has binaries:  
   - lighthouse  
   - chrome-debug  
info "majestic@1.2.24" has binaries:  
   - majestic  
info "np@4.0.2" has binaries:  
   - np  
info "npm@6.0.0" has binaries:  
   - npm  
   - npx  
info "parcel-bundler@1.9.2" has binaries:  
   - parcel  
info "plop@2.1.0" has binaries:  
   - plop  
info "prettier@0.22.0" has binaries:  
   - prettier  
info "release-it@12.3.5" has binaries:  
   - release-it  
info "rimraf@2.6.3" has binaries:  
   - rimraf  
info "semver@5.6.0" has binaries:  
   - semver  
info "serve@10.0.2" has binaries:  
   - serve  
info "strapi@3.0.0-alpha.13.0.1" has binaries:  
   - strapi  
info "terser@3.8.2" has binaries:  
   - terser  
info "types-installer@1.4.0" has binaries:  
   - types-installer  
info "yalc@1.0.0-pre.27" has binaries:  
   - yalc  
✨  Done in 5.61s.  

# with npm  
❯ npm -g ls --depth=0

Custom packages

Autojump

https://github.com/wting/autojump

autojump is a faster way to navigate your filesystem. It works by maintaining a database of the directories you use the most from the command line.

❯ j code

exa

https://github.com/ogham/exa

A modern version of ls

❯ exa -l  
❯ exa -T -L 2 # like tree

FZF

https://github.com/junegunn/fzf

Fuzzy find files. Use ctrl+t to access it

serve

https://github.com/zeit/serve

Static file serving and directory listing

emma

https://github.com/maticzav/emma-cli

Search for npm packages. Run emma to initialise the search, then enter your search criteria

ibrew

https://github.com/mischah/ibrew

Interactive search CLI for Homebrew

Run ibrew to initialise the search, then enter your search criteria

yalc

https://github.com/whitecolor/yalc

Work with yarn/npm packages locally like a boss.

hub

https://hub.github.com/

# clone one of your GitHub repos  
❯ hub clone dotfiles  
# Same as → git clone git://github.com/YOUR_USER/dotfiles.git  

# clone another project's repo  
❯ hub clone github/hub  
# → git clone git://github.com/github/hub.git  

# open the current project's issues page  
❯ hub browse -- issues  
# → open https://github.com/github/hub/issues  

# open another project's wiki  
❯ hub browse mojombo/jekyll wiki

List the current repo's PRs

# this is an alias  
alias prs 'hub pr list -L 20 -b develop --format="%t%n - Branch: [%H]%n - %U%n - %l%n%n"'  
# e.g. ❯ prs

Create a branch and switch to it

# FYI This is a fish shell function  
function branch  
   git branch {$argv} && git checkout {$argv}  
end  
# e.g. ❯ branch feature/WL-88-hello

standup

https://github.com/kamranahmedse/git-standup

Shows a list of commits for the past 24 hours

❯ standup  
/Users/zander/code/fairfx/fx-holiday-money-app  
5315f033 - build(multi): HM-925 Improve perf for a couple of pages (16 hours ago) <Zander Martineau>  
4b41c048 - index on feature/HM-925-improve-performance: 1b854d84 fix(ci): AWS-99 Remove builds/deployments associated (#845) (17 hours ago) <Zander Martineau>

cross-port-killer

https://github.com/milewski/cross-port-killer

Kill a process running on a particular port

❯ kill-port 9001

doctoc

https://github.com/thlorenz/doctoc

Generated markdown table of contents

❯ doctoc README.md --github

fx

https://github.com/antonmedv/fx

Command-line JSON processing tool

❯ fx package.json

jq

https://stedolan.github.io/jq/

jq is like sed for JSON data - you can use it to slice and filter and map and transform structured data with the same ease that sed, awk, grep and friends let you play with text.

# use jq to extract just the first commit from a repos list  
❯ curl 'https://api.github.com/repos/stedolan/jq/commits?per_page=5' | jq '.[0]'

npq

https://github.com/lirantal/npq

Safely* install packages with npm or yarn by auditing them as part of your install process

# with npm   
❯ npq install express   

# with yarn, set an alias like so:  
alias npq="NPQ_PKG_MGR=yarn npq-hero"  
❯ npq add express

youtube-dl

https://youtube-dl.org

# install  
brew install youtube-dl  

# use  
❯ youtube-dl d2qfa3tlgH8

Are there any that I've missed? Let me know in the comments

Lessons learned building design systems

Zander Martineau — Thu, 14 Mar 2019 09:22:57 +0000

Having contributed to a few design systems now, I have found that the same issues appear again and again. Most of the time, these issues can be resolved with a bit of forward planning and some common sense, but the rest of it is down to trial and error. Every team has their own needs from a design system so what works for one person may not work for another. Hopefully, the suggestions in this article can be applied to your design system.

Clearly define what should and shouldn't be included in your component library

In my opinion, a design system should only include component primitives and the most common reusable patterns. These would be known as atoms or molecules if you're using an atomic design methodology.

If a component is too complex then I suggest that you move it out of the design system repository. Equally, if it is not going to be used by everyone consuming your design system, then it is also a good candidate for being moved into another repository. Use the design system as the base for everything else your team builds.

This decision also has a basis in performance. More components will increase the package size of the result.

Each team will have their own criteria for what should be included in a design system, but ultimately it is a personal and evolutionary decision. Once you have arrived at your decision, ensure you document it in a place that is easy to find.

Have a clear and consistent naming strategy

It might sound obvious, but giving your components useful and intuitive names is crucial. What might sound good to a designer might not be clear to a developer (and vice versa). This one sounds easy, but is actually quite difficult in practice.

Document everything

The more information you provide for each component, the more it will be used and maintained. You wouldn't want your component to be used incorrectly, so provide information for how and when it should be used.

Provide information about how to consume it from a development perspective, e.g. what code is needed to import it, and what are some example use cases for it.

Docz is a great solution for documenting components. Documentation is written in markdown format (.mdx) and components can be embedded right into the documentation.

Storybook also has the ability to render markdown (using the readme or info add-ons) and is a great alternative for keeping the docs close to the implementation details.

Make components easy to find

If possible, provide a search to find your components. Both Storybook and Docz have a search but they're limited to names of the stories/items only. Alternatively create an index of all components on one page so that they can be easily be searched, Fannypack does a brilliant job of this on their home page. Having a consistent naming strategy will also help in this matter.

Make your components easy to develop

Providing a dedicated development environment is extremely important too. A tool like Storybook is perfect for this because it creates an environment to preview and develop your components in isolation.

Test your components under different conditions by making use of Storybook's add-ons. The Knobs and Viewport add-ons make development much easier by allowing users to change values and data that the component uses.

The story source add-on shows the source code for a given component so it makes it even easier for developers to see examples of it in use.

Provide an interactive demo

If you can publish your components to npm, you can then use something like CodeSandbox to allow developers to experiment with them and test different combinations.

Make your design tokens easy to access and edit

Your designs tokens will be used more than any other aspect of your system, so make them easy to reference and even more easy to update. If you are writing CSS-in-JS, my library, Design System Utils can greatly help in this matter.

Wherever you choose to document your components, your tokens should also be included there as well.

Make your components accessible by default

The extra effort required to make components accessible is negligible compared to the frustration they cause to users with special needs. There are many resources about accessibility online, here's my ever-growing list of a11y resources.

Test your components

The more tests you add, the more robust and reliable your components will be. There are a few different types of tests that you'll need: unit tests, snapshot tests and visual regression tests.

Visual regression tests are brilliant for picking up bugs in components over time. For example, if someone changes a token value for the border colour that is meant for the form inputs, but another component is also using that for its border, then your visual regression tests will notify your team of the change when the tests are run. Chromatic is great for this because it integrates brilliantly with Storybook, and it's free if your project is open source.

Versioning

Using proper semantic versioning (e.g. 1.2.3) will really help when folks consume your design system. There is a clear understanding of why the version changed and what that means for people referencing and consuming your work.

There are many tools that help automate versioning, one of which is Conventional commits; it automatically determines a semantic version bump; automates CHANGELOG generation; and it also integrates with your continuous integration process so it offsets these features and more so developers don't have to think about it.

Automate as much as possible

If you can automate your unit tests, visual regression tests, code coverage, code linting and even your release process then you will again be offsetting mundane and repetitive tasks that your team will not have to worry about.

Dedicate time and resources to maintaining your codebase

I cannot stress this point enough: if you don't dedicate time and resources to maintaining your codebase it will ultimately fail. Fail to be used; fail to change with the times; and fail to be useful to those that need it.

I would be keen to hear your thoughts on this. Do you have anything to add? Can any of my points be improved upon?

Introducing Design System Utils

Zander Martineau — Wed, 14 Feb 2018 22:49:40 +0000

Maintaining styling consistency in a web app (or React Native) is often tough. There isn’t a common way to manage shared values and settings. This micro framework aims to standardise your design-system and provide helpful utilities to access it’s information. It’s more than a set of variables in a specific structure, it includes a few functions to access values in your design system much more easily.

Let me run through the basics

You first need to create your design system file, this contains all your global variables that your app will use, think font-sizes, color palette, spacing etc. I usually create a top-level directory named theme or designsystem, and add an index.js inside, like so:

// ./theme/index.js
import DesignSystem from 'design-system-utils'

// your design-system goes here, see below for details
export const myDesignSystem = {...}

export const ds = new DesignSystem(myDesignSystem, {
  useModularScale: true,
  fontSizeUnit: 'rem',
})

What is the shape of the design system object?

Below are the mandatory items that your design system should use. Beyond these, you can add anything you like.

{
  type: {
    // this should be set as a px value if you have `options.fontSizeUnit` set
    // to 'rem' or 'em' so that the lib can convert the values properly
    baseFontSize: <string>,

    sizes: {
      key: <number | string>,
    },

    // If you're using a modular scale, set it up here
    // Use these docs to find out more: https://github.com/modularscale/modularscale-js
    modularscale: {
      base: <number | array>,  // should be the same as baseFontSize
      ratio: <number>,
    },
  },

  // Color palette
  // Each object needs to have the same shape
  // Each color object needs a `base` value to be the default
  // Have as many color objects as you like
  colors: {
    // Used with `ds.color('colorName')`
    colorPalette: {
      colorName: {
        base: <string>, // base is the default
      },
    },

    // Used with `ds.brand('colorName)`
    brand: {
      colorName: <string>, // base is the default
    }
  },

  // Breakpoints
  // Used with `ds.bp()`
  // Keys can be anything you like
  // Have as many breakpoints as you like
  // Values can be use any unit you like
  breakpoints: {
    key: <number | string>,
  },

  // Z-index
  // Used with `ds.z()`
  zIndex: {
    key: <number>
  },

  // Spacing
  // Used with `ds.spacing()` or `ds.space()`
  spacing: {
    scale: <array>[<number | string>, ...],
  },
}

This is an excerpt from the example design-system. See a more complete example in the example directory.

export const myDesignSystem = {
  type: {
    baseFontSize: '20px',

    // the values below use modular-scale
    sizes: {
      xs: -2,
      s: -1,
      base: 0, // [default] p, h5, h6
      m: 1, // h4
      l: 2, // h3
      xl: 3, // h2
      xxl: 4, // h1
    },

    modularscale: {
      base: 20,
      ratio: 1.5,
    },

    fontFamily: {
      system:
        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans"',
      sans: '"Helvetica Neue", Helvetica, Arial, sans-serif',
      serif: 'Georgia, "Times New Roman", Times, serif',
      mono: 'Menlo, Monaco, "Courier New", monospace',
    },

    lineHeight: {
      headings: 1.1,
    },

    fontWeight: {
      normal: 300, // Useful to set here if using anything other than `normal`
      bold: 'bold', // Useful to set here when bold webfonts come as 400 font-weight.
      headings: 'bold', // instead of browser default, bold
    },
  },
}

Accessing the design system data in your app

To access your design system, you just need to import it to the current file, like so:

import { ds } from './myDesignSystem'

Here I have created a very simple component using the design system and styled-components, you should be able to see how easy it is to pull information from the design system.

// Example uses styled-components
import styled from 'styled-component'
import { ds } from './theme'
export const Box = styled.div`
  font-family: ${ds.get('type.fontFamilyBase')};
  background-color: ${ds.brand('primary')};
  margin: ${ds.space(2)} 0;
`

Options

There are two options that can be passed to your design system. These relate to font-sizing.

// Use default options
export const ds = new DesignSystem(myDesignSystem)

// With custom options
export const ds = new DesignSystem(myDesignSystem, {

  // converts the `type.sizes` values into modular scale values
  useModularScale: true,

  // sets the font-size unit when calling fs.fontSize()
  fontSizeUnit: 'rem',
})

API methods

Get any value

The ds.get() function can be used to get any value from the design-system. You can use dot notation to find nested values at any depth.

// with the system setup, as above
ds.get('type.lineHeight.headings') // e.g. 1.1

I have provided a few other helper methods to make retrieving certain values more simple. Most are short-hands for the ds.get() method.

Font-sizing

The ds.fontSize() method is a short-hand for the ds.get() method, but with a little extra. It is used to pull values from the type.sizes object.

The type.sizes object’s values can be formatted in a few ways:

s: -2 — if a number is used and options.modularscale = true, then ds.fontSize() converts this number to a value on the modular scale.
s: '13px'
s: '1.4rem'

// define some values// type.sizes object
sizes: {
  xs: -2,
  s: -1,
  base: 0, // [default] p, h5, h6
  m: 1, // h4
  l: 2, // h3
  xl: 3, // h2
  xxl: 4, // h1
},

// retrieve some values

ds.fontSize('xl')
ds.fs('xl') // `fs()` is a short-hand alias for `fontSize()`
ds.fs('xl', true) // return font-size in px regardless of `option.fontSizeUnit` value
ds.fs(6) // returns font-size of the 6th item on the modular-scale. This will only work if the òptions.modularscale` is `true`

Modular scale

To make use of a modular scale, there are a few things that need to be done:

set options.modularscale = true, see above for details on this
define your modular scale options in type.modularscale. Design system utils uses modularscale-js to do the conversions.

modularscale: {
  base: 20,
  ratio: 1.5,
},

Color palette

There are two possible ways to access color information: through the color palette and the brand colors. The color palette is intended to contain all the colors (and their shades) that your app will use, and the brand palette is the specific colors that your brand uses. Two methods can be used to retrieve the values, these are:

colors: {
  // With a color palette like this:
  colorPalette: {
    bright: {
      base: '#F9FAFB',
      dark: '#F4F6F8',
      darker: '#DFE4E8',
    },

    dark: {
      base: '#212B35',
      light: '#454F5B',
      lighter: '#637381',
    },
  },

  // With a brand palette like this:
  brand: {
    red: '#e82219',
    deeporange: '#ff7200',
    orange: '#ff9500',
    green: '#c4d000',
    teal: '#1aa5c8',
    navy: '#0052da',
  }
}

Get color palette value

The ds.color() function gets values from the colorPalette object. It assumes every color has a base property and other properties for different shades of the same color. This is a short-hand for the ds.get() function.

// Get values like this:
ds.color('bright') // #F9FAFB - the `base` key is the default, so it is not needed
ds.color('bright', 'dark')

Get brand palette value

The ds.brand() function gets values from the colors.brand object. This is a short-hand for the ds.get() function.

// Get brand values like this:
ds.brand('orange')
ds.brand('pink')
ds.brand('primary.blue') // it is possible to nest this object as much as you like

Get breakpoint values

The ds.bp() method is a short-hand for the ds.get() method. It can be used to get a breakpoint from the breakpoints object.

ds.bp('m')

Get z-index values

The ds.z() method is a short-hand for the ds.get() method. It can be used to get a breakpoint from the zIndex object.

ds.z('low')

Get spacing values

The ds.spacing() method returns a value from your spacing.scale array. It takes an index for that array and converts the value to pixels.

// Example scale array// scale: [0, 8, 16, 24, 32, 40]
ds.spacing(2) // '16px'

Note: ds.space(2) can also be used.

Calculations

The framework currently provides a few calculation functions, multiply, toPx and pxTo:

`multiply(initial, muliplier)`

ds.multiply(10, 2) // 20

// you can pass in another value from the system
ds.multiply(ds.get('spacing.baseline'), 2)

// or just use the key from the system
// the initial value will always be run through `parseFloat()`
ds.multiply('spacing.baseline', 2)

`pxTo(fontSize, baseFontSize, unit)`

Converts px to rem or em

// ds.pxTo(fontSize, baseFontSize, unit)
ds.pxTo(12, 20, 'rem') // 0.6rem
ds.pxTo(12, 20, 'em') // 0.6em

`toPx(fontSize, baseFontSize)`

Converts rem or em value to px

ds.toPx('1.875rem', 16) // 30px
ds.toPx('1.875em', 16) // 30px

Demo & examples

I created a demo on codesandbox.io, it includes examples of using the design-system utils with emotion, styled-components and glamorous. There is also a basic example here.

How do you get it?

You can install it via npm using:

npm install --save design-system-utils

yarn add design-system-utils

How do you contribute?

I am always looking for ways to improve, so welcome any and all feedback. The code is hosted on GitHub at github.com/mrmartineau/design-system-utils

Rebel with a CORS

Zander Martineau — Wed, 14 Feb 2018 22:34:24 +0000

Or How to make your own simple CORS enabled API from one that has CORS disabled

As a front-end developer, I often consume various 3rd party APIs while developing. These APIs could be for weather, crypto currency prices or the latest XKCD comic.

The problem with some of them is that they do not support cross-origin requests (CORS), which means that client-side AJAX calls to these services do not work. This is frustrating but can easily be fixed with the help of a few lines of code in your own micro-service.

Creating the micro-service
All you need to create a simple micro-service is a package called micro. It is a very simple package that enables the creation of asynchronous micro-services, and if you read the project’s readme, you’ll see that a simple service can be created with no more than a few lines:

module.exports = (req, res) => {
  res.end(‘Hello world’)
}

Obviously the above is completely useless, but let me show how easy it is to consume almost any API, at least any API that didn’t need authentication, using micro.

From comic #1810

For this example, I’ll use the free API from the XKCD comic, which cannot be used in AJAX calls on the client-side because CORS is disabled. Calling the url https://xkcd.com/info.0.json returns the latest comic, like so:

{
  "month": "2",
  "num": 1954,
  "link": "",
  "year": "2018",
  "news": "",
  "safe_title": "Impostor Syndrome",
  "transcript": "",
  "alt": "It's actually worst in people who study the Dunningâ€“Kruger effect. We tried to organize a conference on it, but the only people who would agree to give the keynote were random undergrads.",
  "img": "https://imgs.xkcd.com/comics/impostor_syndrome.png",
  "title": "Impostor Syndrome",
  "day": "12"
}

And it can return a specific comic if passed the correct comic ID (https://xkcd.com/1500/info.0.json):

{
  "month": "3",
  "num": 1500,
  "link": "",
  "year": "2015",
  "news": "",
  "safe_title": "Upside-Down Map",
  "transcript": "((A mercator projection of the world map is shown. All the continents have been rotated one hundred eighty degrees.))\n\n((Cuba  is next to alaska, and alaska is touching the tip of south america, which is all near the equator. Mexico is now friends with greenland.\n\n((Iceland, the UK, and asia are all close together. Japan and Taiwan haven't moved with the asian continent, and are technically European.))\n\n((Siberia is now equatorial. Africa is pretty temperate, except for the north bits which are somewhat antarctic.))\n\nCaption: This upside-down map will change your perspective on the world!\n\n{{Title text: Due to their proximity across the channel, there's long been tension between North Korea and the United Kingdom of Great Britain and Southern Ireland.}}",
  "alt": "Due to their proximity across the channel, there's long been tension between North Korea and the United Kingdom of Great Britain and Southern Ireland.",
  "img": "https://imgs.xkcd.com/comics/upside_down_map.png",
  "title": "Upside-Down Map",
  "day": "18"
}

All the micro-service needs to do is to pass-through any requests to the original API and set a few headers to allow for cross-origin requests so that they can be used in AJAX calls on the client-side, like so:

const axios = require('axios')
const { send } = require('micro')
const microCors = require('micro-cors')
const cors = microCors({ allowMethods: ['GET'] })
const DOMAIN = 'https://xkcd.com/'

const handler = async function(req, res) {
  const params = req.url
  const path = `${DOMAIN}${params}`
  const response = await axios(path)
  send(res, 200, response.data)
}

module.exports = cors(handler)

That’s 14 lines of code!

The example above passes any slug information into the API (e.g. 1000/0.json), so calling https://xkcd.now.sh/1000/0.json (my version of the API), would map to https://xkcd.com/1000/0.json. This could be the end of our journey, but I’d like to improve the API UX a bit by changing the endpoints:

xkcd.now.sh should return the latest comic
xkcd.now.sh/1000 should return comic ID 1000

See below on how to achieve that:

const axios = require('axios')
const { send } = require('micro')
const microCors = require('micro-cors')
const cors = microCors({ allowMethods: ['GET'] })
const DOMAIN = 'https://xkcd.com/'
const PATH = 'info.0.json'

const handler = async function(req, res) {
  let id = req.url.replace('/', '')
  const comicId = id ? `${id}/` : ''
  const path = `${DOMAIN}${comicId}${PATH}`
  const response = await axios(path)
  id = response.data.num
  let newResponse
  if (id >= 1084) {
    newResponse = {
        ...response.data,
        imgRetina: `${response.data.img.replace('.png', '')}_2x.png`,
      }
    } else {
      newResponse = {
      ...response.data,
    }
  }
  send(res, 200, newResponse)
}

module.exports = cors(handler)

That’s 29 lines of code! See it here 👀

You can see above that beyond micro, there are two other packages that the service relies on:

axios for the HTTP requests
micro-cors is a simple CORS for micro

My example with the XKCD API returns all of the original data and actually changes the response data slightly as well as how the API is consumed. I decided to add the retina image path (if there is one) as well as simplify the call to the API. So instead of calling xkcd.com/1894/info.0.json you can call xkcd.now.sh/1894.

So, for example: calling https://xkcd.now.sh/1894 would request this URL from the original XKCD API: https://xkcd.com/1894/info.0.json.

{
  "month": "9",
  "num": 1894,
  "link": "",
  "year": "2017",
  "news": "",
  "safe_title": "Real Estate",
  "transcript": "",
  "alt": "I tried converting the prices into pizzas, to put it in more familiar terms, and it just became a hard-to-think-about number of pizzas.",
  "img": "https://imgs.xkcd.com/comics/real_estate.png",
  "title": "Real Estate",
  "day": "25",
  "imgRetina": "https://imgs.xkcd.com/comics/real_estate_2x.png"
}

💪 The code for this service is hosted on GitHub at github.com/mrmartineau/xkcd-api and can be tested using Postman here.

Hosting your new API

I use now by zeit to host my various apps and APIs. now supports the JavaScript language features that this micro-service requires (async/await) as well as HTTPS out of the box. If your hosting does not support these features, you will need to transpile the code back to a version it does support.

From comic #1700

Other examples

For an example of an even more simple pass-through API, you can see my CORS enabled version of the Pinboard feeds API. The code is hosted on GitHub at github.com/mrmartineau/pinboard-api

My thanks go to Andrew Williams, Ashley Nolan & Ciaran Park for their help with the title of this post. Other suggestions from them include:

No CORS for concern: getting that API
Be-CORS you're worth it
COR Blimey gov’nr
CORS, Ugh, what is is it good for
Just CORS

Creating dynamic layouts with Jekyll

Zander Martineau — Sun, 13 Aug 2017 06:55:35 +0000

Liquid syntax error: Unknown tag 'endraw'