@alkimi.org/ui-kit 0.1.15 → 0.1.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 (6) hide show
  1. package/README.github.md +131 -88
  2. package/README.md +131 -88
  3. package/README.npm.md +131 -88
  4. package/dist/components/button.d.mts +1 -1
  5. package/dist/components/button.d.ts +1 -1
  6. package/package.json +1 -1
package/README.github.md CHANGED
@@ -10,15 +10,28 @@ npm install @alkimi.org/ui-kit
10
10
 
11
11
  ## Setup
12
12
 
13
- ### 1. Install Tailwind CSS v4
13
+ You have **two setup options** depending on your needs:
14
14
 
15
- If you haven't already, install Tailwind CSS v4 and its dependencies in your project:
15
+ - **Option A (Recommended)**: Import pre-compiled library styles - simpler setup, works immediately
16
+ - **Option B (Advanced)**: Manual styling with full control - requires more configuration
17
+
18
+ Choose the option that best fits your project requirements.
19
+
20
+ ---
21
+
22
+ ### Option A: Import Library Styles (Recommended)
23
+
24
+ **Best for**: Most projects. Simple setup with minimal configuration.
25
+
26
+ **What you get**: Pre-compiled utility classes (`rounded-lg`, `bg-primary`, etc.) + CSS variables + fonts
27
+
28
+ #### 1. Install Tailwind CSS v4
16
29
 
17
30
  ```bash
18
31
  npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
19
32
  ```
20
33
 
21
- ### 2. Configure PostCSS
34
+ #### 2. Configure PostCSS
22
35
 
23
36
  Create or update your `postcss.config.js`:
24
37
 
@@ -31,119 +44,149 @@ module.exports = {
31
44
  }
32
45
  ```
33
46
 
34
- ### 3. Configure Tailwind
47
+ #### 3. Import Library Styles
35
48
 
36
- Create a `tailwind.config.js` to specify your content paths:
49
+ In your root layout file (e.g., `app/layout.tsx` for Next.js App Router):
37
50
 
38
- ```js
39
- /** @type {import('tailwindcss').Config} */
40
- module.exports = {
41
- content: [
42
- // 👇 Scans YOUR project files for Tailwind classes
43
- "./src/**/*.{js,jsx,ts,tsx}",
44
- "./app/**/*.{js,jsx,ts,tsx}", // If using Next.js App Router
45
- "./pages/**/*.{js,jsx,ts,tsx}", // If using Next.js Pages Router
46
- "./components/**/*.{js,jsx,ts,tsx}",
47
-
48
- // 👇 Scans the UI Kit's components for their Tailwind classes
49
- // (Required for library components to be styled correctly)
50
- "./node_modules/@alkimi.org/ui-kit/dist/**/*.{js,mjs}",
51
- ],
52
- }
51
+ ```tsx
52
+ import "@alkimi.org/ui-kit/styles.css"
53
+ import "./globals.css" // Your custom CSS
53
54
  ```
54
55
 
55
- **Important**: The second path (`node_modules/@alkimi.org/ui-kit/dist/...`) is **required** for the library components to display correctly. It tells Tailwind to scan the library's compiled files and generate CSS for the utility classes used inside the components (like `bg-primary`, `rounded-3xl`, etc.).
56
+ **Important**: Import the library styles **before** your custom CSS so you can override variables if needed.
56
57
 
57
- ### 4. Import Tailwind in Your CSS
58
+ #### 4. Configure Your CSS
58
59
 
59
- Create or update your main CSS file (e.g., `app.css` or `globals.css`):
60
+ Create your `globals.css`:
60
61
 
61
62
  ```css
62
63
  @import "tailwindcss";
64
+
65
+ /* Optional: Override library CSS variables */
66
+ :root {
67
+ /* Example: Custom primary color */
68
+ --primary: oklch(0.992 0.019 155.826);
69
+ --primary-foreground: oklch(0.205 0 0);
70
+
71
+ /* You can override any of these variables:
72
+ --secondary, --secondary-foreground
73
+ --background, --foreground
74
+ --muted, --muted-foreground
75
+ --accent, --accent-foreground
76
+ --destructive, --destructive-foreground
77
+ --border, --input, --ring
78
+ --radius (border radius)
79
+ */
80
+ }
63
81
  ```
64
82
 
65
- ### 5. Import Styles
83
+ **That's it!** The library components will work immediately because:
66
84
 
67
- Import the library's CSS in your main application file (e.g., `App.tsx` or `index.tsx`):
85
+ - `styles.css` contains pre-compiled utility classes
86
+ - All CSS variables are defined
87
+ - Fonts are included
88
+ - **No `@source` directive needed** (utilities are already compiled into the CSS)
68
89
 
