@atomazing-org/design-system 1.0.14 β†’ 1.0.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.MD +166 -127
  2. package/package.json +1 -1
package/README.MD CHANGED
@@ -3,204 +3,243 @@
3
3
  1. [Introduction](#1-introduction)
4
4
  2. [Installation](#2-installation)
5
5
  3. [Usage](#3-usage)
6
- 3.1 [Theme Provider Setup](#31-theme-provider-setup)
7
- 3.2 [Typography Variants](#32-typography-variants)
8
- 3.3 [Global Styles](#33-global-styles)
9
- 3.4 [Component Overrides](#34-component-overrides)
10
- 4. [Utilities](#4-utilities)
11
- 4.1 [Color Utilities](#41-color-utilities)
12
- 4.2 [System Info](#42-system-info)
13
- 5. [Animations](#5-animations)
14
- 6. [Theming](#6-theming)
15
- 6.1 [Theme Creation](#61-theme-creation)
16
- 6.2 [Dark Mode Strategy](#62-dark-mode-strategy)
17
- 7. [Typography Configuration](#7-typography-configuration)
18
- 8. [Contributing](#8-contributing)
19
- 9. [License](#9-license)
6
+ 3.1 [ThemeProvider Setup](#31-themeprovider-setup)
7
+ 3.2 [Switching Theme Mode (Light/Dark)](#34-switching-theme-mode-lightdark)
8
+ 3.3 [Custom Theme Colors](#35-custom-theme-colors)
9
+ 4. [Peer Dependencies & Requirements](#4-peer-dependencies--requirements)
10
+ 5. [Utilities](#5-utilities)
11
+ 5.1 [Color Utilities](#51-color-utilities)
12
+ 5.2 [System Info](#52-system-info)
20
13
 
21
14
  ## 1. Introduction
22
15
 
23
- **@atomazing-org/design-system** is a reusable, opinionated design system built on top of [Material UI (MUI)](https://mui.com/) and [Emotion](https://emotion.sh/).
24
- It offers a consistent foundation for building modern web interfaces with minimal configuration.
16
+ **@atomazing-org/design-system** is a flexible, modern, and themeable design system built on top of [Material UI (MUI)](https://mui.com/) and [Emotion](https://emotion.sh/).
25
17
 
26
- This package provides:
18
+ It provides a unified approach to building consistent, responsive, and accessible UIs across multiple frontend applications β€” with minimal setup and full customizability.
27
19
 
28
- - 🌈 Customizable MUI theme generator
29
- - ✍️ Extended typography variants
30
- - 🎨 Global styles (with dark/light mode support)
31
- - 🧩 Component style overrides
32
- - πŸ›  Utility functions (e.g., color contrast, system info)
33
- - 🎞 Smooth keyframe animations
20
+ ### πŸ”§ What’s Included
34
21
 
35
- The design system is ideal for teams working across multiple front-end applications who want to unify styles, reduce duplication, and ship faster with consistent UI patterns.
22
+ - 🌈 **Custom MUI Theme Generator**
23
+ Create light/dark themes with primary/background colors in a single line.
24
+
25
+ - ✍️ **Extended Typography Variants**
26
+ Includes consistent, scalable font sizes and weights beyond MUI defaults.
27
+
28
+ - 🎨 **Global Styles**
29
+ Applies CSS resets, adaptive contrast, scrollbar styling, and system theming.
30
+
31
+ - 🧩 **Component Style Overrides**
32
+ Predefined visual rules for MUI components like buttons, dialogs, sliders, etc.
33
+
34
+ - πŸ›  **Utility Functions**
35
+ Helpful tools like color contrast calculation, system info detection, and dark mode strategy.
36
+
37
+ - 🎞 **Predefined Animations**
38
+ Keyframes for transitions like fade, slide, pulse, and more.
39
+
40
+ ### πŸš€ When to Use
41
+
42
+ Use this design system when:
43
+
44
+ - You’re building apps that require a **consistent design language**.
45
+ - You want to **save time on theming and component styling**.
46
+ - You work across multiple projects and need **reusable design tokens**.
47
+ - You want **dark mode support**, animations, and global styles out of the box.
48
+
49
+ This package is ideal for both small projects and large enterprise frontends looking to maintain style consistency and speed up delivery.
50
+
51
+ ---
36
52
 
37
53
  ## 2. Installation
38
54
 
39
- To install the design system in your project, use your preferred package manager:
55
+ To install `@atomazing-org/design-system`, use your preferred package manager:
40
56
 
41
57
  ```bash
42
- # Using npm
58
+ # npm
43
59
  npm install @atomazing-org/design-system
44
60
  ```
45
61
 
46
62
  ```bash
47
- # Using yarn
63
+ # yarn
48
64
  yarn add @atomazing-org/design-system
49
65
  ```
50
66
 
51
67
  ```bash
52
- # Using pnpm
68
+ # pnpm
53
69
  pnpm add @atomazing-org/design-system
54
70
  ```
55
71
 
72
+ > **Note:** This package includes only the core functionality.
73
+ > You must also install the required **peer dependencies** to ensure proper integration with MUI and Emotion.
56
74
 
57
- ## 3. Peer Dependencies & Requirements
58
-
59
- The `@atomazing-org/design-system` package relies on several peer dependencies to integrate properly with your application stack.
75
+ ## 3. Usage
60
76
 
61
- Make sure the following libraries are installed in your project:
77
+ This section describes how to use the design system in your application, including theme setup, global styles, switching between light and dark modes, and accessing theme context via a custom hook.
62
78
 
63
- | Package | Version | Required For |
64
- |----------------------|------------------|-------------------------------------|
65
- | `@mui/material` | `^7.2.0` | Core MUI theming and components |
66
- | `@mui/icons-material`| `^7.2.0` | Icon support |
67
- | `@emotion/react` | `^11.0.0` | Emotion styling engine (required) |
68
- | `@emotion/styled` | `^11.0.0` | Styled components with Emotion |
69
- | `@emotion/css` | `^11.13.5` | (Optional) Raw className utility |
79
+ ### 3.1 ThemeProvider Setup
70
80
 
71
- ### TypeScript Support
81
+ To enable theming, wrap your application with the `ThemeProviderWrapper` provided by `@atomazing-org/design-system`.
82
+ This wrapper handles theme creation, dark mode toggling, system preferences, and context setup β€” all out of the box.
72
83
 
73
- This package is fully written in TypeScript and ships with `.d.ts` type declarations.
74
- Ensure your project uses TypeScript 4.5+ for best compatibility.
84
+ ```tsx
85
+ import { GlobalStyles, ThemeProviderWrapper } from '@atomazing-org/design-system';
75
86
 
76
- > βœ… **Tip:** If you encounter missing types (e.g., for `@emotion/react`), install them manually:
77
- ```bash
78
- npm install -D @types/react
87
+ export const App = () => (
88
+ <ThemeProviderWrapper>
89
+ <GlobalStyles />
90
+ {/* Your application content */}
91
+ </ThemeProviderWrapper>
92
+ );
79
93
  ```
80
94
 
81
- ## 4. Features Overview
95
+ ### πŸ” Key Notes
82
96
 
83
- This package provides a modular and extendable foundation for your design system, broken into the following areas:
97
+ - `ThemeProviderWrapper` abstracts away the creation and management of the MUI theme.
98
+ - It provides built-in support for dark mode, system preferences, and the `useAppThemeProvider` hook.
99
+ - `GlobalStyles` ensures base UI styles adapt to the current theme.
100
+ - Place the wrapper as high in the component tree as possible to ensure theme availability across the app.
84
101
 
85
- ### 🎨 Theme Generator (`createCustomTheme`)
86
- - Dynamically generate MUI themes using custom primary and secondary colors.
87
- - Supports light, dark, system, and auto modes.
88
- - Automatically adapts based on background contrast.
102
+ ### 3.2 Switching Theme Mode (Light/Dark)
89
103
 
90
- ### 🧩 Component Overrides (`commonComponentProps`)
91
- - Global style customizations for common MUI components (e.g. `Button`, `Tooltip`, `Dialog`, `Slider`).
92
- - Shared defaults to ensure consistent spacing, border-radius, shadows, and blur effects.
104
+ The design system includes a built-in hook β€” `useThemeSettings()` β€” to manage theme mode and apply it consistently across your app.
93
105
 
94
- ### ✍️ Typography Variants (`typographyVariants`)
95
- - Dozens of additional font sizes and weights beyond MUI defaults.
96
- - Uses names like `text_md_regular`, `display_lg_bold` for clarity and structure.
97
- - Easily configurable in your MUI theme's `typography` field.
106
+ It supports four modes out of the box:
107
+ - `light`
108
+ - `dark`
109
+ - `system` β€” matches the user’s OS-level preference
110
+ - `auto` β€” determines best contrast based on theme background
98
111
 
99
- ### πŸ–₯ Global Styles (`GlobalStyles`)
100
- - Applies global CSS resets and base styles (scrollbars, font, highlight colors).
101
- - Reacts to theme mode (`light` or `dark`) to dynamically adjust UI contrast.
102
- - Uses Emotion’s `<Global />` component under the hood.
112
+ #### 🧩 Example: Custom Toggle with Options
103
113
 
104
- ### 🎞 Animations (`keyframes`)
105
- - Predefined keyframes for fade, slide, scale, and pulse effects.
106
- - Includes customizable utilities like `pulseAnimation(color)` and `progressPulse(color)`.
114
+ ```tsx
115
+ import {
116
+ useThemeSettings,
117
+ themes,
118
+ } from '@atomazing-org/design-system';
107
119
 
108
- ### πŸ›  Utilities
109
- - `getFontColor`: Calculates readable font color from a background hex.
110
- - `isDarkMode`: Detects appropriate mode based on system or color contrast.
111
- - `systemInfo`: Returns the user's OS and browser in a reliable format.
120
+ const { darkMode, setDarkMode } = useThemeSettings();
121
+
122
+ <CustomRadioGroup
123
+ options={[
124
+ { label: 'Auto', value: 'auto' },
125
+ { label: 'System', value: 'system' },
126
+ { label: 'Light', value: 'light' },
127
+ { label: 'Dark', value: 'dark' },
128
+ ]}
129
+ value={darkMode}
130
+ onChange={val => setDarkMode(val)}
131
+ />
132
+ ```
112
133
 
113
- ---
114
134
 
115
- These modules are built to be tree-shakable and can be imported individually.
135
+ ### 3.3 Custom Theme Colors
116
136
 
117
- ## 5. Usage Examples
137
+ The design system allows you to create and switch between custom color themes using the `createCustomTheme()` function internally via `ThemeProviderWrapper`.
118
138
 
119
- This section shows how to integrate the design system in your React application.
139
+ You can define as many themes as needed by specifying:
140
+ - `primaryColor`: main branding color
141
+ - `secondaryColor` (optional): used for background and surface elements
120
142
 
121
- ### 5.1. Wrapping with ThemeProvider
143
+ #### 🎨 Example: Theme Definitions
122
144
 
123
- ```tsx
124
- import React from 'react';
125
- import ReactDOM from 'react-dom/client';
126
- import App from './App';
145
+ ```ts
146
+ export const themeConfig = {
147
+ BPM: {
148
+ primaryColor: '#203959',
149
+ secondaryColor: '#ffffff',
150
+ },
151
+ Lanit: {
152
+ primaryColor: '#33ccff',
153
+ secondaryColor: '#f7f7f7',
154
+ },
155
+ "Dark Purple": {
156
+ primaryColor: '#b624ff',
157
+ },
158
+ "Light Orange": {
159
+ primaryColor: '#F26E56',
160
+ secondaryColor: '#F6F6F6',
161
+ },
162
+ };
163
+ ```
127
164
 
128
- import {
129
- createCustomTheme,
130
- GlobalStyles,
131
- } from '@atomazing-org/design-system';
165
+ ## 4. Peer Dependencies & Requirements
132
166
 
133
- import { ThemeProvider, CssBaseline } from '@mui/material';
167
+ The `@atomazing-org/design-system` package is built on top of [Material UI v7](https://mui.com/) and [Emotion](https://emotion.sh/) and requires the following peer dependencies to be present in your project.
134
168
 
135
- const theme = createCustomTheme('#4461F2', '#F9F9FC', 'light');
169
+ Install them manually if not already included:
136
170
 
137
- ReactDOM.createRoot(document.getElementById('root')!).render(
138
- <ThemeProvider theme={theme}>
139
- <CssBaseline />
140
- <GlobalStyles />
141
- <App />
142
- </ThemeProvider>,
143
- );
171
+ ### πŸ“¦ Required Peer Dependencies
172
+
173
+ | Package | Version | Purpose |
174
+ |----------------------------|------------|-----------------------------------------|
175
+ | `@mui/material` | ^7.0.0 | Core MUI components and theming |
176
+ | `@mui/icons-material` | ^7.0.0 | MUI icon set |
177
+ | `@emotion/react` | ^11.0.0 | Emotion’s core rendering runtime |
178
+ | `@emotion/styled` | ^11.0.0 | Styled components engine |
179
+ | `@emotion/css` | ^11.0.0 | (Optional) For raw CSS class generation |
180
+
181
+ You can install all required peers with:
182
+
183
+ ```bash
184
+ npm install @mui/material @mui/icons-material @emotion/react @emotion/styled @emotion/css
144
185
  ```
145
186
 
146
- ## 6. Customization
187
+ ## 5. Utilities
147
188
 
148
- The design system is built to be flexible and extendable. You can override or extend the default behavior in several ways.
189
+ The design system includes a collection of lightweight, framework-agnostic utility functions and hooks to support theming, contrast handling, and device detection.
149
190
 
150
- ### 6.1. Customizing the Theme
191
+ ---
151
192
 
152
- You can generate your own theme using `createCustomTheme`:
193
+ ### 5.1 Color Utilities
153
194
 
154
- ```ts
155
- import { createCustomTheme } from '@atomazing-org/design-system';
195
+ #### 🎯 `getFontColor(backgroundColor: string): string`
156
196
 
157
- const theme = createCustomTheme(
158
- '#0088cc', // primary color
159
- '#f0f4f8', // background (secondary) color
160
- 'light', // palette mode
161
- );
197
+ Returns the best readable font color (`dark` or `light`) based on the background brightness.
198
+
199
+ ```ts
200
+ const textColor = getFontColor('#ffffff'); // β†’ "#101727" (dark)
162
201
  ```
163
202
 
164
- ## 7. Tree-Shaking & Importing
203
+ - Accepts any valid hex color (`#fff`, `#ffffff`)
204
+ - Automatically expands short hex (`#abc` β†’ `#aabbcc`)
205
+ - Uses WCAG-recommended brightness formula
206
+ - Returns fallback (`fontDark`) if invalid color
165
207
 
166
- The `@atomazing-org/design-system` package is optimized for modern bundlers and supports tree-shaking out of the box.
208
+ This is useful for generating accessible dynamic UI colors β€” especially in theme builders or color pickers.
167
209
 
168
- To minimize bundle size:
210
+ ---
169
211
 
170
- ### 7.1. Use Named Imports
212
+ ### 5.2 System Info
171
213
 
172
- Instead of importing everything at once, prefer named imports:
214
+ #### 🧩 `systemInfo: { os: OperatingSystem; browser: Browser }`
173
215
 
174
- ```ts
175
- // βœ… Recommended (tree-shakable)
176
- import { fadeIn, getFontColor } from '@atomazing-org/design-system';
216
+ Detects the user's operating system and browser at runtime based on the `navigator.userAgent`.
177
217
 
178
- // 🚫 Not recommended (bundles everything)
179
- import * as DesignSystem from '@atomazing-org/design-system';
218
+ ```ts
219
+ console.log(systemInfo.os); // "macOS" | "Windows" | "Linux" | ...
220
+ console.log(systemInfo.browser); // "Chrome" | "Safari" | ...
180
221
  ```
181
222
 
182
- ## 8. Contribution Guide
223
+ > Uses lightweight string matching for compatibility across most modern devices.
183
224
 
184
- We welcome contributions to the design system! Whether it's improving styles, fixing bugs, or adding utilities β€” every improvement helps.
225
+ #### πŸŒ“ `useSystemTheme(): 'light' | 'dark' | 'unknown'`
185
226
 
186
- ### 8.1. Getting Started
227
+ React hook that listens for system-level theme changes.
187
228
 
188
- Clone the repository and install dependencies:
229
+ ```ts
230
+ const systemTheme = useSystemTheme();
189
231
 
190
- ```bash
191
- git clone https://github.com/atomazing/design-system.git
192
- cd design-system
193
- npm install
232
+ useEffect(() => {
233
+ console.log('System prefers:', systemTheme);
234
+ }, [systemTheme]);
194
235
  ```
195
236
 
196
- ## 9. License
197
-
198
- This project is licensed under the [MIT License](./LICENSE).
199
-
200
- You are free to use, modify, distribute, and sublicense the design system in your projects, whether personal or commercial.
237
+ - Responds to changes in `(prefers-color-scheme)`
238
+ - Automatically updates the value when system settings are changed
239
+ - Useful for defaulting UI themes before user makes a selection
201
240
 
202
241
  ---
203
242
 
204
- Β© PonomarevBPM + MarkSinD, 2025
205
- Maintained under the Atomazing Org initiative.
243
+ These utilities are tree-shakable and can be used independently of the rest of the design system.
244
+
206
245
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atomazing-org/design-system",
3
- "version": "1.0.14",
3
+ "version": "1.0.16",
4
4
  "private": false,
5
5
  "description": "A library providing a set of useful utils, MUI style extensions, and components to build your application.",
6
6
  "author": "PonomarevBPM + MarkSinD",