{"id":"l-ds-3-3","courseId":"design-systems","lang":"ar","kind":"lesson","summary":"ابنِ كل حالات التفاعل وسلوكيات إمكانية الوصول داخل المكوّنات افتراضيًا، بما فيها التركيز المرئي عبر ‎:focus-visible، وحالتي التعطيل والضغط، وأنماط ARIA التي تتبع WAI-ARIA Authoring Practices.","html":"

بدا Button الذي أطلقته Northwind عام 2021 مثاليًا في كل لقطة شاشة، لأن اللقطات لا تُظهر إلا الحالة الافتراضية. في الإنتاج لم يكن له تركيز مرئي للوحة المفاتيح، وفشل نمط التعطيل الخاص به في التباين على علامة Tidewater، وكانت حالة «التحميل» تجعل الزر ينكمش والتخطيط يقفز. لم يكن شيء من هذا في ملف Figma. المكوّنات تفشل في حالاتها، لذا يجب أن يصمّمها النظام كلها ويبنيها ويختبرها.

\n

مصفوفة الحالات

\n

كل مكوّن تفاعلي يحصل على مصفوفة حالات: صف لكل variant، وعمود لكل حالة. للـ Button:

\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

الحالة	ما يطلقها	تُبنى بـ
Hover	المؤشر فوقه	`:hover`
التركيز المرئي	تركيز لوحة المفاتيح	`:focus-visible`
Active	أثناء الضغط	`:active`
معطّل	غير متاح	`disabled` أو `aria-disabled="true"`
تحميل	إجراء قيد التنفيذ	`aria-busy`، وعرض ثابت
مضغوط	زر التبديل مفعّل	`aria-pressed="true"`

تصمّم Northwind كل خانة في Figma (كـ variants للمكوّن) قبل أن يكتب أحد سطر كود، والاختبارات البصرية في القسم 4 تعرض كل خانة في كل theme. وحين تصل مساهمة لم يُصمَّم فيها إلا الحالة الافتراضية والـ hover، تعيدها المراجعة.

\n

تركيز يراه الناس

\n

مستخدمو لوحة المفاتيح يحتاجون أن يروا أين التركيز؛ وWCAG 2.2 يشترط ذلك في المستوى AA ‏(2.4.7، Focus Visible). أما مستخدمو الفأرة فعادةً لا يريدون حلقة بعد النقر. و:focus-visible يحلّ ذلك: تطبّقه المتصفّحات حين يجب أن يكون التركيز مرئيًا، وعادةً بعد التنقّل بلوحة المفاتيح، لا بعد معظم نقرات الفأرة.

\n

CSS

:root {\n  --nw-focus-ring-color: var(--nw-blue-600);\n  --nw-focus-ring-width: 2px;\n  --nw-focus-ring-offset: 2px;\n}\n\n.nw-button:focus-visible {\n  outline: var(--nw-focus-ring-width) solid var(--nw-focus-ring-color);\n  outline-offset: var(--nw-focus-ring-offset);\n}

\n

الحلقة مبنية من tokens، فيستطيع الوضع الداكن وTidewater تعديلها، وكل المكوّنات تستخدم الحلقة نفسها. وهي outline لا box-shadow، لأن أوضاع forced-colors مثل themes التباين في Windows تحذف الظلال وتُبقي الـ outlines.

\n\n

التعطيل، بطريقتين

\n

السمة disabled تُخرج الزر من ترتيب التنقّل بـ Tab ومن التفعيل. وهذا صحيح في معظم الحالات، لكنه يخلق مشكلة: لا يستطيع مستخدمو لوحة المفاتيح وقارئ الشاشة الوصول إلى الزر ليعرفوا لماذا هو معطّل.

\n

حين تحتاج إلى شرح، استخدم aria-disabled="true" بدلًا من ذلك. يبقى الزر قابلًا للتركيز ويُعلَن أنه غير متاح؛ وتربط السبب عبر aria-describedby؛ ولأن المتصفّح لن يمنع النقر عنك، يجب أن يفعل المكوّن ذلك:

\n

JavaScript

button.addEventListener('click', (event) => {\n  if (button.getAttribute('aria-disabled') === 'true') {\n    event.preventDefault();\n    event.stopImmediatePropagation();\n  }\n});

\n

الـ Button في النظام يفعل هذا داخليًا، فتحدّد الفرق prop واحدًا وتحصل على السلوك. وهذا هو جوهر بناء إمكانية الوصول داخل المكوّن: أربعون فريقًا لن يتذكّر كلٌّ منهم stopImmediatePropagation، لكن مكوّنًا واحدًا يستطيع.

\n

أزرار التبديل، والأهداف، والأنماط

\n

الزر الذي يشغّل شيئًا ويطفئه هو زر تبديل (toggle button). علّم حالته بـ aria-pressed="true" أو "false"، ونسّق هذه السمة نفسها حتى لا تتباعد الحالة المرئية عن الحالة المُعلَنة:

\n

CSS

.nw-button[aria-pressed=\"true\"] {\n  --nw-button-bg: var(--nw-color-action-bg-subtle);\n  --nw-button-border: var(--nw-color-action-bg);\n}

\n

والحجم مهمّ أيضًا: معيار النجاح 2.5.8 في WCAG 2.2 يطلب أهدافًا للمؤشر لا تقل عن 24 في 24 بكسل CSS في المستوى AA، مع بعض الاستثناءات. وأصغر ارتفاع لعنصر تحكّم في Northwind هو 32px، تفرضه tokens الحجم sm.

\n

ولأي شيء أبعد من الزر، استخدم العناصر الأصلية أولًا: <button> و<dialog> و<details> و<select>. وحين تبني عنصرًا مخصّصًا مثل التبويبات أو زر القائمة أو الـ combobox، اتبع النمط المقابل في WAI-ARIA Authoring Practices Guide: أدواره وحالاته وتفاعلات لوحة المفاتيح فيه. مستخدمو التقنيات المساعدة يتوقّعون هذه السلوكيات، والدليل يوثّقها بدقّة.

\n\n

في التمرين تصلح مجموعة أزرار تخفي تركيز لوحة المفاتيح وتتجاهل حالة التعطيل الخاصة بها. وبعدها تكتب التوثيق الذي يخبر الفرق كيف تستخدم كل هذا.

\n","toc":[{"id":"sec-1","text":"مصفوفة الحالات","level":2},{"id":"sec-2","text":"تركيز يراه الناس","level":2},{"id":"sec-3","text":"التعطيل، بطريقتين","level":2},{"id":"sec-4","text":"أزرار التبديل، والأهداف، والأنماط","level":2}],"takeaways":["صمّم وابنِ مصفوفة حالات كاملة لكل مكوّن تفاعلي، تشمل التركيز والتعطيل والتحميل والضغط، لا الحالة الافتراضية والـ hover وحدهما.","نسّق تركيز لوحة المفاتيح بـ :focus-visible وبـ outline مأخوذ من token؛ ولا تحذف الـ outline أبدًا دون بديل مرئي.","استخدم العناصر الأصلية أولًا، واتبع WAI-ARIA Authoring Practices في العناصر المخصّصة مثل التبويبات والقوائم والـ comboboxes.","السمة aria-disabled="true" تُبقي العنصر قابلًا للتركيز حتى تشرح سبب عدم توفّره، لكن عليك أن تمنع إجراءه بنفسك.","حين تعيش إمكانية الوصول داخل المكوّن يحصل عليها 40 فريقًا مجانًا؛ وحين تعيش في التوثيق يفوّتها معظمهم."],"further":[{"title":":focus-visible (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:focus-visible"},{"title":"WAI-ARIA Authoring Practices Guide patterns (W3C)","url":"https://www.w3.org/WAI/ARIA/apg/patterns/"},{"title":"Understanding SC 2.5.8 Target Size (Minimum) (W3C)","url":"https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html"},{"title":"aria-pressed (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-pressed"}],"quiz":[{"q":"

أطلق أحد الفرق .nw-button:focus { outline: none; } لأن الحلقة «تبدو قبيحة عند النقر». ما الإصلاح الصحيح في النظام؟

","options":[{"text":"إبقاء outline: none والاعتماد على لون الـ hover لمستخدمي لوحة المفاتيح.","why":"مستخدمو لوحة المفاتيح لا يمرّرون المؤشر فوق العناصر، فيفقدون أي إشارة إلى مكانهم."},{"text":"نقل الحلقة إلى :focus-visible حتى تظهر مع تركيز لوحة المفاتيح لا مع معظم نقرات الفأرة.","why":"صحيح. تطبّق المتصفّحات :focus-visible حين يجب أن يكون التركيز مرئيًا، وهذا ما تريده المجموعتان فعلًا."},{"text":"استبدال الـ outline بحلقة box-shadow على :focus.","why":"ستظلّ تظهر عند النقر، والظلال تُحذف في أوضاع forced-colors، فيفقد مستخدمو التباين العالي الحلقة."},{"text":"إضافة tabindex="-1" إلى الأزرار حتى لا تستقبل التركيز.","why":"هذا يُخرج الأزرار من ترتيب لوحة المفاتيح كليًا، فتصبح غير قابلة للاستخدام دون فأرة."}],"answer":1},{"q":"

زر الحفظ غير متاح حتى يُختار سائق. يريد فريق المنتج tooltip يشرح السبب. أيّ نهج ينجح؟

","options":[{"text":"استخدام السمة disabled وربط الـ tooltip بالزر.","why":"الزر المعطّل لا يستقبل التركيز، فلا يصل مستخدمو لوحة المفاتيح وقارئ الشاشة إلى الـ tooltip أبدًا."},{"text":"إخفاء الزر حتى يُختار سائق.","why":"الإخفاء يزيل أي تلميح بأن الحفظ ممكن أصلًا، ويقفز التخطيط حين يظهر الزر."},{"text":"تحديد aria-disabled="true"، وإبقاء الزر قابلًا للتركيز، ومنع النقر في الكود، وربط الشرح عبر aria-describedby.","why":"صحيح. يبقى العنصر قابلًا للوصول ويُعلَن أنه غير متاح، والسبب متاح للجميع."}],"answer":2},{"q":"

تحتاج Northwind إلى زر تبديل «Show only late shipments». أيّ markup يوصل حالته بشكل صحيح؟

","options":[{"text":"<button type="button" aria-pressed="true">Show only late shipments</button>","why":"صحيح. السمة aria-pressed تحوّل الزر إلى زر تبديل، وقارئات الشاشة تعلن أنه مضغوط أو غير مضغوط."},{"text":"<button type="button" class="is-active">Show only late shipments</button>","why":"الـ class يغيّر الشكل لكنه لا يخبر التقنيات المساعدة بشيء عن الحالة."},{"text":"<div role="button" data-on="true">Show only late shipments</div>","why":"الـ div يحتاج إضافة التعامل مع لوحة المفاتيح وقابلية التركيز يدويًا، وdata-on لا تصل إلى التقنيات المساعدة."},{"text":"<button type="button" aria-label="on">Show only late shipments</button>","why":"الـ label يستبدل الاسم المرئي بـ «on»، وهذا أسوأ من ألّا تقول شيئًا."}],"answer":0},{"q":"

لماذا ترسم Northwind حلقات التركيز بـ outline بدل box-shadow؟

","options":[{"text":"لأن الـ outlines أسرع في الرسم.","why":"تكلفة الرسم ليست فرقًا ذا معنى هنا."},{"text":"لأن الظلال لا تستطيع استخدام الـ custom properties.","why":"تستطيع؛ أي قيمة CSS يمكن أن تأتي من custom property."},{"text":"لأن الـ outlines تُرسم دائمًا خارج صندوق الحدود، فتستحيل الإزاحة مع الظلال.","why":"كلاهما يستطيع إنشاء فجوة؛ outline-offset أسهل فقط. السبب الحاسم في مكان آخر."},{"text":"لأن أوضاع forced-colors مثل themes التباين في Windows تحذف الظلال وتُبقي الـ outlines.","why":"صحيح. الحلقة المبنية على outline تصمد أمام إعدادات التباين العالي، فيظلّ هؤلاء المستخدمون يرون التركيز."}],"answer":3}],"exercise":{"kind":"web","mode":"dom","starter":{"html":"\n

Saved 0 times

","css":":root {\n --nw-blue-600: #1f5ae0;\n --nw-blue-50: #eaf0fd;\n --nw-gray-200: #d9dee3;\n --nw-gray-500: #7b8794;\n --nw-color-action-bg: var(--nw-blue-600);\n --nw-color-action-bg-subtle: var(--nw-blue-50);\n --nw-color-text-disabled: var(--nw-gray-500);\n --nw-color-border: var(--nw-gray-200);\n --nw-focus-ring-color: var(--nw-blue-600);\n --nw-focus-ring-width: 2px;\n --nw-focus-ring-offset: 2px;\n}\n.nw-button {\n --nw-button-bg: #ffffff;\n --nw-button-text: #1f2933;\n --nw-button-border: var(--nw-color-border);\n background: var(--nw-button-bg);\n color: var(--nw-button-text);\n border: 1px solid var(--nw-button-border);\n padding: 8px 16px;\n border-radius: 6px;\n font: inherit;\n cursor: pointer;\n}\n.nw-button:focus {\n outline: none;\n}\n","js":"let saves = 0;\nconst log = document.querySelector('#log');\nconst save = document.querySelector('#save');\nconst late = document.querySelector('#late');\n\nsave.addEventListener('click', () => {\n saves += 1;\n log.textContent = `Saved ${saves} times`;\n});\n\nlate.addEventListener('click', () => {\n // Toggle the filter here\n});\n"},"solution":{"html":"\n

Saved 0 times

","css":":root {\n --nw-blue-600: #1f5ae0;\n --nw-blue-50: #eaf0fd;\n --nw-gray-200: #d9dee3;\n --nw-gray-500: #7b8794;\n --nw-color-action-bg: var(--nw-blue-600);\n --nw-color-action-bg-subtle: var(--nw-blue-50);\n --nw-color-text-disabled: var(--nw-gray-500);\n --nw-color-border: var(--nw-gray-200);\n --nw-focus-ring-color: var(--nw-blue-600);\n --nw-focus-ring-width: 2px;\n --nw-focus-ring-offset: 2px;\n}\n.nw-button {\n --nw-button-bg: #ffffff;\n --nw-button-text: #1f2933;\n --nw-button-border: var(--nw-color-border);\n background: var(--nw-button-bg);\n color: var(--nw-button-text);\n border: 1px solid var(--nw-button-border);\n padding: 8px 16px;\n border-radius: 6px;\n font: inherit;\n cursor: pointer;\n}\n.nw-button:focus-visible {\n outline: var(--nw-focus-ring-width) solid var(--nw-focus-ring-color);\n outline-offset: var(--nw-focus-ring-offset);\n}\n.nw-button[aria-pressed=\"true\"] {\n --nw-button-bg: var(--nw-color-action-bg-subtle);\n --nw-button-border: var(--nw-color-action-bg);\n}\n.nw-button[aria-disabled=\"true\"] {\n --nw-button-text: var(--nw-color-text-disabled);\n cursor: not-allowed;\n}\n","js":"let saves = 0;\nconst log = document.querySelector('#log');\nconst save = document.querySelector('#save');\nconst late = document.querySelector('#late');\n\nsave.addEventListener('click', () => {\n if (save.getAttribute('aria-disabled') === 'true') return;\n saves += 1;\n log.textContent = `Saved ${saves} times`;\n});\n\nlate.addEventListener('click', () => {\n const pressed = late.getAttribute('aria-pressed') === 'true';\n late.setAttribute('aria-pressed', String(!pressed));\n});\n"},"checks":[{"id":"focus-visible-rule","test":"const rules = [...document.styleSheets].flatMap((s) => [...s.cssRules]).filter((r) => r.selectorText); const fv = rules.filter((r) => r.selectorText.includes(':focus-visible')); const plainFocus = rules.filter((r) => /:focus(?![-\\w])/.test(r.selectorText) && /outline/.test(r.style.cssText) && /none|0px/.test(r.style.outlineStyle + r.style.outline + r.style.outlineWidth)); return fv.length > 0 && plainFocus.length === 0;"},{"id":"ring","test":"const b = $('#assign'); b.focus(); const ok = b.matches(':focus-visible') && style(b, 'outline-style') === 'solid' && style(b, 'outline-width') === '2px' && style(b, 'outline-color') === 'rgb(31, 90, 224)' && style(b, 'outline-offset') === '2px'; b.blur(); return ok;"},{"id":"toggle","test":"const b = $('#late'); click(b); await tick(); const on = b.getAttribute('aria-pressed') === 'true' && style(b, 'background-color') === 'rgb(234, 240, 253)'; click(b); await tick(); return on && b.getAttribute('aria-pressed') === 'false' && style(b, 'background-color') === 'rgb(255, 255, 255)';"},{"id":"blocked","test":"click($('#save')); await tick(); return text('#log') === 'Saved 0 times';"},{"id":"disabled-look","test":"return style('#save', 'color') === 'rgb(123, 135, 148)' && style('#save', 'cursor') === 'not-allowed';"}],"title":"ابنِ حالات التركيز والتبديل والتعطيل في المكوّن","prompt":"

شريط الأدوات هذا يخفي تركيز لوحة المفاتيح ويتجاهل حالاته. أصلحه في CSS وJS:

\n

احذف القاعدة :focus { outline: none } وأضف حلقة :focus-visible: ‏outline صلبًا يستخدم --nw-focus-ring-width و--nw-focus-ring-color مع outline-offset بقيمة --nw-focus-ring-offset.
اجعل Show only late زر تبديل حقيقيًا: كل نقرة تقلب aria-pressed بين "true" و"false". وحين يكون مضغوطًا تكون خلفيته --nw-color-action-bg-subtle وحدّه --nw-color-action-bg.
الزر Save route يحمل aria-disabled="true": يجب ألّا يحفظ عند النقر، ويستخدم نصّه --nw-color-text-disabled، ويكون المؤشر فوقه not-allowed.

\n","hints":["نسّق الحالات بسماتها: .nw-button[aria-pressed="true"] و.nw-button[aria-disabled="true"]. وخصّص الـ component tokens داخلها.","في معالج النقر لزر التبديل، اقرأ aria-pressed ثم اجعله عكس قيمته بـ setAttribute('aria-pressed', String(!pressed)).","في أول معالج الحفظ، استخدم return مبكرًا حين يكون save.getAttribute('aria-disabled') === 'true'."],"explanation":"

صارت الحلقة تظهر مع تركيز لوحة المفاتيح عبر :focus-visible، وهي مأخوذة من tokens، فيستطيع كل مكوّن وكل theme مشاركتها. وشكل زر التبديل تقوده aria-pressed، فلا يمكن أن تختلف الحالة المرئية عن الحالة المُعلَنة أبدًا. وaria-disabled تُبقي زر الحفظ قابلًا للتركيز حتى يمكن الوصول إلى شرحه عبر aria-describedby، ولهذا يجب أن يحرس معالج النقر الإجراء بنفسه. في النظام الحقيقي يفعل مكوّن Button كل هذا داخليًا، وتحصل عليه الفرق افتراضيًا.

\n","checkLabels":{"focus-visible-rule":"تنسيق التركيز يستخدم :focus-visible، ولا توجد قاعدة :focus تحذف الـ outline","ring":"تركيز لوحة المفاتيح يُظهر حلقة صلبة بعرض 2px بلون التركيز مع إزاحة 2px","toggle":"النقر على Show only late يقلب aria-pressed ونمط الضغط معه","blocked":"النقر على زر Save المعلَّم بـ aria-disabled لا يحفظ","disabled-look":"يستخدم زر Save لون النص المعطّل ومؤشر not-allowed"}},"words":607,"readMinutes":4}