Skip to main content

Working with CSS

Cascading Style Sheets, best known as CSS, is vital to the visual design integrity of MWF. MWF CSS is architected in such a way that a design system change can be deployed and thousands of Microsoft web sites immediately receive the updated look and feel. In most cases this doesn't even require engineering involvement. This works very well assuming the standards, guidelines, and implementation details for MWF have been followed.

Most of the building blocks within MWF, especially our components and modules, include required and optional attributions that control the styling and functionality through CSS. In some cases it's necessary to progressively enhance the HTML to elevate the user experience.

We recognize that there are situations where a CSS solution is necesary to achieve a desired business goal that may deviate from Microsoft's design or accessibility goals. While strongly discouraged, at times it is necessary and worth taking the risk of falling out of line with Microsoft's Design Language.

When found in this position MWF has documented best practices to safely manage your overrides in an MWF complaint manner.

Best Practices

When manipulating CSS, be very careful. A seemingly simple tweak can result in major collateral damage. Possible issues you may encounter include abnormal behavior from styling conflicts, components that cease to function normally, code validation failure, no apparent effect, some subtle flaw that breaks branding, or some unknown consequence. Here are some things to consider before using a CSS override:

  • Consider using utility classes to achieve desired CSS tweaks.
  • Avoid using inline style statements unless the change is directly related to the content.
  • Try to keep the distribution releases of CSS and JS libraries in synch to avoid unexpected behaviors.
  • Try and avoid local style overrides.
  • If you are using local styles, don't target HTML elements or or apply wholesale changes to MWF components or modules. This creates a high risk of regressions. Instead, apply changes using a contextual class
  • Scope any class names you create by prefixing it so it doesn't clash with MWF styles
  • Make class names semantically meaningful and focused on your specific scenario
  • Reach out to MWF design regarding your requirements and scenario. If this is a change that would benefit all consumers of MWF, it's possible that this is already on our backlog or something we can quickly provide support for.

Inline styles

In most cases, we do not recommend the use of inline styles; however, for certain scenarios and design needs it may be the best choice to solve a problem. This approach is recommended for instances where the style is directly related to a piece of content. Consider the example below for a product placement item. Perhaps one of your images is a transparent .png which requires a background color; in this case, we reccomend applying that background as an inline style to the div as this change directly relates to the image as content.


<div class="f-default-image" style="background: #0078D7">
        <source srcset="/images/content-images/generic-glyph-default-large.png" media="(min-width:0)">
        <img class="c-image" srcset="/images/content-images/generic-glyph-default-large.png" src="/images/content-images/generic-glyph-default-large.png" alt="White frame with mountain landscape illustrated in white on a grey background" onerror="handleImgError(this, 'medium')">

Contextual overrides


Contextual overrides are a good solution when you require an extendable piece of code for a scenario that shows up throughout your site. Typically, we recommend that you leverage contextual classes for things like layout issues rather than wholesale design changes (IE, adding a class to make all call to actions bold because you prefer the heavier weight).

Let's take a layout issue as an example. Perhaps when you place product placement items within a group your design requires more vertical space between the items. This is the perfect scenario for a contextual override because the issue is specifically related to product placement items when they are used within this context. Rather than make changes to the item in an override, we can add a context class to the parent, which applys vertical spacing to product placement items when they are direct children of a group with that class name.


