الرموز
الاستدارة
نظام استدارة من ثلاث طبقات: سلّم من تسع درجات، ورموز أولية، وثلاثة عشر رمزاً دلالياً في خمس فئات شكلية. نصف القطر يشير إلى الوظيفة البنيوية لا إلى الذوق.
الشكل يتبع الدور
المعمار
ثلاث طبقات بلا أوضاع. السلّم تسع درجات خام (0 إلى ٩٩٩). الأولية تسمّيها بأحجام (none إلى full). الدلالية ثلاثة عشر رمز shape في خمس فئات. المكوّنات تستخدم الدلالية فقط.
السلّم والأولية
تسع درجات خام مقترنة بتسعة أسماء أحجام. الدرجة ٩٩٩ حبّية: تُحلّ حسب نسبة الأبعاد. لا تستخدمها في المكوّنات، بل عبر رموز shape.
فئات الشكل
خمس فئات دلالية، كل منها لدور بنيوي. انقر أي شكل لنسخ رمزه.
هندسة بنيوية صارمة.
استخدم · الحدود الحادة، الفواصل البنيوية، حواف الجداول، التخطيطات الكثيفة.
تجنّب · التحكّمات اللمسية، الحاويات المرتفعة، الأسطح التي تحتاج نعومة.
هندسة تفاعلية مدوّرة، الافتراضية لأغلب عناصر التفاعل.
استخدم · الأزرار، الحقول، الوسوم، الرقائق، المفاتيح.
تجنّب · العناصر البنيوية البحتة، الطبقات العائمة، الأسطح غير التفاعلية.
احتواء محدود ضمن مستوى الواجهة.
استخدم · البطاقات، اللوحات، المناطق المجمّعة، مناطق المحتوى دون انفصال.
تجنّب · الأهداف التفاعلية (استخدم Control)، الطبقات العائمة (استخدم Overlay).
احتواء منفصل فوق مستوى الواجهة.
استخدم · النوافذ، القوائم المنبثقة، القوائم المنسدلة، الحوارات، لوحات الأوامر.
تجنّب · عناصر التخطيط الأساسي أو عناصر الاحتواء القياسية.
أشكال مدوّرة بالكامل.
استخدم · الأزرار الحبّية، الصور الرمزية، الشارات، الوسوم الدائرية.
تجنّب · الحاويات المستطيلة والبطاقات والنوافذ، أو أي شكل يحتاج زاوية مرئية.
التداخل والزوايا المتصلة
قاعدتان تحكمان تركيب الأشكال: الأبناء المتداخلون يتبعون صيغة الحشو، والأشكال المتصلة تُربّع حوافها المشتركة.
التداخل: الداخلي = الأب − الحشو
الأب surface.raised (١٦) بحشو ٨ → الداخلي ١٦ − ٨ = ٨ → control.base. الزوايا المتحدة المركز تبدو موازية.
الزوايا المتصلة: الحواف المشتركة مربّعة
المجموعة تُدوّر الحواف الخارجية فقط (control.base)؛ الحواف الداخلية المشتركة تستخدم edge.hard (0) لتفادي التدوير المزدوج.
المبادئ
ثمانية مبادئ حاكمة لقرارات الاستدارة.
نصف قطر الزاوية يشير إلى الوظيفة البنيوية للشكل، لا إلى الحجم أو التفضيل الجمالي.
كل القيم من السلّم التسعيّ (0،2،4،8،12،16،24،32،999). لا أرقام خارجه.
الاحتواء الخارجي يستخدم نصف قطر أكبر من أو يساوي المحتوى الداخلي.
الأبناء المتداخلون يتبعون صيغة: الداخلي = الأب − إزاحة الحشو، لا نسخ الأب.
الأشكال المتجاورة التي تتشارك حداً تحلّ الحافة: الحواف المشتركة بلا نصف قطر (edge.hard).
كل الزوايا داخل صورة ظلية مرئية واحدة تتبع القاعدة نفسها باتساق.
نوع العنصر نفسه يستخدم رمز نصف القطر نفسه عبر كل الحالات والنسخ.
تستخدم الشاشة أقل عدد ممكن من عائلات نصف القطر (غالباً ٢–٣ فئات).
إمكانية الوصول
قيم نصف القطر لا تخالف أي معيار WCAG AA بمفردها؛ المعيار الوحيد المنطبق هو رؤية التركيز، والثوابت البنيوية تحمي تماسك الشكل.
| المعيار | المستوى | لماذا ينطبق |
|---|---|---|
| 2.4.7 · التركيز مرئي | AA | مؤشّرات التركيز ترث نصف قطر العنصر؛ كسر قواعد الزوايا المتصلة/المتداخلة يشوّه هندسة حلقة التركيز. |
أ — التسلسل
الابن لا يساوي أو يتجاوز نصف قطر الأب.
ب — صيغة التداخل
الابن المتداخل = الأب − إزاحة الحشو.
ج — الاستمرارية
الحواف المشتركة تستخدم radius.none (0).
د — اتساق الحالة
الرمز نفسه عبر default/hover/active/focus.
قيم نصف القطر لا تخالف أي معيار WCAG AA بمفردها؛ أقصى شدّة للنتائج تحذير.
الشيفرة للمطوّرين
التسليم الأساسي لطبقة الاستدارة هو متغيّرات CSS المخصّصة، وهي موحّدة عبر كل الأوضاع (لا فاتح/داكن ولا كثافة). المكوّنات تستهلك رموز shape الدلالية فقط، ولا تلمس السلّم أو الأولية ولا قيمة px خام أبداً.
سلسلة المتغيّرات
المتغيّرات تُبنى على ثلاث طبقات: مدرّج أوّلي، ثم رمز أوّلي، ثم رمز دلالي يُحلّ حسب الوضع. المكوّنات تستهلك الطبقة الدلالية فقط.
/* Tier 1 — scale (raw px steps) */
--radius-scale-300: 8px;
--radius-scale-800: 999px; /* full-pill sentinel */
/* Tier 2 — primitive size aliases */
--radius-md: var(--radius-scale-300);
--radius-full: var(--radius-scale-800);
/* Tier 3 — semantic shape; components consume THIS */
:root {
--shape-control-base: var(--radius-md); /* 8px */
--shape-surface-base: var(--radius-lg); /* 12px */
--shape-rounded: var(--radius-full); /* 999px pill */
}
/* A component (e.g. a pill button) consumes the semantic token */
.button-pill {
border-radius: var(--shape-rounded);
}جدول المرجع
| الرمز | متغيّر CSS | القيمة | الاستخدام |
|---|---|---|---|
| shape.rounded | --shape-rounded | 999px | الأزرار الحبّية والرقائق والصور الرمزية |
| shape.control.base | --shape-control-base | 8px | الأزرار والحقول والعناصر التفاعلية |
| shape.control.compact | --shape-control-compact | 4px | العناصر التفاعلية المدمجة |
| shape.surface.base | --shape-surface-base | 12px | البطاقات والأسطح المجمّعة |
| shape.surface.raised | --shape-surface-raised | 16px | الألواح المرتفعة |
| shape.overlay.base | --shape-overlay-base | 16px | النوافذ والقوائم المنبثقة |
| shape.edge.hard | --shape-edge-hard | 0px | الحواف المشتركة والحواف المتلاصقة |
الاستخدام
.button {
border-radius: var(--shape-control-base); /* 8px */
}
.pill, .chip, .avatar {
border-radius: var(--shape-rounded); /* resolves to a full pill */
}
.card {
border-radius: var(--shape-surface-base); /* 12px */
}
/* Segmented control: round only the outer edges, square the seams */
.segment:not(:first-child):not(:last-child) {
border-radius: var(--shape-edge-hard); /* 0px */
}أخطاء شائعة
| الخطأ | ما يفسد | الصواب |
|---|---|---|
border-radius: 999px | لا يتتبّع نيّة الحبّة ولا يتحدّث مع الرمز | var(--shape-rounded) |
border-radius: 8px | يتجاوز طبقة الشكل الدلالية | var(--shape-control-base) |
| استهلاك أولية مثل var(--radius-md) في مكوّن | يفقد الدور البنيوي للشكل | var(--shape-control-base) |
| تدوير الحواف المشتركة في مجموعة متصلة | تدوير مزدوج على الحافة الداخلية | var(--shape-edge-hard) |
كيف تُستهلك
الرموز مصدرها واحد آلي القراءة (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";