Chakra UI Tasarım Sistemi.

Chakra UI Tasarım Sistemi v3 Sistemi: Yapılandırma, Belirteçler ve Bileşenler

Eski bir tema nesnesini aktarmak yerine bir sistem oluşturun

Uygulama üç katmandan oluşur: theme.js tasarım kararlarını tanımlar, main.jsx ortaya çıkan sistemi sağlar ve App.jsx formu bir araya getirir. createSystem(defaultConfig, config), uygulama yapılandırmasını birleştirirken varsayılan bileşen tariflerini korur. Baştan oluşturulmuş özel bir sistem için daha fazla tanım gerekir; burada varsayılanları genişletmek bilinçli bir tercihtir.

Önizlemede görsel taklitler yerine Chakra bileşenleri kullanılır. Kenar çubuğu, uygulamaya özgü sıralı bir ilerleme listesidir; Chakra Steps bileşeninin kullanıldığı iddiası değildir. Profil kartı, alanlar, seçim kutusu, uyarılar ve düğmeler yerel Chakra bileşimleridir.

Destekleyici belirtimi okuyun

Her katmanda neler bulunur?

• tokens: örnekteki iki marka rengi de dahil olmak üzere yeniden kullanılabilir temel değerler.
• semanticTokens: tek tek ekranlardan bağımsız, workspace.action gibi koşullara duyarlı roller.
• recipes: yeniden kullanılabilir bileşen varyantları; uygulamadaki React durumu, formun geçersiz, beklemede, başarısız veya onaylanmış olup olmadığını belirler.

Chakra UI Tasarım Sistemi Temel Renkleri ve Anlamsal Tema Rolleri

Görünüm değiştiğinde rolleri kullanın

bg.panel ve fg.muted, yüzey ve metin işlevlerini belirtir; gray.950 ve gray.400 ise bunların temel değerleridir. Referans tablosunda bu değerlerin açık ve koyu temadaki karşılıkları gösterilir. Demoda belge kökünü açık ve koyu modlar arasında değiştirmek, her Field veya Card bileşenini yeniden yazmadan koşullu değerleri etkinleştirir. Bu yerel değiştirme özellikle kalıcılık veya sistem tercihi entegrasyonu içermez.

workspace.* rolleri uygulamaya eklenmiştir. Açık yüzeyde koyu turkuaz, koyu yüzeyde açık turkuaz eylem rengi ve bunlarla eşleşen bir metin rengi seçerler. Bunlar resmî Chakra belirteç adları değildir. Eşleşen iki rengi temada tutmak, arka planı değişip etiketi beyaz kalan bir koyu mod düğmesini önler.

Destekleyici belirtimi okuyun

Referans sözdizimi, bileşen kısa gösteriminden farklıdır

Belirteç tanımlarında tam referans olan {colors.gray.950} biçimini kullanın. Stil özelliğinde bg="workspace.canvas", renk kategorisi içinde çözümlenir. Bileşik bir CSS değerinde tam belirteç yolunu yeniden kullanmak gerekir. Bu ayrım, bir metin dizgesinin tema referansı sanılmasını önler.

<Box bg="workspace.canvas" color="fg" border="1px solid {colors.gray.200}" p="4" />

Kod referansı

Chakra UI Tasarım Sistemi Açık Belirteçlerle Okunabilir Bir Yazı Ölçeği

Ölçeği bu düzene uyarlayın

Başlıkta fontSize="2xl" ve lineHeight="shorter"; kart başlığında xl, yardımcı metinde sm, örnek açıklamasında xs kullanılır. Bu seçimler anlamsal başlık düzeylerini değiştirmeden hiyerarşi oluşturur: ekran başlığı h1, form başlığı h2 düzeyindedir. Form içeriğinin normal metin boyutu varsayılan gövde ölçeğinde kalır.

Chakra'nın varsayılan gövde ve başlık yazı tipi yığını Inter ile başlar, ardından platform yazı tiplerine geçer. Kendi içinde çalışan demo haricî yazı tipi isteği yapmadığından görüntülenen yedek yazı tipi işletim sistemine göre değişebilir. Tipografinin tam olarak belirlenmesi gerekiyorsa uygun lisanslı bir yazı tipini yerel olarak sunun; yalnızca yazı tipi belirteci ayarlamak, yazı tipi dosyalarını sağlamaz.

Destekleyici belirtimi okuyun

Tipografiyi ve anlamı birbirinden bağımsız tutun

