@goodtogreatschoolsaus/ggsa-design-system v1.0.43

GGSA Design System

Overview

Welcome to the GGSA Design System!

This is an npm package you can use in your Next.js projects which provides standard components, typography and CSS / SASS variables.

Live demo: https://ggsa-design-system.vercel.app/

Codebase: https://bitbucket.org/goodtogreatschools/ggsa-design-system/src/production/ To view a specific component / find documentation about the available props go to: app/components/any_component_name/index.tsx

Figma library: https://www.figma.com/files/team/1204379399841511363/project/304314913/

Usage

Requirements

1. Your project must use Next.js and Typescript.
2. You will need to get access to the private GGSA npm teams account called "goodtogreatschoolsaus". This can be requested interally from Kyle Richards.

Installation

Please note that the below instructions use pnpm for increased performance. However, you can simply use npm if you prefer.

1. Login to npm:

pnpm login

2. Install the private npm package:

pnpm install @goodtogreatschoolsaus/ggsa-design-system

3. Update next.config.ts to include the following configuration.

import type { NextConfig } from "next";

export default {
  ...
  // START CODE TO BE ADDED

  // Support using Typescript within the GGSA Design System
  transpilePackages: ["@goodtogreatschoolsaus/ggsa-design-system"]

  // END CODE TO BE ADDED
  ...
}

4. Import the required CSS into the entry point of your app - e.g. app/layout.tsx. This includes the global styles, fonts and CSS variables.

// Import the global styles, fonts and variables from the GGSA Design System
import '@goodtogreatschoolsaus/ggsa-design-system/app/scss/style.css';

This will make all CSS variables available to you as seen here: https://bitbucket.org/goodtogreatschools/ggsa-design-system/src/production/app/scss/partials/_cssVariables.scss

5. If you're using SASS, you can also make use of the mixins and variables directly inside any SASS file. The SASS variables can be found here and the SASS mixins can be found here.

// Import the variables (relative pathing)
@use '../node_modules/@goodtogreatschoolsaus/ggsa-design-system/app/scss/partials/variables' as v;

// Import the mixins (relative pathing)
@use '../node_modules/@goodtogreatschoolsaus/ggsa-design-system/app/scss/partials/mixins' as m;

// Example usage
button {
  // Mixins usage
  @include m.reset;

  // Variables usage
  background: v.$color_primary;
  color: v.$color_grey;
}

6. Here's how you import and use the components. You can do this anywhere within your app, just like any other npm package.

import { Button } from '@goodtogreatschoolsaus/ggsa-design-system';
...
<Button href='#' size='m'>My example button</Button>

7. To deploy this on Vercel, you will need to generate an npm token. To do this login to npm, then go to Access tokens -> Generate New Token. More information on this can be found here: https://docs.npmjs.com/creating-and-viewing-access-tokens

8. Now go to Vercel, navigate to your app and create a new environment variable called NPM_TOKEN and set this to the npm token you generated eairler. More information on this can be found here: https://vercel.com/guides/using-private-dependencies-with-vercel

That's all there is to it! Enjoy :)

If you have any questions or issues, please reach out to the wider team.

Maintaining and extending this project

Requirements

1. Install Git.

2. Install pnpm.

3. Install Node.js (minimum supported version is 22.11.0).

Installation

1. Clone the Bitbucket repository.

2. Install the dependencies:

pnpm install

3. Use the following commands to start developing:

// Start in development mode and watch for changes
// This will make the project available at http://localhost:3000/ in your browser
pnpm run watch

// Run the linters and auto-fix errors (please also setup linters in your IDE / editor directly!)
pnpm run lint

// Run the automated testing
pnpm run test

// Create a build (no need to do this manually, as it's part of Bitbucket Pipelines and Vercel Deployments)
pnpm run build

Developing

1. Create a new branch for your work:

git branch my-branch
git checkout my-branch

2. Make your changes. When ready, commit and push your work:

git add .
git commit -m "My updates"
git push --set-upstream origin my-branch

Deploying

1. Checkout the production branch:

git checkout production

2. Increment your version number in package.json. Example:

"version": "1.0.8" -> "version": "1.0.9"

3. Merge your changes into the production branch, commit and push:

git merge my-branch
git add .
git commit -m "My new version"
git push

4. This will automatically trigger the deployment pipelines. If all automated tests / linting passed, it will become available on Vercel here: https://vercel.com/good-to-great-schools-projects/ggsa-design-system/

5. Update the published private npm package:

pnpm publish