@bookklik/senangstart-css 0.1.2 → 0.1.4

package/docs/ms/guide/states.md

@@ -0,0 +1,162 @@
+# Hover & Keadaan
+
+Tambah gaya interaktif dengan prefiks keadaan.
+
+## Prefiks Keadaan
+
+| Prefiks | Pencetus |
+|---------|----------|
+| `hover:` | Tetikus atas elemen |
+| `focus:` | Elemen mempunyai fokus |
+| `active:` | Elemen sedang diklik |
+| `disabled:` | Elemen adalah disabled |
+
+## Penggunaan Asas
+
+### Hover
+
+```html
+<button visual="bg:primary hover:bg:[#2563EB] text:white">
+  Hover saya
+</button>
+
+<a visual="text:grey hover:text:primary">
+  Pautan dengan warna hover
+</a>
+```
+
+### Focus
+
+```html
+<input
+  visual="border:grey focus:border:primary"
+  space="p:small"
+/>
+```
+
+### Active
+
+```html
+<button visual="bg:primary active:bg:[#1D4ED8]">
+  Klik saya
+</button>
+```
+
+### Disabled
+
+```html
+<button visual="bg:primary disabled:bg:grey disabled:opacity:[0.5]">
+  Hantar
+</button>
+```
+
+## Corak Biasa
+
+### Butang dengan Keadaan
+
+```html
+<button
+  space="p-x:big p-y:small"
+  visual="
+    bg:primary 
+    text:white 
+    rounded:medium
+    hover:bg:[#2563EB]
+    active:bg:[#1D4ED8]
+    disabled:bg:grey
+    disabled:opacity:[0.5]
+  "
+>
+  Hantar
+</button>
+```
+
+### Kad dengan Kesan Hover
+
+```html
+<div
+  layout="flex col"
+  space="p:medium"
+  visual="
+    bg:white 
+    rounded:big 
+    shadow:small
+    hover:shadow:big
+  "
+>
+  <h3>Tajuk Kad</h3>
+  <p>Kandungan kad yang terangkat apabila hover.</p>
+</div>
+```
+
+### Navigasi Pautan
+
+```html
+<nav layout="flex" space="g:medium">
+  <a visual="text:dark hover:text:primary font:medium">Laman Utama</a>
+  <a visual="text:grey hover:text:primary">Tentang</a>
+  <a visual="text:grey hover:text:primary">Hubungi</a>
+</nav>
+```
+
+### Input dengan Cincin Fokus
+
+```html
+<input
+  type="text"
+  space="p:small w:[100%]"
+  visual="
+    border:grey 
+    border-w:[1px]
+    rounded:small
+    focus:border:primary
+  "
+  placeholder="Masukkan emel anda"
+/>
+```
+
+### Butang Toggle
+
+```html
+<button
+  space="p:small"
+  visual="
+    bg:light
+    text:dark
+    rounded:medium
+    hover:bg:grey
+    active:bg:dark
+    active:text:white
+  "
+>
+  Toggle
+</button>
+```
+
+## Menggabungkan dengan Responsif
+
+Keadaan boleh digabungkan dengan prefiks responsif:
+
+```html
+<button visual="
+  bg:primary
+  hover:bg:[#2563EB]
+  tab:hover:shadow:big
+">
+  Bayang hover hanya pada tablet+
+</button>
+```
+
+## Nota Kebolehcapaian
+
+Sentiasa pastikan kontras warna yang mencukupi untuk keadaan hover dan focus. Keadaan `:focus` terutamanya penting untuk navigasi papan kekunci.
+
+```html
+<button visual="
+  bg:primary
+  text:white
+  focus:shadow:[0_0_0_3px_rgba(59,130,246,0.5)]
+">
+  Cincin fokus yang boleh diakses
+</button>
+```

package/docs/ms/guide/tri-attribute.md

