Skip to content

Commit b3346be

Browse files
jonnyelliotjonnyelliot
committed
Document each prop
1 parent d82bfad commit b3346be

File tree

2 files changed

+293
-12
lines changed

2 files changed

+293
-12
lines changed

‎src/theme/ThemeProvider.tsx

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,9 @@ import { augmentColor } from './themeMaterialUtil'
2424

2525
export interface ThemeProviderProps {
2626
/**
27-
* To override the font families used. default is used for Typography,
27+
* Should either return a `theme.FontOptions` object to replace the Committed theme defaults, or it should return undefined to use the Material-UI defaults.
28+
*
29+
* default is used for Typography,
2830
* text for Text, display for Display and mono for Monospace.
2931
*
3032
* typography: { fontFamily: '-apple-system, BlinkMacSystemFont, "San Francisco", Roboto, "Segoe UI", "Helvetica Neue"'},
@@ -39,13 +41,32 @@ export interface ThemeProviderProps {
3941
*
4042
*/
4143
createFonts?: () => FontOptions | undefined
44+
/**
45+
* Should either return a [set of material-ui color intentions](https://material-ui.com/customization/palette/#customization) to replace the Committed theme defaults, or it should return undefined to use the Material-UI defaults.
46+
*
47+
* The material-ui colors can be specified: palette.primary, palette.secondary, palette.error, palette.warning, palette.info or palette.success
48+
*
49+
* Additionally the committed-theme colors can be specified: palette.brand, palette.neutral
50+
*/
4251
createPaletteOptions?: () => PaletteOptions
52+
/**
53+
* Should either return material-ui shape options i.e. `{ borderRadius: xx }` to replace the Committed theme defaults, or it should return undefined to use the Material-UI defaults.
54+
*/
4355
createShape?: () => ShapeOptions | undefined
56+
/**
57+
* Should either return [material-ui spacing options](https://material-ui.com/customization/spacing/) to replace the Committed theme defaults, or it should return undefined to use the Material-UI defaults.
58+
*/
4459
createSpacing?: () => SpacingOptions | undefined
60+
/**
61+
* Should either return [material-ui typography options](https://material-ui.com/customization/typography/) to replace the Committed theme defaults, or it should return undefined to use the Material-UI defaults.
62+
*/
4563
createTypography?: () =>
4664
| TypographyOptions
4765
| ((palette: Palette) => TypographyOptions)
4866
| undefined
67+
/**
68+
* Should either return [material-ui overrides options](https://material-ui.com/customization/globals/) to replace the Committed theme defaults, or it should return undefined to use the Material-UI defaults. It is passed the palette created using the `createPaletteOptions()` prop
69+
*/
4970
createOverrides?: (palette: Palette) => Overrides | undefined
5071
children?: React.ReactNode
5172
}

‎src/theme/themeProvider.stories.mdx

