augmented-ui v2 documentation

The Pitch and an Introduction

Traditional Sci-Fi web design is tedious and difficult to scale, requiring extra elements or images for each clip, all rotated and carefully positioned to cover corners, often required to match against solid color backgrounds and solid color borders to stay hidden. augmented-ui removes all these limitations. No scripts to install, no extra elements to rotate, no images, and no need to redo everything if the size, content, or context changes. You can even use multiple gradients and gifs in the borders and backgrounds if you wanted to. All this with a handful of custom CSS properties. (+ ~93% global compatibility!)

Version 2 is a complete rewrite, built on (and because of) the discovery of the CSS Space Toggle trick.
As a result, augmented-ui v2 doesn't just augment your element, now it augments CSS itself.

Like standard CSS properties, the core of augmented-ui expands your design options with over 150 --custom-properties. Accessing these core properties just requires adding the data-augmented-ui attribute to your element:
<div data-augmented-ui></div>
It may appear to do nothing on its own but now you can use --css-variable toggles to shape your element in over 250,000 unique ways, then use --css-variable properties to customize the size and alignment of every bend in an infinite number of ways, and use --even-more-options for an augmented inlay and augmented border that follow the shape and can be painted with the full power of the multi-layered CSS <background> value type!

augmented-ui's simplicity in previous versions could be credited to how the augs (individual shapes assigned to positions along the perimeter) were applied just by putting their name in the element attribute's value:
<div data-augmented-ui="tl-clip br-clip both"></div>
This OOCSS-like pattern has returned as a separate layer of mixins.

Mixins are the fastest way to get started, especially for anyone already familiar with augmented-ui. They are essentially a higher-level api that set the low-level core toggles (and some properties) for you. Since there are a handful of technical nuances in core to be aware of, and since Space Toggle is a new technique, using the mixin layer lets you completely avoid both of these concerns until you're interested in diving deeper!

Example of the mixin approach with some customization:


  .pitch-mixin {
    --aug-tr: 25px;
    --aug-b-extend1: 50%;

    --aug-border-all: 7px;
    --aug-border-bg: radial-gradient(
      at top, gold 25%, transparent 50%),
      url("/img/what_a_save.gif") 50% 50% / 100% 100%;

    --aug-inlay-all: 4px;
    --aug-inlay-bg: radial-gradient(gold, black);
    --aug-inlay-opacity: 0.5;
  }

Same example using the core approach with an additional :hover state defined in the CSS itself - a feature that would require JS if you were using mixins. (note: using core directly also helps keep your design decisions primarily in the CSS!)


  .pitch-core {
    --aug-border: initial;
    --aug-border-all: 7px;
    --aug-border-bg: radial-gradient(
      at top, gold 25%, transparent 50%),
      url("/img/what_a_save.gif")
      50% 50% / 100% 100%;

    --aug-inlay: initial;
    --aug-inlay-all: 4px;
    --aug-inlay-bg: radial-gradient(
      at center center, gold, black);
    --aug-inlay-opacity: 0.5;

    --aug-clip-b1: initial;
    --aug-clip-b2: initial;
    --aug-b-extend1: 50%;
  }


  .pitch-core:not(:hover) {
    --aug-clip-tl1: initial;
    --aug-tl-inset1: 30px;
    --aug-tl1-alt-join-in: initial;

    --aug-scoop-tr1: initial;
    --aug-tr1: 25px;
  }
  .pitch-core:hover {
    --aug-clip-t1: initial;
    --aug-clip-t2: initial;
    --aug-clip-r1: initial;
    --aug-clip-r2: initial;
    --aug-clip-l1: initial;
    --aug-clip-l2: initial;
    --aug-t-extend1: 50%;
    --aug-r-extend1: 50%;
    --aug-l-extend1: 50%;
  }

Since core can change augs based on any CSS selector logic now, there's no more need for js libraries packed with more edge cases than use cases like aug-attr-spliced.js! Hooray!

Thank you for checking out augmented-ui!

Browser Support

92.96% Global User Support
(according to browser usage percentages from caniuse.com in mid August 2020)

Browser	IE	Edge	Firefox	Chrome	Safari	Opera	iOS Safari	Opera Mini	Android Browser	Opera Mobile	Chrome for Android	Firefox for Android	UC Browser	Samsung Internet
Unsupported	1.65%	0.91%	0.36%	0.55%	0.16%	0.24%	0.56%	0.91%	0.17%	0.00%			0.00%	0.30%
Supported Since Version		79+	54+	51+	9.1+	38+	11.2+		81+	46+	84	68	12+	5+
Supported Global Usage		1.89%	3.70%	30.66%	3.70%	1.07%	11.20%		0.00%	0.01%	35.38%	0.26%	1.47%	3.62%

augmented-ui v2 has no built in fallbacks (except for -webkit-clip-path support). If you need to support older browsers, you can use this CSS @supports statement to overwrite your site's older styles for browsers that support augmented-ui. @supports (--foo: , 0 0) and ((clip-path: polygon(0 0, 100% 0, 50% 50%)) or (-webkit-clip-path: polygon(0 0, 100% 0, 50% 50%))) { /* augmented-ui styles here */ }
The most important design/styling considerations you should be aware of when also supporting older browsers are:

If you use an augmented inlay as a background, be mindful of text readability when augmented-ui is unsupported.
If you put text behind an augmented element, it may be obstructed when augmented-ui isn't available since the element won't be clipped.
augmented elements create their own stacking context so you may need to force the new stacking context manually in old browsers if you run into z-index differences in your designs.

