@marianmeres/stuic 3.4.3 → 3.5.0
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/AGENTS.md +96 -0
- package/API.md +1010 -0
- package/CLAUDE.md +3 -0
- package/README.md +72 -189
- package/dist/components/Input/FieldLikeButton.svelte +9 -7
- package/dist/components/Input/FieldOptions.svelte +3 -3
- package/dist/components/Input/_internal/InputWrap.svelte +3 -14
- package/dist/components/ModalDialog/ModalDialog.svelte +5 -2
- package/dist/utils/design-tokens.d.ts +10 -4
- package/dist/utils/design-tokens.js +10 -0
- package/docs/DESIGN_TOKENS_MANUAL.md +121 -0
- package/docs/TAILWIND_V4_CSS_VARIABLES.md +313 -0
- package/docs/architecture.md +178 -0
- package/docs/conventions.md +234 -0
- package/docs/domains/actions.md +124 -0
- package/docs/domains/components.md +206 -0
- package/docs/domains/theming.md +215 -0
- package/docs/domains/utils.md +159 -0
- package/docs/tasks.md +271 -0
- package/package.json +12 -3
package/AGENTS.md
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# STUIC - Agent Guide
|
|
2
|
+
|
|
3
|
+
> Svelte 5 + Tailwind CSS v4 component library with centralized design tokens.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Quick Reference
|
|
8
|
+
|
|
9
|
+
| | Command |
|
|
10
|
+
|---|---------|
|
|
11
|
+
| **Dev** | `npm run dev` |
|
|
12
|
+
| **Build** | `npm run build` |
|
|
13
|
+
| **Test** | `npm run test` |
|
|
14
|
+
| **Check** | `npm run check` |
|
|
15
|
+
| **Lint** | `npm run lint` |
|
|
16
|
+
| **Format** | `npm run format` |
|
|
17
|
+
|
|
18
|
+
**Stack:** Svelte 5 (runes) · Tailwind CSS v4 · SvelteKit (library mode) · Vite
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Project Structure
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
src/lib/
|
|
26
|
+
├── components/ # 35 UI components
|
|
27
|
+
├── actions/ # 12 Svelte actions
|
|
28
|
+
├── utils/ # 42 utility functions
|
|
29
|
+
├── themes/ # 26 theme definitions (.ts) + generated CSS (css/)
|
|
30
|
+
├── icons/ # Icon re-exports
|
|
31
|
+
├── index.css # Centralized CSS imports
|
|
32
|
+
└── index.ts # Main exports
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## Critical Conventions
|
|
38
|
+
|
|
39
|
+
### DO NOT
|
|
40
|
+
|
|
41
|
+
1. Use abbreviated CSS var names (`--stuic-lib-bg` wrong → `--stuic-list-item-button-bg`)
|
|
42
|
+
2. Use `-dark` suffix (use `:root.dark {}` selector instead)
|
|
43
|
+
3. Put state before property (`--stuic-button-hover-bg` wrong → `--stuic-button-bg-hover`)
|
|
44
|
+
4. Use Svelte 4 syntax (`export let`, `$:`) — use runes (`$props()`, `$derived()`)
|
|
45
|
+
5. Create components without `unstyled`, `class`, `el` props
|
|
46
|
+
6. Use `dark:` Tailwind prefix when CSS vars handle dark mode
|
|
47
|
+
7. Import CSS inside components — centralize in `src/lib/index.css`
|
|
48
|
+
|
|
49
|
+
### CSS Variable Pattern
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
--stuic-{component}-{element?}-{property}-{state?}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Before Making Changes
|
|
58
|
+
|
|
59
|
+
- [ ] Check existing patterns in similar components
|
|
60
|
+
- [ ] Follow centralized CSS import pattern
|
|
61
|
+
- [ ] Run `npm run build` to verify
|
|
62
|
+
- [ ] Test both light and dark modes
|
|
63
|
+
- [ ] Verify `--stuic-color-primary` changes cascade
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Documentation Index
|
|
68
|
+
|
|
69
|
+
### Core Docs
|
|
70
|
+
- [Architecture](./docs/architecture.md) — System design, data flow
|
|
71
|
+
- [Conventions](./docs/conventions.md) — Code standards, patterns
|
|
72
|
+
- [Tasks](./docs/tasks.md) — Common procedures
|
|
73
|
+
|
|
74
|
+
### Domain Docs
|
|
75
|
+
- [Components](./docs/domains/components.md) — 35 components, Props pattern, snippets
|
|
76
|
+
- [Theming](./docs/domains/theming.md) — CSS tokens, dark mode, themes
|
|
77
|
+
- [Actions](./docs/domains/actions.md) — 12 Svelte directives
|
|
78
|
+
- [Utils](./docs/domains/utils.md) — 42 utility functions
|
|
79
|
+
|
|
80
|
+
### Reference
|
|
81
|
+
- [Design Tokens Manual](./docs/DESIGN_TOKENS_MANUAL.md) — Token philosophy
|
|
82
|
+
- [Tailwind v4 Variables](./docs/TAILWIND_V4_CSS_VARIABLES.md) — CSS variable reference
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Key Files
|
|
87
|
+
|
|
88
|
+
| File | Purpose |
|
|
89
|
+
|------|---------|
|
|
90
|
+
| `src/lib/index.css` | CSS entry point |
|
|
91
|
+
| `src/lib/index.ts` | JS entry point |
|
|
92
|
+
| `src/lib/utils/design-tokens.ts` | Theme types + CSS generation (`ThemeSchema`, `generateThemeCss`, etc.) |
|
|
93
|
+
| `src/lib/themes/*.ts` | Theme definitions (26 themes, `TokenSchema`-typed) |
|
|
94
|
+
| `src/lib/themes/css/stone.css` | Default theme (generated) |
|
|
95
|
+
| `src/lib/components/Button/` | Reference component |
|
|
96
|
+
| `scripts/generate-theme.ts` | CLI: `pnpm run build:theme:all` |
|