@bookklik/senangstart-css 0.1.1 → 0.1.2

package/docs/guide/natural-scale.md

@@ -0,0 +1,123 @@
+# The Natural Scale
+
+SenangStart uses natural adjectives that map to physical objects you can visualize.
+
+## The Philosophy
+
+Instead of arbitrary numbers, think of **physical objects**:
+
+| Keyword | Size | Mental Model |
+|---------|------|--------------|
+| `none` | 0px | No space |
+| `tiny` | 4px | 🪨 **Pebble** — Borders, small offsets |
+| `small` | 8px | 📦 **Matchbox** — Group related items |
+| `medium` | 16px | 📱 **Smartphone** — Standard default |
+| `big` | 32px | 💻 **Laptop** — Separate sections |
+| `giant` | 64px | 🚪 **Door** — Layout divisions |
+| `vast` | 128px | 🏠 **House** — Hero sections |
+
+## Using the Scale
+
+### When to use each size
+
+**`tiny` (4px)** — For subtle details
+- Icon spacing within buttons
+- Border widths
+- Small visual offsets
+
+```html
+<button space="p-x:small p-y:tiny">
+  <icon /> Button
+</button>
+```
+
+**`small` (8px)** — For grouping related items
+- Gap between label and input
+- Spacing between avatar and name
+- Tight list items
+
+```html
+<div layout="flex col" space="g:small">
+  <label>Email</label>
+  <input type="email" />
+</div>
+```
+
+**`medium` (16px)** — The standard default
+- Card padding
+- Form field margins
+- Standard component spacing
+
+```html
+<div space="p:medium">
+  Standard card content
+</div>
+```
+
+**`big` (32px)** — For separating distinct sections
+- Between header and content
+- Between form groups
+- Between major UI blocks
+
+```html
+<header space="m-b:big">Page Title</header>
+<main>Content separated from header</main>
+```
+
+**`giant` (64px)** — For layout divisions
+- Between page sections
+- Major structural breaks
+- Desktop navigation padding
+
+```html
+<section space="p-y:giant">
+  Major page section
+</section>
+```
+
+**`vast` (128px)** — For hero sections and major spacing
+- Hero section padding
+- Large decorative spacing
+- Full-bleed sections
+
+```html
+<section space="p:vast" visual="bg:dark">
+  <h1>Welcome to the App</h1>
+</section>
+```
+
+## Natural Language Mapping
+
+When talking about spacing adjustments, use natural language:
+
+| You say... | Action |
+|------------|--------|
+| "tighten it up" | Scale DOWN (medium → small → tiny) |
+| "compact" | Use small or tiny |
+| "give it air" | Scale UP (medium → big → giant) |
+| "breathe" | Increase spacing |
+| "spacious" | Use big or giant |
+| "cramped" | Too much tiny/small, increase scale |
+
+## Customizing the Scale
+
+Override defaults in `senangstart.config.js`:
+
+```javascript
+export default {
+  theme: {
+    spacing: {
+      'tiny': '2px',      // Tighter tiny
+      'huge': '256px',    // Add custom scale
+      'massive': '512px'  // Even bigger!
+    }
+  }
+}
+```
+
+Use your custom scales:
+
+```html
+<section space="p:huge">Huge padding</section>
+<div space="m-b:massive">Massive margin</div>
+```

package/docs/guide/philosophy.md

