Gerçek anlamsal CSS değişkenleri, bileşik React kontrolleri, açık ve koyu yüzeyleri ve çalışan bir görsel dışa aktarma tarifiyle HeroUI v3 başvuru kaynağı.
OpenDesign Kılavuzu9 Bölüm30 Referans KaydıÖzgün Uygulama Kılavuzu
01
HeroUI Tasarım Sistemi Arayüz Önizlemesi
Yerel bir tarif uygulayın; yerel bir kaydırıcıyla kaliteyi değiştirin, meta veri ayarını değiştirin ve görünümü değiştirin. Kodlayıcı veya yükleme işlemi taklit edilmez.
Özgün çizimler ve yerleşimle, yerel @heroui/react 3.2.6 ve @heroui/styles 3.2.6 üzerinden derlenmiş CSS. · Uygulama başvurusu
02
HeroUI Tasarım Sistemi Tasarım Referansı
HeroUI 3.2.6 varsayılan teması, @heroui/styles/dist/themes/default/variables.css dosyasına göre doğrulandı. Aşağıdaki OKLCH değerleri, paketteki değerlerin aynısıdır. Görsel çalışmaların renkleri ve tipografi uygulama tercihleridir; HeroUI marka tasarım belirteçleri değildir.
Bu örnek HeroUI 3.2.6 sürümünü hedefler. Denetimleri, React Aria davranışıyla desteklenen React bileşenleridir; görsel katman ise @heroui/styles tarafından sağlanır. Resmî hızlı başlangıç, React 19 ve Tailwind CSS v4 gerektirir. v3 kurulumu bu uygulamayı eski HeroUIProvider kalıbıyla sarmalamaz. v2 öğreticilerini bu bileşik bileşen API ile birlikte kullanmak, denetimlerin eksik kalmasına veya yanlış stillendirilmesine sıkça yol açar.
Bu örnek, dışa aktarma tarifi düzenleyicisidir: solda görsel, sağda kalite ve meta veri denetimleri bulunur. İllüstrasyon özgün CSS ile çizilmiştir. Kitaplığın işlediği bir görsel değildir. Tarif uygulandığında seçili ayarlar yerel React durumunda kaydedilir; uydurma bir dosya boyutu veya indirme sonucu özellikle gösterilmez.
HeroUI Tasarım Sistemi Anlamsal Renkler ve Görünüm
Tuval, yüzeyler ve yüzen katmanları birbirinden ayırın
Dış tuval için --background, görsel ve ayarlar kartları için --surface, gelecekteki açılır pencere veya iletişim kutusu için --overlay kullanın. Açık temada ikisi beyaz olsa bile bunlar anlamsal rollerdir. Koyu temada tuval ile yükseltilmiş yüzeyler farklılaşır. Örnek, tüm alt öğelerin aynı tema kapsamını paylaşması için document.documentElement üzerindeki dark sınıfını değiştirir.
Kaydırıcı dolgusunda ve seçili anahtarda vurgu rolü kullanılır. Düz vurgu renkli denetimler bu rengi --accent-foreground ile eşleştirir. İkincil metinde tüm kartın opaklığını düşürmek yerine --muted kullanılır. Görsel, etkileşimli arayüz öğesi değil içerik olduğu için her iki görünümde de kendine özgü sıcak renk paletini korur.
HeroUI stilleri Tailwind yardımcı sınıflarıyla bütünleşir; ancak bu sayfa, zorunlu bir HeroUI yazı tipi uydurmaz. Özgün CSS, gövde metni için 16px ve 1.5 satır yüksekliğiyle Arial/Helvetica kullanır. 32px başlık, dar düzende 28px olur; ayarlar başlığı 24px'tir. Referans tablosu, bu uygulama değerlerini paket değişkenlerinden ayırır.
Resmî --spacing ilkel değeri 0.25rem'dir. Bu bileşimde tarifin iç boşluğu 16px, sütunlar arası ve masaüstü kartlarının çevresindeki boşluk 24px, masaüstü tuvalinin çevresindeki boşluk ise 32px'tir. Alan yarıçapı, resmî 8px yarıçap ilkel değerinden türetilmiştir. Kart yarıçapı bilerek bu ilkel değerin üç katı olarak belirlenmiştir; dolayısıyla 24px değeri, varsayılan Card değeri değil, uygulamaya özgü bir türetmedir.
HeroUI Tasarım Sistemi Eksiksiz Bir Kaydırıcı Oluşturun
Bileşen yapısını ve değer sahipliğini birlikte ele alın
Kök Slider; value, onChange, minValue, maxValue ve step özelliklerinin sahibidir. Label, erişilebilir adı sağlar. Slider.Output aynı değeri okur; Slider.Track ise Slider.Fill ve Slider.Thumb bileşenlerini içerir. Görünür bu parçaların çıkarılması, beklenen iz veya tutamak olmadan çalışır durumda bir bileşene yol açabilir. Bu örnekte aralık dizisi yerine tek bir sayı kullanılır.
Kalite, beşer artışlarla 10–100 arasında sınırlandırılmıştır. Bu sınırlar yerel ürün tercihleridir. HeroUI varsayılan olarak 0–100 aralığını ve birer artışları kullanır. Kalite değeriyle bayt miktarı arasında evrensel ve güvenilir bir ilişki olmadığından, yardımcı metin dosya boyutu tahmini uydurmadan ödünleşimi açıklar. Birden fazla tutamak desteklemek için sayı dizisi kullanın ve her tutamağa doğru dizin değerini verin.
Kalite kaydırıcısına odaklanın ve değeri bir adım değiştirmek için ok tuşuna basın.
Görünür çıktının ve geçerli tarifin birlikte değiştiğini doğrulayın.
Tarifi uygulayın, ardından taslak ile uygulanan anlık görüntüyü ayırt etmek için kaydırıcıyı yeniden hareket ettirin.
Meta veri ayarında Switch bileşeninde isSelected ve onChange kullanılır. Yüklü 3.2.6 uygulamasında Switch.Content, Switch.Control ve Label bileşenlerini sarar. Switch.Control ise Switch.Thumb bileşenini içerir. Description, alan düzeyinde yardım metni olarak Switch.Content bileşeninin yanında yer alır. Bu yapı, SwitchField/SwitchButton bileşen anatomisi önceki bazı v3 belge örneklerinden farklı olan yüklü kaynak kodunu izler. Açıklama, boolean değerinin anlamını belirtir; mavi seçili ize güvenmez. Tek bir meta veri durumu, hem yerel denetimi hem de metin tarifini yönetir.
Bu boolean değerini uygulama işleminden ayrı tutun. Meta veri ayarını değiştirmek geçerli taslağı hemen düzenler; Önizlemeye uygula düğmesine basmaksa bir anlık görüntü kaydeder. Sıfırla, kaliteyi 80'e döndürür, meta verileri kaldırır ve bu anlık görüntüyü temizler. Farklı bir taslak için kayıtlı durum göstergesi yeniden kullanılmaz. Bu uygulama bir kodlayıcıya bağlanacak olsaydı, belirsiz form metnini okumak yerine uygulanan nesneyi bu işleme iletin.
HeroUI Tasarım Sistemi Yüzeyleri Duyarlı Biçimde Oluşturun
Görsel, denetimlerin arkasındaki dekorasyon değil, içerik olarak kalır
Masaüstünde, görsele biraz daha fazla yer verirken ayarların okunaklı kalmasını sağlayan 1.05fr/1fr ızgara kullanılır. Özgün 700px kesme noktasında ızgara tek sütuna dönüşür, üstbilgi alt alta dizilir ve görselin en-boy oranı 4:5'ten 4:3'e değişir. Sabit bir okuma yüzeyi sağlamak için açıklaması görselin dışında kalır.
Tüm etkileşimli denetimler düz anlamsal yüzey üzerinde yer alır. Alan daraldığında düğmeler alt satıra geçer. Önizleme yüksekliği, görüntü alanının minimum yüksekliğine değil içeriğe göre belirlenir; belge otomatik boyutlandırılan bir iframe içine yerleştirildiğinde bu önemlidir. Hiçbir sabit yükseklikli kaydırma kutusu formu veya sonucu gizlemez.
HeroUI Tasarım Sistemi Etkileşim, Odak ve Gerçekçi Sonuçlar
Görsel taklitler yerine yerel durumları kullanın
Button, işaretçiyle sınırlı özel bir olay yerine onPress kullanır. Slider, klavyeyle kullanım ve duyurulan değerleri sağlar. Switch, boolean durumunu yerel erişilebilirlik uygulaması üzerinden sunar. Özel düzen CSS, odak stillerini kaldırmaz. Bileşeni devre dışı bırakmak için yalnızca opaklığı düşürmek yerine isDisabled kullanın; --disabled-opacity yalnızca görünümü tanımlar.
Durum paragrafında role=status kullanılır; böylece klavye odağı taşınmadan uygulanan anlık görüntü duyurulabilir. Koyu görünüm düğmesinin etiketi, sıradaki işlemi açıklayacak şekilde değişir. Görselin açıklayıcı bir bölge etiketi vardır ve şekilleri dekoratif kalır. Bu demodaki hiçbir şey, verilerin yeniden yüklemeden sonra da kalacağını vaat etmez.
Kalite, görünür çıktısı olan ve sınırları belirlenmiş sayısal bir seçenektir.
Meta veri, hem etiketi hem de açıklayıcı metni olan bir booleandır.
Uygula, yerel bir anlık görüntü kaydeder; Sıfırla bu görüntüyü temizleyip başlangıç taslağını geri yükler.
HeroUI Tasarım Sistemi Örneği Kurun ve Yeniden Oluşturun
Bir stil sayfası işlem hattı seçin
Bir Vite React uygulamasında sabitlenmiş HeroUI paketlerini ve Vite eklentisiyle Tailwind CSS v4’ü yükleyin. Ana stil dosyasında önce tailwindcss’i, ardından @heroui/styles’ı içe aktarın ve sonra özgün düzen CSS’yi ekleyin. App’i React createRoot ile oluşturun; bu bileşim için v2 sağlayıcısı gerekmez. Kurulum bloğunda giriş ve Vite yapılandırması yer alır; App’in ve CSS’nin tamamı yukarıda bulunur.
İndirilebilir bağımsız örnek, paketin önceden derlenmiş heroui.min.css dosyasını ve bir esbuild React paketini kullanır; ikisi de satır içine alınmıştır. Böylece önizlemede CDN bağımlılıkları ortadan kalkar. Örnek aynı yerel denetimleri gösterir, ancak derlenmiş stilleri ve Tailwind tarafından oluşturulan HeroUI stillerini aynı üretim uygulamasına birlikte aktarma talimatı değildir. Yinelenen kurallardan kaçınmak için tek bir işlem hattı seçin.
HeroUI Tasarım Sistemi Tarifi Kodlayıcı Uydurmadan Genişletin
Yetenek sınırlarını görünür tutun
Gerçek bir görüntü dönüştürme özelliği eklemek için dosya girişi ve gerçek bir tarayıcı ya da sunucu kodlayıcısı ekleyin; ardından beklemede, başarısız ve tamamlandı durumlarını bu işleme bağlayın. Slider yalnızca bir değer seçer; sıkıştırma yapmaz. Gerçek bir çıktı blob’u oluşana kadar Apply düğmesi Download düğmesine dönüşmemelidir. Tekrarlanan tarif değişikliklerinin kayıplı kodlamayı biriktirmemesi için özgün görüntüyü ayrı tutun.
Uygulamaya tema uygularken anlamı olan renk çiftlerini birlikte geçersiz kılın ve hem açık hem koyu görünümü sınayın. Uygun olmayan bir ön plan rengini koruyup yalnızca --accent değerini değiştirmek, düğme kontrastını bozabilir. Daha kapsamlı özelleştirmelerde, bileşenin erişilebilir girişini görsel olarak benzer bir div ile değiştirmek yerine belgelenmiş bileşen sınıflarını ve data durumlarını hedefleyin.
Bileşik Slider ve Switch parçaları resmî stilleri devralır. Ayrı bir uygulanan anlık görüntü, taslak ve uygulanmış durumları görünür kılar.
jsx
import React,{useState,useEffect} from 'react';
import {Button,Switch,Label,Description,Slider} from '@heroui/react';
import './style.css';
export default function App(){
const[quality,setQuality]=useState(80),[metadata,setMetadata]=useState(false),[dark,setDark]=useState(false),[saved,setSaved]=useState(null);
useEffect(()=>{document.documentElement.classList.toggle('dark',dark)},[dark]);
return <main className='export-app'><header><div><p className='eyebrow'>HeroUI · Export studio</p><h1>Make room for the image.</h1><p className='muted'>Inspect a local export recipe before handing it to an encoder.</p></div><Button variant='secondary' onPress={()=>setDark(!dark)}>{dark?'Light appearance':'Dark appearance'}</Button></header><div className='export-grid'><section className='art-panel' aria-label='Original CSS artwork preview'><div className='art'><div className='sun'/><div className='hill one'/><div className='hill two'/><span>FIELD NOTES<br/>COLLECTION 07</span></div><div className='art-caption'><strong>Morning in the dunes</strong><span>1600 × 1200 · sample composition</span></div></section><section className='settings'><p className='eyebrow'>WEBP PRESET</p><h2>Export settings</h2><p className='muted'>The controls update a recipe. They do not encode or upload an image.</p><Slider value={quality} onChange={setQuality} minValue={10} maxValue={100} step={5}><div className='slider-heading'><Label>Image quality</Label><Slider.Output/></div><Slider.Track><Slider.Fill/><Slider.Thumb/></Slider.Track></Slider><p className='helper'>Higher quality may preserve fine texture. File size depends on the source image and encoder.</p><Switch isSelected={metadata} onChange={setMetadata}><Switch.Content><Switch.Control><Switch.Thumb/></Switch.Control><Label>Keep metadata</Label></Switch.Content><Description>Include source metadata in the recipe.</Description></Switch><div className='recipe'><p className='eyebrow'>CURRENT RECIPE</p><code>format: webp<br/>quality: {quality}<br/>metadata: {metadata?'keep':'strip'}</code></div><div className='actions'><Button onPress={()=>setSaved({quality,metadata})}>Apply to preview</Button><Button variant='tertiary' onPress={()=>{setQuality(80);setMetadata(false);setSaved(null)}}>Reset</Button></div><p role='status' className='status'>{saved?`Preview recipe applied: quality ${saved.quality}, metadata ${saved.metadata?'kept':'stripped'}. No file was generated.`:'Adjust quality with the arrow keys, then apply the recipe.'}</p></section></div><footer>Native HeroUI 3.2.6 controls and official compiled styles. Artwork and page layout are original CSS.</footer></main>;
}
Switch.Control ve Switch.Thumb, görünür bileşen yapısının gerekli parçalarıdır.
onPress bir tarifi uygular; görüntünün kodlandığını iddia etmez.
Özgün düzen CSS
Yüzey ve yarıçap referansları HeroUI değişkenlerini kullanır; çizim renkleri, yazı tipi ölçeği ve kesme noktası açıkça belirtilmiş uygulama tercihleridir.
Bu CSS dosyasını resmî stil sayfasından sonra yükleyin.
html üzerindeki dark sınıfı, belgenin tamamındaki anlamsal değerleri değiştirir.
04
HeroUI Tasarım Sistemi Aracı Kurulumu
Uygulamaya Başlangıç Noktası
Yerel önizleme React 19 ve HeroUI 3.2.6 ile doğrulandı. Sağlanan App ve düzen CSS dosyaları eksiksizdir. Bu Vite yapılandırması, belgelenmiş Tailwind v4 içe aktarma işlem hattını kullanır; çevrimdışı örnekte ise resmî, önceden derlenmiş stil sayfası satır içine alınır.
jsx
// In a Vite React 19 project:
// npm install @heroui/[email protected] @heroui/[email protected] tailwindcss@^4 @tailwindcss/vite@^4
// vite.config.js
import {defineConfig} from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';
export default defineConfig({plugins:[react(),tailwindcss()]});
// globals.css: keep this import order
// @import "tailwindcss";
// @import "@heroui/styles";
// Paste the Original layout CSS after these imports.
// main.jsx
import React from 'react';
import {createRoot} from 'react-dom/client';
import './globals.css';
import App from './App.jsx';
createRoot(document.getElementById('root')).render(<App/>);
// App.jsx is the complete application above. Remove its './style.css'
// import when the same CSS is included in globals.css.
Projeniz İçin Bir İstem
Ajan İstemi
Görüntü dışa aktarma stüdyosunu oluşturmak için sağlanan HeroUI 3.2.6 App.jsx dosyasını, stil sayfasını ve Tailwind entegrasyonunu kullanın. Slider kalite durumunu ve Switch meta veri durumunu dışa aktarma özetiyle bağlantılı tutun; Switch.Content, Control ve Thumb parçalarını etiketleriyle birlikte koruyun. Kalite veya meta veri değiştiğinde kaydedilmiş anlık görüntü geçersiz kılınmalıdır. Koyu görünüm denetimi, stil sayfasının kullandığı aynı belge sınıfını değiştirmelidir. Yalnızca yerel bir dışa aktarma tarifi kaydedin; bir görüntü dosyasının işlendiğini veya indirildiğini ima etmeyin.
05
HeroUI Tasarım Sistemi Kaynakları ve Kapsamı
HeroUI 3.2.6 referansı. Resmî değişkenler, özgün tipografi, çizim ve düzenden ayrı olarak belirtilmiştir. Yerel önizleme yalnızca bellekte tutulan ayarları değiştirir ve görüntü kodlaması yapmaz.
