# السمة والتخصيص

تتكون سمة Tailwind من مجموعة مسطحة من متغيرات CSS. يمكنك توسيعها أو استبدالها بكتلة `@theme { … }` في CSS المدخل، والإشارة إلى تلك القيم من داخل CSS عبر دوال السمة، ثم قراءة القيم المحلولة من PHP. لا يوجد ملف إعداد JavaScript — فالسمة موجودة بالكامل في CSS.

## كتلة `@theme`

تعرّف كتلة `@theme` رموز التصميم على هيئة خصائص مخصصة من CSS. وتحدد بادئة مساحة الاسم لكل متغير (`--color-*` و`--font-*` و`--breakpoint-*` و`--spacing-*` و…) الأدوات المساعدة والمتغيرات التي يغذيها الرمز في Tailwind.

```php
use TailwindPHP\tw;

$css = tw::generate('<div class="bg-brand text-brand xs:flex">', '
    @import "tailwindcss";

    @theme {
        --color-brand: #3b82f6;
        --font-heading: "Inter", sans-serif;
        --breakpoint-xs: 20rem;
        --spacing-huge: 10rem;
    }
');
```

يسجل كل رمز أدوات مساعدة ضمن مساحة اسمه. ينشئ المثال أعلاه `bg-brand` و`text-brand` و`border-brand` وعائلة `font-heading` ومتغيرًا متجاوبًا هو `xs:` وخياري التباعد `p-huge`/`m-huge` — ولا تُنشأ هذه إلا عند ظهور الفئة في محتواك.

```css
/* bg-brand resolves to the theme variable */
:root, :host {
  --color-brand: #3b82f6;
}
.bg-brand {
  background-color: var(--color-brand);
}
```

يسجل الرمز `--breakpoint-xs` المتغير `xs:` مباشرةً:

```css
@media (min-width: 20rem) {
  .xs\:flex {
    display: flex;
  }
}
```

### مساحات الأسماء الشائعة

| مساحة الاسم | ما تولّده |
|-----------|-------|
| `--color-*` | `bg-*` و`text-*` و`border-*` و`fill-*` و`stroke-*` و… |
| `--font-*` | أدوات مساعدة من عائلة `font-*` |
| `--text-*` | أدوات مساعدة لحجم الخط `text-*` |
| `--breakpoint-*` | متغيرات متجاوبة (`sm:` و`md:` و`xs:` مخصص) |
| `--spacing-*` | قيم تباعد مسماة (`p-huge` و`m-huge`) |
| `--radius-*` | أدوات مساعدة `rounded-*` |
| `--shadow-*` | أدوات مساعدة `shadow-*` |

### مسح مساحة اسم

يؤدي ضبط محرف البدل لمساحة اسم على `initial` إلى إزالة الإعدادات الافتراضية في Tailwind لتلك المساحة قبل إضافة رموزك. يتيح لك هذا البدء بلوحة ألوان خالية:

```css
@theme {
    /* Drop every default color, then define only what you need */
    --color-*: initial;
    --color-brand: #3b82f6;
    --color-ink: #111827;
}
```

يمسح `--*: initial;` السمة بالكامل. وتحذف قيمة واحدة من `initial` لمفتاح ليس محرف بدل (`--color-red-500: initial;`) ذلك الرمز وحده. القيمة الوحيدة المقبولة لمحرف بدل `-*` هي `initial` — وأي قيمة أخرى تؤدي إلى خطأ.

## قراءة قيم السمة في CSS

### `theme()`

تقرأ الدالة القديمة `theme()` قيمة باستخدام تدوين النقاط ضمن نطاقات أسماء v3-style. وتحلّها إلى قيمة الرمز أثناء الترجمة، لذا يمكن استخدامها حيثما تُتوقع قيمة، بما في ذلك القواعد المخصصة والتصريحات الأخرى.

```php
$css = tw::generate('<div class="callout">', '
    @import "tailwindcss";
    .callout { color: theme(colors.red.500); }
');
```

```css
.callout {
  color: oklch(63.7% .237 25.331);
}
```

تُطابق المسارات النقطية المتغيرات الأساسية (`colors.red.500` → `--color-red-500`، و`fontFamily.sans` → عائلة sans). يدعم هذا معدِّل العتامة: `theme(colors.red.500 / 50%)`. ويمكن تمرير قيمة احتياطية كوسيط ثانٍ: `theme(colors.brand, #000)`. إذا تعذّر حل مسار ولم تُحدَّد قيمة احتياطية، يُستبعد الخيار الذي يستخدمه.

### `--theme()`

يقرأ `--theme()` متغيرًا من السمة باستخدام اسم الخاصية المخصصة CSS، ويعيد مرجعًا من نوع `var()` افتراضيًا، لتظل القيمة قابلة للتجاوز أثناء التشغيل:

```css
.btn { color: --theme(--color-brand); }
/* → color: var(--color-brand); */
```

