JsonPlaceholder.doc.mdx

union

bool

string

ActionButton.doc.mdx

ActionButton

ActionEdit.doc.mdx

ActionEdit

DataCheckbox.doc.mdx

DataCheckbox

DataColor.doc.mdx

DataColor

DataDate.doc.mdx

DataDate

DataDateTime.doc.mdx

DataDateTime

DataEmail.doc.mdx

DataEmail

DataFile.doc.mdx

DataFile

DataImage.doc.mdx

DataImage

DataMonth.doc.mdx

DataMonth

DataNumber.doc.mdx

DataNumber

DataPassword.doc.mdx

DataPassword

DataRadio.doc.mdx

DataRadio

DataSelect.doc.mdx

DataSelect

DataTel.doc.mdx

DataTel

DataText.doc.mdx

DataText

DataTextArea.doc.mdx

DataTextArea

DataTime.doc.mdx

DataTime

modules

AreaPlaceholder.doc.mdx

AreaPlaceholder

JsonPlaceholder

system-components

Dashboard.doc.mdx

InfoPopover

components

data

tests

widgets

Dashboard

0-Table.mdx

assets

Checkbox

atoms

context

fixtures

state

Table


Cascara is a Functional Design System (FDS). But what _is_ a FDS and how is it different/similar to a Design System or UI Library? What are we trying to achieve by building a FDS instead of only a Design System or UI Library instead? To begin, we need to understand what a Design System is and what sorts of challenges it is intended to solve.

## What Is A Design System?

Design Systems come in different sizes and scope, but essentially, they can be defined as follows:

> A Design System is the single source of truth which groups all the elements that will allow the teams to design, realize, and develop a product.
>
> <footer>
>   <a href='https://uxdesign.cc/everything-you-need-to-know-about-design-systems-54b109851969'>
>     Audrey Hacq
>   </a>
> </footer>

This will typically include, but not limited to, the following groups:

- **Brand Guidelines** (Color, Typography, Logo, Copy)
- **UI Library** (Components, Layout, Animation)
- **User Experience** (Patterns, Rules, Principles)
- Icons/Images/Illustrations

### Value Proposition

