Installation

npm install csscomp

Theming

Start by creating a theme for your application and define your design system in here. The theme you define will be merged with the default theme which comes with a set of default values for the colors, space, radii, durations and breakpoints properties. Read more about how this works below.

const theme = {
  "fonts": {
    "base": "'Noto Sans', sans-serif",
    "title": "'Quantico', sans-serif",
    "code": "'Fira Code', sans-serif"
  },
  "colors": {
    "white": "#f5f5f5",
    "black": "#0a0a0a",
    "primary": "magenta",
    "secondary": "cyan",
    "grey": {
      "1": "#fcfcfc",
      "2": "#fafafa",
      "3": "#f7f7f7",
      "4": "#f5f5f5",
      "5": "#f2f2f2",
      ...
    }
  },
  "sizes": {},
  "fontSizes": {
    "xs": "0.75em",
    "s": "0.9em",
    "m": "1em",
    "l": "1.1em"
  },
  "borders": {
    "main": "1px solid",
    "thick": "2px solid"
  },
  "space": {
    "1": "0.25rem",
    "2": "0.5rem",
    "3": "0.75rem",
    "4": "1rem",
    "5": "1.25rem",
    ...
  },
  "radii": {
    "1": "0.1rem",
    "2": "0.2rem",
    "3": "0.3rem",
    "4": "0.4rem",
    "5": "0.5rem",
    ...
  },
  "durations": {
    "1": "0.25s",
    "2": "0.5s",
    "3": "0.75s",
    "4": "1s",
    "5": "1.25s",
    ...
  },
  "breakpoints": [
    "768px",
    "1024px"
  ]
}

• fonts affects the fontFamily property. The default theme doesn't provide any values for this property.
• fontSizes affects the fontSize property. The default theme doesn't provide any values for this property.
• colors affects color, backgroundColor, borderColor etc. The default theme only comes with a grey property which is a scale of greytones from 0 to 100, accessible like 'grey.25' or 'grey[25]'.
• spacings affects left, right, top, bottom, margin, padding etc. The default theme provides an 8pt grid system (divided by half) with rem values to be responsive to the root fontSize. The values are accessible by passing numbers like { padding: 4 }.
• sizes affects width, height, size etc. The default theme doesn't provide any values for this property.
• borders affects only the border property. The default theme provides the values shown in the example above.
• radii affects only the borderRadius property. The default theme provides the values shown in the example above
• durations affects transition, animation etc. The default theme provides the values shown in the example above
• breakpoints are used to create responsive styles together with array values, each value in the array will be defined in a media query based on the defined breakpoints, with exception to the first item to keep a mobile first approach. The default theme provides the values shown in the example above

After defining your theme wrap your application in a <CSSProvider /> and pass your theme to it.

export default function App () {
  return (
    <CSSProvider theme={theme}>
      ...
    </CSSProvider>
  )
}

Creating Components

Create components by calling a method matching the name of the element you want to create, pass styles to it in object format, or use the callback function to interact with props. These components support some pretty cool features under the hood.

• Property abbreviations are supported (mostly based on emmet.io)
• Theme variables are accessible by passing keys as string values
• Responsive styles are defined by passing arrays of values
• Template functions are available for color manipulation and spacings

Use plain objects:

import { comp } from 'csscomp'

export const Box = comp.div({})

export const Container = comp.div({
  d: 'flex',
  w: '100%',
  maw: ['800px', '1000px', '1200px', '1400px'],
  px: 6,
})

export const Section = comp.div({
  d: 'flex',
  bgi: `radial-gradient(
    {darken(primary, 5)} 25%,
    {darken(primary, 10)} 100%
  )`,
  c: 'white',
  py: [4, 8, 12, 16],
})

export const Button = comp.button({
  bgc: 'primary',
  c: 'white',
  p: 4,
  cur: 'pointer',
  trs: 'all .4s ease',

  '&:hover': {
    bgc: '{darken(primary, 5)}',
  }
})

export const Input = comp.input({
  bgc: 'white',
  bd: 'main',
  bdc: 'primary',
  px: 5,
  py: 2,

  '&:focus': {
    bd: 'thick',
    bdc: '{darken(primary, 5)}',
  }
})

Use functions when interacting with props:

import { comp } from 'csscomp'

export const Spacer = comp.div<{ gap?: number; direction?: 'column' | 'row' }>(
  ({ gap = 4, direction = 'column' }) => ({
    d: 'flex',
    fxd: direction,
    gap,
  
    ...(direction === 'column' ? {
      jc: 'center'
    } : {
      ai: 'center'
    })
  })
)

export const Checkbox = comp.div<{ checked?: boolean }>(
  ({ checked }) => ({
    pos: 'relative',
    d: 'flex',
    ai: 'center',
    jc: 'center',
    size: '1rem',
    bd: 'main',
    bdc: 'primary',
    bdrs: 2,
    cur: 'pointer',

    '&:after': {
      cont: "''",
      pos: 'absolute',
      size: '50%',
      bgc: checked ? 'primary' : 'transparent',
      bdrs: 1
    }
  })
)

Extending components

