---
title: "حقل اللون"
description: "يتيح للناس تعيين لون واحد حقلًا من حقول النموذج، بقيمة نصية يقرؤونها ويكتبونها ويلصقونها، وعيّنة منها بجانب النص، وزر يطلب منتقيًا. وهو يُرسم ويُقاس كما يُرسم ويُقاس حقل النص."
url: "https://tanrei.chnotchy.com/ar/components/color-field/"
last_updated: 2026-10-23T21:17:12.000Z
---

# حقل اللون

> يتيح للناس تعيين لون واحد حقلًا من حقول النموذج، بقيمة نصية يقرؤونها ويكتبونها ويلصقونها، وعيّنة منها بجانب النص، وزر يطلب منتقيًا. وهو يُرسم ويُقاس كما يُرسم ويُقاس حقل النص.

## نظرة عامة

استخدم حقل اللون حيث يعيّن الناس لونًا على أنه قيمة: لون العلامة التجارية في سمة، أو لون تصنيف أو فئة. يقرؤونه، أو يكتبونه، أو يلصقونه من أداة أخرى، ويرون عيّنة منه بجانب النص. ويُرسم الحقل ويُقاس كما يُرسم ويُقاس حقل النص الذي له الطراز نفسه والحجم نفسه.

**يُبنى من** [حقل](https://tanrei.chnotchy.com/ar/components/field/) و [حقل إدخال اللون](https://tanrei.chnotchy.com/ar/components/color-input/). الحقل هو الإطار: التسمية، وعلامة المطلوب أو الاختياري، والمساعدة، والخطأ. وحقل إدخال اللون هو عنصر التحكم: الصندوق، ومربع اللون (swatch)، والقيمة نصًّا، وزر المنتقي. وحقل اللون لا يرسم شيئًا من عنده وليس له أي رمز تصميم (token): فكل خاصية له هي خاصية لأحد الاثنين، تُعطى له كما هي.

هو كتلة بعرض المكان الذي يوضع فيه، وصندوقه يملؤه. وليس له عرض من عنده: فلحقل أضيق أعطِه مكانًا أضيق. وهو حقل أصلًا، فلا يوضع أبدًا داخل [حقل](https://tanrei.chnotchy.com/ar/components/field/).

ولا يرسم منتقيًا من عنده. مع `picker` يطلب زر في النهاية منتقيًا: منتقي المتصفح، أو سطحًا يعرضه المنتج.

على الويب هو `<tanrei-color-field>`. والمنصات الأخرى لم تنفّذه بعد.

### الاستخدام

الخاصية `value` علامة الرقم وستة أرقام سداسية عشرية بأحرف صغيرة (`#0f766e`)، أو سلسلة فارغة حين لا يوجد لون. وليست أبدًا نصًّا نصف مكتوب: ما دام حقل الإدخال يحمل ما ليس لونًا، تكون `value` فارغة.

**Web**

```html
<form>
  <tanrei-color-field name="brand" label="لون العلامة التجارية" value="#0f766e"
    required required-text="مطلوب"
    supporting-text="ستة أرقام سداسية عشرية، مثل &lrm;#0f766e."
    invalid-text="أدخِل ستة أرقام سداسية عشرية، مثل &lrm;#0f766e."
    picker picker-label="اختيار لون"></tanrei-color-field>
</form>

<script type="module">
  import '@tanrei/web/components/color-field';

  const brand = document.querySelector('tanrei-color-field');
  // تغيّرت القيمة: لون، أو سلسلة فارغة. وهي الآن القيمة الجديدة.
  brand.addEventListener('input', () => preview(brand.value));
  // اعتمد الشخص قيمة تغيّرت: غادر التركيز، أو ضُغط المفتاح Enter، أو أُغلق المنتقي.
  brand.addEventListener('change', () => save(brand.value));
  // اعتُمد نص ليس لونًا. يحتفظ به الحقل ويعرض invalidText،
  // وهو أيضًا ما تحمله detail.message.
  brand.addEventListener('entryerror', (e) => console.log(e.detail.text, e.detail.message));
  // لعرض منتقٍ من عندك: ألغِ الطلب، وافتح المنتقي، واضبط value على ما اختير.
  brand.addEventListener('pickerrequest', (e) => {
    e.preventDefault();
    openMyPicker(e.detail.value).then((color) => (brand.value = color));
  });
</script>
```

**React**

```tsx
import { ColorField } from '@tanrei/react';

<ColorField label="لون العلامة التجارية" value={brand} picker pickerLabel="اختيار لون"
  invalidText="أدخِل ستة أرقام سداسية عشرية، مثل &lrm;#0f766e."
  onChange={(event) => setBrand(event.currentTarget.value)} />
```

### مستوى واحد إلى الأسفل

الحقل نفسه مكتوبًا باليد من عضويه هو الصورة نفسها، ومربع النص (text box) نفسه عند التقنيات المساعدة، بالاسم والوصف والحالات نفسها:

```html
<tanrei-field label="لون العلامة التجارية" required required-text="مطلوب"
  supporting-text="ستة أرقام سداسية عشرية، مثل &lrm;#0f766e.">
  <tanrei-color-input name="brand" value="#0f766e"
    invalid-text="أدخِل ستة أرقام سداسية عشرية، مثل &lrm;#0f766e."
    picker picker-label="اختيار لون"></tanrei-color-input>
</tanrei-field>
```

انزل مستوى واحدًا حين تحتاج إلى ترتيب لا يقدّمه حقل اللون:

| تحتاج إلى | استخدم |
| --- | --- |
| تسمية وصندوق ومساعدة وخطأ | حقل اللون |
| شيء من عندك داخل الإطار، بجانب الصندوق أو تحته | [حقل](https://tanrei.chnotchy.com/ar/components/field/) بداخله [حقل إدخال اللون](https://tanrei.chnotchy.com/ar/components/color-input/) وعنصرك أنت |
| الصندوق وحده، في صف أو عمود يسمّي اللون أصلًا: درجات لوحة ألوان، أو خلية في جدول | [حقل إدخال اللون](https://tanrei.chnotchy.com/ar/components/color-input/) وحده، وتسمّيه `label` الخاصة به |

ما يتغيّر في المستوى الأدنى هو الموضع الذي يُقال فيه كل شيء. الخاصيتان `name` و `value` تكونان على حقل إدخال اللون، وهو عندئذ عنصر التحكم الذي يلقاه النموذج، وأحداثه تُسمع عليه. أما `label` و `error` و `disabled` والمطلوب أو الاختياري فتبقى على الحقل، وهو يمرّرها إلى عنصر التحكم: فلا تعيّن ما يخص حقل الإدخال منها. وحقل اللون لا يفعل شيئًا لا يفعله الحقل وحقل إدخال اللون المكتوبان باليد.

## المواصفات

### الحقل

| الجزء | ما هو |
| --- | --- |
| التسمية | فوق الحاوية (في الطراز `stacked`) حيث يرسمها الحقل، أو عائمة داخلها (في الطرازين `filled` و `outlined`) حيث يرسمها حقل إدخال اللون. وهي الاسم المتاح للتقنيات المساعدة، سواء رُسمت أم أُخفيت بالخاصية `labelHidden` |
| علامة المطلوب أو الاختياري | بعد التسمية: وسم المطلوب أو نجمة أو لا شيء حين تكون `required`، ووسم الاختياري حين تكون `optional` |
| مربع اللون | عيّنة من القيمة في بداية الحاوية: مربع صغير معبَّأ بلون القيمة بالضبط، داخل خط رفيع. وحين يكون الحقل فارغًا فهو الخط الرفيع وحده. وليس عنصر تحكم |
| حقل الإدخال | القيمة نصًّا. سطر واحد، يُمرَّر |
| زر المنتقي | مع `picker`: زر من الطراز text بأيقونة وحدها في النهاية، تسمّيه الخاصية `pickerLabel` |
| النص المساعد | سطر مساعدة، يبدأ حيث يبدأ نص القيمة، بعد مربع اللون. وما دام الحقل في حالة الخطأ يأخذ نص الخطأ مكانه (أو يُرسم تحته، حيث يُبقي نظام التصميم الاثنين)، وهو `errorText` ما دامت `error` بالقيمة true، و `invalidText` ما دام النص المعتمد ليس لونًا، أو `errorText` حيث تكون `invalidText` فارغة |

الطُرُز الثلاثة والأحجام الثلاثة، `small` (32) و `medium` (40) و `large` (56)، هي طُرُز حقل النص وأحجامه. والنظام الافتراضي يتضمن الطراز `stacked` وحده. ويقف مربع اللون حيث تقف أيقونة البداية في حقل النص، بحجم تلك الأيقونة، فحقل اللون الذي تحت حقل نص له أيقونة بداية يشاركه حواف البداية.

لا يُمزج شيء في مربع اللون: لا تحويم، ولا صبغة خطأ، ولا ظل. العيّنة التي تتغيّر تحت مؤشر الإدخال عيّنة خاطئة. وحين يكون الحقل معطَّلًا تُرسم تعبئة المربع أبهت وتبقى حافته.

### القيمة والنص

| متى | ما يحدث |
| --- | --- |
| يكتب الشخص أو يلصق أو يُملي | لا يُرفض شيء ولا يُعاد كتابة شيء. يُقرأ النص كله: إن كان لونًا فقيمة `value` ذلك اللون، وإلا فهي فارغة. ويصدر الحدث `input` حين تتغيّر `value` |
| يغادر التركيز، أو يُضغط المفتاح Enter | يُعتمد النص. ويُكتب اللون من جديد بصورة القيمة نفسها. ويصدر الحدث `change` إن اختلفت القيمة عن آخر قيمة معتمدة |
| النص المعتمد ليس لونًا | يبقى النص. يكون الحقل في حالة خطأ ويعرض `invalidText`، ويصدر الحدث `entryerror`. وينتهي الخطأ عند التعديل التالي |
| النص فارغ | تكون `value` فارغة. وليس ذلك خطأ من الحقل أبدًا |
| يضبط المنتج `value` | يُعرض اللون، أيًّا كان ما كُتب. ولا يصدر أي حدث |

يُقرأ النص لونًا حين يكون، بعد حذف المسافات التي حوله، ستة أرقام سداسية عشرية بالضبط، بأحرف كبيرة أو صغيرة، مع علامة الرقم أو من دونها: `0F766E` و `#0f766e` و ` #0F766E ` كلها `#0f766e`.

وكل ما سوى ذلك ليس لونًا: ثلاثة أرقام (`#0f7`)، أو ثمانية (`#0f766e80`)، أو اسم (`teal`)، أو صيغة دالّية (`rgb(15, 118, 110)`). والأرقام الثلاثة ليست لونًا أثناء الكتابة، لأن النص يمرّ بها في طريقه إلى الستة؛ وعند اعتماد النص تُقرأ كما تقرؤها CSS، ستةَ أرقام يتكرر فيها كل رقم: فيصير `#0f7` اللونَ `#00ff77`. وليس هناك قناة ألفا (alpha) ولا ألوان واسعة النطاق (wide gamut).

لا يُبلَّغ عن شيء ما دام الشخص يكتب. ولا يُرفع خطأ إدخال إلا حين يعتمد ما كتبه.

### المنتقي

مع `picker` يعرض الحقل زرًّا في نهايته. تفعيله يُصدر الحدث `pickerrequest`، وهو يحمل القيمة.

| المنتج | ما يحدث |
| --- | --- |
| لا يفعل شيئًا | يعرض الحقل منتقي الألوان الخاص بالمتصفح. كل اختيار تعديل من الشخص: النص، ومربع اللون، والحدث `input`. وحين يُغلق المنتقي يصدر الحدث `change` ويكون التركيز على زر المنتقي |
| يلغي الطلب | لا يعرض الحقل شيئًا. يفتح المنتج سطحه هو، مرتكزًا على الحقل، ويضبط `value` على ما اختير. وذلك السطح يعيد التركيز إلى زر المنتقي حين يُغلق |

حين يظهر زر المنتقي، يفتح الضغط على مربع اللون المنتقي كما يفعل الضغط على الزر؛ ولا ينتقل التركيز إلى حقل الإدخال، ويبقى الزر طريق لوحة المفاتيح. ومن دون الزر، ينقل الضغط على مربع اللون التركيز إلى حقل الإدخال، كما يفعل الضغط في أي مكان آخر من الحقل.

### ما يعطيه كل عضو

- **من الحقل**: الخصائص `label` و `labelHidden` و `supportingText` و `errorText` و `error` و `disabled` و `required` و `optional` و `requiredMark` و `requiredText` و `optionalText`؛ والمنفذ (slot) `label-icon`؛ ورموز التصميم `comp.field.*`.
- **من حقل إدخال اللون**: الخصائص `variant` و `size` و `value` و `invalidText` و `picker` و `pickerLabel`؛ والأحداث `input` و `change` و `pickerRequest` و `entryError`؛ ورموز التصميم `comp.input-box.*` للصندوق، وهي التي يقرؤها كل صندوق إدخال، و `comp.color-input.*` لمربع اللون.

لحقل إدخال اللون `label` و `labelHidden` و `error` و `disabled` خاصة به. وهي ليست ما يعيّنه حقل اللون: فالخاصية `label` فيه هي تسمية الحقل، وهي تسمّي حقل الإدخال، وفي الحقل من الطراز filled أو outlined هي ما يعوم في الصندوق.

### رموز التصميم

ليس لحقل اللون رمز تصميم خاص به. صندوقه يقرأ [رموز تصميم حقل إدخال اللون](https://tanrei.chnotchy.com/ar/components/color-input/#%D8%A7%D9%84%D9%85%D9%88%D8%A7%D8%B5%D9%81%D8%A7%D8%AA)، وصفوفه، أي التسمية والعلامة والمساعدة والخطأ، تقرأ [رموز تصميم الحقل](https://tanrei.chnotchy.com/ar/components/field/#%D8%A7%D9%84%D9%85%D9%88%D8%A7%D8%B5%D9%81%D8%A7%D8%AA)، أينما عُيِّنت. والجدول أدناه يسرد رموز الحقل. ولتغيير مثيل واحد، عيِّن رمز تصميم العضو عليه:

```html
<tanrei-color-field label="لون العلامة التجارية"
  style="--tanrei-comp-field-label-gap: 12px"></tanrei-color-field>
```

- Category: Text inputs
- Level: composed
- Listing: default
- Built from: Field, Color input
- Page: https://tanrei.chnotchy.com/components/color-field/
- Spec: https://github.com/chnotchy/tanrei/blob/main/specs/color-field.spec.json

### Availability

| Design system | Has it | Notes |
| --- | --- | --- |
| Tanrei (`tanrei`) | Yes | Variants left out: `filled`, `outlined`. |
| Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — |
| M3 Expressive-like (Material 3 Expressive-inspired) (`m3-expressive-like`) | Yes | — |
| M3-like (Material 3-inspired) (`m3-like`) | Yes | — |

### Platforms

- Web: the element `<tanrei-color-field>`, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/color-field`).
- React: `ColorField` from `@tanrei/react`.

| Platform | Name | Status |
| --- | --- | --- |
| Web | `tanrei-color-field` | lagging |
| SwiftUI | `TanreiColorField` | planned |
| Jetpack Compose | `TanreiColorField` | planned |
| Flutter | `TanreiColorField` | planned |
| React Native | `ColorField` | planned |

Names a platform gives in its own idiom:

| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
| --- | --- | --- | --- | --- | --- |
| `value` (prop) | `value` | `hex` | `value` | `controller` | `value` |
| `label` (prop) | `label` | `label` | `label` | `labelText` | `label` |
| `labelHidden` (prop) | `labelHidden` | `labelsHidden` | `labelHidden` | `labelHidden` | `labelHidden` |
| `supportingText` (prop) | `supportingText` | `supportingText` | `supportingText` | `helperText` | `supportingText` |
| `error` (prop) | `error` | `error` | `isError` | `isError` | `error` |
| `disabled` (prop) | `disabled` | `disabled` | `enabled` | `enabled` | `disabled` |
| `required` (prop) | `required` | `isRequired` | `required` | `required` | `required` |
| `optional` (prop) | `optional` | `isOptional` | `optional` | `optional` | `optional` |
| `picker` (prop) | `picker` | `showsPicker` | `onPickerRequest` | `onPickerRequest` | `onPickerRequest` |
| `pickerLabel` (prop) | `pickerLabel` | `pickerLabel` | `pickerContentDescription` | `pickerSemanticLabel` | `pickerAccessibilityLabel` |
| `input` (event) | `input` | `hex` | `onValueChange` | `onChanged` | `onValueChange` |
| `change` (event) | `change` | `onCommit` | `onCommit` | `onCommit` | `onEndEditing` |
| `pickerRequest` (event) | `pickerrequest` | `onPickerRequest` | `onPickerRequest` | `onPickerRequest` | `onPickerRequest` |
| `entryError` (event) | `entryerror` | `onEntryError` | `onEntryError` | `onEntryError` | `onEntryError` |

Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal.

### Anatomy

- `field`: The Field: the label row with its glyph and its requirement mark, and the supporting row with the help and the error text. In a look whose input floats the label it draws no label row.
- `color-input`: The color input, as the Field's one control: the box, the swatch, the value as text, the picker button, and the label that floats in the box in the looks that float one.

### Props

| Prop | Type | Default | Web attribute | Description |
| --- | --- | --- | --- | --- |
| `variant` | `enum`: `stacked`, `filled`, `outlined` | `"stacked"` | `variant` | The text input's three looks, so that a color input is drawn as the text inputs beside it. Stacked is a filled box that shows focus and error with a line inside its edge and draws no label: the label of the Field that frames it stands above it. Filled and outlined float the label inside the box. Use one style per form. A design system may leave some out (the Tanrei system ships stacked only) or add values. (From Color input.) |
| `size` | `enum`: `small`, `medium`, `large` | `"medium"` | `size` | Minimum height of the container: stacked 32 / 40 / 56, as tall as a Button of the same size, so that the box and a Button side by side in one row stand as tall as each other; filled and outlined 40 / 48 / 56, which hold the label that floats inside them. These are the text input's three sizes, small for a bar, a toolbar or a dense row of controls. The hit area always meets the minimum target. A design system may add values. (From Color input.) |
| `value` | `string` | `""` | `value` | The color the input holds: a number sign and six hexadecimal digits in lowercase ("#0f766e"), an opaque sRGB color; or empty for no color. It is never a half-typed text: while the input holds something that is not a color, value is empty. (From Color input: What the color field reports as its own is the value its color input holds, in that value's own form (CLF-43, CLI-16, CLI-21).) |
| `label` | `string` | `""` | `label` | Names the control, visibly and to assistive technology. Required, unless the control names itself (a checkbox or a switch with its own label): then leave it empty and the field adds only help and an error. (From Field: Names the color input. In a filled or outlined look the input draws it, floating in its box, and the Field draws no label row (FLD-25, CLI-15).) |
| `labelHidden` | `boolean` | `false` | `label-hidden` | Does not draw the label, which stays the accessible name. For a control whose visible label is elsewhere (a table column, a toolbar). (From Field: Hides the label wherever it would be drawn: the Field's row, or the input's floating label (FLD-25).) |
| `supportingText` | `string` | `""` | `supporting-text` | Help shown below the control and given to assistive technology as the control's description. While the field is in error it gives way to errorText, unless the design system keeps both (comp.field.error-text.placement append). (From Field.) |
| `errorText` | `string` | `""` | `error-text` | Shown while error is true, in supportingText's place — or below it, which then stays, where the design system's comp.field.error-text.placement is append: what is wrong and how to put it right, in words. (From Field.) |
| `error` | `boolean` | `false` | `error` | Puts the field in the error condition: the error text is drawn, the control is exposed as invalid and, where it has an error condition of its own, drawn in it. What a value means is the product's to validate; the field never sets this itself. (From Field: The Field puts its color input in the input's own error condition (FLD-8, CLI-9).) |
| `disabled` | `boolean` | `false` | `disabled` | Disables the control and draws the frame as disabled. Disable a framed control here, not on the control, so that its label follows. (From Field: The Field disables its color input, the picker button with it (FLD-14, CLI-31); the color field is then left out of its form (CLF-44).) |
| `required` | `boolean` | `false` | `required` | What the form asks of the control: true exposes it as required and draws the required mark beside the label. It never validates: a missing answer is the product's to report with error. (From Field: The Field exposes its color input as required (FLD-10, CLI-11).) |
| `optional` | `boolean` | `false` | `optional` | Draws the optional tag after the label and adds optionalText to the control's description, because assistive technology has no state for it. Ignored while required is true: a control is never both. (From Field.) |
| `requiredMark` | `enum`: `auto`, `tag`, `asterisk`, `none` | `"auto"` | `required-mark` | How this control shows that it is required: tag is a small filled Tag with requiredText, asterisk is "*" after the label, none draws nothing and keeps the semantics. Auto takes comp.field.requirement.mark, which follows sys.behavior.requirement-mark, the system's one answer. Ignored unless required is true. (From Field.) |
| `requiredText` | `string` | `""` | `required-text` | The text of the required tag, in the product's language ("Required", "必須"). The product's: Tanrei has no word for it. Empty reads the product's words; with neither, FLD-24 says what is drawn. (From Field.) |
| `optionalText` | `string` | `""` | `optional-text` | The text of the optional tag, in the product's language ("Optional", "任意"); also read to assistive technology as part of the description. The product's: Tanrei has no word for it. Empty reads the product's words. (From Field.) |
| `invalidText` | `string` | `""` | `invalid-text` | The words for an input committed with a text that is not a color ("Enter six hexadecimal digits, like #0f766e"), in the product's language: given to the Field that frames the input, which shows them as its error text (CLI-20). While it is empty that Field shows its own errorText. (From Color input: Shown by the Field, in its supporting row (FLD-28).) |
| `picker` | `boolean` | `false` | `picker` | Shows the picker button. Activated, it emits pickerRequest, and where the platform has a color picker of its own the input presents that picker unless the product cancelled the request. The input draws no picker surface itself. (From Color input.) |
| `pickerLabel` | `string` | `""` | `picker-label` | The accessible name of the picker button ("Choose color"). Required while picker is shown. (From Color input.) |

### Events

| Event | Description |
| --- | --- |
| `input` | The person changed the value — by an edit of the text that made it a color, another color or no color, or by a pick in the platform's picker; carries the new value. Not emitted when the product sets value, nor for an edit that leaves value as it was. (From Color input.) |
| `change` | The person committed a changed value: focus left the input, the action key was pressed, or the platform's picker closed; carries the value. (From Color input.) |
| `pickerRequest` | The person activated the picker button; carries the value. Cancelling it keeps the input from presenting the platform's picker: the product then presents its own surface and sets value to what was picked. (From Color input.) |
| `entryError` | The person committed a text that is not empty and is not a color; carries the text as typed and invalidText, the words the input has for it (empty where the product gave none: the Field that frames the input then shows its own errorText). (From Color input.) |

### Slots

| Slot | Description |
| --- | --- |
| `label-icon` | A glyph before the label. (From Field.) |

### States

`enabled`, `disabled`, `hovered`, `focused`, `error`

### Accessibility

- Role: `textbox`
- Labeling: The color field adds nothing to what its members expose and coordinates nothing: the Field gives the color input its name, its description and its required, invalid and disabled states (FLD-8, FLD-10, FLD-11, FLD-14), and the color input carries them on its own element (CLI-11). Assistive technology meets one text box named by label whose value is the color as text, and, while picker is true, one button named by pickerLabel — exactly as it meets a Field around a color input written by hand.
- Minimum target size: yes

| Keys | Action |
| --- | --- |
| Every key | The color input's (its accessibility block; CLI-13, CLI-19, CLI-28). The color field handles no key and adds no focus stop (CLF-45). |

- One level down is the same thing: a Field with a color input in it. Every fixture has that pair as its twin, and the accessibility tree of the two is the same (CLF-43).
- On the web the two members stand in the color field's own shadow root, so the form meets the color field and not the input (CLF-44); focus passes through to the input (CLF-45).
- The color is never told by the swatch alone (WCAG 1.4.1), an error is always words (WCAG 3.3.1), and the swatch alone keeps its color in forced colors: each is the color input's or the Field's, and is said there (CLI-25, CLI-35, FLD-7, FLD-17).

### Behaviour

Requirements in EARS form, each with its stable id.

- **CLF-43** THE color field SHALL be a Field that frames one color input, and nothing else. It SHALL give label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText and optionalText to its Field and variant, size, value, invalidText, picker and pickerLabel to its color input, each unchanged; SHALL hold the label-icon slot for its Field; and SHALL emit its color input's events as its own, each once. THE color field SHALL be as wide as the place it stands in, and its color input SHALL fill it: it is a block with no width of its own, as its Field is (FLD-1), around a control that fills the width it is given (CLI-44). Its value SHALL at every moment be the value its color input holds — a color in the value's own form, or the empty string (CLI-16) — and not the text the product set where the two differ (CLI-21). It SHALL draw no part of its own, hold no state of its own and have no token of its own: what it shows, how it behaves and what it exposes to assistive technology SHALL be exactly what that Field and that color input do when a product places the one in the other (FLD-1 to FLD-28; CLI-1 to CLI-44) — the label row and its requirement mark (FLD-2 to FLD-6), or the label that floats in the box with the Field's row left out (FLD-25, CLI-15, CLI-7); the supporting row, started at the value's text, after the swatch (FLD-7 to FLD-9, FLD-26, CLI-43); the name, the description and the states (FLD-10, FLD-11, FLD-14, CLI-11); and the entry error of a text that is not a color, shown in the Field's row (FLD-28, CLI-20).
- **CLF-44** WHERE the platform has forms (the web) THE color field SHALL be the one control the form sees: it SHALL take name, submit its color input's value, reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its color input would report there (CLI-11, CLI-20), and be left out WHILE disabled is true or a disabled group of the form holds it; its color input and its Field SHALL take no part in the form themselves. WHEN the action key asks for the form's submission (CLI-19) the form asked SHALL be the color field's own.
- **CLF-45** WHEN the color field is given focus — by the product, by a press on any part of it that FLD-12 or CLI-24 gives to the input, or by a form that reports its validity — THE color field SHALL pass the focus to the input of its color input, never to the picker button, and SHALL add no stop to the focus order: the stops inside it are its color input's, in that input's order (the input, then the picker button while it is shown, CLI-13). WHILE focus is anywhere inside it, the picker button included, THE color field SHALL count as focused for its Field, whose rows take their focused colors (FLD-13); the box takes its own only WHILE its input has focus (CLI-22). WHEN a picker the color input presented closes, focus SHALL be on the picker button (CLI-29), inside the color field.
- **CLF-46** IF the color field is placed in a Field THE color field SHALL in debug builds report that it is a field already and that the bare control is the color input, and both SHALL still render (FLD-15). WHILE it stands in a field group THE color field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-20).
- **CLF-47** THE color field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), each from the instance's prop and then from the product's words; invalidText and pickerLabel are the instance's alone and are given to its color input as they are (CLI-42).
- **CLF-48** WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE color field SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the color field is invalid — except those the color field owns (aria-label, aria-labelledby, aria-disabled), which it SHALL move and not expose: its name is label (CLF-43). WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE color field SHALL take it off that element. WHEN the product sets an aria- attribute the color field owns THE color field SHALL report it in debug builds.

### Tokens

As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.field.…` → `--tanrei-comp-field-…`).

#### `tanrei.comp.field`

| Token | Type | Value |
| --- | --- | --- |
| `comp.field.label.typescale` | `typography` | `{tanrei.sys.typescale.label}` |
| `comp.field.label.gap` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.field.label-icon.size` | `dimension` | `{tanrei.sys.icon.small}` |
| `comp.field.label-icon.gap` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.field.requirement.mark` | `number` | `{tanrei.sys.behavior.requirement-mark}` |
| `comp.field.requirement.gap` | `dimension` | `{tanrei.sys.space.space100}` |
| `comp.field.requirement.asterisk-gap` | `dimension` | `{tanrei.sys.space.space25}` |
| `comp.field.supporting-text.typescale` | `typography` | `{tanrei.sys.typescale.label-small}` |
| `comp.field.supporting-text.gap` | `dimension` | `{tanrei.sys.space.space50}` |
| `comp.field.counter.gap` | `dimension` | `{tanrei.sys.space.space200}` |
| `comp.field.motion.state-duration` | `duration` | `{tanrei.sys.motion.role.state.default}` |
| `comp.field.motion.state-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` |
| `comp.field.standard.label.color` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.field.standard.label-icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.supporting-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.counter.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.required-asterisk.color` | `color` | `{tanrei.sys.color.primary}` |
| `comp.field.standard.error.label.color` | `color` | `{tanrei.sys.color.on-surface}` |
| `comp.field.standard.error.label-icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.error.supporting-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.error.counter.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.error.required-asterisk.color` | `color` | `{tanrei.sys.color.primary}` |
| `comp.field.standard.error.value-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.value-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` |
| `comp.field.standard.error-text.color` | `color` | `{tanrei.sys.color.error}` |
| `comp.field.value-text.typescale` | `typography` | `{tanrei.sys.typescale.label}` |
| `comp.field.value-text.gap` | `dimension` | `{tanrei.sys.space.space200}` |
| `comp.field.error-text.gap` | `dimension` | `{tanrei.sys.space.space50}` |
| `comp.field.error-text.placement` | `number` | `0` |

Per-state tokens, valued by the design system's pattern rules (not written by hand):

- `comp.field.<variant>.<state>.<property>` for the variants `standard`, the states `focused`, `disabled` and the properties `label.color`, `label-icon.color`, `supporting-text.color`, `required-asterisk.color`, `error.label.color`, `error.label-icon.color`, `error.supporting-text.color`, `error.required-asterisk.color`, `counter.color`, `error.counter.color`, `value-text.color`, `error.value-text.color`, `error-text.color`.

### ما يرسمه الويب بطريقة مختلفة

- جذر الظل (shadow root) في العنصر فيه عنصر `<tanrei-field>` بداخله عنصر `<tanrei-color-input>`، ولا شيء غيرهما. واستيراد العنصر يعرّف الاثنين.
- حقل اللون عنصر مرتبط بالنماذج (form-associated). يأخذ `name` ويرسل `value`: اللون، أو سلسلة فارغة. ويعود عند إعادة الضبط إلى قيمة خاصية HTML `value`، ويبلّغ النموذج بأن القيمة ناقصة ما دامت `required` و `value` فارغة، وبأن الإدخال غير صالح ما دام خطأ الإدخال قائمًا. وعضواه لا يضيفان أي مُدخلة (entry) إلى النموذج.
- الخاصية `value` هي دائمًا قيمة حقل إدخال اللون: فالقيمة التي تُعيَّن `0F766E` تُقرأ `#0f766e`، والتي ليست لونًا تُقرأ سلسلة فارغة.
- الحدثان `input` و `change` حدثان عاديان: اقرأ `value` من العنصر. أما `pickerrequest` و `entryerror` فمن النوع CustomEvent، الأول مع `detail.value` والثاني مع `detail.text` و `detail.message`. وهما حدثا حقل إدخال اللون نفسه، وهدفهما العنصر. و `detail.message` هي `invalidText`، وتكون فارغة حيث لم تعطِ نصًّا، حتى حين يعرض الحقل `errorText` مكانها.
- الأجزاء: `field` و `color-input` هما العضوان. وأجزاؤهما لها هنا الأسماء نفسها التي لها في المستوى الأدنى: `label-icon`، `supporting-text`؛ `container`، `outline`، `active-indicator`، `swatch`، `input`، `picker-button`. والجزءان `label` و `requirement-label` هما المرسومان، أيًّا كان العضو الذي يرسمهما؛ أما `field-label` و `color-input-label` و `field-requirement-label` و `color-input-requirement-label` فتسمّي ما يخص عضوًا واحدًا.
- العنصر نفسه غير قابل للتركيز وليس له دور: فالدالة `focus()` تذهب إلى حقل الإدخال، لا إلى زر المنتقي أبدًا. والضغط على صف التسمية أو على الصندوق أو على مربع اللون (حين لا يكون هناك زر منتقٍ) أو على تسمية عائمة ينقل التركيز إلى حقل الإدخال. والضغط على المساعدة أو نص الخطأ لا يفعل شيئًا.
- التسمية والمساعدة تأخذان ألوان حالة التركيز ما دام التركيز في أي مكان من الحقل، ومنه زر المنتقي. والصندوق لا يأخذ ألوانه هو إلا ما دام التركيز على حقل الإدخال فيه.
- سمِّه بالخاصية `label`، ومعها `label-hidden` حيث لا يُراد رسم التسمية، ولا تسمِّه أبدًا بالخاصية `aria-label`، فهي لا تسمّي شيئًا هنا.
- ليس للعنصر كلمات من عنده. الخاصيتان `requiredText` و `optionalText` فارغتان إلى أن تعطيهما. والحقل المطلوب بلا `requiredText` يعرض النجمة حيث كان الوسم سيقف.
- منتقي المتصفح يختلف من متصفح إلى آخر: نافذة منبثقة من الصفحة في Chromium، ونافذة الألوان الخاصة بالنظام في Firefox و Safari. ومظهره وموضعه ومفاتيحه شأن المتصفح.
- النص المكتوب بأحرف كاملة العرض (`＃０ｆ７６６ｅ`) لا يُقرأ لونًا.
- قبل أن يُعرَّف العنصر لا حجم له. احجز الارتفاع.

## الإرشادات

### حقل اللون أم حقل النص

| الجانب | حقل اللون | حقل النص |
| --- | --- | --- |
| يحمل | لونًا واحدًا، على صورة `#` وستة أرقام | أي نص |
| يعرض | عيّنة من اللون بجانب النص | النص |
| يتحقق | من أن النص لون | لا يتحقق من شيء |

للّون الذي يُعرض ولا يُعدَّل، ارسم عيّنة ومعها قيمته أو اسمه نصًّا بجانبها. حقل اللون للون يعيّنه الناس.

### افعل

- اكتب تسمية تقول لأي شيء اللون، وأبقِها ظاهرة في النموذج.
- قل صورة القيمة في `supportingText`. فهو يبقى ما دام الحقل في حالة الخطأ، ولذلك لا حاجة إلى تكرارها في `invalidText`.
- سمِّ اللون بالكلمات في `supportingText` حيث يهمّ ذلك («أزرق مخضرّ»). القيمة السداسية العشرية لا تقول كثيرًا عن مظهر اللون.
- أعطِ `pickerLabel` كلما ضُبطت `picker`.
- تحقق بنفسك مما يعنيه اللون، كتباينه مع خلفية أو كونه لونًا مأخوذًا أصلًا، وقله بالخاصيتين `error` و `errorText`.
- استخدم [حقل إدخال اللون](https://tanrei.chnotchy.com/ar/components/color-input/) في صف يسمّي كل لون أصلًا، كدرجات لوحة ألوان: فهو الصندوق وحده، وتسمّيه `label` الخاصة به.

### لا تفعل

- لا تعرِّف اللون بمربع اللون وحده. القيمة نص؛ ومن لا يستطيع التمييز بين عيّنتين يقرأ قيمتين مختلفتين.
- لا تعامل `value` الفارغة على أنها خطأ بنفسها. الخاصية `required` لا تتحقق من شيء أبدًا.
- لا تضبط `aria-invalid` ولا `error` ما دام الشخص يكتب. انتظر `change` أو `entryerror`.
- لا تضع حقل لون داخل حقل. فهو حقل أصلًا؛ وعنصر التحكم الذي يؤطّره الحقل هو [حقل إدخال اللون](https://tanrei.chnotchy.com/ar/components/color-input/).

## إمكانية الوصول

### ما يتكفل به المكوّن

- حقل الإدخال حقل نص. اسمه قيمة `label`، مرسومةً أو مخفية، وقيمته النص الذي يعرضه.
- النص المساعد أو نص الخطأ المعروض هو وصفه، ومعه `optionalText` ما دام الحقل اختياريًّا.
- يُعرض على أنه غير صالح ما دامت `error` بالقيمة true أو ما دام خطأ إدخال قائمًا، وعلى أنه مطلوب ما دامت `required` معيَّنة.
- الخطأ الذي يظهر والتركيز على الحقل يُعلَن مرة واحدة، بتهذيب. ولا يأخذ التركيز أبدًا.
- مربع اللون زخرفي ومخفي عن التقنيات المساعدة: نص القيمة هو الذي يقول اللون.
- زر المنتقي زر مستقل، تسمّيه الخاصية `pickerLabel`، ويُعرض على أنه يفتح مربع حوار. وهو موضع توقف للتركيز بعد حقل الإدخال. والتركيز الذي يُعطى للحقل نفسه يذهب دائمًا إلى حقل الإدخال.
- لا يُعلَن شيء حين تتغيّر القيمة، ولا يضيف الحقل اسمًا للّون.
- ما دام أسلوب الإدخال يركّب نصًّا (input-method composition)، لا يقرأ الحقل شيئًا ولا يعالج أي مفتاح.
- مساحة اللمس للحقل تستوفي الحد الأدنى للهدف، وزر المنتقي هدف كامل.
- عند تكبير النص إلى 200% تلتفّ التسمية ونص المساعدة. وتبقى القيمة على سطر واحد، وتُمرَّر؛ ويحتفظ مربع اللون بحجمه.
- في الألوان المفروضة (forced colors) يكتسب الحقل حافة ويأخذ ألوان الشخص. ومربع اللون وحده يحتفظ بلون القيمة، لأن إظهار ذلك اللون هو غايته؛ وحافته بلون النص.
- في التخطيط من اليمين إلى اليسار ينعكس الحقل: مربع اللون في اليمين، وزر المنتقي في اليسار. أما القيمة نفسها فتبقى من اليسار إلى اليمين.

فجوات معروفة على الويب:

- منتقي المتصفح ليس من Tanrei: إمكانية الوصول فيه شأن المتصفح.
- قبل أن يُعرَّف العنصر لا يُرسم شيء.

### ما عليك فعله

- أعطِ كل حقل لون `label`.
- اكتب `invalidText` و `pickerLabel` على الحقل، بلغة الصفحة. وأعطِ `requiredText` و `optionalText` على الحقل، أو مرة واحدة للمنتج كله بالاستدعاء `setWords({ requiredText, optionalText })`. انظر [كلمات المنتج](https://tanrei.chnotchy.com/ar/foundations/words/).
- تحقق من اللون بنفسك، واضبط `error`، واكتب `errorText` بحيث يقول كيف يُصحَّح اللون.
- إن عرضت منتقيًا من عندك، فافتحه من زر المنتقي، وأعطِه اسمًا، وأعِد التركيز إلى الزر حين يُغلق.