Leverage the wide variety of powerful React components to build your design system. Display your colors, typography or any other design tokens with ease and focus on the design system itself, not on how to showcase it. Works seamlessly with MDX.
[](https://specimens.lekoarts.de)
Read the [Source Code](https://github.com/LekoArts/gatsby-starter-specimens).
Also be sure to check out other [Free & Open Source Gatsby Themes](https://themes.lekoarts.de) and my [Personal Website](https://www.lekoarts.de?utm_source=specimens&utm_medium=Theme).
## Features
- Theme UI-based theming
- Suitable for MDX
- Offers React components specifically designed for design systems. You can display:
- Colors as swatches and rows. Individually placed or automated from an object/array in your theme file
- Typography e.g. font-family, font-size, font-weight and headings
- Spacing scales
- Audio files and downloads
- border-radius or box-shadow
- Alerts to emphasize important messages
## Installation
```sh
npm install @lekoarts/gatsby-theme-specimens theme-ui
```
This theme has `theme-ui` defined as a `peerDependency` so make sure to also install it if you don't use it already.
### Install as a starter
This will generate a new site that pre-configures the theme including example content and additional plugins. Replace the `theme.js` file with your theme file and you have a living style-guide!
```sh
npx gatsby new gatsby-starter-specimens https://github.com/LekoArts/gatsby-starter-specimens
```
[**View the starter's code**](https://github.com/LekoArts/gatsby-starter-specimens)
## Usage
### Theme options
| Key | Default Value | Description |
| -------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `contrastGuidelines` | `AA` | The color swatches display in their top section whether white/black text has sufficient color contrast with the respective color. By default the function determines that Pass/Fail by 'AA' (ratio at least 4.5:1). You can also set this value to 'AAA' (ratio at least 7:1). |
| `CMYK` | `true` | The color swatch and color row component display their values in HEX, RGB, and CMYK. You can optionally disable the CMYK field. |
| `codeExample` | `true` | The heading component displays Theme UI code implementation examples below the different headings. You can disable those by setting it to `false`. |
| `rootFontSize` | `16` | Values for spacing, border-radius, font-size mostly can be defined as `rem` values. As the examples shouldn't be influenced by the root font size of the website, but the design system itself you can define your theme's rootFontSize here. |
#### Example usage
```js
// gatsby-config.mjs
const config = {
plugins: [
{
resolve: `@lekoarts/gatsby-theme-specimens`,
options: {
contrastGuidelines: `AAA`,
codeExample: false,
rootFontSize: 16,
}
}
}
]
}
export default config
```
## Components
The heart of this theme are the reusable React components that you can use to fill your design system with content. Every component has mandatory (and sometimes optional) fields. Some components such as the ones for color require the input in a specific format, please keep that in mind. Visit the [**Demo Website**](https://specimens.lekoarts.de) to see how to use the components.
### Shadowing
Please read the guide [Shadowing in Gatsby Themes](https://www.gatsbyjs.com/docs/how-to/plugins-and-themes/shadowing/) to understand how to customize the theme!
### Modifications
As with every Gatsby theme you can of course shadow the files (e.g. `src/@lekoarts/gatsby-theme-specimens/alert.js`) but if you only want to change some styles, not the whole structure of the component you can get away with another approach. Since all components are styled with a Theme UI/System UI compatible theme file, you are able to override it.
Every component has a `variant` defined in its styles, e.g. the mentioned "Alert" component:
```jsx
const Alert = ({ children, type = `hint` }: AlertProps) => (
{dict[type]}
{children}
);
```
Here: `...theme.alerts[type]`
You can use the variant to add additional styles / override styles. Create a new file at `src/@lekoarts/gatsby-theme-specimens/theme.js` with the following content:
```js
import baseTheme from "@lekoarts/gatsby-theme-specimens/src/theme";
export default {
...baseTheme,
alerts: {
hint: {
padding: `3rem`,
},
},
};
```
The [**Demo Website**](https://specimens.lekoarts.de) tells you the respective variant names you can use to change styles. Normally the variant is defined on the outermost HTML element of the component, if you want to change elements inside those you are able to use CSS selectors. In doubt have a look at the source file :)
### Using together with existing Theme UI config
Since this theme uses a local file with the [`@theme-ui/presets` tailwind](https://theme-ui.com/packages/presets) your Theme UI config you e.g. set up with `gatsby-plugin-theme-ui` won't affect the styles of this theme.
### MDX Shortcodes
In order to be able to use these components without importing them every time in your MDX files, you should define them as components / shortcodes. MDX has [documentation](https://mdxjs.com/blog/shortcodes/) on that, and also [Theme UI](https://theme-ui.com/packages/gatsby-plugin#components).
When you use `gatsby-plugin-theme-ui` in your project, create a new file at `src/gatsby-plugin-theme-ui/components.js` and insert this content:
```jsx
import {
Alert,
Audio,
BorderRadius,
ColorFamilies,
ColorRow,
ColorSwatch,
Download,
FontFamily,
FontSize,
FontWeight,
Heading,
Palette,
Shadow,
Space,
Table,
Video,
} from "@lekoarts/gatsby-theme-specimens";
export default {
Alert: ({ type, children }) => {children},
Audio: ({ autoplay, loop, name, desc, src }) => (
),
BorderRadius: ({ radii }) => ,
ColorFamilies: ({ colors }) => ,
ColorRow: ({ color, name, prefix }) => (
),
ColorSwatch: ({ color, name, minimal, prefix }) => (
),
Download: ({ name, src, bg, preview, notes }) => (
),
FontFamily: ({ fonts, previewText }) => (
),
FontSize: ({ fontSizes }) => ,
FontWeight: ({ fontWeights, previewText }) => (
),
Heading: ({ styles, theme, previewText }) => (
),
Palette: ({ colors, mode, single, minimal, prefix }) => (
),
Shadow: ({ shadows }) => ,
Space: ({ space }) => ,
Table: ({ columns, titles, children, className }) => (
{children}
),
Video: ({ autoplay, loop, muted, name, poster, src }) => (
),
};
```
This way you are able to use the components directly in your MDX file without importing them:
```md
Make it so!
```
## Changelog
You can find the extensive [changelog of changes on GitHub](https://github.com/LekoArts/gatsby-themes/blob/main/themes/gatsby-theme-specimens/CHANGELOG.md). You'll be able to see each patch, minor, and major changes and what pull requests contributed to them.
## Questions?
If you have general questions or need help with Gatsby, please go to one of the [support platforms](https://www.gatsbyjs.com/contributing/community/#where-to-get-support) mentioned in Gatsby's documentation. If you have a specific question about this theme, you can head to the [GitHub Discussions](https://github.com/LekoArts/gatsby-themes/discussions) of the repository.
## 🌟Supporting me
Thanks for using this project! I'm always interested in seeing what people do with my projects, so don't hesitate to tag me on [Bluesky](https://bsky.app/profile/lekoarts.de) and share the project with me.
Please star this project, share it on Social Media or consider supporting me on [GitHub Sponsors](https://github.com/sponsors/LekoArts)!