Geçerli adım rozeti, ana yönerge değil, kısa bir üst veridir. Zorunlu alan ve hata mesajları, okunabilir bir boyutta alanın yanında kalır. Üst etiketin harf aralığını değiştirmek form etiketlerini etkilemez; uzun bir çalışma alanı adı da çevresindeki kartın genişliğini değiştirmek yerine giriş alanının içinde tutulur.

Chakra UI Tasarım Sistemi Field, NativeSelect, Card ve Alert Bileşenlerini Birleştirin

Field, stillendirilmiş bir giriş alanı değil, bileşenler arası ilişkidir

Field.Root; etiketi, kontrolü, yardımcı metni ve hata mesajını gruplar. Zorunlu işareti ve RequiredIndicator, alanın zorunlu olduğunu belirtir; invalid ise hata durumunu denetler. Örnekte giriş, React üzerinden kontrollü tutulur ve çalışma alanı adı hatası Field.ErrorText içinde gösterilir. Hata stilleri, bağımsız bir paragrafa ayrı olarak uygulanmaz.

Ekip büyüklüğü için NativeSelect.Root, NativeSelect.Field ve NativeSelect.Indicator kullanılır. Böylece kısa ve sabit seçenek listesi için yerel seçim kutusu davranışı korunur. Aranabilir uzak sonuçlar sunuyormuş gibi davranmaz; bu, farklı bir kontrol ve veri etkileşimi gerektirir.

Destekleyici belirtimi okuyun

Geri bildirim ayrı bir bileşimdir

Destekleyici belirtimi okuyun

Chakra UI Tasarım Sistemi Aralık Belirteçlerini ve Duyarlı Stil Özelliklerini Uygulayın

Somut bir boşluk politikası

Alan grupları arasında gap="6", eylemler arasında gap="3" ve ilerleme sütunuyla form arasında gap="8" kullanın. Sayfa, md noktasında p="4" değerinden p="8" değerine geçer. Kök yazı tipi boyutu 16px olduğunda bunlar sırasıyla 24px, 12px, 32px, 16px ve 32px karşılıklarına gelir. rem tabanlı değerler, kullanıcının kök yazı tipi boyutuna göre ölçeklenir.

Kartta rounded="xl", durum etiketinde ise rounded="md" kullanılır. Farklı yarıçaplar bilinçli olarak seçilmiştir: büyük kapsayıcıyla kompakt etiketin geometrileri farklıdır. Bu kullanım tercihlerini tüm Chakra uygulamalarının uyması gereken varsayılan kurallar olarak değerlendirmeyin.

Destekleyici belirtimi okuyun

Düzeni md noktasında değiştirin

Izgara, md noktasının altında tek sütun kullanır; md noktasından itibaren ise esnek bir formun yanında 220px genişliğinde bir ilerleme sütunu yer alır. minmax(0, 1fr), formun ızgara içinde küçülmesine olanak tanır. Eylem yığını sm noktasında değişir. Bu nesne değerleri, cihaza göre algılama değil, mobil öncelikli geçersiz kılmalardır.

<Grid templateColumns={{ base: "1fr", md: "220px minmax(0, 1fr)" }} gap="8">
  <Box as="nav" aria-label="Setup progress">…</Box>
  <Card.Root rounded="xl">…</Card.Root>
</Grid>

Kod referansı

Chakra UI Tasarım Sistemi: Doğrulama, Yükleme ve Kurtarma

Önizlemenin durum makinesi

Kırpılmış adı boş olan form gönderildiğinde invalid ayarlanır ve giriş alanına odaklanılır. Geçerli gönderim pending durumuna geçer, düzenlemeyi devre dışı bırakır ve Button loadingText değerini gösterir. Yerel zamanlayıcının ardından hata onay kutusu, örneğin failed mı yoksa complete mi göstereceğini belirler. Bu dalların hiçbiri ağ isteği göndermez veya veri kaydetmez.

Başarısız sonuçta denetlenen ad ve seçilen boyut korunur. Hata simülasyonunu kapatmak yeniden denemeyi sağlar. Tamamlandığında profil alanları devre dışı kalır ve ilk ilerleme etiketi değişir; Reset düzenleme durumuna döndürür. Bu, görünür durumların bileşimini kanıtlar; arka uçta kayıt yapılacağına ilişkin bir sözleşme değildir.

Destekleyici belirtimi okuyun

Durumları sırayla deneyin

