@marianmeres/stuic 3.51.0 → 3.51.1
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 +39 -0
- package/README.md +25 -4
- package/docs/conventions.md +57 -0
- package/docs/domains/theming.md +45 -4
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -45,6 +45,7 @@ src/lib/
|
|
|
45
45
|
5. Create components without `unstyled`, `class`, `el` props
|
|
46
46
|
6. Use `dark:` Tailwind prefix when CSS vars handle dark mode
|
|
47
47
|
7. Import CSS inside components — centralize in `src/lib/index.css`
|
|
48
|
+
8. Declare component tokens at `:root` that reference shared structural tokens (use fallback pattern instead)
|
|
48
49
|
|
|
49
50
|
### CSS Variable Pattern
|
|
50
51
|
|
|
@@ -52,6 +53,44 @@ src/lib/
|
|
|
52
53
|
--stuic-{component}-{element?}-{property}-{state?}
|
|
53
54
|
```
|
|
54
55
|
|
|
56
|
+
### Shared Structural Tokens
|
|
57
|
+
|
|
58
|
+
Global tokens that control cross-component visual properties. Defined in `src/lib/index.css`:
|
|
59
|
+
|
|
60
|
+
| Token | Default | Purpose |
|
|
61
|
+
| -------------------------- | -------------------- | --------------------------------------------- |
|
|
62
|
+
| `--stuic-radius` | `var(--radius-md)` | Element-level radius (buttons, inputs, badges) |
|
|
63
|
+
| `--stuic-radius-container` | `var(--radius-lg)` | Container-level radius (cards, modals, dropdowns) |
|
|
64
|
+
| `--stuic-shadow` | `var(--shadow-sm)` | Default resting shadow |
|
|
65
|
+
| `--stuic-shadow-hover` | `var(--shadow-md)` | Hover/elevated shadow |
|
|
66
|
+
| `--stuic-shadow-overlay` | `var(--shadow-lg)` | Overlays (dropdowns, notifications) |
|
|
67
|
+
| `--stuic-shadow-dialog` | `var(--shadow-xl)` | Dialogs/modals |
|
|
68
|
+
| `--stuic-border-width` | `1px` | Default border width |
|
|
69
|
+
| `--stuic-transition` | `150ms` | Default transition duration |
|
|
70
|
+
|
|
71
|
+
**When creating new components**, use the fallback pattern at CSS usage sites:
|
|
72
|
+
|
|
73
|
+
```css
|
|
74
|
+
/* CORRECT: fallback resolved at element level — scoped overrides work */
|
|
75
|
+
.stuic-my-component {
|
|
76
|
+
border-radius: var(--stuic-my-component-radius, var(--stuic-radius));
|
|
77
|
+
box-shadow: var(--stuic-my-component-shadow, var(--stuic-shadow));
|
|
78
|
+
border-width: var(--stuic-my-component-border-width, var(--stuic-border-width));
|
|
79
|
+
transition: background var(--stuic-my-component-transition, var(--stuic-transition));
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
```css
|
|
84
|
+
/* WRONG: :root declarations resolve eagerly — scoped overrides on child elements are ignored */
|
|
85
|
+
:root {
|
|
86
|
+
--stuic-my-component-radius: var(--stuic-radius); /* DO NOT DO THIS */
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**Element vs Container classification:**
|
|
91
|
+
- **Element** (`--stuic-radius`): buttons, inputs, badges, list items, checkboxes, tabs — interactive controls
|
|
92
|
+
- **Container** (`--stuic-radius-container`): cards, modals, dropdowns, notifications, accordions — content wrappers
|
|
93
|
+
|
|
55
94
|
---
|
|
56
95
|
|
|
57
96
|
## Before Making Changes
|
package/README.md
CHANGED
|
@@ -29,14 +29,16 @@ npm install @marianmeres/stuic
|
|
|
29
29
|
|
|
30
30
|
## Theming System
|
|
31
31
|
|
|
32
|
-
STUIC uses a
|
|
32
|
+
STUIC uses a 4-layer CSS variable token system:
|
|
33
33
|
|
|
34
34
|
```
|
|
35
35
|
Layer 1: Theme Tokens (--stuic-color-*)
|
|
36
|
+
↓
|
|
37
|
+
Layer 2: Structural Tokens (--stuic-radius, --stuic-shadow, --stuic-border-width, --stuic-transition)
|
|
36
38
|
↓ (used as fallback defaults)
|
|
37
|
-
Layer
|
|
39
|
+
Layer 3: Component Tokens (--stuic-button-radius, --stuic-input-accent, etc.)
|
|
38
40
|
↓ (Tailwind utility class references)
|
|
39
|
-
Layer
|
|
41
|
+
Layer 4: Instance Overrides (inline styles, class props)
|
|
40
42
|
```
|
|
41
43
|
|
|
42
44
|
### Global Theming
|
|
@@ -54,13 +56,32 @@ Override theme tokens in your app's CSS:
|
|
|
54
56
|
}
|
|
55
57
|
```
|
|
56
58
|
|
|
59
|
+
### Structural Tokens
|
|
60
|
+
|
|
61
|
+
Override shared structural tokens to change the entire library's visual character:
|
|
62
|
+
|
|
63
|
+
```css
|
|
64
|
+
/* Brutalist — sharp, flat, borderless */
|
|
65
|
+
:root {
|
|
66
|
+
--stuic-radius: 0;
|
|
67
|
+
--stuic-radius-container: 0;
|
|
68
|
+
--stuic-shadow: none;
|
|
69
|
+
--stuic-shadow-hover: none;
|
|
70
|
+
--stuic-shadow-overlay: none;
|
|
71
|
+
--stuic-shadow-dialog: none;
|
|
72
|
+
--stuic-border-width: 0;
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Available tokens: `--stuic-radius`, `--stuic-radius-container`, `--stuic-shadow`, `--stuic-shadow-hover`, `--stuic-shadow-overlay`, `--stuic-shadow-dialog`, `--stuic-border-width`, `--stuic-transition`.
|
|
77
|
+
|
|
57
78
|
### Per-Component Customization
|
|
58
79
|
|
|
59
80
|
Override specific component tokens:
|
|
60
81
|
|
|
61
82
|
```css
|
|
62
83
|
:root {
|
|
63
|
-
--stuic-button-radius: 9999px; /* Pill buttons */
|
|
84
|
+
--stuic-button-radius: 9999px; /* Pill buttons — overrides the shared --stuic-radius */
|
|
64
85
|
--stuic-switch-accent: #10b981; /* Green switches */
|
|
65
86
|
}
|
|
66
87
|
```
|
package/docs/conventions.md
CHANGED
|
@@ -35,6 +35,63 @@ Code standards and patterns for STUIC development.
|
|
|
35
35
|
|
|
36
36
|
---
|
|
37
37
|
|
|
38
|
+
## Shared Structural Tokens
|
|
39
|
+
|
|
40
|
+
Global tokens in `src/lib/index.css` that control cross-component visual properties (radius, shadow, border-width, transition). Override them to change the entire library's look:
|
|
41
|
+
|
|
42
|
+
```css
|
|
43
|
+
/* Brutalist example — 7 lines to transform everything */
|
|
44
|
+
:root {
|
|
45
|
+
--stuic-radius: 0;
|
|
46
|
+
--stuic-radius-container: 0;
|
|
47
|
+
--stuic-shadow: none;
|
|
48
|
+
--stuic-shadow-hover: none;
|
|
49
|
+
--stuic-shadow-overlay: none;
|
|
50
|
+
--stuic-shadow-dialog: none;
|
|
51
|
+
--stuic-border-width: 0;
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Fallback Pattern (for new components)
|
|
56
|
+
|
|
57
|
+
Component CSS must reference shared tokens as **fallbacks at usage sites**, not as `:root` declarations:
|
|
58
|
+
|
|
59
|
+
```css
|
|
60
|
+
/* CORRECT — fallback resolved at element level, scoped overrides work */
|
|
61
|
+
.stuic-widget {
|
|
62
|
+
border-radius: var(--stuic-widget-radius, var(--stuic-radius));
|
|
63
|
+
box-shadow: var(--stuic-widget-shadow, var(--stuic-shadow));
|
|
64
|
+
border-width: var(--stuic-widget-border-width, var(--stuic-border-width));
|
|
65
|
+
transition: background var(--stuic-widget-transition, var(--stuic-transition));
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
```css
|
|
70
|
+
/* WRONG — CSS vars resolve eagerly at :root, so overriding --stuic-radius on a
|
|
71
|
+
descendant element has no effect on --stuic-widget-radius */
|
|
72
|
+
:root {
|
|
73
|
+
--stuic-widget-radius: var(--stuic-radius);
|
|
74
|
+
}
|
|
75
|
+
.stuic-widget {
|
|
76
|
+
border-radius: var(--stuic-widget-radius);
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Per-component overrides (`--stuic-widget-radius: 0`) still take precedence over the shared fallback.
|
|
81
|
+
|
|
82
|
+
### Element vs Container
|
|
83
|
+
|
|
84
|
+
Two tiers of radius for natural visual hierarchy:
|
|
85
|
+
|
|
86
|
+
| Tier | Token | Default | Use for |
|
|
87
|
+
| ---- | ----- | ------- | ------- |
|
|
88
|
+
| Element | `--stuic-radius` | `var(--radius-md)` | Buttons, inputs, badges, list items, checkboxes, tabs |
|
|
89
|
+
| Container | `--stuic-radius-container` | `var(--radius-lg)` | Cards, modals, dropdowns, notifications, accordions |
|
|
90
|
+
|
|
91
|
+
**Rule of thumb:** if it wraps other interactive elements, it's a container.
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
38
95
|
## Svelte 5 Patterns
|
|
39
96
|
|
|
40
97
|
### Props Declaration
|
package/docs/domains/theming.md
CHANGED
|
@@ -182,23 +182,64 @@ const css = generateThemeCss(custom, "stuic-");
|
|
|
182
182
|
|
|
183
183
|
---
|
|
184
184
|
|
|
185
|
+
## Shared Structural Tokens
|
|
186
|
+
|
|
187
|
+
Global tokens defined in `src/lib/index.css` that control cross-component visual properties. Override these to change the entire library's visual character:
|
|
188
|
+
|
|
189
|
+
| Token | Default | Purpose |
|
|
190
|
+
| -------------------------- | -------------------- | ------------------------------------------------ |
|
|
191
|
+
| `--stuic-radius` | `var(--radius-md)` | Element-level radius (buttons, inputs, badges) |
|
|
192
|
+
| `--stuic-radius-container` | `var(--radius-lg)` | Container-level radius (cards, modals, dropdowns) |
|
|
193
|
+
| `--stuic-shadow` | `var(--shadow-sm)` | Default resting shadow |
|
|
194
|
+
| `--stuic-shadow-hover` | `var(--shadow-md)` | Hover/elevated shadow |
|
|
195
|
+
| `--stuic-shadow-overlay` | `var(--shadow-lg)` | Overlays (dropdowns, notifications) |
|
|
196
|
+
| `--stuic-shadow-dialog` | `var(--shadow-xl)` | Dialogs/modals |
|
|
197
|
+
| `--stuic-border-width` | `1px` | Default border width |
|
|
198
|
+
| `--stuic-transition` | `150ms` | Default transition duration |
|
|
199
|
+
|
|
200
|
+
Example — brutalist style in 7 lines:
|
|
201
|
+
|
|
202
|
+
```css
|
|
203
|
+
:root {
|
|
204
|
+
--stuic-radius: 0;
|
|
205
|
+
--stuic-radius-container: 0;
|
|
206
|
+
--stuic-shadow: none;
|
|
207
|
+
--stuic-shadow-hover: none;
|
|
208
|
+
--stuic-shadow-overlay: none;
|
|
209
|
+
--stuic-shadow-dialog: none;
|
|
210
|
+
--stuic-border-width: 0;
|
|
211
|
+
}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Components reference these via the fallback pattern (not `:root` declarations):
|
|
215
|
+
|
|
216
|
+
```css
|
|
217
|
+
.stuic-button {
|
|
218
|
+
border-radius: var(--stuic-button-radius, var(--stuic-radius));
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
185
224
|
## Component Tokens
|
|
186
225
|
|
|
187
|
-
Components define their own tokens
|
|
226
|
+
Components define their own customization tokens in `:root` (for non-structural properties like colors, padding, typography):
|
|
188
227
|
|
|
189
228
|
```css
|
|
190
229
|
:root {
|
|
191
|
-
--stuic-button-radius: var(--radius-md);
|
|
192
230
|
--stuic-button-ring-color: var(--stuic-color-ring);
|
|
193
231
|
--stuic-button-padding-x-md: 1rem;
|
|
232
|
+
--stuic-button-font-weight: var(--font-weight-medium);
|
|
194
233
|
}
|
|
195
234
|
```
|
|
196
235
|
|
|
197
|
-
|
|
236
|
+
For structural properties (radius, shadow, border-width, transition), components use the **fallback pattern** at usage sites instead of `:root` declarations — see [Conventions: Shared Structural Tokens](../conventions.md#shared-structural-tokens).
|
|
237
|
+
|
|
238
|
+
Override per-component tokens globally:
|
|
198
239
|
|
|
199
240
|
```css
|
|
200
241
|
:root {
|
|
201
|
-
--stuic-button-radius: 9999px; /* Pill buttons */
|
|
242
|
+
--stuic-button-radius: 9999px; /* Pill buttons — overrides the shared fallback */
|
|
202
243
|
}
|
|
203
244
|
```
|
|
204
245
|
|