Components are extendable, just wrap an existing component in the comp constructor and use the return function to add more styling to the extended component.

import { comp } from 'csscomp'
import { Section, Button, Checkbox } from './components'

export const SectionHighlight = comp(Section)({
  bgc: 'primary',
  c: 'white',
  jc: 'center',
  py: [8, 16, 24, 32],
})

export const ButtonSecondary = comp(Button)({
  bgc: 'secondary',

  '&:hover': {
    bgc: 'secondaryDark',
  }
})

export const ButtonOutline = comp(Button)({
  bgc: 'transparent',
  c: 'primary',
  bd: 'main',
  bdc: 'primary',

  '&:hover': {
    bgc: 'transparent',
    c: 'primaryDark',
    bdc: 'primaryDark',
  }
})

export const CheckboxSecondary = comp(Checkbox)(({ checked }) => ({
  bdc: 'secondary',

  '&:after': {
    bgc: checked ? 'secondary' : 'transparent',
  }
}))

Using Components

Components are exposed with a css prop for inline styling, you can pass the same objects here as when defining the component. You can also change the element type of any component with the as prop.

Here is an example of a register form component built with the components defined in the previous section.

import { useState } from 'react'
import { Box, Spacer, Checkbox, Input, Button } from './components'

export const Register = () => {
  const [formData, setFormData] = useState({})

  const updateFormData = (event) => {
    setFormData({ ...formData, [event.target.name]: event.target.value })
  }

  const handleRegister = () => {
    // TODO: submit register form
  }

  return (
    <Box
      as='form'
      onSubmit={handleRegister}
      css={{
        w: '100%',
        p: 5,
        maw: '640px',
        bgc: 'white',
        bdrs: 4,
      }}
    >
      <Spacer>
        <Spacer gap={2}>
          <p>Username</p>
          <Input type='text' name='username' onChange={updateFormData} />
        </Spacer>
        <Spacer gap={2}>
          <p>Email</p>
          <Input type='text' name='email' onChange={updateFormData} />
        </Spacer>
        <Spacer gap={2}>
          <p>Password</p>
          <Input type='password' name='password' onChange={updateFormData} />
        </Spacer>
        <Spacer
          as='label'
          gap={2}
          direction='row'
          css={{ cur: 'pointer' }}
        >
          <Box
            as='input'
            type='checkbox'
            name='stayUpdated'
            onChange={updateFormData}
            css={{ d: 'none' }}
          />
          <Checkbox checked={new Boolean(formData.stayUpdated)} />
          <p>Stay updated</p>
        </Spacer>
        <Button type='submit'>Submit</Button>
      </Spacer>
    </Box>
  )

Global styling

You can create global stylesheet components with the css constructor. These components do not render anything but do inject styles into the document.

import { CSSProvider, css } from 'csscomp'
import { Theme } from './theme'

const RootStyle = css<{ rootFontSizes: string[] }>(
  ({ rootFontSizes }) => ({
    '*': {
      boxs: 'border-box'
    },

    ':root': {
      ff: 'base',
      fs: rootFontSizes || '16px',
      bgc: 'black',
      scrollBehavior: 'smooth',
      '-webkit-font-smoothing': 'antialiased',
      '-moz-osx-font-smoothing': 'grayscale',
    }
  })
)

const App = () => {
  return (
    <CSSProvider theme={Theme}>
      <RootStyle rootFontSizes={['14px', '15px', '16px']} />
      ...
    </CSSProvider>
  )
}

Keyframes

You can create keyframes definitions with the useKeyframes hook. When passed a function the hook will return a another function that accepts props and returns the animation name, when passed an object or string the hook will return the animation name directly.

import { comp, useKeyframes } from 'csscomp'

const SSpinner = comp.div<{ animName: string }>(({ animName }) => ({
  size: '5rem',
  bd: '.5rem solid',
  bdbc: 'transparent',
  bdr: '100%',
  anim: `${animName} 1s linear infinite`,
}))

export const Spinner = () => {
  const animName = useKeyframes({
    '0%': {
      tf: 'rotate(0deg)'
    },
    '100%': {
      tf: 'rotate(360deg)'
    }
  })

  return (
    <SSpinner animName={animName} />
  )
}

Reference

Abbreviations

| Abbreviation | Properties | | --- | --- | | pos | position | | d | display | | fx | flex | | fxf | flexFlow | | fxb | flexBasis | | fxd | flexDirection | | fxg | flexGrow | | fxs | flexShrink | | fxw | flexWrap | | ac | alignContent | | ai | alignItems | | as | alignSelf | | at | alignTracks | | jc | justifyContent | | ji | justifyItems | | js | justifySelf | | jt | justifyTracks | | or | order | | t | top | | b | bottom | | l | left | | r | right | | w | width | | miw | minWidth | | maw | maxWidth | | h | height | | mih | minHeight | | mah | maxHeight | | size | width, height | | m | margin | | my | marginTop, marginBottom | | marginY | marginTop, marginBottom | | mx | marginLeft, marginRight | | marginX | marginLeft, marginRight | | mt | marginTop | | mb | marginBottom | | ml | marginLeft | | mr | marginRight | | p | padding | | py | paddingTop, paddingBottom | | paddingY | paddingTop, paddingBottom | | px | paddingLeft, paddingRight | | paddingX | paddingLeft, paddingRight | | pt | paddingTop | | pb | paddingBottom | | pl | paddingLeft | | pr | paddingRight | | bg | background | | bgc | backgroundColor | | bgi | backgroundImage | | bgr | backgroundRepeat | | bgs | backgroundSize | | bgp | backgroundPosition | | bgpX | backgroundPositionX | | bgpY | backgroundPositionY | | bd | border | | bdt | borderTop | | bdb | borderBottom | | bdl | borderLeft | | bdr | borderRight | | bdw | borderWidth | | bdtw | borderTopWidth | | bdbw | borderBottomWidth | | bdlw | borderLeftWidth | | bdrw | borderRightWidth | | bdc | borderColor | | bdtc | borderTopColor | | bdbc | borderBottomColor | | bdlc | borderLeftColor | | bdrc | borderRightColor | | bdrs | borderRadius | | bdtlrs | borderTopLeftRadius | | bdtrrs | borderTopRightRadius | | bdblrs | borderBottomLeftRadius | | bdbrrs | borderBottomRightRadius | | bdi | borderImage | | c | color | | f | font | | fs | fontSize | | ff | fontFamily | | fw | fontWeight | | fst | fontStyle | | lh | lineHeight | | ta | textAlign | | ttf | textTransform | | td | textDecoration | | tdc | textDecorationColor | | op | opacity | | of | overflow | | trns | transition | | anim | animation | | animn | animationName | | animdur | animationDuration | | animtf | animationTimingFunction | | animdel | animationDelay | | animic | animationIterationCount | | animdir | animationDirection | | animfm | animationFillMode | | cur | cursor | | tf | transform | | us | userSelect | | vi | visibility | | whs | whiteSpace | | wob | wordBreak | | wos | wordSpacing | | wow | wordWrap | | z | zIndex | | gr | grid-area | | grac | grid-auto-columns | | graf | grid-auto-flow | | graw | grid-auto-rows | | grc | grid-column | | grce | grid-column-end | | grcs | grid-column-start | | grr | grid-row | | grre | grid-row-end | | grrs | grid-row-start | | grt | grid-template | | grta | grid-template-areas | | grtc | grid-template-columns | | grtr | grid-template-rows | | tsh | textShadow | | bdst | borderStyle | | bdtst | borderTopStyle | | bdbst | borderBottomStyle | | bdlst | borderLeftStyle | | bdrst | borderRightStyle | | bsh | boxShadow | | trnsp | transitionProperty | | trnsdur | transitionDuration | | trnsdel | transitionDelay | | trnstf | transitionTimingFunction | | ofx | overflowX | | ofy | overflowY | | objf | objectFit | | objp | objectPosition | | cont | content | | boxs | boxSizing |

Theme key usage

The theme keys that can be used per property. This set is defined because different instances of the theme can have the same keys.

| Property | Theme keys | | --- | --- | | flexBasis | sizes | | gridGap | space, sizes | | gridRowGap | space, sizes | | gridColumnGap | space, sizes | | gap | space, sizes | | top | space, sizes | | bottom | space, sizes | | left | space, sizes | | right | space, sizes | | width | sizes | | minWidth | sizes | | maxWidth | sizes | | height | sizes | | minHeight | sizes | | maxHeight | sizes | | size | sizes | | margin | space, sizes | | marginY | space, sizes | | marginX | space, sizes | | marginTop | space, sizes | | marginBottom | space, sizes | | marginLeft | space, sizes | | marginRight | space, sizes | | padding | space, sizes | | paddingY | space, sizes | | paddingX | space, sizes | | paddingTop | space, sizes | | paddingBottom | space, sizes | | paddingLeft | space, sizes | | paddingRight | space, sizes | | background | colors | | backgroundColor | colors | | border | borders, colors | | borderTop | borders | | borderBottom | borders | | borderLeft | borders | | borderRight | borders | | borderWidth | borderWidths | | borderTopWidth | borderWidths | | borderBottomWidth | borderWidths | | borderLeftWidth | borderWidths | | borderRightWidth | borderWidths | | borderColor | colors | | borderTopColor | colors | | borderBottomColor | colors | | borderLeftColor | colors | | borderRightColor | colors | | borderStyle | borderStyles | | borderTopStyle | borderStyles | | borderBottomStyle | borderStyles | | borderLeftStyle | borderStyles | | borderRightStyle | borderStyles | | borderRadius | radii | | borderTopLeftRadius | radii | | borderTopRightRadius | radii | | borderBottomLeftRadius | radii | | borderBottomRightRadius | radii | | boxShadow | shadows, colors | | color | colors | | fontSize | fontSizes | | fontFamily | fonts | | fontWeight | fontWeights | | lineHeight | lineHeights | | textShadow | shadows, colors | | columnGap | space, sizes | | letterSpacing | letterSpacings | | outlineColor | colors | | rowGap | space, sizes | | zIndex | zIndices | | fill | colors | | stroke | colors | | -webkit-text-fill-color | colors |