@@ -0,0 +1,103 @@
+# Why Natural Language?
+
+The philosophy behind SenangStart's natural adjective approach.
+
+## The Problem with Numbers
+
+Traditional utility frameworks use abstract numeric scales:
+
+```html
+<!-- What do these numbers mean? -->
+<div class="p-4 m-8 gap-2 text-xl">
+```
+
+Every developer asks:
+- Is `p-4` bigger than `m-8`?
+- What's the difference between `gap-2` and `gap-4`?
+- Is `text-xl` larger than `text-lg`?
+
+**You constantly lookup documentation.** Mental overhead slows you down.
+
+## The Natural Solution
+
+SenangStart uses words you already understand:
+
+```html
+<!-- Instantly clear -->
+<div space="p:medium m:big g:small" visual="text-size:big">
+```
+
+No lookup needed. You *know* that:
+- `big` is larger than `medium`
+- `medium` is larger than `small`
+- `giant` is larger than `big`
+
+## Physical Mental Models
+
+Each scale maps to a physical object you can visualize:
+
+| Keyword | Physical Model | Example Use |
+|---------|---------------|-------------|
+| `tiny` | 🪨 Pebble | Icon gaps, borders |
+| `small` | 📦 Matchbox | Form field spacing |
+| `medium` | 📱 Smartphone | Standard padding |
+| `big` | 💻 Laptop | Section spacing |
+| `giant` | 🚪 Door | Layout divisions |
+| `vast` | 🏠 House | Hero sections |
+
+When you think "I need laptop-sized spacing here", you write `big`.
+
+## AI-Friendly Communication
+
+Natural language works better with AI assistants:
+
+### Traditional Approach
+> "Make the padding larger"  
+> AI: "Should I use p-6, p-8, or p-12?"
+
+### SenangStart Approach
+> "Make the padding larger"  
+> AI: "Changed from `medium` to `big`" ✓
+
+The AI understands the *intent* behind your words.
+
+## Semantic Conversations
+
+With SenangStart, you can speak naturally:
+
+| You Say | AI Understands |
+|---------|---------------|
+| "tighten it up" | Scale DOWN (medium → small → tiny) |
+| "give it breathing room" | Scale UP (medium → big → giant) |
+| "make it more compact" | Use smaller spacing |
+| "it feels cramped" | Increase spacing |
+| "too much whitespace" | Reduce spacing |
+
+## Separation of Concerns
+
+Three attributes keep your code organized:
+
+```html
+<div
+  layout="flex col center"   <!-- Structure -->
+  space="p:medium g:small"   <!-- Sizing -->
+  visual="bg:white rounded:big"  <!-- Appearance -->
+>
+```
+
+Anyone reading this code instantly knows:
+- **What it does** (flexbox, column, centered)
+- **How big it is** (medium padding, small gap)
+- **How it looks** (white, rounded)
+
+## The Intent-First Mindset
+
+Stop thinking in pixels. Start describing intent.
+
+| Instead of... | Think... |
+|---------------|----------|
+| "I need 16px padding" | "I need medium padding" |
+| "Add 8px gap" | "Add a small gap" |
+| "Make it 32px margin" | "Give it big margin" |
+
+**Your code becomes self-documenting.**

package/docs/guide/responsive.md

@@ -0,0 +1,129 @@
+# Responsive Design
+
+SenangStart uses mobile-first responsive prefixes.
+
+## Breakpoints
+
+| Prefix | Min-Width | Device |
+|--------|-----------|--------|
+| (none) | 0px | Mobile (default) |
+| `mob:` | 480px | Large mobile |
+| `tab:` | 768px | Tablet |
+| `lap:` | 1024px | Laptop |
+| `desk:` | 1280px | Desktop |
+
+## Usage
+
+Add breakpoint prefixes to any space or layout value:
+
+```html
+<div space="p:small tab:p:medium lap:p:big">
+  <!-- Small padding on mobile -->
+  <!-- Medium padding on tablet+ -->
+  <!-- Big padding on laptop+ -->
+</div>
+```
+
+## Common Patterns
+
+### Responsive Padding
+
+```html
+<section space="p:medium tab:p:big desk:p:giant">
+  Content with progressive padding
+</section>
+```
+
+### Responsive Layout
+
+```html
+<div layout="flex col tab:row">
+  <!-- Stacked on mobile, horizontal on tablet+ -->
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+```
+
+### Responsive Grid
+
+```html
+<div
+  layout="grid"
+  space="g:small tab:g:medium"
+  style="grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));"
+>
+  <div>Card 1</div>
+  <div>Card 2</div>
+  <div>Card 3</div>
+</div>
+```
+
+### Hide on Mobile
+
+```html
+<nav layout="hidden tab:flex">
+  <!-- Hidden on mobile, flex on tablet+ -->
+</nav>
+```
+
+### Mobile Navigation
+
+```html
+<!-- Mobile menu button -->
+<button layout="block tab:hidden">☰ Menu</button>
+
+<!-- Desktop navigation -->
+<nav layout="hidden tab:flex" space="g:medium">
+  <a>Home</a>
+  <a>About</a>
+  <a>Contact</a>
+</nav>
+```
+
+## Full Responsive Example
+
+```html
+<div
+  layout="flex col lap:row"
+  space="p:medium tab:p:big gap:medium tab:gap:big"
+>
+  <!-- Sidebar -->
+  <aside
+    space="w:[100%] lap:w:[300px]"
+    visual="bg:light"
+  >
+    Sidebar content
+  </aside>
+  
+  <!-- Main content -->
+  <main space="w:[100%] lap:w:[calc(100%-300px)]">
+    Main content
+  </main>
+</div>
+```
+
+## Custom Breakpoints
+
+Override in `senangstart.config.js`:
+
+```javascript
+export default {
+  theme: {
+    screens: {
+      'mob': '480px',
+      'tab': '768px',
+      'lap': '1024px',
+      'desk': '1280px',
+      'wide': '1536px'  // Add custom breakpoint
+    }
+  }
+}
+```
+
+Use your custom breakpoint:
+
+```html
+<div space="p:big wide:p:giant">
+  Extra large padding on wide screens
+</div>
+```

