ثبّت، وغلّف تطبيقك، وتحكّم بكل رمز تصميمي.

#المتطلّبات

يستهدف dev-dga إصدارات React الحديثة وأي أداة بناء تستطيع استيراد ملف CSS.

#ثبّت الحزم

ثلاث حزم: مكوّنات React، وملف CSS المُجمَّع، والرموز التصميمية. ثبّتها الثلاث معًا.

npm i @dev-dga/react @dev-dga/css @dev-dga/tokens

#استورد الأنماط مرة واحدة

استورد ملف الأنماط مرة واحدة في جذر التطبيق (في التخطيط الجذري أو ملف الدخول). يشحن التصفير والرموز والسمة الداكنة وكل أنماط المكوّنات.

// app/layout.tsx (Next.js) or your entry fileimport '@dev-dga/css';

لأن نظام التصميم يعيش في @layer ddga-base / ddga-components، فأي قاعدة غير مُطبَّقة في طبقة عندك تتجاوزه دون الحاجة إلى !important .

#التنسيق مع Tailwind أو بدونه

حزمة @dev-dga/css ملف CSS عادي في طبقتين متتاليتين: ddga-base و ddga-components. و Tailwind اختياري. استخدم خصائص المكوّن لما بداخله، والأصناف أو CSS الخاص بك للتخطيط من حوله. إعادة تنسيق داخل المكوّن بأصناف Tailwind هشّة: ترتيب الطبقات، وليس التخصيص، هو ما يحدّد القاعدة الغالبة.

يحصل إصدارا Tailwind الثالث والرابع على سلّم DGA كأصناف عبر جسر الرموز: bg-primary و text-ink و text-ink-secondary و rounded-lg و shadow-md و text-display-md و max-w-dga وكل درجة في اللوحة (bg-sa-600 و border-gray-200). كل قيمة إحالة إلى var(--ddga-*)، فتسري سمات DgaProvider والوضع الداكن عبر الأصناف.

import '@dev-dga/css';import { DgaProvider, Button } from '@dev-dga/react';

npm install @dev-dga/tokens

// tailwind.config.jsimport { dgaPreset } from '@dev-dga/tokens/tailwind-preset';export default { presets: [dgaPreset], content: ['./src/**/*.{ts,tsx}'] };

/* app.css */@layer tailwind-base, ddga-base, ddga-components, tailwind-utilities;@import '@dev-dga/css';@layer tailwind-base {  @tailwind base;}@layer tailwind-utilities {  @tailwind components;  @tailwind utilities;}

/* app.css */@layer theme, base, ddga-base, ddga-components, components, utilities;@import 'tailwindcss/theme.css' layer(theme);@import 'tailwindcss/utilities.css' layer(utilities);@import '@dev-dga/css';@import '@dev-dga/css/tailwind.css';

@import 'tailwindcss/preflight.css' layer(base);

