IDX Design System

Local dev setup

To install you will need Node 18 on your computer locally: https://nodejs.org/en/download (Select LTS)

Once that's installed, you will need to install yarn which you can do by running

npm install --global yarn

Clone this repo and cd idx-design-system

Install dependencies

Following the initial clone, run:

yarn

Running this is the same as yarn install and will install all the required dependencies.

Start dev server

From there, you should be able to run:

yarn workspace @idx/styleguide dev

From there you will them have the styleguide running at http://localhost:3000

Add the environment file (only required for Drupal starter):

echo "NEXT_IMAGE_DOMAIN=v2-develop.docksal.site" > .env

Commands

Global

There are a few global commands worth mentioning:

Running tests

To run jest you can use:

yarn test

adding the --watch flag will watch new and amended tests in the background.

If you are wishing to check coverage it's possible to that with the flags --coverage --collectCoverageFrom="./packages/idx-design-system/**{.ts,.tsx}"

Linting code

To ensure that the codebase is meeting the best practices, we can run it through ESLint.

yarn lint

Formatting code

Code formatting can automatically be applied with Prettier. You can run this by using the following command:

yarn format

Running them all

To run all of these commands at once, there is the following command which can be run:

yarn mac-daddy

Next.js

All of the Next.js command are available to see here. The ones used commonly on this codebase are:

Dev server

Runs the node.js development server

yarn workspace {STARTER} dev

Build

Builds the codebase into a production ready version fo the site.

yarn workspace {STARTER_NAME} build

Serve

Runs an express server using the files built in the above command

yarn workspace {STARTER} serve

Code structure

The codebase is using the following tools:

• Next.js - React meta-framework provides the frontends
• Typescript – Compiles project with type safety
• Theme UI — CSS-in-JS styling library based on Emotion and uses the System UI theme spec.
• Jest — JS unit testing tool
• ESlint — code linter
• Prettier - code formatter
• Lerna & Yarn workspaces — Manages releases and versioning for monorepo
• Next-Drupal - connects Drupal with Next.js

├── packages
│   ├── idx-design-system
│   │   ├── base
│   │   │   ├── atoms
│   │   │   │   ├── colour
│   │   │   │   ├── grid
│   │   │   │   ├── icons
│   │   │   │   ├── pictograms
│   │   │   │   ├── radius
│   │   │   │   ├── shadows
│   │   │   │   ├── spacing
│   │   │   │   └── typography
│   │   │   └── molecules
│   │   │       ├── accordions
│   │   │       ├── buttons
│   │   │       ├── category-tags
│   │   │       ├── logo
│   │   │       ├── navigation-collection
│   │   │       ├── navigation-items
│   │   │       ├── pagination-arrows
│   │   │       └── text-links
│   │   ├── components
│   │   │   ├── footers
│   │   │   ├── globals
│   │   │   └── headers
│   │   ├── lib
│   │   └── theme
│   └── idx-next-drupal-connector
│       ├── components
│       │   └── content-types
│       └── lib
├── starters
│   ├── create-idx-next-drupal-app
│   │   ├── pages
│   │   │   ├── api
│   │   │   └── styleguide
│   │   └── variations
│   │       ├── components
│   │       │   ├── globals
│   │       │   └── headers
│   │       └── styles
│   └── styleguide
│       ├── components
│       │   └── section
│       ├── pages
│       │   ├── atoms
│       │   └── molecules
│       └── variations
├── test
└── types

Packages

Packages are isolated portions of code that can be installed indiviudally depending on the context.

IDX Design System

Currently, this is the most important package and is building the various React components for the IDX Design System. It's based on the following Figma file which has been created by the design team and it is loosely following the Atomic Design principles.

The structure of the codebase has been built to mirror a closely as possible the structure in the Figma file.

.
├── base
│   ├── atoms
│   └── molecules
├── components
│   ├── globals
│   └── ...
├── lib
├── pages
│   ├── results-presentations
│   └── ...
└── theme

lib — stores global utility functions such as getting the current path theme — This is the main ThemeUI JSON Object which is combining all of the component styles together.

Creating a new React component in IDX Design System

When creating a new component in the IDX Design System package the following structure should be followed:

.
├── __tests__
│   ├── __snapshots__
│   │   └── {COMPONENT_NAME}.test.tsx.snap
│   └── {COMPONENT_NAME}.test.tsx
├── styles
│   └── {COMPONENT_NAME}.ts
├── {COMPONENT_NAME}.tsx
└── utils
    ├── __tests__
    │   ├── __snapshots__
    │   │   └── {COMPONENT_NAME}.test.ts.snap
    │   └── {COMPONENT_NAME}.test.ts
    └── {COMPONENT_NAME}.ts

{COMPONENT_NAME}.tsx — Required the main component to be imported. utils — any helper utilities that are required. styles — Theme UI style configurations to be added to the main theme/theme.ts file. __tests__ — Jest assertions go here if utils or styles require additional tests then they should also contain a __tests__ directory. {COMPONENT_NAME}.test.tsx — The file containing the Jest tests. __tests__/__snapshots__ — This is an automatically generated file which contains any Jest snapshots that have been created in the {COMPONENT_NAME}.test.tsx.snap file.

IDX Next/Drupal Connector

This is very much a WIP and is using the Next-Drupal package to link content types to a Drupal instance.

Starters

IDX Next Drupal App

A WIP demo to show the the connection between a Drupal and Next instance. To be converted into a create-{package_name}-app recipe.

Styleguide

Displays the different options available in a theme-able manner.