@@ -0,0 +1,187 @@
+# Sintaksis Tri-Atribusi
+
+SenangStart mengasingkan aspek stail kepada tiga atribusi yang berbeza.
+
+## Gambaran Keseluruhan
+
+| Atribusi | Tujuan | Contoh |
+|---------|--------|--------|
+| `layout` | Struktur & kedudukan | `layout="flex col center"` |
+| `space` | Saiz & jarak | `space="p:medium g:small"` |
+| `visual` | Warna & penampilan | `visual="bg:white rounded:big"` |
+
+## Mengapa Tiga Atribusi?
+
+### Kelas CSS tradisional adalah huru-hara:
+
+```html
+<div class="flex flex-col items-center p-4 gap-2 bg-white rounded-lg shadow-md">
+```
+
+Semua bercampur aduk. Mana layout? Mana spacing? Mana visual?
+
+### SenangStart adalah teratur:
+
+```html
+<div
+  layout="flex col center"
+  space="p:medium g:small"
+  visual="bg:white rounded:big shadow:medium"
+>
+```
+
+**Pengasingan jelas.** Sesiapa yang baca kod ini terus tahu:
+- **Struktur:** Flexbox column, di tengah
+- **Saiz:** Medium padding, small gap
+- **Penampilan:** Putih, bulat, berlorek
+
+## Atribusi `layout`
+
+Mengawal **bagaimana elemen diposisikan** dan **bagaimana ia mengalir**.
+
+### Jenis Paparan
+
+```html
+<div layout="flex">Kontena Flexbox</div>
+<div layout="grid">Kontena Grid</div>
+<div layout="block">Elemen Block</div>
+<div layout="hidden">Elemen Tersembunyi</div>
+```
+
+### Arah Flex
+
+```html
+<div layout="flex row">Horizontal (lalai)</div>
+<div layout="flex col">Menegak</div>
+<div layout="flex row-reverse">Horizontal terbalik</div>
+<div layout="flex col-reverse">Menegak terbalik</div>
+```
+
+### Penjajaran
+
+```html
+<div layout="flex center">Tengah kedua-dua paksi</div>
+<div layout="flex between">Jarak antara item</div>
+<div layout="flex start">Jajar ke permulaan</div>
+<div layout="flex end">Jajar ke hujung</div>
+```
+
+### Kedudukan
+
+```html
+<nav layout="fixed z:top">Navigasi Fixed</nav>
+<div layout="sticky">Elemen Sticky</div>
+<div layout="absolute z:high">Absolute positioned</div>
+<div layout="relative">Relative positioned</div>
+```
+
+## Atribusi `space`
+
+Mengawal **saiz dan jarak** menggunakan skala semula jadi.
+
+### Sintaksis
+
+```
+[breakpoint]:[property]:[scale]
+```
+
+### Padding
+
+```html
+<div space="p:medium">Semua sisi</div>
+<div space="p-x:big p-y:small">Horizontal & menegak</div>
+<div space="p-t:small p-b:big">Atas & bawah</div>
+```
+
+### Margin
+
+```html
+<div space="m:medium">Semua sisi</div>
+<div space="m-b:big">Bawah sahaja</div>
+<div space="m-x:auto">Tengah secara horizontal</div>
+```
+
+### Sela (Flex/Grid)
+
+```html
+<div layout="flex" space="g:small">Small gap</div>
+<div layout="grid" space="g:medium">Medium gap</div>
+```
+
+### Saiz
+
+```html
+<div space="w:[100%] h:[400px]">Saiz eksplisit</div>
+<div space="max-w:[1200px] min-h:[80vh]">Kekangan</div>
+```
+
+### Nilai Arbitrari (Escape Hatch)
+
+Guna kurungan untuk nilai spesifik:
+
+```html
+<div space="w:[350px]">Lebar 350px</div>
+<div space="p:[20px_40px]">20px atas/bawah, 40px kiri/kanan</div>
+<div space="m-t:[5rem]">5rem margin atas</div>
+```
+
+## Atribusi `visual`
+
+Mengawal **warna, tekstur, dan penampilan**.
+
+### Latar Belakang
+
+```html
+<div visual="bg:white">Latar belakang putih</div>
+<div visual="bg:primary">Warna primary</div>
+<div visual="bg:[#FF5733]">Hex tersuai</div>
+```
+
+### Teks
+
+```html
+<span visual="text:dark">Teks gelap</span>
+<span visual="text:grey text-size:small">Kelabu, teks kecil</span>
+<span visual="font:bold">Teks tebal</span>
+```
+
+### Sempadan & Bayang
+
+```html
+<div visual="rounded:medium shadow:big">Bulat dengan bayang</div>
+<div visual="border:grey border-w:[2px]">Sempadan kelabu</div>
+```
+
+### Menggabungkan Sari Diri
+
+```html
+<div visual="bg:white rounded:big shadow:medium text:dark">
+  Kad dengan pelbagai visual properties
+</div>
+```
+
+## Menggabungkan Ketiga-tiga
+
+Berikut contoh lengkap:
+
+```html
+<div
+  layout="flex col"
+  space="w:[320px] p:medium g:small"
+  visual="bg:white rounded:big shadow:medium"
+>
+  <h2 visual="font:bold text-size:big text:dark">Tajuk Kad</h2>
+  <p visual="text:grey">Penerangan kad di sini.</p>
+  <button
+    space="p-x:big p-y:small"
+    visual="bg:primary text:white rounded:medium"
+  >
+    Tindakan
+  </button>
+</div>
+```
+
+**Membaca kod ini:**
+- Kontena adalah flex column menegak, lebar 320px, dengan medium padding, small gap, latar belakang putih, sudut bulat big, dan bayang medium
+- Tajuk adalah bold, teks big, warna dark
+- Butang mempunyai big horizontal padding, small vertical padding, latar belakang primary, teks putih, sudut bulat medium

