Matryoshka

Matryoshka is a generic and versatile set of SASS functions, mixins and Javascript tools, hybridly based on Atomic Design and ITCSS to start building your own design system.

What’s different with other frameworks?

It builds your own custom classes based on your own settings.

matryoshka/
├── components/     <!-- Files that build CSS declarations -->
├── engine/         <!-- Core files -->
└── settings/       <!-- Settings file(s) -->
_core.scss          <!-- Core imports - required -->
_components.scss    <!-- Components imports - optional -->

Components

.my-

CSS declarations of UI elements like grids, buttons, forms, tables, etc.

Modifiers

.mod-

Apply variations on the component. Modifiers are always attached to a component.

Utilities

.u-

CSS utilities classes that override components and modifiers with the !important rule. For example .u-p-foo returns spacing called foo as padding.

<div class="u-[CSS shorthand property]-[Pattern name][Optional screen size pattern name]"></div>
<!-- Utility padding foo -->
<div class="u-p-foo"></div>
<!-- Returns padding: [foo value + design system unit] !important 
    For example padding: 20px !important; -->

<!-- Utility padding foo on bar screen size -->
<div class="u-p-foo-bar"></div>
<!-- Returns 
    @media (bar screen width) {
        padding: [foo value + design system unit] !important
    } -->

1. u- is the prefix to use to call utility class name
2. CSS shorthand property refers to CSS property here is the list
3. Pattern name refers to the name of your pattern (color, spacing, font size, etc) from your own Matryoshka settings
4. Optional screen size pattern name refers to an optional responsive suffix based on your own screen sizes settings $ds-sreen-sizes

Responsive display

matryoshka/components/utilities/responsive-display.scss

Responsive display refers to $ds-screen-sizes. It is used to build responsive class utilities, when you want to display someting on a specified screen size.

Call responsive display utilities with custom data attributes to quickly apply a responive display on several screen sizes at once. Just separate screen sizes with space or comma or both.

Spacings - Responsive

matryoshka/components/utilities/spacings.scss

Spacings refer to margins and paddings. $ds-spacings is used to build margins and paddings class utilities.

Spacings come with custom responsive data attributes to quickly apply a spacing on several screen sizes at once. Just separate screen sizes with space or comma or both.

Core

_core.scss

Settings and main functionalities. Include _core.scss to get all the functions and mixins. No CSS declaration is compiled from this file. Only core functions, mixins and variables. You may include this file in any SASS file, no changes will be made. Only core functions.

Components

_components.scss

Components are CSS classes presets ready to use. HTML5 tags are considered as components. Matryoshka comes with basic components called utilities. To add components, add @import components/yourComponent.scss in the file _components.scss.

Components are html/css structures presets that can be customized with defined patterns called modifers. Each component has its own modifiers coming with its own documentation.

mod- means modifier and must be added to an existing component.

<div class="componentName">

<div class="componentName mod-modifierName">

In addition, components can be easily customized with utilities:

<div class="componentName mod-modifierName u-c-colorName">

Available components

• Alerts w/ Javascript
• Badges
• Buttons
• Dropdowns w/ Javascript
• Forms
• Grid
• Lists
• Modals w/ Javascript
• Tabs w/ Javascript

Settings

The most important part for the user, this file contains all Matryoshka parameters.

Unit

$ds-unit

The unit that will be used by default. You can enter any CSS valid unit.

• SASS variable type: string
• Learn more about CSS Units

// Example
$ds-unit: px;

Colors

$ds-colors

In Matryoshka, colors are organised in groups - color families into a SASS map $ds-colors. There are 3 type of color families:

Automatic

Enter a single valid CSS color and Matryoshka computes a set of matched contrasted colors with the same hue. The computed set is depending on your own settings in $ds-contrasts.

• SASS variable type: string
• Learn more about CSS colors

// Example
$ds-colors: (
    automaticFamilyName: #1234ef
);

Manual

You manually enter a SASS map of custom valid CSS colors with one colors set as reference.

• SASS variable type: map
• Learn more about CSS colors

// Example
$ds-colors: (
    manualReferenceFamilyName: (
        0:              #1234ef,  // 0 (required) is the reference color
        colorName1:     red,
        colorName2:     hsl(50, 10%, 50%),
        colorName3:     rgba(0, 10, 25, .8)
    )
);

Custom

You enter a simple SASS map of valid CSS colors.

• SASS variable type: map
• Learn more about CSS colors

    customColorGroupName: (
        colorName1:     #123456,
        colorName2:     orange,
        colorName3:     hsl(79.7, 50%, 20%)
    )
);

Contrasts

$ds-contrasts

This feature is enabled only if the color family is set as automatic.

Useful for automatic contrast adjustments and accessibility. Matryoshka automatically computes matching color sets from color groups defined as automatic in $ds-colors. Returned colors are rendered with the same hue as the reference color, only lightness is modified.

• Enter any name as contrast name
• Contrasts values must be integer between -100 and +100
• SASS variable type: map

Contrast > 0

