@newtonschool/grauity

gra.UI.ty

Discovering the most elegant UI components for your next project

A meticulously crafted UI component library, bringing the simplicity and elegance of nature to your digital interfaces.
Explore the components and start building beautiful, efficient, and user-friendly interfaces with ease.

Explore gra.UI.ty docs »

About gra.UI.ty

Inspired by the natural laws that guide the cosmos, gra.UI.ty (pronounced "gravity") is a React-based UI component library designed to harmonize simplicity and functionality. Our mission is to provide developers and designers with the tools to create intuitive and aesthetically pleasing user interfaces.

Philosophy

Like the gravitational force itself, the principles of great design are universal, omnipresent, yet often unobserved. With gra.UI.ty, we aim to tap into these fundamental elements to craft UI components that not only look stunning but feel inherently right.

Component Naming Convention

gra.UI.ty components should be prefixed by NS. For example, NSButton, NSTable, NSInput

Alias

gra.UI.ty is also affectionately known as grauity, graUIty or simply as gravity

Setup gra.UI.ty to make it your own!

Developing Components

To start your development journey in grauity, follow these steps:

# Install all packages in grauity
npm install

# Update submodules (mainly iconland, the submodule for icons)
git submodule init
git submodule update --recursive

# Build icons (required when running for first time)
npm run build-icons

# Run grauity Storybook
npm run storybook
# Then head to localhost:6006

# To build grauity Storybook docs, run this command in grauity
npm run build-storybook

Integrating locally with your app for side-by-side development & testing

To integrate grauity locally with your app, follow these steps:

# Install all packages in grauity
grauity$: npm install

# Build grauity
grauity$: npm run build

# Install local version of grauity
your-app$: npm install ../grauity

# Now, link react, react-dom from grauity to your-app:
your-app$: npm link ../grauity/node_modules/react ../grauity/node_modules/react-dom --legacy-peer-deps

# Finally, run your-app
your-app$: npm run dev

After you have made changes in grauity, build it.

grauity$: npm run build

If changes are not showing up even after rebuilding, you may have to delete your-app/node_modules/@newtonschool/grauity folder and install grauity again:

grauity$: npm run build

your-app$: npm install ../grauity

Then simply import components you want from @newtonschool/grauity in your-app like so:

import { NSButton, BUTTON_VARIANTS_ENUM } from '@newtonschool/grauity';

And use it as you wish

import { NSButton } from '@newtonschool/grauity';

export const MyComponent = () => (
    <NSButton
        variant="primary"
        onClick={() => {
            setShowFormErrors(true);
        }}
    >
        Click me!
    </NSButton>
);

How to's

Add new icons from .svg files

1. Update the iconland submodule in grauity

grauity$: git submodule update --remote --merge

2. Add your .svg files

To add a new font icon, add your .svg files for the new icon in the ./iconland/seeds/ directory in the iconland submodule.

3. Optimize & Generate new font files

grauity$: npm run build-icons:optimize
grauity$: npm run build-icons:generate

Alternatively, run the command

grauity$: npm run build-icons

Font files will be created in ui/fonts folder.

Use theming in your React app

Without theming, only foundational (theme agnostic) CSS variables (found here: constantGlobalStyle) will be provided.

To enable theming, wrap your components with GrauityThemeProvider:

import { GrauityThemeProvider } from '@newtonschool/grauity';

const App = ({ children, ...props }) => {
    return <GrauityThemeProvider>{children}</GrauityThemeProvider>;
};

export default App;

Theming can be controlled by providing different class names to your root/local DOM elements, like the body element.

• Add class grauity-theme-light to use the light theme
• Add class grauity-theme-dark to use the dark theme

Now, you will be provided with the foundational as well as themed CSS variables, whose value will change depending on the theme applied.

These themed CSS variables can be found here:

• Dark theme color mapping
• Light theme color mapping

Use icons in your React app

To use grauity icons, add the following import in global-styles.scss or any root-level CSS/SCSS file. Make sure CSS/SCSS loaders are setup properly in your app.

@import '~@newtonschool/grauity/dist/css/index.scss';

Recommended IDE Setup

1. Visual Studio Code (VS Code) is our recommended Integrated Development Environment of choice.
2. Required Extensions:

• ESLint (by Microsoft) - For JavaScript/TypeScript code linting
• Prettier - Code formatter (by Prettier)
• Prettier ESLint (by Rebecca Vest) - For code formatting and ESLint integration

3. Enable format on save:

• Mac: Code > Preferences > Settings (cmd + ,)
• Windows/Linux: File > Preferences > Settings (Ctrl + ,)
• Search for "format on save"
• Check the box for "Editor: Format On Save"

Alternatively, you can add the following snippet to your settings.json file:

{
  "editor.formatOnSave": true
}