silva-ui 1.3.0 → 2.0.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.
Files changed (59) hide show
  1. package/README.md +133 -30
  2. package/dist/library/silva-ui.css +1 -1
  3. package/dist/library/silva-ui.js +993 -23305
  4. package/dist/types/core/Theme.d.ts +28 -6
  5. package/dist/types/core/colors/index.d.ts +16 -8
  6. package/dist/types/core/compound.d.ts +6 -0
  7. package/dist/types/core/dynamic-colors.css.d.ts +6 -0
  8. package/dist/types/core/gradient.d.ts +1 -1
  9. package/dist/types/core/sprinkles.css.d.ts +17 -407
  10. package/dist/types/core/theme/index.css.d.ts +4 -398
  11. package/dist/types/core/theme.css.d.ts +3 -3
  12. package/dist/types/core/themes/index.d.ts +228 -6
  13. package/dist/types/core/types.d.ts +11 -6
  14. package/dist/types/core/utils.d.ts +2 -1
  15. package/dist/types/core/visuals.css.d.ts +2 -2
  16. package/dist/types/display/Avatar.d.ts +1 -1
  17. package/dist/types/display/Card.d.ts +1 -1
  18. package/dist/types/display/Image.d.ts +2 -2
  19. package/dist/types/display/ListItem.d.ts +1 -1
  20. package/dist/types/display/Loader.d.ts +1 -1
  21. package/dist/types/display/Spinner.d.ts +1 -1
  22. package/dist/types/forms/Button.d.ts +1 -1
  23. package/dist/types/forms/Checkbox.d.ts +1 -1
  24. package/dist/types/forms/Field.d.ts +1 -1
  25. package/dist/types/forms/Form.d.ts +1 -1
  26. package/dist/types/forms/Input.d.ts +1 -1
  27. package/dist/types/forms/Label.d.ts +1 -1
  28. package/dist/types/forms/Progress.d.ts +1 -1
  29. package/dist/types/forms/RadioGroup.d.ts +1 -1
  30. package/dist/types/forms/Select.d.ts +9 -2
  31. package/dist/types/forms/Slider.d.ts +1 -1
  32. package/dist/types/forms/Switch.d.ts +1 -1
  33. package/dist/types/forms/TextArea.d.ts +1 -1
  34. package/dist/types/forms/ToggleGroup.d.ts +1 -1
  35. package/dist/types/index.d.ts +99 -99
  36. package/dist/types/layout/Box.d.ts +2 -2
  37. package/dist/types/layout/Separator.d.ts +1 -1
  38. package/dist/types/layout/XGroup.d.ts +1 -1
  39. package/dist/types/layout/XStack.d.ts +1 -1
  40. package/dist/types/layout/YStack.d.ts +1 -1
  41. package/dist/types/overlays/Accordion.d.ts +1 -1
  42. package/dist/types/overlays/AlertDialog.d.ts +3 -2
  43. package/dist/types/overlays/ContextMenu.d.ts +1 -1
  44. package/dist/types/overlays/Dialog.d.ts +3 -2
  45. package/dist/types/overlays/Menu.d.ts +1 -1
  46. package/dist/types/overlays/Popover.d.ts +1 -1
  47. package/dist/types/overlays/Sheet.d.ts +3 -2
  48. package/dist/types/overlays/Tabs.d.ts +1 -1
  49. package/dist/types/overlays/Toast.d.ts +1 -1
  50. package/dist/types/overlays/Tooltip.d.ts +1 -1
  51. package/dist/types/typography/Anchor.d.ts +1 -1
  52. package/dist/types/typography/Heading.d.ts +1 -1
  53. package/dist/types/typography/Headings.d.ts +1 -1
  54. package/dist/types/typography/Paragraph.d.ts +1 -1
  55. package/dist/types/typography/SizableText.d.ts +2 -2
  56. package/dist/types/typography/Text.d.ts +1 -1
  57. package/package.json +81 -69
  58. package/dist/library/previews/index.html +0 -51
  59. package/dist/types/core/colors/radix.d.ts +0 -1396
package/README.md CHANGED
@@ -18,6 +18,12 @@
18
18
 