Renders matched colors from the reference color, optimized and recommended for readability. If reference color is light, returns a dark color and vice-versa. For example, if full black is set as reference color, returns full white.

Contrast < 0

Emphasizes, accent the current luminance of the reference color. If the color is dark, result gets darker. May render unexpected colors, use knowingly. For example, if full black is set as reference color, returns full black.

Contrast = 100

This value is very useful to automatically obtain the proper web contrast for readability.

• Returns white #ffffff if the input color luminance is below or equal the luminance threshold
• Returns black #000000 if the input color luminance is above the luminance threshold

Contrast = -100

Opposite behavior of contrast = 100.

• Returns white #ffffff if the input color luminance is below or equal the luminance threshold
• Returns black #000000 if the input color luminance is above the luminance threshold

Example with dark color

// Example
$ds-colors: (
    autoFamilyName: #123456
);
// with
$ds-contrasts: (
    max:       100, // Returns a fully contrasted color, recommended for proper web contrast
    light:     30,  // Returns contrasted color, recommended for proper web contrast
    light-rev: -50, // Returns accentuated contrast, not recommended for proper web contrast
    max-rev:   -100 // Returns fully accentuated contrast, not recommended for proper web contrast
);

Example with light color

// Example
$ds-colors: (
    autoFamilyName: #d3e8f8
);
// with
$ds-contrasts: (
    max:       100, // Returns a fully contrasted color, recommended for proper web contrast
    light:     30,  // Returns contrasted color, recommended for proper web contrast
    light-rev: -50, // Returns accentuated contrast, not recommended for proper web contrast
    max-rev:   -100 // Returns fully accentuated contrast, not recommended for proper web contrast
);

Luminance method

Matryoshka comes with functions that computes color contrasts automatically. These functions can be adjusted to your needs with luminance method and luminance threshold.

Method

$ds-luminance-method

Sets the method to apply on automatic contrasts.

• SASS variable type: SASS number
• Possible values:
  • 1 Weighted Euclidean Distance in 3D RGB Space
  • 2 W3C recommandation
  • 3 Luma sRGB default

Threshold

$ds-luminance-threshold

Define the luminance threshold between light and dark.

• SASS variable type: SASS number
• Possible values: Float between 0 and 1
  • 0.5 default

Screen sizes

$ds-screen-sizes

Sets the different screen sizes you wish to use. It is recommended to use semantic names, easy to remenber and to use, they are used to name your CSS classes utilities.

• SASS variable type: SASS map
• Enter any name as screen size name
• Enter an integer as value without unit
• Always use infinite as value for the largest screen

Example 1

Example with Bootstrap break points and naming

$ds-screen-sizes: (
    xs: 576,
    sm: 768,
    md: 992,
    lg: 1250,
    xl: infinite
);

You get these utilities classes

Example 2

Custom example with custom break points and naming.

// Other custom example
$ds-screen-sizes: (
    mini:   400,
    medium: 808,
    large:  1024,
    wide:   infinite
);

You get these utilities classes

Fonts

$ds-fonts

Matryoshka enables easy fonts integration for local fonts, Google Fonts and web safe font. Each font type is declared as a SASS map.

Google Fonts

Matryoshka supports Google Fonts as follows:

// Example of a Google Font declaration
$ds-fonts: (
    myCustomGoogleFontName: ( // Your own font family name
        type:        'google', // Sets the font type
        name:        'Montserrat', // The Google font name
        weight:      'Bold', // Sets the weight of the font, leave empty '' for default weight
        fallback:    'sans-serif' // Sets a web safe fallback font. Value can be any web safe font.
    )
);

• SASS variable type: SASS map
• Enter any name that will be used as font family name
  • myCustomGoogleFontName: ( Your own font family name (that has nothing to do with your font file name).
    • type: 'google' sets that it is a Google Font.
    • name: 'Montserrat' sets a valid Google Font family name
    • weight: 'Bold' sets a valid weight of the Google Font, leave empty '' for default weight
    • fallback: '' sets a web safe fallback font. Value can be any web safe font.
  • )

Local fonts

When your font files are placed locally.

// Example of a local font declaration
$ds-fonts: (
    myCustomLocalFontName: ( // Your own font family name
        type:        'local', // Sets the font type
        name:        'myFontFile', // The font file names without extension (*.ttf, *.woff, etc)
        path:        '../path/to/the/fonts/folder/',
        fallback:    'sans-serif'
    )
);

• SASS variable type: SASS map
• Enter any name that will be used as font family name
  • myCustomLocalFontName: ( Your own font family name (that has nothing to do with your font file name).
    • type: 'local' sets that it is a local font.
    • path: '../path/to/the/fonts/folder/' is the relative path to the folder containing your font files from the compiled CSS path.
    • name: 'myFontFile' is the font file name without extension (.ttf, .woff, etc), assuming you have a folder with your font files called
      • myFontFile.ttf
      • myFontFile.woff
      • myFontFile.woff2
      • myFontFile.otf
      • myFontFile.svg
      • etc
    • fallback: '' sets a web safe fallback font. Value can be any web safe font.
  • )

