@asyarb/panko

JAMStack Design System/Business Template POC

Proof of concept repository showcasing how we can build a robust and reusable design system for a cheapo Business Template in JAMStack-Headless CMS sites.

This library is intended to be consumed as a package that we can drop in to any site or tooling (NextJS or Gatsby). This would be accomplished just like any other npm or yarn package.

• Getting Started
• Technical Stack
• Project Structure Summary
  • Notable files in project root
  • Components
  • Css
• License

Getting Started

• Clone this repo.
• Run yarn.
• Run yarn start to start your development environment.

Technical Stack

This design system was created and developed with the following:

• React - Declarative, reusable components.
• TypeScript - Static typechecking.
• TailwindCSS - Declarative and performant utility-based CSS.
• StoryBook - Dedicated and isolated environment for developing components.

Project Structure Summary

Notable files in project root

The only notable file in the project root is our taildinw.config.js file. Use this file to customize our generated utility classes for styling.

Right now, we're mostly relying on the default theme provided out of the box.

Components

Within the src directory we have our components folder. This is where most development will take place.

Within components, we have the following folders:

core - Low level components that will aid in quickly creating larger components. An example of one of these components would is our <AspectRatio> component. This component ensures that an image is always affixed to a certain x:y ratio.

These components should not have any styling and should be entirely utility-centric.

common - Components that are commonly reused across larger components that contain styling. Examples of components in this directory include <Button> or <Heading>.

These components should not have any spacing related styling applied to them by default. These components should always provide an intuitive API to allow spacing/alignment to be modified via props or Tailwind classes.

Css

Within the css directory we have 3 stylesheets. For the most part, we should avoid writing custom CSS as much as possible, and leverage Tailwind utilities whenever we can. However, sometimes we need to eject and write plain CSS (CSS grid, clip-path, etc.), so we can use these stylesheets to do so.

base.css - contains our custom preflight styles for our system. This shouldn't ever need to be modified.

components.css - contains custom CSS styling for each component that may need it. When writing custom CSS, adhere to standard BEM practice by using the component's name as the top level Block.

Whenever possible, leverage Tailwind's theme(), @screen, and @apply directives. This helps to ensure design consistency even when writing custom CSS.

License

MIT.