.store-context-product-group > .m-product-placement-item {
    padding-top: 12px;

<div class="c-group store-context-product-group">
    <!-- Product placement items -->


While we typically don't recommend making wholesale design changes, there are certain scenarios where it would be appropriate to use a context class. Let's say that for the holidays, all feature modules that pertain to products need to have a red background and white text for accessibility. Since this is a repeatable pattern across the site, a context class makes sense. We don't recommend applying this as an override to the feature base class because we only want to target certain feature modules.

    background: #A80000;
    color: #FFFFFF;
} > div > .c-call-to-action {
    color: #FFFFFF;
} > div > .c-call-to-action:hover {
    color: #e6e6e6;

<div class="m-feature f-align-left store-context-holiday-feature">
    <!-- Feature code -->

Create your own module

If you find yourself needing to change the structure of a module or apply large scale CSS changes to meet design or business requirements, it is probably a good time to consider creating your own module. One way to do this is to fork the MWF module you are trying to change and create something specific to your scenario. Perhaps you need a hero item that includes a heading, a subheading, and a description - consider forking the MWF Hero as a base and creating your own hero with a namespaced class. Doing this will ensure that MWF doesn't break your specific scenario if we make changes to our hero item module. Forking also allows you to use what MWF has and refine the styles to match your scenario. If you follow our design guidelines and maintain the integrity of the components themselves, this is a perfectly acceptable way of accomplishing your goals using MWF without the risk of regressions that overrides bring with them.

Utility selectors

To provide you with some design flexibility, MWF includes several utility classes that provide many common CSS tweaks that can be applied to you web pages. We call them Utility Selectors or Utility Classes. The below section examines the available utility selectors and what they do.

Floats and clears

Use a float to specify that an element should be taken from the normal flow and placed along the left or right side of its container. In many cases a float will need to be preceeded or followed with a clearfix as illustrated here.


<div class="x-clearfix">
  <div class="x-float-left"> ...</div>
  <div class="x-float-right"> ...</div>


Offset content

The offset content utility class can be used to align blocks of content or components to the content grid. A padding offset is on both left and right sides. The degree of offset is based on the viewport size.

x-offset-content is built to work with the grid. Positioning components within the grid often requires a bit of padding to align with the grid. This is usually done by adding a flag (e.g. pad-12x) to the grid parent of the children that need padding. To ensure correct alignment to the content grid, we have to add different values based on the padding that is already being added. For example, at VP6, we want 48px of padding for everything on the content grid. If pad-12x already has added to the grid parent, x-offset-content should have no effect. The left/right padding for the content grid reduces in size as we scale down in viewport size — at each step — just like the various pad- values for the data-grid. To be sure these match, we have calculated the correct amount of padding to align things to the content grid and set up the CSS accordingly. This will require some creativity at times when laying out complex pages.


<div data-grid="col-12 pad-6x" class="x-offset-content"> ..content..</div>

Keep in mind that x-offset-content is designed as a helper class for aligning modules or components to fit into the content grid. By default, most all modules (m-foo) receive similar left/right padding to align them to the content grid. This means that using x-offset-content with a module will have no real effect. However, there may be certain cases where using x-offset-content may make sense. One example is the social module. Most use cases for this module require it to be positioned contextually, but what if you had a hypothetical design that required it to be in its own column aligned to the content grid? Using x-offset-content here should enable that use case. Nevertheless, most modules are already designed to align to the content grid.

On the other hand, when dealing with components, x-offset-content becomes very useful in providing grid alignment. It can even be used in a simple page designs to provide insetting of blocks of content, even though that is not its intended purpose.

Offset to align with UHF

The offset UHF utility class can be used to solve certain scenarios such as accommodating the need for pre-footer content or aligning content to the header and footer when there isn't a strong visual structure (checkout flows or article and documentation pages).

The x-offset-uhf utility selector should only be used inside the container and currently only supports standard data-grid="col-12" layouts (pad-__ scenarios are supported by design.


<div data-grid="col-12" class="x-offset-uhf"> ..content..</div>

Display type helpers

Use as optional layout and display type properties.


<div class="x-hidden">Hidden from view</div>
<div class="x-visible-block">Block element</div>
<div class="x-visible-inline-block">Inline-block element</div>
<div class="x-visible-inline">Inline element</div>

Vertical spacing

If vertical spacing is excessive above a module or component, in some cases you can apply the f-lean class to reduce the top spacing.


<ul class="c-list f-lean">
    <li>List item with reduced vertical spacing</li>
    <li>List item with reduced vertical spacing</li>

f-lean is known to work with the following classes:

  • c-heading-1
  • c-heading-2
  • c-heading-3
  • c-heading-4
  • c-heading-5
  • c-heading-6
  • c-list
  • c-paragraph
  • c-universal-header
  • m-image
  • m-highlight-feature
  • m-track-list

Breakpoint support

Breakpoint/viewport support for optional layout and display type properties. Supported viewports are:
vp1 (320px), vp2 (540px), vp3 (768px), vp4 (1084px) and vp5 (1400px)

Examples in code:


<div class="x-hidden-vp1">
    Hidden from any view with a max-width of 320px

<div class="x-visible-vp1-block">
    Block element; max-width of 320px

<div class="x-visible-vp1-inline-block">
    Inline-block element; max-width of 320px

<div class="x-visible-vp1-inline">
    Inline; max-width of 320px


Within a HTML block, use these utility selectors to position copy along a horizontal axis.


<div class="x-type-left">
  This text will be left justified.
<div class="x-type-center">
  This text will be centered.
<div class="x-type-right">
  This text will be right justified.

Accessibility (a11y)

If a content block is only intended to be seen by screen readers for a11y reasons and is not needed for presentation, using the x-screen-reader utility selector will remove this content from the view.


<div class="x-screen-reader">
  This text will only be viewable by a screen reader.


Use these utility classes to provide control over what content gets printed.


    <div class="x-visible-print-block">
        This text will be printed as a block.
    <div class="x-visible-print-inline">
        This text will be printed as inline content.
    <div class="x-visible-print-inline-block">
        This text will be printed as an inline block.
    <div class="x-hidden-print">
        This text will not be printed.