Introduction to Components

Overview

Welcome to Blueprints for React, a collection of 40+ components designed for documentation experiences. Whether you’re looking to extend a Starter project or embarking on building a documentation site from scratch, our library is tailored to support your vision. It’s especially useful for projects that demand a high level of customization, allowing you to construct a documentation site that perfectly aligns with your project’s identity and requirements.

  1. 1
    Blueprints components are designed and built to seamlessly integrate within the Fluent ecosystem.
  2. 2
    Each component in our library is the result of research into successful design patterns. This ensures that when you use our components, you’re not just building a site; you’re leveraging best practices in documentation.
  3. 3
    We place a high emphasis on accessibility and usability standards, ensuring that your documentation is not only beautiful but also inclusive of users with different needs.

Getting Started

In the following sections, we’ll dive deeper into the technical details—design and code—and how you can start using them.

  • —
    Fluent tokens. The designs and React implementation draw from Fluent tokens.
  • —
    Light and dark modes. All components support light and dark mode out of the box.
  • —
    Brand ramp. Components will respond to a custom branding colors.

Working with Figma Toolkit

Each React component has a mirror Figma component that provides designers with a high-fidelity and interactive design environment. The toolkit is designed to ensure that what you create in Figma aligns perfectly with the final product, bridging the gap between initial design and final implementation.

Each component documentation page has a link to its Figma toolkit. This setup allows you to prototype and iterate on your designs using components that are visually and functionally consistent with their React counterparts.

Setting up the project

1. Utilizing Griffel for Styling

Blueprints React components are styled with Fluent’s Griffel library for styling. While Griffel is not a requirement, it is a great choice for styling, especially for projects within the Fluent ecosystem. Griffel excels in optimizing CSS and enhancing the developer experience. To learn more about Griffel head over to its documentation.

Here is a sample of how Blueprints styles its components with Fluent tokens and Griffel.

1import { tokens } from '@fluentui/react-theme';
2import { makeStyles } from '@griffel/react';
3
4export const useMyComponentStyles = makeStyles({
5  root: {
6    display: 'grid',
7    rowGap: tokens.spacingVerticalS,
8  },
9});
10
11
1import { mergeClasses } from '@griffel/react';
2import type { FC } from 'react';
3import * as React from 'react';
4
5import { useMyComponentStyles } from './my-component.styles';
6import type { MyComponentProps } from './my-component.types';
7
8export const MyComponent: FC<MyComponentProps> = ({ className, children }) => {
9  // Styles
10  const classes = useMyComponentStyles();
11
12  return <div className={mergeClasses(classes.root, className)}>{children}</div>;
13};
14
15

2. Wrapping Your Project with ThemeProvider

Blueprints components require ThemeProvider to function correctly.

1import { ThemeProvider } from '@microsoft/blueprints.theming';
2
3const App = () => (
4  <ThemeProvider>
5    {/* Your app components */}
6  </ThemeProvider>
7);
8
9

3. Customizing with Optional Brand Ramp

You have the option to further customize your application's theme by passing a brand ramp to the ThemeProvider. A brand ramp allows you to align the component styling with your brand colors.

1import { type BrandVariants } from '@fluentui/react-theme';
2
3export const YOUR_DOCS_BRAND_VARIANTS: BrandVariants = {
4  10: '#151515',
5  20: '#1E1F22',
6  30: '#26282E',
7  40: '#2D303D',
8  50: '#34394F',
9  60: '#3A4261',
10  70: '#304391',
11  80: '#3853BD',
12  90: '#405BC6',
13  100: '#5E78E0',
14  110: '#7188E6',
15  120: '#8398EB',
16  130: '#9FAFF1',
17  140: '#B7C4F7',
18  150: '#CFD8FA',
19  160: '#EBEEFC',
20};
21// Pass to <ThemeProvider brandVariants={YOUR_DOCS_BRAND_VARIANTS}>
22

4. Enhancing with the Shell Component

For a more comprehensive setup, consider adding the Shell component. The Shell component provides a foundational layout, including navigation, header, and footer. It also integrates functionality to switch between light and dark modes. Learn more about Shell in its documentation.

P.S.

Check the project’s dependencies for the currently supported version of React and Typescript.