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

#المتطلبات

يستهدف 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 بإحدى ثلاث صيغ. يملأ اسم اللوحة أو اللون درجات --ddga-brand-* الاثنتي عشرة كلها، مما يجعل الأزرار وحلقات التركيز والدرجات الفاتحة والوضع الداكن تتبعه.

1. 1

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

   إحدى اللوحات: saGreen أو info أو success أو warning أو error أو gray أو gold أو lavender.

2. 2

   أي لون CSS

   يصبح لون hex أو rgb() أو oklch() الدرجة 600، وتمزج منه الدرجات الإحدى عشرة الأخرى مع الأبيض أو الأسود في oklab. ويقرأ الوضع الداكن الدرجة 400.

3. 3

   ثلاثية صريحة

   تضبط { base, hover, active, foreground } أدوار اللون الرئيس بقيم محددة في الوضعين. يبقى سلم العلامة والدرجات الفاتحة المبنية عليه بالأخضر السعودي.

// 1 - a built-in palette name<DgaProvider theme={{ primary: 'info' }}>…</DgaProvider>// 2 - any CSS color: becomes brand step 600<DgaProvider theme={{ primary: '#7C3AED' }}>…</DgaProvider>// 3 - a triplet: exact primary role values<DgaProvider  theme={{    primary: {      base: '#1B8354',      hover: '#166A45',      active: '#104631',      foreground: '#FFFFFF',    },  }}>  …</DgaProvider>

لوصفة CSS وحدها، وقاعدة التباين للنص على اللون الرئيس، وملاحظات الترقية من 1.5، اقرأ دليل تخصيص السمة. ولتجربة لون ونسخ CSS، افتح منسق السمة.

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

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

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

/* globals.css: after '@dev-dga/css', outside any @layer */:root {  --ddga-radius-md: 4px; /* one token: squarer corners, system-wide */}/* Brand color: set the 12 --ddga-brand-* steps, not --ddga-color-primary.   Copy the brand-ramp block from /theming#one-block. */.compact {  --ddga-card-padding: var(--ddga-space-3);  --ddga-radius-lg: 6px;}

لا يكفي تجاوز ⁦--ddga-color-primary⁩ وحده لتغيير لون العلامة، لأن الدرجات الفاتحة وحلقات التركيز تقرأ درجات ⁦--ddga-brand-*⁩ وتبقى بالأخضر السعودي. ويفقد الوضع الداكن أيضاً درجته الأفتح للون الرئيس. املأ الدرجات الاثنتي عشرة من لون واحد عبر كتلة سلم العلامة في دليل تخصيص السمة.

احصر التجاوزات في شجرة فرعية بضبط المتغيرات على أي عنصر مغلف، ويتكفل التتالي بالباقي في الوضعين الفاتح والداكن. الاستثناء هو درجات العلامة: اضبطها على عنصر يحمل ⁦data-theme⁩، لأن أدوار اللون الرئيس تحسب عليه.

#باني السمة

لمحة سريعة: عدّل بعض الرموز وشاهد المعاينة تتبدل. للتحكم في الرموز كلها (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>

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

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