m5-docs/docs

M5Stack Documents

Style once, use everywhere.

A M5Stack Documentation is a system that allows you to define styles once, in a way for any platform or language to consume. A single place to create and edit your styles, and a single command exports these rules to all the places you need them - iOS, Android, CSS, JS, HTML, sketch files, style documentation, etc. It is available as a CLI through npm, but can also be used like any normal node module if you want to extend its functionality.

When you are managing user experiences, it can be quite challenging to keep styles consistent and synchronized across multiple development platforms and devices. At the same time, designers, developers, PMs and others must be able to have consistent and up-to-date style documentation to enable effective work and communication. Even then, mistakes inevitably happen and the design may not be implemented accurately. StyleDictionary solves this by automatically generating style definitions across all platforms from a single source - removing roadblocks, errors, and inefficiencies across your workflow.

Watch the Demo on Youtube

The basics

A M5Stack Documents consists of:

1. Style properties organized in JSON files
2. Static assets that can be used across platforms

What a M5Stack Documents does:

1. Allows the style properties and assets to be consumed in any platform or language

Let's take a look at a very basic example.

{
  "size": {
    "font": {
      "small" : { "value": "10px" },
      "medium": { "value": "16px" },
      "large" : { "value": "24px" },
      "base"  : { "value": "{size.font.medium.value}" }
    }
  }
}

Here we are creating some basic font size properties. The style property size.font.small is "10px" for example. The style definition size.font.base.value is automatically aliased to the value found in size.font.medium.value, so both of those resolve to "16px".

Now what the M5Stack Documents build system will do with this information is convert it to different formats so that you can use these values in any type of codebase. From this one file you can generate any number of files like:

$size-font-small: 10px;
$size-font-medium: 16px;
$size-font-large: 24px;
$size-font-base: 16px;

<dimen name="font-small">10sp</dimen>
<dimen name="font-medium">16sp</dimen>
<dimen name="font-large">24sp</dimen>
<dimen name="font-base">16sp</dimen>

float const SizeFontSmall = 10.00f;
float const SizeFontMedium = 16.00f;
float const SizeFontLarge = 24.00f;
float const SizeFontBase = 16.00f;

This is a very simple example, take a deeper dive into the M5Stack Documents framework in

The M5Stack Documents framework is completely extensible and modular so you can create any type of file from a M5Stack Documents. If there is a new language, platform, file type, you can extend the M5Stack Documents framework to create the files you need.

Some other things you can build with a M5Stack Documents

1. Images and graphics
2. Sketch files
3. Documentation site
4. Literally anything

Style Properties

Synonyms: design token, design variable, design constant, atom

A style property is a key/value data to describe any fundamental/atomic visual properties. This information is stored in a canonical source, the M5Stack Documents, and transformed for use in different platforms, languages, and contexts. A simple example is a color. A color can be represented in many ways, all of these are the same color: #ffffff, rgb(255,255,255), hsl(0,0,1).

A M5Stack Documents organizes style properties in a structured way for easy access. Style properties are organized as a deep object with the leaf nodes being the style properties.

{
  "color": {
    "font": {
      "base": { "value": "#111111" },
      "secondary": { "value": "#333333" },
      "tertiary": { "value": "#666666" },
      "inverse": {
        "base": { "value": "#ffffff" }
      }
    }
  }
}

In this example there are 4 style properties: color.font.base, color.font.secondary, color.font.tertiary, and color.font.inverse.base. A style property is any object in the JSON that has a value attribute on it. In this way you can nest properties at different levels. This allows you to easily access the property as well as do things like get all the inverse font colors.

Contributing

Please help make this framework better. For more information take a look at CONTRIBUTING.md

License

Apache 2.0