# makeStyles spec ## Background `makeStyles` is a way how CSS is applied to core components and their variants as well as a utility used to implement style overrides for those components. ## Prior Art This section summarises previous approaches and their pros and cons. ### v0 approach `@fluentui/react-northstar` (aka v0 aka Stardust) uses CSS-in-JS. [Fela](https://github.com/robinweser/fela) CSS-in-JS library is used. #### Fela uses atomic CSS classes - one CSS property = one CSS class - all selectors have one class specificity - the same classes are reused anywhere in the application = smaller DOM #### CSS classes are added to DOM when used for the first time - only the classes that are used are added to DOM - that means those are added in non-deterministic order #### Two CSS classes setting the same property cannot be applied to the same element If there are two classes setting the same CSS property (`.r {color: red}` and `.b {color: blue}`) those can never be applied to the same element. As both classes have the same one class specificity, the rule defined later in the DOM will win. As the insertion order is non-deterministic, the resulting style would be non-deterministic as well. As a consequence, there is a couple of restrictions: - Shorthand css properties (`margin`) must be expanded before merging (to `margin-top`, `margin-right`, `margin-bottom`, `margin-left`). - To apply any overrides, it is not possible to just concatenate classes. Style object are deeply nested as they can contain styles for pseudo elements (`::before`), pseudo classes (`:hover`) or nested elements (`& .indicator`). Therefore style objects must be always deep merged and then the classes can be computed. - Due to the previous point, when parent component is passing style overrides to a child component it needs to know what kind of component the child is. If that is a non-FUI component, parent must pass the overrides as a list of classnames. If the child is a FUI component, the overrides must be passed as `styles` object so that the child can merge the styles correctly. This can be complicated as there are scenarios where the parent does not know what child it will render (especially when the styles are not applied by the direct child but somewhere else down the tree). - When overrides are passed from parent to child, the whole styles must be re-evaluated in runtime every time. Child can cache evaluated styles and classnames based on (limited) set of input props and state. And FUI components do that. But once style overrides are passed to the component, the overrides (`styles` or `variables`) and component styles object must be deep merged. #### Application overrides are part of the theme object All application-owned style overrides are part of the Theme object. Most of those are just one-off overrides. This results in a huge object (several files and thousands of lines per component) which is not tree-shakeable. There is also unnecessary and confusing indirection when defining overrides and no support for dead code elimination. Overrides are defined far away from their usage, see the example below. ```jsx // App // Component usage - I need to go to a completely different file to find out what styles the variable overrides. ; }; ``` ### Theme specific overrides ```jsx const useStyles = makeStyles({ root: { color: 'black', borderWidth: '2px' }, rootDarkTheme: { color: 'white', borderWidth: '0' }, // should be always dark and have no border }); // const classes = useStyles(); const className = mergeClasses( classes.root, someCondition /* some condition based on React Context */ && classes.rootDarkTheme, ); ``` ## Issues, open questions ### Theme-level style overrides As described in _Applying theme to styles_, a theme can only define tokens but can never change styles. There is a concern that this is not flexible enough and there might be a valid scenario where theme-specific style overrides will be required. How would that be implemented? Example API: ```js // The Button styles need an id to pull overrides // from the theme: const makeStyles({ id: 'Button', { ... } }); // The theme needs to be able to define them: const theme = { styles: { Button: { // id? styles: makeStyles({ ... }) // maybe? } } } ``` ### CSS variables and shorthand expand Having a token which defines multiple values for a CSS shorthand, how can we expand the CSS property? ```js fourValuesPaddingToken = '1 2 3 4' // results in --four-values-padding: 1 2 3 4 padding: var(--four-values-padding); // how can this be expanded to padding-top, padding-right... ``` ### Impact on bundle size What is the impact on bundle size having all the expanded styles in bundle? Can we hash property keys (`display`,`display:hover`)?