This guide covers the UI components that are used across the new MSDN/TechNet technical documentation experiences for conceptual, reference, and hub pages.

Important

While this document attempts to be comprehensive in representing the UI components, it is ultimately a guide. Developers utilizing the front end code represented here should take full ownership and responsibility of it. Code is always work-in-progress, and this code is no different.

The components as well as the frame for conceptual, reference, and hub pages have been designed with accessibility in mind. The designs and front end markup employ many best practices like semantic markup, color contrast, proportional sizing units to support zooming, etc. to provide a solid foundation for building a very accessible platform

That said, the example mark up files as well as the code snippets for all the components are being provided stripped of ARIA roles, alt titles, etc. to avoid confusion. We recommend that the team prioritize a sprint prior to launch that focuses on updating the master templates and markdown extensions for components with all the necessary accessibility features.

Tip

A good starting point for information about accessibility is Foundation’s Accessibility Guidelines page.

Preview

Assembly
Inheritance
Cloud
Edit
Share
Options
Help
Comments
Feedback
Connect
Check Box
Alert - Warning
Alert - Tip
Alert - Important
Alert - Note
Theme - Both
Theme - Night
Theme - Day
Next
Previous
Up Arrow
Down Arrow

Code

<ul class="list-clean">
<li><span class="icon icon-assembly"></span> <mark>Assembly</mark></li>
<li><span class="icon icon-inheritance"></span> <mark>Inheritance</mark></li>
<li><span class="icon icon-cloud"></span> <mark>Cloud</mark></li>
<li><span class="icon icon-edit"></span> <mark>Edit</mark></li>
<li><span class="icon icon-share"></span> <mark>Share</mark></li>
<li><span class="icon icon-options"></span> <mark>Options</mark></li>
<li><span class="icon icon-help"></span> <mark>Help</mark></li>
<li><span class="icon icon-comments"></span> <mark>Comments</mark></li>
<li><span class="icon icon-feedback"></span> <mark>Feedback</mark></li>
<li><span class="icon icon-connect"></span> <mark>Connect</mark></li>
<li><span class="icon icon-uniE0A2"></span> <mark>Check Box</mark></li>
<li><span class="icon icon-warning"></span> <mark>Alert - Warning</mark></li>
<li><span class="icon icon-tip"></span> <mark>Alert - Tip</mark></li>
<li><span class="icon icon-important"></span> <mark>Alert - Important</mark></li>
<li><span class="icon icon-note"></span> <mark>Alert - Note</mark></li>
<li><span class="icon icon-theme-both"></span> <mark>Theme - Both</mark></li>
<li><span class="icon icon-theme-night"></span> <mark>Theme - Night</mark></li>
<li><span class="icon icon-theme-day"></span> <mark>Theme - Day</mark></li>
<li><span class="icon icon-next"></span> <mark>Next</mark></li>
<li><span class="icon icon-prev"></span> <mark>Previous</mark></li>
<li><span class="icon icon-down-arrow"></span> <mark>Up Arrow</mark></li>
<li><span class="icon icon-up-arrow"></span> <mark>Down Arrow</mark></li>
</ul>

Preview

h1. Heading Level 1

h2. Heading Level 2

h3. Heading Level 3

h4. Heading Level 4

h5. Heading Level 5

h6. Heading Level 6

Code

<h1>h1. Heading Level 1</h1>
<h2>h2. Heading Level 2</h2>
<h3>h3. Heading Level 3</h3>
<h4>h4. Heading Level 4</h4>
<h5>h5. Heading Level 5</h5>
<h6>h6. Heading Level 6</h6>

Preview

Code

<hr />

Preview

So, I heard you like paragraphs. Especially ones with a strong personality, a flair for emphasizing syllables, and the unfortunate need to ~~correct their mistakes~~.

Code

<p>
  So, I heard you like paragraphs. 
  Especially ones with a <strong>strong</strong> personality, 
  a flair for <em>emphasizing</em> syllables, 
  and the unfortunate need to <del>correct their mistakes</del>.
