| 1 | ---
|
| 2 | title: Theme
|
| 3 | isExperimentalPackage: true
|
| 4 | ---
|
| 5 |
|
| 6 | 🚧 — Under construction
|
| 7 |
|
| 8 | The theme packages exports a set of objects and utilities that are used
|
| 9 | internally to create Spark Web components as well as for consumers to be able to
|
| 10 | override
|
| 11 |
|
| 12 | ## useTheme
|
| 13 |
|
| 14 | The `useTheme` hook returns an object with our theme tokens along with a set of
|
| 15 | styling utilities.
|
| 16 |
|
| 17 | The theme will always be in the same shape, but the values can be overridden by
|
| 18 | [passing in a custom theme to the SparkProvider](/package/core).
|
| 19 |
|
| 20 | Theme tokens differ slightly from the values passed into the provider (or the
|
| 21 | defaultTokens if you don't provide a theme) as they are run through the
|
| 22 | [decorateTokens](https://github.com/brighte-labs/spark-web/blob/6fc8d1bc37e25d0cd622bc37f68a1d92eb5961b5/packages/theme/src/make-theme.ts#L101)
|
| 23 | function which add some extra values that should never change (and therefore
|
| 24 | aren't themeable) as well as using
|
| 25 | [Capsize](https://seek-oss.github.io/capsize/) to add tokens we need to trim
|
| 26 | space above capital letters and below the baseline so spacing between elements
|
| 27 | is consistent and doesn't vary depending on line-height, font-size etc.
|
| 28 |
|
| 29 | For more documentation about our tokens, please see the
|
| 30 | [tokens reference page](/reference/tokens).
|
| 31 |
|
| 32 | #### mapResponsiveProp
|
| 33 |
|
| 34 | Returns either the string value of the token provided to it, or an array which
|
| 35 | maps to [our breakpoints](/reference/tokens#breakpoint) (where index 0 refers to
|
| 36 | the mobile breakpoint, 1 is the tablet breakpoint and so on).
|
| 37 |
|
| 38 | ### Theme utils
|
| 39 |
|
| 40 | #### mapResponsiveScale
|
| 41 |
|
| 42 | Helper for mapping keys/breakpoint map to a theme scale e.g.
|
| 43 |
|
| 44 | ```jsx
|
| 45 | mapResponsiveProp('small', { small: 8, large: 16 }); // 8
|
| 46 | mapResponsiveProp(
|
| 47 | { mobile: 'small', tablet: 'large' },
|
| 48 | { small: 8, medium: 12, large: 16 }
|
| 49 | ); // [8, 16]
|
| 50 | ```
|
| 51 |
|
| 52 | #### optimizeResponsiveArray
|
| 53 |
|
| 54 | TODO
|
| 55 |
|
| 56 | #### responsiveRange
|
| 57 |
|
| 58 | Designed to be used alongside `optimizeResponsiveArray`.
|
| 59 |
|
| 60 | #### responsiveStyles
|
| 61 |
|
| 62 | TODO
|
| 63 |
|
| 64 | #### resolveResponsiveProps
|
| 65 |
|
| 66 | TODO
|
| 67 |
|
| 68 | ## defaultTokens
|
| 69 |
|
| 70 | This is the default tokens for the Brighte theme _before_ they've been
|
| 71 | decorated.
|
| 72 |
|
| 73 | ## makeBrighteTheme
|
| 74 |
|
| 75 | This function
|
| 76 |
|
| 77 | - decorates to passed in tokens
|
| 78 | - decorates them
|
| 79 | - works out if the background tokens are dark or light
|
| 80 | - adds the [theme utils](#theme-utils)
|
| 81 |
|
| 82 | Pass the result of this function into the
|
| 83 | [SparkProvider](/package/core#sparkprovider) if you want to override the default
|
| 84 | theme.
|