انتقل إلى المحتوى
TopClass UI

الألوان

كل رمز لوني في كل وضع، مع التباين الذي يُفحص مقابله.

نصف القطر (rem)0.5
الكثافة1

يضبط المنزلقان --tc-radius و--tc-density على هذه الصفحة فقط. مبدّل الوضع في الشريط العلوي.

الطبقات الثلاث

لا يسمّي المكوّن لونًا أبدًا، بل يسمّي دورًا، ويُحَلّ هذا الدور بشكل مختلف في كل وضع.

لوحة الألوان هي تدرّج oklch في Tailwind v4. تربط الطبقة الدلالية كل دور بدرجة لونية، ثم يحوّل @theme inline كل دور إلى صنف مساعد.

/* palette - never referenced by a component */
--color-blue-600: oklch(54.6% 0.245 262.881);

/* semantic - what a component means */
--tc-primary-solid: var(--color-blue-600);
--tc-primary-on-solid: var(--color-white);

/* utility - what Tailwind generates */
@theme inline {
  --color-primary-solid: var(--tc-primary-solid);
}

/* what you write */
className="bg-primary-solid text-primary-on-solid"

لا يستخدم أي مكوّن إلا الطبقة الدلالية، لذا لا يحتاج أي وضع جديد إلى تغيير في المكوّنات.

كل الأصناف

صنف واحد لكل دور. هذه هي الأسماء التي تستخدمها المكوّنات، وهي نفسها التي تستخدمها أنت بجانبها.

الصنف, المتغيّر, الغرض منه, فاتح, داكن, محيط
العيّنةالصنفالمتغيّرالغرض منهفاتحداكنمحيط
bg-page--tc-pageالصفحة خلف كل شيءwhiteغير مقيس: سطح أو خط زخرفيneutral-950غير مقيس: سطح أو خط زخرفيwhiteغير مقيس: سطح أو خط زخرفي
bg-surface--tc-surfaceسطح غائر أو مخطّطneutral-50غير مقيس: سطح أو خط زخرفيneutral-900غير مقيس: سطح أو خط زخرفيneutral-50غير مقيس: سطح أو خط زخرفي
bg-surface-raised--tc-surface-raisedبطاقة، نافذة منبثقة، حقل إدخالwhiteغير مقيس: سطح أو خط زخرفيneutral-800غير مقيس: سطح أو خط زخرفيwhiteغير مقيس: سطح أو خط زخرفي
text-body--tc-bodyنص المحتوىneutral-95018.96:1، والحد الأدنى 4.5:1neutral-5014.48:1، والحد الأدنى 4.5:1neutral-95018.96:1، والحد الأدنى 4.5:1
text-muted--tc-mutedالنص الثانويneutral-6007.47:1، والحد الأدنى 4.5:1neutral-4005.83:1، والحد الأدنى 4.5:1neutral-6007.47:1، والحد الأدنى 4.5:1
border-line--tc-lineخط رفيع للزينةneutral-200غير مقيس: سطح أو خط زخرفيneutral-800غير مقيس: سطح أو خط زخرفيneutral-200غير مقيس: سطح أو خط زخرفي
border-line-strong--tc-line-strongحدّ عنصر التحكم، ويجب أن يبلغ 3:1neutral-5004.53:1، والحد الأدنى 3:1neutral-4005.83:1، والحد الأدنى 3:1neutral-5004.53:1، والحد الأدنى 3:1
outline-ring--tc-ringحلقة التركيزblue-8008.47:1، والحد الأدنى 3:1blue-4005.73:1، والحد الأدنى 3:1cyan-8006.94:1، والحد الأدنى 3:1
bg-primary-solid--tc-primary-solidعنصر تحكم مُعبّأblue-6005.26:1، والحد الأدنى 4.5:1blue-6005.26:1، والحد الأدنى 4.5:1cyan-7005.28:1، والحد الأدنى 4.5:1
text-primary-on-solid--tc-primary-on-solidالنص فوق تلك التعبئةwhite5.26:1، والحد الأدنى 4.5:1white5.26:1، والحد الأدنى 4.5:1white5.28:1، والحد الأدنى 4.5:1
bg-primary-soft--tc-primary-softصبغة خفيفة، لشريحة أو لصف يمرّ عليه المؤشر12% من primary-solid ممزوجة بالصفحة7.52:1، والحد الأدنى 4.5:124% من primary-solid ممزوجة بالصفحة6.25:1، والحد الأدنى 4.5:112% من primary-solid ممزوجة بالصفحة6.14:1، والحد الأدنى 4.5:1
text-primary-on-soft--tc-primary-on-softالنص والأيقونات فوق تلك الصبغةblue-8007.52:1، والحد الأدنى 4.5:1blue-4006.25:1، والحد الأدنى 4.5:1cyan-8006.14:1، والحد الأدنى 4.5:1

