Skip to content

UI System & Variables

FrogUI uses a systematic approach to building your user interface. It utilizes design variables to keep styling values constrained so you can focus on building consistent users interfaces.

UI System

In FrogUI, the UI System is depicted via createSystem and comprises of Variables as input, that provides Primitive Components as output. The properties of the components may accept the provided Variables as values (e.g. backgroundColor="red400" or padding="8").

import { createSystem } from 'frog/ui'
 
export const {
  Box,
  Columns,
  Column,
  Divider,
  Heading,
  HStack,
  Icon,
  Image,
  Rows,
  Row,
  Spacer,
  Text,
  VStack,
  vars,
} = createSystem()

UI Variables

UI Variables are the source of truth for the UI System. They are used to define the styling property values for the Primitive Components.

The createSystem function accepts on object of variables. If no variables are passed to createSystem, FrogUI uses a default set of variables.

Here is an example of how you can define your own variables:

import { createSystem } from 'frog/ui'
 
export const {
  // ...
} = createSystem({
  colors: {
    text: '#000000',
    background: '#ffffff',
    blue: '#0070f3',
    green: '#00ff00',
    red: '#ff0000',
    orange: '#ffaa00',
  },
  fonts: {
    default: [
      {
        name: 'Open Sans',
        source: 'google',
        weight: 400,
      },
      {
        name: 'Open Sans',
        source: 'google',
        weight: 600,
      },
    ],
    madimi: [
      {
        name: 'Madimi One',
        source: 'google',
      },
    ],
  },
})

See the Variables API.

Consume Variables

UI Variables can be consumed by the Primitive Components.

The following table shows what variables are mapped to what style properties:

VariableProperty
colorsbackground, backgroundColor, borderColor, borderBottomColor, borderLeftColor, borderRightColor, borderTopColor, color
fontsfontFamily
fontSizesfontSize
iconsname (Icon component)
unitsborderBottomLeftRadius, borderBottomRightRadius, borderBottomWidth, borderLeftWidth, borderRadius, borderRightWidth, borderTopLeftRadius, borderTopRightRadius, borderTopWidth, borderWidth, bottom, height, gap, letterSpacing, lineHeight, margin, marginTop, marginBottom, marginLeft, marginRight, maxHeight, minHeight, maxWidth, minWidth, padding, paddingTop, paddingBottom, paddingLeft, paddingRight, right, top, width

Colors

The colors variable is used to constrain the available colors on color-based style properties (e.g. backgroundColor).

Code
import { createSystem } from 'frog/ui'
 
const { Box } = createSystem({
  colors: {
    black: '#000000',
    blue100: '#cce4ff',
    blue200: '#99ccff',
    blue300: '#66b3ff',
    blue400: '#3399ff',
    blue500: '#0070f3',
    blue600: '#005ce6',
    blue700: '#0047cc',
    blue800: '#0033b3',
    blue900: '#001a99',
  }
})
 
function Example() {
  return (
    <Box 
      backgroundColor="b
blue100
blue200
blue300
blue400
blue500
blue600
blue700
blue800
blue900
black
lue500" 
      height="48" 
      width="48" 
    />
  )
}

Fonts

The fonts variable is used to constrain the available fonts on the fontFamily style property.

import { createSystem } from 'frog/ui'
 
const { Box } = createSystem({
  fonts: {
    default: [
      {
        name: 'Open Sans',
        source: 'google',
        weight: 400,
      },
      {
        name: 'Open Sans',
        source: 'google',
        weight: 600,
      },
    ],
    madimi: [
      {
        name: 'Madimi One',
        source: 'google',
      },
    ],
  },
})
 
function Example() {
  return (
    <Box fontFamily="
default
madimi
madimi">
      Hello world
    </Box>
  )
}

Font Sizes

The fontSizes variable is used to constrain the available font sizes on the fontSize style property.

import { createSystem } from 'frog/ui'
 
const { Box, Text } = createSystem({
  fontSizes: {
    small: 0.01,
    medium: 0.02,
    large: 0.03,
  }
})
 
function Example() {
  return (
    <Box fontSize="
small
medium
large
small">
      Hello world
    </Box>
  )
}

Icons

The icons variable is used to set the icon collection for the <Icon> component.

import { createSystem } from 'frog/ui'
 
const { Icon } = createSystem({
  icons: 'lucide',
})
 
function Example() {
  return <Icon 
name: string | number | symbol
Icon name in the current icon collection.
name="zap" />
}

Units

The units variable is used to constrain the available units on spacing-based style properties (e.g. spacing).

import { createSystem } from 'frog/ui'
 
const { Box, Text } = createSystem({
  units: { 
    small: 0.01, 
    medium: 0.02, 
    large: 0.03, 
  } 
})
 
function Example() {
  return (
    <Box padding="
small
medium
large
small">
      Hello world
    </Box>
  )
}

Light & Dark Mode

FrogUI supports light and dark mode out of the box by providing color palettes for both modes via a colors export.

import { colors, createSystem } from 'frog/ui'
 
export const {
  // ...
} = createSystem({
  colors: colors.light
})