Lines changed: 271 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -40,17 +40,30 @@ but others can be used if necessary.
4040
</ThemeProvider>
4141
```
4242

43+
## Custom Fonts
44+
45+
The optional `createFonts()` prop should either return a `theme.FontOptions` object to replace the Committed theme defaults, or it should return undefined to use the Material-UI defaults.
46+
4347
Custom font stacks can be provided for different typography components. You may need to separately load your font, using imports, links or css; see [example](https://github.com/commitd/components/tree/master/example).
4448
We recommend using [typefaces](https://github.com/KyleAMathews/typefaces)
4549

4650
<Preview>
4751
<Story name="default">
4852
<ThemeProvider
49-
fonts={{
50-
typography: { fontFamily: '"Helvetica Neue"' },
51-
text: { fontFamily: '"Times New Roman"' },
52-
display: { fontFamily: 'Arial, sans-serif', fontWeight: 700 },
53-
mono: { fontFamily: 'monospace', fontWeight: 100 }
53+
createFonts={() => {
54+
const fontFamily = 'Rockwell, sans-serif'
55+
return {
56+
typography: { fontFamily },
57+
heading: { fontFamily },
58+
subheading: { fontFamily },
59+
text: { fontFamily },
60+
display: {
61+
fontFamily
62+
},
63+
monospace: {
64+
fontFamily
65+
}
66+
}
5467
}}
5568
>
5669
<Heading.h2>Heading</Heading.h2>
@@ -63,20 +76,267 @@ We recommend using [typefaces](https://github.com/KyleAMathews/typefaces)
6376
</Story>
6477
</Preview>
6578

66-
Custom palette colours can be specified. For example, the primary, secondary or brand colors. Either variants of each shade must be specified, or a [material-ui color preset](https://material-ui.com/customization/color/#color) should be used.
79+
## Custom Colours
80+
81+
Custom palette colours can be specified. For example, the primary, secondary or brand colors.
82+
83+
The optional `createPalette()` prop should either return a [set of material-ui color intentions](https://material-ui.com/customization/palette/#customization) to replace the Committed theme defaults, or it should return undefined to use the Material-UI defaults.
84+
85+
The material-ui colors can be specified: palette.primary, palette.secondary, palette.error, palette.warning, palette.info or palette.success
86+
87+
Additionally the committed-theme colors can be specified: palette.brand, palette.neutral
6788

6889
<Preview>
69-
<Story name="colors">
70-
<ThemeProvider paletteColors={{ primary: blueGrey, brand: cyan }}>
71-
<Button color="primary">Custom Colours</Button>
90+
<Story name="custom-colors">
91+
<ThemeProvider
92+
createPaletteOptions={() => ({
93+
primary: {
94+
//blue
95+
light: '#4f83cc',
96+
main: '#01579b',
97+
dark: '#002f6c',
98+
contrastText: '#fff'
99+
},
100+
brand: {
101+
//blue
102+
light: '#4f83cc',
103+
main: '#01579b',
104+
dark: '#002f6c',
105+
contrastText: '#fff'
106+
},
107+
secondary: {
108+
//yellow
109+
light: '#ffff6b',
110+
main: '#fdd835',
111+
dark: '#c6a700',
112+
contrastText: '#000'
113+
}
114+
})}
115+
>
116+
<Button color="primary" mr={3}>
117+
Custom Primary Button
118+
</Button>
119+
<Button color="secondary">Custom Secondary Button</Button>
120+
</ThemeProvider>
121+
</Story>
122+
</Preview>
123+
124+
## Custom Shape
125+
126+
The optional `createShape()` prop should either return material-ui shape options i.e. `{ borderRadius: xx }` to replace the Committed theme defaults, or it should return undefined to use the Material-UI defaults.
127+
128+
<Preview>
129+
<Story name="custom-shape">
130+
<ThemeProvider
131+
createShape={() => ({
132+
borderRadius: 20
133+
})}
134+
>
135+
<Button color="primary" mr={3}>
136+
Custom Primary Button
137+
</Button>
138+
<Button color="secondary">Custom Secondary Button</Button>
72139
</ThemeProvider>
73140
</Story>
74141
</Preview>
75142

76-
An Example of custom theming, with blue and yellow colours:
143+
## Custom Spacing
144+
145+
Override the meaning of spacing props. These are dimensionless values given to things like margin and padding. All Material components will be affected, so Use with care.
146+
147+
The optional `createSpacing()` prop should either return [material-ui spacing options](https://material-ui.com/customization/spacing/) to replace the Committed theme defaults, or it should return undefined to use the Material-UI defaults.
148+
149+
<Preview>
150+
<Story name="custom-spacing">
151+
<C.ThemeProvider
152+
style={{ width: '100%', height: '100%', border: '1px' }}
153+
createSpacing={() => factor => factor * 10}
154+
>
155+
<Background width="1VH">
156+
<C.Column flexWrap="wrap">
157+
<C.Flex
158+
flexGrow={1}
159+
p={3}
160+
m={1}
161+
justifyContent="space-evenly"
162+
border="1px solid black"
163+
>
164+
<C.Column>
165+
<C.Button m={3}>Default</C.Button>
166+
<C.Button m={3} color="primary">
167+
Primary
168+
</C.Button>
169+
<C.Button m={3} color="secondary">
170+
Secondary
171+
</C.Button>
172+
</C.Column>
173+
<C.Column>
174+
<C.Button m={3} variant="outlined">
175+
Default
176+
</C.Button>
177+
<C.Button m={3} variant="outlined" color="primary">
178+
Primary
179+
</C.Button>
180+
<C.Button m={3} variant="outlined" color="secondary">
181+
Secondary
182+
</C.Button>
183+
</C.Column>
184+
<C.Column>
185+
<C.Button m={3} variant="text">
186+
Default
187+
</C.Button>
188+
<C.Button m={3} variant="text" color="primary">
189+
Primary
190+
</C.Button>
191+
<C.Button m={3} variant="text" color="secondary">
192+
Secondary
193+
</C.Button>
194+
</C.Column>
195+
<C.Column>
196+
<C.Button disabled={true} m={3}>
197+
Default
198+
</C.Button>
199+
<C.Button disabled={true} m={3} color="primary">
200+
Primary
201+
</C.Button>
202+
<C.Button disabled={true} m={3} color="secondary">
203+
Secondary
204+
</C.Button>
205+
</C.Column>
206+
</C.Flex>
207+
</C.Column>
208+
</Background>
209+
</C.ThemeProvider>
210+
</Story>
211+
</Preview>
212+
213+
## Custom Typography
214+
215+
The optional `createTypography()` prop should either return [material-ui typography options](https://material-ui.com/customization/typography/) to replace the Committed theme defaults, or it should return undefined to use the Material-UI defaults.
216+
217+
<Preview>
218+
<Story name="custom-typography">
219+
<C.ThemeProvider
220+
style={{ width: '100%', height: '100%', border: '1px' }}
221+
createTypography={() => ({
222+
htmlFontSize: 16,
223+
fontSize: 20,
224+
h1: {
225+
fontSize: '1.2rem'
226+
}
227+
})}
228+
>
229+
<Background width="1VH">
230+
<C.Flex
231+
flexGrow={1}
232+
p={3}
233+
pt={4}
234+
m={1}
235+
border="1px solid black"
236+
bgcolor="background.default"
237+
>
238+
<C.Box width={1 / 2}>
239+
<C.Typography>System Typography</C.Typography>
240+
<C.Heading.h2 gutterBottom>h2. Heading</C.Heading.h2>
241+
<C.Heading.h3 gutterBottom>h3. Heading</C.Heading.h3>
242+
<C.Heading.h4 gutterBottom>h4. Heading</C.Heading.h4>
243+
<C.Subheading.h3 gutterBottom>
244+
subheading. Lorem ipsum dolor sit amet, consectetur adipisicing
245+
elit. Quos blanditiis tenetur
246+
</C.Subheading.h3>
247+
<C.Typography variant="body1" gutterBottom>
248+
body1. Lorem ipsum dolor sit amet, consectetur adipisicing elit.
249+
Quos blanditiis tenetur unde suscipit, quam beatae rerum inventore
250+
consectetur.
251+
</C.Typography>
252+
<C.Typography variant="body2" gutterBottom>
253+
body2. Lorem ipsum dolor sit amet, consectetur adipisicing elit.
254+
Quos blanditiis tenetur unde suscipit, quam beatae rerum inventore
255+
consectetur.
256+
</C.Typography>
257+
</C.Box>
258+
<C.Box width={1 / 2}>
259+
<C.Text>Disply Typography</C.Text>
260+
<C.Display.d1 gutterBottom>d1. Heading</C.Display.d1>
261+
<C.Display.d2 gutterBottom>d2. Heading</C.Display.d2>
262+
<C.Text gutterBottom>
263+
Text. Lorem ipsum dolor sit amet, consectetur adipisicing elit.
264+
Quos blanditiis tenetur unde suscipit, quam beatae rerum inventore
265+
consectetur.
266+
</C.Text>
267+
<C.Monospace wrap>
268+
Monospace. Lorem ipsum dolor sit amet, consectetur adipisicing
269+
elit. Quos blanditiis tenetur unde suscipit, quam beatae rerum
270+
inventore consectetur.
271+
</C.Monospace>
272+
</C.Box>
273+
</C.Flex>
274+
</Background>
275+
</C.ThemeProvider>
276+
</Story>
277+
</Preview>
278+
279+
## Custom Global CSS Overrides
280+
281+
The optional `createOverrides()` prop should either return [material-ui overrides options](https://material-ui.com/customization/globals/) to replace the Committed theme defaults, or it should return undefined to use the Material-UI defaults. It is passed the palette created using the `createPaletteOptions()` prop
282+
283+
<Preview>
284+
<Story name="custom-overrides">
285+
<C.ThemeProvider
286+
style={{ width: '100%', height: '100%', border: '1px' }}
287+
createOverrides={palette => ({
288+
MuiButton: {
289+
contained: {
290+
color: 'white',
291+
backgroundColor: 'red'
292+
},
293+
containedPrimary: {
294+
color: 'black',
295+
backgroundColor: 'white'
296+
},
297+
containedSecondary: {
298+
color: 'white',
299+
backgroundColor: 'blue'
300+
}
301+
}
302+
})}
303+
>
304+
<Background width="1VH">
305+
<C.Caption>
306+
<C.Link href="/components/?path=/docs/components-button--default-story">
307+
Buttons
308+
</C.Link>
309+
</C.Caption>
310+
<C.Column flexWrap="wrap">
311+
<C.Flex
312+
flexGrow={1}
313+
p={3}
314+
m={1}
315+
justifyContent="space-evenly"
316+
border="1px solid black"
317+
>
318+
<C.Column>
319+
<C.Button m={3}>Default</C.Button>
320+
<C.Button m={3} color="primary">
321+
Primary
322+
</C.Button>
323+
<C.Button m={3} color="secondary">
324+
Secondary
325+
</C.Button>
326+
</C.Column>
327+
</C.Flex>
328+
</C.Column>
329+
</Background>
330+
</C.ThemeProvider>
331+
</Story>
332+
</Preview>
333+
334+
## Example theme
335+
336+
An example of a theme with all options customised:
77337

78338
<Preview>
79-
<Story name="custom-theming">
339+
<Story name="custom-theme">
80340
<C.ThemeProvider
81341
style={{ width: '100%', height: '100%', border: '1px' }}
82342
createPaletteOptions={() => ({

0 commit comments

Comments
 (0)