1. Formu sıfırlayın ve ad girmeden gönderin; alan iletisini ve odağın giriş alanında olduğunu inceleyin.
2. Bir ad girin, başarısız kayıt simülasyonunu etkinleştirin ve gönderin; hata sonrasında değerlerin korunduğunu doğrulayın.
3. Başarısızlık simülasyonunu devre dışı bırakıp yeniden gönderin; onay özetini inceleyin, ardından görünümü değiştirin.

Chakra UI Tasarım Sistemi: Bileşim Boyunca Yerel Anlamsal Yapıyı Koruyun

Doğrulama ve ilerleme anlaşılır kalır

Bu örnek, özel Field hata akışını göstermek ve tarayıcının doğrulama arayüzünde durmamak için noValidate kullanır. Field aracılığıyla etiket alanla ilişkili kalır ve ilk geçersiz giriş alanına odaklanılır. Bekleyen işlem, canlı bir durum bölgesiyle bildirilir; yalnızca bir dönen simgeyle ifade edilmez.

İlerleme listesi sıralı liste anlamını kullanır ve etkin öğede aria-current="step" bulunur. Mevcut olmayan ekranlara yönlendiren sahte bağlantılar içermez. Önizlemedeki ikinci ve üçüncü adımlar bağlamı açıklar ancak tıklanabilir değildir. Böylece gösterimin sınırları görünür olur.

Destekleyici belirtimi okuyun

Odak, özel eylem tarifinin bir parçasıdır

Başlangıç varyantı, açık bir focus-visible dış çizgisi ve ofset tanımlar. Koyu görünümde, eylem rolüyle birlikte dış çizgi rolü de değişir. Yerel onay kutusu ve seçme alanı klavyeyle kullanılabilir. Tüketici uygulamada odağı, alan duyurularını, yakınlaştırmayı ve ekran okuyucu çıktısını da inceleyin; bileşen düzeyindeki bir örnek, başlangıç ürününün tamamının erişilebilir olduğunu kanıtlayamaz.

Chakra UI Tasarım Sistemi: Tarifler, Sağlayıcı Yapılandırması ve Sürüm Sınırları

Button'ı genişletin; Status'ı yerel olarak tanımlayın

Başlangıç Button varyantı theme.recipes.button altında eklenir. Yapılandırma defaultConfig'i genişlettiğinden outline gibi mevcut varyantlar kullanılmaya devam eder. Durum etiketi, defineRecipe ve useRecipe kullanılarak yerel olarak tanımlanır: durum varyantları current, complete ve waiting değerlerini farklı anlamsal rollere eşler. Bu bir uygulama bileşenidir, Chakra dışa aktarımı değildir.

Tek öğeli bir tarif, tek bir stil nesnesi döndürür. Field gibi birden çok parçalı bileşenlerin çeşitli yuvaları vardır; parçaları birlikte temalandırılacaksa yuva tarifleri gerekir. Düğme benzeri bir tarifi tüm Field'a uygulamak; etiket, denetim ve hata öğelerini ayrı ayrı yönetmez.

Destekleyici belirtimi okuyun

Sağlanan dosyaları birlikte kullanın

v2 extendTheme kurulumunu içe aktarmayın veya bu v3 sağlayıcısına theme={...} aktarmayın. Gerçek kök bileşen ChakraProvider value={system} kullanır. Örneğe bilerek ikinci bir renk modu sağlayıcısı eklenmemiştir: yerel açık/koyu sınıf değiştiricisi bu yalıtılmış önizleme için yeterlidir; gerçek bir uygulamada kalıcı tercih ve sunucu tarafında oluşturma desteği gerekebilir.

Destekleyici belirtimi okuyun

Chakra UI Tasarım Sistemi: Temayı ve Formu Birlikte Doğrulayın

Bu örneğin kanıtladıkları

Anlamlı inceleme birimi, her iki görünümdeki profil kartının tamamıdır: etiket, giriş alanı, yardımcı metin, geçersiz geri bildirimi, bekleyen düğme, hata uyarısı ve başarı özeti. Tek bir düğme; anlamsal arka planın eksik olduğunu veya denetimin hata durumunun etiketiyle ilişkilendirilmediğini gösteremez.

Başvuru tablosunu oluşturulan arayüzle karşılaştırın. Özel turkuaz eylem, varsayılan outline eyleminden farklı olmalı; 6 boşluğu alanları ayırmalı; md noktasının altında ızgara tek sütuna geçmelidir. Bu kontroller, yazılı kuralları oluşturulan çıktıya bağlar.

