_{Many thanks to Clojurists Together for generously supporting this project!}

Kushi

Kushi is a foundation for building web UI with ClojureScript.

Explore Kushi UI Playground »

Kushi Quickstart »

Features

• 100% Clojure(Script)

• Suite of accessible, headless UI components

• Themeable design system foundation

• Co-location of styling at the element level

• Shorthand styling syntax shadows CSS standard

• Supports media-queries, psuedos, and combo selectors

• Leverages CSS variables for runtime dynamics

• Composable, user-defined shared classes

• Many useful CSS utility classes

• Default industry-standard breakpoint scale

• Auto-generated selectors to avoid pontential collisions

• Flexible selector prefixing options

• Helpers for typography, keyframe animations, and more

• Enhanced debugging via metadata

• Detailed, human-readable warnings

• Framework & build-tool agnostic

• Generates interactive UI documentation

Table of Contents

• Introduction
  
• Project Status
  
• Setup and usage
  
• Kushi styling syntax
  
• Shared styles
  
• Styles as tokenized keywords
  
• Working with media queries
  
• Pseudos and combo selectors
  
• Selector prefixing options
  
• Defining CSS at-rules
  
• Injecting stylesheets
  
• Configuration options
  
• Actionable warnings
  
• Defining components
  
• Kushi Playground
• Usage with build tools
  
• Contributing
  
• License

Introduction

Kushi provides a comprehensive solution for creating and evolving web-based UI projects in ClojureScript.

The following features work in concert, making it easy to roll your own design system:

• A set of professionally designed, themeable, headless UI components
• Solid foundation of hand-tuned global design tokens
• Functional styling engine
• Configurable theming

Usage of Kushi's design system and component library is completly optional. You can just use the styling engine as a pure ClojureScript alternative to mainstream JS solutions such as Tailwind, Emotion, etc.

Project status

Current version is pre-release intended for early adopters and anyone who would like to provide feedback. New 1.0 alphas will be released frequently, while I continue to make improvements/changes/additions. Working towards a stable 1.0 release by end of 2024 or Q1 of 2025.

Please report anything unexpected on GitHub Issues.

Setup and Usage

Usage with Reagent + Shadow-CLJS is currently recommended.

Please check out Kushi Quickstart for a well commented, feature-complete minimal project template. This is probably the easiest way to get started with Kushi.

Checkout the interactive playground of pre-built headless UI components.

Build system basics

Currently, Kushi depends on the shadow-cljs build-hook system to generate and bundle CSS. The sx and css macros return an html attributes map or class string, respectively. The CSS is transpiled and generated in a separate analyzation phase triggered by kushi.css.build.analyze/hook. By default, lightningcss is leveraged to achieve fast and efficient minification, bundling, vendor prefixing, and syntax-lowering (to target older browsers).

Kushi styling syntax

Basic usage of the css macro

Styles are co-located at the element level. You don't need to think about choosing an appropriate classname, as it is generated automatically. The macro kushi.core/css takes any number of styles:

(ns myns.core
  (:require
   [kushi.core :refer [css]]))

(defn my-component []
 [:div
  {:class (css :c--red
               :ta--c
               :fs--18px)}])

As you can see in the above example, Kushi promotes a simple tokenized-keyword-based shorthand grammar which shadows standard CSS. This approach is similar solutions such as Tachyons and Tailwind, but much more helpful in learning actual CSS, and much more intuitive if you are an existing CSS expert.

In the example above, the css macro would expand to the following (shown in context):

(defn my-component []
 [:div
  {:class "myns_core__L7C11"}])

When your build finishes, the following css will be written to disk:

.myns_core__L7C11 {
  color: red;
  text-align: center;
  font-size: 18px;
}

Check out the Styles as tokenized keywords section for more details on Kushi's shorthand grammar.

Note that the shorthand grammar is totally optional - you can also write these tokenized keywords with fully hydrated props and values.

(defn my-component []
 [:div
  {:class (css :color--red
               :text-align--center
               :font-size--18px)}])

If you have an aversion to the tokenized keyword approach, you can also just use a map - check out the Using maps section.