19
19
  A Hono JSX UI component library with framework-neutral styling and Tamagui-inspired theming, built on `@vanilla-extract/css` and `@vanilla-extract/sprinkles`.
20
20
 
21
+ Read the [Silva UI documentation](https://blacksilva.com/silva-ui) for installation, theming, foundations, components, and API guidance.
22
+
23
+ Try the [palette playground](https://black-silva.github.io/silva-ui-palette-playground/) to explore named colours, shades, themes, and gradients. It is a deployed snapshot of this palette branch; see the [playground README](./examples/palette-playground/README.md) to run it locally.
24
+
25
+ AI tools can use the [full Silva UI reference](https://blacksilva.com/silva-ui/llms-full.txt) for the complete published documentation in one file.
26
+
21
27
  Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for
22
28
  development setup, validation commands, and pull request expectations.
23
29
 
@@ -134,11 +140,17 @@ export function SignupCard() {
134
140
  The published package includes prebuilt CSS. Import `silva-ui/style.css` once
135
141
  from your application entry point.
136
142
 
143
+ Choose one sizing approach consistently wherever the relevant props support it.
144
+ Mixing named fixed tokens, numeric size tokens, and viewport-projected `$n`
145
+ tokens in a layout can cause breakages across browsers and screen sizes. For
146
+ apps designed to scale with screen width, prefer `$n` on supported props and
147
+ test across target screens. Component `size` variants are separate fixed recipes.
148
+ See the [sizing guide](https://blacksilva.com/silva-ui/docs/foundations/sprinkles#choose-a-sizing-approach).
149
+
137
150
  ## Colors and themes
138
151
 
139
152
  Theme styling is generated at build time with Vanilla Extract. `Theme` scopes the
140
- selected theme to a subtree, so nested themes override their parent without
141
- runtime style injection:
153
+ selected theme to a subtree, so nested themes override their parent:
142
154
 
143
155
  ```tsx
144
156
  import { Box, Text, Theme } from 'silva-ui';
@@ -155,32 +167,64 @@ import { Box, Text, Theme } from 'silva-ui';
155
167
  </Theme>;
156
168
  ```
157
169
 
158
- Color ramps are exported as `colorScales` and are also registered as sprinkles
159
- color tokens. They follow the Tamagui/Radix convention: the same numbered token
160
- has a light-palette value in light themes and a dark-palette value in dark
161
- themes. The referenced `colors` source provides 28 hue ramps plus `blackA` and
162
- `whiteA`, each with 12 numbered stops.
170
+ The palette provides typed scales for 148 CSS named colours, each with stops
171
+ `1`–`10`. A stop mixes the literal named colour with the theme base in linear
172
+ sRGB: `blue6` uses 60% blue, while `blue10` uses 100% blue. Built-in light
173
+ scopes use a white base and dark scopes use black; these colours do not preserve
174
+ the old Radix ramps. `colorScales` and `darkColorScales` lazily provide
175
+ ten-element arrays (index 0 is stop 1); `colorTokens` and `darkColorTokens`
176
+ lazily provide mix strings, with `blue` as an alias for `blue1`. These
177
+ accessors are not enumerable catalogues: spreading them or using `Object.keys`
178
+ does not yield the palette. No runtime named-colour catalogue is exported.
179
+
180
+ Named colours are resolved on demand by component `color`, `backgroundColor`,
181
+ `bg`, and `borderColor` props, including their state conditions. Direct
182
+ `sprinkles()` accepts semantic colour tokens, not named palette tokens;
183
+ `themeColors` and `tokens.colors` now contain semantic keys only. For a CSS
184
+ value outside component props, use `namedColorTokenToCss('blue6')` or
185
+ `colorTokens.blue6` instead of `themeColors.blue6`.
186
+
187
+ Use tokens such as `bg="blue6"` or `borderColor="teal4"` when a hue is
188
+ intentional. Semantic names such as `background`, `card`, `primary`, `muted`,
189
+ and `border` remain theme-aware and are preferred when the UI role is clearer.
190
+ `<Theme name="light" accentColor="rebeccapurple">` changes semantic accent
191
+ values such as `primary` and `ring`, but `blue6` still uses blue, not the accent.
192
+ `accentColor` accepts CSS named colours and selects a black or white contrast
193
+ input. Built-in semantic values use these inputs; fixed values in a custom
194
+ semantic class do not. Check text, focus and component contrast in every theme
195
+ rather than assuming a stop is accessible.
196
+
197
+ **Breaking migration:** numbered stops `11` and `12` and the predefined Radix
198
+ ramps are removed; the named-token resolver throws for invalid numbered shades.
199
+ `createThemes` and `applyThemeTemplate` now throw for zero, non-integer or
200
+ out-of-range palette indices instead of clamping them. Choose semantic tokens
201
+ for text and surfaces, or deliberately select and contrast-test a new stop or
202
+ explicit colour for each use. Old Radix-only names and alpha ramps
203
+ such as `grass` and `blackA4` have no automatic equivalent; audit and replace
204
+ them explicitly, using a custom theme or explicit colour where required. See
205
+ the [migration guide](docs/theming.mdx#palette-migration) for details and
206
+ browser compatibility.
207
+
208
+ Built-in base themes are `light`, `dark`, `emerald`, `emerald-dark`, and
209
+ `midnight`; each also has `surface1` and `surface2` variants such as
210
+ `dark_surface1`. The exported `ThemeName` type accepts these names, CSS named
211
+ colours, and `light-${CSSNamedColor}` / `dark-${CSSNamedColor}`; it does not
212
+ accept shade tokens such as `red5`, arbitrary strings, or generated class names.
213
+ This is a TypeScript breaking change: replace `name={darkTheme}` with
214
+ `name="dark"`, and apply other classes explicitly with `class` or use a custom
215
+ scope below. For JavaScript compatibility, legacy `name={classString}` values
216
+ whose string starts with `theme_` remain supported at runtime; this exception
217
+ does not make arbitrary class strings valid `ThemeName` values in TypeScript.
163
218
 
164
- For example, `color="blue12"` is dark on light themes and light on dark themes;
165
- `bg="blue6"` adapts with the rest of the ramp. Use tokens such as `bg="blue6"`,
166
- `color="gray11"`, `borderColor="teal4"`, or alpha tokens such as
167
- `backgroundColor="blackA4"`. Semantic names such as `background`, `card`,
168
- `primary`, `muted`, and `border` also adapt to the active theme and are
169
- preferred when a semantic role is clearer than a specific hue.
170
-
171
- Built-in themes are `light`, `dark`, `emerald`, `emerald-dark`, and `midnight`.
172
219
  Their semantic values are defined in `src/core/themes`; the token contract and
173
- CSS variables are in `src/core/theme`; `src/core/theme-builder` combines theme
174
- definitions with the palette tokens. To add a theme, add a complete semantic
175
- color map to `themeDefinitions` in `src/core/themes` and register dark variants
176
- in `darkThemeNames` there so their ramps reverse. The theme class and
177
- `data-theme` selector are generated from those maps. Add a switcher control in
178
- `example/App.tsx` if you want it available in the demo. Theme classes and CSS
179
- variables are emitted at build time.
220
+ CSS variables are in `src/core/theme`. Theme classes and `data-theme` selectors
221
+ are emitted at build time; switching `Theme` in the browser changes the active
222
+ scope. For application-specific semantic colours, see the
223
+ [custom theme guide](docs/theming.mdx#custom-themes-with-createtheme).
180
224
 
181
225
  `Theme` can be nested to switch a subtree back to any built-in theme. For inline styles, use the exported contract values such as
182
- `themeColors.background` or `themeColors.blue6`; Vanilla Extract can then keep
183
- the variable names consistent through production builds.
226
+ `themeColors.background`; Vanilla Extract can then keep semantic variable names
227
+ consistent through production builds.
184
228
 
185
229
  Silva UI follows Tamagui's palette/template model. The exported `createThemes` helper composes named palettes and
186
230
  templates into theme records, and built-in themes include generated surface
@@ -198,7 +242,7 @@ import { Card, Theme } from 'silva-ui';
198
242
  ```
199
243
 
200
244
  Palette themes can also be selected without registering or prebuilding a
201
- custom theme. Pass a supported color scale directly to `Theme`, or prefix it
245
+ custom theme. Pass an unnumbered CSS named colour to `Theme`, or prefix it
202
246
  with `light-` or `dark-`:
203
247
 
204
248
  ```tsx
@@ -211,8 +255,67 @@ with `light-` or `dark-`:
211
255
  </Theme>
212
256
  ```
213
257
 
214
- These names are resolved from the existing color ramps at runtime and scoped
215
- to that `Theme` subtree. Built-in names such as `dark`, `emerald`, and
216
- `midnight` continue to use their precompiled theme classes. Supported palette
217
- names are the exported color scales, including `red`, `blue`, `green`,
218
- `purple`, and the other Radix scales.
258
+ These names are resolved on demand and scoped to that `Theme` subtree.
259
+ `CSSNamedColor` is a TypeScript-only union, not a runtime catalogue. JavaScript
260
+ and untrusted strings are not fully validated: runtime parsing does not verify
261
+ that an alphabetic name is a real CSS colour, so invalid names may generate
262
+ invalid CSS. Validate untrusted names against your own allowlist. Built-in
263
+ names such as `dark`, `emerald`, and `midnight` continue to use their
264
+ precompiled theme classes.
265
+
266
+ ### Custom theme scopes
267
+
268
+ Create a Vanilla Extract class using Silva UI's semantic contract in a
269
+ `*.css.ts` file:
270
+
271
+ ```ts
272
+ import { createTheme } from '@vanilla-extract/css';
273
+ import { lightColors, themeColors } from 'silva-ui';
274
+
275
+ export const brandTheme = createTheme(themeColors, {
276
+ ...lightColors,
277
+ primary: '#7c3aed',
278
+ primaryHover: '#6d28d9',
279
+ primaryActive: '#5b21b6',
280
+ primaryContrast: '#ffffff',
281
+ ring: '#7c3aed',
282
+ });
283
+ ```
284
+
285
+ Bind it to a literal key in a locally typed component:
286
+
287
+ ```tsx
288
+ import { Box, Text, createThemeScope } from 'silva-ui';
289
+ import { brandTheme } from './brand-theme.css';
290
+
291
+ const AppTheme = createThemeScope({
292
+ brand: { className: brandTheme, mode: 'light' },
293
+ });
294
+
295
+ <AppTheme name="brand">
296
+ <Box bg="card" color="primary"><Text>Brand theme</Text></Box>
297
+ </AppTheme>;
298
+ ```
299
+
300
+ `AppTheme` accepts built-in and CSS-colour `ThemeName` values plus its own map's
301
+ literal keys; `Theme` and other scopes do not gain `brand`. Runtime theme
302
+ creation cannot mutate global TypeScript types. Scoped keys must not collide
303
+ with built-in names, CSS named colours or shades. `mode: 'light'` sets the
304
+ named-shade base to white; `mode: 'dark'` sets it to black. Omitting mode
305
+ inherits the surrounding base. You can instead apply the class explicitly to a
306
+ wrapper inside a suitable built-in `Theme`. The class itself supplies semantic
307
+ values, not the named-shade base.
308
+
309
+ `accentColor` sets the scope's `--silva-theme-color` and
310
+ `--silva-theme-contrast` inputs; it does not replace fixed semantic values in
311
+ the class. For example, the fixed `primary`, `primaryHover`, `primaryActive`,
312
+ `primaryContrast`, and `ring` above stay fixed even if `AppTheme` receives an
313
+ `accentColor`. To make a value respond, define it using the relevant accent or
314
+ contrast variable, or retain the corresponding variable-based `lightColors`
315
+ value instead of overriding it. `mode` controls the base and contrast
316
+ calculation, not whether fixed values respond.
317
+
318
+ `createThemes` generates plain value records, while the separate mutable theme
319
+ registry stores records. Neither creates or applies a CSS class or registers a
320
+ name/type. Pass a complete semantic record to Vanilla Extract's `createTheme`
321
+ and then apply the resulting class explicitly or bind it with `createThemeScope`.