Installing augmented-ui

Install with NPM:
$ npm install augmented-ui
Then include the /node_modules/augmented-ui/augmented-ui.min.css file once, before any stylesheets that use it.

OR

Use your favorite NPM CDN and include it on your page before other stylesheets for small projects. Like so:
<link rel="stylesheet" type="text/css" href="https://unpkg.com/augmented-ui@2/augmented-ui.min.css">

Note: Many CSS linters and minifiers, including the most popular today, have parsing bugs that will block your project build, produce invalid CSS when minifying, or incorrectly call parts of augmented-ui's CSS a syntax error. If your project is built with Create React App, for example, you'll need to copy the augmented-ui CSS file into your app's public folder and manually include it in the index.html file to avoid the automatic minification. Read more here: Ecosystem Compatibility

augmented-ui namespacing

Every user-facing css variable is prefixed with --aug- so it doesn't step on the toes of other libraries you may be using.
Every internal css variable starts with --aug_ for a similar reason. (These should not be overwritten directly.)

There is 1 primary html attribute: data-augmented-ui
plus 3 lesser used html attributes: data-augmented-ui-reset, data-augmented-ui-border, data-augmented-ui-inlay

The value for data-augmented-ui is where all mixins are added (if you use them). Its individual mixin names are not namespaced since they only appear inside this specific attribute's value.

There are no reserved class names, ids, or elements.

Selector Specificity

Since augmented-ui uses attribute selectors for everything, you'll need to use at least a class selector in weight to override the built in defaults:

div { --aug-t: 50px; } uses a type selector and will NOT override the defaults, but .divclass { --aug-t: 50px; } would.

See CSS Selector Specificity on MDN for more information.

Nesting augmented elements

You can nest augmented elements but it usually* requires a reset layer in between
[data-augmented-ui] [data-augmented-ui-reset] [data-augmented-ui]

<div data-augmented-ui> Augmented Parent Container <ul data-augmented-ui-reset>  <li data-augmented-ui> Augmented descendant with unique configuration </li> <li data-augmented-ui> Augmented descendant with unique configuration </li> </ul> </div>

The CSS Spec is in progress of changing to remove this newly adopted necessity and make the previous 4 years of behavior the new spec.

* There is an edge case where you may not need the reset layer if the augmented children use a subset of the augs (or all the same augs), in the same positions, as the augmented ancestor. It is still recommended to use the reset layer for consistency though, at least until the spec changes.

☢
✋
⛉
⚑

For example, this figure is an augmented <ul> with augmented <li> direct descendants. Both the parent and child use clip augs in tl1, tr1, br1, and bl1 positions without the children using additional augs that the parent didn't, so the edge case is satisfied.

Technical nuance: This edge case result is the same in either Invalid-at-Computed-Value-Time implementation because both the parent and child would resolve specific internal variables of augmented-ui (since they're derived from the same toggles being flipped to `initial`) to the same simple values (like '0px' or ' '), AND they don't do further computation themselves. Therefore when the child inherits the parent's resolved value, it's the same answer the child would have resolved to (more efficiently) if the previous 4 years of browser behavior was still implemented. A rep from W3C and from Mozilla agree with updating the spec and reverting the change, Safari is open to the change as well, a Chromium member is holding it up for not-so-altruistic reasons though since they made the call to change it a few months ago without realizing or measuring the damage it could cause. People are complex though, so please do not add negativity to the discussion even though it's a bit frustrating. When your position's autonomy and authority imply you have to make the right decisions robotically, any indication that you didn't would cause most people anxiety. Beyond that, these things are questioned in public forum, which would cause anyone even more anxiety when requesting you change your decisions - almost worse when there's a pile of evidence showing it was a bad call. It's not an easy position to be in, everyone reacts differently, so please allow it to play out, and please keep any support for the change positive without dogpiling. I'm sure it'll land where it needs to, even if it's delayed unnecessarily for now.

augmented border and inlay

A border in augmented-ui is the ::after pseudo element with a background applied, clipped to remove the center. A border may be delegated to a child element instead, allowing it to be painted with anything you can render in dom. The border's background is only applied when CSS feature detection knows the center can be clipped away to avoid obstructing visibility of content in older browsers.

border

inlay

An inlay in augmented-ui is the ::before pseudo element with a background applied, clipped a distance from the border or outer edge. An inlay may be delegated to a child element instead, allowing it to be anything you can render in dom.

Both the border and inlay follow a degradation of the equipped aug path to maintain a constant distance from the outer shape.

Adding a Border or Inlay

Using MixinsUsing core toggles in CSS Add border<div data-augmented-ui="border">--aug-border: initial; Add inlay<div data-augmented-ui="inlay">--aug-inlay: initial; Shorthand to add both<div data-augmented-ui="both"> Enable delegated border<div data-augmented-ui="delegated-border">


            --aug-border: initial;

            --aug-delegated-border: initial;

Enable delegated inlay<div data-augmented-ui="delegated-inlay">


            --aug-inlay: initial;

            --aug-delegated-inlay: initial;

Deus Ex: Alien Intervention
The trillogy concludes Aug 2021.

Using Border/Inlay Delegates

Designate delegate border<div data-augmented-ui-border>

Any element, with any content, can be used as the delegate border if the parent enables it. All augs and settings are determined by properties of the parent.

Designate delegate inlay<div data-augmented-ui-inlay>

Any element, with any content, can be used as the delegate inlay if the parent enables it. All augs and settings are determined by properties of the parent.