زر الأيقونة (Icon Button)

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

التثبيت

زر الأيقونة جزء من العنصر button في السجل، فتثبيت مكوّن زر يثبّته معه.

bash

npx @smicolon/fasla-ui@latest add button

قبل إضافة أي مكوّن، شغّل الأمر init مرة واحدة في مشروعك. التفاصيل في صفحة التثبيت.

معاينة

الأنماط (variant)

أربعة أنماط، كما في زر الأيقونة في Figma: default، soft، outline، ghost، ولكل منها الألوان الدلالية الثلاثة. ولا يوجد زر أيقونة بالنمط link، لأن الأيقونة وحدها لا تُقرأ رابطًا.

default

soft

outline

ghost

الأحجام

أربعة أحجام مربّعة: قياس الحجم icon-xs هو 26px، والحجم icon-sm هو 32px، والحجم icon-md هو 36px، والحجم icon-lg هو 40px. والأيقونة بحجم 16px في كل الأحجام.

الحالات

التمرير والضغط والتركيز من لوحة المفاتيح حالات CSS حقيقية، كما في مكوّن زر. تخفت أزرار الأيقونة الممتلئة، وتزداد صبغة الأنماط soft، outline، ghost. ويظهر الزر المعطّل بنصف شفافيته في كل الأنماط.

مفعّل

معطّل

الاسم المقروء

لا تحمل الأيقونة نصًا يقرؤه قارئ الشاشة، لذلك يحتاج كل زر أيقونة إلى اسم: السمة aria-label، أو نص داخله تخفيه عن العين. وفي بيئة التطوير، يكتب الزر تحذيرًا في وحدة التحكم إذا لم يجد اسمًا. ولإظهار الاسم عند التمرير أيضًا، ضع الزر داخل تلميح.

إتاحة الوصول (accessibility)

أعطِ كل زر أيقونة السمة aria-label. ويحذّرك الزر في بيئة التطوير إذا لم يكن له اسم.
الأيقونة زخرفية. أخفِها عن التقنيات المساعدة بالسمة aria-hidden إن لم تفعل ذلك مكتبة الأيقونات.
يرسم التركيز من لوحة المفاتيح حلقة بعرض 2px، على بعد 2px من الزر، باللون ring.
قياس الحجم icon-xs هو 26px. ويطلب المعيار WCAG 2.5.8 مساحة نقر لا تقل عن 24px، فكل الأحجام تفي به.

الخصائص (props)

الخاصية	النوع	الافتراضي	الوصف
`tone`	`"primary" \| "secondary" \| "destructive"`	لا يوجد	اللون داخل النمط. لكل نمط قيمة افتراضية.
`variant`	`"default" \| "outline" \| "ghost" \| "soft"`	`"default"`	نمط الزر: ممتلئ، أو بحدّ، أو شفاف، أو بصبغة خفيفة.
`size`	`"icon-xs" \| "icon-sm" \| "icon-md" \| "icon-lg"`	لا يوجد	أحجام الأيقونة: مربّعة، مع أيقونة واحدة بحجم 16px.
`aria-label`	`string`	لا يوجد	الاسم الذي يقرؤه قارئ الشاشة. مطلوب ما لم يكن في الزر نص مخفي عن العين.
`radius`	`"standard" \| "rounded"`	`"standard"`	شكل الزوايا: مستديرة قليلًا، أو دائرة.
`loading`	`boolean`	`false`	يضع مؤشر تحميل دوّارًا مكان الأيقونة ويعطّل الزر.
`disabled`	`boolean`	`false`	يعطّل الزر.
`className`	`string`	لا يوجد	أصناف إضافية للمكوّن.

للتوافق مع shadcn/ui، ما زالت القيمتان secondary، destructive تعملان للخاصية variant، وهما النمط Solid بهذين اللونين. وما زالت القيمة icon تعمل للخاصية size، وهي الحجم icon-md.

الاستخدام

زر أيقونة

tsx

import { PlusIcon } from "lucide-react"
import { Button } from "@/components/ui/button"

export function AddButton() {
  return (
    <Button size="icon-md" aria-label="إضافة">
      <PlusIcon aria-hidden="true" strokeWidth={1.5} />
    </Button>
  )
}

شريط أدوات من أزرار الأيقونة

tsx

import { PencilIcon, Trash2Icon, XIcon } from "lucide-react"
import { Button } from "@/components/ui/button"

export function RowActions() {
  return (
    <div className="flex items-center gap-1">
      <Button size="icon-sm" variant="ghost" aria-label="تعديل">
        <PencilIcon aria-hidden="true" strokeWidth={1.5} />
      </Button>
      <Button size="icon-sm" variant="ghost" tone="destructive" aria-label="حذف">
        <Trash2Icon aria-hidden="true" strokeWidth={1.5} />
      </Button>
      <Button size="icon-sm" variant="ghost" aria-label="إغلاق">
        <XIcon aria-hidden="true" strokeWidth={1.5} />
      </Button>
    </div>
  )
}