</p>

Preview

If at first you can't File > Exit, try ^try _again.

Code

<p>
  If at first you can't <mark>File > Exit</mark>, 
  <code>try</code> <sup>try</sup> <sub>again</sub>.
</p>

Preview

One fish. Two fish. Red fish. Blue fish.

Code

<p>
  One fish. 
  Two fish. 
  Red fish. 
  <a href="http://www.mfwi.edu/MFWI/Recordings/One%20Fish.pdf">Blue</a> fish.
</p>

Preview

This is a small button:

This is a default button:

This is a big button:

This is a big, disabled button:

This is a big button with an icon (don't forget to leave a space after the icon):

Tip

You can add an icon to any button using an icon font class. UICF provides a custom icon font (generated from Microsoft's internal icon font library) with 24 individual glyphs. It is recommended that this icon font be expanded whenever icons need to be added so as to ensure that only a single request is made to download icons.

Code

<p>This is a small button:
  <button type="button" class="button-small">Hello</button>
</p>
<p>This is a default button:
  <button type="button">Hello</button>
</p>
<p>This is a big button:
  <button type="button" class="button-big">Hello</button>
</p>
<p>This is a big, disabled button:
  <button type="button" class="button-big" disabled>Hello</button>
</p>
<p>This is a big button with an icon (don't forget to leave a space after the icon):
  <button type="button" class="button-big"><span class="icon icon-theme-day"> </span>Hello</button>
</p>

Preview

Hover over this for the definition of the word definition.

Code

<p>
  <span class="definition" title="the formal statement of the meaning or significance of a word, phrase, idiom, etc., as found in dictionaries.">Hover over this</span> for the definition of the word <em>definition</em>
</p>

Preview

Lists can be ordered:

Hey diddle diddle,
The cat and the fiddle
The...
1. Cow
2. Jumped over
3. The
4. Moon.

Lists can also be unordered:

The little dog laughed,
To see such fun.
And the...
- Dish
- Ran away
- With the
- Spoon

Lists can also be mixed:

Baa, baa, black sheep,
Have you any wool?
Yes, sir, yes, sir,
Three bags full:
1. One for the master,
2. And one for the dame,
3. And one for the little boy
Who lives down the lane.

Code

<p>Lists can be ordered:</p>
<ol>
  <li>Hey diddle diddle,</li>
  <li>The cat and the fiddle</li>
  <li>The...
    <ol>
      <li>Cow</li>
      <li>Jumped over</li>
      <li>The</li>
      <li>Moon.</li>
    </ol>
  </li>
</ol>
<p>Lists can also be unordered:</p>
<ul>
  <li>The little dog laughed,</li>
  <li>To see such fun.</li>
  <li> And the...
    <ul>
      <li>Dish</li>
      <li>Ran away</li>
      <li>With the</li>
      <li>Spoon</li>
    </ul>
  </li>
</ul>
<p>Lists can also be mixed:</p>
<ul>
  <li>Baa, baa, black sheep,</li>
  <li>Have you any wool?</li>
  <li>Yes, sir, yes, sir,</li>
  <li>Three bags full:
    <ol>
      <li>One for the master,</li>
      <li>And one for the dame,</li>
      <li>And one for the little boy</li>
    </ol>
  </li>
  <li>Who lives down the lane.</li>
</ul>

Preview

Unless someone like you
Cares a whole awful lot,
Nothing is going to get better.
It’s not.

— Dr. Seuss

Code

<blockquote>
  <p>
    Unless someone like you<br>
    Cares a whole awful lot,<br>
    Nothing is going to get better.<br>
    It’s not.
  </p>
  <footer>— <cite title="Dr. Seuss">Dr. Seuss</cite></footer>
</blockquote>

Preview

You can use superscript numbers¹ to² create³ footnotes.

Boom!
Boom!!
Aaaaand, boom!!!

Code

<p>
  You can use superscript numbers<sup><a href="#footnote-1">1</a></sup> 
  to<sup><a href="#footnote-2">2</a></sup> create 
  <sup><a href="#footnote-3">3</a></sup>footnotes.
</p>
<ol class="list-footnotes">
  <li id="footnote-1">Boom!</li>
  <li id="footnote-2">Boom!!</li>
  <li id="footnote-3">Aaaaand, boom!!!</li>
</ol>

Alerts

Alerts are stylized UI blocks that draw the reader's attention to the content they contain. Content within alerts may contain paragraphs, lists, and inline styles, but authors should try to keep alerts brief and use them sparingly.

In all, we provide five kinds of alerts, but only four may be employed by authors. The fifth style — Minimal — is a reserved style for use within Reference documentation:

Note
Tip
Warning
Important
Minimal

Preview

Note

Oh me! Oh my! Oh me! Oh my! What a lot of funny things go by.

Tip

I meant what I said, and I said what I meant. An elephant’s faithful, one hundred percent! And it should be, it should be, it SHOULD be like that! Because Horton was faithful! He sat and he sat!

“My goodness! My gracious!” they shouted. “MY WORD! It’s something brand new! IT’S AN ELEPHANT-BIRD!!”

Warning

So be sure when you step. Step with care and great tact, and remember that:

Life’s a
Great
Balancing
Act

Important

If we didn’t have birthdays, you wouldn’t be you. If you’d never been born, well then what would you do? If you’d never been born, well then what would you be? You might be a fish! Or a toad in a tree! You might be a doorknob! Or three baked potatoes! You might be a bag full of hard green tomatoes. Or worse than all that… why, you might be a WASN’T! A Wasn’t has no fun at all. No, he doesn’t. A Wasn’t just isn’t. He just isn’t present. But you… you ARE YOU! And, now isn’t that pleasant!

Assembly

mscorlib (in mscorlib.dll)

Code

<div class="alert alert-note">
  <h5><span class="icon-note"></span> Note</h5>
  <p>Oh me! Oh my! Oh me! Oh my! What a lot of <code>funny</code> 
  things go by.</p>
</div>

<div class="alert alert-tip">
  <h5><span class="icon-tip"></span> Tip</h5>
  <p>I meant what I said, and I said what I meant. An elephant’s 
  <em>faithful</em>, one hundred percent! And it should be, it 
  should be, it <strong>SHOULD</strong> be like that! Because 
  Horton was faithful! He sat and he sat!</p>
  <p>“My goodness! My gracious!” they shouted. “MY WORD! It’s 
  something brand new! IT’S AN <a href="">ELEPHANT-BIRD</a>!!”</p>
</div>

<div class="alert alert-warning">
  <h5><span class="icon-warning"></span> Warning</h5>
  <p>So be sure when you step. Step with care and great tact, and 
  remember that:</p>
  <ul>
     <li>Life’s a</li>
     <li>Great</li>
     <li>Balancing</li>
     <li>Act</li>
  </ul>
</div>

<div class="alert alert-important">
  <h5><span class="icon-important"></span> Important</h5>
  <p>If we didn’t have birthdays, you wouldn’t be you.  If you’d 
  never been born, well then what would you do?  If you’d never 
  been born, well then what would you be?  You might be a fish! 
  Or a toad in a tree!  You might be a doorknob! Or three baked 
  potatoes!  You might be a bag full of hard green tomatoes. 
  Or worse than all that… why, you might be a WASN’T!  A Wasn’t 
  has no fun at all. No, he doesn’t.  A Wasn’t just isn’t. He 
  just isn’t present.  But you… you ARE YOU! And, now isn’t that 
  pleasant!</p>
</div>

<div class="alert alert-minimal">
  <h5><span class="icon icon-assembly"></span> Assembly</h5>
  <p><code>mscorlib (in mscorlib.dll)</code></p>
</div>

Preview

Following are examples of code blocks wrapped in figures. The first has a caption above it, and the second has the caption below it.

A caption can be at the top of the code block.

using System;

public class Example
{
  public static void Main() { }
}

using System;

public class Example
{
  public static void Main() { }
}

A caption can also be at the bottom of the code block.

Code

<figure>
  <figcaption>A caption can be at the top of the code 
  block.</figcaption>
  <pre><code>
using System;

public class Example
{
public static void Main() { }
}
  </code></pre>
</figure>

<figure>
  <pre><code>
using System;

public class Example
{
  public static void Main() { }
}
  </code></pre>
  <figcaption>A caption can also be at the bottom of 
  the code block.</figcaption>
</figure>

Images must be wrapped in <figure> tags even if they don't require captions (for more details about adding captions to elements wrapped in figures, see Figures, Figure Captions, & Code). All common web image formats are supported: jpg, png, gif, svg (included animated).

Video is supported via the <video> tag. UICF provides basic responsive block styling for video elements, however, videos will need to be integrated using an HTML5 video player component that is outside the scope of this framework.

Important

Images in UICF are furnished with basic responsive styling so they scale proportionally to fill no more than the width of their containers. However, this is the bare minimum. True responsive images take many more factors into account, and require the use of new standards like srcset. They are out of scope for this first version of the UICF, but should be appropriately prioritized for future releases as they can dramatically improve the performance and user experience of web pages. More information about responsive images may be found here.

Preview

Code

<figure>
  <img src="./img/hololens.gif" alt="" />
</figure>

<!-- Image without border -->
<figure class="no-border">
  <img src="./img/hololens.gif" alt="" />
</figure>

Preview

Code

<div class="step-by-step">
  <button type="button"><span class="icon icon-prev"></span> Prev</button>
  <button type="button">Next <span class="icon icon-next"></span></button>
</div>

Preview

Optional table caption
Style	Supported In Table?
Bold text	Yes
Italicized text	Yes
~~Striked out~~ text	Yes
Inline `code`	Yes
Links	Yes
Lists, Alerts, Code Blocks, Images, Videos, Buttons, Giraffes	No

Code

<div class="table-wrapper">
  <table class="table-striped">
    <caption>Optional table caption</caption>
    <thead>
      <tr>
        <th>Style</th>
        <th>Supported In Table?</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><strong>Bold</strong> text</td>
        <td>Yes</td>
      </tr>
      <tr>
        <td><em>Italicized</em> text</td>
        <td>Yes</td>
      </tr>
      <tr>
        <td><del>Striked out</del> text</td>
        <td>Yes</td>
      </tr>
      <tr>
        <td>Inline <code>code</code></td>
        <td>Yes</td>
      </tr>
      <tr>
        <td><a href="">Links</a></td>
        <td>Yes</td>
      </tr>
      <tr>
        <td>Lists, Alerts, Code Blocks, Images, Videos, Buttons, 
        Giraffes</td>
        <td>No</td>
      </tr>
    </tbody>
  </table>
</div>

Preview

Dropdowns may provide a flat list of links:

Dropdowns may provide a grouped list of links:

Dropdowns come in three explicit sizes (apart from the default that sizes automatically): small, medium, & large, & full width:

Important

The dropdown UI element should not directly be made available for use in authoring documents. UICF provides a separate component — Doc-level Options — for allowing authors to embed UI with selectors and buttons within conceptual documents for scenarios like platform/language switching.

Code

<p>Dropdowns may provide a flat list of links:
  <div class="dropdown-container">
    <div class="dropdown">
      <select>
        <option value="option-1">Option 1</option>
        <option value="option-2">Option 2</option>
        <option value="option-3">Option 3</option>
      </select>
    </div>
  </div>
</p>
<p>Dropdowns may provide a grouped list of links:
  <div class="dropdown-container">
    <div class="dropdown">
      <select>
        <optgroup label="Group A">
          <option value="option-A1">Option 1</option>
          <option value="option-A2">Option 2</option>
          <option value="option-A3">Option 3</option>
        </optgroup>
        <optgroup label="Group B">
          <option value="option-B1">Option 1</option>
          <option value="option-B2">Option 2</option>
          <option value="option-B3">Option 3</option>
        </optgroup>
      </select>
    </div>
  </div>
</p>
<p>Dropdowns come in three explicit sizes 
(apart from the default that sizes automatically): 
small, medium, & large, & full width:
  <div class="dropdown-container dropdown-small">
    <div class="dropdown">
      <select>
        <option value="option-1">Option 1</option>
        <option value="option-2">Option 2</option>
        <option value="option-3">Option 3</option>
      </select>
    </div>
  </div><br /><br />
  <div class="dropdown-container dropdown-medium">
    <div class="dropdown dropdown-medium">
      <select>
        <option value="option-1">Option 1</option>
        <option value="option-2">Option 2</option>
        <option value="option-3">Option 3</option>
      </select>
    </div>
  </div><br /><br />
  <div class="dropdown-container dropdown-large">
    <div class="dropdown">
      <select>
        <option value="option-1">Option 1</option>
        <option value="option-2">Option 2</option>
        <option value="option-3">Option 3</option>
      </select>
    </div>
  </div><br /><br />
  <div class="dropdown-container dropdown-full">
    <div class="dropdown">
      <select>
        <option value="option-1">Option 1</option>
        <option value="option-2">Option 2</option>
        <option value="option-3">Option 3</option>
      </select>
    </div>
  </div>
</p>

Preview

Code

<aside class="toc">
<h5>In this article</h5>
<ul>
  <li><a href="">First section</a></li>
  <li><a href="">Second section</a></li>
  <li><a href="">Third section</a></li>
  <li><a href="">Fourth section</a></li>
  <li><a href="">Fifth section</a></li>
  <li><a href="">etc.</a></li>
</ul>
</aside>

Preview

Pick an option
And another

Code

<ul class="document-ui">
  <li>
    <div class="dropdown-container">
      <label for="dropdown">Pick an option</label>
      <div class="dropdown">
        <select>
          <option value="option-a">Option A</option>
          <option value="option-b">Option B</option>
        </select>
      </div>
    </div>
  </li>
  <li>
    <div class="dropdown-container">
      <label for="dropdown">And another</label>
      <div class="dropdown">
        <select>
            <option value="option-c">Option C</option>
            <option value="option-d">Option D</option>
        </select>
      </div>
    </div>
  </li>
  <li>
    <button type="button" class="button-small">Button</button> 
  </li>
</ul>

Preview

Inheritance Hierarchy

System.Object
System.String

Code

<div class="alert alert-minimal inheritance">
  <h5><span class="icon icon-inheritance"></span> Inheritance Hierarchy</h5>
  <ul>
    <li class="l0"><a href=""><code>System.Object</code></a></li>
    <li class="l1"><code>System.String</code></li>
  </ul>
</div>

Member Details

The member details component is a very flexible and versatile component for the presentation of detailed technical lists including method parameters, return values, exceptions, REST resource properties, HTTP response codes, enumeration members, and more.

Structurally, each list item in the component consists of three parts:

Meta: This provides two slots to encaspulate information like parameter name and type. Optionally, it can accept only one slot which is floated right. The type of information it accepts is configurable, but must always be wrapped in a <code> element.
Description: This part is used to present short-form information about the member, e.g. parameter description for a method. It is fairly flexible and should be able to accommodate a variety of inline styles. We recommend limiting the content within to paragraphs, links, and standard inline styles.
Tags: This part is optional, but may be used for supplementary information. For instance, REST resoure properties, may indicate CRUD information, filterability, and so on.

Below you'll find various permutations of the same component to display all types of information.

Preview - REST Resource Properties

1. accountEnabled
2. Edm.Boolean
true if the account is enabled; otherwise, false. This property is required when a user is created.
1. C
2. R
3. U
4. D
5. Filterable
1. assignedLicenses
2. Collection(AssignedLicense)
The licenses that are assigned to the user. Not nullable.
1. C
2. R
3. U
4. D

Code

<ul class="member-details">
<li>
  <ol class="meta">
    <li><code>accountEnabled</code></li>
    <li><code>Edm.Boolean</code></li>
  </ol>
  <section class="description">
    <p><code>true</code> if the account is enabled; otherwise, <code>false</code>. This property is required when a user is created.</p>
  </section>
  <ol class="tags">
    <li class="round">C</li>
    <li class="round">R</li>
    <li class="round off">U</li>
    <li class="round off">D</li>
    <li>Filterable</li>
  </ol>
</li>
<li>
  <ol class="meta">
    <li><code>assignedLicenses</code></li>
    <li><code>Collection(<a href="">AssignedLicense</a>)</code></li>
  </ol>
  <section class="description">
    <p>The licenses that are assigned to the user. Not nullable.</p>
  </section>
  <ol class="tags">
    <li class="round">C</li>
    <li class="round">R</li>
    <li class="round">U</li>
    <li class="round">D</li>
  </ol>
</li>

Preview - REST API HTTP Response Codes

1. 204
No Content. Indicates success. No response body is returned.

Code

<ul class="member-details">
  <li>
    <ol class="meta">
      <li><code>204</code></li>
    </ol>
    <section class="description">
      <p>No Content. Indicates success. No response body is returned.</p>
    </section>
  </li>
</ul>

Preview - Client SDK Method Parameters

1. values
2. Generic.IEnumerable<String>
A collection object that implements IEnumerable<T> and whose generic type argument is String.
1. values
2. Generic.IEnumerable<String>
A collection object that implements IEnumerable<T> and whose generic type argument is String.

Code

<ul class="member-details">
  <li>
    <ol class="meta">
      <li><code>values</code></li>
      <li><code><a href="">Generic</a>.IEnumerable&lt;<a href="">String</a>&gt;</code></li>
    </ol>
    <section class="description">
      <p>A collection object that implements <a href=""><code>IEnumerable&lt;T&gt;</code></a> and whose generic type argument is <a href=""><code>String</code></a>.</p>
    </section>
  </li>
  <li>
    <ol class="meta">
      <li><code>values</code></li>
      <li><code><a href="">Generic</a>.IEnumerable&lt;<a href="">String</a>&gt;</code></li>
    </ol>
    <section class="description">
      <p>A collection object that implements <a href=""><code>IEnumerable&lt;T&gt;</code></a> and whose generic type argument is <a href=""><code>String</code></a>.</p>
    </section>
  </li>
</ul>

Preview - Client SDK Method Returns

1. String
The concatenated strings in values.

Code

<ul class="member-details">
  <li>
    <ol class="meta">
      <li><a href=""><code>String</code></a></li>
    </ol>
    <section class="description">
      <p>The concatenated strings in <code>values</code>.</p>
    </section>
  </li>
</ul>

Preview - Client SDK Method Exceptions

1. ArgumentNullException
values is null.
1. OutOfMemoryException
Out of memory.

Code

<ul class="member-details">
  <li>
    <ol class="meta">
      <li><a href=""><code>ArgumentNullException</code></a></li>
    </ol>
    <section class="description">
      <p><code>values</code> is null.</p>
    </section>
  </li>
  <li>
    <ol class="meta">
      <li><a href=""><code>OutOfMemoryException</code></a></li>
    </ol>
    <section class="description">
      <p>Out of memory.</p>
    </section>
  </li>                        
</ul>

Preview - Client SDK Enumeration Members

1. None
No initialization action.
1. RegisterWithHost
Register the COM callable wrapper for the current AppDomainManager with the unmanaged host.

Code

<ul class="member-details">
  <li>
    <ol class="meta">
      <li><code>None</code></li>
    </ol>
    <section class="description">
      <p>No initialization action.</p>
    </section>
  </li>
  <li>
    <ol class="meta">
      <li><code>RegisterWithHost</code></li>
    </ol>
    <section class="description">
      <p>Register the COM callable wrapper for the current AppDomainManager with the unmanaged host.</p>
    </section>
  </li>
</ul>