Skip to contentSkip to footer
Close-up image of a chameleon showcasing its textured skin and vibrant colors

Photo: Pierre Bamin

Customization

Make Natura11y Yours

The Natura11y Design Ecosystem is made to be customized, extended, and adapted to your needs. Create anything from a simple website theme to a comprehensive design system.

Customizable CDN

The Quick Start guide shows how to add Natura11y’s stylesheet from the CDN. Because Natura11y uses CSS variables, you can update colors, typography, spacing, and other style attributes in your own stylesheet without changing Natura11y Core.

In Figure 1 below, theme.css loads after the Natura11y stylesheet, so custom values set in this file will take effect.

HTML
<!-- Natura11y Stylesheet -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@natura11y/core@5.2.5/dist/natura11y.css" />


<!-- Custom Stylesheet -->
<link rel="stylesheet" href="/css/theme.css" />
Figure 1

CSS Variables

Natura11y’s CSS variables are declared inside :root, making them available throughout the page. Variables are grouped by feature, and each documentation page lists the custom properties available for that feature.

Example: Updating Colors

Add new color values to theme.css by declaring them inside :root. Figure 2 replaces several of Natura11y’s default colors with a custom palette.

CSS
:root {
  --primary: #008f47;
  --secondary: #004d40;
  --dark: #0d1627;
  --canvas: #f4f4ef;
  --secondary-text: white;
}
Figure 2

Any Natura11y style that uses these variables will now use the new values. The same approach can be used for typography, spacing, borders, and other documented variables.

Core: HTML, CSS, and JS

Natura11y Core gives you access to its Sass and JavaScript source. Figure 3 shows the basic structure.

core/
├── src/
│   ├── js/
│   │   ├── accordion.js
│   │   ├── alert.js
│   │   ├── backdrop.js
│   │   ├── ...
│   │   └── utilities/
│   ├── scss/
│   │   ├── _accordion.scss
│   │   ├── _alert.scss
│   │   ├── _backdrop.scss
│   │   ├── ...
│   │   └── index.scss (loads Sass partials)
│   └── index.js (loads styles and initializes JavaScript classes)
└── dist/
    ├── natura11y.css (compiled CSS output)
    └── natura11y.js (compiled JS output)
Figure 3

SCSS

Natura11y’s Sass is organized much like the documentation, with a partial for each component, utility, or feature. Component class names follow BEM conventions, and related CSS variables are grouped near the top of each partial. The compiled CSS uses cascade layers and logical properties to keep styles predictable and easy to customize.

Vanilla JavaScript

Natura11y’s JavaScript uses native browser APIs and a simple class-based structure, with each class focused on a single interaction. Shared Core utilities support common behavior and are also used by Natura11y React, keeping both versions aligned without adding a framework dependency to Core.

The Sass and JavaScript compile into two files in dist: natura11y.css and natura11y.js.

Design System Architecture

Natura11y is structured to serve as the foundation for a complete design system. Its tools and packages work together to connect design decisions, shared assets, component behavior, and production code.

  • Figma UI Kits use local variables, theme modes, and reusable patterns that align with Natura11y’s CSS foundation.

  • Natura11y Icons can be managed across Figma and the front end as part of a shared icon system.

  • Natura11y React applies the same Core styling foundation and accessibility patterns to React projects.

  • Natura11y Storybook presents vanilla and React examples side by side.

Together, these resources can establish a shared visual language while keeping design decisions, accessible behavior, and production code connected as the system grows.

Document Custom Properties

The document canvas can be customized by redefining the related CSS custom properties. The reduced-motion media query automatically changes --html-scroll-behavior to auto when a visitor requests reduced motion.

CSS
:root {
  --body-min-width: 325px;
  --body-max-width: 100dvw;
  --body-min-height: 100%;
  --html-scroll-behavior: smooth;
}
Figure 4
Custom propertyDefaultPurpose
--body-min-width325pxMinimum inline size of the document body.
--body-max-width100dvwMaximum inline size of the document body.
--body-min-height100%Minimum block size applied to the html and body elements.
--html-scroll-behaviorsmoothScrolling behavior of the document; reduced-motion preference changes it to auto.

Get Started

Accessibility

Figma