Documentation is generated by using either the yarn build:variable-docs or the yarn build command.
Output is in /dist/variable-schema.json and is a JSON schema for a flat variable structure.
Usage
Documentation lives inline in the code as docblocks around the variables. Technically the docblocks could be anywhere in any styles file (file matching in (S|s)tyles.ts(x)?) and it will be picked up. Generally you colocate the docblocks with the variables they describe.
@var
An @var annotation describes a single variable.
/**
* @var myComponent.title.size
* @title MyComponent - Title - Size
* @description Specify a size for the title.
* Note, large sizes display as medium on mobile devices.
* @type string
* @enum large | medium | small
*/
Let's break this down.
@var myComponent.title.size- Give the full dot notation path to the variable. This is the same way these are referenced in the theme editor. This is required and must be first.@titleSpecify a short title for the variable.Optional with default. If omitted the last portion of the variable key will be converted into its name. For example myComponent.title.size will become "Size".@descriptionProvide an optional description for the variable. These should almost always be specified unless it is blatantly obvious what the variable is. Remember, people consuming the documentation may not have any idea how the system works internally or have any knowledge of vanilla internals. Please note, descriptions can be multiple lines, and contain markdown formatting. Optional, but highly recommende@typeGive a JSON schema type for the variable. One or more of string, boolean, integer, null, number, array, object. If it can be multiple types, represent it with a union operator. Eg. string|integerRequired@enumOptional extension for string types. An array of possible strings the value could be.Optional@format hex-colorSpecify for color valuesOptional
@varGroup
Variable groups can help reduce the boilerplate when describing variables by giving common titles and descriptions.
/**
* @varGroup myComponent
* @commonTitle My Component
*/
/**
* @varGroup myComponent.title
* @commonTitle My Component - Title
* @commonDescription The title will not appear unless `myComponent.title.enabled` is set to `true`
*/
/**
* @varGroup myComponent.title.font
* @commonTitle MyComponent - Title - Font
* @expand font
*/
@VarGroup - The dot notation key of the varGroup. This is used to match to variablesRequired@commonTitle - A common title that will prefix any associated @var titles.Optional@commonDescription - A common description that will suffix and associated @var descriptions. Optional@expand - Used to automatically created multiple child @var declarations. Optional
Rules of @varGroup associations
- An
@var searches for a varGroup by dropping of parts of it's key. So @var myComponent.title.size will check for varGroups in the following order. myComponent.title -> myComponent. - An
@varGroup must be declared before an associated @var.
Expansions
VarGroup expands are used to easily describe common "buckets" of variables. Each expand has an associated static method on the Variables class that will declare the variables in styles as well and an associated mixin to apply all of the variables.
font
Declare common font properties size, color, weight, lineHeight, shadow, align, family, transform, letterSpacing
Variable Declaration - Variables.font().
Mixins - Mixins.font()
spacing
Declare common spacing properties for paddings or margins. top, right, left, bottom, vertical, horizontal, all.
Variable Declaration - Variables.spacing()
Mixins - Mixins.padding(), Mixins.margin()
background
Declare common background properties. color, attachment, position, repeat, size, image, opacity.
Variable Declaration - Variables.background().
Mixin - Mixins.background() .
border
Declare common border properties. color, width, style, radius.
Variable Declaration - Variables.border().
Mixin - Mixins.border()