Theme Variable Documentation - HL Vanilla Community
<main> <article class="userContent"> <p>Documentation is generated by using either the <code class="code codeInline" spellcheck="false" tabindex="0">yarn build:variable-docs</code> or the <code class="code codeInline" spellcheck="false" tabindex="0">yarn build</code> command.</p><p>Output is in <code class="code codeInline" spellcheck="false" tabindex="0">/dist/variable-schema.json</code> and is a JSON schema for a flat variable structure.</p><h2 data-id="usage">Usage</h2><p>Documentation lives inline in the code as docblocks around the variables. Technically the docblocks could be anywhere in any styles file (file matching in <code class="code codeInline" spellcheck="false" tabindex="0">(S|s)tyles.ts(x)?</code>) and it will be picked up. Generally you colocate the docblocks with the variables they describe.</p><h2 data-id="%40var"><code class="code codeInline" spellcheck="false" tabindex="0">@var</code></h2><p>An <code class="code codeInline" spellcheck="false" tabindex="0">@var</code> annotation describes a single variable.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">/** * @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 */ </pre><p>Let's break this down.</p><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">@var myComponent.title.size- </code>Give the full dot notation path to the variable. This is the same way these are referenced in the theme editor. <em>This is required and must be first.</em></li><li><code class="code codeInline" spellcheck="false" tabindex="0">@title</code>Specify a short title for the variable.<em>Optional with default.</em> If omitted the last portion of the variable key will be converted into its name. For example <code class="code codeInline" spellcheck="false" tabindex="0">myComponent.title.size</code> will become <code class="code codeInline" spellcheck="false" tabindex="0">"Size".</code></li><li><code class="code codeInline" spellcheck="false" tabindex="0">@description</code>Provide 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</li><li><code class="code codeInline" spellcheck="false" tabindex="0">@type</code>Give a JSON schema type for the variable. One or more of <code class="code codeInline" spellcheck="false" tabindex="0">string</code>, <code class="code codeInline" spellcheck="false" tabindex="0">boolean</code>, <code class="code codeInline" spellcheck="false" tabindex="0">integer</code>, <code class="code codeInline" spellcheck="false" tabindex="0">null</code>, <code class="code codeInline" spellcheck="false" tabindex="0">number</code>, <code class="code codeInline" spellcheck="false" tabindex="0">array</code>, <code class="code codeInline" spellcheck="false" tabindex="0">object</code>. If it can be multiple types, represent it with a union operator. Eg. <code class="code codeInline" spellcheck="false" tabindex="0">string|integer</code>Required</li><li><code class="code codeInline" spellcheck="false" tabindex="0">@enum</code>Optional extension for string types. An array of possible strings the value could be.Optional</li><li><code class="code codeInline" spellcheck="false" tabindex="0">@format hex-color</code>Specify for color valuesOptional</li></ul><h2 data-id="%40vargroup"><code class="code codeInline" spellcheck="false" tabindex="0">@varGroup</code></h2><p>Variable groups can help reduce the boilerplate when describing variables by giving common titles and descriptions.</p><pre class="code codeBlock" spellcheck="false" tabindex="0">/** * @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 */ </pre><ul><li><a href="https://github.com/VarGroup?type=source" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">@VarGroup</code></a> - The dot notation key of the varGroup. This is used to match to variablesRequired</li><li><code class="code codeInline" spellcheck="false" tabindex="0">@commonTitle</code> - A common title that will prefix any associated <a href="https://github.com/var" rel="nofollow noreferrer ugc">@var</a> titles.Optional</li><li><code class="code codeInline" spellcheck="false" tabindex="0">@commonDescription</code> - A common description that will suffix and associated <a href="https://github.com/var" rel="nofollow noreferrer ugc">@var</a> descriptions. Optional</li><li><a href="https://github.com/expand" rel="nofollow noreferrer ugc"><code class="code codeInline" spellcheck="false" tabindex="0">@expand</code></a> - Used to automatically created multiple child <a href="https://github.com/var" rel="nofollow noreferrer ugc">@var</a> declarations. Optional</li></ul><h4 data-id="rules-of-%40vargroup-associations">Rules of <code class="code codeInline" spellcheck="false" tabindex="0">@varGroup</code> associations</h4><ul><li>An <code class="code codeInline" spellcheck="false" tabindex="0">@var</code> searches for a varGroup by dropping of parts of it's key. So <code class="code codeInline" spellcheck="false" tabindex="0">@var myComponent.title.size</code> will check for varGroups in the following order. <code class="code codeInline" spellcheck="false" tabindex="0">myComponent.title</code> -> <code class="code codeInline" spellcheck="false" tabindex="0">myComponent</code>.</li><li>An <code class="code codeInline" spellcheck="false" tabindex="0">@varGroup</code> must be declared <em>before</em> an associated <code class="code codeInline" spellcheck="false" tabindex="0">@var</code>.</li></ul><h2 data-id="expansions">Expansions</h2><p>VarGroup expands are used to easily describe common "buckets" of variables. Each expand has an associated static method on the <code class="code codeInline" spellcheck="false" tabindex="0">Variables</code> class that will declare the variables in styles as well and an associated mixin to apply all of the variables.</p><h3 data-id="font"><code class="code codeInline" spellcheck="false" tabindex="0">font</code></h3><p>Declare common font properties <code class="code codeInline" spellcheck="false" tabindex="0">size</code>, <code class="code codeInline" spellcheck="false" tabindex="0">color</code>, <code class="code codeInline" spellcheck="false" tabindex="0">weight</code>, <code class="code codeInline" spellcheck="false" tabindex="0">lineHeight</code>, <code class="code codeInline" spellcheck="false" tabindex="0">shadow</code>, <code class="code codeInline" spellcheck="false" tabindex="0">align</code>, <code class="code codeInline" spellcheck="false" tabindex="0">family</code>, <code class="code codeInline" spellcheck="false" tabindex="0">transform</code>, <code class="code codeInline" spellcheck="false" tabindex="0">letterSpacing</code></p><p><strong>Variable Declaration </strong>- <code class="code codeInline" spellcheck="false" tabindex="0">Variables.font()</code>.</p><p><strong>Mixins</strong> - <code class="code codeInline" spellcheck="false" tabindex="0">Mixins.font()</code></p><h3 data-id="spacing"><code class="code codeInline" spellcheck="false" tabindex="0">spacing</code></h3><p>Declare common spacing properties for paddings or margins. <code class="code codeInline" spellcheck="false" tabindex="0">top</code>, <code class="code codeInline" spellcheck="false" tabindex="0">right</code>, <code class="code codeInline" spellcheck="false" tabindex="0">left</code>, <code class="code codeInline" spellcheck="false" tabindex="0">bottom</code>, <code class="code codeInline" spellcheck="false" tabindex="0">vertical</code>, <code class="code codeInline" spellcheck="false" tabindex="0">horizontal</code>, <code class="code codeInline" spellcheck="false" tabindex="0">all</code>.</p><p><strong>Variable Declaration - </strong><code class="code codeInline" spellcheck="false" tabindex="0">Variables.spacing()</code></p><p><strong>Mixins - </strong><code class="code codeInline" spellcheck="false" tabindex="0">Mixins.padding()</code>, <code class="code codeInline" spellcheck="false" tabindex="0">Mixins.margin()</code></p><h3 data-id="background"><code class="code codeInline" spellcheck="false" tabindex="0">background</code></h3><p>Declare common background properties. <code class="code codeInline" spellcheck="false" tabindex="0">color</code>, <code class="code codeInline" spellcheck="false" tabindex="0">attachment</code>, <code class="code codeInline" spellcheck="false" tabindex="0">position</code>, <code class="code codeInline" spellcheck="false" tabindex="0">repeat</code>, <code class="code codeInline" spellcheck="false" tabindex="0">size</code>, <code class="code codeInline" spellcheck="false" tabindex="0">image</code>, <code class="code codeInline" spellcheck="false" tabindex="0">opacity.</code></p><p><strong>Variable Declaration -</strong> <code class="code codeInline" spellcheck="false" tabindex="0">Variables.background()</code>.</p><p><strong>Mixin</strong> - <code class="code codeInline" spellcheck="false" tabindex="0">Mixins.background()</code> .</p><h3 data-id="border"><code class="code codeInline" spellcheck="false" tabindex="0">border</code></h3><p>Declare common border properties. <code class="code codeInline" spellcheck="false" tabindex="0">color</code>, <code class="code codeInline" spellcheck="false" tabindex="0">width</code>, <code class="code codeInline" spellcheck="false" tabindex="0">style</code>, <code class="code codeInline" spellcheck="false" tabindex="0">radius</code>.</p><p><strong>Variable Declaration </strong>- <code class="code codeInline" spellcheck="false" tabindex="0">Variables.border()</code>.</p><p><strong>Mixin</strong> - <code class="code codeInline" spellcheck="false" tabindex="0">Mixins.border()</code></p> </article> </main>