Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ktranish/unit
A React-based design system built for consistency and flexibility, with support for Tailwind CSS and utility-first styling.
https://github.com/ktranish/unit
design-system hooks react tailwindcss typescript
Last synced: about 2 months ago
JSON representation
A React-based design system built for consistency and flexibility, with support for Tailwind CSS and utility-first styling.
- Host: GitHub
- URL: https://github.com/ktranish/unit
- Owner: ktranish
- License: mit
- Created: 2024-11-13T17:23:17.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2024-11-30T10:49:19.000Z (2 months ago)
- Last Synced: 2024-11-30T10:51:43.635Z (2 months ago)
- Topics: design-system, hooks, react, tailwindcss, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@ktranish/unit
- Size: 71.3 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Unit
> **A React-based design system built for consistency and flexibility, utilizing Tailwind CSS and utility-first styling.**
## About
**Unit** is a flexible and scalable design system developed with React and Tailwind CSS. It provides a set of reusable UI components, hooks, and utility classes to help build responsive, consistent, and maintainable web applications. This project follows utility-first principles to offer maximum customization with minimal configuration.
## Features
- ⚛️ **React Components**: Custom components designed for reusability and easy integration.
- 🎨 **Tailwind CSS Integration**: Built-in support for Tailwind CSS, allowing quick styling with utility classes.
- 📘 **TypeScript**: Full TypeScript support for better type safety and developer experience.
- ✂️ **Utility-first Styling**: Offers a range of configurable design tokens for spacing, typography, colors, and more.
- 🌍 **Translation Hook**: Provides an easy-to-use translation hook (`useTranslation`) for multilingual support, with support for dynamic language loading.
## Getting Started
### Installation
Install Unit via your preferred package manager:
```bash
# npm
npm install @ktranish/unit
# yarn
yarn add @ktranish/unit
# pnpm
pnpm add @ktranish/unit
```
### Usage
1. Import the desired component(s) into your React project.
2. Use the `cn` utility to merge class names where needed (useful for custom styling with Tailwind classes).
Example usage:
```tsx
import React from "react";
import { Button } from "@ktranish/unit";
import { cn } from "@ktranish/unit/utils/cn";
function App() {
return (
);
}
```
## Tailwind Configuration
Unit includes a custom Tailwind configuration file (`tailwind.config.js`) that consumers can extend in their own projects. This allows your project’s Tailwind setup to seamlessly inherit Unit’s custom themes, spacing, colors, and other configurations.
To use Unit’s configuration, import it in your own `tailwind.config.js` file and extend it as shown below.
```js
// tailwind.config.js in the consumer project
const designSystemConfig = require("@ktranish/unit/tailwind.config");
module.exports = {
content: [
"./src/**/*.{js,ts,jsx,tsx}",
"./node_modules/@ktranish/unit/dist/**/*.{js,ts,jsx,tsx}",
],
theme: {
extend: {
...designSystemConfig.theme,
},
},
plugins: [...designSystemConfig.plugins],
};
```
## Translation Setup
Unit includes a `getServerSideTranslations` utility function and `TranslationProvider` to support multilingual content. This feature works seamlessly with or without namespaces.
### With Namespaces
For projects that use namespaces (e.g., modular translations for `common`, `home`, etc.), you can specify the namespaces to load:
#### Example Directory Structure
```bash
locales/
├── en/
│ ├── common.json
│ ├── home.json
├── es/
│ ├── common.json
│ ├── home.json
```
#### Example Consumer Code
```tsx
import { getServerSideTranslations } from "@ktranish/unit/utils/getServerSideTranslations";
export async function getServerSideProps(context) {
const { locale = "en" } = context;
// Load specific namespaces for the locale
const translations = await getServerSideTranslations(locale, [
"common",
"home",
]);
return {
props: {
locale,
translations,
},
};
}
export default function HomePage({ translations }: { translations: any }) {
return (
);
}
```
### Without Namespaces
For projects that don’t use namespaces, the utility will automatically load all translation files in the specified locale directory.
#### Example Directory Structure
```bash
locales/
├── en.json
├── es.json
```
#### Example Consumer Code
```tsx
import { getServerSideTranslations } from "@ktranish/unit/utils/getServerSideTranslations";
export async function getServerSideProps(context) {
const { locale = "en" } = context;
// Load all translations for the locale
const translations = await getServerSideTranslations(locale);
return {
props: {
locale,
translations,
},
};
}
export default function HomePage({ translations }: { translations: any }) {
return (
);
}
```
### Custom Translation Path
If your translations are stored in a non-standard directory, you can use the `basePath` parameter to specify the root directory of your translations.
#### Custom Directory Structure
```bash
translations/
├── en/
│ ├── common.json
│ ├── home.json
├── es/
│ ├── common.json
│ ├── home.json
```
#### Example Consumer Code
```tsx
import { getServerSideTranslations } from "@ktranish/unit/utils/getServerSideTranslations";
import path from "path";
export async function getServerSideProps(context) {
const { locale = "en" } = context;
// Specify a custom basePath for translations
const translations = await getServerSideTranslations(
locale,
["common", "home"],
path.resolve(process.cwd(), "translations"),
);
return {
props: {
locale,
translations,
},
};
}
export default function HomePage({ translations }: { translations: any }) {
return (
);
}
```
### Dynamic Language Loading
For larger applications, translations can be loaded dynamically based on the selected language. Consumers can store each language in a separate JSON file and load it as needed.
#### Example setup with JSON files:
Organize translations in `locales` directory as follows:
```bash
src/
├── locales/
│ ├── en.json
│ ├── es.json
│ └── fr.json
└── App.tsx
```
Each JSON file contains translations for one language. For example, `en.json`:
```json
{
"welcome": "Welcome",
"goodbye": "Goodbye"
}
```
Then, in `App.tsx`, dynamically load translations based on the selected language:
```tsx
import React, { useState, useEffect } from "react";
import { Button } from "@ktranish/unit";
import {
TranslationProvider,
useTranslation,
} from "@ktranish/unit/hooks/useTranslation";
const App = () => {
const [language, setLanguage] = useState("en");
const [translations, setTranslations] = useState({});
const loadTranslations = async (lang: string) => {
const translations = await import(`./locales/${lang}.json`);
setTranslations(translations);
};
useEffect(() => {
loadTranslations(language);
}, [language]);
const switchLanguage = () => {
setLanguage((prev) => (prev === "en" ? "es" : "en"));
};
return (
Switch to {language === "en" ? "Spanish" : "English"}
);
};
const Welcome = () => {
const { t } = useTranslation();
return (
{t("welcome")}
);
};
```
This setup allows you to load only the necessary translations, keeping the app lightweight and efficient.
## Development
### Building the Project
To build the project, ensure you have all dependencies installed. Then run:
```bash
pnpm build
```
### Linting & Formatting
This project uses **ESLint** for linting and **Prettier** for code formatting.
- **Lint**: Run `pnpm run lint` to check for linting errors.
- **Format**: Run `pnpm run prettier:format` to auto-format your code.
## Components
List of core components available in Unit (update with actual components as they’re added):
Each component supports Tailwind utility classes, making it easy to customize and extend.
## Hooks
Unit includes several utility hooks to facilitate common patterns and functionality:
Each hook provides functionality designed to integrate smoothly with Unit’s components, enhancing the developer experience and making complex functionality easy to manage.
## Contributing
Contributions are welcome! To contribute:
1. Fork the repository.
2. Create a feature branch (`git checkout -b feature-name`).
3. Commit your changes (`git commit -m 'Add new feature'`).
4. Push to the branch (`git push origin feature-name`).
5. Open a Pull Request.
## License
This project is licensed under the [MIT License](LICENSE).