package/docs/guide/states.md

@@ -0,0 +1,162 @@
+# Hover & States
+
+Add interactive styles with state prefixes.
+
+## State Prefixes
+
+| Prefix | Trigger |
+|--------|---------|
+| `hover:` | Mouse over element |
+| `focus:` | Element has focus |
+| `active:` | Element is being clicked |
+| `disabled:` | Element is disabled |
+
+## Basic Usage
+
+### Hover
+
+```html
+<button visual="bg:primary hover:bg:[#2563EB] text:white">
+  Hover me
+</button>
+
+<a visual="text:grey hover:text:primary">
+  Link with hover color
+</a>
+```
+
+### Focus
+
+```html
+<input
+  visual="border:grey focus:border:primary"
+  space="p:small"
+/>
+```
+
+### Active
+
+```html
+<button visual="bg:primary active:bg:[#1D4ED8]">
+  Click me
+</button>
+```
+
+### Disabled
+
+```html
+<button visual="bg:primary disabled:bg:grey disabled:opacity:[0.5]">
+  Submit
+</button>
+```
+
+## Common Patterns
+
+### Button with States
+
+```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]
+  "
+>
+  Submit
+</button>
+```
+
+### Card with Hover Effect
+
+```html
+<div
+  layout="flex col"
+  space="p:medium"
+  visual="
+    bg:white 
+    rounded:big 
+    shadow:small
+    hover:shadow:big
+  "
+>
+  <h3>Card Title</h3>
+  <p>Card content that lifts on hover.</p>
+</div>
+```
+
+### Link Navigation
+
+```html
+<nav layout="flex" space="g:medium">
+  <a visual="text:dark hover:text:primary font:medium">Home</a>
+  <a visual="text:grey hover:text:primary">About</a>
+  <a visual="text:grey hover:text:primary">Contact</a>
+</nav>
+```
+
+### Input with Focus Ring
+
+```html
+<input
+  type="text"
+  space="p:small w:[100%]"
+  visual="
+    border:grey 
+    border-w:[1px]
+    rounded:small
+    focus:border:primary
+  "
+  placeholder="Enter your email"
+/>
+```
+
+### Toggle Button
+
+```html
+<button
+  space="p:small"
+  visual="
+    bg:light
+    text:dark
+    rounded:medium
+    hover:bg:grey
+    active:bg:dark
+    active:text:white
+  "
+>
+  Toggle
+</button>
+```
+
+## Combining with Responsive
+
+States can be combined with responsive prefixes:
+
+```html
+<button visual="
+  bg:primary
+  hover:bg:[#2563EB]
+  tab:hover:shadow:big
+">
+  Hover shadow only on tablet+
+</button>
+```
+
+## Accessibility Note
+
+Always ensure sufficient color contrast for hover and focus states. The `:focus` state is especially important for keyboard navigation.
+
+```html
+<button visual="
+  bg:primary
+  text:white
+  focus:shadow:[0_0_0_3px_rgba(59,130,246,0.5)]
+">
+  Accessible focus ring
+</button>
+```

package/docs/guide/tri-attribute.md

