صيغة DTCG للـ Tokens

الـ CSS custom properties طريقة ممتازة لـ استهلاك الـ tokens على الويب، لكنها مكان سيئ لـ تخزينها. تطبيق iOS لا يستطيع قراءة ملف الأنماط، وFigma لا يستطيع استيراده، والسكربت الذي يفحص التباين عبر الـ themes يضطر إلى تحليل CSS ليجد القيم. لذلك تعيش tokens في Northwind في ملفات JSON، بالصيغة التي حدّدتها مجموعة Design Tokens Community Group (DTCG)، ويُولَّد كود كل منصّة منها.

أين تقف الصيغة في 2026

الـ DTCG مجموعة مجتمعية (Community Group) تابعة لـ W3C، أعضاؤها من صانعي أدوات التصميم وفرق أنظمة تصميم كبيرة. في 28 أكتوبر 2025 نشرت أول إصدار مستقر من مواصفتها، 2025.10، ويتكوّن من ثلاث وحدات: Format، وColor، ووحدة Resolver لتركيب المجموعات والـ themes.

كن دقيقًا حين تصفها للآخرين. إنها تقرير مستقر من Community Group، وليست توصية رسمية من W3C (Recommendation)؛ فالمجموعات المجتمعية لا تُصدر معايير ويب رسمية. وعمليًا هي الصيغة التي تتقارب حولها الأدوات: Style Dictionary وTokens Studio وTerrazzo تطبّقها، وFigma يستورد المتغيّرات ويصدّرها كـ JSON بصيغة DTCG. لكن دعم الأجزاء الأحدث، مثل صيغة اللون ككائن ووحدة Resolver، ما زال متفاوتًا بين الأدوات، لذا افحص ما يقرؤه خط الإنتاج لديك فعلًا قبل تبنّي ميزة.

تشريح ملف الـ tokens

{
  "color": {
    "$type": "color",
    "blue": {
      "600": {
        "$value": { "colorSpace": "srgb", "components": [0.122, 0.353, 0.878], "hex": "#1f5ae0" },
        "$description": "Northwind brand blue. Passes 4.5:1 on white."
      }
    },
    "white": {
      "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" }
    }
  },
  "space": {
    "$type": "dimension",
    "4": { "$value": { "value": 1, "unit": "rem" } }
  }
}

اقرأه من الخارج إلى الداخل:

• المجموعات (groups) كائنات متداخلة عادية (color، blue، space). تنظّم الـ tokens وتشكّل المسار المستخدم في المراجع.
• الـ token أي كائن فيه $value. هنا color.blue.600 وspace.4 هما الـ tokens.
• $type يحدّد نوع القيمة التي يحملها الـ token. وحين يُحدَّد على مجموعة، ترثه كل الـ tokens داخلها، ولهذا تعرّفه color مرة واحدة.
• $description نص حرّ تعرضه الأدوات في المنتقيات والتوثيق.

الخصائص التي تبدأ بـ $ محجوزة للصيغة، فلا يمكن أن تبدأ أسماء الـ tokens والمجموعات بـ $. ولا يمكن أن تحتوي الأسماء أيضًا على { أو } أو .، لأن هذه الرموز تنتمي إلى صيغة المراجع.

الأنواع وأشكال القيم

لكل نوع شكل قيمة ثابت. هذه هي الأنواع التي ستستخدمها يوميًا:

وهناك أيضًا fontFamily وcubicBezier، إضافة إلى أنواع مركّبة تجمع عدّة قيم: typography وshadow وborder وtransition وgradient وstrokeStyle.

كائن اللون جديد في 2025.10. المسودّات الأقدم، وكثير من ملفات الـ tokens المتداولة، تخزّن نص hex بسيطًا. أما صيغة الكائن فتستطيع وصف ألوان خارج sRGB، مثل display-p3 أو oklch، ولهذا حلّت محلّ النص. احتفظ بالـ hex الاختياري للأدوات التي لا تفهم إلا sRGB.

الأسماء المستعارة (aliases)

الطبقة الدلالية من الدروس السابقة تعيش في الصيغة نفسها، على شكل مراجع:

{
  "color": {
    "$type": "color",
    "action": {
      "bg": { "$value": "{color.blue.600}" },
      "text": { "$value": "{color.white}" },
      "bg-hover": { "$value": "{color.blue.700}" },
      "bg-dark": {
        "$value": "{color.blue.700}",
        "$deprecated": "Use color.action.bg-hover instead. Removed in 5.0."
      }
    }
  }
}

المرجع بالأقواس المعقوفة يسمّي token بمساره المفصول بنقاط، ويُحَلّ إلى قيمة $value الكاملة لذلك الـ token. ويجب أن يشير إلى token، لا إلى مجموعة أبدًا. يمكن أن تتسلسل المراجع (من semantic إلى primitive)، ويجب أن ترفض الأداة المراجع الدائرية. وللحالة النادرة التي تحتاج فيها جزءًا من قيمة، مثل مكوّن لون واحد، تدعم الصيغة أيضًا مراجع JSON Pointer عبر $ref.

هذا جوهر ما تفعله كل أداة tokens مع الأسماء المستعارة:

const tokens = {
  color: {
    $type: 'color',
    blue: { 600: { $value: { colorSpace: 'srgb', components: [0.122, 0.353, 0.878], hex: '#1f5ae0' } } },
    action: {
      bg: { $value: '{color.blue.600}' },
      'bg-subtle': { $value: '{color.action.bg}' },
    },
  },
};

function lookup(path) {
  const node = path.split('.').reduce((n, key) => n?.[key], tokens);
  if (!node || !('$value' in node)) throw new Error(`{${path}} is not a token`);
  return node;
}

function resolve(path, seen = []) {
  if (seen.includes(path)) throw new Error(`circular reference: ${[...seen, path].join(' -> ')}`);
  const { $value } = lookup(path);
  const ref = typeof $value === 'string' && $value.match(/^\{(.+)\}$/);
  return ref ? resolve(ref[1], [...seen, path]) : $value;
}

console.log(resolve('color.action.bg-subtle').hex);
try { resolve('color.action'); } catch (e) { console.log(e.message); }

ميزتان أخريان تستحقّان المعرفة

$deprecated، الظاهرة أعلاه على bg-dark (اسم يصف المظهر، وهو ما حذّر منه درس التسمية)، تعلّم token بأنه في طريقه إلى الخروج. قيمتها true أو نص يشرح ما يُستخدم بدلًا منه، ويمكن للأدوات أن تحذّر حين يختاره أحد. ستبني عملية deprecation كاملة حولها في القسم 4.

ويمكن للمجموعات أيضًا أن ترث من مجموعات أخرى عبر $extends، فتخصّص ما يختلف فقط. وهذا مفيد لمجموعة Tidewater التي تعيد استخدام معظم بنية Northwind. أما لتركيبات الفاتح والداكن والعلامات الكاملة، فوحدة Resolver تحدّد كيف تتركّب مجموعات الـ tokens المنفصلة والمعدِّلات، لكنها أحدث جزء في المواصفة، لذا ما زالت Northwind تجمّع الـ themes في خط إنتاج البناء الخاص بها. امتدادات الملفات الموصى بها هي .tokens و.tokens.json؛ وتستخدم Northwind الثاني حتى تلوّن المحرّرات الملفات كـ JSON.

في التمرين التالي تراجع ملف tokens كما يراجعه خط الإنتاج، وتجد الأسطر التي سيرفضها. وبعدها تبني خط الإنتاج هذا بنفسك.