Theme

The theme object is what defines our design system. It contains things like the color palette, units for space and type sizes, font families, responsive breakpoints, box shadows, and more. Blockstack UI is based on the Styled System theme specification.

Colors

All of the colors come from a theme.colors object. By default these colors can be referenced by the color, borderColor, and backgroundColor, fill, stroke, style props. For example, passing blue.100 to a bg prop would result in the color: #e3e5ff. Each color typically contains a range from 50-900. You can also pass blue with no range.

// theme.js
export
default
{
colors
:
{
transparent
:
'transparent'
,
current
:
'currentColor'
,
black
:
'#000000'
,
white
:
'#ffffff'
,
blue
:
Object
.
assign
(
'#3700ff'
,
{
50
:
'#f2f2ff'
,
100
:
'#e3e5ff'
,
150
:
'#D8DAF3'
,
200
:
'#c5ccff'
,
300
:
'#aab3ff'
,
// ...
900
:
'#5548ff'
,
}
)
,
// ...
}
,
}
;

blue

blue
#3700ff
blue.900
#5548ff
blue.400
#AAB3FF
blue.300
#C5CCFF
blue.200
#E3E5FF
blue.100
#F2F2FF

ink

ink
#0f1117
ink.900
#222933
ink.600
#677282
ink.400
#A7A7AD
ink.300
#C8C8CC
ink.250
#C8C8CC
ink.200
#E7E7E8
ink.150
#F4F4F5
ink.100
#F9F9FC
ink.50
#f4f4f5

UI feedback

feedback.info
#00d4ff
feedback.warning
#f7aa00
feedback.success
#00a73e
feedback.error
#de0014

darken

darken.150
rgba(15, 17, 23, 0.15)
darken.100
rgba(15, 17, 23, 0.1)
darken.50
rgba(15, 17, 23, 0.05)

Typography

To manage Typography options, the theme object supports the following keys:

  • fonts (font families)
  • fontSizes
  • fontWeights
  • lineHeights
  • letterSpacings
// example theme object
export
default
{
colors
:
{
...
}
,
fonts
:
{
heading
:
`
'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"
`
,
body
:
`
'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"
`
,
mono
:
`
SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace
`
}
,
fontSizes
:
[
12
,
14
,
16
,
20
,
24
,
28
,
32
,
36
,
48
,
64
,
96
,
128
]
,
fontWeights
:
{
hairline
:
100
,
thin
:
200
,
light
:
300
,
normal
:
400
,
medium
:
500
,
semibold
:
600
,
bold
:
700
,
extrabold
:
800
,
black
:
900
}
,
lineHeights
:
{
normal
:
"normal"
,
none
:
"1"
,
shorter
:
"1.333"
,
short
:
"1.4"
,
base
:
"1.5"
,
tall
:
"1.625"
,
taller
:
"2"
}
,
letterSpacings
:
{
tighter
:
"-0.02em"
,
tight
:
"-0.01em"
,
normal
:
"0"
,
wide
:
"0.025em"
,
wider
:
"0.05em"
,
widest
:
"0.1em"
}
}
;

Breakpoints

To configure the default breakpoints used in responsive array values, add a breakpoints array to your theme. These values will be used to generate mobile-first (i.e. min-width) media queries, which can then be used to apply responsive styles.

For example, you can write <Box fontSize={["14px", "16px"]}/> to make the fontSize responsive.

// theme.js
export
default
{
breakpoints
:
[
'30em'
,
'48em'
,
'62em'
,
'80em'
]
,
}
;

Spacing

The space key allows you to customize the global spacing and sizing scale for your project. By default these spacing value can be referenced by the padding, margin, and top, left, right, bottom styles.

export
default
{
space
:
{
'0'
:
'0'
,
px
:
'1px'
,
'1'
:
'0.25rem'
,
'2'
:
'0.5rem'
,
'3'
:
'0.75rem'
,
'4'
:
'1rem'
,
'5'
:
'1.25rem'
,
'6'
:
'1.5rem'
,
'8'
:
'2rem'
,
'10'
:
'2.5rem'
,
'12'
:
'3rem'
,
'16'
:
'4rem'
,
'20'
:
'5rem'
,
'24'
:
'6rem'
,
'32'
:
'8rem'
,
'40'
:
'10rem'
,
'48'
:
'12rem'
,
'56'
:
'14rem'
,
'64'
:
'16rem'
,
}
,
}
;

By default, Blockstack UI includes a comprehensive numeric spacing scale inspired by Tailwind CSS. The values are proportional, so 1 spacing unit is equal to 0.25rem, which translates to 4px by default in common browsers.

Mental model: If you need a spacing of 40px, divide it by 4. That'll give you 10. Then use it in your component as ml={10}.

NameSpacePixels
000px
px1px1px
10.25rem4px
20.5rem8px
30.75rem12px
41rem16px
51.25rem20px
61.5rem24px
82rem32px
102.5rem40px
123rem48px
164rem64px
205rem80px
246rem96px
328rem128px
4010rem160px
4812rem192px
5614rem224px
6416rem256px

Sizes

The sizes key allows you to customize the global sizing of components you build for your project. By default these spacing value can be referenced by the width, height, and maxWidth, minWidth, maxHeight, minHeight styles.

export
default
{
sizes
:
{
...
theme
.
space
,
full
:
'100%'
,
'3xs'
:
'14rem'
,
'2xs'
:
'16rem'
,
xs
:
'20rem'
,
sm
:
'24rem'
,
md
:
'28rem'
,
lg
:
'32rem'
,
xl
:
'36rem'
,
'2xl'
:
'42rem'
,
'3xl'
:
'48rem'
,
'4xl'
:
'56rem'
,
'5xl'
:
'64rem'
,
'6xl'
:
'72rem'
,
}
,
}
;

For a component like this: <Box w={4} h={3} /> will generate an empty div with width set to 1rem or 16px and height set to 0.75rem or 12px

Configuration reference

Except for breakpoints, colors, and spacing, all of the keys in the theme object map to one of Blockstack UI's core theme. All of these keys can be replaced or extended.

See the full reference table of properties.