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.
- package/README.md +129 -30
- package/dist/library/silva-ui.css +1 -1
- package/dist/library/silva-ui.js +993 -23305
- package/dist/types/core/Theme.d.ts +28 -6
- package/dist/types/core/colors/index.d.ts +16 -8
- package/dist/types/core/compound.d.ts +6 -0
- package/dist/types/core/dynamic-colors.css.d.ts +6 -0
- package/dist/types/core/gradient.d.ts +1 -1
- package/dist/types/core/sprinkles.css.d.ts +17 -407
- package/dist/types/core/theme/index.css.d.ts +4 -398
- package/dist/types/core/theme.css.d.ts +3 -3
- package/dist/types/core/themes/index.d.ts +228 -6
- package/dist/types/core/types.d.ts +11 -6
- package/dist/types/core/utils.d.ts +2 -1
- package/dist/types/core/visuals.css.d.ts +2 -2
- package/dist/types/display/Avatar.d.ts +1 -1
- package/dist/types/display/Card.d.ts +1 -1
- package/dist/types/display/Image.d.ts +2 -2
- package/dist/types/display/ListItem.d.ts +1 -1
- package/dist/types/display/Loader.d.ts +1 -1
- package/dist/types/display/Spinner.d.ts +1 -1
- package/dist/types/forms/Button.d.ts +1 -1
- package/dist/types/forms/Checkbox.d.ts +1 -1
- package/dist/types/forms/Field.d.ts +1 -1
- package/dist/types/forms/Form.d.ts +1 -1
- package/dist/types/forms/Input.d.ts +1 -1
- package/dist/types/forms/Label.d.ts +1 -1
- package/dist/types/forms/Progress.d.ts +1 -1
- package/dist/types/forms/RadioGroup.d.ts +1 -1
- package/dist/types/forms/Select.d.ts +9 -2
- package/dist/types/forms/Slider.d.ts +1 -1
- package/dist/types/forms/Switch.d.ts +1 -1
- package/dist/types/forms/TextArea.d.ts +1 -1
- package/dist/types/forms/ToggleGroup.d.ts +1 -1
- package/dist/types/index.d.ts +99 -99
- package/dist/types/layout/Box.d.ts +2 -2
- package/dist/types/layout/Separator.d.ts +1 -1
- package/dist/types/layout/XGroup.d.ts +1 -1
- package/dist/types/layout/XStack.d.ts +1 -1
- package/dist/types/layout/YStack.d.ts +1 -1
- package/dist/types/overlays/Accordion.d.ts +1 -1
- package/dist/types/overlays/AlertDialog.d.ts +3 -2
- package/dist/types/overlays/ContextMenu.d.ts +1 -1
- package/dist/types/overlays/Dialog.d.ts +3 -2
- package/dist/types/overlays/Menu.d.ts +1 -1
- package/dist/types/overlays/Popover.d.ts +1 -1
- package/dist/types/overlays/Sheet.d.ts +3 -2
- package/dist/types/overlays/Tabs.d.ts +1 -1
- package/dist/types/overlays/Toast.d.ts +1 -1
- package/dist/types/overlays/Tooltip.d.ts +1 -1
- package/dist/types/typography/Anchor.d.ts +1 -1
- package/dist/types/typography/Heading.d.ts +1 -1
- package/dist/types/typography/Headings.d.ts +1 -1
- package/dist/types/typography/Paragraph.d.ts +1 -1
- package/dist/types/typography/SizableText.d.ts +2 -2
- package/dist/types/typography/Text.d.ts +1 -1
- package/package.json +81 -70
- 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
|
|
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
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
`
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
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
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
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
|
|
187
|
-
|
|
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
|
|
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
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
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`.
|