augmented-ui from PropJockey

Home: http://augmented-ui.com/

Docs: http://augmented-ui.com/docs/

Informal/Visual Tests: http://augmented-ui.com/test.html

NPM: https://www.npmjs.com/package/augmented-ui

GitHub: https://github.com/propjockey/augmented-ui

Install: $ npm install augmented-ui Then include the /node_modules/augmented-ui/augmented.css file 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/augmented.css">

data-augmented.css

You may, optionally, use data-augmented.css instead of augmented.css if you prefer to stick to standard markup. They are not interchangeable, please only use one or the other. The API is exactly the same, just instead of the augmented-ui="tl-clip exe" attributes, you'll use data-augmented-ui="tl-clip exe" instead. data-augmented.css is currently incompatible with aug-attr-spliced.js

Support

Sponsors

Become a sponsor and get your logo on this README with a link to your site. [Become a sponsor]

Backers

Help the developer follow his excitement and support augmented-ui with a monthly donation. [Become a backer]

CHANGELOG:

v1.1.2 - March 5th, 2020:

• Added data-augmented.css option for data- prefixed augmented-ui attribute.
• Added compatibility notes for specific frameworks/libraries at the bottom of this README

v1.1.0 - September 9th, 2019:

• Increased full support global user reach from ~70% to ~91% with -webkit-clip-path
• Bought an old iPhone to isolate and feature detect the iOS issue found before launch, enabling -webkit-clip-path to be used everywhere else
• Better docs: http://augmented-ui.com/docs/

v1.0.0 - August 31st, 2019:

• Initial release
• -webkit-clip-path support removed before release due to breaking issues on older iOS versions used by ~2% of global users

Cross Compatibility

augmented-ui relies on dynamic and optional composition of standard comma-separated CSS properties. This requires a leading comma in a custom property + an empty fallback in var(). Here is a minimal example of how that works: https://jsbin.com/cemujarozo/1/edit?html,css,output

A common problem in CSS parsers is to erroneously give meaning to commas in custom properties, and then complain about having a leading comma. Even old versions of safari on iOS ran into this issue and they have since fixed it. Fortunately it can be safely feature detected to avoid problems in those versions of iOS: @supports (--foo: , 0 0)

Compatibility with Create React App

Create React App depends on PostCSS and cssnano. Both of these libraries have parsing bugs that block augmented-ui so you'll need to copy augmented.css (or data-augmented.css) into the public folder and manually include it in the index.html file to avoid them until they're fixed.

You can read more about using the public folder here: https://create-react-app.dev/docs/using-the-public-folder/

You can read more about the Post CSS bug here (issue has been open for about 1 year): https://github.com/postcss/postcss-calc/issues/77

You can read more about the cssnano bug here (solved, but there hasn't been a release in over a year): https://github.com/cssnano/cssnano/issues/822

Compatibility with styled-components in React

styled-components strips non-standard attributes so make sure to use data-augmented.css

Compatibility in VSCode

VSCode complains about the leading comma and currently the only way to avoid it is to disable its CSS Validation.

You can read more about disabling it here: https://github.com/propjockey/augmented-ui/issues/2#issuecomment-540184111

You can read more about the issue here: https://github.com/microsoft/vscode/issues/82178

Compatibility with SASS

SASS has multiple implementations/compilers, some have parsing bugs related to the leading comma in custom properties. The compiler used on sassmeister.com handles the leading comma correctly in custom properties (by ignoring it), but trips up when it's used in a supports statement @supports (--foo: , 0 0) If you run into trouble, include augmented.css separately from your SASS ecosystem.

Other notes?

Please feel free to file an issue if you run into any trouble, I'll be glad to take a look and work on a path forward for you!