I've spent the last year helping build a design system. These are some of the things I learned along the way

Building reusable components are harder than tutorials make it out to be - especially when writing components for a design system. There are tons of use cases to consider, and stakeholders you've never even met!

At my current project, I've helped flesh out a design system with React components and other functionality for some time now. You can check it out here (Norwegian only). It's not perfect, but it sure let's us write apps a lot quicker, with a lot less bugs.

In this article, I'm going to share some of my learnings from this process. They might not be ground breaking news to some, but if you're building components that people outside your team end up using, they'll thank you for reading this. Hopefully.

Don't allow conflicting props

When you design the API of your component (that is, which props it should accept and what to name them), consider whether or not a future requirement could lead to props colliding or conflicting with each other.

Here's a Button component:

If you want a primary button, all you need to do is to pass primary={true}! That's what you call a slick API, am I right? Nope.

It has two ways of looking - "regular" or "primary". Instinctively, this sounds fine, but what if future you realize you also need a secondary button?

Now, your component will look like this:

Now, that's a potential bug. What if some less experienced developer starts applying both modifiers at once?

Instead, introduce a buttonType property, which accepts a string value of either primary, secondary or whatever future you decides is appropriate. This has proven to work great for us, and I think it'll work great for you too!

Always allow for element substitution

When I first started out as a developer, I was taught the somewhat charming slogan that "assumptions are the mother of all fuck-ups". One thing we often assume when we create reusable components, is the context they will be used in.

In HTML, some contexts require different semantics. If we return to our button, we can't really use it if we want to link to something. I mean, technically we can, but we can't use an <a /> tag. Let's fix that.

By convention, I always support an as prop, which either accepts a component or a string.

Here, I'm renaming the as prop to Element (just for clarity's sake), and refering to that component instead of the hard coded button. Since I'm defaulting the as prop to be button, things work just as before if I don't specify as.

If I later want to use the Button component with a <a /> tag or a <Link /> tag (from react-router, for instance), I can do so without creating a new component!

Pass all unspecified props

When you at first implement a component (particularly lower-level ones like buttons, typography etc), you're not going to have a clue about what future you are going to throw at it. In that case - assume nothing, and just apply any non-API props to the root element!

or, even simpler (since children is a regular prop, too):

This way, when future you (or your colleagues) need support for onMouseEnter, tabIndex or aria-describedby, you don't need to go and add another prop for that. Just spread whatever the user passes in to your root element, and you should be good to go.

One final thing to remember is className. className is a prop that's typically set from the get-go, and in those cases, you should make sure to allow the consumer to add to the existing class names, not overwrite them. You can fix that by applying it like this:

Never rename existing DOM-props!

When we started out with our design system, we tried to be clever, and rename existing DOM props to make them more in line with the rest. That is a terrible idea.

Buttons, for example, have a type property. It's what decides whether a button submits a form, resets it, or does nothing at all. However, "type" is a pretty usable name - for example if we wanted to specify the visual type, like above.

It might be tempting to "repurpose" DOM properties, because they might not make sense in the moment. But stay away from them! Changing from type to buttonType at a later time, for instance, is a really annoying breaking change that's going to piss off your consumers. Believe me - I did exactly that.

Only allow one way of doing things

The last foot-gun I'm going to warn you about today, is the fallacy that several ways of providing a value is convenient. Take our trusted ol' <Button />. When we first created it, we provided the content as a label prop. Then, as time went by, some clever developer (probably me), added the possibility of sending in content via the children prop. However, our implementation now looked like this:

Now, we had to explain to all consumers that you could do both, but if you did, label would take presedence over children. That led to much more confusion than it solved.

So don't do that. Use children for content if possible, and never allow for several ways of doing the same thing.

Another example of this is when we needed to add some invalid styles to input fields. We added an invalid prop, and set the aria-invalid tag based on its value:

Seems fair enough - but you could actually do the same by letting the consumer pass the aria-invalid prop themselves! This is a known API from HTML, and almost as convenient too.

Go create reusable stuff!

