ما هو DESIGN.md؟

من أين جاء DESIGN.md#

بنية ملف DESIGN.md#

---
name: DevFocus Dark
colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
rounded:
  md: 8px
---

# Design System

## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14-16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text

الأقسام المعيارية الثمانية#

يستخدم متن Markdown عناوين ##. يمكن حذف الأقسام غير المناسبة، لكن الأقسام الموجودة يجب أن تتبع هذا الترتيب. تكرار أي عنوان يجعل الملف غير صالح، أما الأقسام غير المعروفة فتُحفظ.

1. Overview (أو Brand & Style). المظهر والإحساس العام في بضع جمل: الأجواء، والكثافة، والشخصية.
2. Colors. كل رمز لون والدور الذي يؤديه، مثل الإجراءات الأساسية أو أسطح الصفحة.
3. Typography. عائلات الخطوط وسلّم أحجامها، من العناوين الكبيرة إلى التسميات الصغيرة.
4. Layout (أو Layout & Spacing). سلّم المسافات، والشبكة، وعرض المحتوى، والهوامش.
5. Elevation & Depth (أو Elevation). كيف تنفصل الأسطح: الظلال، والحدود، والتدرجات اللونية.
6. Shapes. أنصاف أقطار الزوايا وقواعد الأشكال الأخرى.
7. Components. الأزرار وحقول الإدخال والبطاقات وغيرها من العناصر الأساسية، مع رموزها وحالاتها.
8. Do's and Don'ts. القواعد التي يجب ألا يخالفها الوكيل.

متن Markdown مختصر يضم كل قسم معياري بالترتيب. عدّل المحتوى ليناسب منتجك، وحافظ على العناوين وترتيبها.