package/docs/ms/index.md

@@ -0,0 +1,64 @@
+---
+layout: home
+
+hero:
+  name: SenangStart CSS
+  text: Enjin CSS Niat Nan Utama
+  tagline: Cakap Manusia. Kompil ke Logik.
+  image:
+    src: https://senangstart.com/img/use_senangstart.svg
+    alt: SenangStart CSS
+  actions:
+    - theme: brand
+      text: Bermula
+      link: /ms/guide/getting-started
+    - theme: alt
+      text: Lihat di GitHub
+      link: https://github.com/bookklik-technologies/senangstart-css
+
+features:
+  - icon: 🧠
+    title: Bahasa Semula Jadi
+    details: Guna tiny, small, medium, big, giant, vast — perkataan yang anda sudah tahu. Tak perlu hafal px-4, px-8, px-16.
+  - icon: 🎯
+    title: Pengasingan Tanggungjawab
+    details: layout untuk struktur, space untuk saiz, visual untuk penampilan. Bersih, semantik, mudah diselenggara.
+  - icon: 🤖
+    title: Mesra AI
+    details: Menghasilkan fail konteks untuk LLM. Cakap "ketatkan" dan AI tahu untuk kurangkan jarak.
+  - icon: ⚡
+    title: Pilihan Tanpa Bina
+    details: Guna CDN JIT runtime untuk stail serta-merta. Tiada langkah bina diperlukan untuk prototaip.
+  - icon: 📱
+    title: Responsif Secara Rekaan
+    details: Titik Henti mobile-first dengan prefiks intuitif seperti mob:, tab:, lap:, desk:.
+  - icon: 🎨
+    title: Boleh Disesuaikan Sepenuhnya
+    details: Tindih ganti mana-mana skala, tambah warna tersuai, lanjutkan tema untuk padankan jenama anda.
+---
+
+<style>
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #2563EB 30%, #3B82F6);
+  --vp-home-hero-image-background-image: linear-gradient(-45deg, #2563EB 50%, #3B82F6 50%);
+  --vp-home-hero-image-filter: blur(44px);
+  --vp-c-brand-1: #2563EB;
+  --vp-c-brand-2: #3B82F6;
+  --vp-c-brand-3: #DBEAFE;
+}
+</style>
+
+## Contoh Pantas
+
+```html
+<div
+  layout="flex col center"
+  space="p:big"
+  visual="bg:primary text:white rounded:big"
+>
+  Hello SenangStart!
+</div>
+```
+
+Ini mencipta flexbox column, di tengah, dengan padding big, latar belakang primary, teks putih, dan sudut bulat big. **Tiada kelas CSS untuk dihafal.**

