docs: fix some errors and describe the recommended pattern of writing styleName

Author: cray0000

docs/api/jsx-props.md

@@ -13,28 +13,21 @@ Apply class-based styles to an element. Works like `className` but with scoped,
 **Syntax Options:**
 
 ```jsx
-// String
+// String — simple static class
 <div styleName="card" />
 
-// Object - keys with truthy values are included
-<div styleName={{ card: true, active, highlighted }} />
-
-// Array - falsy values are filtered out
-<div styleName={['card', active && 'active']} />
-
-// Mixed - combine arrays, strings, and objects (recommended)
-<div styleName={['button', variant, { active, disabled }]} />
+// Array with object — recommended for dynamic classes
+<div styleName={['card', variant, { active, disabled }]} />
 ```
 
-### Modifier Classes with Object/Array Syntax
+### Array Pattern (Recommended)
 
-The object and array syntax is cleaner than string interpolation for conditional classes. Name your variables to match the CSS class names for the cleanest syntax:
+Use arrays with an object at the end for modifiers:
 
 ```jsx
-function Card({ highlighted, compact }) {
+function Card({ variant, highlighted, compact }) {
   return (
-    // Object shorthand - cleanest when variable names match class names
-    <div styleName={{ card: true, highlighted, compact }}>
+    <div styleName={['card', variant, { highlighted, compact }]}>
       Content
     </div>
   )
@@ -44,21 +37,22 @@ function Card({ highlighted, compact }) {
       background white
       border 1px solid #ddd
       padding 16px
+    .card.featured
+      border 2px solid gold
     .card.highlighted
-      border-color gold
       box-shadow 0 0 10px gold
     .card.compact
       padding 8px
   `
 }
 ```
 
-Compare this to the less readable string interpolation:
+The pattern:
+- Static base classes first (`'card'`)
+- Dynamic variant strings next (`variant` — could be `'featured'`, `'simple'`, etc.)
+- Boolean modifiers in an object at the end (`{ highlighted, compact }`)
 
-```jsx
-// Avoid - harder to read with multiple modifiers
-<div styleName={`card ${highlighted ? 'highlighted' : ''} ${compact ? 'compact' : ''}`}>
-```
+**Tip:** Name variables to match class names for clean shorthand: `{ active }` instead of `{ active: isActive }`.
 
 ### Dynamic Styles
 

docs/api/pug.md

@@ -60,11 +60,11 @@ div.card.featured.large
 ### Dynamic Classes
 
 ```jsx
-// With condition
-div.button(styleName={active && 'active'})
+// Array with object for modifiers (recommended)
+div.button(styleName=['button', variant, { active, disabled }])
 
 // Object syntax
-div.button(styleName={{ active, disabled }})
+div.button(styleName={ active, disabled })
 ```
 
 ## Attributes
@@ -90,9 +90,9 @@ div.card(part="root")
 ### Text Content
 
 ```jsx
-h1.title= title          // Variable
-p.text Hello World       // Static text
-span.count {count} items // Inline JS
+h1.title= title              // Variable
+p.text Hello World           // Static text
+span.count #{count} items    // Inline interpolation
 ```
 
 ### Children
@@ -262,7 +262,7 @@ If you don't use Pug, disable it for faster builds:
 |---------|-----|-----|
 | Class names | `styleName="a b"` | `.a.b` |
 | Attributes | `prop={value}` | `(prop=value)` |
-| Text | `{text}` | `= text` |
+| Text | `{text}` | `= text` or `#{text}` inline |
 | Conditionals | `{cond && <El />}` | `if cond` |
 | Loops | `{items.map(...)}` | `each item in items` |
 

docs/api/styl-function.md

@@ -58,13 +58,7 @@ The first argument supports the same syntax as `styleName`:
 // String
 <Card {...styl('card')} />
 
-// Object
-<Card {...styl({ card: true, highlighted, compact })} />
-
-// Array
-<Card {...styl(['card', active && 'active'])} />
-
-// Mixed
+// Array with object (recommended)
 <Card {...styl(['card', variant, { highlighted, disabled }])} />
 ```
 

docs/examples/button.md

@@ -5,9 +5,9 @@ A simple button with variants and sizes.
 ```jsx
 import { styl } from 'cssxjs'
 