أضف `inline` لاستبدال مرجع `var()` بالقيمة التي تم حلها: `--theme(--color-brand inline)`. الوسيط الثاني قيمة احتياطية (`--theme(--color-brand, #000)`)، وتُعالَج قيمة `initial` الاحتياطية بطريقة خاصة — إذ تُدرج في مراجع `var()` المتداخلة التي تُحل بدورها إلى `initial`. داخل قاعدة at-rule (`@media`، `@container`)، يُحل `--theme()` دائمًا مباشرةً لأن `var()` غير صالح في تلك المقدمات.

### `--spacing()`

يضرب `--spacing(n)` وحدة التباعد الأساسية للسمة (`--spacing`) في `n`:

```css
@utility my-gap { gap: --spacing(4); }
/* → gap: calc(var(--spacing) * 4); */
```

تُحل قيمة المضاعف `1` إلى المتغير الأساسي نفسه (`--spacing(1)` → `var(--spacing)`، وهو أيضًا ما يصدره `p-1`)، بينما تُحل `0` إلى طول صفري عادي.

هذا هو الحساب نفسه الذي تستخدمه أدوات التباعد المضمنة، لذا تظل القيم المخصصة متوافقة مع `p-4` و`m-4` وما شابهها.

### `--alpha()`

يطبّق `--alpha(color / opacity)` العتامة على لون باستخدام `color-mix()` في فضاء الألوان oklab:

```css
@utility tint { color: --alpha(var(--color-red-500) / 50%); }
```

```css
.tint {
  color: #fb2c3680;
}
@supports (color: color-mix(in lab, red, red)) {
  .tint {
    color: color-mix(in oklab, var(--color-red-500) 50%, transparent);
  }
}
```

تظل صيغة `color-mix()` قابلة للتجاوز أثناء التشغيل؛ وتغطي القيمة الاحتياطية الثابتة التي تسبقها، والمحتسبة من قيمة السمة، المتصفحات التي لا تدعم `color-mix()`. عطّل القيمة الاحتياطية باستخدام الخيار `polyfills` في [`tw::compile()`](https://tailwindphp.inline0.dev/ar/docs/api#twcompile).

### تراكب العتامة و`color-mix()` → `oklab()`

تتراكب معدّلات العتامة. تطبيق 50% على قيمة تحمل عتامة بنسبة 50% ينتج 25%، ويُحسب ذلك في oklab. عندما يُحل معدّل العتامة على لون ثابت، يختزل TailwindPHP تعبير `color-mix(in oklab, …)` إلى قيمة `oklab()` ملموسة — وهو التحويل نفسه الذي يجريه lightningcss في سلسلة أدوات Tailwind الأصلية — بينما تحتفظ الألوان الديناميكية (التي لا تزال ضمن `var()`) بصيغة `color-mix()` لتظل قابلة للتجاوز أثناء التشغيل.

## قراءة قيم السمة من PHP

تعيد ثلاث دوال وصول قيم السمة المحلولة على هيئة مصفوفات PHP. تقبل كل منها سلسلة إدخال اختيارية CSS (الافتراضية `@import "tailwindcss";`)، وتتوفر أيضًا على [مثيل المترجم](https://tailwindphp.inline0.dev/ar/docs/api).

```php
use TailwindPHP\tw;

tw::colors();
// ['red-500' => 'oklch(63.7% .237 25.331)', 'blue-500' => 'oklch(62.3% .214 259.815)', ...]

tw::breakpoints();
// ['sm' => '40rem', 'md' => '48rem', 'lg' => '64rem', 'xl' => '80rem', '2xl' => '96rem']

tw::spacing('@import "tailwindcss"; @theme { --spacing-huge: 10rem; }');
// ['huge' => '10rem']
```

مرّر سلسلة CSS لقراءة القيم وفق سمة مخصصة:

```php
tw::colors('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');
// [..., 'brand' => '#3b82f6']

tw::breakpoints('@import "tailwindcss"; @theme { --breakpoint-xs: 20rem; }');
// ['sm' => '40rem', ..., '2xl' => '96rem', 'xs' => '20rem']
```

يستخدم TailwindCSS 4 قيمة أساسية واحدة من `--spacing` بدلًا من مقياس `--spacing-*`، لذا يعيد `tw::spacing()` رموز `--spacing-*` المخصصة التي تحددها فقط. تتوفر الطرق نفسها من مثيل المترجم: `$compiler->colors()` و`$compiler->breakpoints()` و`$compiler->spacing()`. راجع [API](https://tailwindphp.inline0.dev/ar/docs/api) للاطلاع على التواقيع كاملة.

## الخطوات التالية

- [التوجيهات](https://tailwindphp.inline0.dev/ar/docs/usage/directives) — `@apply`, `@utility`, `@custom-variant`, `@layer`.
- [الاستيرادات](https://tailwindphp.inline0.dev/ar/docs/usage/imports) — `@import`، والوحدات الافتراضية، وPreflight.
- [API](https://tailwindphp.inline0.dev/ar/docs/api) — كل دالة وصول وطريقة فحص.