Using Design Tokens Generated by the A11y Theme Builder

Design tokens generated by the A11y Theme Builder are provided in a structured JSON format. These tokens encapsulate design decisions such as colors, typography, spacing, and more, which can be directly used in your project's stylesheets and code.

JSON Structure

The generated JSON file is structured into various sections, each corresponding to different aspects of your design system:

• Atoms
• Molecules
• Organisms
• Layers
• Metadata

Example JSON Structure

{
    "atoms": {
        "colorPalette": {
            "colors": [
                {
                    "name": "Teal",
                    "hex": "#3fb394"
                }
            ],
            "defaultColorName": "Teal"
        },
        ...
    },
    "molecules": {
        "avatars": {},
        ...
    },
    "organisms": {
        "dataTables": {},
        ...
    },
    "layers": {},
    "metadata": {
        ...
    },
    "id": "My Design"
}
 ```
 ### Working with Design Tokens

#### Atoms

Atoms are the basic building blocks of your design system. They include color palettes, typography, spacing, and more.

**Color Palette Example:**

{ "colorPalette": { "colors": [ { "name": "Teal", "hex": "#3fb394" } ], "defaultColorName": "Teal" } }

To use this color in your CSS:

:root { --color-teal: #3fb394; }

body { background-color: var(--color-teal); }

**Typography Example:**

{ "fontsSettings": { "baseFontSize": 16, "fontWeights": [ 300, 400, 600, 700, 800 ] } }

To use these font settings in your CSS:

:root { --base-font-size: 16px; --font-weight-regular: 400; --font-weight-bold: 700; }

body { font-size: var(--base-font-size); font-weight: var(--font-weight-regular); }

h1 { font-weight: var(--font-weight-bold); }

#### Molecules

Molecules combine atoms to form more complex components like buttons, dropdowns, and sliders.

**Button Example:**
 ```
 {
    "standardButtons": {
        "minWidth": 6
    }
}

To use this button setting in your CSS:

 button.standard {
    min-width: 6rem;
}

Chart Example:

{
    "chartDonut": {
        "cutoutThickness": {
            "min": 0,
            "max": 100
            }
        }
    }
}

To use this chart setting in your JavaScript chart configuration:

const donutChartConfig = {
    type: 'doughnut',
    data: {...},
    options: {
        cutoutPercentage: 50 // Use a value between min and max
    }
};

Organisms

Organisms are complex components made up of multiple molecules. Examples include data tables, navigation bars, and footers.

Navigation Bar Example:

{
    "primaryNav": {}
}

To use this navigation bar in your HTML and CSS:

<nav class="primary-nav">
    <!-- Navigation items here -->
</nav>

.primary-nav {
    /* Add your styles here */
}

Metadata

Metadata provides additional information about the design tokens, such as creation and update timestamps, and overall color settings.

Metadata Example:

{
    "metadata": {
        "sample": false,
        "time": {
            "createdInMs": 1681464745221,
            "lastUpdateInMs": 1698766878813
        },
        "colors": {
            "primary": "#339779",
            "secondary": "#3FB394",
            "tertiary": "#75C8B2",
            "background": "#F6FBFA"
        }
    }
}

This information can be used for versioning or auditing purposes.

How to Work with Design Tokens

Step 1: Extract the JSON File

First, ensure you have the JSON file generated by the A11y Theme Builder. This file contains all the design tokens you'll need for your project.

Step 2: Import the JSON File

Import the JSON file into your project. This can be done in various ways depending on your project's setup.

Example using JavaScript:

import designTokens from './path/to/design-tokens.json';

Step 3: Convert JSON to CSS Variables

You can convert the JSON tokens to CSS variables for easy use in your stylesheets.

Example using JavaScript:

const root = document.documentElement;

const setCSSVariables = (tokens) => {
    Object.keys(tokens).forEach(key => {
        const value = tokens[key];
        if (typeof value === 'object') {
            setCSSVariables(value);
        } else {
            root.style.setProperty(`--${key}`, value);
        }
    });
};

setCSSVariables(designTokens.atoms.colorPalette.colors[0]);

Step 4: Use CSS Variables in Your Stylesheets

Once the tokens are converted to CSS variables, you can use them throughout your stylesheets.

Example using CSS:

body {
    background-color: var(--hex);
}

Step 5: Utilize Tokens in Component Styles

Integrate the design tokens into your component styles to ensure consistency across your project.

Example using React:

const Button = () => {
    return (
        <button style={{ backgroundColor: 'var(--color-teal)' }}>
            Click Me
        </button>
    );
};