1.md

Styleverse mini-doc:

Styleverse is a system to generate, harmonize and assign gss-specific styles on GOM elements. It resembles JSON and CSS at the same time.

Terms

• Styleverse loads multiple sheets
• finds element by kind (like tag in HTML)
• and filters them by index (like class in HTML)
• to match against rules
• to assign properties and values

Lifecycle

• Page GOM is built with empty sheet tags in stacks and layouts
• Page is wrapped into virtual document element, which triggers styleverse pass
• Styleverse matches sheet against GOM to remove rules that dont match anything
• Styleverse sorts conflicting values by specificity of their rules
• Styleverse collapses styles merging all inherited and default values into individual rules
• Multiverse computes solution and collapses object further removing Y_ branches
• Styleverse serializes GSS stylesheets and inserts them into empty sheets

Rules

Styles applied with rules, similar to CSS. Kinds (like HTML tags) are predefined in gss folder which has following structure:

- aside         // tag
 |- font-size   // property
 | |- large.gss // value

Rules can be applied to kinds, or combinations of kind and index. In case of conflicts, deeper rules rules overcome more shallow ones.

aside:                 // depth: 1
  font_size: 'big'     // value for all aside elements

  attribution          // depth: 2, more important
    font_size: 'small' // value for aside with index attribution.

Unlike in CSS, rules only match direct children:

  decoration:          // does not match decorations within group
    size: 'small'

  group:
    decoration:        // only matches decorations directly nested into a group
      size: 'big'

Branching:

Multiverse branches are defined with key starting with Y_. Each property in the object by that key becomes a named branch. Styleverse adds $class directive to each branch internally. It adds class to the rendered element with the name of the branch. It allows multiverse to apply harmonies, to choose the best fitting branch.

group:
  Y_my_unique_name:    // define two named branches
    small:             // adds $class: small
      font-size: 'small'
    big:
      font-size: 'big'

Usually, values coming from branches overwrite regular values unconditionally, except one specific case: kind specific values defined in branch are shadowed by index specific values outside.

group:
  my-repost:           //two index-specific rules
    h_align: 'left'
    v_align: 'top'

Y_align:
  left:
    group: 
      v_align: 'bottom'  // will NOT overwrite
      my-repost:
        h_align: 'right' // will overwrite

This is useful to create branched mass effects (e.g. content alignment) leaving ability to overcome those effects.

Serialization:

Once multiverse computes the styles, styleverse serializes results into GSS source. If kind-property-value triplet matches a file in gss folder, rule will have an @import call pointing to that file. It executes gss file in the scope of element matching the rule.

If a value of a property looks like a number with optional unit, styleverse will generate variable assignment. It is a primary way to pass numerical values to the system.

It's possible to define custom properties that will do custom GSS serialization logic, like we do with h-attach/v-attach properties. VFLs are defined in a similar way, as serializing macros through h-vfl/v-vfl properties.

Reference:

Styleverse operates on design systems which have similar structure.

Layout:

High-level wrappers that define column composition and available whitespace.

Options:

• h-gutter: Total gutter space per column
• v-gutter-min: Minimal vertical gap between items
• v-gutter-max: Maximum vertical gap between items

Properties:

• columns (property): Defines number of columns

  • one (default): Single column layout with gaps on the sides

  • two: Two column layout with gaps on the sides and in the middle

• sizing (property): Computes available space

  • container (default): container

• v-align (property): Defines vertical of alignments in row in 2 column layouts

  • top: Align top edges of elements in a row
  • bottom: Align bottom edges of elements in a row
  • center: Center elements vertically in a row
  • bricks: Each element aligned to center of previous element

• v-align-first (property): Defines vertical of alignment of first 2 items in 2 column layouts

  • top: Align top edges of elements in first row
  • bottom: Align bottom edges of elements in first row
  • center: Center elements vertically in first row
  • bricks: Each element aligned to center of previous element

• v-align-last (property): Defines vertical of alignment of last 2 items in 2 column layouts

  • top: Align top edges of elements in last row
  • bottom: Align bottom edges of elements in last row
  • center: Center elements vertically in last row
  • bricks: Each element aligned to center of previous element

• h-distribute (property): How horizontal gutter should be distributed across columns?

  • center (default): Center stacks within columns
  • equal (todo): Equal gaps on the sides and in the middle

Stack:

One dimensional collection of groups.

Options:

• inner-gap-horizontal: Minimal total horizontal padding of stack
• inner-gap-vertical: Minimal total vertical padding of stack
• inner-gap: Padding between groups

Properties:

• direction (property): Defines orientation of group flow

  • vertical (default): Groups stack on on top of another
  • horizontal: Groups stack side to side

• h-distribute (property): How total horizontal gap should be divided between left & right sides?

  • center (default): Equalize left & right minimum gaps
  • left: Only add minimal-gap on the left
  • right: Only add minimal-gap on the right

• v-distribute (property): How total vertical gap should be divided between top & bottom sides?

  • center (default): Equalize top & bottom minimum gaps
  • top: Only add minimal-gap on top
  • bottom: Only add minimal-gap on bottom

• v-align (property): How should groups be aligned vertically?

  • center (default): Equalize gaps between edges of stack and first/last group
  • top: Align top edges of groups
  • bottom: Align bottom edges of groups

• h-align (property): How should groups be aligned horizontally?

  • center (default): Equalize gaps between edges of stack and first/last group
  • top: Align top edges of groups
  • bottom: Align bottom edges of groups

Group:

Smallest content groupping (e.g. title + description).

Options:

• inner-gap-horizontal: Minimal total horizontal padding of group
• inner-gap-vertical: Minimal total vertical padding of group
• inner-gap: Padding between elements
• outer-gap-horizontal: Reduce available width by given amount

Properties:

• font-size (property): Choice of typography size

  • small (default): Choose a small font size
  • large: Choose a medium font size
  • medium: Choose a large font size

• h-sqeueze (property): Which way should outer-gap-horizontal push group?

  • center (default): Keep group centered
  • left: Move group to the left
  • right: Move group to the right

• h-distribute (property): How total horizontal gap should be divided between left & right sides?

  • center (default): Equalize left & right minimum gaps
  • left: Only add minimal-gap on the left
  • right: Only add minimal-gap on the right

• v-distribute (property): How total vertical gap should be divided between top & bottom sides?

  • center (default): Equalize top & bottom minimum gaps
  • top: Only add minimal-gap on top
  • bottom: Only add minimal-gap on bottom

• v-align (property): How should groups be aligned vertically?

  • center (default): Equalize gaps between edges of group and first/last element
  • top: Align top edges of groups
  • bottom: Align bottom edges of groups

• h-align (property): How should groups be aligned horizontally?

  • center (default): Equalize gaps between edges of group and first/last element
  • top: Align top edges of groups
  • bottom: Align bottom edges of groups