mockingbird

Design System using tailwind and helix in ClojureScript.

A simple way to develop a user interface with a consistent user experience, without the need to clutter cljs code with CSS (unless you want to).

Work In Progress: if your desire is to use mockingbird using npm (how dare you!), you can, of course, use our npm package. Read more here.

name reference?

"mockingbird" is for everyone!

The name is a reference to the book To Kill a Mockingbird by Harper Lee. The idea is that the design system is a "mockingbird" that sings the same song everywhere.

It's impossible to talk about "mockingbird" without remembering the song Mockingbird by Eminem with his daughter Hailie Jade. The song is a declaration of love from a father to his daughter.

mockingbird is a declaration of love for all developers ~~(frontend will never be easy for backend developers)~~.

Overview

Mockingbird offers a set of reusable components and utilities that increases speed and beauty on your UI development. By integrating Tailwind, Helix and ReFx, Mockingbird combines functional programming and a powerful component model in order to create a fast and lightweight design system. This allows your team to focus on building robust, reactive interfaces without getting bogged down in styling and local state management concerns.

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Clojure: Follow the Clojure Installation guide to set up your environment.
• Node.
• npm.

Installation

We distribute our software via clojars (and intend to do so also by npm):

deps.edn:

  moclojer/mockingbird {:mvn/version "0.0.2"}

You will also need to start a project with shadow-cljs and install the npm deps.

npm:

$ npx create-cljs-project your-project
# Install runtime dependencies
$ npm install react react-dom --save
# Install development dependencies
$ npm install --save-dev \
  # Build tools
  shadow-cljs rimraf \
  # CSS processing
  autoprefixer postcss postcss-cli postcss-loader postcss-preset-env css-loader cssnano tailwindcss \
  # Testing
  karma karma-chrome-launcher karma-cljs-test msw \
  # Utilities
  npm-run-all glob cliui react-refresh

Consider creating a package.json file and adding these used dependencies or, maybe, you can just copy our package.json.

As you can see, our components have specific built-in styles for you. You can see a handful tutorial on the parameters for styling the components here.

deps.edn

Add these deps to your project in order to render using helix.

{:paths ["src" "resources"]
 :deps {moclojer/mockingbird {:mvn/version "0.0.2"}
        com.fbeyer/refx {:mvn/version "0.0.49"}
        lilactown/helix {:mvn/version "0.1.11"}
        com.teknql/shadow-cljs-tailwind-jit {:mvn/version "1.0.0"}}
 :aliases {:dev {:extra-paths ["test"]
                 :extra-deps {cider/cider-nrepl {:mvn/version "0.28.6"}
                              thheller/shadow-cljs {:mvn/version "2.20.10"}}}}}

Shadow cljs config

This is a shadow-cljs config example, you can use it the way you want it

{:deps {:aliases [:dev]}
 :builds {:app {:target      :browser
                :output-dir  "resources/public/assets/js"
                :asset-path  "/assets/js"
                :devtools    {:reload-strategy :full
                              :http-port 8080
                              :http-root "resources/public"}
                :dev         {:modules {:core {:init-fn your.ns.core/init}}}}}}

Usage

Add a import for a specific component or layout component you want and load it in your screen

(:require 
  [mockingbird.components.button :refer [button]]
  [helix.core :refer [$]])
  ;; use it then
  ($ button)

You can pass arguments into our components simply as this:

    ($ button {:type :submit
               :theme :mockingbird
               :size :lg} 
    "my magic button")

Getting our styles

Add this entry to your shadow-cljs build, so you can copy the styles from our .jar file.

remember to create the direcotory where your css file will be set.

:build-hooks [(mockingbird.dev.shadow.hooks/get-target-css 
    {:path "resources/public/assets/css/target.css"})]

# html file exambple

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My Project</title>
    <link rel="stylesheet" href="./assets/css/target.css">
  </head>
  <body>
    <div id="app"></div>
    <script src="./assets/js/core.js"></script> 
  </body>
</html>

This hook copies the Mockingbird styles from the JAR file to your project's resources directory during the build process.

Rendering with shadow-cljs

You will also need to render the components on your UI, so you can use our core file and this example file.

It will look something like this:

(ns your-project.core
  (:require
   ["react-dom/client" :as rdom]
   [mockingbird.examples.main :as ex]
   [helix.core :refer [$ <>]]))

;; this is a front app application using shadow-cljs, postcss, helix and refx.
;; You can see a simple page example running here.

(defn app []
  (<>
   ($ ex/app)))

(defonce root
  (rdom/createRoot (js/document.getElementById "app")))

(defn render []
  (.render root ($ app)))

(defn config []
  (println "ok"))

(defn ^:export init []
  (config)
  (render))

for better understanding, follow the offcial shadow-cljs guide and helix

You can clone and build this repo, to see some examples of good usage of our dear Mockingbird. You can read more here.

Contributing

Mockingbird is open-source, and contributions are welcome! If you have ideas for new features, improvements, or bug fixes, feel free to open an issue or submit a pull request.