Örneğin kapsamadıkları

Önizlemede hesap oluşturma, davetiye gönderme, kalıcı depolama, kimlik doğrulama veya başka bir başlangıç ekranıyla entegrasyon yoktur. Zamanlayıcının bir simülasyon olduğu açıkça belirtilmiştir. Gerçek bir uç noktaya bağlarken gösterilen alan ve istek durumu ayrımını koruyun, zamanlayıcıyı istekle değiştirin ve tamamlanmanın yerel olarak kabul, uzaktan kaydedilme veya tam etkinleştirme anlamına gelip gelmediğini tanımlayın.

Chakra UI Tasarım Sistemi Bileşen Örnekleri

import { createSystem, defaultConfig, defineConfig, defineRecipe } from '@chakra-ui/react';

export const statusRecipe = defineRecipe({
  base: { display: 'inline-flex', px: '2', py: '1', rounded: 'md', fontSize: 'xs', fontWeight: 'semibold' },
  variants: {
    state: {
      current: { bg: 'teal.subtle', color: 'teal.fg' },
      complete: { bg: 'bg.success', color: 'fg.success' },
      waiting: { bg: 'bg.muted', color: 'fg.muted' },
    },
  },
  defaultVariants: { state: 'waiting' },
});

const config = defineConfig({
  theme: {
    tokens: { colors: { brand: { 700: { value: '#0c5d56' }, 300: { value: '#5eead4' } } } },
    semanticTokens: { colors: {
      'workspace.canvas': { value: { base: '{colors.gray.50}', _dark: '{colors.gray.950}' } },
      'workspace.action': { value: { base: '{colors.brand.700}', _dark: '{colors.brand.300}' } },
      'workspace.onAction': { value: { base: '{colors.white}', _dark: '{colors.gray.950}' } },
    } },
    recipes: {
      button: defineRecipe({ variants: { variant: {
        onboarding: {
          bg: 'workspace.action', color: 'workspace.onAction',
          _hover: { opacity: 0.9 },
          _focusVisible: { outline: '2px solid', outlineColor: 'workspace.action', outlineOffset: '2px' },
        },
      } } }),
    },
  },
});
export const system = createSystem(defaultConfig, config);

import React, { useEffect, useRef, useState } from 'react';
import { Box, Button, Card, Field, Grid, Heading, Input, NativeSelect, Stack, Text, Alert, chakra, useRecipe } from '@chakra-ui/react';
import { statusRecipe } from './theme';

function Status({ state, children }) {
  const recipe = useRecipe({ recipe: statusRecipe });
  return <chakra.span css={recipe({ state })}>{children}</chakra.span>;
}