النبرات الست

لكل نبرة المجموعة نفسها من الأدوار، لذا يستخدم كلٌّ من Badge وAlert وButton النبرة بالطريقة نفسها.

الدور, الغرض منه, فاتح, داكن, محيط
العيّنةالدورالغرض منهفاتحداكنمحيط
primary/solidعنصر تحكم مُعبّأ بتسمية بيضاءblue-6005.26:1، والحد الأدنى 4.5:1blue-6005.26:1، والحد الأدنى 4.5:1cyan-7005.28:1، والحد الأدنى 4.5:1
primary/softصبغة خفيفة، لشريحة أو لصف يمرّ عليه المؤشر12% من primary-solid ممزوجة بالصفحة7.52:1، والحد الأدنى 4.5:124% من primary-solid ممزوجة بالصفحة6.25:1، والحد الأدنى 4.5:112% من primary-solid ممزوجة بالصفحة6.14:1، والحد الأدنى 4.5:1
primary/on-softالنص والأيقونات فوق تلك الصبغةblue-8007.52:1، والحد الأدنى 4.5:1blue-4006.25:1، والحد الأدنى 4.5:1cyan-8006.14:1، والحد الأدنى 4.5:1
success/solidعنصر تحكم مُعبّأ بتسمية بيضاءemerald-7005.37:1، والحد الأدنى 4.5:1emerald-7005.37:1، والحد الأدنى 4.5:1emerald-7005.37:1، والحد الأدنى 4.5:1
warning/solidتسميته شبه سوداء، لا بيضاءamber-5009.23:1، والحد الأدنى 4.5:1amber-5009.23:1، والحد الأدنى 4.5:1amber-5009.23:1، والحد الأدنى 4.5:1
danger/solidالإجراءات المدمِّرةred-6004.76:1، والحد الأدنى 4.5:1red-6004.76:1، والحد الأدنى 4.5:1red-6004.76:1، والحد الأدنى 4.5:1
info/solidمعلومات محايدةsky-7005.85:1، والحد الأدنى 4.5:1sky-7005.85:1، والحد الأدنى 4.5:1sky-7005.85:1، والحد الأدنى 4.5:1
neutral/solidيتبدّل مع الوضعneutral-90017.91:1، والحد الأدنى 4.5:1neutral-10018.15:1، والحد الأدنى 4.5:1neutral-90017.91:1، والحد الأدنى 4.5:1

معروضة في وضع الصفحة. كل صف متغيّر حيّ، لا صورة له.

أين يُستخدم كل لون

شاشة واحدة، وعلى كل دور فيها اسمه.

شاشة مثال، كل جزء منها موسوم بالصنف الذي يلوّنه
bg-page
TopClass UIbg-surface
إعدادات المشروعtext-bodyاختر طريقة نشر هذا المشروع.text-muted
bg-primary-solidborder-line
الإنتاجbg-primary-softالمعاينةالتطويرbg-surface-raised
  • bg-surface: الشريط العلوي، صندوق يستقر فوق الصفحة.
  • border-line: الخط الرفيع تحت الشريط وحول البطاقة.
  • text-body: العناوين والنص العادي.
  • text-muted: سطر الوصف الرمادي.
  • bg-primary-solid + text-primary-on-solid: زر «حفظ».
  • bg-primary-soft + text-primary-on-soft: الصف المحدد في القائمة المنسدلة.
  • bg-surface-raised: القائمة المنسدلة، طافيةً فوق البطاقة، أفتح منها بدرجة واحدة ومعها ظل.
  • bg-page: الشاشة كلها، خلف كل شيء.

الأوضاع الثلاثة