## Overview
A minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- Primary (#2665fd): CTAs and active states
- Surface (#0b1326): Page backgrounds
- On-surface (#dae2fd): Text on dark backgrounds

## Typography
- Headlines: Inter, semibold
- Body: Inter, regular, 14-16px
- Labels: Inter, medium, 12px, uppercase

## Layout
- 8px base spacing unit, scale: 4 / 8 / 16 / 24 / 32 / 48
- Max content width 720px with 24px gutters on mobile

## Elevation & Depth
- Surfaces rely on background contrast instead of shadow
- Overlays use an 8 percent white tint on dark surfaces

## Shapes
- Rounded 8px for controls, 16px for cards
- Avoid mixing sharp and rounded corners in one view

## Components
- Buttons: 8px rounded, primary filled with brand blue
- Inputs: 1px border, subtle surface-variant background
- Cards: no elevation, rely on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, for the most important action
- Don't mix rounded and sharp corners in one view
- Do maintain at least a 4:1 contrast ratio for all text

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

يضمّن DESIGN.md رموز التصميم في مقدمة YAML (front matter) في بداية الملف. تبدأ كتلة المقدمة بسطر يحتوي على --- فقط، وتنتهي بالفاصل نفسه.

version: <string>
name: <string>
description: <string>
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

من أسماء السلالم الشائعة xs و sm و md و lg و xl و full، لكن أي مفتاح وصفي صالح. توجد رموز المسافات في YAML تحت spacing:، ويصفها قسم Layout في متن Markdown.

أنواع الرموز

اللون (Color)

أي قيمة لون صالحة في CSS. صيغة Hex #RRGGBB هي الخيار الافتراضي الموصى به، مثل "#1A1C1E".

البُعد (Dimension)

رقم مع وحدة px أو em أو rem. أمثلة: 48px، -0.02em.

مرجع الرمز (Token Reference)

يُكتب بين أقواس معقوصة ويشير إلى قيمة في شجرة YAML. مثال: {colors.primary}.

الخطوط (Typography)

كائن مركّب يضم خصائص الخط، مثل العائلة والحجم والوزن وارتفاع السطر والتباعد بين الحروف. راجع خصائص الخطوط.

خصائص الخطوط

fontFamily

اسم عائلة الخط.

fontSize

حجم الخط كقيمة بُعد.

fontWeight

وزن رقمي مثل 400 أو 700.

lineHeight

قيمة بُعد أو مُضاعِف بلا وحدة. يوصى بالقيم بلا وحدة.

letterSpacing

ضبط التباعد بين الحروف كقيمة بُعد.

fontFeature

يضبط font-feature-settings.

fontVariation

يضبط font-variation-settings.

مراجع الرموز

يُكتب مرجع الرمز بين أقواس معقوصة، ويحتوي على مسار كائن يشير إلى قيمة أخرى في شجرة YAML. في معظم مجموعات الرموز، يجب أن يشير المرجع إلى قيمة أولية لا إلى مجموعة. أما داخل قسم المكونات فيُسمح بالمراجع إلى قيم مركّبة مثل مستويات الخطوط.

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

المكونات

backgroundColor

اللون (Color)

textColor

اللون (Color)

typography

الخطوط (Typography)

rounded

البُعد (Dimension)

padding

البُعد (Dimension)

size

البُعد (Dimension)

height

البُعد (Dimension)

width

البُعد (Dimension)

أسماء الرموز الموصى بها

كيف يستخدم وكلاء الذكاء الاصطناعي DESIGN.md#

## Design
Follow DESIGN.md for every UI change: use its color, typography,
spacing and component tokens instead of inventing new values.

Claude Code

يقرأ الملفات في مستودعك ويحمّل CLAUDE.md عند البدء. أضف هناك سطرًا يشير إلى DESIGN.md، أو اذكر الملف في الموجّه.

Cursor

أضف DESIGN.md إلى سياق المحادثة، أو أشِر إليه من قاعدة مشروع (project rule) ليُطبَّق على كل طلب يخص الواجهة.

GitHub Copilot

أشِر إلى DESIGN.md من ملف تعليمات Copilot في مستودعك، أو أرفقه في المحادثة عندما تطلب عملًا على الواجهة.

Google Stitch

حيث بدأت الصيغة. يستخدم Stitch ملف DESIGN.md لتتشارك الشاشات المولَّدة لوحة ألوان واحدة وسلّم خطوط واحدًا ولغة مكونات واحدة.

بعد ذلك يأخذ الوكيل القيم الدقيقة من الرموز (قيمة hex للزر الأساسي، وحجم تسمية body-md) ويستعين بالنص ليقرر أين تُستخدم.

DESIGN.md و AGENTS.md و README.md: ما الفرق؟#

توجد الملفات الثلاثة جنبًا إلى جنب وتجيب عن أسئلة مختلفة. لا يحل DESIGN.md محل AGENTS.md، بل يعمل الاثنان معًا.

أمثلة حقيقية على DESIGN.md#

أسرع طريقة لفهم الصيغة هي قراءة بضعة ملفات حقيقية. تعرض كل صفحة من صفحات المعرض هذه ملف DESIGN.md مستخرجًا من الموقع العام للعلامة التجارية، مع لوحة ألوانها وعينة خطوطها. وهي ليست إرشادات رسمية للعلامات التجارية.

• ⁨Stripe⁩ DESIGN.md
• ⁨Anthropic⁩ DESIGN.md
• ⁨Airbnb⁩ DESIGN.md
• ⁨Linear⁩ DESIGN.md
• ⁨Notion⁩ DESIGN.md
• ⁨Supabase⁩ DESIGN.md

تصفّح كل أمثلة DESIGN.md

كيف تحصل على ملف DESIGN.md#

1. اكتبه يدويًا. ابدأ من المواصفات والأمثلة أعلاه، ثم افحص الملف باستخدام DESIGN.md Validator المجاني أو الأمر lint من Google.
2. ابدأ من مثال. انسخ ملفًا من المعرض وعدّل الرموز والنص ليطابقا منتجك.
3. ولّده من موقع حي. الصق رابط صفحة عامة في Design Extractor. يعرض الموقع في متصفح ويعيد ملف DESIGN.md بألوانه وخطوطه ومسافاته ومكوناته، وفق المواصفات أعلاه. تشرح صفحة مولّد DESIGN.md ما ستحصل عليه. وتعمل عملية الاستخراج نفسها من إضافة Chrome ومن وكيلك عبر خادم MCP.