silva-ui 1.3.1 → 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 (58) hide show
  1. package/README.md +129 -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 -70
  58. package/dist/types/core/colors/radix.d.ts +0 -1396
package/README.md CHANGED
@@ -20,6 +20,8 @@ A Hono JSX UI component library with framework-neutral styling and Tamagui-inspi
20
20
 
21
21
  Read the [Silva UI documentation](https://blacksilva.com/silva-ui) for installation, theming, foundations, components, and API guidance.
22
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
+
23
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.
24
26
 
25
27
  Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for
@@ -138,11 +140,17 @@ export function SignupCard() {
138
140
  The published package includes prebuilt CSS. Import `silva-ui/style.css` once
139
141
  from your application entry point.
140
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
+
141
150
  ## Colors and themes
142
151
 
143
152
  Theme styling is generated at build time with Vanilla Extract. `Theme` scopes the
144
- selected theme to a subtree, so nested themes override their parent without
145
- runtime style injection:
153
+ selected theme to a subtree, so nested themes override their parent:
146
154
 
147
155
  ```tsx
148
156
  import { Box, Text, Theme } from 'silva-ui';
@@ -159,32 +167,64 @@ import { Box, Text, Theme } from 'silva-ui';
159
167
  </Theme>;
160
168
  ```
161
169
 
162
- Color ramps are exported as `colorScales` and are also registered as sprinkles
163
- color tokens. They follow the Tamagui/Radix convention: the same numbered token
164
- has a light-palette value in light themes and a dark-palette value in dark
165
- themes. The referenced `colors` source provides 28 hue ramps plus `blackA` and
166
- `whiteA`, each with 12 numbered stops.
167
-
168
- For example, `color="blue12"` is dark on light themes and light on dark themes;
169
- `bg="blue6"` adapts with the rest of the ramp. Use tokens such as `bg="blue6"`,
170
- `color="gray11"`, `borderColor="teal4"`, or alpha tokens such as
171
- `backgroundColor="blackA4"`. Semantic names such as `background`, `card`,
172
- `primary`, `muted`, and `border` also adapt to the active theme and are
173
- preferred when a semantic role is clearer than a specific hue.
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.
174
218
 
175
- Built-in themes are `light`, `dark`, `emerald`, `emerald-dark`, and `midnight`.
176
219
  Their semantic values are defined in `src/core/themes`; the token contract and
177
- CSS variables are in `src/core/theme`; `src/core/theme-builder` combines theme
178
- definitions with the palette tokens. To add a theme, add a complete semantic
179
- color map to `themeDefinitions` in `src/core/themes` and register dark variants
180
- in `darkThemeNames` there so their ramps reverse. The theme class and
181
- `data-theme` selector are generated from those maps. Add a switcher control in
182
- `example/App.tsx` if you want it available in the demo. Theme classes and CSS
183
- 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).
184
224
 
185
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
186
- `themeColors.background` or `themeColors.blue6`; Vanilla Extract can then keep
187
- the variable names consistent through production builds.
226
+ `themeColors.background`; Vanilla Extract can then keep semantic variable names
227
+ consistent through production builds.
188
228
 
189
229
  Silva UI follows Tamagui's palette/template model. The exported `createThemes` helper composes named palettes and
190
230
  templates into theme records, and built-in themes include generated surface
@@ -202,7 +242,7 @@ import { Card, Theme } from 'silva-ui';
202
242
  ```
203
243
 
204
244
  Palette themes can also be selected without registering or prebuilding a
205
- 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
206
246
  with `light-` or `dark-`:
207
247
 
208
248
  ```tsx
@@ -215,8 +255,67 @@ with `light-` or `dark-`:
215
255
  </Theme>
216
256
  ```
217
257
 
218
- These names are resolved from the existing color ramps at runtime and scoped
219
- to that `Theme` subtree. Built-in names such as `dark`, `emerald`, and
220
- `midnight` continue to use their precompiled theme classes. Supported palette
221
- names are the exported color scales, including `red`, `blue`, `green`,
222
- `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`.