@waaelg/dga-design-system 0.4.2
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 +480 -0
- package/docs/README.md +76 -0
- package/docs/changelog.md +54 -0
- package/docs/components/accordion.md +114 -0
- package/docs/components/alert.md +130 -0
- package/docs/components/avatar.md +74 -0
- package/docs/components/breadcrumb.md +56 -0
- package/docs/components/button.md +163 -0
- package/docs/components/card.md +78 -0
- package/docs/components/chart.md +97 -0
- package/docs/components/code-snippet.md +110 -0
- package/docs/components/divider.md +54 -0
- package/docs/components/forms.md +123 -0
- package/docs/components/link.md +52 -0
- package/docs/components/navbar.md +93 -0
- package/docs/components/table.md +69 -0
- package/docs/components/tag.md +76 -0
- package/docs/components/verify-bar.md +79 -0
- package/docs/foundations/colors-cheatsheet.md +593 -0
- package/docs/foundations/colors-swatches.md +441 -0
- package/docs/foundations/colors.md +1284 -0
- package/docs/foundations/grid.md +1406 -0
- package/docs/foundations/radius.md +1166 -0
- package/docs/foundations/spacing.md +134 -0
- package/docs/foundations/typography.md +111 -0
- package/docs/foundations/width-height.md +305 -0
- package/docs/getting-started/installation.md +158 -0
- package/docs/getting-started/javascript-api.md +204 -0
- package/docs/getting-started/rtl-arabic.md +89 -0
- package/docs/getting-started/web-components.md +134 -0
- package/package.json +41 -0
package/README.md
ADDED
|
@@ -0,0 +1,480 @@
|
|
|
1
|
+
# @waaelg/dga-design-on-sass
|
|
2
|
+
|
|
3
|
+
Saudi **DGA (Digital Government Authority)** design system — compiled CSS utilities, components, and optional JavaScript for interactive behavior.
|
|
4
|
+
|
|
5
|
+
- Responsive 12-column grid
|
|
6
|
+
- Typography, spacing, colors, radius, and **width/height** utilities
|
|
7
|
+
- UI components (buttons, alerts, accordion, navbar, cards, forms, and more)
|
|
8
|
+
- Optional JS helpers for interactive components
|
|
9
|
+
- Built-in **IBM Plex Sans Arabic** font
|
|
10
|
+
- RTL-friendly markup patterns
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm install @waaelg/dga-design-on-sass
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The published package includes compiled assets from the `dist` folder:
|
|
21
|
+
|
|
22
|
+
| Import path | Description |
|
|
23
|
+
|-------------|-------------|
|
|
24
|
+
| `@waaelg/dga-design-on-sass/style.css` | All compiled styles |
|
|
25
|
+
| `@waaelg/dga-design-on-sass` | JavaScript component classes |
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Quick start
|
|
30
|
+
|
|
31
|
+
### 1. Import the stylesheet
|
|
32
|
+
|
|
33
|
+
```js
|
|
34
|
+
import '@waaelg/dga-design-on-sass/style.css';
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### 2. Use `dga-*` classes in your HTML
|
|
38
|
+
|
|
39
|
+
```html
|
|
40
|
+
<html lang="ar" dir="rtl">
|
|
41
|
+
<body class="dga-bg-gray-25">
|
|
42
|
+
<div class="dga-container">
|
|
43
|
+
<div class="dga-row">
|
|
44
|
+
<div class="dga-col-12 dga-col-md-6">
|
|
45
|
+
<button class="dga-btn dga-btn-primary">زر أساسي</button>
|
|
46
|
+
</div>
|
|
47
|
+
</div>
|
|
48
|
+
</div>
|
|
49
|
+
</body>
|
|
50
|
+
</html>
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### 3. Initialize JavaScript (only when needed)
|
|
54
|
+
|
|
55
|
+
Static components work with CSS alone. For **legacy HTML markup**, interactive components need a one-time JS setup. **Web components** (`<dga-*>`) handle behavior automatically.
|
|
56
|
+
|
|
57
|
+
```js
|
|
58
|
+
import '@waaelg/dga-design-on-sass/style.css';
|
|
59
|
+
import '@waaelg/dga-design-on-sass'; // registers <dga-*> elements
|
|
60
|
+
|
|
61
|
+
// Legacy only:
|
|
62
|
+
import { DGAAlert } from '@waaelg/dga-design-on-sass';
|
|
63
|
+
new DGAAlert();
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
**Web component (no init):**
|
|
67
|
+
|
|
68
|
+
```html
|
|
69
|
+
<dga-alert variant="success-color" title="Success" dismissible>
|
|
70
|
+
Operation completed successfully.
|
|
71
|
+
</dga-alert>
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Usage by project type
|
|
77
|
+
|
|
78
|
+
### Vite / React / Vue / Svelte
|
|
79
|
+
|
|
80
|
+
Add the CSS import once in your entry file (`main.js`, `main.tsx`, `App.vue`, etc.):
|
|
81
|
+
|
|
82
|
+
```js
|
|
83
|
+
import '@waaelg/dga-design-on-sass/style.css';
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**React example**
|
|
87
|
+
|
|
88
|
+
```jsx
|
|
89
|
+
import { useEffect } from 'react';
|
|
90
|
+
import '@waaelg/dga-design-on-sass/style.css';
|
|
91
|
+
import { DGAAccordion, DGAAlert } from '@waaelg/dga-design-on-sass';
|
|
92
|
+
|
|
93
|
+
export function App() {
|
|
94
|
+
useEffect(() => {
|
|
95
|
+
const accordionEl = document.getElementById('faq');
|
|
96
|
+
if (accordionEl) new DGAAccordion(accordionEl);
|
|
97
|
+
new DGAAlert();
|
|
98
|
+
}, []);
|
|
99
|
+
|
|
100
|
+
return (
|
|
101
|
+
<div className="dga-container">
|
|
102
|
+
<div className="dga-acc" id="faq">
|
|
103
|
+
<div className="dga-acc-item">
|
|
104
|
+
<button className="dga-acc-header" aria-expanded="false">
|
|
105
|
+
<span>السؤال الأول</span>
|
|
106
|
+
</button>
|
|
107
|
+
<div className="dga-acc-content">
|
|
108
|
+
<div className="dga-acc-body">الإجابة هنا.</div>
|
|
109
|
+
</div>
|
|
110
|
+
</div>
|
|
111
|
+
</div>
|
|
112
|
+
</div>
|
|
113
|
+
);
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Next.js (App Router)
|
|
118
|
+
|
|
119
|
+
Import styles in `app/layout.tsx`:
|
|
120
|
+
|
|
121
|
+
```tsx
|
|
122
|
+
import '@waaelg/dga-design-on-sass/style.css';
|
|
123
|
+
|
|
124
|
+
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
|
125
|
+
return (
|
|
126
|
+
<html lang="ar" dir="rtl">
|
|
127
|
+
<body>{children}</body>
|
|
128
|
+
</html>
|
|
129
|
+
);
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Use a client component for JS initialization:
|
|
134
|
+
|
|
135
|
+
```tsx
|
|
136
|
+
'use client';
|
|
137
|
+
|
|
138
|
+
import { useEffect } from 'react';
|
|
139
|
+
import { DGAAlert } from '@waaelg/dga-design-on-sass';
|
|
140
|
+
|
|
141
|
+
export function DGAInit() {
|
|
142
|
+
useEffect(() => {
|
|
143
|
+
new DGAAlert();
|
|
144
|
+
}, []);
|
|
145
|
+
|
|
146
|
+
return null;
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### Plain HTML
|
|
151
|
+
|
|
152
|
+
```html
|
|
153
|
+
<!DOCTYPE html>
|
|
154
|
+
<html lang="ar" dir="rtl">
|
|
155
|
+
<head>
|
|
156
|
+
<meta charset="UTF-8" />
|
|
157
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
158
|
+
<link rel="stylesheet" href="./node_modules/@waaelg/dga-design-on-sass/dist/style.css" />
|
|
159
|
+
</head>
|
|
160
|
+
<body>
|
|
161
|
+
<button class="dga-btn dga-btn-primary">زر</button>
|
|
162
|
+
|
|
163
|
+
<script type="module">
|
|
164
|
+
import { DGAAlert } from './node_modules/@waaelg/dga-design-on-sass/dist/index.js';
|
|
165
|
+
new DGAAlert();
|
|
166
|
+
</script>
|
|
167
|
+
</body>
|
|
168
|
+
</html>
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
> **Tip:** For production, copy `dist/style.css` to your `public` folder or let your bundler handle the import.
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## CSS-only usage
|
|
176
|
+
|
|
177
|
+
Most of the design system works without JavaScript. Apply utility and component classes directly.
|
|
178
|
+
|
|
179
|
+
### Grid layout
|
|
180
|
+
|
|
181
|
+
```html
|
|
182
|
+
<div class="dga-container">
|
|
183
|
+
<div class="dga-row">
|
|
184
|
+
<div class="dga-col-12 dga-col-md-6 dga-col-lg-4">Column 1</div>
|
|
185
|
+
<div class="dga-col-12 dga-col-md-6 dga-col-lg-4">Column 2</div>
|
|
186
|
+
<div class="dga-col-12 dga-col-md-6 dga-col-lg-4">Column 3</div>
|
|
187
|
+
</div>
|
|
188
|
+
</div>
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Common utility prefixes
|
|
192
|
+
|
|
193
|
+
| Prefix | Examples |
|
|
194
|
+
|--------|----------|
|
|
195
|
+
| Layout | `dga-container`, `dga-row`, `dga-col-*`, `dga-d-flex`, `dga-gap-*` |
|
|
196
|
+
| Width | `dga-w-full`, `dga-w-50`, `dga-max-w-lg`, `dga-w-screen` |
|
|
197
|
+
| Height | `dga-h-full`, `dga-h-100`, `dga-min-h-screen`, `dga-h-4` |
|
|
198
|
+
| Spacing | `dga-p-*`, `dga-m-*`, `dga-py-*`, `dga-px-*` |
|
|
199
|
+
| Colors | `dga-bg-primary-500`, `dga-text-gray-700` |
|
|
200
|
+
| Typography | `dga-text-sm`, `dga-text-xl`, `dga-fw-bold`, `dga-display-md` |
|
|
201
|
+
| Radius | `dga-rounded-md`, `dga-rounded-lg` |
|
|
202
|
+
| Flex direction | `dga-flex-col` / `dga-flex-column`, `dga-flex-row` |
|
|
203
|
+
|
|
204
|
+
### Included CSS components
|
|
205
|
+
|
|
206
|
+
These work with markup and classes only (no JS required):
|
|
207
|
+
|
|
208
|
+
- Buttons — `dga-btn`, `dga-btn-primary`, `dga-btn-neutral`, `dga-btn-subtle`, sizes `dga-btn-sm` / `dga-btn-md` / `dga-btn-lg`
|
|
209
|
+
- Cards — `dga-card`
|
|
210
|
+
- Forms — `dga-input`, `dga-select`, `dga-textarea`, `dga-label`
|
|
211
|
+
- Links & tags — `dga-link`, `dga-tag`
|
|
212
|
+
- Tables — `dga-table`
|
|
213
|
+
- Breadcrumb, divider, avatar
|
|
214
|
+
|
|
215
|
+
For the full documentation index, see **[docs/README.md](./docs/README.md)**.
|
|
216
|
+
|
|
217
|
+
Quick links:
|
|
218
|
+
- [Documentation index](./docs/README.md)
|
|
219
|
+
- [Installation](./docs/getting-started/installation.md)
|
|
220
|
+
- [JavaScript API](./docs/getting-started/javascript-api.md)
|
|
221
|
+
- [Web Components](./docs/getting-started/web-components.md)
|
|
222
|
+
- [Components](./docs/README.md#components)
|
|
223
|
+
- [Grid](./docs/foundations/grid.md) · [Colors](./docs/foundations/colors.md)
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## JavaScript components
|
|
228
|
+
|
|
229
|
+
Import from the main package entry:
|
|
230
|
+
|
|
231
|
+
```js
|
|
232
|
+
import {
|
|
233
|
+
DGAAccordion,
|
|
234
|
+
DGAAlert,
|
|
235
|
+
DGAChart,
|
|
236
|
+
DGACodeSnippet,
|
|
237
|
+
DGAMenuDropDown,
|
|
238
|
+
DGAVerifyBar,
|
|
239
|
+
} from '@waaelg/dga-design-on-sass';
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Importing the package also registers **web components** — prefer these in Vue/React:
|
|
243
|
+
|
|
244
|
+
| Web component | Legacy class |
|
|
245
|
+
|---------------|--------------|
|
|
246
|
+
| `<dga-alert>` | `DGAAlert` |
|
|
247
|
+
| `<dga-accordion>` + `<dga-accordion-item>` | `DGAAccordion` |
|
|
248
|
+
| `<dga-code-snippet>` | `DGACodeSnippet` |
|
|
249
|
+
| `<dga-pie-chart>` | `DGAChart` |
|
|
250
|
+
| `<dga-verify-bar>` | `DGAVerifyBar` |
|
|
251
|
+
|
|
252
|
+
See [Web Components](./docs/getting-started/web-components.md) for framework setup.
|
|
253
|
+
|
|
254
|
+
### DGAAccordion (legacy)
|
|
255
|
+
|
|
256
|
+
Expands and collapses accordion panels. Supports click and keyboard (Enter / Space).
|
|
257
|
+
|
|
258
|
+
```html
|
|
259
|
+
<div class="dga-acc" id="myAccordion">
|
|
260
|
+
<div class="dga-acc-item">
|
|
261
|
+
<button class="dga-acc-header" aria-expanded="false">
|
|
262
|
+
<span>Section title</span>
|
|
263
|
+
</button>
|
|
264
|
+
<div class="dga-acc-content">
|
|
265
|
+
<div class="dga-acc-body">Content goes here.</div>
|
|
266
|
+
</div>
|
|
267
|
+
</div>
|
|
268
|
+
</div>
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
```js
|
|
272
|
+
new DGAAccordion(document.getElementById('myAccordion'));
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
### DGAAlert (legacy)
|
|
276
|
+
|
|
277
|
+
Handles dismiss buttons on alerts. Requires `[data-alert-close]` on the close button.
|
|
278
|
+
|
|
279
|
+
```html
|
|
280
|
+
<div class="dga-alert" data-variant="success-color">
|
|
281
|
+
<span class="dga-alert-icon" aria-hidden="true"></span>
|
|
282
|
+
<div class="dga-alert-content">
|
|
283
|
+
<h4 class="dga-alert-title">Success</h4>
|
|
284
|
+
<div class="dga-alert-body">Operation completed successfully.</div>
|
|
285
|
+
</div>
|
|
286
|
+
<button class="dga-alert-close" type="button" data-alert-close aria-label="Dismiss alert">×</button>
|
|
287
|
+
</div>
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
```js
|
|
291
|
+
new DGAAlert(); // listens on document by default
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
**Variants:** `success-color`, `warning-color`, `destructive-color`, `info-color`, `neutral-color`, `success-white`, `warning-white`, `destructive-white`, `info-white`, `neutral-white`
|
|
295
|
+
|
|
296
|
+
### DGAChart (legacy)
|
|
297
|
+
|
|
298
|
+
Renders a pie chart using a `conic-gradient` background.
|
|
299
|
+
|
|
300
|
+
```html
|
|
301
|
+
<div id="myChart" class="dga-pie-chart" data-hole="false"></div>
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
```js
|
|
305
|
+
new DGAChart(document.getElementById('myChart'), [
|
|
306
|
+
{ label: 'Item 1', from: '0%', to: '40%', color: 'var(--dga-primary-100)' },
|
|
307
|
+
{ label: 'Item 2', from: '40%', to: '100%', color: 'var(--dga-gray-200)' },
|
|
308
|
+
]);
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
Set `data-hole="true"` on the element for a donut-style chart.
|
|
312
|
+
|
|
313
|
+
### DGACodeSnippet (legacy)
|
|
314
|
+
|
|
315
|
+
Enables copy-to-clipboard on code snippet blocks.
|
|
316
|
+
|
|
317
|
+
```js
|
|
318
|
+
new DGACodeSnippet(); // listens on document by default
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
Copy buttons must use `.dga-code-snippet-inline__copy` or `.dga-code-snippet-multiline__copy`.
|
|
322
|
+
|
|
323
|
+
### DGAMenuDropDown
|
|
324
|
+
|
|
325
|
+
Powers the responsive navbar with dropdown menus.
|
|
326
|
+
|
|
327
|
+
```html
|
|
328
|
+
<nav class="dga-navbar" role="navigation">
|
|
329
|
+
<a class="dga-navbar-brand" href="#">Brand</a>
|
|
330
|
+
<ul class="dga-menu">
|
|
331
|
+
<li>
|
|
332
|
+
<a class="dga-menu-item dga-has-dropdown" href="#" role="button" aria-expanded="false" aria-haspopup="true">
|
|
333
|
+
Menu
|
|
334
|
+
</a>
|
|
335
|
+
<div class="dga-dropdown">
|
|
336
|
+
<div class="dga-dropdown-content">
|
|
337
|
+
<ul>
|
|
338
|
+
<li><a href="#">Link</a></li>
|
|
339
|
+
</ul>
|
|
340
|
+
</div>
|
|
341
|
+
</div>
|
|
342
|
+
</li>
|
|
343
|
+
</ul>
|
|
344
|
+
<button class="dga-navbar-toggler" aria-label="Toggle menu"></button>
|
|
345
|
+
</nav>
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
```js
|
|
349
|
+
const menu = new DGAMenuDropDown({
|
|
350
|
+
navbar: document.querySelector('.dga-navbar'),
|
|
351
|
+
});
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
### Web components
|
|
355
|
+
|
|
356
|
+
```html
|
|
357
|
+
<dga-alert variant="success-color" title="Success" dismissible>Message</dga-alert>
|
|
358
|
+
|
|
359
|
+
<dga-accordion>
|
|
360
|
+
<dga-accordion-item title="Question">Answer</dga-accordion-item>
|
|
361
|
+
</dga-accordion>
|
|
362
|
+
|
|
363
|
+
<dga-code-snippet code="npm install @waaelg/dga-design-on-sass"></dga-code-snippet>
|
|
364
|
+
|
|
365
|
+
<dga-pie-chart data='[{"label":"A","from":"0%","to":"100%","color":"primary-100"}]'></dga-pie-chart>
|
|
366
|
+
|
|
367
|
+
<dga-verify-bar domain=".edu.sa"></dga-verify-bar>
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
### DGAVerifyBar (legacy)
|
|
371
|
+
|
|
372
|
+
Controls the Saudi government verification bar (legacy markup with fixed element IDs).
|
|
373
|
+
|
|
374
|
+
Expected IDs: `dga-verify-bar`, `dga-verifyBtn`, `dga-verify-bar_content`.
|
|
375
|
+
|
|
376
|
+
```js
|
|
377
|
+
const verifyBar = new DGAVerifyBar();
|
|
378
|
+
const menu = new DGAMenuDropDown();
|
|
379
|
+
|
|
380
|
+
// Optional: coordinate verify bar and navbar
|
|
381
|
+
verifyBar.menu = menu;
|
|
382
|
+
menu.verifyBar = verifyBar;
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
| `<dga-verify-bar>` attribute | Default | Description |
|
|
386
|
+
|------------------------------|---------|-------------|
|
|
387
|
+
| `domain` | `.edu.sa` | Official domain suffix shown in the verify panel |
|
|
388
|
+
| `registration-number` | `20250105758` | DGA registration number |
|
|
389
|
+
| `registration-link` | DGA Raqmi URL | Link to the platform license page |
|
|
390
|
+
|
|
391
|
+
---
|
|
392
|
+
|
|
393
|
+
## RTL and Arabic
|
|
394
|
+
|
|
395
|
+
The design system targets Arabic government websites. Set `dir="rtl"` and `lang="ar"` on the `<html>` element for correct layout direction. The default font is **IBM Plex Sans Arabic**, loaded automatically with the stylesheet.
|
|
396
|
+
|
|
397
|
+
---
|
|
398
|
+
|
|
399
|
+
## What's included in the npm package
|
|
400
|
+
|
|
401
|
+
Only compiled files are published:
|
|
402
|
+
|
|
403
|
+
```
|
|
404
|
+
node_modules/@waaelg/dga-design-on-sass/
|
|
405
|
+
├── dist/
|
|
406
|
+
│ ├── index.js # JavaScript components
|
|
407
|
+
│ ├── index.js.map
|
|
408
|
+
│ └── style.css # Compiled CSS
|
|
409
|
+
└── package.json
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
SCSS source files are **not** included in the npm package. To customize variables or mixins, clone the [repository](https://github.com/waaelg/personal_fe_dga-sass) and build locally.
|
|
413
|
+
|
|
414
|
+
---
|
|
415
|
+
|
|
416
|
+
## Local development (contributors)
|
|
417
|
+
|
|
418
|
+
```bash
|
|
419
|
+
git clone https://github.com/waaelg/personal_fe_dga-sass.git
|
|
420
|
+
cd personal_fe_dga-sass
|
|
421
|
+
npm install
|
|
422
|
+
npm run dev # demo pages at http://localhost:5173
|
|
423
|
+
npm run build # outputs dist/index.js and dist/style.css
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
Demo pages in the repo:
|
|
427
|
+
|
|
428
|
+
| File | Contents |
|
|
429
|
+
|------|----------|
|
|
430
|
+
| `index.html` | Full component showcase |
|
|
431
|
+
| `alerts.html` | Alert variants |
|
|
432
|
+
| `colors.html` | Color palette |
|
|
433
|
+
| `verify-bar.html` | `<dga-verify-bar>` web component |
|
|
434
|
+
|
|
435
|
+
Documentation:
|
|
436
|
+
|
|
437
|
+
| File | Contents |
|
|
438
|
+
|------|----------|
|
|
439
|
+
| `docs/foundations/grid.md` | Grid, flexbox, layout |
|
|
440
|
+
| `docs/foundations/width-height.md` | Width & height utilities |
|
|
441
|
+
| `docs/foundations/colors.md` | Color tokens and utilities |
|
|
442
|
+
| `docs/foundations/radius.md` | Border radius utilities |
|
|
443
|
+
|
|
444
|
+
---
|
|
445
|
+
|
|
446
|
+
## Troubleshooting
|
|
447
|
+
|
|
448
|
+
**Styles not applied**
|
|
449
|
+
- Confirm `import '@waaelg/dga-design-on-sass/style.css'` runs before your app renders.
|
|
450
|
+
- In plain HTML, verify the `<link>` path points to `dist/style.css`.
|
|
451
|
+
|
|
452
|
+
**Interactive component not working**
|
|
453
|
+
- Check that the required HTML structure and classes match the examples above.
|
|
454
|
+
- Ensure the matching JS class is instantiated after the DOM is ready.
|
|
455
|
+
- For alerts and code snippets, `new DGAAlert()` / `new DGACodeSnippet()` must run once.
|
|
456
|
+
|
|
457
|
+
**Navbar dropdown or verify bar issues**
|
|
458
|
+
- `DGAMenuDropDown` requires a `.dga-navbar` element with `.dga-menu` and `.dga-navbar-toggler`.
|
|
459
|
+
- `DGAVerifyBar` requires the legacy ID-based markup (`#dga-verify-bar`, etc.), or use `<dga-verify-bar>` instead.
|
|
460
|
+
|
|
461
|
+
**Vite: `does not provide an export named 'DGAAlert'`**
|
|
462
|
+
- Stale Vite pre-bundle in `node_modules/.vite/deps/`. Clear it and restart:
|
|
463
|
+
```bash
|
|
464
|
+
rm -rf node_modules/.vite
|
|
465
|
+
npm run dev
|
|
466
|
+
```
|
|
467
|
+
- Or add to `vite.config.js`:
|
|
468
|
+
```js
|
|
469
|
+
export default defineConfig({
|
|
470
|
+
optimizeDeps: {
|
|
471
|
+
exclude: ['@waaelg/dga-design-on-sass'],
|
|
472
|
+
},
|
|
473
|
+
})
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
---
|
|
477
|
+
|
|
478
|
+
## License
|
|
479
|
+
|
|
480
|
+
MIT — Wael Alghamdi
|
package/docs/README.md
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# DGA Design System — Documentation
|
|
2
|
+
|
|
3
|
+
Documentation for **@waaelg/dga-design-on-sass**: Saudi DGA design system utilities, components, and optional JavaScript.
|
|
4
|
+
|
|
5
|
+
**Package:** [npm](https://www.npmjs.com/package/@waaelg/dga-design-on-sass) · **Demo:** run `npm run dev` in the repo root
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Getting Started
|
|
10
|
+
|
|
11
|
+
| Doc | Description |
|
|
12
|
+
|-----|-------------|
|
|
13
|
+
| [Installation](./getting-started/installation.md) | npm, HTML, ASP.NET, Vue, React |
|
|
14
|
+
| [JavaScript API](./getting-started/javascript-api.md) | Interactive component classes |
|
|
15
|
+
| [Web Components](./getting-started/web-components.md) | `<dga-*>` custom elements |
|
|
16
|
+
| [RTL & Arabic](./getting-started/rtl-arabic.md) | Right-to-left setup |
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Foundations
|
|
21
|
+
|
|
22
|
+
| Doc | Description |
|
|
23
|
+
|-----|-------------|
|
|
24
|
+
| [Colors](./foundations/colors.md) | Palettes, semantic colors, utilities |
|
|
25
|
+
| [Colors cheatsheet](./foundations/colors-cheatsheet.md) | Quick class reference |
|
|
26
|
+
| [Color swatches](./foundations/colors-swatches.md) | Hex values per shade |
|
|
27
|
+
| [Typography](./foundations/typography.md) | Display, text sizes, weights |
|
|
28
|
+
| [Spacing](./foundations/spacing.md) | Padding, margin, gap |
|
|
29
|
+
| [Grid & Flex](./foundations/grid.md) | Layout, flexbox, display |
|
|
30
|
+
| [Width & Height](./foundations/width-height.md) | `dga-w-*`, `dga-h-*` |
|
|
31
|
+
| [Border radius](./foundations/radius.md) | Radius utilities |
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Components
|
|
36
|
+
|
|
37
|
+
| Component | Doc | Demo | JS / WC |
|
|
38
|
+
|-----------|-----|------|---------|
|
|
39
|
+
| Button | [button.md](./components/button.md) | `index.html` | No |
|
|
40
|
+
| Alert | [alert.md](./components/alert.md) | `alerts.html` | WC or class |
|
|
41
|
+
| Accordion | [accordion.md](./components/accordion.md) | `index.html` | WC or class |
|
|
42
|
+
| Navbar | [navbar.md](./components/navbar.md) | `index.html` | Yes |
|
|
43
|
+
| Card | [card.md](./components/card.md) | `index.html` | No |
|
|
44
|
+
| Forms | [forms.md](./components/forms.md) | `index.html` | No |
|
|
45
|
+
| Table | [table.md](./components/table.md) | `index.html` | No |
|
|
46
|
+
| Breadcrumb | [breadcrumb.md](./components/breadcrumb.md) | `index.html` | No |
|
|
47
|
+
| Link | [link.md](./components/link.md) | `index.html` | No |
|
|
48
|
+
| Tag | [tag.md](./components/tag.md) | `index.html` | No |
|
|
49
|
+
| Divider | [divider.md](./components/divider.md) | `index.html` | No |
|
|
50
|
+
| Code snippet | [code-snippet.md](./components/code-snippet.md) | `index.html` | WC or class |
|
|
51
|
+
| Pie chart | [chart.md](./components/chart.md) | `index.html` | WC or class |
|
|
52
|
+
| Verify bar | [verify-bar.md](./components/verify-bar.md) | `verify-bar.html` | WC or class |
|
|
53
|
+
| Avatar | [avatar.md](./components/avatar.md) | — | No |
|
|
54
|
+
|
|
55
|
+
**WC** = web component (`<dga-*>`) registered on package import.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Changelog
|
|
60
|
+
|
|
61
|
+
See [changelog.md](./changelog.md).
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Doc conventions
|
|
66
|
+
|
|
67
|
+
Every component page includes:
|
|
68
|
+
|
|
69
|
+
1. Overview
|
|
70
|
+
2. HTML structure
|
|
71
|
+
3. Classes and variants (from source SCSS)
|
|
72
|
+
4. Copy-paste examples (from demo HTML)
|
|
73
|
+
5. JavaScript setup (if needed)
|
|
74
|
+
6. Accessibility notes
|
|
75
|
+
|
|
76
|
+
Class names are verified against `dist/style.css` after `npm run build`.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to **@waaelg/dga-design-on-sass**.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## [0.4.0] — 2026-06-29
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
- Web components: `<dga-alert>`, `<dga-accordion>`, `<dga-code-snippet>`, `<dga-pie-chart>`
|
|
11
|
+
- [Web Components guide](./getting-started/web-components.md)
|
|
12
|
+
- Full documentation under `docs/`:
|
|
13
|
+
- Getting started (installation, JS API, RTL, web components)
|
|
14
|
+
- Foundations (`colors`, `grid`, `width-height`, `radius`, typography, spacing)
|
|
15
|
+
- All 15 component docs
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
- Legacy JS classes share utilities with web components (`src/scripts/shared/`)
|
|
19
|
+
- Foundation docs moved to `docs/foundations/` with npm quick-start sections
|
|
20
|
+
- Alert, accordion, code snippet, and chart docs: legacy + web component options
|
|
21
|
+
- JavaScript API and README: web component registration and usage
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## [0.3.9]
|
|
26
|
+
|
|
27
|
+
### Added
|
|
28
|
+
- Height utilities (`dga-h-*`, `dga-max-h-*`, `dga-min-h-*`)
|
|
29
|
+
- Flex direction aliases: `dga-flex-column`, `dga-flex-column-reverse`
|
|
30
|
+
- Avatar component in build (`components/avatar`)
|
|
31
|
+
- Initial documentation under `docs/`
|
|
32
|
+
|
|
33
|
+
### Changed
|
|
34
|
+
- Grid documentation: width/height section, justify-content table
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## [0.3.8]
|
|
39
|
+
|
|
40
|
+
- Published npm package with compiled `dist/`
|
|
41
|
+
- Grid, color, radius utilities
|
|
42
|
+
- Components: button, alert, accordion, navbar, card, forms, table, verify bar, code snippet, chart
|
|
43
|
+
- JavaScript exports: `DGAAccordion`, `DGAAlert`, `DGAChart`, `DGACodeSnippet`, `DGAMenuDropDown`, `DGAVerifyBar`
|
|
44
|
+
- `<dga-verify-bar>` web component
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Versioning
|
|
49
|
+
|
|
50
|
+
This project uses [Semantic Versioning](https://semver.org/):
|
|
51
|
+
|
|
52
|
+
- **Patch** — bug fixes, doc updates, new utility classes
|
|
53
|
+
- **Minor** — new components or features (backward compatible)
|
|
54
|
+
- **Major** — breaking class renames or API changes
|