Our components are a collection of small, independent, general-purpose UI components intended to be reused throughout an application.
We have two main buckets for components, Experimental and Fundamental. These categories are created to notify Fabric users which components are expected to be fully supported and stable and which ones are likely to change drastically over a short period of time.
Before making the decision to design a new component, check to see if the pattern already exists within any current Microsoft design system including our Adobe XD Toolkit. Please feel free to open Github issues to clarify doubts.
If you are a Microsoft employee please check the internal version of the Adobe XD Toolkit (Microsoft Employees) or if you have more in depth questions regarding any Microsoft design system, please visit our internal Microsoft Teams channel.
If the new component pattern you are proposing already exists, but varies slightly, then please consider creating a variant of the component. For example, if you were to create a new button that does one new thing for our exisiting button then we would suggest creating a variant off the original button, but containing the one additional feature. The Button component is a good example of this. It has multiple variants like the ActionButton, PrimaryButton, CommandBarButton each of which is a very small component in itself. They all use the BaseButton for the core implementation but apply specific variations.
If it’s a new component request, does it add value at a broad level or is it a product-specific customization? Product-specific customizations should be stored in local product repos.
If the new component contains Microsoft Intellectual Property, it should be considered Internal and therefore all discussions around the component should only happen internally or within our Fabric Design Teams channel. If the component does not contain Microsoft Intellectual Property then this component can be discussed directly on GitHub in our issues section.
Create a new component pattern or leverage an existing component and create a variant. Use our Adobe XD Toolkit as a model for how we document component patterns in Fabric. We require that all components have detailed usage guidelines for developers and designers who want to integrate this pattern into their respective product/project. Component should be genericized before submission as much as possible leaving out product specific colors/customizations etc.
Ask for design feedback within the Fabric community through our Fabric Design Teams channel. Or, schedule review with the HVC product team for review. Socialize component in Fabric community so other teams have visibility. You can also post an issue on GitHub outlining the component request as long as it doesn't contain any Microsoft Intellectual Property.
Submit Internal components to our Fabric Design Teams channel so a designer on our team can update our toolkit. External components can be submitted via GitHub in our issue tracking section.
If the component has no Microsoft Intellectual Property then it belongs in our public project office-ui-fabric-react. If the component contains Microsoft Intellectual Property then it must live internally. Please reach out to our team for more information about our internal repository.
Before you start coding up your component, it is important to understand the lifecycle of a component.
-
All new components should start in the Experimental category. Please read the Experimental components section below for more details.
-
Once the component has been designed, developed and tested it can be deemed ready for promotion to the Fundamental components category. Please note, these components are widely used and changes can affect a lot of products.
-
Once you feel your component is ready to be promoted to become a Fundamental component, please request for a review with a Fabric core members. From outside Microsoft, you can do this through a GitHub issue.
-
Once the review is complete, you should be able to promote your component to the Fundamental components category. That is a big milestone.
Experimental components are any new components that do not currently exist within our Adobe XD Toolkit. By default, our create-component script will place the component folder and files in packages/experiments. New components stay in the experimental phase until a Fabric core team member approves the migrations from Experimental to Fundamental. Experimental components are developed in the experiments project located in the <root of project>packages/experiments folder. We also view any components that were created as a prototype or proof of concept.
Fundamental components are the official React representation of our Adobe XD Toolkit and receive higher priority in respect to stabilization, bug fixes, accessibility and general design resourcing. Components cannot be immediately added as a Fundamental type component as it will need a period of stabilization and API review. All components should always start off as Experimental. A good portion of the Fundamental components are currently integrated within some of our major products such as OneDrive, SharePoint and Outlook. Fundamental components are developed in the office-ui-fabric-react project in the <root of project>/packages/office-ui-fabric-react folder.
- This is the recommended way of creating a new component.
- Open a command prompt in the root directory of your project directory.
- Run
npm run create-component -- --name ExcitingNewComponent.
- From the root of the project, navigate to
packages/experiments/src/components/ - Create a new folder here with your component name
- Our components use the Pascal Case naming convention.
- In this example the component will be called
ExcitingNewComponent.
- Create a
ExcitingNewComponent.types.tsfile that will contain an interface for your component props
- Import React
import * as React from 'react';
- Import ExcitingNewComponent
import { ExcitingNewComponent } from './ExcitingNewComponent';- Note: This class and file don't exist yet but they will during step 4 of this small tutorial.
- Create an empty interface
IExcitingNewComponentexport interface IExcitingNewComponent {}
- Add your props interface to this file.
export interface IExcitingNewComponentProps extends React.Props<ExcitingNewComponent> { … Props }
- Create and export an interface for ExcitingNewComponent styles.
- Create a react file,
ExcitingNewComponent.tsx.
import * as React from 'react';
import { BaseComponent } from '../../Utilities';
import { IExcitingNewComponentProps } from './ExcitingNewComponent.types';
export class ExcitingNewComponent extends BaseComponent <IExcitingNewComponentProps, {}> {
public render() {
return(
<div>Hello World!</div>
);
}
}; // @todo: this ; needs to be removed- Create a class names file
ExcitingNewComponent.classNames.ts
import { memoizeFunction } from '../../Utilities';
import { mergeStyleSets} from '../../Styling';
export interface IExcitingNewComponentStyles {
/**
* Style for the root element in the default enabled/unchecked state.
*/
root?: IStyle;
}
export interface IExcitingNewComponentNames {
/**
* Root html container for this component.
*/
root?: string;
}
export const getClassNames = memoizeFunction((): IExcitingNewComponentNames => {
return mergeStyleSets({
root: []
});
});- Create an exports file
index.ts
export * from './ExcitingNewComponent';
export * from './ExcitingNewComponent.types';For any new component you should think of adding Unit tests, React functional tests and Screener tests to prevent regressions.
Add yourself to the Code owners file.