Configuration

Siimple is based in a set of configuration rules written in JavaScript, where you can define your theme, mixins for core elements and additional styles.

This is an example of a configuration file for siimple:

import colors from "@siimple/colors";
import base from "@siimple/preset-base";

export default {
    ...base,
    useRootStyles: true,
    useBorderBox: true,
    prefix: "",
    colors: {
        ...base.colors,
        primary: colors.blue["500"],
        secondary: colors.mint["600"],
        text: colors.gray["800"],
        background: "#fff",
        muted: colors.gray["200"],
    },
    fonts: {
        body: "'Roboto',sans-serif",
        heading: "'Montserrat',sans-serif",
        code: "monospace",
    },
};

Prefix

The prefix section allows you to customize the prefix that will be used for naming the elements of siimple. Using a prefix is useful to prevent naming collision with your custom classes or with other CSS libraries.

For example, you can use si- as prefix by setting the prefix section:

export default {
    prefix: "si-",
    // ...other configuration
}

Now every component class will have the configured prefix:

.si-button {
    /* ... */
}
.si-button.is-primary {
    /* ... */
}
.si-button.is-secondary {
    /* ... */
}

Breakpoints

You can customize the breakpoints used in siimple adding an object in the breakpoints section with your custom breakpoints. The keys in this object are the breakpoints names, and the value can be one of the following:

• A string with the screen size in px, that will be set as the min-width value.
• An object with the values for min-width and max-width. For example, {min: "0px", max: "600px"} will generate @media screen and (min-width: 0px) and (max-width: 600px).

This is the default breakpoints configuration:

export default {
    breakpoints: {
        mobile: {
            max: "600px",
        },
        tablet: {
            min: "600px",
        },
        desktop: {
            min: "1200px",
        },
    },
    // ...other configuration
};

Theme scales

You can configure the list of CSS properties specific for your project using the theme scales, that includes colors, fonts, sizes, and more!

import colors from "@siimple/colors";

export default {
    colors: {
        primary: colors.blue["500"],
        secondary: colors.mint["600"],
        text: colors.gray["800"],
        background: "#fff",
        muted: colors.gray["200"],
    },
    fonts: {
        body: "'Roboto',sans-serif",
        heading: "'Montserrat',sans-serif",
        code: "monospace",

        body: ["Roboto", "sans-serif"],
        heading: ["Montserrat", "sans-serif"],
        code: ["monospace"],
    },
    // ...other configuration
};

Color Modes

Color modes makes it easy to change the color mode of your website, including support for dark and light modes. Color modes can be configured in the colorModes field of your theme configuration:

import colors from "@siimple/colors";

export default {
    useColorModes: true,
    colors: {
        text: colors.gray["700"],
        background: "#fff",
        primary: colors.blue["500"],
        // ...other colors
    },
    colorModes: {
        dark: {
            text: "#fff",
            background: colors.gray["800"],
        },
        // ...other color modes
    },
    // ...other configuration
};

Read more about color modes.

Mixins

Mixins allows you to define groups of styles that can be re-used throughout your custom styles. Mixins can be also used to customize built-in elements.

Mixins are defined in the configuration of siimple, and can be applied in the styles using the apply keyword:

export default {
    buttons: {
        // Mixin to customize built-in button element
        default: {
            backgroundColor: "primary",
            color: "white",
            padding: "2rem",
        },
        // Custom button mixin
        outline: {
            // custom outline button styles
        }
    },
    // ...other configuration
    style: {
        ".outline-button": {
            apply: "buttons.outline",
        },
    },
};

Configuration flags

Use the configuration flags to enable or disable some features of siimple:

• useRootStyles: add root styles to the <html> element. Default is true.
• useBorderBox: adds a global box-sizing: border-box. Default is true.
• useCssVariables: uses CSS variables for some theme scale values (colors and font families). Default is false.
• useColorModes: allows to use color modes defined in the colorModes field of your configuration. Default is false.
• useColorModesMediaQuery: allows to use the prefers-color-scheme media query to set the color mode to apply. Note that useColorModes flag should be also enabled. Default is false.

Flags are defined in the first level of the configuration object:

export default {
    useRootStyles: true,
    useBorderBox: true,
    useCssVariables: false,
    useColorModes: false,
    useColorModesMediaQuery: false,
    // ...other configuration
};

Root styles

Add additional styles to the <html> element using the root section:

export default {
    root: {
        margin: "0px",
        padding: "0px",
    },
    // ...other configuration
};

Styles

You can include your styles on siimple using the styles section of the configuration. Styles in this section have access to values defined in the scales section, such as colors and fonts.

export default {
    styles: {
        "h1": {
            fontFamily: "heading",
            fontSize: "2.5rem",
        },
        ".my-button": {
            backgroundColor: "primary",
            display: "block",
            "&:hover": {
                backgroundColor: "secondary",
            },
        },
    },
    // ...other configuration
};

Styles defined in this section must follow the styles syntax specification.

Presets

Presets allows you to extend siimple with reusable styles, mixins and theme scales.

import base from "@siimple/preset-base";

export default {
    ...base,
    // ...other configuration
};

Core modules (added in v4.1.0)

In the modules field of your configuration you can disable the core modules (elements, helpers, markup or reset) that you do not need for your project.

To disable only specific modules, provide an object in the modules field and set a false value to the modules that you do not need:

export default {
    modules: {
        button: false,
        badge: false,
        margin: false,
        reset: false,
    },
    // ...other configuration
};

To enable only specific modules, provide an array with the modules that you need for your project:

export default {
    modules: [
        "button",
        "padding",
    ],
    // ...other configuration
};

If you want to disable all modules, provide an empty array to the modules field:

export default {
    modules: [],
    // ...other configuration
};

This is the list of the available core modules of siimple:

You can use the elements or helpers aliases for enable or disable all elements or helpers, instead of adding or removing all items individually. For example, to disable all elements you can just use elements: false instead of disabling all elements individually:

export default {
    modules: {
        elements: false,
    },
    // ...other configuration
};

If you need to enable or disable only some individual elements, you can use the following available elements:

In case that you need to enable or disable only specific helpers, you can use the following list of available helpers: