Skip to content

Specimens for Gatsby powered Design Systems

Created Aug 29, 2019 – Last Updated Apr 21, 2021

Digital Garden

Some time ago I created a remark plugin for Gatsby called gatsby-remark-design-system. It was my first deep-dive into remark and customizing the AST. It helped me a lot to understand Gatsby and remark plugins. It’s purpose is to display components such as color swatches, typography scales etc. in Markdown files. It works fine to this day, however it’s rather limited in its functionality and doesn’t stand a chance against MDX. Yeah, four years ago MDX wasn’t a thing, time flies!

That’s why I created @lekoarts/gatsby-theme-specimens! It’s the MDX implementation of the old plugin. It exposes React components you can use in your Gatsby/React code (like usual) or in your MDX files — the latter is really comfortable if you use MDX shortcodes. Head over to the interactive preview if you want to see it in action. The preview uses react-live hence you can customize the props/input as you want.

#Installation & Usage

As with any other Gatsby theme you install it via npm/yarn:

npm install @lekoarts/gatsby-theme-specimens

Add it to your config:

module.exports = {
plugins: [
resolve: "@lekoarts/gatsby-theme-specimens",
options: {},

You can also use the preview page as a starter project, by using the Gatsby CLI (you need to install that first if you haven’t done so already):

gatsby new specimens LekoArts/gatsby-starter-specimens

The starter sets up the MDX shortcodes and interactive code blocks with react-live for you :) You don’t have to make them interactive, if you leave out the live prop they’ll just be syntax-highlighted code blocks.

General usage is straightforward, you can import the components from the npm package, e.g. like:

import {
} from "@lekoarts/gatsby-theme-specimens";

The interactive preview shows you how to use these components.

Please follow the rest of the usage instructions in the README and let me know (with an issue) how it can be improved!

#Other components?

The currently implemented components are definitely not the end, I plan on integrating some other components in the future. If you have something specific in mind, please open a feature request, and we can discuss. Thanks!

#Why a Gatsby theme tho?

You might ask yourself why I didn’t publish it as a normal npm package that exposes React components instead of a Gatsby theme.

It’s because Gatsby themes have the powerful shadowing feature which will allow you to edit parts of theme to your liking. In this case you have two possibilities: Shadow the components itself (to create a new structure for example) or use Theme UI to change styles. By creating a file in src/gatsby-plugin-theme-ui/index.js you’re shadowing the Theme UI config of the theme and can use variants for example to change individual designs. This works because the theme uses Theme UI under the hood.

It also makes it possible to accept options (such as contrastGuidelines etc.) and apply them to multiple components or functions. In my opinion it can’t get any easier than that to expose options.

Want to learn more? Browse my Digital Garden