@w5-ui/wc 0.2.1 → 0.3.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 +101 -0
- package/dist/index.js +3863 -1703
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/README.md
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# @w5-ui/wc
|
|
2
|
+
|
|
3
|
+
Framework-agnostic Web Components (`<dash-*>`) for the Dash UI design system. Compiled from
|
|
4
|
+
`@w5-ui/svelte`. Use in any framework or vanilla HTML.
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
yarn add @w5-ui/wc
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
## Quick start
|
|
11
|
+
|
|
12
|
+
```html
|
|
13
|
+
<link rel="stylesheet" href="@w5-ui/wc/styles.css" />
|
|
14
|
+
<script type="module" src="@w5-ui/wc"></script>
|
|
15
|
+
|
|
16
|
+
<dash-app-layout page-label="Dashboard">
|
|
17
|
+
<dash-topbar slot="topbar" site-name="HQ" active-app="system"></dash-topbar>
|
|
18
|
+
<dash-sidebar slot="sidebar"></dash-sidebar>
|
|
19
|
+
|
|
20
|
+
<dash-page-header title="Dashboard"></dash-page-header>
|
|
21
|
+
<div class="grid">
|
|
22
|
+
<dash-stat span="4" label="Internet" value="847" unit="Mbps"></dash-stat>
|
|
23
|
+
<dash-stat span="4" label="Clients" value="124"></dash-stat>
|
|
24
|
+
<dash-stat span="4" label="Throughput" value="12.4" unit="Gbps"></dash-stat>
|
|
25
|
+
<dash-card span="8">
|
|
26
|
+
<h3>Traffic <dash-pill variant="success">healthy</dash-pill></h3>
|
|
27
|
+
</dash-card>
|
|
28
|
+
<dash-card span="4">
|
|
29
|
+
<h3>Top clients</h3>
|
|
30
|
+
</dash-card>
|
|
31
|
+
</div>
|
|
32
|
+
</dash-app-layout>
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
That single skeleton (`dash-app-layout` then `dash-page-header` then `<div class="grid">` then
|
|
36
|
+
`<dash-card span="n">`) carries every padding, gap, and column value the reference dashboards use.
|
|
37
|
+
Reproduce it verbatim and spacing falls into place automatically.
|
|
38
|
+
|
|
39
|
+
## The contract (read this before styling anything)
|
|
40
|
+
|
|
41
|
+
The reference dashboards (rendered in Storybook under **Dashboard**) all share one skeleton.
|
|
42
|
+
Userland looking different almost always comes down to one of these:
|
|
43
|
+
|
|
44
|
+
| Don't | Do |
|
|
45
|
+
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
46
|
+
| Wrap `.grid` in your own `<div style="padding: ...">` | Render `.grid` as a direct child of `<main>`. It already pads 16px x 24px. |
|
|
47
|
+
| `display: flex; gap: ...` on the page root | Render `dash-banner`, `dash-page-header`, `.grid` as siblings. They own their spacing. |
|
|
48
|
+
| Re-implement `.card` with a `<div>` and a custom border-radius | Use `<dash-card>` or `<dash-stat>`. The radius, padding, and `<h3>` rhythm ship together. |
|
|
49
|
+
| `<h3>` outside a `<dash-card>` | Keep titles inside `<dash-card>`. The `.card h3` selector sizes and colours them. |
|
|
50
|
+
| `<span style="color: green">online</span>` | Use `<dash-pill variant="success">online</dash-pill>` (or `<dash-badge>`). |
|
|
51
|
+
| Mix `span="5"` and `span="7"` | Use 4 / 6 / 8 / 12 so rows divide cleanly into the 12-column grid. |
|
|
52
|
+
| Skip `dash-app-layout` and roll your own `.app` grid | Use `dash-app-layout` once at the root. `.app`, `.workspace`, and `<main>` line up. |
|
|
53
|
+
| Hand-pick hex colours | Use tokens via the `data-motif` CSS variables. See `@w5-ui/tokens`. |
|
|
54
|
+
|
|
55
|
+
## Grid math
|
|
56
|
+
|
|
57
|
+
`.grid` is `repeat(12, 1fr)` with a 12px gap and 16px x 24px outer padding.
|
|
58
|
+
|
|
59
|
+
| Tile width | `span` | Typical use |
|
|
60
|
+
| ---------- | ------ | ------------------------------------ |
|
|
61
|
+
| Third | `4` | Single-stat card, donut |
|
|
62
|
+
| Half | `6` | Two-column comparison |
|
|
63
|
+
| Two-thirds | `8` | Wide table, line chart |
|
|
64
|
+
| Full | `12` | Time series, sankey, page-wide table |
|
|
65
|
+
|
|
66
|
+
4+4+4, 8+4, 6+6, and 12 all snap cleanly. Avoid 5 and 7. They leave dead pixels.
|
|
67
|
+
|
|
68
|
+
## What lives where
|
|
69
|
+
|
|
70
|
+
| Package | Description |
|
|
71
|
+
| --------------- | -------------------------------------------------------- |
|
|
72
|
+
| `@w5-ui/wc` | ~165 custom elements (this package) |
|
|
73
|
+
| `@w5-ui/react` | The same component surface for React |
|
|
74
|
+
| `@w5-ui/svelte` | The same component surface for Svelte |
|
|
75
|
+
| `@w5-ui/tokens` | CSS variables (`data-motif="dark"` / `"light"`) + JS map |
|
|
76
|
+
| `@w5-ui/assets` | Brand mark, wordmark, app-rail SVGs |
|
|
77
|
+
|
|
78
|
+
`@w5-ui/wc/styles.css` re-exports `@w5-ui/tokens/dashboard.css`, so importing it once is enough for
|
|
79
|
+
tokens, the `.app` / `.workspace` / `.grid` / `.card` classes, and component styles.
|
|
80
|
+
|
|
81
|
+
## Themes
|
|
82
|
+
|
|
83
|
+
Two motifs ship in tokens. Set the attribute on `<html>` (or any ancestor of the app root):
|
|
84
|
+
|
|
85
|
+
```html
|
|
86
|
+
<html data-motif="dark">
|
|
87
|
+
<!-- the default -->
|
|
88
|
+
</html>
|
|
89
|
+
<html data-motif="light"></html>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Reference
|
|
93
|
+
|
|
94
|
+
- **Storybook (Web Components)**: `/wc/` in the published site
|
|
95
|
+
- **Foundations / Page layout** in `/svelte/` or `/` Storybooks: the canonical recipe in full
|
|
96
|
+
- **Foundations / Spacing**, **Colours**, **Type**, **Icons**, **Forms**, **Tables**, **Charts**,
|
|
97
|
+
**Status & feedback**, **Navigation**, **Overlays**, **Actions**: pick-by-question tables for
|
|
98
|
+
every primitive
|
|
99
|
+
|
|
100
|
+
When your page looks different from the reference, open the matching Storybook story and diff the
|
|
101
|
+
markup.
|