Supplying additional classes to the css macro

You can supply additional classes as needed. These classes might be shared classes that you have defined, utility classes that ship with Kushi, or classes from 3rd party libraries. They must take the form of a keyword prefixed with a dot:

(defn my-component []
 [:div
  {:class (css :.absolute-centered
               :.text-large
               :c--red
               :ta--c
               :fs--18px)])

The above call to css would expand to the following class string:

"myns_core__L7C11 absolute-centered text-large"

Supplying dynamic classes to the css macro

If you want to supply classes conditionally, based on runtime logic, you can do so like this:

(defn my-component [positioning-class]
 [:div
  {:class (css positioning-class
               :c--red
               :ta--c
               :fs--18px)])

;; At call site
[my-component "absolute-centered"]

The above call to css would expand to the following:

(str "myns_core__L7C11 " positioning-class)

;; At runtime, based on the example call-site value, this would resolve to:
"myns_core__L7C11 absolute-centered"" 

You can also define more than one class using css and apply one conditionally:

(defn my-component [k]
 (let [foo-class (css :c--red :bgc--black :fs--48px)
       bar-class (css :c--blue :bgc--gray :fs--28px)
       baz-class (css :c--orange :bgc--beige :fs--18px)
       my-class (case k
                  :foo foo-class
                  :bar bar-class
                  :baz baz-class
                  nil)]
   [:div
    {:class my-class}])

;; At call site
[my-component :foo]

Using css custom properties (aka css variables) with the css macro.

In the tradition of Sass and Less, Kushi uses a leading $ syntax for css custom properties

The example below uses :c--$red-500, which will set the color property to var(--red-500). In this case, var(--red-500) is a global variable that is predefined within the design token system that ships with Kushi.

(defn my-component []
 [:div
  {:class (css :.absolute
               font-size-class
               :c--$red-500
               :ta--c
               :fs--18px)])

Supplying dynamic values for individual css properties with the css macro.

If you want to supply dynamic values for individual css properties, you can utilize the kushi.core/css-vars macro, or the kushi.core/css-vars-map macro (if you are using React under the hood). This will create a "local" custom css property in the style attribute that you will then reference within your call to css using the $ css variable syntax:

(defn my-component [text-color]
 [:div
  {:style (css-vars text-color)
   :class (css :.absolute
               font-size-class
               :c--$text-color
               :ta--c
               :fs--18px)])

;; At call site
[my-component "red"]

In the example above, the css macro, and the css-vars macro would expand to the following (shown in context):

(defn my-component [text-color]
 [:div
  {:style (str "--text-color: " text-color)
   :class "myns_core__L7C11"}])

When your build finishes, the following css will be written to disk:

.myns_core__L7C11 {
  color: var(--text-color);
  text-align: center;
  font-size: 18px;
}

If you are using Kushi with a React abstraction such as reagent, you will probably want use the kushi.core/css-vars-map macro instead, which would expand to this:

(defn my-component [text-color]
 [:div
  {:style {"--text-color" text-color}
   :class "myns_core__L7C11"}])

Reducing ceremony with the sx macro

If you don't need to use dynamic values as in the example above, and you don't need to supply html attributes other than class, you can use use the kushi.core/sx macro to style elements and reduce some of the boilerplate. It works the same as the css macro, but returns a map with a :class entry instead of a string:

(ns myns.core
  (:require
   [kushi.core :refer [css sx]]))

(defn my-component []
 [:div
  (sx :c--red
      :ta--c
      :fs--18px)}])

Which would expand to the following (shown in context):

(defn my-component []
 [:div
  {:class "myns_core__L7C11"}])

Modifier syntax: pseudo-classes

Kushi offers a modifier syntax for conveniently describing things like pseudo-classes:

(css :c--red
     :hover:c--blue
     :hover:td--u)

The above example produces the following css:

.myns_core__L7C11 {
  color: red;
  &:hover {
    color: blue;
    text-decoration: underline;
  }
}

Modifier syntax: nested selectors

You can use the same modifier syntax for nested selectors. Underscore chars _ are transformed to a spaces:

(css :c--red
     :>p:c--teal
     :>p.foo:c--orange
     :_a:c--purple)

The above example produces the following css:

.myns_core__L7C11 {
  color: red;
  &>p {
    color: teal;
    &.foo {
      color: orange;
    }
  }
  & a {
    color: purple;
  }
}

Modifier syntax: breakpoints

You can use the same modifier syntax for media queries:

(css :fs--18px
     :lg:fs--22px)

The above example produces the following css:

.myns_core__L7C11 {
  font-size: 18px;
  @media (min-width: 1024px) {
    font-size: 22px;
  }
}

See the Working with media queries section for more details on media queries and Kushi's default breakpoint scale.

Modifier syntax: dark-mode

Using the modifier syntax for dark-mode styling:

(css :c--black
     :dark:c--white)

The above example produces the following css:

.myns_core__L7C11 {
  color: black; 
  .dark & {
    color: white;
  }
}

See the Working with dark-mode section for more details on media queries and Kushi's built-in functionality for dark-mode.

Modifier syntax: stacking

These modifiers are designed to be "stacked". They must be separated with a colon and the order must be media-query (optional), dark-mode (optional), then any sequence of selectors and pseudo-class/pseudo-elements:

(css :c--black
     :hover:c--red
     :lg:hover:c--orange
     :dark:c--white
     :dark:hover:c--hotpink
     :lg:dark:hover:c--yellow
     :lg:dark:hover:>div.foo:c--silver)

The above example produces the following css:

.myns_core__L7C11 {
  color: black;
  @media(min-width: 1024px) {
    .dark & {
      &:hover {
        color: yellow;
        &>div.foo {
          color: silver;
        }
      }
    }
    &:hover {
      color: orange;
    }
  }
  .dark & {
    color: white;
    &:hover {
      color: hotpink;
    }
  }
  &:hover {
    color: red;
  }
}

Using maps

If Kushi's tokenized keyword syntax isn't your speed, your can also just use maps to describe your all your styles:

(css {:color      :red
      :text-align :center
      :font-size  :18px})

You can also mix in maps with tokenized keywords. Maps are very useful when you want to use nesting to avoid repetition:

(css :c--red
     {:hover {:c   :blue
              :td  :underline
              :bgc :yellow}})

The above example produces the following css:

.myns_core__L7C11 {
  color: red;
  &:hover {
    color: blue;
    text-decoration: underline;
    background-color: yellow;
  }
}

You can nest as deep as you want:

(css :c--red
     {:>p {:hover {:c   :blue
                   :td  :underline
                   :bgc :yellow
                   :_a  {:c   :purple
                         :td  :none
                         :bgc :pink}}})

The above example produces the following css:

.myns_core__L7C11 {
  color: red;
  &>p {
    &:hover {
      color: blue;
      text-decoration: underline;
      background-color: yellow;
      & a {
        color: purple;
        text-decoration: none;
        background-color: pink;
      }
    }
  }
}

The following is a more complex example taken from a working codebase. There is a single map entry that defines styles for some direct descendant elements in a sidenav. The styles only apply, however, if the element targeted by the selector has an ancestor that matches "nav[data-foo-bar-sidenav][aria-expanded=\"true\"]. This works because of the appended & character:

(css {"nav[data-foo-bar-sidenav][aria-expanded=\"true\"] &"
      {:>.sidenav-menu-icon:d  :none
       :>.sidenav-close-icon:d :inline-flex
       :>ul:h                  "calc((100vh - (var(--navbar-height) * 2)) * 1)"
       :o                      1}}

The above example produces the following css:

.myns_core__L7C11 {
  nav[data-foo-bar-sidenav][aria-expanded="true"] & {
    &>.sidenav-menu-icon {
      display: none;
    }
    &>.sidenav-close-icon {
      display: inline-flex;
    }
    &>ul {
      height: calc((100vh - (var(--navbar-height) * 2)) * 1);
    }
    opacity: 1;
  }
}

CSS Shorthand Properties

CSS shorthand properties are a fundamental feature of CSS. They are properties that let you set the values of multiple other CSS properties simultaneously. With Kushi, you can write them like this:

;; with tokenized keyword
(css :b--1px:solid:black)

;; if using a map
(css {:b :1px:solid:black})

;; same as above, with string
(css {:b "1px solid black"})

All of the above examples will resolve to the following css declaration:

border: 1px solid black;

CSS Value Lists

In css, sometimes multiple values are seperated by commas to indicate they are ordered, or that there are ordered alternatives. With Kushi, you can write them like this:

(css :ff--FiraCodeRegular|Consolas|monospace)

The above will resolve to the following css declaration:

font-family: FiraCodeRegular, Consolas, monospace;

The example below uses a list of css shorthand values in order to render multiple text-shadows in different colors:

(css :text-shadow--5px:5px:10px:red|-5px:-5px:10px:blue)

The above will resolve to the following css declaration:

text-shadow: 5px 5px 10px red, -5px -5px 10px blue;

Shared Styles

kushi.core/defcss is intended for the creation of shared styles.

These shared styles should be defined in a dedicated namespace, or set of dedicated namespaces, and required once in your core or main ns.

defcss takes a selector (string) as the first argument, followed by any number of style arguments. Any style argument that is valid for css macro is valid for defcss.

(ns myapp.shared-styles
  (:require
   [kushi.core :refer [defcss]]))


;; Using tokenized keywords
(defcss ".headline"
  :ta--left
  :w--100%
  :ff--Inter|system-ui|sans-serif
  :fw--900
  :fs--24px
  :tt--u
  :mix-blend-mode--darken)


;; Tokenized-keywords + usage of a map for css function syntax
(defcss ".headline2"
  :top--0
  :left--0
  :b--1px:solid:black
  :fs--200px
  :tt--u
  :mix-blend-mode--darken
  {:c "rgba(155 155 155 / 0.8)"})


;; Example using a single map.
(defcss ".headline3"
  {:top               0
   :left              0
   :b                 :1px:solid:black
   :fs                :200px
   :tt                :u
   :mix-blend-mode    :darken
   :c                 "rgba(155 155 155 / 0.8)"})

By authoring your shared styles in a dedicated ns (or namespaces), you only need to require once in your main or core ns, and all the styles from that ns will be available globally.

(ns myapp.core
  (:require
   [kushi.core :refer [sx]]
   [myapp.shared-styles]))

  (defn my-headline [text]
    [:h1 (sx :.headline :mt--5px) text])

Styles as tokenized keywords

With the css, sx, and defcss macros, the simplest and most convenient way to describe styles is the usage of tokenized keywords. These keywords contain a --, and represent a css prop and value pair (split on --).

:color--red

More examples, using Kushi's optional shorthand grammer.

:c--red    ; :color--red
:ai--c     ; :align-items--center
:ai--e     ; :align-items--end
:ta--r     ; :text-align--right
:fs--18px  ; :font-size--18px
:ff--serif ; :font-family--serif

This shorthand grammer is available for the most commonly used props:

:ai   ; :align-items
:b    ; :border
:bc   ; :border-color
:bi   ; :border-inline
:bb   ; :border-block
:bs   ; :border-style
:bw   ; :border-width
:bg   ; :background
:c    ; :color
:d    ; :display
:ff   ; :font-family
:fs   ; :font-size
:fv   ; :font-variant
:fw   ; :font-weight
:h    ; :height
:jc   ; :justify-content
:ji   ; :justify-items
:lh   ; :line-height
:m    ; :margin
:mb   ; :margin-block
:mbs  ; :margin-block-start
:mbe  ; :margin-block-end
:mi   ; :margin-inline
:mis  ; :margin-inline-start
:mie  ; :margin-inline-end
:o    ; :opacity
:p    ; :padding
:pb   ; :padding-block
:pbs  ; :padding-block-start
:pbe  ; :padding-block-end
:pi   ; :padding-inline
:pis  ; :padding-inline-start
:pie  ; :padding-inline-end
:ta   ; :text-align
:td   ; :text-decoration
:tt   ; :text-transform
:w    ; :width
:ws   ; :white-space
:zi   ; :z-index

See the complete list of supported css properties here.

Shorthand grammer extends to cover enumerated values:

;; text-decoration
:td--u   ; text-decoration--uppercase
:td--o   ; text-decoration--overline
:td--lt  ; text-decoration--line-through

;; background-repeat
:bgr--nr ; background-repeat--no-repeat
:bgr--rx ; background-repeat--repeat-x
:bgr--ry ; background-repeat--repeat-y
:bgr--r  ; background-repeat--round
:bgr--s  ; background-repeat--space

;; align-items
:ai--c   ; align-items--center
:ai--fs  ; align-items--flex-start
:ai--fe  ; align-items--flex-end
:ai--n   ; align-items--normal
:ai--s   ; align-items--start
:ai--e   ; align-items--end
:ai--b   ; align-items--baseline

Note that the enumerated value none, as well as global properties such as inherit, initial, revert, unset, etc. are intentially not supported with shorthand syntax:

;; This will NOT work
:td--r

;; This will work
:td--revert ; => text-decoration: revert;

See the complete list of supported enum values here.

Working with media queries

;; Specify the font-size of an <h1> element across breakpoints
[:h1
 (sx :fs--1.25rem
     :md:fs--1.5rem
     :lg:fs--1.75rem
     :xl:fs--2rem)]

As in the example above, you can use preceding modifiers to set different values for a property at different breakpoints.

Kushi ships with the following, industry-standard, mobile-first breakpoint scale:

[:xsm {:min-width :480px}
 :sm {:min-width :640px}
 :md {:min-width :768px}
 :lg {:min-width :1024px}
 :xl {:min-width :1280px}
 :xxl {:min-width :1536px}]

Both the names and values can be customized via supplying a kwargs vector (not a map) as the :media entry in your kushi.edn config file. Because CSS Media Queries must be explicity ordered, this scale must be written as a vector of kwargs. See Configuration Options.

Below is an example of a scale that is desktop-first and uses different names.
Note that in the case of desktop-first (max-width), the order is reversed (relative to mobile-first / min-width).

[:desktop {:max-width :1280px}
 :tablet {:max-width :1024px}
 :mobile {:max-width :768px}
 :small {:max-width :640px}]

Any media-query modifier that you use must correspond to a key in the breakpoint map.

When "stacking" other modifiers (such as psuedo-classes) in front of css props, the media queries must always come first.

Pseudos and Combo Selectors

Pseudo-classes, pseudo-elements, and combo selectors are available via modifiers:

[:div (sx :hover:c--blue
          :>a:hover:c--red
          :&_a:hover:c--gold ; The "_" gets converted to " "
          :&.bar:hover:c--pink
          :before:fw--bold
          :after:mie--5px
          ["~a:hover:c" :blue] ; Vector is used as "~" is not valid in a keyword
          ["nth-child(2):c" :red] ; Vector is used as "(" and ")" are not valid in keywords
          [:before:content "\"⌫\""])
 [:a "Erase"]]

CSS resulting from the above example:

.myns_core__L7C11 {
  &>a {
    &:hover {
      color: red;
    }
  }
  & a {
    &:hover {
      color: gold;
    }
  }
  &.bar {
    &:hover {
      color: pink;
    }
  }
  &::after {
    margin-inline-end: 5px;
  }
  &~a {
    &:hover {
      color: blue;
    }
  }
  &:nth-child(2) {
    color: red;
  }
  &::before {
    font-weight: bold;
    content: "⌫";
  }
  &:hover {
    color: blue;
  }
}

Parents and ancestors

Kushi provides 2 fake css pseudo-classes in the form of has-parent() and has-ancestor(). With these, you to achieve further specificity with regards to parents and ancestors of the element that you are styling. This is useful when you want to use styles that might change when a class is toggled or changed further up in the DOM.

(defn my-button [text]
  [:button
   (sx ["has-ancestor(section.baz):color" :blue]
       ["has-parent(section.dark):color" :white]
       {:on-click #(prn "clicked!")})
     text])

The above would result in the following css:

section.baz .myns_core__L7C11 {color: blue}
section.dark > .myns_core__L7C11 {color: white}

Targeting dark mode

You can use the dark modifier to define styles that are scoped to the dark themes. This is sugar for has-ancestor(.dark). It is assumed there will potentially be a class of .dark on an ancestor element in the DOM. This would typically be the <body> or the target element for the app.

(defn my-button [text]
  [:button
   (sx :dark:color--hotpink
       :dark:b--2px:solid:hotpink
       :dark:&_.some-other-class:c--white
       {:on-click #(prn "clicked!")})
     text])

The above would result in the following css:

.dark .myns_core__L7C11 {color: hotpink; border: 2px solid hotpink}
.dark .myns_core__L7C11 .some-other-class {color: white}

You can use kushi.ui.core/lightswitch! to toggle a .dark class on the body, or a specific element of your choice.

(ns myns.core
  (:require [kushi.ui.core :refer [lightswitch!]]))

;; Toggle `.dark` class on body
(lightswitch!)

;; Toggle `.dark` class using querySelector
(lightswitch! "#my-id")

;; Any querySelector is valid and will work as long as it
;; corresponds to an existing element in the DOM.
(lightswitch! "div.some-class")

Selector Prefixing Options

You can narrow the specificity of you selectors by globally prepending a class or id (or any valid selector) of an ancestor element. Typically this would be something like the id of your "app" container.

;; In your kushi.edn map ...
{:selector-prepend "#my-app"}

;; In one of your component namespaces ...
[:div
 (sx :c--red)]

;; The above example would write the following rule to the css file:
;; #my-app .myns_core__L7C11 {
;;    color: red;
;;}

Defining CSS at-rules

at-rules are CSS statements that instruct CSS how to behave. You can define any at-rule with kushi.core/defcss by supplying a selector that starts with @ character.

Note - Although you can create global @media rules like this, @media rules are typically defined within defcss, css, and sx. Refer to the Media queries section for more details.

Defining @keyframes animations

Use kushi.core/defcss with the keyword such as "@keyframes my-animation-name" to define CSS @keyframes animation. If you supply an @keyframes selector, the remainder of the arguments must be 2 element vectors consisting of a keyword or string at index 0, followed by a stylemap at index 1. The keyword or string at index 0 must be one of #{:from "from" :to "to"}, or a percentage from 0 - 100, expressed as a keyword or string, e.g. :50% or "50%".

;; This will twirl something on its y-axis
(defcss "@keyframes yspinner"
  [:0% {:transform "rotateY(0deg)"}]
  [:100% {:transform "rotateY(360deg)"}])

;; Somewhere in your component code...
[:div
 (sx :animation--yspinner:12s:linear:infinite)
 "Round & Round"]

;; ------------------------------------------------------------

;; Another example, creating a class that will transitions color
(defcss "@keyframes blue-to-red"
  [:from {:color :blue}]
  [:to {:color :red}])

;; Somewhere in your shared styles code...
(defcss blue-to-red :animation--blue-to-red:5s:linear)

;; When you add the "blue-to-red" class on an element, it will
;; transition the element's `color` property from blue to red.

Adding Font Resources with @font-face

You can use kushi.core/defcss with a "@font-face" selector to load a local font from a file. This will add an @font-face block to the css file generated by Kushi.

The :src entry must be a path (string), or vector of paths if you want to specify multiple urls. The path(s) must be relative to the location of the generated css file. You could also use a remote url to load a hosted font file.

(defcss "@font-face"
  {:font-family "FiraCodeRegular"
   :font-weight "400"
   :font-style "normal"
   :src "url(../fonts/FiraCode-Regular.woff)"})

Injecting Stylesheets

kushi.inject/inject-stylesheet! will inject a stylesheet, or a third-party style library into the head of your index.html. This is more of an edge case, as you would typically just do this with a <link> in your index.html. However, if your project uses a clj file to generate the contents of your <head> at build time, it may be handy to use this during development to inject new stylesheets without restarting your build.

(ns myapp.core
  (:require
   [kushi.inject :refer [inject-stylesheet!]]))

(inject-stylesheet! {:rel "stylesheet"
                     :href "css/my-global-styles.css"})

Loading Google Fonts

A more common use case for injecting a stylesheet would the loading of webfonts via stylesheets, ala Google Fonts, or another similar webfonts service.

You can leverage kushi.inject/add-google-fonts! to simplify the process of adding Google fonts to your project.

The example below is a typical use case which loads a stylesheet from Google Fonts.

(ns myapp.core
  (:require
   [kushi.inject :refer [add-google-fonts!]]))

(add-google-fonts! {:family "Playfair Display"
                    :styles {:normal [400 700]
                             :italic [400 700]}})

;; The above call is equivalent to the following:

;; Note - the additional "preconnect" hints will improve Google Fonts performance.

;; (inject-stylesheet {:rel "preconnet"
;;                     :href "https://fonts.gstatic.com"
;;                     :cross-origin "anonymous"})

;; (inject-stylesheet {:rel "preconnet"
;;                     :href "https://fonts.googleapis.com"})

;; (inject-stylesheet {:rel "stylesheet"
;;                     :href "https://fonts.googleapis.com/css2?family=Playfair+Display:ital,wght@0,400;0,700;1,400;1,700&display=swap"})

kushi.inject/add-google-fonts! accepts any number of args, each one a single map that represents a font-family and associated weights & styles. You can as many different families as you want in a single go (although be mindful of performance):

(ns myapp.core
  (:require
   [kushi.inject :refer [add-google-fonts!]]))

(add-google-fonts! {:family "Playfair Display"
                    :styles {:normal [400 700] :italic [400 700]}}
                   {:family "Lato"
                    :styles {:normal [100 400]}}
                   {:family "Pacifico"
                    :styles {:normal [400]}})

Configuration Options

Various options are configurable via a required kushi.edn file.

This file must live in your project's root directory.

The only required entry in this map is :css-dir.

For a well commented starting point to build your own config, the sample kushi.edn config from the Kushi Quickstart template (similar to below) is recommended.

Actionable Warnings

It is highly recommended to keep the terminal (that is running the cljs-shadow build process) visible so that you can catch warnings for malformed arguments to Kushi functions.

Given the following:

(sx :.flex-col-c
    :.absolute-fill
    :h--100%
    "badstring"
    :m-10px
    12
    :ai--c
    :bgc--black)

You would receive warnings about invalid args in the terminal:

Defining components

Kushi promotes a component definition pattern that mirrors hiccup itself by standardizing the function signature as an (optional) single map of attributes followed by any number of children. This pattern relies on using the kushi.ui.core/opts+children helper function.

Under the hood, this helper function pulls out any keys in attributes map that start with :- and puts them in a separate opts map. This allows passing in various custom options within the attributes map that will not clash with existing html attributes. You can optionally make use of kushi.core/merge-attrs to enable decoration and composition of attribute maps.

(ns myapp.core
  (:require
   [kushi.core :refer [sx]]
   [kushi.ui.core :refer [opts+children]]))

(defn my-section
  [& args]
  (let [[opts attrs & children]  (opts+children args)
        {:keys [label label-attrs body-attrs]} opts]
    [:section
     attrs
     (when label [:div label-attrs label])
     (into [:div body-attrs] children)]))

The example above assumes the following:

• The args list in the function definition is variadic
• The optional attributes map may contain the custom attributes :-label, :-label-attrs, :-body-attrs.
• The values of :-label-attrs and :-body-attrs are html attribute maps.

The helper function kushi.ui.core/opts+children will pull any keys prefixed with :- out of the attributes map and into a user opts map. opts+children always returns a vector in the form of [user-opts attr child & more-children].

Usage with Build Tools

Although Kushi is designed to be build-tool and framework agnostic, thus far it has only been used in production with Reagent + Shadow-CLJS.

shadow-cljs

See the kushi-quickstart template for a detailed example of using Kushi in a shadow-cljs project.

Contributing

Feel free to file issues or initiate discussion in Issues.

License

Copyright © 2021-2024 Jeremiah Coyle

Distributed under the EPL License. See LICENSE.