podo-ui 0.4.3 → 0.4.5
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.
- package/AI-GUIDE.md +775 -0
- package/package.json +3 -2
package/AI-GUIDE.md
ADDED
|
@@ -0,0 +1,775 @@
|
|
|
1
|
+
# Podo UI - AI Assistant Guide
|
|
2
|
+
|
|
3
|
+
> **For AI Assistants Only**: This guide provides essential information for AI assistants working with the Podo UI library. This document is distributed with the NPM package.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Package Overview
|
|
8
|
+
|
|
9
|
+
**Podo UI** is a hybrid SCSS-first design system with minimal React components.
|
|
10
|
+
|
|
11
|
+
- **Philosophy**: 97% CSS classes, 3% React components
|
|
12
|
+
- **Distribution**: NPM package with SCSS files and compiled React components
|
|
13
|
+
- **Main exports**: `/dist` (React), `/scss` (SCSS source), `/global.scss`, `/mixin.scss`
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Package Structure (NPM Distribution)
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
podo-ui/
|
|
21
|
+
├── dist/ # Compiled React components (TypeScript → JavaScript)
|
|
22
|
+
│ ├── index.js # Main entry point
|
|
23
|
+
│ ├── index.d.ts # TypeScript definitions
|
|
24
|
+
│ └── react/
|
|
25
|
+
│ ├── atom/ # Atomic components
|
|
26
|
+
│ │ ├── input.js
|
|
27
|
+
│ │ ├── textarea.js
|
|
28
|
+
│ │ ├── editor.js
|
|
29
|
+
│ │ └── editor-view.js
|
|
30
|
+
│ └── molecule/ # Molecular components
|
|
31
|
+
│ ├── field.js
|
|
32
|
+
│ └── pagination.js
|
|
33
|
+
├── scss/ # SCSS source files (DO NOT MODIFY)
|
|
34
|
+
│ ├── button/
|
|
35
|
+
│ ├── color/
|
|
36
|
+
│ ├── form/
|
|
37
|
+
│ ├── icon/
|
|
38
|
+
│ ├── layout/
|
|
39
|
+
│ ├── molecule/
|
|
40
|
+
│ └── typo/
|
|
41
|
+
├── global.scss # Global styles entry point
|
|
42
|
+
├── mixin.scss # SCSS functions and mixins
|
|
43
|
+
├── vite-fonts.scss # Vite-specific font paths
|
|
44
|
+
└── README.md # User documentation
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Import Patterns
|
|
50
|
+
|
|
51
|
+
### ✅ Correct Import Methods
|
|
52
|
+
|
|
53
|
+
```typescript
|
|
54
|
+
// Named imports (recommended)
|
|
55
|
+
import { Input, Textarea, Editor, EditorView, Field, Pagination } from 'podo-ui';
|
|
56
|
+
|
|
57
|
+
// Direct imports (legacy, still supported)
|
|
58
|
+
import Input from 'podo-ui/react/atom/input';
|
|
59
|
+
import Field from 'podo-ui/react/molecule/field';
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### ❌ Incorrect Import Methods
|
|
63
|
+
|
|
64
|
+
```typescript
|
|
65
|
+
// DON'T: Import from dist directly
|
|
66
|
+
import Input from 'podo-ui/dist/react/atom/input';
|
|
67
|
+
|
|
68
|
+
// DON'T: Import from source files (not in NPM package)
|
|
69
|
+
import Input from 'podo-ui/react/atom/input.tsx';
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## SCSS Usage
|
|
75
|
+
|
|
76
|
+
### Global SCSS Import
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
// main.tsx or App.tsx
|
|
80
|
+
import 'podo-ui/global.scss';
|
|
81
|
+
|
|
82
|
+
// If using Vite bundler
|
|
83
|
+
import 'podo-ui/vite-fonts.scss';
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### SCSS Module Usage
|
|
87
|
+
|
|
88
|
+
```scss
|
|
89
|
+
// component.module.scss
|
|
90
|
+
@use 'podo-ui/mixin' as *;
|
|
91
|
+
|
|
92
|
+
.myComponent {
|
|
93
|
+
// Design tokens (ALWAYS use these, not hardcoded values)
|
|
94
|
+
padding: s(5); // Spacing: s(0-13)
|
|
95
|
+
background: color(primary-base); // Color: color(semantic-variant)
|
|
96
|
+
border-radius: r(4); // Radius: r(1-full)
|
|
97
|
+
|
|
98
|
+
@include p1; // Typography: @include display1~7, p1~5
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Available Design Tokens
|
|
103
|
+
|
|
104
|
+
#### Spacing Function: `s(0-13)`
|
|
105
|
+
```
|
|
106
|
+
0: 0px 1: 2px 2: 4px 3: 8px 4: 12px
|
|
107
|
+
5: 16px 6: 24px 7: 32px 8: 40px 9: 48px
|
|
108
|
+
10: 64px 11: 80px 12: 96px 13: 160px
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
#### Color Function: `color(semantic-variant)`
|
|
112
|
+
```
|
|
113
|
+
Semantics: primary, default, default-deep, info, link, success, warning, danger
|
|
114
|
+
Variants: base, hover, pressed, focus, fill, reverse, outline
|
|
115
|
+
|
|
116
|
+
Examples:
|
|
117
|
+
color(primary-base)
|
|
118
|
+
color(danger-hover)
|
|
119
|
+
color(success-fill)
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
#### Radius Function: `r(value)`
|
|
123
|
+
```
|
|
124
|
+
Values: 1, 2, 3, 4, full
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
#### Typography Mixins
|
|
128
|
+
```
|
|
129
|
+
Display: @include display1; @include display2; ... @include display7;
|
|
130
|
+
Paragraph: @include p1; @include p2; @include p3; @include p4; @include p5;
|
|
131
|
+
Semibold variants: @include p1-semibold; @include p2-semibold; etc.
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## React Components API
|
|
137
|
+
|
|
138
|
+
### Input Component
|
|
139
|
+
|
|
140
|
+
```tsx
|
|
141
|
+
import { Input } from 'podo-ui';
|
|
142
|
+
import { z } from 'zod';
|
|
143
|
+
|
|
144
|
+
const emailSchema = z.string().email();
|
|
145
|
+
|
|
146
|
+
<Input
|
|
147
|
+
value={value}
|
|
148
|
+
onChange={setValue}
|
|
149
|
+
placeholder="Enter email"
|
|
150
|
+
validator={emailSchema} // Optional: Zod validator
|
|
151
|
+
withIcon="mail" // Optional: icon name
|
|
152
|
+
unit="원" // Optional: unit display
|
|
153
|
+
/>
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
**Props:**
|
|
157
|
+
- `value`: string
|
|
158
|
+
- `onChange`: (value: string) => void
|
|
159
|
+
- `placeholder`: string (optional)
|
|
160
|
+
- `validator`: Zod schema (optional)
|
|
161
|
+
- `withIcon`: string (optional) - icon name from icon system
|
|
162
|
+
- `unit`: string (optional) - display unit (e.g., "원", "kg")
|
|
163
|
+
- `disabled`: boolean (optional)
|
|
164
|
+
|
|
165
|
+
### Textarea Component
|
|
166
|
+
|
|
167
|
+
```tsx
|
|
168
|
+
import { Textarea } from 'podo-ui';
|
|
169
|
+
|
|
170
|
+
<Textarea
|
|
171
|
+
value={value}
|
|
172
|
+
onChange={setValue}
|
|
173
|
+
placeholder="Enter description"
|
|
174
|
+
validator={schema} // Optional: Zod validator
|
|
175
|
+
/>
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
**Props:** Similar to Input, without `withIcon` and `unit`
|
|
179
|
+
|
|
180
|
+
### Editor Component (WYSIWYG)
|
|
181
|
+
|
|
182
|
+
```tsx
|
|
183
|
+
import { Editor } from 'podo-ui';
|
|
184
|
+
|
|
185
|
+
<Editor
|
|
186
|
+
value={htmlContent}
|
|
187
|
+
onChange={setHtmlContent}
|
|
188
|
+
height="400px" // Or "contents" for auto-height
|
|
189
|
+
placeholder="Enter content"
|
|
190
|
+
validator={schema} // Optional: Zod validator
|
|
191
|
+
/>
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
**Props:**
|
|
195
|
+
- `value`: string (HTML content)
|
|
196
|
+
- `onChange`: (html: string) => void
|
|
197
|
+
- `height`: string | "contents" (optional, default: "400px")
|
|
198
|
+
- `placeholder`: string (optional)
|
|
199
|
+
- `validator`: Zod schema (optional)
|
|
200
|
+
|
|
201
|
+
**Features:**
|
|
202
|
+
- Rich text formatting (bold, italic, underline, strikethrough)
|
|
203
|
+
- Headers (H1-H6), paragraphs, blockquotes
|
|
204
|
+
- Text alignment, font, size, color
|
|
205
|
+
- Image upload and editing
|
|
206
|
+
- YouTube video embedding
|
|
207
|
+
- Resizable
|
|
208
|
+
|
|
209
|
+
### EditorView Component (Read-only)
|
|
210
|
+
|
|
211
|
+
```tsx
|
|
212
|
+
import { EditorView } from 'podo-ui';
|
|
213
|
+
|
|
214
|
+
<EditorView value={htmlContent} />
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
**Props:**
|
|
218
|
+
- `value`: string (HTML content from Editor)
|
|
219
|
+
|
|
220
|
+
**Purpose:** Display HTML content generated by Editor component in read-only mode.
|
|
221
|
+
|
|
222
|
+
### Field Component (Form Field Wrapper)
|
|
223
|
+
|
|
224
|
+
```tsx
|
|
225
|
+
import { Field, Input } from 'podo-ui';
|
|
226
|
+
|
|
227
|
+
<Field
|
|
228
|
+
label="Email"
|
|
229
|
+
required
|
|
230
|
+
helper="Enter a valid email address"
|
|
231
|
+
validator={emailSchema}
|
|
232
|
+
value={email}
|
|
233
|
+
>
|
|
234
|
+
<Input value={email} onChange={setEmail} />
|
|
235
|
+
</Field>
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
**Props:**
|
|
239
|
+
- `label`: string
|
|
240
|
+
- `required`: boolean (optional) - shows asterisk
|
|
241
|
+
- `helper`: string (optional) - helper text
|
|
242
|
+
- `validator`: Zod schema (optional)
|
|
243
|
+
- `value`: string (optional) - for validation display
|
|
244
|
+
- `children`: ReactNode - input component
|
|
245
|
+
|
|
246
|
+
### Pagination Component
|
|
247
|
+
|
|
248
|
+
```tsx
|
|
249
|
+
import { Pagination } from 'podo-ui';
|
|
250
|
+
|
|
251
|
+
<Pagination
|
|
252
|
+
currentPage={currentPage}
|
|
253
|
+
totalPages={10}
|
|
254
|
+
onPageChange={setCurrentPage}
|
|
255
|
+
/>
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
**Props:**
|
|
259
|
+
- `currentPage`: number
|
|
260
|
+
- `totalPages`: number
|
|
261
|
+
- `onPageChange`: (page: number) => void
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## CSS Classes (Utility Classes)
|
|
266
|
+
|
|
267
|
+
### Button Classes
|
|
268
|
+
|
|
269
|
+
```html
|
|
270
|
+
<!-- Semantic variants -->
|
|
271
|
+
<button class="primary">Primary</button>
|
|
272
|
+
<button class="default">Default</button>
|
|
273
|
+
<button class="info">Info</button>
|
|
274
|
+
<button class="success">Success</button>
|
|
275
|
+
<button class="warning">Warning</button>
|
|
276
|
+
<button class="danger">Danger</button>
|
|
277
|
+
<button class="link">Link</button>
|
|
278
|
+
|
|
279
|
+
<!-- Sizes -->
|
|
280
|
+
<button class="primary small">Small</button>
|
|
281
|
+
<button class="primary large">Large</button>
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
### Form Elements
|
|
285
|
+
|
|
286
|
+
```html
|
|
287
|
+
<!-- Input -->
|
|
288
|
+
<input type="text" placeholder="Text input" />
|
|
289
|
+
|
|
290
|
+
<!-- Textarea -->
|
|
291
|
+
<textarea placeholder="Textarea"></textarea>
|
|
292
|
+
|
|
293
|
+
<!-- Select -->
|
|
294
|
+
<select>
|
|
295
|
+
<option>Option 1</option>
|
|
296
|
+
<option>Option 2</option>
|
|
297
|
+
</select>
|
|
298
|
+
|
|
299
|
+
<!-- Checkbox -->
|
|
300
|
+
<label>
|
|
301
|
+
<input type="checkbox" />
|
|
302
|
+
Checkbox label
|
|
303
|
+
</label>
|
|
304
|
+
|
|
305
|
+
<!-- Radio -->
|
|
306
|
+
<label>
|
|
307
|
+
<input type="radio" name="group" />
|
|
308
|
+
Radio label
|
|
309
|
+
</label>
|
|
310
|
+
|
|
311
|
+
<!-- Toggle -->
|
|
312
|
+
<label>
|
|
313
|
+
<input type="checkbox" role="switch" />
|
|
314
|
+
Toggle switch
|
|
315
|
+
</label>
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
### Grid System
|
|
319
|
+
|
|
320
|
+
```html
|
|
321
|
+
<!-- Auto-wrapping grid -->
|
|
322
|
+
<div class="grid">
|
|
323
|
+
<div class="w-4">Column 1 (4/12)</div>
|
|
324
|
+
<div class="w-8">Column 2 (8/12)</div>
|
|
325
|
+
</div>
|
|
326
|
+
|
|
327
|
+
<!-- Fixed column grid -->
|
|
328
|
+
<div class="grid-fix-3">
|
|
329
|
+
<div>Item 1</div>
|
|
330
|
+
<div>Item 2</div>
|
|
331
|
+
<div>Item 3</div>
|
|
332
|
+
</div>
|
|
333
|
+
|
|
334
|
+
<!-- Width utilities -->
|
|
335
|
+
<div class="w-6">50% width (6/12)</div>
|
|
336
|
+
<div class="w-200px">200px width</div>
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
**Grid columns:**
|
|
340
|
+
- PC: 12 columns
|
|
341
|
+
- Tablet: 6 columns
|
|
342
|
+
- Mobile: 4 columns
|
|
343
|
+
|
|
344
|
+
**Width classes:**
|
|
345
|
+
- `.w-1` to `.w-12` (column-based)
|
|
346
|
+
- `.w-1_4`, `.w-2_6`, etc. (fraction-based)
|
|
347
|
+
- `.w-{n}px` (0-5000, pixel-based)
|
|
348
|
+
|
|
349
|
+
### Spacing Utilities
|
|
350
|
+
|
|
351
|
+
```html
|
|
352
|
+
<!-- Padding -->
|
|
353
|
+
<div class="p-5">Padding 16px all sides</div>
|
|
354
|
+
<div class="p-t-3">Padding-top 8px</div>
|
|
355
|
+
<div class="p-l-4 p-r-4">Padding left/right 12px</div>
|
|
356
|
+
|
|
357
|
+
<!-- Margin -->
|
|
358
|
+
<div class="m-6">Margin 24px all sides</div>
|
|
359
|
+
<div class="m-b-7">Margin-bottom 32px</div>
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
**Pattern:** `{property}-{direction?}-{value}`
|
|
363
|
+
- Property: `p` (padding), `m` (margin)
|
|
364
|
+
- Direction: `t` (top), `b` (bottom), `l` (left), `r` (right), `x` (horizontal), `y` (vertical), or omit for all
|
|
365
|
+
- Value: 0-13 (see spacing scale above)
|
|
366
|
+
|
|
367
|
+
### Border Radius Utilities
|
|
368
|
+
|
|
369
|
+
```html
|
|
370
|
+
<div class="r-2">Small radius</div>
|
|
371
|
+
<div class="r-4">Medium radius</div>
|
|
372
|
+
<div class="r-full">Full rounded (pill shape)</div>
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
### Icon System
|
|
376
|
+
|
|
377
|
+
```html
|
|
378
|
+
<i class="icon-star"></i>
|
|
379
|
+
<i class="icon-heart-fill"></i>
|
|
380
|
+
<i class="icon-check"></i>
|
|
381
|
+
<i class="icon-x"></i>
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
**Complete Icon List (117 icons):**
|
|
385
|
+
|
|
386
|
+
```
|
|
387
|
+
// Basic Actions
|
|
388
|
+
icon-plus icon-minus icon-close
|
|
389
|
+
icon-check icon-check-small icon-cancel
|
|
390
|
+
icon-edit icon-save icon-delete
|
|
391
|
+
icon-trash icon-refresh
|
|
392
|
+
|
|
393
|
+
// Arrows
|
|
394
|
+
icon-arrow-up icon-arrow-down icon-arrow-left
|
|
395
|
+
icon-arrow-right icon-arrow-dropdown icon-arrow-dropdown-up
|
|
396
|
+
icon-arrow-dropdown-left icon-arrow-dropdown-right
|
|
397
|
+
|
|
398
|
+
// Expand/Collapse
|
|
399
|
+
icon-expand-up icon-expand-down icon-expand-left
|
|
400
|
+
icon-expand-right icon-expand-up-double icon-expand-down-double
|
|
401
|
+
icon-expand-left-double icon-expand-right-double
|
|
402
|
+
|
|
403
|
+
// Navigation
|
|
404
|
+
icon-home icon-menu icon-search
|
|
405
|
+
icon-more icon-more-horizontal icon-map
|
|
406
|
+
icon-compass icon-gps
|
|
407
|
+
|
|
408
|
+
// Communication
|
|
409
|
+
icon-mail icon-email icon-phone
|
|
410
|
+
icon-phone-stroke icon-dm icon-share
|
|
411
|
+
icon-notification icon-notification-stroke
|
|
412
|
+
|
|
413
|
+
// User & Social
|
|
414
|
+
icon-user icon-user-stroke icon-counselor
|
|
415
|
+
icon-facebook icon-naver icon-insta
|
|
416
|
+
icon-tiktok icon-apple icon-google
|
|
417
|
+
icon-youtube icon-kakao icon-x
|
|
418
|
+
|
|
419
|
+
// Files & Documents
|
|
420
|
+
icon-file icon-paper icon-clip
|
|
421
|
+
icon-upload icon-download icon-upload-cloud
|
|
422
|
+
icon-import icon-export icon-excel
|
|
423
|
+
icon-img icon-print
|
|
424
|
+
|
|
425
|
+
// UI Elements
|
|
426
|
+
icon-star icon-star-fill icon-favorite
|
|
427
|
+
icon-favorite-fill icon-ellipse icon-ellipse-stroke
|
|
428
|
+
icon-tag icon-flag icon-flag-finish
|
|
429
|
+
icon-pin icon-link icon-link-alt
|
|
430
|
+
icon-new-window icon-calendar icon-time
|
|
431
|
+
icon-show icon-hidden icon-lock
|
|
432
|
+
icon-unlock icon-drag icon-handle
|
|
433
|
+
|
|
434
|
+
// Status & Feedback
|
|
435
|
+
icon-check-circle-stroke icon-check-circle-fill icon-info
|
|
436
|
+
icon-warning icon-danger icon-danger-fill
|
|
437
|
+
icon-help icon-fordid
|
|
438
|
+
|
|
439
|
+
// Business & Commerce
|
|
440
|
+
icon-card icon-briefcase icon-receipt
|
|
441
|
+
icon-coin icon-currency icon-car
|
|
442
|
+
icon-chart icon-chart-bar icon-pyramid-chart
|
|
443
|
+
|
|
444
|
+
// Tools & Settings
|
|
445
|
+
icon-setting icon-setting-stroke icon-zoom-in
|
|
446
|
+
icon-zoom-out icon-hand icon-global
|
|
447
|
+
|
|
448
|
+
// Technical/Specialized
|
|
449
|
+
icon-layers icon-ruler icon-contour
|
|
450
|
+
icon-temperature icon-turbine icon-pressure
|
|
451
|
+
icon-exchange-horizontally icon-exchange-vertical
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
**Usage Pattern:**
|
|
455
|
+
- Class name format: `icon-{name}`
|
|
456
|
+
- All icons are from a custom icon font
|
|
457
|
+
- Icons inherit font-size and color from parent element
|
|
458
|
+
- Use filled variants (e.g., `icon-star-fill`) for solid icons
|
|
459
|
+
- Use stroke variants (e.g., `icon-user-stroke`) for outline icons
|
|
460
|
+
|
|
461
|
+
**Styling Icons:**
|
|
462
|
+
|
|
463
|
+
```html
|
|
464
|
+
<!-- Size control via font-size -->
|
|
465
|
+
<i class="icon-star" style="font-size: 24px;"></i>
|
|
466
|
+
|
|
467
|
+
<!-- Color control via color -->
|
|
468
|
+
<i class="icon-heart-fill" style="color: red;"></i>
|
|
469
|
+
|
|
470
|
+
<!-- Using with SCSS -->
|
|
471
|
+
<style>
|
|
472
|
+
.my-icon {
|
|
473
|
+
font-size: s(6); /* 24px */
|
|
474
|
+
color: color(primary-base);
|
|
475
|
+
}
|
|
476
|
+
</style>
|
|
477
|
+
<i class="icon-check my-icon"></i>
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
---
|
|
481
|
+
|
|
482
|
+
## Theme System
|
|
483
|
+
|
|
484
|
+
### Dark Mode Toggle
|
|
485
|
+
|
|
486
|
+
```html
|
|
487
|
+
<!-- Light mode -->
|
|
488
|
+
<html data-color-mode="light">
|
|
489
|
+
|
|
490
|
+
<!-- Dark mode -->
|
|
491
|
+
<html data-color-mode="dark">
|
|
492
|
+
|
|
493
|
+
<!-- Auto (follows system preference) -->
|
|
494
|
+
<html data-color-mode="">
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
### Color Tone (Optional)
|
|
498
|
+
|
|
499
|
+
```html
|
|
500
|
+
<!-- Default tone -->
|
|
501
|
+
<html data-color-tone="">
|
|
502
|
+
|
|
503
|
+
<!-- Warm tone -->
|
|
504
|
+
<html data-color-tone="warm">
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
---
|
|
508
|
+
|
|
509
|
+
## Common Mistakes to Avoid
|
|
510
|
+
|
|
511
|
+
### ❌ Mistake 1: Hardcoded Values in SCSS
|
|
512
|
+
|
|
513
|
+
```scss
|
|
514
|
+
// BAD
|
|
515
|
+
.component {
|
|
516
|
+
padding: 16px;
|
|
517
|
+
background: #007bff;
|
|
518
|
+
border-radius: 8px;
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
// GOOD
|
|
522
|
+
@use 'podo-ui/mixin' as *;
|
|
523
|
+
|
|
524
|
+
.component {
|
|
525
|
+
padding: s(5);
|
|
526
|
+
background: color(primary-base);
|
|
527
|
+
border-radius: r(4);
|
|
528
|
+
}
|
|
529
|
+
```
|
|
530
|
+
|
|
531
|
+
### ❌ Mistake 2: Modifying Distributed Files
|
|
532
|
+
|
|
533
|
+
```bash
|
|
534
|
+
# BAD - Don't modify files in node_modules
|
|
535
|
+
Edit: node_modules/podo-ui/dist/react/atom/input.js
|
|
536
|
+
Edit: node_modules/podo-ui/scss/button/layout.scss
|
|
537
|
+
|
|
538
|
+
# GOOD - Override with your own styles
|
|
539
|
+
Create: src/styles/custom-button.module.scss
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
### ❌ Mistake 3: Incorrect Import Paths
|
|
543
|
+
|
|
544
|
+
```typescript
|
|
545
|
+
// BAD
|
|
546
|
+
import { Input } from 'podo-ui/dist/index';
|
|
547
|
+
import Input from 'podo-ui/react/atom/input.tsx';
|
|
548
|
+
|
|
549
|
+
// GOOD
|
|
550
|
+
import { Input } from 'podo-ui';
|
|
551
|
+
```
|
|
552
|
+
|
|
553
|
+
### ❌ Mistake 4: Missing SCSS Import
|
|
554
|
+
|
|
555
|
+
```tsx
|
|
556
|
+
// BAD - Using components without importing global styles
|
|
557
|
+
import { Input } from 'podo-ui';
|
|
558
|
+
|
|
559
|
+
function App() {
|
|
560
|
+
return <Input value="" onChange={() => {}} />;
|
|
561
|
+
}
|
|
562
|
+
|
|
563
|
+
// GOOD - Import global styles first
|
|
564
|
+
import 'podo-ui/global.scss';
|
|
565
|
+
import { Input } from 'podo-ui';
|
|
566
|
+
|
|
567
|
+
function App() {
|
|
568
|
+
return <Input value="" onChange={() => {}} />;
|
|
569
|
+
}
|
|
570
|
+
```
|
|
571
|
+
|
|
572
|
+
---
|
|
573
|
+
|
|
574
|
+
## Vite-Specific Configuration
|
|
575
|
+
|
|
576
|
+
When using **Vite** bundler, import the font path fix:
|
|
577
|
+
|
|
578
|
+
```typescript
|
|
579
|
+
// main.tsx (Vite projects only)
|
|
580
|
+
import 'podo-ui/global.scss';
|
|
581
|
+
import 'podo-ui/vite-fonts.scss'; // Required for Vite
|
|
582
|
+
```
|
|
583
|
+
|
|
584
|
+
**Why?** Vite has different font path resolution. This file corrects the paths for icon font and Pretendard font.
|
|
585
|
+
|
|
586
|
+
**Not needed for:** Next.js, Create React App, or other bundlers.
|
|
587
|
+
|
|
588
|
+
---
|
|
589
|
+
|
|
590
|
+
## TypeScript Support
|
|
591
|
+
|
|
592
|
+
All React components include TypeScript definitions:
|
|
593
|
+
|
|
594
|
+
```typescript
|
|
595
|
+
import { Input, Field, Editor } from 'podo-ui';
|
|
596
|
+
import type { InputProps, FieldProps, EditorProps } from 'podo-ui';
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
Type definitions are located at:
|
|
600
|
+
- `podo-ui/dist/index.d.ts`
|
|
601
|
+
- `podo-ui/dist/react/atom/*.d.ts`
|
|
602
|
+
- `podo-ui/dist/react/molecule/*.d.ts`
|
|
603
|
+
|
|
604
|
+
---
|
|
605
|
+
|
|
606
|
+
## Validation with Zod
|
|
607
|
+
|
|
608
|
+
All input components support Zod schema validation:
|
|
609
|
+
|
|
610
|
+
```typescript
|
|
611
|
+
import { Input } from 'podo-ui';
|
|
612
|
+
import { z } from 'zod';
|
|
613
|
+
|
|
614
|
+
const schema = z.string()
|
|
615
|
+
.min(2, 'Minimum 2 characters')
|
|
616
|
+
.max(50, 'Maximum 50 characters')
|
|
617
|
+
.email('Invalid email format');
|
|
618
|
+
|
|
619
|
+
<Input
|
|
620
|
+
value={email}
|
|
621
|
+
onChange={setEmail}
|
|
622
|
+
validator={schema}
|
|
623
|
+
/>
|
|
624
|
+
```
|
|
625
|
+
|
|
626
|
+
**Visual feedback:**
|
|
627
|
+
- ✅ Valid input: green border
|
|
628
|
+
- ❌ Invalid input: red border
|
|
629
|
+
- Error message displayed below input
|
|
630
|
+
|
|
631
|
+
---
|
|
632
|
+
|
|
633
|
+
## Framework Compatibility
|
|
634
|
+
|
|
635
|
+
### React / Next.js
|
|
636
|
+
|
|
637
|
+
```typescript
|
|
638
|
+
import 'podo-ui/global.scss';
|
|
639
|
+
import { Input, Editor, Field } from 'podo-ui';
|
|
640
|
+
```
|
|
641
|
+
|
|
642
|
+
### Vite + React
|
|
643
|
+
|
|
644
|
+
```typescript
|
|
645
|
+
import 'podo-ui/global.scss';
|
|
646
|
+
import 'podo-ui/vite-fonts.scss'; // Important!
|
|
647
|
+
import { Input, Editor, Field } from 'podo-ui';
|
|
648
|
+
```
|
|
649
|
+
|
|
650
|
+
### Vue / Angular / Vanilla JS
|
|
651
|
+
|
|
652
|
+
Use CSS classes only. React components are React-specific and won't work in other frameworks.
|
|
653
|
+
|
|
654
|
+
```html
|
|
655
|
+
<!-- Works in any framework -->
|
|
656
|
+
<button class="primary">Click me</button>
|
|
657
|
+
<input type="text" placeholder="Email" />
|
|
658
|
+
<div class="grid">
|
|
659
|
+
<div class="w-6">Column 1</div>
|
|
660
|
+
<div class="w-6">Column 2</div>
|
|
661
|
+
</div>
|
|
662
|
+
```
|
|
663
|
+
|
|
664
|
+
---
|
|
665
|
+
|
|
666
|
+
## Performance Considerations
|
|
667
|
+
|
|
668
|
+
### Tree Shaking
|
|
669
|
+
|
|
670
|
+
Named imports support tree shaking:
|
|
671
|
+
|
|
672
|
+
```typescript
|
|
673
|
+
// Only Input code is included in bundle
|
|
674
|
+
import { Input } from 'podo-ui';
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
### CSS Size
|
|
678
|
+
|
|
679
|
+
Global CSS is ~50KB minified. Consider:
|
|
680
|
+
- Importing only needed SCSS modules if building custom bundle
|
|
681
|
+
- Using PurgeCSS to remove unused classes in production
|
|
682
|
+
|
|
683
|
+
---
|
|
684
|
+
|
|
685
|
+
## Debugging Checklist
|
|
686
|
+
|
|
687
|
+
### Styles not appearing?
|
|
688
|
+
|
|
689
|
+
```
|
|
690
|
+
□ Did you import 'podo-ui/global.scss'?
|
|
691
|
+
□ For Vite: Did you import 'podo-ui/vite-fonts.scss'?
|
|
692
|
+
□ Are you using correct class names?
|
|
693
|
+
□ Check browser console for CSS loading errors
|
|
694
|
+
```
|
|
695
|
+
|
|
696
|
+
### React components not working?
|
|
697
|
+
|
|
698
|
+
```
|
|
699
|
+
□ Is React version ≥18?
|
|
700
|
+
□ Did you import from 'podo-ui' correctly?
|
|
701
|
+
□ For Editor: Is it a client component (Next.js)?
|
|
702
|
+
□ Check browser console for JavaScript errors
|
|
703
|
+
```
|
|
704
|
+
|
|
705
|
+
### TypeScript errors?
|
|
706
|
+
|
|
707
|
+
```
|
|
708
|
+
□ Are type definitions installed (should be automatic)?
|
|
709
|
+
□ Try restarting TypeScript server
|
|
710
|
+
□ Check that you're importing from correct paths
|
|
711
|
+
```
|
|
712
|
+
|
|
713
|
+
---
|
|
714
|
+
|
|
715
|
+
## Quick Reference
|
|
716
|
+
|
|
717
|
+
### Essential Imports
|
|
718
|
+
|
|
719
|
+
```typescript
|
|
720
|
+
// Global styles (required)
|
|
721
|
+
import 'podo-ui/global.scss';
|
|
722
|
+
|
|
723
|
+
// Vite users only
|
|
724
|
+
import 'podo-ui/vite-fonts.scss';
|
|
725
|
+
|
|
726
|
+
// React components
|
|
727
|
+
import { Input, Textarea, Editor, EditorView, Field, Pagination } from 'podo-ui';
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
### Essential Design Tokens
|
|
731
|
+
|
|
732
|
+
```scss
|
|
733
|
+
@use 'podo-ui/mixin' as *;
|
|
734
|
+
|
|
735
|
+
.component {
|
|
736
|
+
padding: s(5); // Spacing
|
|
737
|
+
color: color(primary-base); // Color
|
|
738
|
+
border-radius: r(4); // Radius
|
|
739
|
+
@include p1; // Typography
|
|
740
|
+
}
|
|
741
|
+
```
|
|
742
|
+
|
|
743
|
+
### Essential CSS Classes
|
|
744
|
+
|
|
745
|
+
```html
|
|
746
|
+
<button class="primary">Button</button>
|
|
747
|
+
<div class="grid">
|
|
748
|
+
<div class="w-6">50%</div>
|
|
749
|
+
<div class="w-6">50%</div>
|
|
750
|
+
</div>
|
|
751
|
+
<div class="p-5 m-t-4">Padding 16px, margin-top 12px</div>
|
|
752
|
+
```
|
|
753
|
+
|
|
754
|
+
---
|
|
755
|
+
|
|
756
|
+
## Support
|
|
757
|
+
|
|
758
|
+
- **Documentation**: https://podoui.com
|
|
759
|
+
- **GitHub**: https://github.com/hada0127/podo-ui
|
|
760
|
+
- **Issues**: https://github.com/hada0127/podo-ui/issues
|
|
761
|
+
|
|
762
|
+
---
|
|
763
|
+
|
|
764
|
+
## Summary
|
|
765
|
+
|
|
766
|
+
**For AI Assistants:**
|
|
767
|
+
1. **Always** use design tokens (s, color, r) in SCSS, never hardcoded values
|
|
768
|
+
2. **Always** import 'podo-ui/global.scss' before using any components or classes
|
|
769
|
+
3. **Vite users** must also import 'podo-ui/vite-fonts.scss'
|
|
770
|
+
4. **Import components** using named imports from 'podo-ui'
|
|
771
|
+
5. **Never modify** files in node_modules/podo-ui
|
|
772
|
+
6. **Use CSS classes** for framework-agnostic styling
|
|
773
|
+
7. **Use React components** only when validation or complex interaction is needed
|
|
774
|
+
|
|
775
|
+
This library prioritizes CSS-first design with minimal JavaScript, ensuring maximum compatibility and performance.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "podo-ui",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.5",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"author": "hada0127 <work@tarucy.net>",
|
|
6
6
|
"license": "MIT",
|
|
@@ -21,7 +21,8 @@
|
|
|
21
21
|
"global.d.ts",
|
|
22
22
|
"mixin.scss",
|
|
23
23
|
"vite-fonts.scss",
|
|
24
|
-
"README.md"
|
|
24
|
+
"README.md",
|
|
25
|
+
"AI-GUIDE.md"
|
|
25
26
|
],
|
|
26
27
|
"exports": {
|
|
27
28
|
".": {
|