التنسيق

يستخدم Carats تنسيق SASS محدود النطاق، مشجّعًا على HTML دلالي بأقل عدد من أصناف CSS.

base.sass

يحتوي ملف base.sass في src/client على رموز التصميم العامة وعمليات تصفير الأنماط. وكل ملفات SASS الأخرى تستورده بـ @use وas * حتى تتوفر الرموز دون بادئة نطاق.

إنشاء base.sass

// Colors
$color-primary: #000000
$color-secondary: #ffffff
$color-background: #f5f5f5
$color-text: #333333
$color-text-light: #666666

// Spacing
$spacing-xs: 4px
$spacing-sm: 8px
$spacing-md: 16px
$spacing-lg: 24px
$spacing-xl: 32px

// Typography
$font-family-base: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif
$font-size-base: 16px
$font-size-sm: 14px
$font-size-lg: 18px
$font-size-xl: 24px
$font-weight-normal: 400
$font-weight-bold: 700

// Breakpoints
$breakpoint-sm: 576px
$breakpoint-md: 768px
$breakpoint-lg: 992px
$breakpoint-xl: 1200px

// Border radius
$border-radius: 4px
$border-radius-lg: 8px

// Box shadows
$box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1)
$box-shadow-lg: 0 4px 8px rgba(0, 0, 0, 0.15)

// Transitions
$transition-fast: 150ms ease
$transition-normal: 250ms ease

رموز التصميم

عرّف الألوان والتباعد والطباعة ونقاط التوقف ورموز التصميم الأخرى في المستوى الأعلى من base.sass. لا تُداخلها.

استخدام صحيح

@use '../base.sass' as *

.my-component
    color: $color-text
    padding: $spacing-md
    font-size: $font-size-base

استخدام غير صحيح

// Tokens must stay at the top level of base.sass
.my-component
    $color-text: #333
    .inner
        color: $color-text

الرمز المعرَّف داخل قاعدة موجود فقط داخل تلك القاعدة، لذا فإن أي ورقة أنماط أخرى تحتاجه تُعيد تعريفه. وهكذا تتباعد لوحة الألوان بهدوء عبر المشروع.

HTML دلالي

فضِّل عناصر HTML الدلالية بأقل استخدام للأصناف. دع بنية المكوّن ورموز التصميم يتولّيان التنسيق، وأدخِل المحدِّدات داخل SASS بدل إضافة أصناف مساعدة إلى الترميز.

مكوّن نموذجي

import './card.sass';

export default function Card(props: { title: string; children?: JSX.Element }) {
    return (
        <article class="card">
            <header>
                <h2>{props.title}</h2>
            </header>
            <section>
                {props.children}
            </section>
            <footer>
                <button>Action</button>
            </footer>
        </article>
    );
}

ملف SASS المقابل

@use '../base.sass' as *

.card
    background: $color-secondary
    border-radius: $border-radius-lg
    box-shadow: $box-shadow
    padding: $spacing-md
    margin-bottom: $spacing-md

    header
        margin-bottom: $spacing-sm

        h2
            font-size: $font-size-lg
            font-weight: $font-weight-bold

    section
        margin-bottom: $spacing-md

    footer
        display: flex
        justify-content: flex-end

        button
            background: $color-primary
            color: $color-secondary
            padding: $spacing-sm $spacing-md
            border: none
            border-radius: $border-radius
            cursor: pointer
            transition: background $transition-fast

            &:hover
                opacity: 0.9

التنسيق المتجاوب

@use '../base.sass' as *

.container
    max-width: $breakpoint-xl
    margin: 0 auto
    padding: $spacing-md

    @media (max-width: $breakpoint-md)
        padding: $spacing-sm

.grid
    display: grid
    grid-template-columns: repeat(3, 1fr)
    gap: $spacing-md

    @media (max-width: $breakpoint-lg)
        grid-template-columns: repeat(2, 1fr)

    @media (max-width: $breakpoint-sm)
        grid-template-columns: 1fr

أفضل الممارسات

اتبع أفضل الممارسات هذه لتنسيق يسهل صيانته:

1. عرّف الرموز في المستوى الأعلى. لا تُداخل رموز التصميم داخل mixin أو دوال أبدًا.
2. فضِّل HTML دلالي. دع البنية تعرّف التنسيق بدل إضافة أصناف.
3. استورد base.sass بشكل صحيح. استخدم دائمًا @use 'relative/path/to/base.sass' as *.
4. أبقِ التخصيص specificity منخفضًا. تجنّب المحدِّدات المداخلة بعمق.
5. استخدم المتغيرات للتجانس. لا تُضمِّن الألوان أو المسافات أو المقاسات بشكل صريح أبدًا.