There are [plenty](https://reusserdesign.com/resources/articles/why-should-you-consider-a-design-system) of [other articles](https://www.invisionapp.com/inside-design/guide-to-design-systems/) about [design systems](https://uxdesign.cc/what-the-heck-is-a-design-system-c89a8ea73b0d) and their advantages, so let's wrap up with the benefits of a Design System that are most valuable to us at Espressive:

- Faster time to market
- More consistent user experience
- Codebase becomes more stable and easier to maintain
- Increased efficiency in decision making

## What is a _Functional_ Design System?

If you're caught up on what a Design System is and what some of the elements of a Design System are, we can ask: What is the _functional_ part of a Functional Design System?

> A Functional Design System is a superset of a design system which has additional components that help it enforce experience, patterns, and other rules of the Design System as a whole.
>
> <footer>
>   <a href='https://www.linkedin.com/in/brianjespinosa/'>Brian Espinosa</a>
> </footer>

Update a single "margin" value in our tokens:

- All design prototypes get updates
- All UI library gets updated
- All documentation gets updated

If this sounds like magic, it kind of is. There is a lot of tooling that has to work together to achieve this. We also have a long way to go to make all of this automatic. For now, we can highlight some of the strategies we are using to make this possible.

- [Public API Components](/20-public-api-components)
- [Structures and Layouts](/30-structures-and-layouts)
- [Modules](40-modules)

> This section of our documentation will expand further over time.


Functional Design Systems (FDS), Design Systems, UI Libraries, and what we are trying to achieve.

Functional Design System


Public API Components (PAC) are the public API for Cascara. We can think of PAC as a container that has other internal components and functionality inside. This internal functionality is private and generally not exposed to developers. By keeping most of the functionality private, developers have fewer decisions to make (and maintain) when it comes to consistency and experience.

A PAC has a limited API surface area, which might feel strange to developers who are used to UI libraries with dozens of configuration parameters (examples below). By using a PAC, we help developers by simplifying decisions and helping them implement/maintain less functionality.

## PAC Examples

The concept of a PAC might seem somewhat abstract at first, so let's take a look at some examples.

### Simple Component

The easiest place to start is a ubiquitous button component. A button is used in almost every application so we are all familiar with them. Let's take a look at the API surface area of a Button component in Semantic UI React:

```javascript
<Button
  active
  animated={false}
  as={Link}
  attached='top' // left, right, top, bottom
  basic
  circular={false}
  color='red' // red, orange, yellow, olive, green, teal, blue, violet, purple, pink, brown, grey, black, facebook, google plus, instagram, linkedin, twitter, vk, youtube
  compact
  content='Hello World'
  disabled
  floated='right' // right, left
  fluid
  icon='globe'
  inverted
  label='Test'
  labelPosition='right' // right, left
  loading
  negative
  positive
  primary
  secondary
  size='mini' // mini, tiny, small, medium, large, big, huge, massive
  toggle
/>
```

There's a lot going on here (this does not even include all of the event functions like `onClick()`). This makes sense because UI library authors want to give as much flexibility as possible to developers to use in all kinds of applications... but that same flexibility can also slow developers down each time they configure a component. Many of these properties are not used in our applications. Certain combinations of thes properties also yield unwanted results.

If we were to have only the attributes that we want to control, the API might look more like this:

```javascript
<ButtonPAC
  as={Link}
  content='Hello World'
  isActive
  isDisabled
  isFluid
  isLoading
  size // small, regular, large
  variant='secondary' // default, primary, secondary, tertiary
/>
```

The most notable things missing here are options for additional styling and positioning. Instead of forcing developers to decide what the styles should be on every button, we instead let them declare the variant or size and perhaps some [_limited_ boolean attributes](https://spicefactory.co/blog/2019/03/26/how-to-avoid-the-boolean-trap-when-designing-react-components/) as well. Syling of the button should be driven by the variants in the design system. Positioning should be [driven by layouts](/30-structures-and-layouts) of the design system and not by the button itself.

What happened to our original button? Well, we could have replaced it entirely... or we could have simply wrapped it in our new ButtonPAC component. Our new PAC can take all of the configurations from the simplified list of properties and decide how to implement them on our old Button component.

> A good way to think about a PAC is just an API wrapper where we only expose the simplest configurations that we want to allow and make everything else private. This pattern is excellent to follow when using external libraries. If we replace a Button, Form, Table, Router in the future, if we have it wrapped in a PAC, all we have to do is update the component inside of our PAC and our entire application gets the update.

### Complex Components

Using a PAC on complex components becomes even more powerful. Let's think about a Table and all of the associated functionality we need to handle. There is a lot of configuration that we need to do every time we implement a table:

- Set up our column count
- Figure out what labels to display for our table header
- Iterate over data to set up our rows
- Determine display type for each column

This is only the simplest use case. There are many other advanced actions we might need to set up like editing inline, selecting records for editing, sorting, etc. Even more problematic... much of this configuration becomes imperative and not reusable. Without a design system for guidance we end up with a bunch of one-off table implementations that are inconsistently implemented and hard to maintain.

If we wrap our Table in a PAC, we can create a table that becomes more portable and all of our implementation work becomes portable as well.


Component wrapper patterns for a opinionated and minimal API surface area.

Public API Components


In a design system, guidelines about overall application structure and page layout can easily become boilerplate. As codebases grow, implementation details of that boilerplate can be forgotten or left behind. With Cascara we hope to guide the principles of applicaiton structure and page layout not just from system guidelines, but also with components.

## Structures

<img src='/structure.svg' alt='Structure' className='right' />

In Cascara, Structures are essentially a responsive grid and baseline styles for holding together an application. They usually do not contain any state except when required for opening and closing collapsed presentational content on smaller devices.

We have multiple applications at Espressive, our main application being Barista. Structures will be used to unify the experience across all of our applications.

- [Admin](/docs/structures/Admin)
- [Barista](/docs/structures/Barista)

All of our applications will use the Admin structure except for Barista which will be more complex and have functionality to display correctly inside of native devices.

## Layouts

<img src='/layout.svg' alt='Layout' className='right' />

We can think of Layouts and content that fills the grid of a Structure. Layouts will probably be intended for use inside of a specific Structure, but they should be created to be consumed in any application Structure.

At the time of writing, there are two types of layouts we will be using, presentational and functional. A presentational layout is generally going to be similar to a Structure in that it will provide areas to place other content and components. A functional layout will usually not give options on where content is presented. Functional layouts will instead be more opinionated about what happens inside of them. We can think of them as micro-applications.

Examples of presentational layouts:

- List View
- Admin Page

Examples of functional layouts:

- Admin Page Table w/ search, filtering, pagination, sorting, etc.
- Chat
- List View User Directory

> Notes:
>
> - Functional layouts will likely be built from presentational layouts
> - We may need to split in how we name these later
> - Presentational layouts may not end up being part of the public API


Reusable application structure and layout component concepts for consistency.

Structures and Layouts


A Module as it pertains to Cascara is a component intended to both display and edit a discreet piece of data. Think of a display where we need to display information about a user. If we click a button that display changes into a form. If we slice all of the inputs of that form up, those would be Modules.

As of today, we will have two kinds of modules: Data Modules and Action Modules. A Data Module is for displaying or editing a piece of data. An Action Module is a control for different kinds of actions.

Modules have:

- A display mode and an editing mode
  - This can be configured to not allow editing
- Are either a data or action module
- Rely on a parent Context in order to tell what mode to be in

## Data Modules

Let's see how a data module might work and how it becomes reusable across our application. Staying with our user form example, if we build a form out of a bunch of Data Modules, they can start in display mode. We can display our entire user record as information. We can then change the form to edit mode and it becomes a form. What if there are read-only attributes? We configure those modules not to switch to editing mode. When we submit our form, we can return the updated data to the form which will automatically reset the Context to display mode and the new values will be displayed.

Each data module will have logic for displaying and editing its specific data piece of data. Maybe we have a `boolean` type that we want to display as a checkbox, switch, or as a button. We can have modules for each. How do those display when in display mode? How do they display in edit mode? Those decisions are controlled by the design system, so we can implement them once and reuse that everywhere.

What about more complex Data Modules like a date or image? In display mode, a date may need to display a local or UTC time. For editing, it may have a date or time picker. For an image, maybe that image will have different display sizes. For editing, maybe that image will have a regular file picker... or perhaps a file picker with an image editor to crop the image before saving. Again... these modules once implemented can then be used everywhere inside of a Module Context.

These modules can also be used in other display and edit modes. We can create tables that display Data Modules inside of each cell that will allow inline editing of content in a table.


Reusable component logic for interacting with and displaying data.

Modules


When our first alpha version is ready to use, documentation on how to install Cascara in our apps will appear here.


Getting Started

Cascara

JsonPlaceholder

Default display

Can be open on mount

Can display a unique title

If needed, can be customized