69
- ```tsx
70
- import "@alkimi.org/ui-kit/styles.css"
71
- ```
90
+ #### When to Use Option A
72
91
 
73
- ## Customizing Colors
92
+ - You want the quickest setup
93
+ - You're happy with the library's default styling approach
94
+ - You want to customize colors via CSS variables
95
+ - You don't need complete control over Tailwind configuration
74
96
 
75
- The library uses CSS variables for colors, making it easy to customize. You have two approaches:
97
+ ---
76
98
 
77
- ### Option A: Override CSS Variables (Recommended)
99
+ ### Option B: Manual Styling (Advanced)
78
100
 
79
- Add custom color values to your CSS file **after** importing the library styles:
101
+ **Best for**: Advanced users who want complete control over CSS generation and Tailwind configuration.
80
102
 
81
- ```css
82
- /* In your app.css or globals.css */
83
- @import "tailwindcss";
84
- @import "@alkimi.org/ui-kit/styles.css";
103
+ **What you do**: Define all CSS variables yourself and use `@source` to dynamically generate utility classes.
85
104
 
86
- /* 👇 Override the library's default colors */
87
- @layer base {
88
- :root {
89
- /* Your custom colors (HSL format: Hue Saturation% Lightness%) */
90
- --primary: 220 100% 50%; /* Custom blue primary color */
91
- --primary-foreground: 0 0% 100%; /* White text on primary */
92
- --secondary: 280 60% 60%; /* Custom purple secondary */
93
- --background: 0 0% 100%; /* White background */
94
- --foreground: 0 0% 0%; /* Black text */
95
-
96
- /* You can override any of these variables:
97
- --muted, --muted-foreground
98
- --accent, --accent-foreground
99
- --destructive, --destructive-foreground
100
- --border, --input, --ring
101
- --radius (border radius)
102
- */
103
- }
105
+ #### 1. Install Tailwind CSS v4
106
+
107
+ ```bash
108
+ npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
109
+ ```
110
+
111
+ #### 2. Configure PostCSS
112
+
113
+ Create or update your `postcss.config.js`:
114
+
115
+ ```js
116
+ module.exports = {
117
+ plugins: {
118
+ "@tailwindcss/postcss": {},
119
+ autoprefixer: {},
120
+ },
104
121
  }
105
122
  ```
106
123
 
107
- ### Option B: Don't Import Library CSS (Manual Setup)
124
+ #### 3. Do NOT Import Library Styles
125
+
126
+ In your root layout file (e.g., `app/layout.tsx`):
127
+
128
+ ```tsx
129
+ // ❌ Do NOT import library styles in Option B
130
+ // import "@alkimi.org/ui-kit/styles.css"
131
+
132
+ import "./globals.css" // Only import your custom CSS
133
+ ```
134
+
135
+ #### 4. Configure Your CSS with @source
108
136
 
109
- If you want complete control, skip importing the library CSS and define all variables yourself:
137
+ Create your `globals.css`:
110
138
 
111
139
  ```css
112
- /* In your app.css or globals.css */
113
140
  @import "tailwindcss";
114
141
 
