@waaelg/dga-design-system 0.4.7 → 0.4.9

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