@waaelg/dga-design-system 0.4.2

package/docs/foundations/spacing.md

@@ -0,0 +1,134 @@
+# Spacing
+
+Padding, margin, and gap utilities. Base unit: **4px** (`1` = 4px).
+
+**Source:**
+- `src/styles/utilities/padding.scss`
+- `src/styles/utilities/margin.scss`
+- Grid gap utilities in `src/styles/utilities/grid.scss`
+
+---
+
+## Numeric scale
+
+| Class key | Value |
+|-----------|-------|
+| `0` | 0 |
+| `1` | 4px |
+| `2` | 8px |
+| `3` | 12px |
+| `4` | 16px |
+| `6` | 24px |
+| `8` | 32px |
+| `12` | 48px |
+| `16` | 64px |
+| `24` | 96px |
+
+Full scale: `0`, `px`, `0_5`, `1` … `480` (see `src/styles/variables/spacing.scss`).
+
+---
+
+## Padding
+
+| Pattern | Example | CSS |
+|---------|---------|-----|
+| All sides | `dga-p-4` | `padding: 16px` |
+| Top | `dga-pt-4` | `padding-top` |
+| Bottom | `dga-pb-4` | `padding-bottom` |
+| Left | `dga-pl-4` | `padding-left` |
+| Right | `dga-pr-4` | `padding-right` |
+| Horizontal | `dga-px-4` | left + right |
+| Vertical | `dga-py-4` | top + bottom |
+
+```html
+<div class="dga-p-4 dga-px-6">Padded box</div>
+```
+
+---
+
+## Margin
+
+Same pattern with `m` prefix:
+
+| Pattern | Example |
+|---------|---------|
+| All sides | `dga-m-4` |
+| Top | `dga-mt-4` |
+| Bottom | `dga-mb-4` |
+| Horizontal | `dga-mx-4` |
+| Vertical | `dga-my-4` |
+| Auto center | `dga-mx-auto` |
+
+```html
+<section class="dga-my-8 dga-mb-4">Section</section>
+```
+
+---
+
+## Named spacing
+
+Semantic names from the DGA scale:
+
+| Name | Size |
+|------|------|
+| `xxs` | 2px |
+| `xs` | 4px |
+| `sm` | 6px |
+| `md` | 8px |
+| `lg` | 12px |
+| `xl` | 16px |
+| `2xl` | 20px |
+| `3xl` | 24px |
+| `4xl` | 32px |
+| … | up to `11xl` (160px) |
+
+```html
+<div class="dga-p-lg dga-mb-xl">Named spacing</div>
+```
+
+---
+
+## Gap (flex & grid)
+
+Prefer gap over margin for spacing between flex children:
+
+| Class | Description |
+|-------|-------------|
+| `dga-gap-4` | 16px all directions |
+| `dga-gap-x-4` | Horizontal gap |
+| `dga-gap-y-4` | Vertical gap |
+| `dga-gap-md` | Named gap (8px) |
+| `dga-gap-lg` | Named gap (12px) |
+
+```html
+<div class="dga-d-flex dga-flex-col dga-gap-3">
+  <button class="dga-btn dga-btn-primary">زر 1</button>
+  <button class="dga-btn dga-btn-neutral">زر 2</button>
+</div>
+```
+
+See [Grid — Spacing & Gaps](./grid.md#spacing--gaps).
+
+---
+
+## Examples
+
+```html
+<!-- Card padding -->
+<div class="dga-card dga-p-4">
+  <h3 class="dga-mb-2">Title</h3>
+  <p class="dga-mb-0">Content</p>
+</div>
+
+<!-- Section spacing -->
+<div class="dga-container dga-py-8">
+  <div class="dga-row dga-gap-4">...</div>
+</div>
+```
+
+---
+
+## Related
+
+- [Grid](./grid.md)
+- [Width & Height](./width-height.md)

package/docs/foundations/typography.md

@@ -0,0 +1,111 @@
+# Typography
+
+Font utilities for the DGA design system. Default font: **IBM Plex Sans Arabic**.
+
+**Source:** `src/styles/utilities/typography.scss`
+
+---
+
+## Display sizes
+
+For headings and hero text. Responsive sizes apply below 768px and 375px.
+
+| Class | Desktop size | Line height |
+|-------|--------------|-------------|
+| `dga-display-2xl` | 72px | 90px |
+| `dga-display-xl` | 60px | 72px |
+| `dga-display-lg` | 48px | 60px |
+| `dga-display-md` | 36px | 44px |
+| `dga-display-sm` | 30px | 38px |
+| `dga-display-xs` | 24px | 32px |
+
+```html
+<h1 class="dga-display-md dga-fw-bold">عنوان الصفحة</h1>
+```
+
+---
+
+## Text sizes
+
+| Class | Size | Line height |
+|-------|------|-------------|
+| `dga-text-xl` | 20px | 30px |
+| `dga-text-lg` | 18px | 28px |
+| `dga-text-md` | 16px | 24px |
+| `dga-text-sm` | 14px | 20px |
+| `dga-text-xs` | 12px | 18px |
+| `dga-text-2xs` | 10px | 14px |
+
+```html
+<p class="dga-text-md">نص أساسي</p>
+<p class="dga-text-sm dga-text-gray-600">نص ثانوي</p>
+```
+
+---
+
+## Font weight
+
+| Class | Weight |
+|-------|--------|
+| `dga-fw-regular` | 400 |
+| `dga-fw-medium` | 500 |
+| `dga-fw-semibold` | 600 |
+| `dga-fw-bold` | 700 |
+
+```html
+<h2 class="dga-text-xl dga-fw-bold">عنوان فرعي</h2>
+```
+
+---
+
+## Text alignment
+
+| Class | Effect |
+|-------|--------|
+| `dga-text-start` | Logical start (right in RTL) |
+| `dga-text-end` | Logical end (left in RTL) |
+| `dga-text-center` | Center |
+| `dga-text-left` | Physical left |
+| `dga-text-right` | Physical right |
+
+**Responsive:** `dga-text-md-center`, `dga-text-sm-start`, etc.
+
+Prefer `start` / `end` for RTL. See [RTL & Arabic](../getting-started/rtl-arabic.md).
+
+---
+
+## Text colors
+
+Combine with color utilities:
+
+```html
+<p class="dga-text-primary-500">نص بلون العلامة</p>
+<p class="dga-text-gray-700">نص محايد</p>
+```
+
+See [Colors](./colors.md).
+
+---
+
+## Common patterns
+
+```html
+<!-- Page title -->
+<h1 class="dga-display-md dga-fw-bold dga-text-gray-950">لوحة التحكم</h1>
+
+<!-- Section heading -->
+<h2 class="dga-text-xl dga-fw-semibold">الإعدادات</h2>
+
+<!-- Body -->
+<p class="dga-text-md dga-text-gray-700">وصف القسم هنا.</p>
+
+<!-- Caption -->
+<span class="dga-text-xs dga-text-gray-500">آخر تحديث: اليوم</span>
+```
+
+---
+
+## Related
+
+- [Colors](./colors.md)
+- [RTL & Arabic](../getting-started/rtl-arabic.md)

package/docs/foundations/width-height.md

@@ -0,0 +1,305 @@
+# Width & Height
+
+Fixed, percentage, and viewport sizing utilities (`dga-w-*`, `dga-h-*`).
+
+**Source:** `src/styles/utilities/width.scss`, `src/styles/utilities/height.scss`
+
+---
+
+## Quick start (npm)
+
+```js
+import '@waaelg/dga-design-on-sass/style.css'
+```
+
+```html
+<div class="dga-w-full dga-h-screen dga-d-flex dga-flex-column">
+  <header class="dga-h-16">Header</header>
+  <main class="dga-flex-1 dga-min-h-0">Content</main>
+</div>
+```
+
+Common classes: `dga-w-full`, `dga-w-50`, `dga-h-full`, `dga-h-screen`, `dga-min-h-screen`, `dga-max-w-lg`.
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Quick Reference](#quick-reference)
+3. [Width Utilities](#width-utilities)
+4. [Height Utilities](#height-utilities)
+5. [Named Sizes](#named-sizes)
+6. [Spacing Scale](#spacing-scale)
+7. [Percentage & Fractions](#percentage--fractions)
+8. [Max & Min Variants](#max--min-variants)
+9. [Examples](#examples)
+10. [SCSS Source (Contributors)](#scss-source-contributors)
+11. [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+Width and height utilities follow the same naming pattern:
+
+| Pattern | Width | Height |
+|---------|-------|--------|
+| Fixed / named | `dga-w-{size}` | `dga-h-{size}` |
+| Max | `dga-max-w-{size}` | `dga-max-h-{size}` |
+| Min | `dga-min-w-{size}` | `dga-min-h-{size}` |
+
+**Source files:**
+
+- `src/styles/utilities/width.scss`
+- `src/styles/utilities/height.scss`
+- `src/styles/variables/spacing.scss` — shared size tokens (`$dga-widths`, `$dga-heights`)
+
+---
+
+## Quick Reference
+
+| Goal | Class |
+|------|-------|
+| Full width of parent | `dga-w-full` or `dga-w-100` |
+| Full height of parent | `dga-h-full` or `dga-h-100` |
+| Full viewport width | `dga-w-screen` |
+| Full viewport height | `dga-h-screen` or `dga-min-h-screen` |
+| Half width / height | `dga-w-1-2` / `dga-h-1-2` |
+| Auto size | `dga-w-auto` / `dga-h-auto` |
+| 16px height (spacing scale) | `dga-h-4` |
+| 640px height (named `lg`) | `dga-h-lg` |
+
+---
+
+## Width Utilities
+
+### Utility values
+
+| Class | CSS |
+|-------|-----|
+| `dga-w-auto` | `width: auto` |
+| `dga-w-full` | `width: 100%` |
+| `dga-w-screen` | `width: 100vw` |
+| `dga-w-min` | `width: min-content` |
+| `dga-w-max` | `width: max-content` |
+| `dga-w-fit` | `width: fit-content` |
+
+```html
+<div class="dga-w-full">Spans parent width</div>
+<div class="dga-w-screen">Spans viewport width</div>
+<div class="dga-w-fit">Shrinks to content</div>
+```
+
+---
+
+## Height Utilities
+
+### Utility values
+
+| Class | CSS |
+|-------|-----|
+| `dga-h-auto` | `height: auto` |
+| `dga-h-full` | `height: 100%` |
+| `dga-h-screen` | `height: 100vh` |
+| `dga-h-min` | `height: min-content` |
+| `dga-h-max` | `height: max-content` |
+| `dga-h-fit` | `height: fit-content` |
+
+```html
+<!-- Fill parent height (parent must have a defined height) -->
+<div class="dga-h-full">Full height</div>
+
+<!-- Full viewport height -->
+<section class="dga-min-h-screen">Hero section</section>
+```
+
+> **Note:** `dga-w-screen` uses `100vw` while `dga-h-screen` uses `100vh`.
+
+---
+
+## Named Sizes
+
+Both width and height share the same named breakpoint scale:
+
+| Class suffix | Size |
+|--------------|------|
+| `xxs` | 320px |
+| `xs` | 384px |
+| `sm` | 480px |
+| `md` | 560px |
+| `lg` | 640px |
+| `xl` | 768px |
+| `2xl` | 1024px |
+| `3xl` | 1280px |
+| `4xl` | 1440px |
+| `5xl` | 1600px |
+| `6xl` | 1920px |
+
+```html
+<div class="dga-w-md dga-h-lg">560px wide, 640px tall</div>
+<img class="dga-w-sm dga-h-sm" src="thumb.jpg" alt="">
+```
+
+---
+
+## Spacing Scale
+
+Use numeric keys from the 4px spacing scale (`1` = 4px, `4` = 16px, `8` = 32px, etc.):
+
+```html
+<div class="dga-w-16">64px wide</div>
+<div class="dga-h-10">40px tall</div>
+<div class="dga-w-96">384px wide</div>
+```
+
+Common spacing keys: `0`, `px`, `0_5`, `1`, `2`, `3`, `4`, `5`, `6`, `8`, `10`, `12`, `16`, `20`, `24`, `32`, `48`, `64`, `96`, `120`, … `480`.
+
+---
+
+## Percentage & Fractions
+
+| Class | Value |
+|-------|-------|
+| `dga-w-0` / `dga-h-0` | 0% |
+| `dga-w-25` / `dga-h-25` | 25% |
+| `dga-w-50` / `dga-h-50` | 50% |
+| `dga-w-75` / `dga-h-75` | 75% |
+| `dga-w-100` / `dga-h-100` | 100% |
+| `dga-w-1-2` / `dga-h-1-2` | 50% |
+| `dga-w-1-3` / `dga-h-1-3` | 33.333% |
+| `dga-w-2-3` / `dga-h-2-3` | 66.667% |
+| `dga-w-1-4` / `dga-h-1-4` | 25% |
+| `dga-w-3-4` / `dga-h-3-4` | 75% |
+| `dga-w-1-12` … `dga-w-12-12` | 12-column fractions |
+
+```html
+<div class="dga-row">
+  <div class="dga-h-1-2 dga-w-1-2">Half width and height</div>
+</div>
+```
+
+---
+
+## Max & Min Variants
+
+Same value sets apply to `max-*` and `min-*` prefixes:
+
+```html
+<!-- Cap width, allow content to shrink -->
+<div class="dga-max-w-3xl dga-w-full">Responsive capped content</div>
+
+<!-- At least viewport tall -->
+<main class="dga-min-h-screen">Page body</main>
+
+<!-- Fixed max height with scroll -->
+<div class="dga-max-h-lg dga-overflow-auto">Scrollable panel</div>
+
+<!-- Prevent shrinking below content -->
+<div class="dga-min-w-min">Won't clip text</div>
+```
+
+---
+
+## Examples
+
+### Full-height page layout
+
+```html
+<body class="dga-d-flex dga-flex-col dga-min-h-screen">
+  <header>Header</header>
+  <main class="dga-flex-grow-1">Content</main>
+  <footer>Footer</footer>
+</body>
+```
+
+### Centered hero (no inline height)
+
+```html
+<section class="dga-d-flex dga-align-items-center dga-justify-content-center dga-min-h-screen">
+  <div class="dga-container">
+    <h1>Welcome</h1>
+    <p>Your tagline here</p>
+  </div>
+</section>
+```
+
+### Card with fixed image area
+
+```html
+<div class="dga-card">
+  <div class="dga-w-full dga-h-48 dga-bg-gray-100"></div>
+  <div class="dga-p-4">
+    <h3>Card title</h3>
+    <p>Card body</p>
+  </div>
+</div>
+```
+
+### Sidebar + content
+
+```html
+<div class="dga-d-flex dga-min-h-screen">
+  <aside class="dga-w-64 dga-h-full">Sidebar</aside>
+  <main class="dga-flex-grow-1 dga-w-full">Main</main>
+</div>
+```
+
+---
+
+## SCSS Source (Contributors)
+
+```scss
+@import 'utilities/width';
+@import 'utilities/height';
+
+@include generate-all-width-utilities();
+@include generate-all-height-utilities();
+```
+
+Height tokens reuse the width scale with one override:
+
+```scss
+$dga-heights: map.merge(
+  $dga-widths,
+  (
+    "screen": 100vh,
+  )
+);
+```
+
+---
+
+## Troubleshooting
+
+### `dga-h-full` has no effect
+
+**Cause:** Parent has no explicit height.
+
+**Fix:** Set height on the parent chain, or use `dga-min-h-screen` / `dga-h-screen` on a top-level wrapper.
+
+```html
+<!-- Parent needs height -->
+<div class="dga-min-h-screen">
+  <div class="dga-h-full">Now fills parent</div>
+</div>
+```
+
+### `dga-h-screen` causes scrollbars
+
+**Cause:** `100vh` includes space under mobile browser chrome, or padding/margin adds overflow.
+
+**Fix:** Use `dga-min-h-screen` instead of `dga-h-screen`, or combine with flex layout.
+
+### Width works but height utility missing
+
+**Cause:** Older published package before height utilities were added.
+
+**Fix:** Update `@waaelg/dga-design-on-sass` to the latest version and rebuild.
+
+---
+
+## Related Documentation
+
+- [Grid & Flex](./grid.md) — layout, flexbox, containers
+- [README](../README.md) — npm install and usage

package/docs/getting-started/installation.md

@@ -0,0 +1,158 @@
+# Installation
+
+## npm
+
+```bash
+npm install @waaelg/dga-design-on-sass
+```
+
+## Package exports
+
+| Import | Purpose |
+|--------|---------|
+| `@waaelg/dga-design-on-sass/style.css` | All compiled styles |
+| `@waaelg/dga-design-on-sass` | JavaScript classes + `<dga-*>` web components |
+
+Importing the main entry registers web components automatically. See [Web Components](./web-components.md).
+
+---
+
+## Plain HTML & server-rendered pages
+
+Works with static HTML, **ASP.NET Core `.cshtml`**, PHP, etc. Load CSS + JS once, then use `<dga-*>` tags in markup.
+
+```html
+<!DOCTYPE html>
+<html lang="ar" dir="rtl">
+<head>
+  <link rel="stylesheet" href="./node_modules/@waaelg/dga-design-on-sass/dist/style.css" />
+</head>
+<body>
+  <dga-alert variant="success-color" title="نجاح" dismissible>
+    تمت العملية بنجاح
+  </dga-alert>
+
+  <script type="module">
+    import './node_modules/@waaelg/dga-design-on-sass/dist/index.js'
+  </script>
+</body>
+</html>
+```
+
+See [Web Components](./web-components.md) for ASP.NET layout setup and more examples.
+
+---
+
+## ASP.NET Core (Razor)
+
+In `_Layout.cshtml`, reference the built files from `wwwroot`:
+
+```html
+<link rel="stylesheet" href="~/lib/dga/style.css" />
+<script type="module" src="~/lib/dga/index.js"></script>
+```
+
+In any view:
+
+```html
+<dga-verify-bar domain=".gov.sa"></dga-verify-bar>
+```
+
+---
+
+## Vite / Vue
+
+**`main.js`** — import CSS and register web components:
+
+```js
+import { createApp } from 'vue'
+import '@waaelg/dga-design-on-sass/style.css'
+import '@waaelg/dga-design-on-sass'
+import App from './App.vue'
+
+createApp(App).mount('#app')
+```
+
+**`App.vue`** — use `<dga-alert>` etc. (no `new DGAAlert()` needed):
+
+```vue
+<template>
+  <dga-alert variant="success-color" title="نجاح" dismissible>
+    تمت العملية بنجاح
+  </dga-alert>
+</template>
+```
+
+**`vite.config.js`** — avoid stale dependency cache:
+
+```js
+export default defineConfig({
+  optimizeDeps: {
+    exclude: ['@waaelg/dga-design-on-sass'],
+  },
+})
+```
+
+---
+
+## React
+
+```jsx
+// main.jsx
+import '@waaelg/dga-design-on-sass/style.css'
+import '@waaelg/dga-design-on-sass'
+```
+
+```jsx
+export function App() {
+  return (
+    <>
+      <dga-alert variant="success-color" title="Success" dismissible>
+        Operation completed.
+      </dga-alert>
+      <button className="dga-btn dga-btn-primary">زر</button>
+    </>
+  )
+}
+```
+
+For legacy HTML markup, use `useEffect` with `new DGAAlert()` instead. See [Web Components](./web-components.md).
+
+---
+
+## Next.js
+
+```tsx
+// app/layout.tsx
+import '@waaelg/dga-design-on-sass/style.css'
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="ar" dir="rtl">
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+---
+
+## What gets published
+
+Only `dist/` is on npm:
+
+```
+dist/index.js    → JS components
+dist/style.css   → compiled CSS
+```
+
+SCSS source is not included. Clone the [GitHub repo](https://github.com/waaelg/personal_fe_dga-sass) to customize variables.
+
+---
+
+## Related
+
+- [Web Components](./web-components.md)
+- [JavaScript API](./javascript-api.md)
+- [RTL & Arabic](./rtl-arabic.md)
+- [Components index](../README.md#components)