SwfSoft theming system for Styled Components
swf-theme generates a theme object that is designed to be used to configure a styled components theme, however it is not strickly opinionated and in addition to organizing values for styling, also exposes other useful methods for working with colors, typography, etc.
NOTE: Documentation is for version 2.0.1
yarn add @swfsoft/swf-themeor
npm install --save @swfsoft/swf-themeThis will return a theme object that can be used throughout your application:
import {createTheme} from '@swfsoft/swf-theme'
createTheme(<options>)NOTE: (this will accept custom defaults, to use your own defaults see "Typical Usage" below)
First install styled components:
npm install --save styled-components
Create a file somewhere in your project (generally close to the root or src directory):
src/theme.js
In theme.js instantiate and export your theme:
NOTE: for full list of defaults that can be overriden see below
import { createTheme } from '@swfsoft/swf-theme'
const theme = createTheme({
colors: {
// override default colors
primary: '#fff',
secondary: '#fff',
//NOTE: all default color types below
// add your own colors
myColor: '#fff',
},
breaks: {
// override breakpoints
tablet: {
num: 767,
val: '767px'
},
// small desktop
sdesk: {
num: 1100,
val: '1100px'
}
// large desktop
ldesk: {
num: 1480,
val: '1480px'
},
// NOTE: we encourage mobile first dev by using min-width media queries
},
// add your own data to be included in the theme
myData: 'useful data',
//... More defaults available - see below
})
export default themeStyled-components provides a helper function for generating global styles.
These global styles additionally have direct access to the theme just like a typical styled component.
HINT: These should be used sparingly and only target blanket html elements for reset, or default purposes. Generally, the real power of styled-components is to scope your styles to specific components.
Global styles can be exported from the theme.js file:
import {createGlobalStyle} from 'styled-components'
import { createTheme } from '@swfsoft/swf-theme'
export const ProjectGlobalStyles = createGlobalStyle`
body {
position: relative;
color: ${props => (props.theme.colors.black.val)};
}
`
const theme = createTheme({
colors: {
// override default colors
primary: '#fff',
secondary: '#fff',
...Swf-theme also provides a createGlobalThemeStyles function to generate pre-built global styles with some basic resets as well as options to include additional resets and presets.
NOTE: The global styles generated by Swf-theme must be passed into the createGlobalStyles function from styled-components.
In the theme.js file you can add:
import {createGlobalStyle} from 'styled-components'
import { createThemeGlobalStyles, createTheme } from './components/theme.js'
const theme = createTheme()
const themeGlobalStyles = createThemeGlobalStyles(theme, {
include: {
fluidHeadings: false
cssReset: true
milligram: false
// For include options info see below
}
})
// pass the global styles into the styled-component function to create a global styles component
export const ThemeGlobalStyles = createGlobalStyle(themeGlobalStyles)Global styles include options:
| Description | Default | |
|---|---|---|
| fluidHeadings | uses the fluidFontSizes function to generate fluid font sizes that can be use by applying a class of .fluid to h tags | false |
| cssReset | includes styled-reset | true |
| milligram | includes milligram css framework | false |
Styled-components provides a theme provider that should be included at the entry point to your app.
NOTE: GlobalStyles must be rendered inside of the ThemeProvider.
HINT: Render the ProjectGlobalStyles after the GlobalStyles from Swf-Theme to override these.
import { ThemeProvider, createGlobalStyle } from 'styled-components'
import theme, { ProjectGlobalStyles, ThemeGlobalStyles } from 'src/theme'
const App = ({ children }) => (
<ThemeProvider theme={theme}>
// global styles should be rendered inside of the ThemeProvider but before all other components
in your app
<ThemeGlobalStyles />
<ProjectGlobalStyles />
{children}
</ThemeProvider>
)The theme is automatically inserted as props in all styled components throughout the app:
For more information about using styled-components take a look at their documentation
import styled from 'styled-components'
const MyComponent = styled.div`
color: ${props => props.theme.colors.primary.val};
`| Option | Details | Defaults |
|---|---|---|
| colors | See defaults for options | See color defaults below |
| colorFallbacks | See defaults for options | See color fallbacks below |
| breaks | See defaults for options | See breaks defaults below |
| sizes | See defaults for options | See sizes defaults below |
| times | See defaults for options | See times defaults below |
Swf-theme will create an instance of a SwfColor handler class for every color that can be used to run a handful of useful color manipulation operations.
NOTE: Swf-theme uses TinyColor2 to perform color manipulation operations under the hood.
Available operations:
| Description | Default value | |
|---|---|---|
| light | Will lighten the color by a percentage value from 7-100 | 25 |
| dark | Will darken the color by a percentage value from 7-100 | 20 |
| bright | Will brighten the color by a percentage value from 7-100 | 25 |
| sat | Will saturate the color by a percentage value from 7-100 | 40 |
| desat | Will desaturate the color by a percentage value from 7-100 | 40 |
| tint | Will change the opacity to a percentage value | 25 |
| invert | Will invert the color based on the standard color wheel | n/a |
You may notice that the percentage value for operations is from 7-100. This is because values 0-6 are reserved for presets. These are useful for more consistent variations across the application.
The presets are automatically generated off of the colorFallback settings and are based on a percentage offset below and above the fallback, where each number from 0-6 represent a value either above or below the fallback percentage.
For example the light operation presets look like this (assuming the fallback is the default value of 25%):
| Lightens color by | Multiplier | |
|---|---|---|
| 0 | 10% | 0.4 |
| 1 | 15% | 0.6 |
| 2 | 20% | 0.8 |
| 3 | 25% | 1 |
| 4 | 30% | 1.2 |
| 5 | 35% | 1.4 |
| 6 | 40% | 1.6 |
NOTE: The same multipliers are used for light, dark, bright, sat, and desat operations.
tint operation does not use presets but if no value is passed in will use the fallback value (default is 25).
example usege with styled-components:
Lightens primary color value by 25% (if no value is passed in, it defaults to the equivalent preset of 3)
import styled from 'styled-componets'
const MyStyledDiv = styled.div`
color: ${props => props.theme.colors.primary.light().val};
`Lightens by 15% (based on preset of 1)
import styled from 'styled-componets'
const MyStyledDiv = styled.div`
color: ${props => props.theme.colors.primary.light(1).val};
`Lightens by 7% (only values 0-6 use presets, so we just use the raw value as a percentage)
import styled from 'styled-componets'
const MyStyledDiv = styled.div`
color: ${props => props.theme.colors.primary.light(7).val};
`NOTE: values above 100 are treated as 100%.
Operations can also be chained:
Lightens by 22% and changes opacity to 60%
import styled from 'styled-componets'
const MyStyledDiv = styled.div`
color: ${props => props.theme.colors.primary.light(22).tint(60).val};
`Calling .val
Since all operations return another SwfColor class instance you will need to use .val at the end to return the calculated color value.
This includes the raw color (remember this is also a SwfColor class instance):
import styled from 'styled-componets'
const MyStyledDiv = styled.div`
color: ${props => props.theme.colors.primary.val};
`Main defaults:
| Default | Intended usage | |
|---|---|---|
| primary | #0569b1 |
backgrounds, borders, etc |
| secondary | #f7a707 |
CTAs, links, emphasis, etc |
| aux1 | #7990ad |
accent color - less emphasis, sub-content for CTA, etc. |
| aux2 | #79a6ad |
Alternative accent color - rarely needed |
Utility defaults:
| Default | Description | |
|---|---|---|
| ok | #5bbb12 |
green - success color |
| err | #df1500 |
red - error/alert color |
| warn | #ff9900 |
orange - warning/info color |
| disabled | #c0c4c5 |
grey - disabled interactive elements |
| text | #3a3f42 |
dark grey - base font color |
Monochromatic defaults
| Default | Intended usage | |
|---|---|---|
| black | #000 |
General purpose |
| white | #FFF |
General purpose |
| grey | #868b8d |
General purpose |
By Name Defaults
| Default | |
|---|---|
| blue | #0e8be4 |
| brown | #866f3c |
| purple | #7032d0 |
| orange | #e88d00 |
| slate | #3a3f42 |
| midnight | #1c1e1f |
Fallback defaults
colorFallbacks: {
lighten: 25,
darken: 25,
saturate: 40,
desaturate: 40,
tint: 0.25
}Break-point presets. Also see Media below for media queries.
Default breaks:
{
tablet: {
num: 767
val: '767px'
},
// small desktop
sdesk: {
num: 1112
val: '1112px'
},
// large desktop
ldesk: {
num: 1480
val: '1480px'
},
}There are some media query builder helpers that use the values set in the breaks.
Example tablet media query:
import styled from 'styled-components'
const StyledComponent = styled`
${props => props.theme.media.tablet} {
display: block;
}
`This is the same as:
@media only screen and (min-device-width: ${props => (props.theme.breaks.tablet.px)}) {
display: block;
}Options:
| Targets | Media Query (based on default breaks) | |
|---|---|---|
| mobile | under tablet width (mobile only) | @media only screen and (max-width: 766px) |
| tablet | tablet width and above | @media only screen and (min-width: 767px) |
| sdesk | sdesk width and above | @media only screen and (min-width: 1112px) |
| ldesk | ldesk width and above | @media only screen and (min-width: 1480px) |
For css transitions, animations, etc.
HINT: When accessed via useTheme, these are also handy for setTimouts or triggered transitions in js that need to time with css transitions.
NOTE: Values are in milliseconds
defaults:
{
short: 100
med: 250
long: 500
ease: "ease-in-out"
// handy presets for css transitions
tranS: "100ms ease-in-out",
tranM: "250ms ease-in-out",
tranL: "500ms ease-in-out"
}Semi-opinionated values for maintaining global styles accross your app.
defaults:
{
fonts: {
// base font size (GlobalStyles automatically applies this to the body tag)
base: {
val: "15px",
num: 15
},
},
// global header
header: {
mobile: {
val: "40px",
num: 40
},
tablet: {
val: "50px",
num: 50
},
sdesk: {
val: "80px",
num: 80
}
}
// page gutters (spacing from left and right sides of the view port)
gutter: {
mobile: {
val: "1.1em",
num: 1.1
},
tablet: {
val: "0.5vw",
num: 0.5
},
sdesk: {
val: "4vw",
num: 4
},
ldesk: {
val: "6vw",
num: 6
}
}
}TODO: add docs
Function for generating font-sizes using css calculations. It returns css calculations based on options passed in (if no options passed in, will use defaults)
These font sizes are responsive and will grow or shrink based on screen dimensions within the min/max restrictions set for the fonts and viewport.
Example with styled-components:
import styled from 'styled-components'
const H1 = styled.h1`
${props =>
props.theme.fluidFontSize({
minSize: 22, // in pixels (min size the font will ever be)
maxSize: 45, // in pixels (max size the font will ever be)
minViewport: 320, // is fixed at minSize below this threshold (defaults to breaks.mobile)
maxViewport: 1480, // is fixed at maxSize above this threshold (defaults to breaks.ldesk)
})}
`fluidFontSizes is also exported from Swf-theme:
import styled from 'styled-components'
import { fluidFontSize } from '@swfsoft/swf-theme'
const H1 = styled.h1`
${fluidFontSize()}
`Swf-theme is built on typescript and exports the following types:
- Theme
- ThemeConfig
In order to use Swf-theme in typescript project with styled-components you will need to follow the steps laid out in styled-components for getting type support inside styled components:
npm install @types/styled-components
import 'styled-components'
import {Theme} from '@swfsoft/swf-theme'
declare module 'styled-components' {
export interface DefaultTheme extends Theme
}Now you should get type inference inside of styled components
MIT © swiftforge