الفاتح والداكن والمحيط ثلاث كتل CSS تضبط أسماء المتغيّرات نفسها. يتبع هذا الموقع وضع نظامك إلى أن تختار وضعًا.

وضع المحيط هو الوضع الفاتح بلون أساسي سماوي وزوايا على شكل كبسولة. لا يحتاج الوضع المخصّص إلى أكثر من كتلة CSS واحدة.

topclassui/tokens.css
[data-theme='dark'] {
  --tc-page: var(--color-neutral-950);
  --tc-surface: var(--color-neutral-900);
  --tc-surface-raised: var(--color-neutral-800);
  --tc-body: var(--color-neutral-50);
  --tc-muted: var(--color-neutral-400);
  --tc-line: var(--color-neutral-800);
  /* neutral-400 not neutral-500: on a raised card neutral-500 measured only 3.19:1. */
  --tc-line-strong: var(--color-neutral-400);
  --tc-overlay: oklch(0 0 0 / 0.7);

  --tc-neutral-solid: var(--color-neutral-100);
  --tc-neutral-on-solid: var(--color-neutral-950);
  --tc-neutral-on-soft: var(--color-neutral-200);
  --tc-primary-on-soft: var(--color-blue-400);
  --tc-success-on-soft: var(--color-emerald-400);
  --tc-warning-on-soft: var(--color-amber-400);
  --tc-danger-on-soft: var(--color-red-400);
  --tc-info-on-soft: var(--color-sky-400);

  /* At the light percentages every dark tint measured 1.01-1.03 on --tc-surface. */
  --tc-primary-mix: 24%;
  --tc-neutral-mix: 12%;
  --tc-success-mix: 24%;
  --tc-warning-mix: 14%;
  --tc-danger-mix: 22%;
  --tc-info-mix: 24%;

  /* Near-white in dark, so it steps toward the middle from the other side. */
  --tc-neutral-hover: var(--color-neutral-200);
  --tc-neutral-active: var(--color-neutral-300);

  /* neutral-400 not neutral-500: on a raised card neutral-500 measured only 3.19:1. */
  --tc-scrollbar-thumb: var(--color-neutral-400);
  --tc-scrollbar-track: transparent;
}

ما يفرضه فحص التباين

يُفحص التباين عند كل تغيير في المكتبة، وأي إخفاق يوقف ذلك التغيير. ويعتمد الفحص على ربط النطاق اللوني (gamut mapping) وفق CSS Color 4، لأن بعض الدرجات تقع خارج sRGB.

ما يُقاس, الحدّ, يُقاس مقابل
ما يُقاسالحدّيُقاس مقابل
النص، بما فيه نص النبرة فوق صبغتها4.5:1السطح الذي يقع عليه
line-strong وring والأيقونات3:1الأسطح الثلاثة كلها، لا الصفحة وحدها
الصبغة الخفيفةخطوة 1.06الأسطح الثلاثة كلها
lineمُستثنىخط رفيع للزينة، WCAG 1.4.11

أضف سمتك الخاصة

أضف كتلة CSS واحدة، وضع data-theme="brand" على العنصر الذي تغطيه. يمكن للوضع أن يغيّر مفاتيح الضبط كما يغيّر الألوان.

الوضع الذي يضبط --tc-primary-solid يجب أن يضبط --tc-primary-on-solid أيضًا، وإلا فقد ينزل تباين تسميته عن 4.5:1 فوق التعبئة الجديدة.
app/globals.css
/* after the three imports */
[data-theme="brand"] {
  color-scheme: dark;

  --tc-page: var(--color-slate-950);
  --tc-surface: var(--color-slate-900);
  --tc-surface-raised: var(--color-slate-800);
  --tc-body: var(--color-slate-50);
  --tc-muted: var(--color-slate-400);
  --tc-line: var(--color-slate-800);
  --tc-line-strong: var(--color-slate-600);

  --tc-primary-solid: var(--color-teal-500);
  --tc-primary-on-solid: var(--color-slate-950);
  --tc-primary-on-soft: var(--color-teal-300);

  --tc-radius: 1rem;
}
لا يحفظ ThemeScript إلا light وdark وocean، لذا ضع الوضع المخصّص على قسم من الصفحة، أو على html في تخطيط لا يعرض ThemeScript.
التاليالأيقونات