Castle UI

A Design System and Twig pattern library for the Smithsonian American Art Museum. The static styleguide is built with Fractal and the component library itself uses TailwindCSS CSS utility framework and Alpine JS for javascript functionality. The goal of this project is to use these tools to create an extremely flexible pattern library, requiring little to no custom css and javascript.

View the demo at design.saam.media

Installation

Install Castle UI using npm.

Note: use the --production flag if don't need to customize Castle UI.

npm install @americanart/castle-ui

To customize Castle UI you'll probably want to create a castle.config.js configuration file for your project. Run the following from your project root to copy the config file:

castle init

Exporting Castle UI for use in you project, will export all templates and assets to a given directory within your project. This directory then become your project's own version of the Castle UI pattern library, and will need to be recreated any time the @mericanart/castle-ui package is updated. Run the following from your project root to export to a directory named castle-ui:

castle export

Usage

After install and exporting Castle UI to your project you'll have all the css, js, and component templates needed to use in your application. It will be up to you to wire these assets up with your application, but it should be pretty straight forward for any PHP application using Twig. You'll need to add the castle-ui/castle.css and castle-ui/castle.js files, and configure a twig namespace pointing to the exported directory. You'll then be able to include/embed Castle UI components in your application, see the example below or read more on the Documentation wiki.

{% include "@castle/components/alert/alert.twig" with {
    id: "example-alert",
    modifier: "danger",
    title: "Important message!",
    messages: [
      'This is a Castle UI alert.'
    ]
} only %}

Development

Instructions for developing Castle UI. For example, modifying templates or javascript functionality, or customizing the styleguide.

Directory Structure

• src The component library source files.
• dist The compiled script, styles, and component files for use in projects.
• build The generated Styleguide/Design System website.
• docs The Fractal styleguide documentation pages.
• theme The styleguide theme overrides.

Compile assets

The following will compile any changes made in the src directory to the dist directory

castle build

Building the Styleguide

The following will start a local server to server the styleguide at http://localhost:3000.

castle fractal start

To export the static HTML styleguide to the build directory run:

castle fractal build