ad-desing

ad-desing, farklı projelerde tekrar kullanılabilen, modüler ve ölçeklenebilir bir vanilla CSS UI framework / design system altyapısıdır.

Hedef

• Semantic component class'ları (.btn, .card, .alert)
• Utility class yaklaşımı (.d-flex, .mt-4, .text-center)
• Token tabanlı theme yönetimi
• Framework bağımsız kullanım (React, Vue, ASP.NET Core MVC, plain HTML)
• Storybook ile yaşayan dokümantasyon

Kurulum

npm install
npm run build-tokens

NPM Paketi Olarak Kullanım

Paket başka bir projeye eklendiğinde (React, Vue, Blazor, Jinja tabanlı sunucu render vb.) tek bir derlenmiş CSS dosyası import edilir:

npm i @ademaydemir/ad-design

Bundler kullanan projelerde:

import "@ademaydemir/ad-design/dist/ad.css";

Bundler kullanmayan projelerde:

• node_modules/@ademaydemir/ad-design/dist/ad.css dosyasını kendi statik klasörüne kopyalayın
• layout dosyanızda <link rel="stylesheet" href="/css/ad.css"> olarak ekleyin

Storybook:

npm run storybook

Root playground (Vite):

npm run dev

Storybook Bilgi Mimarisi

• Foundations
  • Colors
  • Typography
  • Spacing
  • Radius
  • Shadows
• Components
  • Alert
  • Badge
  • Button
  • Card
  • Input
  • Select
  • Textarea
• Utilities
  • Display
  • Flex
  • Spacing
  • Text
  • Radius
  • Shadow

Proje Yapısı

ad-desing/
  .github/workflows/
  .storybook/
    main.js
    preview.js
    preview-head.html
    static/logos/{en,tr}/
  tokens/
    colors.json
  src/
    assets/logos/{en,tr}/
    base/
    css/
      ad.css
      utilities.css
    styles/
      tokens.css (build ile üretilir)
    components/
      *.css
      *.js
      *.stories.js
      STORY_STANDARD.md
      StoryTemplate.js
      storyHelpers.js
    utilities/
    index.css
  build-tokens.js
  tailwind.config.js
  tailwind-preset.js
  postcss.config.js
  vite.config.js
  index.html

Token ve Theme Hattı

• Tek kaynak: tokens/colors.json
• Üretici script: build-tokens.js
• Çıktı: src/styles/tokens.css

tokens.css içinde:

• light varsayılan palette (:root)
• dark override ([data-theme="dark"])
• semantic alias tokenlar (--ui-color-*)
• typography / spacing / radius / shadow / breakpoint tokenları

Tailwind Entegrasyonu

Tailwind aktif olarak projeye entegredir:

• tailwind.config.js
• tailwind-preset.js
• postcss.config.js

Notlar:

• corePlugins.preflight = false (mevcut component görünümünü korumak için)
• Tailwind tasarım tokenları var(--ui-*) üzerinden consume eder

Component Story Standardı

Her yeni component için src/components altında:

• <Component>.js
• <Component>.stories.js

Önerilen story başlıkları:

• Overview
• Variants
• Sizes
• States
• Usage
• Playground

Form bileşenlerinde States sırası:

1. default
2. focus
3. disabled
4. invalid/error
5. placeholder

Detaylı standart için:

• src/components/STORY_STANDARD.md

Dark Theme Hazırlığı

Storybook toolbar üzerinden Light / Dark seçimi yapılır.

Uygulama:

• preview.js global theme toolbar
• root element üstünde data-theme set edilmesi
• token değerlerinin otomatik değişmesi

Test ve Build

npm run build-tokens
npm run build-storybook
npm run test-storybook

Kısa Kullanım Örnekleri

<button class="btn btn-primary">Kaydet</button>
<input class="input" placeholder="Ad Soyad" />
<select class="select"><option>Seçim yapın</option></select>
<textarea class="textarea" placeholder="Mesaj"></textarea>
<div class="alert alert-info">Bilgilendirme</div>
<span class="badge badge-success">Aktif</span>