package/docs/ms/reference/breakpoints.md

@@ -0,0 +1,131 @@
+# Rujukan Titik Henti
+
+Rujukan lengkap untuk breakpoint responsif.
+
+## Titik Henti Lalai
+
+| Prefiks | Min-Width | Sasaran Peranti |
+|---------|-----------|-----------------|
+| (tiada) | 0px | Mudah alih (lalai) |
+| `mob:` | 480px | Mudah alih besar |
+| `tab:` | 768px | Tablet |
+| `lap:` | 1024px | Komputer riba |
+| `desk:` | 1280px | Desktop |
+
+## Media Query CSS
+
+```css
+/* Mobile first - tiada prefiks diperlukan */
+
+@media (min-width: 480px) { /* mob: */ }
+@media (min-width: 768px) { /* tab: */ }
+@media (min-width: 1024px) { /* lap: */ }
+@media (min-width: 1280px) { /* desk: */ }
+```
+
+## Penggunaan
+
+### Jarak Responsif
+
+```html
+<div space="p:small tab:p:medium lap:p:big">
+  Padding progresif
+</div>
+```
+
+### Layout Responsif
+
+```html
+<div layout="flex col tab:row">
+  Column pada mudah alih, row pada tablet+
+</div>
+
+<nav layout="hidden tab:flex">
+  Tersembunyi pada mudah alih, kelihatan pada tablet+
+</nav>
+```
+
+### Tipografi Responsif
+
+```html
+<h1 visual="text-size:big tab:text-size:giant lap:text-size:vast">
+  Tajuk responsif
+</h1>
+```
+
+## Pendekatan Mobile-First
+
+SenangStart menggunakan reka bentuk responsif mobile-first:
+
+1. **Gaya asas** digunakan untuk semua saiz skrin
+2. **Prefiks breakpoint** digunakan dari breakpoint itu KE ATAS
+
+```html
+<!-- Ini bermaksud: -->
+<!-- - Mudah alih: small padding -->
+<!-- - Tablet dan ke atas: medium padding -->
+<!-- - Laptop dan ke atas: big padding -->
+<div space="p:small tab:p:medium lap:p:big">
+  Kandungan
+</div>
+```
+
+## Penyesuaian
+
+Tambah atau ubah breakpoint dalam `senangstart.config.js`:
+
+```javascript
+export default {
+  theme: {
+    screens: {
+      'mob': '480px',
+      'tab': '768px',
+      'lap': '1024px',
+      'desk': '1280px',
+      'wide': '1536px',    // Tambah lebih lebar
+      'ultra': '1920px'    // Tambah ultra-wide
+    }
+  }
+}
+```
+
+Guna breakpoint tersuai:
+
+```html
+<div space="desk:p:big wide:p:giant ultra:p:vast">
+  Padding skrin besar
+</div>
+```
+
+## Corak Biasa
+
+### Tunjuk/Sembunyi Elemen
+
+```html
+<!-- Mudah alih sahaja -->
+<div layout="block tab:hidden">Menu mudah alih</div>
+
+<!-- Desktop sahaja -->
+<div layout="hidden lap:block">Sidebar desktop</div>
+```
+
+### Grid Responsif
+
+```html
+<div 
+  layout="grid"
+  space="g:small tab:g:medium"
+  style="grid-template-columns: 1fr; 
+         @media (min-width: 768px) { grid-template-columns: repeat(2, 1fr); }"
+>
+  Kad...
+</div>
+```
+
+### Kontena Responsif
+
+```html
+<div space="p:small tab:p:medium lap:p:big max-w:[1200px] m-x:auto">
+  Kontena di tengah dengan padding responsif
+</div>
+```