# Theming
*As of Jan 25th, 2021*

## How to apply theme?
### Scenario: V7/V8 components
Provider name: `ThemeProvider`
Theme shape: [Theme](https://github.com/microsoft/fluentui/blob/master/packages/theme/src/types/Theme.ts#L129), [PartialTheme](https://github.com/microsoft/fluentui/blob/master/packages/theme/src/types/Theme.ts#L168)

Example code:

import { ThemeProvider, Checkbox } from '@fluentui/react';

// overriding default Fluent theme
const appThemeOverrides = {
   ...
};

const App = () => (
 <ThemeProvider theme={appThemeOverrides}>
    <Checkbox label='Checkbox' />
 </ThemeProvider>
);

### Scenario: converged components
Provider name: `ThemeProvider`
Theme shape: [Theme](https://github.com/microsoft/fluentui/blob/master/packages/theme/src/types/Theme.ts#L129), [PartialTheme](https://github.com/microsoft/fluentui/blob/master/packages/theme/src/types/Theme.ts#L168)

Example code:

import { ThemeProvider } from '@fluentui/react-theme-provider';
import { Button } from '@fluentui/react-button';

// overriding default Fluent theme
const appThemeOverrides = {
   ...
};

const App = () => (
 <ThemeProvider theme={appThemeOverrides}>
    <Button>Button</Button>
 </ThemeProvider>
);

### Scenario: Northstar component
Provider name: `Provider`
Theme shape: [ThemeInput](https://github.com/microsoft/fluentui/blob/master/packages/fluentui/styles/src/types.ts#L209)

import React from 'react'
import { Button, Provider } from '@fluentui/react-northstar'

const App = () => (
  <Provider theme={teamsTheme}>
    <Button content="Button" />
  </Provider>
)

### Scenario: V7/8 component & converged component

import React from 'react'
import { ThemeProvider, Checkbox } from '@fluentui/react';
import { Button } from '@fluentui/react-button'

const App = () => (
   /* applies theme to both `Button` and `Checkbox` */
    <ThemeProvider>
        <Button content="Button" />
        <Checkbox label="Checkbox" />
    </ThemeProvider>
)

### Scenario: Northstar component & converged component

import React from 'react'
import { Avatar } from '@fluentui/react-avatar';
import { Button, Provider } from '@fluentui/react-northstar';

const App = () => (
  /* `Provider` applies theme to `Button`, not `Avatar`*/
  <Provider theme={teamsTheme}>
    /* `ThemeProvider` applies theme to `Avatar`, not `Button`*/
    <ThemeProvider>
        <Button content="Button" />
        <Avatar name="John Doe" />
    </ThemeProvider>
  </Provider>
)

## How to create theme?

| Scenario | Default Theme | Theme designer |
| -------- | -------- | -------- |
| V7/8 component | Fluent |https://aka.ms/themedesigner |
| converged component | Fluent | TBD |
| northstar component | Teams | N/A |

Current state:
- No change for northstar components.
- For coverged component (e.g `react-button`)
- component default styles are authored based on V7/8 theme (e.g. `palette`, `semanticColors`);
- component default variants and styles are defined in each component package, not inside default theme.
- app author is recommended to use `components.{COMPONENT_NAME}.variants` instead of `semanticColors` to theme a particular component.

Future state:
- No change for northstar components.
- For converged component
- `tokens` should be used instead of `palette`
- `variants` should be used instead of `semanticColors`

What needs to be done for future state?
- [ ] finalize interface for global tokens
- [ ] Replace `palette` and `semanticColors` usages in converged components
- [ ] update theme-designer accordingly

-----------------

*As of Feb 2nd, 2021*

## How to apply theme?
### Scenario: V7/V8 components
Provider name: `ThemeProvider` (in `@fluentui/react`)
Theme shape: [Theme](https://github.com/microsoft/fluentui/blob/master/packages/theme/src/types/Theme.ts#L129), [PartialTheme](https://github.com/microsoft/fluentui/blob/master/packages/theme/src/types/Theme.ts#L168)

Example code:

import { ThemeProvider, Checkbox } from '@fluentui/react';

// overriding default Fluent theme
const appThemeOverrides = {
   ...
};

const App = () => (
 <ThemeProvider theme={appThemeOverrides}>
    <Checkbox label='Checkbox' />
 </ThemeProvider>
);

### Scenario: converged components
Provider name: `ThemeProvider` (in `@fluentui/react-theme-provider`)
Theme shape: [Theme](https://github.com/microsoft/fluentui/blob/master/packages/react-theme/src/types.ts#L244), [PartialTheme](https://github.com/microsoft/fluentui/blob/master/packages/react-theme/src/types.ts#L256)

Example code:

import { ThemeProvider } from '@fluentui/react-theme-provider';
import { Button } from '@fluentui/react-button';

// overriding default Fluent theme
const appThemeOverrides = {
   ...
};

const App = () => (
 <ThemeProvider theme={appThemeOverrides}>
    <Button>Button</Button>
 </ThemeProvider>
);

### Scenario: Northstar component
Provider name: `Provider`
Theme shape: [ThemeInput](https://github.com/microsoft/fluentui/blob/master/packages/fluentui/styles/src/types.ts#L209)

import React from 'react'
import { Button, Provider } from '@fluentui/react-northstar'

const App = () => (
  <Provider theme={teamsTheme}>
    <Button content="Button" />
  </Provider>
)

### Scenario: V7/8 component & converged component

import React from 'react'
import { ThemeProvider, Checkbox } from '@fluentui/react';
import { Button } from '@fluentui/react-button'
import { ThemeProvider as ConvergedThemeProvider } from '@fluentui/react-theme-provider'

const App = () => (
   /* applies theme to both `Button` and `Checkbox` */
    <ThemeProvider>
      <ConvergedThemeProvider>
        <Button content="Button" />
        <Checkbox label="Checkbox" />
      </ThemeProvider>
    </ThemeProvider>
)

### Scenario: Northstar component & converged component

import React from 'react'
import { Avatar } from '@fluentui/react-avatar';
import { Button, Provider } from '@fluentui/react-northstar';

const App = () => (
  /* `Provider` applies theme to `Button`, not `Avatar`*/
  <Provider theme={teamsTheme}>
    /* `ThemeProvider` applies theme to `Avatar`, not `Button`*/
    <ThemeProvider>
        <Button content="Button" />
        <Avatar name="John Doe" />
    </ThemeProvider>
  </Provider>
)