@financial-times/o-visual-effects

Provides visual effects through SCSS mixins, such as shadows and animations

Usage no npm install needed!

<script type="module">
  import financialTimesOVisualEffects from 'https://cdn.skypack.dev/@financial-times/o-visual-effects';
</script>

README

o-visual-effects

This Origami component provides CSS visual effects via a set of Sass variables and mixins.

Usage

Check out how to include Origami components in your project to get started with o-visual-effects.

Markup

o-visual-effects provides helper classes to style with different levels of box shadow:

  • .o-visual-effects-shadow-ultralow
  • .o-visual-effects-shadow-low
  • .o-visual-effects-shadow-mid
  • .o-visual-effects-shadow-high
<div class="o-visual-effects-shadow-high">Box content</div>

o-visual-effects also provides timing functions for slide, expand, or fade animations and transitions as CSS custom properties (CSS Variables). Sass users may use Sass variables to apply these timing functions instead.

CSS Custom Properties

Build Service users may use CSS Custom Properties (CSS Variables) to apply consistent timing functions within custom CSS. The variables avalible are:

  • --o-visual-effects-timing-slide
  • --o-visual-effects-timing-expand
  • --o-visual-effects-timing-fade

E.g.

.transition--slide {
    transition: all 0.5s var(--o-visual-effects-timing-slide);
}

.transition--expand {
    transition: all 0.5s var(--o-visual-effects-timing-expand);
}

.transition--fade {
    transition: all 0.5s var(--o-visual-effects-timing-fade);
}

Sass users should use Sass variables instead for improved browser support.

Sass

To include all o-visual-effects css call the oVisualEffects mixin. This will include box shadow styles and CSS custom properties for transition timing functions.

@include oVisualEffects();

o-visual-effects may also be output granularly. For example ommit the CSS custom properties if you are using Sass variables such as $o-visual-effects-timing-slide instead:

@include oVisualEffects($opts: (
    'shadows': ('ultralow', 'low', 'mid', 'high')
));

If you are not using o-visual-effects CSS, and instead are using other Sass mixins or variables directly there is no need to call oVisualEffects.

Shadows mixin

The oVisualEffectsShadowContent mixin is used to add a consistent shadow to your element. There are 4 levels of shadow available: ultralow, low (default), mid, and high.

Example:

.my-element {
    @include oVisualEffectsShadowContent('mid');
}

Output:

.my-element {
    box-shadow: 0 1px 3px rgba(77, 72, 69, 0.2), 0 6px 10px rgba(77, 72, 69, 0.15);
}

Transition variables

When adding transitions to elements in CSS, you should use o-visual-effects variables for consistent timings for slide, expand, and fade effects.

Example:

.transition--slide {
    transition: all 0.5s $o-visual-effects-timing-slide;
}

.transition--expand {
    transition: all 0.5s $o-visual-effects-timing-expand;
}

.transition--fade {
    transition: all 0.5s $o-visual-effects-timing-fade;
}

Output:

.transition--slide {
    transition: all 0.5s cubic-bezier(1, 0, 0.5, 1.275);
}

.transition--expand {
    transition: all 0.5s cubic-bezier(0.215, 0.61, 0.355, 1);
}

.transition--fade {
    transition: all 0.5s cubic-bezier(0.165, 0.84, 0.44, 1);
}

Migration guide

State Major Version Last Minor Release Migration guide
✨ active 3 N/A migrate to v3
⚠ maintained 2 2.1 migrate to v2
╳ deprecated 1 1.0 N/A

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.


Licence

This software is published by the Financial Times under the MIT licence.