Web safe fonts

You can also simply use a web safe font

// Example of a web safe font declaration
$ds-fonts: (
    myCustomLocalFontName: ( // Your own font family name
        type:        'local', // Sets the font type
        name:        'myFontFile', // The font file names without extension (*.ttf, *.woff, etc)
        path:        '../path/to/the/fonts/folder/',
        fallback:    'sans-serif'
    )
);

• SASS variable type: SASS map
• Enter any name that will be used as font family name
  • myCustomWebsafeFontName: ( Your own web safe font family name (that has nothing to do with your font name).
    • type: 'websafe' sets that it is a web safe font.
    • name: 'sans-serif' must be a valid web safe font name.
  • )

Font sizes

$ds-font-sizes

Here is the list of all the different font sizes that will be used into your design system.

• SASS variable type: SASS map
• Enter any name for each font size
• Each value must be an integer without unit, assuming your design system unit $ds-unit

Example

Example of a set of font sizes

$ds-font-sizes: (
    xxs:            10,
    sm:             18,
    xxl:            64
);

You get these utilities classes

Assuming your have the following screen size set

// Other custom example
$ds-screen-sizes: (
    mini:   400,
    medium: 808,
    wide:   infinite
);

Typography

$ds-typography

Typography is a SASS map that contains your own list of CSS properties dedicated to fonts. You can use is through SASS mixin. The goal is to obtain a typography consistency into your design system and avoid misuse of fonts.

• SASS variable type: SASS map
• Enter any name that will be used as typography name
  • myTypographyName: ( Your own typography.
    • font-family sets the name of a font family declared into $ds-fonts.
      • Assuming you have a font family name called foo, enter font-family: foo.
      • Using font families names from $ds-fonts is recommended but you can use any static valid family name (like web safe)
    • any-other-valid-css-property You may include as much as valid CSS properties as you want.
    • For consistency purpose, it is recommended to use Matryoshka functions for values when applicable:
      • my-font-size(nameOfTheFontSize)
      • my-color(nameOfTheColor[, optional contrastName])
  • )

Example 1

// Assuming we have the a font family called myFontFamilyName
$ds-fonts: (
    myFontFamilyName: (
        type:               'local',
        name:               'myFontFile',
        path:               '../path/to/the/fonts/folder/',
        fallback:           'sans-serif'
    )
);

$ds-typography: (
    caps: (
        font-family:        myFontFamilyName,
        text-transform:     uppercase
    ),
    default: (
        font-family:        myFontFamilyName,
        text-transform:     capitalize,
        font-size:          my-font-size(small) // Example with a Matryoshka function
    )
);

// Call typography with its mixin
@include my-typography(caps)
// Renders
// font-family: myFontFamilyName, sans-serif;
// text-transform: uppercase;

// Call typography with its mixin
@include my-typography(default)
// Renders
// font-family: myFontFamilyName, sans-serif;
// text-transform: capitalize;
// font-size: 16px; // Assuming 'small' is a font size 16 with $ds-unit = px

Spacings

$ds-spacings

For design consistency, Matryoshka uses a list of spacings that can be used for any purpose like margins and paddings.

• SASS variable type: SASS map
• Enter any name as spacing name
• Enter an integer as value without unit

$ds-spacings: (
    none:   0,
    md:     25,
    xxl:    128
);

You get these utilities classes

Assuming we have the following screen sizes

// Other custom example
$ds-screen-sizes: (
    mini:   400,
    medium: 808,
    large:  1024,
    wide:   infinite
);

Borders

$ds-borders

A list of borders shorthands.

• SASS variable type: SASS map
• Enter any name as border name
• Enter a valid CSS border shorthand as value. For consistency purpose, it is recommended to use Matryoshka functions for values when applicable:
  • For colors my-spacing(spacingName)
  • For border width my-color(nameOfTheColor[, optional contrastName])

// Example
$ds-borders: (
    main: my-spacing(ultraMini) solid my-color(brand), // With Matryoshka functions
    light: 1px solid #123456 // With custom values
);

Border radius

$ds-border-radius

A simple list of border radius.

• SASS variable type: SASS map
• Enter any name as border radius name
• Enter an integer as value

// Example
$ds-border-radius: (
    none:   0,
    small:  4,
    large:  9
);

Utilities

Utilities are atoms that overrides components and modifiers CSS with conventional naming as follows.

u- means utility that returns CSS values always with the important rule !important

<div class="u-c-myColorName"></div>
// Renders for example color: #123456 !important

Global utilities

Responsive utilities

For responsiveness, text alignment and spacings utilities classes are available

Alternate responsive utilities with HTML attributes

This method is similar to standard CSS classes utilities but comes with extended feature: Multiple screen size selection.

HTML attribute

u-m-spacingName="screenName1, screenName2, screenName3"

is similar to

class="u-m-spacingName-screenName1 u-m-spacingName-screenName2 u-m-spacingName-screenName3"