@@ -0,0 +1,187 @@
+# Tri-Attribute Syntax
+
+SenangStart separates styling concerns into three distinct attributes.
+
+## Overview
+
+| Attribute | Purpose | Example |
+|-----------|---------|---------|
+| `layout` | Structure & positioning | `layout="flex col center"` |
+| `space` | Sizing & spacing | `space="p:medium g:small"` |
+| `visual` | Colors & appearance | `visual="bg:white rounded:big"` |
+
+## Why Three Attributes?
+
+### Traditional CSS classes are chaotic:
+
+```html
+<div class="flex flex-col items-center p-4 gap-2 bg-white rounded-lg shadow-md">
+```
+
+Everything is mixed together. What's layout? What's spacing? What's visual?
+
+### SenangStart is organized:
+
+```html
+<div
+  layout="flex col center"
+  space="p:medium g:small"
+  visual="bg:white rounded:big shadow:medium"
+>
+```
+
+**Clear separation.** Anyone reading this code instantly knows:
+- **Structure:** Flexbox column, centered
+- **Sizing:** Medium padding, small gap
+- **Appearance:** White, rounded, shadowed
+
+## The `layout` Attribute
+
+Controls **how elements are positioned** and **how they flow**.
+
+### Display Types
+
+```html
+<div layout="flex">Flexbox container</div>
+<div layout="grid">Grid container</div>
+<div layout="block">Block element</div>
+<div layout="hidden">Hidden element</div>
+```
+
+### Flex Direction
+
+```html
+<div layout="flex row">Horizontal (default)</div>
+<div layout="flex col">Vertical</div>
+<div layout="flex row-reverse">Reversed horizontal</div>
+<div layout="flex col-reverse">Reversed vertical</div>
+```
+
+### Alignment
+
+```html
+<div layout="flex center">Center both axes</div>
+<div layout="flex between">Space between items</div>
+<div layout="flex start">Align to start</div>
+<div layout="flex end">Align to end</div>
+```
+
+### Position
+
+```html
+<nav layout="fixed z:top">Fixed navigation</nav>
+<div layout="sticky">Sticky element</div>
+<div layout="absolute z:high">Absolute positioned</div>
+<div layout="relative">Relative positioned</div>
+```
+
+## The `space` Attribute
+
+Controls **sizing and spacing** using the natural scale.
+
+### Syntax
+
+```
+[breakpoint]:[property]:[scale]
+```
+
+### Padding
+
+```html
+<div space="p:medium">All sides</div>
+<div space="p-x:big p-y:small">Horizontal & vertical</div>
+<div space="p-t:small p-b:big">Top & bottom</div>
+```
+
+### Margin
+
+```html
+<div space="m:medium">All sides</div>
+<div space="m-b:big">Bottom only</div>
+<div space="m-x:auto">Center horizontally</div>
+```
+
+### Gap (Flex/Grid)
+
+```html
+<div layout="flex" space="g:small">Small gap</div>
+<div layout="grid" space="g:medium">Medium gap</div>
+```
+
+### Sizing
+
+```html
+<div space="w:[100%] h:[400px]">Explicit size</div>
+<div space="max-w:[1200px] min-h:[80vh]">Constraints</div>
+```
+
+### Arbitrary Values (Escape Hatch)
+
+Use brackets for specific values:
+
+```html
+<div space="w:[350px]">350px width</div>
+<div space="p:[20px_40px]">20px top/bottom, 40px left/right</div>
+<div space="m-t:[5rem]">5rem top margin</div>
+```
+
+## The `visual` Attribute
+
+Controls **colors, textures, and appearance**.
+
+### Background
+
+```html
+<div visual="bg:white">White background</div>
+<div visual="bg:primary">Primary color</div>
+<div visual="bg:[#FF5733]">Custom hex</div>
+```
+
+### Text
+
+```html
+<span visual="text:dark">Dark text</span>
+<span visual="text:grey text-size:small">Grey, small text</span>
+<span visual="font:bold">Bold text</span>
+```
+
+### Borders & Shadows
+
+```html
+<div visual="rounded:medium shadow:big">Rounded with shadow</div>
+<div visual="border:grey border-w:[2px]">Grey border</div>
+```
+
+### Combining Properties
+
+```html
+<div visual="bg:white rounded:big shadow:medium text:dark">
+  Card with multiple visual properties
+</div>
+```
+
+## Combining All Three
+
+Here's a complete example:
+
+```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">Card Title</h2>
+  <p visual="text:grey">Card description goes here.</p>
+  <button
+    space="p-x:big p-y:small"
+    visual="bg:primary text:white rounded:medium"
+  >
+    Action
+  </button>
+</div>
+```
+
+**Reading this code:**
+- The container is a vertical flex column, 320px wide, with medium padding, small gap, white background, big rounded corners, and medium shadow
+- The title is bold, big text, dark color
+- The button has big horizontal padding, small vertical padding, primary background, white text, medium rounded corners