@import '@dev-dga/css';@theme inline {  --color-*: initial;  --color-white: #fff;}@import '@dev-dga/css/tailwind.css';

قواعد للإصدارين

• الخصائص تنسّق داخل المكوّن. والأصناف أو CSS الخاص بك تنسّق التخطيط من حوله.
• دالة cn() في @dev-dga/react هي clsx فقط. للأصناف المتعارضة المتراكمة على عناصرك، استخدم tailwind-merge من جهتك.
• يتبع dark: السمة [data-theme="dark"] من DgaProvider، وليس تفضيل نظام التشغيل.
• في Tailwind v3: يجب أن يسبق بيان ترتيب @layer الاستيراد @import '@dev-dga/css'، وأن يكون @tailwind base داخل @layer tailwind-base. فـ preflight خارج أي طبقة يزيل حدود كل مكوّن.
• في Tailwind v4: يجب أن يسبق الوضع الصارم (--color-*: initial) استيراد الجسر.
• يتخطّى Tailwind v3 مُعدِّلات الشفافية مثل bg-primary/50 على ألوان var().
• يتجاوز الجسر بعض افتراضات Tailwind عمدًا: rounded-lg يساوي 16px و rounded-xl يساوي 24px، و shadow-* سلّم DGA الكحلي، و gray-* سلّم DGA الرمادي، و text-xs إلى text-xl تحمل ارتفاعات أسطر DGA، و max-w-xs إلى max-w-6xl عروض DGA.
• المسافات ونقاط التوقّف تساوي افتراضات Tailwind، فلا يربط الجسر أيًّا منها.

<article className="bg-card text-ink border border-border rounded-lg shadow-md p-6 max-w-paragraph">  <div className="flex flex-wrap items-center gap-2">    <span className="bg-primary text-primary-foreground rounded-full px-3 py-1 text-xs font-medium">      Utilities only    </span>    <span className="text-ink-tertiary text-xs dark:hidden">light mode</span>    <span className="text-ink-tertiary text-xs hidden dark:inline">dark: active</span>  </div>  <h3 className="text-display-sm font-semibold mt-5">Commercial registration</h3>  <p className="text-ink-secondary mt-2">    Register a new establishment, update its activities, or renew its record.  </p>  <dl className="grid grid-cols-1 sm:grid-cols-3 gap-3 mt-5">    <div className="bg-muted rounded-md p-3">      <dt className="text-ink-tertiary text-2xs">Fee</dt>      <dd className="text-ink text-sm font-medium">SAR 200</dd>    </div>    <div className="bg-muted rounded-md p-3">      <dt className="text-ink-tertiary text-2xs">Duration</dt>      <dd className="text-ink text-sm font-medium">3 working days</dd>    </div>    <div className="bg-muted rounded-md p-3">      <dt className="text-ink-tertiary text-2xs">Channel</dt>      <dd className="text-ink text-sm font-medium">Online</dd>    </div>  </dl>  <div className="border-t border-border mt-5 pt-4">    <a      href="#"      className="text-primary hover:text-primary-hover text-sm font-medium underline-offset-4 hover:underline"    >      Start the service    </a>  </div></article>

#ضَع تطبيقك داخل المزوّد

يوفّر DgaProvider الاتجاه والوضع الداكن وسمة العلامة وجذر الإرساء الذي تُرسى فيه الطبقات المنبثقة (الحوارات والتلميحات والإشعارات). ضَعه مرة واحدة قرب الجذر فوق كل ما يستخدم المكتبة.

import { DgaProvider } from '@dev-dga/react';import '@dev-dga/css';export default function App({ children }) {  return (    <DgaProvider dir="rtl" mode="light" theme={{ primary: 'saGreen' }}>      {children}    </DgaProvider>  );}

خصائص DgaProvider

#نسّق اللون الرئيس

يتبدّل النظام بأكمله من قيمة واحدة. مرّر theme.primary بأيٍّ من ثلاث صيغ - وتُشتقّ حالات التمرير والضغط تلقائيًا عبر color-mix().

1. 1

   اسم لوحة جاهزة

   إحدى: saGreen أو info أو success أو warning أو error أو gray.

2. 2

   أي لون CSS

   قيمة hex أو rgb أو oklch. وتُشتقّ حالتا التمرير والضغط نيابةً عنك.

3. 3

   ثلاثية صريحة

   تحكّم كامل عبر { base, hover, active, foreground } حين تحتاج قيمًا محدّدة.

// 1 - a built-in palette name<DgaProvider theme={{ primary: 'info' }}>…</DgaProvider><DgaProvider theme={{ primary: '#7C3AED' }}>…</DgaProvider><DgaProvider  theme={{    primary: {      base: '#1B8354',      hover: '#166A45',      active: '#104631',      foreground: '#FFFFFF',    },  }}>  …</DgaProvider>

#تجاوز أي رمز تصميمي

كل لون واستدارة ومسافة وخط وظل هو متغيّر CSS باسم --ddga-* مُعرَّف في @layer ddga-base. أعِد تعريف أيٍّ منها في أي مكان - عامًّا على :root أو محصورًا في شجرة فرعية - فيتبعه النظام. دون خطوة بناء ودون Sass.

مجموعات الرموز

/* your globals.css - imported AFTER '@dev-dga/css' */:root {  --ddga-radius-md: 4px;          /* squarer corners, system-wide */  --ddga-color-primary: #0f766e;  /* teal brand */  --ddga-font-ar: 'Cairo', sans-serif;}.compact {  --ddga-card-padding: var(--ddga-space-3);  --ddga-radius-lg: 6px;}

احصر التجاوزات في شجرة فرعية بضبط المتغيّرات على أي عنصر مُغلِّف - ويتكفّل التتالي بالباقي، في الوضعين الفاتح والداكن.

#باني السمة

لمحة سريعة - عدّل بعض الرموز وشاهد المعاينة تتبدّل. للتحكّم الكامل بكل الرموز الـ188، افتح منسّق السمة الكامل.

@import '@dev-dga/css'; /* the DGA design system (index.css) - load it first */:root {  /* غيّر أي عنصر تحكّم أدناه لتوليد تجاوزات الرموز */}

#الوضع الداكن

الوضع الداكن مجموعة رموز مُنتقاة بعناية، لا عكسٌ آليّ. فعِّله بخاصية mode في المزوّد، أو بتبديل data-theme="dark" على عنصر مُغلِّف. طبّقه قبل أول رسم (كما يفعل هذا الموقع) لتفادي الوميض.

// Controlled by the provider<DgaProvider mode="dark">…</DgaProvider><div data-theme="dark"></div>

#العربية والاتجاه

اضبط dir="rtl" فينعكس التخطيط بالكامل عبر الخصائص المنطقية - دون عملٍ لكل مكوّن. ويغطّي خط IBM Plex Sans Arabic العربية واللاتينية من عائلة واحدة، فيبقى المحتوى المختلط متّسقًا.

<DgaProvider dir="rtl" locale="ar"></DgaProvider>

#الخطوات التالية

اكتمل إعدادك. إلى أين تذهب من هنا: