@leodamours/ds-components 0.2.0 → 0.2.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 +142 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# @leodamours/ds-components
|
|
2
|
+
|
|
3
|
+
Vue 3 component library with built-in design tokens and theming support via CSS custom properties.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @leodamours/ds-components
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
**Peer dependency:** `vue ^3.5.0`
|
|
12
|
+
|
|
13
|
+
## Setup
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
// main.ts
|
|
17
|
+
import '@leodamours/ds-components/style.css'
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
That's it. The stylesheet includes both the default theme (CSS custom properties) and the component styles.
|
|
21
|
+
|
|
22
|
+
## Usage
|
|
23
|
+
|
|
24
|
+
```vue
|
|
25
|
+
<script setup>
|
|
26
|
+
import { DsButton, DsInput } from '@leodamours/ds-components'
|
|
27
|
+
</script>
|
|
28
|
+
|
|
29
|
+
<template>
|
|
30
|
+
<DsInput label="Email" placeholder="you@example.com" />
|
|
31
|
+
<DsButton variant="primary" label="Submit" />
|
|
32
|
+
</template>
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Components
|
|
36
|
+
|
|
37
|
+
| Component | Description |
|
|
38
|
+
|---|---|
|
|
39
|
+
| `DsAvatar` | User avatar with initials fallback |
|
|
40
|
+
| `DsBadge` | Status badge / label |
|
|
41
|
+
| `DsButton` | Button with variants: primary, secondary, outline, ghost, danger, success |
|
|
42
|
+
| `DsCheckbox` | Checkbox input |
|
|
43
|
+
| `DsDropdownSelect` | Dropdown select with floating UI positioning |
|
|
44
|
+
| `DsInput` | Text input with label, help text, error state |
|
|
45
|
+
| `DsLoadingSpinner` | Animated loading spinner |
|
|
46
|
+
| `DsModal` | Modal dialog with backdrop |
|
|
47
|
+
| `DsRadio` | Radio input |
|
|
48
|
+
| `DsSelect` | Native select wrapper |
|
|
49
|
+
| `DsTable` | Data table with sorting and pagination |
|
|
50
|
+
| `DsTabs` | Tab navigation |
|
|
51
|
+
| `DsTextarea` | Multiline text input |
|
|
52
|
+
| `DsToast` / `DsToastContainer` | Toast notifications |
|
|
53
|
+
| `DsTooltip` | Tooltip on hover |
|
|
54
|
+
|
|
55
|
+
All components export their prop types (e.g., `DsButtonProps`, `DsInputProps`).
|
|
56
|
+
|
|
57
|
+
## Theming
|
|
58
|
+
|
|
59
|
+
Every color in the library flows through CSS custom properties prefixed with `--ds-`. The default theme is included in `style.css`. To customize, override the variables you need:
|
|
60
|
+
|
|
61
|
+
```css
|
|
62
|
+
/* my-theme.css */
|
|
63
|
+
:root {
|
|
64
|
+
--ds-brand: #8B5CF6;
|
|
65
|
+
--ds-brand-hover: #7C3AED;
|
|
66
|
+
--ds-brand-active: #6D28D9;
|
|
67
|
+
--ds-brand-on-solid: #FFFFFF;
|
|
68
|
+
--ds-bg: #FAFAFA;
|
|
69
|
+
--ds-error: #DC2626;
|
|
70
|
+
/* Only override what differs — everything else inherits defaults */
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
import '@leodamours/ds-components/style.css' // defaults
|
|
76
|
+
import './my-theme.css' // overrides
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### Token naming convention
|
|
80
|
+
|
|
81
|
+
Tokens follow a **role + tone** pattern: `{role}[-{tone}][-{state}]`
|
|
82
|
+
|
|
83
|
+
| Role | Purpose | Example tokens |
|
|
84
|
+
|---|---|---|
|
|
85
|
+
| Core | Page-level UI | `bg`, `fg`, `border`, `icon`, `surface-hover` |
|
|
86
|
+
| `brand` | Primary actions | `brand`, `brand-hover`, `brand-soft`, `brand-on-solid` |
|
|
87
|
+
| `neutral` | Secondary actions | `neutral-soft`, `neutral-on-soft`, `neutral-border` |
|
|
88
|
+
| `error` | Error / destructive | `error`, `error-soft`, `error-on-solid`, `error-border` |
|
|
89
|
+
| `success` | Success feedback | `success`, `success-soft`, `success-on-solid` |
|
|
90
|
+
| `warning` | Warning feedback | `warning`, `warning-soft`, `warning-on-soft` |
|
|
91
|
+
| `info` | Informational | `info`, `info-soft`, `info-on-soft` |
|
|
92
|
+
|
|
93
|
+
**Tones:**
|
|
94
|
+
- `{role}` — the solid color (e.g., `--ds-error` = `#EF4444`)
|
|
95
|
+
- `{role}-soft` — light background variant (e.g., `--ds-error-soft` = `#FEF2F2`)
|
|
96
|
+
- `{role}-on-solid` — text/icon color on the solid bg (e.g., `--ds-error-on-solid` = `#FFFFFF`)
|
|
97
|
+
- `{role}-on-soft` — text/icon color on the soft bg (e.g., `--ds-error-on-soft` = `#EF4444`)
|
|
98
|
+
- `{role}-border` — border color for that role
|
|
99
|
+
|
|
100
|
+
### Runtime theme switching
|
|
101
|
+
|
|
102
|
+
```css
|
|
103
|
+
[data-theme="dark"] {
|
|
104
|
+
--ds-bg: #0F172A;
|
|
105
|
+
--ds-fg: #F8FAFC;
|
|
106
|
+
--ds-border: #334155;
|
|
107
|
+
--ds-brand: #38BDF8;
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
```ts
|
|
112
|
+
document.documentElement.dataset.theme = 'dark'
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Programmatic theme generation
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
import { generateThemeCss } from '@leodamours/ds-components'
|
|
119
|
+
|
|
120
|
+
const css = generateThemeCss(
|
|
121
|
+
{ brand: '#8B5CF6', 'brand-hover': '#7C3AED' },
|
|
122
|
+
'[data-theme="purple"]'
|
|
123
|
+
)
|
|
124
|
+
// Returns a CSS string you can inject into a <style> tag
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Exports
|
|
128
|
+
|
|
129
|
+
```ts
|
|
130
|
+
// Components
|
|
131
|
+
import { DsButton, DsInput, /* ... */ } from '@leodamours/ds-components'
|
|
132
|
+
|
|
133
|
+
// Prop types
|
|
134
|
+
import type { DsButtonProps, DsInputProps } from '@leodamours/ds-components'
|
|
135
|
+
|
|
136
|
+
// Token utilities
|
|
137
|
+
import { colorTokens, generateThemeCss, tokenToCssVar } from '@leodamours/ds-components'
|
|
138
|
+
import type { ColorToken, ThemeOverride } from '@leodamours/ds-components'
|
|
139
|
+
|
|
140
|
+
// Composables
|
|
141
|
+
import { useToast, useId } from '@leodamours/ds-components'
|
|
142
|
+
```
|