@mellow.io/ds 0.1.0 → 0.1.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/README.md +229 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
# @mellow.io/ds
|
|
2
|
+
|
|
3
|
+
Mellow Design System — a library of 30+ UI components built with [Lit 3](https://lit.dev/) Web Components. Works with any framework or no framework at all.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @mellow.io/ds
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
### HTML / Vanilla JS
|
|
14
|
+
|
|
15
|
+
Import the components you need. Each import auto-registers the custom element.
|
|
16
|
+
|
|
17
|
+
```html
|
|
18
|
+
<script type="module">
|
|
19
|
+
import '@mellow.io/ds/button'
|
|
20
|
+
import '@mellow.io/ds/input'
|
|
21
|
+
</script>
|
|
22
|
+
|
|
23
|
+
<mellow-button variant="primary" size="md">Save</mellow-button>
|
|
24
|
+
<mellow-input label="Email" placeholder="you@example.com"></mellow-input>
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### React
|
|
28
|
+
|
|
29
|
+
React wrappers handle property binding and event mapping via `@lit/react`.
|
|
30
|
+
|
|
31
|
+
```tsx
|
|
32
|
+
import { MellowButtonReact, MellowInputReact } from '@mellow.io/ds/react'
|
|
33
|
+
|
|
34
|
+
function App() {
|
|
35
|
+
return (
|
|
36
|
+
<>
|
|
37
|
+
<MellowButtonReact variant="primary" size="md">
|
|
38
|
+
Save
|
|
39
|
+
</MellowButtonReact>
|
|
40
|
+
<MellowInputReact
|
|
41
|
+
label="Email"
|
|
42
|
+
placeholder="you@example.com"
|
|
43
|
+
onMellowChange={(e) => console.log(e.detail.value)}
|
|
44
|
+
/>
|
|
45
|
+
</>
|
|
46
|
+
)
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Import Strategies
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
// Full bundle — registers all 30+ components at once
|
|
54
|
+
import '@mellow.io/ds'
|
|
55
|
+
|
|
56
|
+
// Per-component (tree-shakeable, recommended)
|
|
57
|
+
import '@mellow.io/ds/button'
|
|
58
|
+
import '@mellow.io/ds/tabs'
|
|
59
|
+
|
|
60
|
+
// React wrappers
|
|
61
|
+
import { MellowButtonReact } from '@mellow.io/ds/react'
|
|
62
|
+
|
|
63
|
+
// TypeScript types only
|
|
64
|
+
import type { ButtonVariant, ButtonSize } from '@mellow.io/ds/button'
|
|
65
|
+
|
|
66
|
+
// Design tokens as CSS
|
|
67
|
+
import '@mellow.io/ds/tokens'
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Components
|
|
71
|
+
|
|
72
|
+
### Forms
|
|
73
|
+
|
|
74
|
+
| Component | Tag | Description |
|
|
75
|
+
|---|---|---|
|
|
76
|
+
| [Button](docs/components.md#button) | `<mellow-button>` | Primary, secondary, brand, link variants with loading state |
|
|
77
|
+
| [Input](docs/components.md#input) | `<mellow-input>` | Text input with label, error, helper, clearable, icon slots |
|
|
78
|
+
| [Textarea](docs/components.md#textarea) | `<mellow-textarea>` | Multi-line input with character count |
|
|
79
|
+
| [Checkbox](docs/components.md#checkbox) | `<mellow-checkbox>` | Checkbox with indeterminate state |
|
|
80
|
+
| [Radio](docs/components.md#radio) | `<mellow-radio>` | Radio button (use inside `<mellow-radio-group>`) |
|
|
81
|
+
| [Switch](docs/components.md#switch) | `<mellow-switch>` | Toggle switch |
|
|
82
|
+
| [Select](docs/components.md#select) | `<mellow-select>` | Dropdown select with searchable option |
|
|
83
|
+
| [Form Field](docs/components.md#form-field) | `<mellow-form-field>` | Wrapper providing label, error, hint for any input |
|
|
84
|
+
|
|
85
|
+
### Primitives
|
|
86
|
+
|
|
87
|
+
| Component | Tag | Description |
|
|
88
|
+
|---|---|---|
|
|
89
|
+
| [Badge](docs/components.md#badge) | `<mellow-badge>` | Status badge with 7 semantic variants |
|
|
90
|
+
| [Tag](docs/components.md#tag) | `<mellow-tag>` | Selectable/removable chip |
|
|
91
|
+
| [Icon](docs/components.md#icon) | `<mellow-icon>` | SVG icon with registry system |
|
|
92
|
+
| [Divider](docs/components.md#divider) | `<mellow-divider>` | Horizontal/vertical separator |
|
|
93
|
+
|
|
94
|
+
### Layout
|
|
95
|
+
|
|
96
|
+
| Component | Tag | Description |
|
|
97
|
+
|---|---|---|
|
|
98
|
+
| [Card](docs/components.md#card) | `<mellow-card>` | Content container with header, icon, actions |
|
|
99
|
+
| [Stack](docs/components.md#stack) | `<mellow-stack>` | Flex layout (row/column) |
|
|
100
|
+
| [Grid](docs/components.md#grid) | `<mellow-grid>` | CSS grid layout |
|
|
101
|
+
|
|
102
|
+
### Feedback
|
|
103
|
+
|
|
104
|
+
| Component | Tag | Description |
|
|
105
|
+
|---|---|---|
|
|
106
|
+
| [Alert](docs/components.md#alert) | `<mellow-alert>` | Inline notification with 5 variants |
|
|
107
|
+
| [Toast](docs/components.md#toast) | `<mellow-toast>` | Floating notification with auto-dismiss |
|
|
108
|
+
| [Spinner](docs/components.md#spinner) | `<mellow-spinner>` | Loading spinner |
|
|
109
|
+
| [Skeleton](docs/components.md#skeleton) | `<mellow-skeleton>` | Content placeholder |
|
|
110
|
+
| [Progress](docs/components.md#progress) | `<mellow-progress>` | Progress bar |
|
|
111
|
+
| [Stepper](docs/components.md#stepper) | `<mellow-stepper>` | Segmented step indicator |
|
|
112
|
+
|
|
113
|
+
### Overlay
|
|
114
|
+
|
|
115
|
+
| Component | Tag | Description |
|
|
116
|
+
|---|---|---|
|
|
117
|
+
| [Dialog](docs/components.md#dialog) | `<mellow-dialog>` | Modal dialog |
|
|
118
|
+
| [Tooltip](docs/components.md#tooltip) | `<mellow-tooltip>` | Hover/focus tooltip with subtitle |
|
|
119
|
+
| [Popover](docs/components.md#popover) | `<mellow-popover>` | Click/hover popover |
|
|
120
|
+
| [Dropdown](docs/components.md#dropdown) | `<mellow-dropdown>` | Dropdown menu with search |
|
|
121
|
+
|
|
122
|
+
### Navigation
|
|
123
|
+
|
|
124
|
+
| Component | Tag | Description |
|
|
125
|
+
|---|---|---|
|
|
126
|
+
| [Tabs](docs/components.md#tabs) | `<mellow-tabs>` | Segmented tab navigation |
|
|
127
|
+
| [Breadcrumb](docs/components.md#breadcrumb) | `<mellow-breadcrumb>` | Breadcrumb trail |
|
|
128
|
+
| [Pagination](docs/components.md#pagination) | `<mellow-pagination>` | Page navigation |
|
|
129
|
+
| [Link](docs/components.md#link) | `<mellow-link>` | Styled anchor |
|
|
130
|
+
|
|
131
|
+
### Data
|
|
132
|
+
|
|
133
|
+
| Component | Tag | Description |
|
|
134
|
+
|---|---|---|
|
|
135
|
+
| [Table](docs/components.md#table) | `<mellow-table>` | Data table with sorting, pagination, selection |
|
|
136
|
+
| [Avatar](docs/components.md#avatar) | `<mellow-avatar>` | User avatar (image, initials, fallback) |
|
|
137
|
+
| [Accordion](docs/components.md#accordion) | `<mellow-accordion>` | Collapsible sections |
|
|
138
|
+
|
|
139
|
+
## Theming
|
|
140
|
+
|
|
141
|
+
All visual values are exposed as CSS custom properties with sensible defaults. Override them at any scope.
|
|
142
|
+
|
|
143
|
+
```css
|
|
144
|
+
/* Global theme override */
|
|
145
|
+
:root {
|
|
146
|
+
--mellow-colors-primary-mellow-orange: #ff6f23;
|
|
147
|
+
--mellow-text-primary: #232222;
|
|
148
|
+
--mellow-text-secondary: #8a8686;
|
|
149
|
+
--mellow-typography-font-family-body: 'Suisse Int\'l', system-ui, sans-serif;
|
|
150
|
+
--mellow-space-5: 20px;
|
|
151
|
+
--mellow-radius-2: 8px;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/* Per-component override */
|
|
155
|
+
mellow-button {
|
|
156
|
+
--mellow-button-primary-default: #1a1a2e;
|
|
157
|
+
--mellow-button-primary-hovered: #16213e;
|
|
158
|
+
}
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Token Categories
|
|
162
|
+
|
|
163
|
+
| Prefix | Purpose | Examples |
|
|
164
|
+
|---|---|---|
|
|
165
|
+
| `--mellow-colors-*` | Color palette | `--mellow-colors-primary-mellow-orange` |
|
|
166
|
+
| `--mellow-text-*` | Text colors | `--mellow-text-primary`, `--mellow-text-brand` |
|
|
167
|
+
| `--mellow-bg-*` | Background colors | `--mellow-bg-surface-primary` |
|
|
168
|
+
| `--mellow-button-*` | Button-specific colors | `--mellow-button-primary-default` |
|
|
169
|
+
| `--mellow-space-*` | Spacing scale | `--mellow-space-1` (4px) through `--mellow-space-6` (24px) |
|
|
170
|
+
| `--mellow-radius-*` | Border radius | `--mellow-radius-1` (4px) through `--mellow-radius-full` (9999px) |
|
|
171
|
+
| `--mellow-font-size-*` | Font sizes | `--mellow-font-size-12` through `--mellow-font-size-18` |
|
|
172
|
+
| `--mellow-line-height-*` | Line heights | `--mellow-line-height-14` through `--mellow-line-height-24` |
|
|
173
|
+
| `--mellow-font-weight-*` | Font weights | `--mellow-font-weight-regular` (400), `--mellow-font-weight-medium` (500) |
|
|
174
|
+
| `--mellow-typography-font-family-*` | Font families | `--mellow-typography-font-family-body` |
|
|
175
|
+
|
|
176
|
+
## Events
|
|
177
|
+
|
|
178
|
+
All custom events use the `mellow-` prefix, bubble, and are composed (cross shadow DOM boundaries).
|
|
179
|
+
|
|
180
|
+
```ts
|
|
181
|
+
// Vanilla JS
|
|
182
|
+
document.querySelector('mellow-input')
|
|
183
|
+
.addEventListener('mellow-change', (e) => {
|
|
184
|
+
console.log(e.detail.value)
|
|
185
|
+
})
|
|
186
|
+
|
|
187
|
+
// React (via wrappers)
|
|
188
|
+
<MellowInputReact onMellowChange={(e) => console.log(e.detail.value)} />
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
| Event | Components | Detail |
|
|
192
|
+
|---|---|---|
|
|
193
|
+
| `mellow-change` | input, textarea, checkbox, radio-group, select, switch | `{ value }` or `{ checked }` |
|
|
194
|
+
| `mellow-input` | input, textarea | `{ value }` |
|
|
195
|
+
| `mellow-select` | dropdown, tag | `{ value }` or `{ selected }` |
|
|
196
|
+
| `mellow-dismiss` | alert, toast | — |
|
|
197
|
+
| `mellow-close` | dialog | — |
|
|
198
|
+
| `mellow-toggle` | accordion-item, popover | `{ open }` |
|
|
199
|
+
| `mellow-sort` | table | `{ column, direction }` |
|
|
200
|
+
| `mellow-page-change` | pagination, table | `{ page }` |
|
|
201
|
+
| `mellow-tab-change` | tabs | `{ index }` |
|
|
202
|
+
| `mellow-remove` | tag | — |
|
|
203
|
+
| `mellow-search` | dropdown | `{ query }` |
|
|
204
|
+
| `mellow-page-size-change` | table | `{ pageSize }` |
|
|
205
|
+
|
|
206
|
+
## Browser Support
|
|
207
|
+
|
|
208
|
+
Works in all browsers that support Web Components (Custom Elements v1 + Shadow DOM):
|
|
209
|
+
- Chrome / Edge 67+
|
|
210
|
+
- Firefox 63+
|
|
211
|
+
- Safari 13.1+
|
|
212
|
+
|
|
213
|
+
## API Reference
|
|
214
|
+
|
|
215
|
+
See [docs/components.md](docs/components.md) for the full API of every component — properties, slots, events, and types.
|
|
216
|
+
|
|
217
|
+
## Development
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
npm install # Install dependencies
|
|
221
|
+
npm run dev # Start Storybook on :6006
|
|
222
|
+
npm test # Run 497 tests
|
|
223
|
+
npm run build # Vite build + type declarations
|
|
224
|
+
npm run typecheck # TypeScript check
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
## License
|
|
228
|
+
|
|
229
|
+
UNLICENSED
|