I hope this article has given you some new ideas as to how you could structure your components and their APIs. As an added bonus, if you follow these principles in your apps as well, you end up refactoring less, and reusing more.

Thanks for reading!

5 tips for reusable components

Cross Origin Resource Sharing (CORS) is an important concept in modern webapplication security. We will try to explain what it is.

To understand CORS, we also have to understand the same-origin policy. The same-origin policy states that content retrieved from different origins are isolated from eachother. That is, if a webpage is retrieved from origin X it can interact with other resources on origin X only. Most browsers determine that two resources have the same origin if they have identical protocol, host and port. Internet Explorer is an exception, as it excludes the port from the same-origin check.

To illustrate how important the same-origin policy is, we provide an example. Assume that you have logged into your Facebook account in one browser tab, while you browse a webpage with some harmful JavaScript in it in another tab. While you browse Facebook, your browser makes several AJAX-requests to endpoints on Facebook´s servers. These requests are initiated by JavaScript that your browser has downloaded from Facebook. Thus, the resources initiating the requests have the same origin as the endpoints receiving them, and everything is just fine. However, without the same-origin policy, the Facebook endpoints would happily answer every request, regardless of their origin. The harmful JavaScript on the other webpage could then do everything to your account that you are allowed to do yourself.

But, what if we know what we are doing and intentionally want to make requests between these two origins possible, in a secure and controlled manner? This is where Cross Origin Resource Sharing (CORS) comes in. In its simplest form, it allows servers to specifiy which origins that they will allow access to its resources.

The CORS-standard supports the following HTTP-headers:

Access-Control-Allow-Origin

Access-Control-Allow-Credentials

Access-Control-Allow-Headers

Access-Control-Allow-Methods

Access-Control-Expose-Headers

Access-Control-Max-Age

Access-Control-Request-Headers

Access-Control-Request-Method

Origin

We will not explain each here, but instead focus on the first one, Allow-Origin. To allow every origin access, the server can use a wildcard, and return the following header: Access-Control-Allow-Origin: *. This wildcard should only be used for a public, open API. If the server hosts an API that is supposed to be private, it should instead specify an allowed domain, or a comma separated list of domains, like Access-Control-Allow-Origin: https://my-site.com, https://my-site2.com There are different solutions available for setting these headers. They can be set in the configuration of the webserver or they can be set on the endpoints in your application.

If you develop webapplications, you might have seen this message in your console when you try to make a request somewhere: Failed to load <some URL>: No 'Access-Control-Allow-Origin' header is present on the requested resource. This is the same-origin policy in practice. As the message explains, the API is not sending the Allow-Origin-header to allow access to the origin that you make the request from. If you or someone you know control the API it is easy, as you can configure the header yourself. If you do not control the API you should try to determine why the API does not send the header. Is the API not supposed to be requested by external consumers? Maybe you have to provide some authorization tokens?

In this post we have only scratched the surface of CORS. If you are interested in learning more you might enjoy looking into the referenced articles.

Cross Origin Resource Sharing

In the magic year of 2015 I started my career in Bekk and we were introduced to destructuring in Javascript through ES6. Before this we had to assign values from objects and arrays the hard way.

This can be really cumbersome for larger structures. Destructuring allow us to assign these values in a simpler way:

Custom variable names

If we wanted to name our variables lat and long instead we could destructure like this:

While not as straightforward, it provide powerful flexibility to our destructuring.

Nested destructuring

Destructuring nested objects is just as simple really. The difference is that we have to account for the structure when we assign the variables.

Default values

To save ourself a lot of lines checking for undefined values if the property we try to assign from does not exist, we can set default values when we destructure.

As you can see in this example, we have to provide a default value to position as well as latitude and longitude for the default values in a nested object to work.

Named parameters

When programming Javascript I use destructuring a lot as named parameters in functions.

This allow us to use all the destructuring functionality above on the parameters to a function. Does providing default values to function parameters sound appealing? You bet. A long with other obvious advantages such as ignoring parameter ordering when using the function.

11-Dec

Today's posts

5 tips for reusable components

Cross Origin Resource Sharing

Destructuring and named parameters