export default function App() {
  const [dark, setDark] = useState(false);
  useEffect(() => { document.documentElement.className = dark ? 'dark' : 'light'; }, [dark]);
  const [name, setName] = useState('Northstar Studio');
  const [size, setSize] = useState('2–10');
  const [invalid, setInvalid] = useState(false);
  const [phase, setPhase] = useState('editing');
  const [simulateFailure, setSimulateFailure] = useState(false);
  const nameInput = useRef(null);
  const pending = phase === 'pending';
  const complete = phase === 'complete';
  const save = (event) => {
    event.preventDefault();
    if (!name.trim()) { setInvalid(true); nameInput.current?.focus(); return; }
    setInvalid(false); setPhase('pending');
    window.setTimeout(() => setPhase(simulateFailure ? 'failed' : 'complete'), 600);
  };
  return <Box className={dark ? 'dark' : 'light'} bg='workspace.canvas' color='fg' p={{ base: '4', md: '8' }}>
    <Box maxW='960px' mx='auto'>
      <Stack direction={{ base: 'column', sm: 'row' }} justify='space-between' align={{ base: 'stretch', sm: 'center' }} gap='4' mb='8'>
        <Box><Text fontSize='xs' fontWeight='semibold' color='teal.fg' letterSpacing='wide'>CHAKRA UI · NATIVE SPECIMEN</Text><Heading as='h1' fontSize='2xl' lineHeight='shorter' mt='2'>Set up your workspace</Heading></Box>
        <Button variant='outline' size='sm' onClick={() => setDark(!dark)} aria-pressed={dark}> {dark ? 'Light appearance' : 'Dark appearance'} </Button>
      </Stack>
      <Grid templateColumns={{ base: '1fr', md: '220px minmax(0, 1fr)' }} gap='8'>
        <Box as='nav' aria-label='Setup progress'>
          <Stack as='ol' gap='6' listStyleType='none' m='0' p='0'>
            <Box as='li' aria-current={complete ? undefined : 'step'}><Status state={complete ? 'complete' : 'current'}>{complete ? 'Complete' : 'Current'}</Status><Text fontWeight='semibold' mt='2'>1. Workspace profile</Text><Text fontSize='sm' color='fg.muted'>Name and team size</Text></Box>
            <Box as='li'><Status state='waiting'>Next</Status><Text fontWeight='medium' mt='2'>2. Invite your team</Text><Text fontSize='sm' color='fg.muted'>Available in the full product</Text></Box>
            <Box as='li'><Status state='waiting'>Optional</Status><Text fontWeight='medium' mt='2'>3. Connect tools</Text><Text fontSize='sm' color='fg.muted'>Complete this later</Text></Box>
          </Stack>
          <Box mt='8' borderTopWidth='1px' borderColor='border' pt='4'><Text fontSize='xs' color='fg.muted'>Scale in this specimen</Text><Text fontSize='sm' mt='2'>Field gap 6 · Card padding 6<br/>Page gap 8 · Radius xl</Text></Box>
        </Box>
        <Card.Root bg='bg.panel' borderColor='border' rounded='xl'>
          <Card.Header><Heading as='h2' fontSize='xl'>Workspace profile</Heading><Text color='fg.muted' fontSize='sm'>The name appears on your team's workspace.</Text></Card.Header>
          <Card.Body>
            <form onSubmit={save} noValidate>
              <Stack gap='6'>
                <Field.Root required invalid={invalid} disabled={pending || complete}>
                  <Field.Label>Workspace name <Field.RequiredIndicator /></Field.Label>
                  <Input ref={nameInput} value={name} onChange={e => {setName(e.target.value);setInvalid(false);}} autoComplete='organization' />
                  <Field.HelperText>Use a name your teammates will recognize.</Field.HelperText>
                  <Field.ErrorText>Enter a workspace name.</Field.ErrorText>
                </Field.Root>
                <Field.Root disabled={pending || complete}>
                  <Field.Label>Team size</Field.Label>
                  <NativeSelect.Root><NativeSelect.Field value={size} onChange={e => setSize(e.target.value)}><option>Just me</option><option>2–10</option><option>11–50</option><option>51+</option></NativeSelect.Field><NativeSelect.Indicator /></NativeSelect.Root>
                  <Field.HelperText>Used only for this local preview summary.</Field.HelperText>
                </Field.Root>
                <Box><label style={{display:'flex',gap:'8px',alignItems:'center',fontSize:'14px'}}><input type='checkbox' checked={simulateFailure} disabled={pending || complete} onChange={e=>setSimulateFailure(e.target.checked)} />Simulate a failed save</label></Box>
                {phase === 'failed' && <Alert.Root status='error'><Alert.Indicator /><Alert.Content><Alert.Title>Demo save failed</Alert.Title><Alert.Description>Your values are still here. Turn off failure simulation and retry.</Alert.Description></Alert.Content></Alert.Root>}
                {complete && <Alert.Root status='success'><Alert.Indicator /><Alert.Content><Alert.Title>Profile confirmed in this preview</Alert.Title><Alert.Description>{name.trim()} · {size} people. Nothing was sent or stored.</Alert.Description></Alert.Content></Alert.Root>}
                <Stack direction={{base:'column',sm:'row'}} gap='3'>
                  <Button type='submit' variant='onboarding' loading={pending} loadingText='Checking profile' disabled={complete}>Confirm profile</Button>
                  <Button type='button' variant='outline' disabled={pending} onClick={()=>{setPhase('editing');setInvalid(false);setName('');setSize('2–10');setSimulateFailure(false);nameInput.current?.focus();}}>Reset example</Button>
                </Stack>
                <Text role='status' aria-live='polite' fontSize='sm' color='fg.muted'>{pending ? 'Simulating a response. No network request is made.' : complete ? 'Profile step complete. Reset to try another state.' : 'Try an empty name, a failed save, or a different appearance.'}</Text>
              </Stack>
            </form>
          </Card.Body>
        </Card.Root>
      </Grid>
      <Text mt='6' fontSize='xs' color='fg.muted'>Actual Chakra UI 3.37.0 components. Custom workspace semantic tokens and button recipe. Memory-only demonstration.</Text>
    </Box>
  </Box>;
}