-function Button({ variant = 'primary', size = 'medium', children }) {
+function Button({ variant = 'primary', size = 'medium', disabled, children }) {
   return (
-    <button styleName={{ button: true, [variant]: true, [size]: true }}>
+    <button styleName={['button', variant, size, { disabled }]}>
       {children}
     </button>
   )
@@ -60,6 +60,6 @@ function Button({ variant = 'primary', size = 'medium', children }) {
 
 ## Key Concepts
 
-- **Dynamic class names** with computed property syntax `[variant]: true`
+- **Array pattern** `['button', variant, size, { disabled }]` — base class, variants, then boolean modifiers
 - **Compound selectors** for size variants (`.small`, `.medium`, `.large`)
-- **Object shorthand** in `styleName` for cleaner conditional classes
+- **Object shorthand** `{ disabled }` for boolean modifiers

docs/examples/form.md

@@ -11,8 +11,9 @@ function Input({
   hint,
   ...inputProps  // native input props (type, value, onChange, etc.)
 }) {
+  const hasError = !!error
   return (
-    <div part="root" styleName={{ field: true, error: !!error }}>
+    <div part="root" styleName={['field', { error: hasError }]}>
       {label && (
         <label part="label" styleName="label">
           {label}
@@ -88,7 +89,7 @@ function Input({
 
 ## Key Concepts
 
-- **Conditional error class** with `{ error: !!error }`
+- **Array pattern** with boolean modifier `['field', { error: hasError }]`
 - **Nested selectors** for error state styling (`.error .input`)
 - **Focus states** with `&:focus`
 - **`part` attribute** for external customization

docs/examples/list.md

@@ -19,7 +19,7 @@ function SelectableList({ items, onSelect }) {
       {items.map(item => (
         <li
           key={item.id}
-          styleName={{ item: true, selected: selectedId === item.id }}
+          styleName={['item', { selected: selectedId === item.id }]}
           onClick={() => handleSelect(item)}
         >
           <span styleName="icon">{item.icon}</span>
@@ -98,6 +98,6 @@ const items = [
 
 ## Key Concepts
 
-- **Dynamic selection state** with `{ selected: selectedId === item.id }`
+- **Array pattern** `['item', { selected: ... }]` for dynamic selection
 - **List item layout** with flexbox
 - **Modifier class** `.selected` for active state

docs/examples/tabs.md

@@ -17,7 +17,7 @@ function Tabs({ tabs, defaultTab }) {
         {tabs.map(tab => (
           <button
             key={tab.id}
-            styleName={{ tab: true, active: activeTab === tab.id }}
+            styleName={['tab', { active: activeTab === tab.id }]}
             onClick={() => setActiveTab(tab.id)}
             role="tab"
             aria-selected={activeTab === tab.id}
@@ -95,7 +95,7 @@ const tabs = [
 
 ## Key Concepts
 
-- **Active indicator** using `::after` pseudo-element
+- **Array pattern** `['tab', { active: ... }]` for dynamic active state
+- **Active indicator** using `&.active::after` pseudo-element
 - **Accessibility** with `role="tablist"`, `role="tab"`, `aria-selected`
-- **Dynamic active class** with `{ active: activeTab === tab.id }`
 - **Flexible layout** with `flex: 1` for equal-width tabs

docs/guide/pug.md

@@ -81,17 +81,16 @@ div.card.featured.large
 
 ### Dynamic Classes
 
-Use curly braces for dynamic values:
+Use array with object for modifiers (recommended):
 
 ```jsx
-div.button(styleName={isActive && 'active'})
-// → <div styleName={`button ${isActive && 'active'}`} />
+div.button(styleName=['button', variant, { active, disabled }])
 ```
 
-Or with object syntax:
+Or object syntax only:
 
 ```jsx
-div.button(styleName={active: isActive, disabled: isDisabled})
+div.button(styleName={ active, disabled })
 ```
 
 ## Attributes
@@ -119,9 +118,9 @@ div.card(part="root")
 Use `=` for interpolated text or plain text after the tag:
 
 ```jsx
-h1.title= title          // Variable interpolation
-p.text Hello World       // Static text
-span.count {count} items // Curly braces for inline JS
+h1.title= title              // Variable interpolation
+p.text Hello World           // Static text
+span.count #{count} items    // Inline interpolation with #{}
 ```
 
 ### Children

docs/guide/usage.md

@@ -7,9 +7,9 @@ This guide covers the essentials of CSSX: writing styles and applying them to co
 ```jsx
 import { styl } from 'cssxjs'
 
-function Button({ children, primary }) {
+function Button({ children, variant, disabled }) {
   return (
-    <button styleName={{ button: true, primary }}>
+    <button styleName={['button', variant, { disabled }]}>
       {children}
     </button>
   )
@@ -24,6 +24,9 @@ function Button({ children, primary }) {
     .button.primary
       background #007bff
       color white
+
+    .button.disabled
+      opacity 0.5
   `
 }
 ```
@@ -66,32 +69,72 @@ css`
 
 ## Applying Styles with styleName
 
-The `styleName` prop connects elements to CSS classes:
+The `styleName` prop connects elements to CSS classes. For simple cases, use a string:
 
 ```jsx
-// String
 <div styleName="card" />
+```
+
+### The Recommended Pattern
+
+For dynamic styling, use the **array pattern** — it's the cleanest and most maintainable approach:
+
+```jsx
+<div styleName={['card', variant, { highlighted, compact }]} />
+```
+
+This pattern has three parts, in order:
+
+1. **Base class** — the main class name (`'card'`)
+2. **Variant variables** — string variables that map to class names (`variant`)
+3. **Boolean modifiers** — an object where keys become classes when values are truthy (`{ highlighted, compact }`)
+
+**Example breakdown:**
+
+```jsx
+function Card({ variant = 'default', highlighted, compact }) {
+  // If variant='featured', highlighted=true, compact=false
+  // Results in: class="card featured highlighted"
+  return (
+    <div styleName={['card', variant, { highlighted, compact }]}>
+      Content
+    </div>
+  )
 
-// Object — keys with truthy values are included
-<div styleName={{ card: true, active, highlighted }} />
+  styl`
+    .card
+      background white
+      padding 16px
 
-// Array — falsy values are filtered out
-<div styleName={['card', active && 'active']} />
+    .card.featured
+      border 2px solid gold
+
+    .card.highlighted
+      box-shadow 0 0 10px gold
 
-// Mixed — combine all syntaxes
-<div styleName={['card', variant, { active, disabled }]} />
+    .card.compact
+      padding 8px
+  `
+}
 ```
 
-**Tip:** Name variables to match class names for clean shorthand: `{ active }` instead of `{ active: isActive }`.
+**Why this pattern works:**
+
+- **Readable** — clear separation between base, variants, and modifiers
+- **Clean** — no verbose `{ card: true, [variant]: true }` syntax
+- **Flexible** — add as many variants or modifiers as needed
+- **Maintainable** — easy to see what classes are applied
+
+**Tip:** Name your variables to match class names for clean shorthand: use `{ active }` instead of `{ active: isActive }`. This makes the code self-documenting.
 
 ## Modifier Classes
 
 Use compound selectors for variants:
 
 ```jsx
-function Card({ highlighted, compact }) {
+function Card({ variant, highlighted, compact }) {
   return (
-    <div styleName={{ card: true, highlighted, compact }}>
+    <div styleName={['card', variant, { highlighted, compact }]}>
       Content
     </div>
   )
@@ -101,9 +144,12 @@ function Card({ highlighted, compact }) {
       background white
       padding 16px
 
-    .card.highlighted
+    .card.featured
       border 2px solid gold
 
+    .card.highlighted
+      box-shadow 0 0 10px gold
+
     .card.compact
       padding 8px
   `