الرموز
الألوان
نظام لوني كامل من طبقتين: مدرجات أساسية خام، وطبقة دلالية قائمة على الأدوار تحكم كل قرار لوني، الخلفية والنص والحد والتركيز، في الوضعين الفاتح والداكن.
مبني على مدرجاتنا
المعمار
طبقتان، والتغيير يتدفّق من الأعلى للأسفل. المدرجات الأساسية هي القيم الخام المنظّمة حسب الصبغة والدرجة. الطبقة الدلالية أسماء قائمة على الأدوار تشير إلى الأساسيات وتُحلّ لقيمة مختلفة في كل سمة. القاعدة الذهبية: المكوّنات تستخدم الرموز الدلالية فقط، لا الأساسيات مباشرة، ولا قيم ثابتة أبداً.
الطبقة ١
الرموز الأساسية
ست مدرجات (٦٦ درجة) + طبقات ألفا. قيم خام حسب الصبغة والدرجة.
الطبقة ٢
الرموز الدلالية
١٠٣ رمز في أربع مجموعات (خلفية، مقدمة، حد، تركيز)، تُحلّ لكل سمة.
المدرجات الأساسية
المادة الخام لكل عائلة لون، وما تشير إليه كل عائلة في الطبقة الدلالية. في الوضع الداكن تُعرض المدرجات بنسختها المهيّأة للخلفيات الداكنة. لا تستخدمها مباشرة في المنتج.
الطبقة الدلالية
الرموز الـ١٠٣ التي تبني بها، مجمّعة حسب الخاصية ثم الدور. كل صف يعرض قيمتَي الفاتح والداكن معاً، فتبني لأي سمة. المربّع الأول فاتح والثاني داكن. انقر أي رمز لنسخ متغيّره.
طبقات الأسطح
ست درجات عمق تحدّد البنية العمودية لكل شاشة، من Canvas (الجذر) إلى Elevated (النوافذ). خطوات الإضاءة توحي بالارتفاع. الحاجب Overlay طبقة عمق لا سطح محتوى.
عائلات الدلالة
ست عائلات تحمل معنى ثابتاً عبر النظام. لكل عائلة سطح خفيف وسطح قوي ونص وحد. البنفسجي يبقى أساسياً متاحاً بلا دلالة مربوطة.
هوية العلامة واللحظات التفاعلية المهمة.
النتائج الناجحة والتغذية الراجعة المطمئنة.
الحذر والانتباه المرتفع والمخاطر القابلة للاستدراك.
النية المدمّرة والمشاكل الحرجة والفشل.
الإرشاد المحايد وحالة النظام والتغذية الراجعة.
أدوار اللون
خمس فئات قائمة على الأدوار تحدّد كيف يُطبَّق كل رمز لوني.
| الدور | الغرض | القاعدة |
|---|---|---|
| خلفية | تحديد تسلسل الأسطح والتراكب البصري. | أنشئ التسلسل دوماً عبر الارتفاع والتباين. |
| نص | نقل تدرّج المحتوى والتأكيد الدلالي. | يجب أن يحقّق القراءة والتباين في كل سمة. |
| حد | فصل البنية وتحديد الحدود ودعم القابلية. | يدعم البنية دون أن يصبح الإشارة البصرية الأساسية. |
| أيقونة | تواصل بصري للإجراءات والحالة. | تتوافق مع النص المجاور دون تأكيد متعارض. |
| تركيز | الإشارة إلى تركيز لوحة المفاتيح وحالة الوصول. | محصور برؤية التركيز، لا يُعاد استخدامه للزينة. |
المبادئ
عشرة مبادئ حاكمة تفسّر القرارات خلف النظام.
وزن اللون يوجّه الانتباه عبر طبقات الواجهة. احجز أعلى تباين للمحتوى والإجراءات الأساسية.
كل صبغة تحمل معنى تواصلياً ثابتاً. استخدم ألوان الحالة لوظيفتها فقط، لا للزينة.
النص والعناصر التفاعلية تحقّق حدود التباين الدنيا. افحص كل زوج مقدمة/خلفية عند التصميم والبناء (WCAG AA).
العلامة والمحايد والحالة والبيانات لأغراض مميّزة لا تتداخل. لا تخلط فئات الأدوار في مكوّن واحد.
الحالات التفاعلية تُميّز بتغيّر لوني يحقّق التباين. لا تعتمد على اللون وحده لمؤشر التركيز.
الرموز الدلالية تحفظ معناها وتباينها عبر الفاتح والداكن. لا استخدام مباشر للأساسيات ولا قيم ثابتة.
الألوان عالية التشبّع تميّز ولا تملأ الأسطح الكبيرة. احصرها في العناصر التفاعلية ومؤشرات الحالة.
خطوات الإضاءة توحي بالارتفاع دون الاعتماد على الظلال وحدها. استخدم خطوات الخلفية المتسلسلة.
دور الرمز الدلالي لا يتغيّر عبر السياقات. دقّق المكوّنات الجديدة على الأدوار القائمة قبل إضافة رموز.
أي معلومة ينقلها اللون تُنقل أيضاً بالشكل أو النص أو الأيقونة. 8% من الذكور لديهم عمى ألوان.
مصفوفة الاقتران
ما يقبله كل سطح من مقدمة وحد وتركيز. اتبعها ليبقى كل زوج ميسّراً ومتّسق الدلالة.
أسطح محايدة أساسية (canvas / section / surface / raised / elevated)
كل رموز fg الأساسية والدلالية · كل حدود base والدلالية · focus.default و focus.negative.
bg.base.disabled
fg.base.disabled و border.base.disabled فقط. بلا حلقة تركيز.
bg.base.inverse
رموز inverse فقط: fg.inverse و border.inverse و focus.inverse (و focus.negative).
bg.base.overlay
لا اقترانات مباشرة. طبقة عمق لا سطح محتوى.
دلالة خفيفة (accent/positive/warning/negative/info · subtle)
fg الأساسي primary/secondary/tertiary + fg الدلالي المطابق · حدود base + الحد الدلالي المطابق · focus.default/negative.
دلالة قوية (accent/positive/negative/info · strong)
fg.base.on-color فقط · focus.inverse.
تنبيه قوي (warning.strong)
fg.base.on-tint فقط (أفتح من غيره) · focus.inverse.
اقترانات ممنوعة
تركيبات صريحة تكسر منطق الأدوار أو التماسك الدلالي أو التباين. لا تستخدمها أبداً.
| الرمز | على | لماذا |
|---|---|---|
| fg.base.on-color | أسطح محايدة أو خفيفة | on-color محجوز للتعبئات القوية؛ على المحايد يكسر الدور والوضوح. |
| fg.base.on-color | bg.intent.warning.strong | التنبيه القوي أفتح، يحتاج on-tint لا on-color. |
| fg.base.primary/secondary/tertiary | أسطح ملوّنة عالية التأكيد | التعبئات القوية تتطلّب مقدمات on-color. |
| fg.base.primary/secondary/tertiary | أسطح معكوسة | الأسطح المعكوسة تتطلّب معالجة inverse. |
| border.base.subtle/medium/strong | سياقات بنيوية معكوسة | الأسطح المعكوسة تتطلّب حدود inverse. |
| fg.base.inverse / border.base.inverse | أسطح فاتحة قياسية | رموز inverse تُنشئ انعكاساً زائفاً على القياسي. |
| border.base.subtle | فصل بنيوي عالي التأكيد | الحدود الخفيفة لا توفّر فصلاً كافياً. |
| border.intent.* | تأطير بنيوي محايد | حدود الدلالة إشارات لا فواصل بنيوية. |
| fg.intent.* | محتوى قراءة طويل أو أيقونات افتراضية | رموز الدلالة لمّاحات؛ الإفراط يقلّل وضوح الإشارة. |
| أي رمز دلالي | سطح بدلالة مختلفة | الاقترانات متعارضة الدلالة تكسر التماسك. |
| محتوى قابل للقراءة | bg.base.overlay | الحاجب طبقة عمق لا سطح محتوى. |
| أي رمز معطّل | سياقات فعّالة أو تفاعلية | رموز المعطّل تعني عدم التوفّر لا خفض التأكيد. |
| focus.default | أسطح ملوّنة عالية التأكيد | قد يفشل التباين؛ استخدم focus.inverse. |
| focus.inverse | أسطح فاتحة قياسية | يكسر اتساق التركيز على القياسي. |
قواعد الاستخدام
افعل / تجنّب لكل فئة دور.
مقدمة أساسية
افعل · primary للمحتوى الأساسي، secondary/tertiary لخفض التأكيد تدريجياً.
تجنّب · الإشارة الدلالية، أو استبدال المعطّل بـ secondary/tertiary.
حد أساسي
افعل · التحكّم بالبروز في السياقات البنيوية المحايدة.
تجنّب · الحالة أو التحقّق أو الإشارة الدلالية.
مقدمة دلالية
افعل · على المستوى المضمّن للتغذية الراجعة ونص التحقّق والحالة.
تجنّب · المتن الطويل أو محتوى الصفحة أو الأيقونات الزخرفية.
حد دلالي
افعل · حين يجب أن ينقل الحد الحالة أو الشدّة أو التحقّق.
تجنّب · البنية المحايدة أو فصل التخطيط أو حدود التحكّم الافتراضية.
on-color
افعل · حين يجلس المحتوى مباشرة على سطح ملوّن عالي التأكيد.
تجنّب · الأسطح الخفيفة أو المحايدة أو warning.strong.
on-tint
افعل · حين يكون السطح فاتحاً بحيث لا يكفي on-color (warning.strong).
تجنّب · التعبئات الداكنة أو عالية التشبّع.
inverse
افعل · حين يكون المحيط معكوساً: حواجب داكنة، حاويات inverse مرتفعة.
تجنّب · الأسطح الفاتحة القياسية والنماذج الافتراضية.
معطّل
افعل · لكل التحكّمات غير المتوفّرة والأسطح غير التفاعلية.
تجنّب · التأكيد الثانوي أو خفض الوزن خارج حالات المعطّل.
تركيز
افعل · default للقياسي، inverse للداكن/القوي، negative للمدمّر.
تجنّب · الحدود الزخرفية أو تنسيق الاختيار الدائم أو مؤشرات التحويم.
الوصول
طبقة الألوان تحكم كل قرار لوني، والمخاطر الأساسية هي فشل التباين، وترميز المعلومة باللون وحده، ورؤية التركيز. الهدف WCAG 2.1 AA في الوضعين.
| المعيار | المستوى | لماذا ينطبق |
|---|---|---|
| 1.4.1 · استخدام اللون | A | الدلالة لا تكون الوسيلة الوحيدة للمعلومة، اقرنها بأيقونة أو نص. |
| 1.4.3 · التباين (الأدنى) | AA | كل رموز نص fg تحقّق 4.5:1 (أو 3:1 للنص الكبير). |
| 1.4.11 · تباين غير النص | AA | حدود الدلالة والإجراء وحلقات التركيز تحقّق 3:1 مع خلفيتها. |
| 2.4.7 · التركيز مرئي | AA | رموز focus مميّزة بصرياً على كل سياقات الخلفية. |
استقلال الإشارة
الشيفرة للمطوّرين
التسليم الأساسي لطبقة اللون هو متغيّرات CSS المخصّصة. المكوّنات تستهلك الرموز الدلالية فقط (bg، fg، border، focus)، ولا تلمس المدرّجات الأوّلية ولا قيم hex خام أبداً.
سلسلة المتغيّرات
المتغيّرات تُبنى على ثلاث طبقات: مدرّج أوّلي، ثم رمز أوّلي، ثم رمز دلالي يُحلّ حسب الوضع. المكوّنات تستهلك الطبقة الدلالية فقط.
/* Tier 1 — primitive ramp (from @mercato/tokens) */
--color-dodger-blue-600: #1b79f5;
--color-dodger-blue-500: #3d8bf8;
/* Tier 2 — alpha overlay primitive (added by the color foundation) */
--color-alpha-black-200: rgba(0, 0, 0, 0.08);
/* Tier 3 — semantic role, resolved per mode; components consume THIS */
:root {
--color-bg-action-accent-primary-default: var(--color-dodger-blue-600);
--color-fg-action-accent-on-color: #ffffff;
--color-focus-default: var(--color-dodger-blue-500);
}
:root[data-theme="dark"] {
--color-bg-action-accent-primary-default: var(--color-dodger-blue-500);
--color-focus-default: var(--color-dodger-blue-400);
}جدول المرجع
| الرمز | متغيّر CSS | القيمة | الاستخدام |
|---|---|---|---|
| bg.action.accent.primary.default | --color-bg-action-accent-primary-default | blue-600 / blue-500 | تعبئة الزر الأساسي |
| fg.action.accent.on-color | --color-fg-action-accent-on-color | #ffffff | النص فوق التعبئة الملوّنة |
| bg.base.canvas | --color-bg-base-canvas | #ffffff / #15161b | خلفية الصفحة، العمق 0 |
| bg.base.section | --color-bg-base-section | oud-50 / #191a20 | سطح مجمّع داخل الصفحة |
| fg.base.primary | --color-fg-base-primary | نص العلامة الأساسي | النص الأساسي |
| focus.default | --color-focus-default | blue-500 / blue-400 | حلقة التركيز |
الاستخدام
.primary-button {
background: var(--color-bg-action-accent-primary-default);
color: var(--color-fg-action-accent-on-color);
}
.primary-button:focus-visible {
outline: 2px solid var(--color-focus-default);
}
/* Dark mode needs no override here: the semantic tokens self-resolve
under :root[data-theme="dark"]. */أخطاء شائعة
| الخطأ | ما يفسد | الصواب |
|---|---|---|
#1b79f5 | لا يتبدّل مع الوضع الداكن | var(--color-bg-action-accent-primary-default) |
| استهلاك مدرّج أوّلي مباشرة | يتجاوز الطبقة الدلالية | var(--color-fg-base-primary) |
| لون على سطح حاجب كسطح محتوى | يفشل تباين النص | استخدم bg.base.canvas أو section |
| الإشارة باللون وحده | يفشل الوصول للمكفوفين لونياً | اقرن اللون بأيقونة أو نص |
كيف تُستهلك
الرموز مصدرها واحد آلي القراءة (tokens.json في المهارة). حزمة @mercato/tokens تولّد منه: متغيّرات CSS (التسليم الأساسي)، وإعداد Tailwind جاهز، وكائن سمة مطبوع بـ TypeScript. أهداف المنصّات الأخرى (Style Dictionary وDTCG وiOS وAndroid وCompose) تتولّد من المصدر نفسه عند الطلب.
// CSS variables (canonical) — import once at the app root
import "@mercato/tokens/css";
// Tailwind preset
// tailwind.config: { presets: [require("@mercato/tokens/tailwind")] }
// Typed theme object (JS/TS)
import { tokens } from "@mercato/tokens";