115
- @layer base {
116
- :root {
117
- /* Define ALL color variables used by the library */
118
- --background: 0 0% 100%;
119
- --foreground: 0 0% 0%;
120
- --card: 0 0% 100%;
121
- --card-foreground: 0 0% 0%;
122
- --popover: 0 0% 100%;
123
- --popover-foreground: 0 0% 0%;
124
- --primary: 220 100% 50%;
125
- --primary-foreground: 0 0% 100%;
126
- --secondary: 280 60% 60%;
127
- --secondary-foreground: 0 0% 100%;
128
- --muted: 0 0% 96%;
129
- --muted-foreground: 0 0% 45%;
130
- --accent: 0 0% 96%;
131
- --accent-foreground: 0 0% 0%;
132
- --destructive: 0 84% 60%;
133
- --destructive-foreground: 0 0% 100%;
134
- --border: 0 0% 90%;
135
- --input: 0 0% 90%;
136
- --ring: 220 100% 50%;
137
- --radius: 0.5rem;
138
- }
142
+ /* REQUIRED: Tell Tailwind v4 to scan library components */
143
+ @source "../node_modules/@alkimi.org/ui-kit/dist/**/*.{js,mjs}";
144
+
145
+ /* REQUIRED: Define ALL CSS variables the library needs */
146
+ :root {
147
+ --background: oklch(0.992 0.019 155.826);
148
+ --foreground: oklch(0.205 0 0);
149
+ --card: oklch(0.992 0.019 155.826);
150
+ --card-foreground: oklch(0.205 0 0);
151
+ --popover: oklch(0.992 0.019 155.826);
152
+ --popover-foreground: oklch(0.205 0 0);
153
+ --primary: oklch(0.992 0.019 155.826);
154
+ --primary-foreground: oklch(0.205 0 0);
155
+ --secondary: oklch(0.269 0 0);
156
+ --secondary-foreground: oklch(0.992 0.019 155.826);
157
+ --muted: oklch(0.269 0 0);
158
+ --muted-foreground: oklch(0.608 0 0);
159
+ --accent: oklch(0.269 0 0);
160
+ --accent-foreground: oklch(0.992 0.019 155.826);
161
+ --destructive: oklch(0.576 0.214 25.467);
162
+ --destructive-foreground: oklch(0.992 0.019 155.826);
163
+ --border: #3f3f46;
164
+ --input: #3f3f46;
165
+ --ring: oklch(0.992 0.019 155.826);
166
+ --radius: 0.625rem;
167
+ --font-family: "Helvetica Now Display", "Helvetica", sans-serif;
168
+ }
139
169
 
140
- body {
141
- @apply bg-background text-foreground;
142
- }
170
+ body {
171
+ @apply bg-background text-foreground;
143
172
  }
144
173
  ```
145
174
 
146
- **Note**: When using Option B, don't import `@alkimi.org/ui-kit/styles.css` in your code.
175
+ **Key points**:
176
+
177
+ - The `@source` directive tells Tailwind v4 to scan the library's component files
178
+ - Tailwind will dynamically generate utility classes for any classes used in those components
179
+ - You must define all CSS variables the library expects
180
+ - VS Code may show a warning for `@source` - you can safely ignore it (it's a valid Tailwind v4 directive)
181
+
182
+ #### When to Use Option B
183
+
184
+ - You want complete control over CSS generation
185
+ - You're customizing Tailwind's configuration extensively
186
+ - You want to manage all CSS variables manually
187
+ - You're comfortable with more advanced Tailwind v4 configuration
188
+
189
+ ---
147
190
 
148
191
  ## Typography & Sizing
149
192
 
@@ -181,7 +224,7 @@ You can override the default font family by setting the `--font-family` CSS vari
181
224
  @layer base {
182
225
  :root {
183
226
  /* Override the library's default font */
184
- --font-family: 'Your Custom Font', 'Helvetica', sans-serif;
227
+ --font-family: "Your Custom Font", "Helvetica", sans-serif;
185
228
  }
186
229
  }
187
230
  ```
@@ -190,11 +233,11 @@ Make sure to include your custom font using `@font-face` or a web font service l
190
233
 
191
234
  ```css
192
235
  /* Example: Using Google Fonts */
193
- @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
236
+ @import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap");
194
237
 
195
238
  @layer base {
196
239
  :root {
197
- --font-family: 'Inter', system-ui, sans-serif;
240
+ --font-family: "Inter", system-ui, sans-serif;
198
241
  }
199
242
  }
200
243
  ```
package/README.md CHANGED
@@ -10,15 +10,28 @@ npm install @alkimi.org/ui-kit
10
10
 
11
11
  ## Setup
12
12
 
13
- ### 1. Install Tailwind CSS v4
13
+ You have **two setup options** depending on your needs:
14
14
 
15
- If you haven't already, install Tailwind CSS v4 and its dependencies in your project:
15
+ - **Option A (Recommended)**: Import pre-compiled library styles - simpler setup, works immediately
16
+ - **Option B (Advanced)**: Manual styling with full control - requires more configuration
17
+
18
+ Choose the option that best fits your project requirements.
19
+
20
+ ---
21
+
22
+ ### Option A: Import Library Styles (Recommended)
23
+
24
+ **Best for**: Most projects. Simple setup with minimal configuration.
25
+
26
+ **What you get**: Pre-compiled utility classes (`rounded-lg`, `bg-primary`, etc.) + CSS variables + fonts
27
+
28
+ #### 1. Install Tailwind CSS v4
16
29
 
17
30
  ```bash
18
31
  npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
19
32
  ```
20
33
 
21
- ### 2. Configure PostCSS
34
+ #### 2. Configure PostCSS
22
35
 
23
36
  Create or update your `postcss.config.js`:
24
37
 
@@ -31,119 +44,149 @@ module.exports = {
31
44
  }
32
45
  ```
33
46
 
34
- ### 3. Configure Tailwind
47
+ #### 3. Import Library Styles
35
48
 
36
- Create a `tailwind.config.js` to specify your content paths:
49
+ In your root layout file (e.g., `app/layout.tsx` for Next.js App Router):
37
50
 
38
- ```js
39
- /** @type {import('tailwindcss').Config} */
40
- module.exports = {
41
- content: [
42
- // Scans YOUR project files for Tailwind classes
43
- "./src/**/*.{js,jsx,ts,tsx}",
44
- "./app/**/*.{js,jsx,ts,tsx}", // If using Next.js App Router
45
- "./pages/**/*.{js,jsx,ts,tsx}", // If using Next.js Pages Router
46
- "./components/**/*.{js,jsx,ts,tsx}",
47
-
48
- // Scans the UI Kit's components for their Tailwind classes
49
- // (Required for library components to be styled correctly)
50
- "./node_modules/@alkimi.org/ui-kit/dist/**/*.{js,mjs}",
51
- ],
52
- }
51
+ ```tsx
52
+ import "@alkimi.org/ui-kit/styles.css"
53
+ import "./globals.css" // Your custom CSS
53
54
  ```
54
55
 
55
- **Important**: The second path (`node_modules/@alkimi.org/ui-kit/dist/...`) is **required** for the library components to display correctly. It tells Tailwind to scan the library's compiled files and generate CSS for the utility classes used inside the components (like `bg-primary`, `rounded-3xl`, etc.).
56
+ **Important**: Import the library styles **before** your custom CSS so you can override variables if needed.
56
57
 
57
- ### 4. Import Tailwind in Your CSS
58
+ #### 4. Configure Your CSS
58
59
 
59
- Create or update your main CSS file (e.g., `app.css` or `globals.css`):
60
+ Create your `globals.css`:
60
61
 
61
62
  ```css
62
63
  @import "tailwindcss";
64
+
65
+ /* Optional: Override library CSS variables */
66
+ :root {
67
+ /* Example: Custom primary color */
68
+ --primary: oklch(0.992 0.019 155.826);
69
+ --primary-foreground: oklch(0.205 0 0);
70
+
71
+ /* You can override any of these variables:
72
+ --secondary, --secondary-foreground
73
+ --background, --foreground
74
+ --muted, --muted-foreground
75
+ --accent, --accent-foreground
76
+ --destructive, --destructive-foreground
77
+ --border, --input, --ring
78
+ --radius (border radius)
79
+ */
80
+ }
63
81
  ```
64
82
 
65
- ### 5. Import Styles
83
+ **That's it!** The library components will work immediately because:
66
84
 
67
- Import the library's CSS in your main application file (e.g., `App.tsx` or `index.tsx`):
85
+ - `styles.css` contains pre-compiled utility classes
86
+ - All CSS variables are defined
87
+ - Fonts are included
88
+ - **No `@source` directive needed** (utilities are already compiled into the CSS)
68
89
 
69
- ```tsx
70
- import "@alkimi.org/ui-kit/styles.css"
71
- ```
90
+ #### When to Use Option A
72
91
 
73
- ## Customizing Colors
92
+ - You want the quickest setup
93
+ - You're happy with the library's default styling approach
94
+ - You want to customize colors via CSS variables
95
+ - You don't need complete control over Tailwind configuration
74
96
 
75
- The library uses CSS variables for colors, making it easy to customize. You have two approaches:
97
+ ---
76
98
 
77
- ### Option A: Override CSS Variables (Recommended)
99
+ ### Option B: Manual Styling (Advanced)
78
100
 
79
- Add custom color values to your CSS file **after** importing the library styles:
101
+ **Best for**: Advanced users who want complete control over CSS generation and Tailwind configuration.
80
102
 
81
- ```css
82
- /* In your app.css or globals.css */
83
- @import "tailwindcss";
84
- @import "@alkimi.org/ui-kit/styles.css";
103
+ **What you do**: Define all CSS variables yourself and use `@source` to dynamically generate utility classes.
85
104
 
86
- /* 👇 Override the library's default colors */
87
- @layer base {
88
- :root {
89
- /* Your custom colors (HSL format: Hue Saturation% Lightness%) */
90
- --primary: 220 100% 50%; /* Custom blue primary color */
91
- --primary-foreground: 0 0% 100%; /* White text on primary */
92
- --secondary: 280 60% 60%; /* Custom purple secondary */
93
- --background: 0 0% 100%; /* White background */
94
- --foreground: 0 0% 0%; /* Black text */
95
-
96
- /* You can override any of these variables:
97
- --muted, --muted-foreground
98
- --accent, --accent-foreground
99
- --destructive, --destructive-foreground
100
- --border, --input, --ring
101
- --radius (border radius)
102
- */
103
- }
105
+ #### 1. Install Tailwind CSS v4
106
+
107
+ ```bash
108
+ npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
109
+ ```
110
+
111
+ #### 2. Configure PostCSS
112
+
113
+ Create or update your `postcss.config.js`:
114
+
115
+ ```js
116
+ module.exports = {
117
+ plugins: {
118
+ "@tailwindcss/postcss": {},
119
+ autoprefixer: {},
120
+ },
104
121
  }
105
122
  ```
106
123
 
107
- ### Option B: Don't Import Library CSS (Manual Setup)
124
+ #### 3. Do NOT Import Library Styles
125
+
126
+ In your root layout file (e.g., `app/layout.tsx`):
127
+
128
+ ```tsx
129
+ // ❌ Do NOT import library styles in Option B
130
+ // import "@alkimi.org/ui-kit/styles.css"
131
+
132
+ import "./globals.css" // Only import your custom CSS
133
+ ```
134
+
135
+ #### 4. Configure Your CSS with @source
108
136
 
109
- If you want complete control, skip importing the library CSS and define all variables yourself:
137
+ Create your `globals.css`:
110
138
 
111
139
  ```css
112
- /* In your app.css or globals.css */
113
140
  @import "tailwindcss";
114
141
 
115
- @layer base {
116
- :root {
117
- /* Define ALL color variables used by the library */
118
- --background: 0 0% 100%;
119
- --foreground: 0 0% 0%;
120
- --card: 0 0% 100%;
121
- --card-foreground: 0 0% 0%;
122
- --popover: 0 0% 100%;
123
- --popover-foreground: 0 0% 0%;
124
- --primary: 220 100% 50%;
125
- --primary-foreground: 0 0% 100%;
126
- --secondary: 280 60% 60%;
127
- --secondary-foreground: 0 0% 100%;
128
- --muted: 0 0% 96%;
129
- --muted-foreground: 0 0% 45%;
130
- --accent: 0 0% 96%;
131
- --accent-foreground: 0 0% 0%;
132
- --destructive: 0 84% 60%;
133
- --destructive-foreground: 0 0% 100%;
134
- --border: 0 0% 90%;
135
- --input: 0 0% 90%;
136
- --ring: 220 100% 50%;
137
- --radius: 0.5rem;
138
- }
142
+ /* REQUIRED: Tell Tailwind v4 to scan library components */
143
+ @source "../node_modules/@alkimi.org/ui-kit/dist/**/*.{js,mjs}";
144
+
145
+ /* REQUIRED: Define ALL CSS variables the library needs */
146
+ :root {
147
+ --background: oklch(0.992 0.019 155.826);
148
+ --foreground: oklch(0.205 0 0);
149
+ --card: oklch(0.992 0.019 155.826);
150
+ --card-foreground: oklch(0.205 0 0);
151
+ --popover: oklch(0.992 0.019 155.826);
152
+ --popover-foreground: oklch(0.205 0 0);
153
+ --primary: oklch(0.992 0.019 155.826);
154
+ --primary-foreground: oklch(0.205 0 0);
155
+ --secondary: oklch(0.269 0 0);
156
+ --secondary-foreground: oklch(0.992 0.019 155.826);
157
+ --muted: oklch(0.269 0 0);
158
+ --muted-foreground: oklch(0.608 0 0);
159
+ --accent: oklch(0.269 0 0);
160
+ --accent-foreground: oklch(0.992 0.019 155.826);
161
+ --destructive: oklch(0.576 0.214 25.467);
162
+ --destructive-foreground: oklch(0.992 0.019 155.826);
163
+ --border: #3f3f46;
164
+ --input: #3f3f46;
165
+ --ring: oklch(0.992 0.019 155.826);
166
+ --radius: 0.625rem;
167
+ --font-family: "Helvetica Now Display", "Helvetica", sans-serif;
168
+ }
139
169
 
140
- body {
141
- @apply bg-background text-foreground;
142
- }
170
+ body {
171
+ @apply bg-background text-foreground;
143
172
  }
144
173
  ```
145
174
 
146
- **Note**: When using Option B, don't import `@alkimi.org/ui-kit/styles.css` in your code.
175
+ **Key points**:
176
+
177
+ - The `@source` directive tells Tailwind v4 to scan the library's component files
178
+ - Tailwind will dynamically generate utility classes for any classes used in those components
179
+ - You must define all CSS variables the library expects
180
+ - VS Code may show a warning for `@source` - you can safely ignore it (it's a valid Tailwind v4 directive)
181
+
182
+ #### When to Use Option B
183
+
184
+ - You want complete control over CSS generation
185
+ - You're customizing Tailwind's configuration extensively
186
+ - You want to manage all CSS variables manually
187
+ - You're comfortable with more advanced Tailwind v4 configuration
188
+
189
+ ---
147
190
 
148
191
  ## Typography & Sizing
149
192
 
@@ -181,7 +224,7 @@ You can override the default font family by setting the `--font-family` CSS vari
181
224
  @layer base {
182
225
  :root {
183
226
  /* Override the library's default font */
184
- --font-family: 'Your Custom Font', 'Helvetica', sans-serif;
227
+ --font-family: "Your Custom Font", "Helvetica", sans-serif;
185
228
  }
186
229
  }
187
230
  ```
@@ -190,11 +233,11 @@ Make sure to include your custom font using `@font-face` or a web font service l
190
233
 
191
234
  ```css
192
235
  /* Example: Using Google Fonts */
193
- @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
236
+ @import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap");
194
237
 
195
238
  @layer base {
196
239
  :root {
197
- --font-family: 'Inter', system-ui, sans-serif;
240
+ --font-family: "Inter", system-ui, sans-serif;
198
241
  }
199
242
  }
200
243
  ```
package/README.npm.md CHANGED
@@ -10,15 +10,28 @@ npm install @alkimi.org/ui-kit
10
10
 
11
11
  ## Setup
12
12
 
13
- ### 1. Install Tailwind CSS v4
13
+ You have **two setup options** depending on your needs:
14
14
 
15
- If you haven't already, install Tailwind CSS v4 and its dependencies in your project:
15
+ - **Option A (Recommended)**: Import pre-compiled library styles - simpler setup, works immediately
16
+ - **Option B (Advanced)**: Manual styling with full control - requires more configuration
17
+
18
+ Choose the option that best fits your project requirements.
19
+
20
+ ---
21
+
22
+ ### Option A: Import Library Styles (Recommended)
23
+
24
+ **Best for**: Most projects. Simple setup with minimal configuration.
25
+
26
+ **What you get**: Pre-compiled utility classes (`rounded-lg`, `bg-primary`, etc.) + CSS variables + fonts
27
+
28
+ #### 1. Install Tailwind CSS v4
16
29
 
17
30
  ```bash
18
31
  npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
19
32
  ```
20
33
 
21
- ### 2. Configure PostCSS
34
+ #### 2. Configure PostCSS
22
35
 
23
36
  Create or update your `postcss.config.js`:
24
37
 
@@ -31,119 +44,149 @@ module.exports = {
31
44
  }
32
45
  ```
33
46
 
34
- ### 3. Configure Tailwind
47
+ #### 3. Import Library Styles
35
48
 
36
- Create a `tailwind.config.js` to specify your content paths:
49
+ In your root layout file (e.g., `app/layout.tsx` for Next.js App Router):
37
50
 
38
- ```js
39
- /** @type {import('tailwindcss').Config} */
40
- module.exports = {
41
- content: [
42
- // Scans YOUR project files for Tailwind classes
43
- "./src/**/*.{js,jsx,ts,tsx}",
44
- "./app/**/*.{js,jsx,ts,tsx}", // If using Next.js App Router
45
- "./pages/**/*.{js,jsx,ts,tsx}", // If using Next.js Pages Router
46
- "./components/**/*.{js,jsx,ts,tsx}",
47
-
48
- // Scans the UI Kit's components for their Tailwind classes
49
- // (Required for library components to be styled correctly)
50
- "./node_modules/@alkimi.org/ui-kit/dist/**/*.{js,mjs}",
51
- ],
52
- }
51
+ ```tsx
52
+ import "@alkimi.org/ui-kit/styles.css"
53
+ import "./globals.css" // Your custom CSS
53
54
  ```
54
55
 
55
- **Important**: The second path (`node_modules/@alkimi.org/ui-kit/dist/...`) is **required** for the library components to display correctly. It tells Tailwind to scan the library's compiled files and generate CSS for the utility classes used inside the components (like `bg-primary`, `rounded-3xl`, etc.).
56
+ **Important**: Import the library styles **before** your custom CSS so you can override variables if needed.
56
57
 
57
- ### 4. Import Tailwind in Your CSS
58
+ #### 4. Configure Your CSS
58
59
 
59
- Create or update your main CSS file (e.g., `app.css` or `globals.css`):
60
+ Create your `globals.css`:
60
61
 
61
62
  ```css
62
63
  @import "tailwindcss";
64
+
65
+ /* Optional: Override library CSS variables */
66
+ :root {
67
+ /* Example: Custom primary color */
68
+ --primary: oklch(0.992 0.019 155.826);
69
+ --primary-foreground: oklch(0.205 0 0);
70
+
71
+ /* You can override any of these variables:
72
+ --secondary, --secondary-foreground
73
+ --background, --foreground
74
+ --muted, --muted-foreground
75
+ --accent, --accent-foreground
76
+ --destructive, --destructive-foreground
77
+ --border, --input, --ring
78
+ --radius (border radius)
79
+ */
80
+ }
63
81
  ```
64
82
 
65
- ### 5. Import Styles
83
+ **That's it!** The library components will work immediately because:
66
84
 
67
- Import the library's CSS in your main application file (e.g., `App.tsx` or `index.tsx`):
85
+ - `styles.css` contains pre-compiled utility classes
86
+ - All CSS variables are defined
87
+ - Fonts are included
88
+ - **No `@source` directive needed** (utilities are already compiled into the CSS)
68
89
 
69
- ```tsx
70
- import "@alkimi.org/ui-kit/styles.css"
71
- ```
90
+ #### When to Use Option A
72
91
 
73
- ## Customizing Colors
92
+ - You want the quickest setup
93
+ - You're happy with the library's default styling approach
94
+ - You want to customize colors via CSS variables
95
+ - You don't need complete control over Tailwind configuration
74
96
 
75
- The library uses CSS variables for colors, making it easy to customize. You have two approaches:
97
+ ---
76
98
 
77
- ### Option A: Override CSS Variables (Recommended)
99
+ ### Option B: Manual Styling (Advanced)
78
100
 
79
- Add custom color values to your CSS file **after** importing the library styles:
101
+ **Best for**: Advanced users who want complete control over CSS generation and Tailwind configuration.
80
102
 
81
- ```css
82
- /* In your app.css or globals.css */
83
- @import "tailwindcss";
84
- @import "@alkimi.org/ui-kit/styles.css";
103
+ **What you do**: Define all CSS variables yourself and use `@source` to dynamically generate utility classes.
85
104
 
86
- /* 👇 Override the library's default colors */
87
- @layer base {
88
- :root {
89
- /* Your custom colors (HSL format: Hue Saturation% Lightness%) */
90
- --primary: 220 100% 50%; /* Custom blue primary color */
91
- --primary-foreground: 0 0% 100%; /* White text on primary */
92
- --secondary: 280 60% 60%; /* Custom purple secondary */
93
- --background: 0 0% 100%; /* White background */
94
- --foreground: 0 0% 0%; /* Black text */
95
-
96
- /* You can override any of these variables:
97
- --muted, --muted-foreground
98
- --accent, --accent-foreground
99
- --destructive, --destructive-foreground
100
- --border, --input, --ring
101
- --radius (border radius)
102
- */
103
- }
105
+ #### 1. Install Tailwind CSS v4
106
+
107
+ ```bash
108
+ npm install -D tailwindcss@next @tailwindcss/postcss@next postcss autoprefixer
109
+ ```
110
+
111
+ #### 2. Configure PostCSS
112
+
113
+ Create or update your `postcss.config.js`:
114
+
115
+ ```js
116
+ module.exports = {
117
+ plugins: {
118
+ "@tailwindcss/postcss": {},
119
+ autoprefixer: {},
120
+ },
104
121
  }
105
122
  ```
106
123
 
107
- ### Option B: Don't Import Library CSS (Manual Setup)
124
+ #### 3. Do NOT Import Library Styles
125
+
126
+ In your root layout file (e.g., `app/layout.tsx`):
127
+
128
+ ```tsx
129
+ // ❌ Do NOT import library styles in Option B
130
+ // import "@alkimi.org/ui-kit/styles.css"
131
+
132
+ import "./globals.css" // Only import your custom CSS
133
+ ```
134
+
135
+ #### 4. Configure Your CSS with @source
108
136
 
109
- If you want complete control, skip importing the library CSS and define all variables yourself:
137
+ Create your `globals.css`:
110
138
 
111
139
  ```css
112
- /* In your app.css or globals.css */
113
140
  @import "tailwindcss";
114
141
 
115
- @layer base {
116
- :root {
117
- /* Define ALL color variables used by the library */
118
- --background: 0 0% 100%;
119
- --foreground: 0 0% 0%;
120
- --card: 0 0% 100%;
121
- --card-foreground: 0 0% 0%;
122
- --popover: 0 0% 100%;
123
- --popover-foreground: 0 0% 0%;
124
- --primary: 220 100% 50%;
125
- --primary-foreground: 0 0% 100%;
126
- --secondary: 280 60% 60%;
127
- --secondary-foreground: 0 0% 100%;
128
- --muted: 0 0% 96%;
129
- --muted-foreground: 0 0% 45%;
130
- --accent: 0 0% 96%;
131
- --accent-foreground: 0 0% 0%;
132
- --destructive: 0 84% 60%;
133
- --destructive-foreground: 0 0% 100%;
134
- --border: 0 0% 90%;
135
- --input: 0 0% 90%;
136
- --ring: 220 100% 50%;
137
- --radius: 0.5rem;
138
- }
142
+ /* REQUIRED: Tell Tailwind v4 to scan library components */
143
+ @source "../node_modules/@alkimi.org/ui-kit/dist/**/*.{js,mjs}";
144
+
145
+ /* REQUIRED: Define ALL CSS variables the library needs */
146
+ :root {
147
+ --background: oklch(0.992 0.019 155.826);
148
+ --foreground: oklch(0.205 0 0);
149
+ --card: oklch(0.992 0.019 155.826);
150
+ --card-foreground: oklch(0.205 0 0);
151
+ --popover: oklch(0.992 0.019 155.826);
152
+ --popover-foreground: oklch(0.205 0 0);
153
+ --primary: oklch(0.992 0.019 155.826);
154
+ --primary-foreground: oklch(0.205 0 0);
155
+ --secondary: oklch(0.269 0 0);
156
+ --secondary-foreground: oklch(0.992 0.019 155.826);
157
+ --muted: oklch(0.269 0 0);
158
+ --muted-foreground: oklch(0.608 0 0);
159
+ --accent: oklch(0.269 0 0);
160
+ --accent-foreground: oklch(0.992 0.019 155.826);
161
+ --destructive: oklch(0.576 0.214 25.467);
162
+ --destructive-foreground: oklch(0.992 0.019 155.826);
163
+ --border: #3f3f46;
164
+ --input: #3f3f46;
165
+ --ring: oklch(0.992 0.019 155.826);
166
+ --radius: 0.625rem;
167
+ --font-family: "Helvetica Now Display", "Helvetica", sans-serif;
168
+ }
139
169
 
140
- body {
141
- @apply bg-background text-foreground;
142
- }
170
+ body {
171
+ @apply bg-background text-foreground;
143
172
  }
144
173
  ```
145
174
 
146
- **Note**: When using Option B, don't import `@alkimi.org/ui-kit/styles.css` in your code.
175
+ **Key points**:
176
+
177
+ - The `@source` directive tells Tailwind v4 to scan the library's component files
178
+ - Tailwind will dynamically generate utility classes for any classes used in those components
179
+ - You must define all CSS variables the library expects
180
+ - VS Code may show a warning for `@source` - you can safely ignore it (it's a valid Tailwind v4 directive)
181
+
182
+ #### When to Use Option B
183
+
184
+ - You want complete control over CSS generation
185
+ - You're customizing Tailwind's configuration extensively
186
+ - You want to manage all CSS variables manually
187
+ - You're comfortable with more advanced Tailwind v4 configuration
188
+
189
+ ---
147
190
 
148
191
  ## Typography & Sizing
149
192
 
@@ -181,7 +224,7 @@ You can override the default font family by setting the `--font-family` CSS vari
181
224
  @layer base {
182
225
  :root {
183
226
  /* Override the library's default font */
184
- --font-family: 'Your Custom Font', 'Helvetica', sans-serif;
227
+ --font-family: "Your Custom Font", "Helvetica", sans-serif;
185
228
  }
186
229
  }
187
230
  ```
@@ -190,11 +233,11 @@ Make sure to include your custom font using `@font-face` or a web font service l
190
233
 
191
234
  ```css
192
235
  /* Example: Using Google Fonts */
193
- @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
236
+ @import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap");
194
237
 
195
238
  @layer base {
196
239
  :root {
197
- --font-family: 'Inter', system-ui, sans-serif;
240
+ --font-family: "Inter", system-ui, sans-serif;
198
241
  }
199
242
  }
200
243
  ```
package/dist/components/button.d.mts CHANGED
@@ -3,7 +3,7 @@ import * as React from 'react';
3
3
  import { VariantProps } from 'class-variance-authority';
4
4
 
5
5
  declare const buttonVariants: (props?: ({
6
- variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
6
+ variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
7
7
  size?: "default" | "sm" | "lg" | "icon" | null | undefined;
8
8
  } & class_variance_authority_types.ClassProp) | undefined) => string;
9
9
  interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
package/dist/components/button.d.ts CHANGED
@@ -3,7 +3,7 @@ import * as React from 'react';
3
3
  import { VariantProps } from 'class-variance-authority';
4
4
 
5
5
  declare const buttonVariants: (props?: ({
6
- variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
6
+ variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
7
7
  size?: "default" | "sm" | "lg" | "icon" | null | undefined;
8
8
  } & class_variance_authority_types.ClassProp) | undefined) => string;
9
9
  interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alkimi.org/ui-kit",
3
- "version": "0.1.15",
3
+ "version": "0.1.16",
4
4
  "packageManager": "pnpm@10.26.0",
5
5
  "description": "A React component library built with shadcn/ui and Tailwind CSS",
6
6
  "main": "./dist/index.js",