Docs: Custom units

[Pistus]

Made another educated guess start of documenting custom units. Would be great to know if this is anywhere close @somebee 🔍 The example can be made simpler, but not sure what the best selling points of custom units are yet.

Custom Units

You can define your own custom numerical unit that can be used for styling and calculations. You define a custom unit by using a css property starting with a number (measure) and then the unit name. For example 1t: . The unit can have modifiers like break points and you can use the units in the same way as native numerical units like px and em.

Here is an example defining t and w as units:

tag base-dialog
    css
        1t:5vmin @md:200px @lg:10% # define t to different variable sizes depending on the width of the screen
        1w:340px # define the w unit as a fixed size
        max-width:2w # basic use of custom unit
        max-height: calc(100vh - 1t) # calculate with custom unit
        position:absolute top:1t left:calc(50% - 0.5w) # Using fraction of units

tag larger-dialog < base-dialog
    css
        1t:10vmin @md:400px @lg:20% # re-defining the `t` unit - all inherited styles will use the new value
        1w:400px
        # will inherit max-width, max-height, top and left properties with overwritten w and t values. 
        # max-width: 2w => 2 * 400px => 800px
        # max-height: calc(100vh - (10vmin @md:400px @lg:20%))
        # position:absolute top:(10vmin @md:400px @lg:20%) left:calc(50% - 0.5 * 400px) # Using fraction of units

[Pistus]

Part of of #163

[ericvida]

People often use a css variable to store a custom unit, and then multiply from it to have units relative to that like this: padding: $global-padding * 2 instead of that, you just make your own custom unit like 1gp:0.2em and just double it as 2gp. I believe that's the selling point or idea behind why @somebee made custom units if I remember correctly.

[Pistus]

Thanks @ericvida - I pushed a first draft based on your feedback.

Custom Units

You can define your own unit that can be used for styling and calculations. The unit can have modifiers like break points and you can use the units in the same way as other css units. The syntax to define a custom unit is <measure><name>: <value> e.g. 1col: calc(100vw / 12).

global css @root
    1pad: 25px
    1col: calc(100vw / 12)

tag app-dialog
    css 
        width: 12col @md: 6col lg: 3col
        p: 1pad

[ericvida]

@Pistus this is a great example. Very smart use of custom units. The only thing is that when I use 1col it doesn't work for me. If I use 1column it works. Not sure if there's some conflict going on.