solid-tom-ui 1.0.7 → 1.0.10

package/dist/skill/chat-bubble.skill.md.txt

@@ -0,0 +1,342 @@
+## COMPONENT IDENTITY
+- **Import**: `import { ChatBubble } from 'solid-tom-ui';`
+- **Export**: `ChatBubble` (named export)
+- **Framework**: SolidJS
+- **Purpose**: Chat message bubble — NOT a `ParentComponent`; all content passed via props
+
+---
+
+## TYPE SIGNATURE
+
+```ts
+type ChatBubbleProps = {
+  bubble: SolidComponent;       // REQUIRED — main message content
+  align?: 'start' | 'end';      // message side; no default applied in component
+  color?: BaseColorProps;        // bubble background color
+  avatar?: SolidComponent;      // avatar displayed beside the bubble
+  header?: SolidComponent;      // content above the bubble (name, timestamp, etc.)
+  footer?: SolidComponent;      // intended for status below bubble — see BUG note
+  class?: {
+    avatar?: string;            // extra classes on .chat-image wrapper
+    bubble?: string;            // extra classes on .chat-bubble wrapper
+    header?: string;            // extra classes on .chat-header wrapper
+    footer?: string;            // extra classes on .chat-footer wrapper
+  };
+};
+
+// BaseColorProps:
+type BaseColorProps =
+  | 'default' | 'neutral' | 'primary' | 'secondary' | 'accent'
+  | 'info' | 'success' | 'warning' | 'error';
+```
+
+---
+
+## PROP REFERENCE
+
+| Prop           | Type             | Required | Description                                                                                   |
+|----------------|------------------|----------|-----------------------------------------------------------------------------------------------|
+| `bubble`       | `SolidComponent` | ✅ YES   | Main message body — rendered inside `.chat-bubble` div                                        |
+| `align`        | `'start' \| 'end'` | ❌ NO  | `'start'` = left side (received); `'end'` = right side (sent). No default — omitting applies no alignment class |
+| `color`        | `BaseColorProps` | ❌ NO    | Background color of the bubble                                                                |
+| `avatar`       | `SolidComponent` | ❌ NO    | Rendered inside `.chat-image` — only shown when truthy (via `<Show>`)                        |
+| `header`       | `SolidComponent` | ❌ NO    | Rendered inside `.chat-header` above the bubble — only shown when truthy                     |
+| `footer`       | `SolidComponent` | ❌ NO    | **⚠️ BUG**: renders `bubble` content instead of `footer` — see bug section below             |
+| `class.avatar` | `string`         | ❌ NO    | Extra classes on `.chat-image` wrapper div                                                    |
+| `class.bubble` | `string`         | ❌ NO    | Extra classes on `.chat-bubble` wrapper div                                                   |
+| `class.header` | `string`         | ❌ NO    | Extra classes on `.chat-header` wrapper div                                                   |
+| `class.footer` | `string`         | ❌ NO    | Extra classes on `.chat-footer` wrapper div                                                   |
+
+---
+
+## ⚠️ KNOWN BUG — `footer` renders `bubble` content
+
+In the current source (`chatBubble.tsx` line 43), the `.chat-footer` div renders `props.bubble` instead of `props.footer`:
+
+```tsx
+// Source code (line 43) — BUG:
+<div class={cn('chat-footer', props.class?.footer)}>{props.bubble as Element}</div>
+//                                                            ^^^^^^ should be props.footer
+```
+
+**Impact for agents:**
+- The `footer` prop controls **visibility only** (via `<Show when={props.footer}>`) — if `footer` is truthy, the `.chat-footer` div renders with `bubble` content inside
+- The actual `footer` JSX value is **never rendered**
+- Do NOT rely on `footer` prop to display delivery status, timestamps, or any footer-specific content — it will show the bubble text instead
+- Until fixed, avoid using `footer` for any meaningful content
+
+---
+
+## COLOR REFERENCE
+
+| Value         | DaisyUI class             |
+|---------------|---------------------------|
+| `'default'`   | *(no class)*              |
+| `'neutral'`   | `chat-bubble-neutral`     |
+| `'primary'`   | `chat-bubble-primary`     |
+| `'secondary'` | `chat-bubble-secondary`   |
+| `'accent'`    | `chat-bubble-accent`      |
+| `'info'`      | `chat-bubble-info`        |
+| `'success'`   | `chat-bubble-success`     |
+| `'warning'`   | `chat-bubble-warning`     |
+| `'error'`     | `chat-bubble-error`       |
+
+---
+
+## INTERNAL DOM STRUCTURE
+
+```
+<div class="chat chat-start|chat-end">
+  │
+  ├── <Show when={avatar}>
+  │     <div class="chat-image [class.avatar]">
+  │       {avatar}
+  │     </div>
+  │   </Show>
+  │
+  ├── <Show when={header}>
+  │     <div class="chat-header [class.header]">
+  │       {header}
+  │     </div>
+  │   </Show>
+  │
+  ├── <Show when={bubble}>
+  │     <div class="chat-bubble chat-bubble-{color} [class.bubble]">
+  │       {bubble}
+  │     </div>
+  │   </Show>
+  │
+  └── <Show when={footer}>
+        <div class="chat-footer [class.footer]">
+          {bubble}    ← ⚠️ BUG: renders bubble, not footer
+        </div>
+      </Show>
+```
+
+All four sections (`avatar`, `header`, `bubble`, `footer`) are independently conditional via `<Show>`.
+
+---
+
+## ALIGN BEHAVIOR
+
+| `align`     | DaisyUI class  | Visual placement       | Typical use              |
+|-------------|----------------|------------------------|--------------------------|
+| `'start'`   | `chat-start`   | Left side of container | Received / incoming msg  |
+| `'end'`     | `chat-end`     | Right side of container | Sent / outgoing msg     |
+| *(omitted)* | *(none)*       | Browser default        | Avoid — renders unstyled |
+
+Always pass `align` explicitly. Omitting it leaves the chat div without a positioning class.
+
+---
+
+## AVATAR INTEGRATION
+
+`avatar` accepts any `SolidComponent`. Typically used with the `Avatar` component from `@/components/avatar/avatar`:
+
+```tsx
+import { Avatar } from 'solid-tom-ui';
+
+// Image avatar
+<ChatBubble
+  align="start"
+  avatar={<Avatar image="/profile.webp" width={40} />}
+  bubble={<span>Hello!</span>}
+/>
+
+// Placeholder avatar (initials)
+<ChatBubble
+  align="end"
+  avatar={
+    <Avatar
+      width={36}
+      placeholder={
+        <div class="bg-primary text-primary-content flex h-9 w-9 items-center justify-center rounded-full">
+          <span class="text-sm font-bold">JD</span>
+        </div>
+      }
+    />
+  }
+  bubble={<span>Message from JD</span>}
+/>
+```
+
+---
+
+## USAGE PATTERNS
+
+### Pattern 1 — Minimal (bubble only)
+```tsx
+<ChatBubble
+  align="start"
+  color="neutral"
+  bubble={<span>Hi there!</span>}
+/>
+```
+
+### Pattern 2 — With avatar
+```tsx
+<ChatBubble
+  align="start"
+  color="neutral"
+  avatar={<Avatar image="/user.webp" width={40} />}
+  bubble={<span>Hello! How can I help?</span>}
+/>
+```
+
+### Pattern 3 — With header (name + timestamp)
+```tsx
+<ChatBubble
+  align="start"
+  color="info"
+  avatar={<Avatar image="/user.webp" width={40} />}
+  header={
+    <div class="flex items-center gap-2">
+      <span class="font-bold">Alice</span>
+      <time class="text-xs opacity-50">12:45</time>
+    </div>
+  }
+  bubble={<span>Did you see the latest update?</span>}
+/>
+```
+
+### Pattern 4 — Rich bubble content (multiline)
+```tsx
+<ChatBubble
+  align="end"
+  color="primary"
+  bubble={
+    <div>
+      <p>Good morning!</p>
+      <p class="mt-1">Sure, I'll take a look right now.</p>
+    </div>
+  }
+/>
+```
+
+### Pattern 5 — Full conversation layout
+```tsx
+<div class="bg-base-200 max-w-xl space-y-2 rounded-lg p-4">
+  <ChatBubble
+    align="start"
+    color="neutral"
+    avatar={<Avatar image="/customer.webp" width={36} />}
+    header={<span class="text-sm font-bold">Customer</span>}
+    bubble={<span>Hi, I have a question about my order.</span>}
+  />
+  <ChatBubble
+    align="end"
+    color="info"
+    avatar={
+      <Avatar
+        width={36}
+        placeholder={
+          <div class="bg-info text-info-content flex h-9 w-9 items-center justify-center rounded-full">
+            <span class="text-sm">CS</span>
+          </div>
+        }
+      />
+    }
+    header={<span class="text-sm font-bold">Support</span>}
+    bubble={<span>Hello! What's your order number?</span>}
+  />
+</div>
+```
+
+### Pattern 6 — Rendering a list of messages from data
+```tsx
+type Message = {
+  id: string;
+  text: string;
+  sender: 'me' | 'other';
+  senderName: string;
+  time: string;
+};
+
+<For each={messages()}>
+  {msg => (
+    <ChatBubble
+      align={msg.sender === 'me' ? 'end' : 'start'}
+      color={msg.sender === 'me' ? 'primary' : 'neutral'}
+      header={
+        <div class="flex items-center gap-2">
+          <span class="font-bold">{msg.senderName}</span>
+          <time class="text-xs opacity-50">{msg.time}</time>
+        </div>
+      }
+      bubble={<span>{msg.text}</span>}
+    />
+  )}
+</For>
+```
+
+---
+
+## BEHAVIOR NOTES FOR AGENTS
+
+1. **`bubble` is the only required prop** — but always pass `align` explicitly to control message side. Without `align`, the bubble renders without a positioning class.
+
+2. **All optional sections are independently conditional** — `avatar`, `header`, `footer` each use `<Show when={prop}>`. Falsy values (`undefined`, `null`, `false`, empty string) cause their section to be unmounted entirely.
+
+3. **`bubble` accepts any JSX** — string, `<span>`, `<div>` with multiline content, images, etc. The `.chat-bubble` div wraps whatever is passed.
+
+4. **`footer` prop is broken** — see bug section. The footer visibility toggle works (via `<Show>`), but the content rendered is `bubble`, not `footer`. Do not use `footer` in production UI until fixed.
+
+5. **Component renders inside a `<>` fragment** — the root `<div class="chat">` is not the component root; it's wrapped in a fragment. This has no practical impact but means the component emits no additional wrapper element.
+
+6. **Convention for conversation UIs** — wrap multiple `ChatBubble` components in a `<div class="space-y-2">` container. Use `max-w-xl` or similar to constrain chat width.
+
+---
+
+## COMMON MISTAKES TO AVOID
+
+| Mistake | Correct approach |
+|---|---|
+| Omitting `align` prop | Always pass `align="start"` or `align="end"` explicitly |
+| Using `footer` prop expecting custom footer content | `footer` has a bug — it renders `bubble` content instead; avoid until fixed |
+| Passing `align` as a reactive signal without accessor | Pass signal accessor: `align={message.isOwn ? 'end' : 'start'}` |
+| Putting children inside `<ChatBubble>` | Component is NOT a `ParentComponent` — use `bubble` prop instead |
+| Omitting `color` and expecting styled bubble | Without `color`, bubble uses DaisyUI default (no color class) |
+| Forgetting `space-y-2` wrapper for conversation | Multiple bubbles need spacing — wrap in `<div class="space-y-2">` |
+
+---
+
+## FULL EXAMPLE — Complete chat UI
+
+```tsx
+import { ChatBubble } from 'solid-tom-ui';
+import { Avatar } from 'solid-tom-ui';
+import { For } from 'solid-js';
+
+const messages = [
+  { id: '1', sender: 'other', name: 'Alice', time: '12:44', text: 'Hey! Are you free today?' },
+  { id: '2', sender: 'me',    name: 'You',   time: '12:45', text: 'Yes, what's up?' },
+  { id: '3', sender: 'other', name: 'Alice', time: '12:45', text: 'Want to grab lunch?' },
+  { id: '4', sender: 'me',    name: 'You',   time: '12:46', text: 'Sure! Where do you want to go?' },
+];
+
+<div class="bg-base-200 max-w-xl space-y-2 rounded-xl p-4">
+  <For each={messages}>
+    {msg => (
+      <ChatBubble
+        align={msg.sender === 'me' ? 'end' : 'start'}
+        color={msg.sender === 'me' ? 'primary' : 'neutral'}
+        avatar={<Avatar image="/avatar.webp" width={36} />}
+        header={
+          <div class="flex items-center gap-2">
+            <span class="font-bold text-sm">{msg.name}</span>
+            <time class="text-xs opacity-50">{msg.time}</time>
+          </div>
+        }
+        bubble={<span>{msg.text}</span>}
+      />
+    )}
+  </For>
+</div>
+```
+---
+
+## Component Conventions
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `cb01`, `cb02`) per project convention.
+
+> **Unique IDs**: if this component needs to generate HTML `id` attributes, always use `createUniqueId()` from `solid-js` — never `Math.random()` or `Date.now()`.

package/dist/skill/checkbox.skill.md.txt

@@ -0,0 +1,326 @@
+## COMPONENT IDENTITY
+- **Import**: `import { Checkbox } from 'solid-tom-ui';`
+- **Export**: `Checkbox` (named export)
+- **Framework**: SolidJS
+- **Purpose**: Single `<input type="checkbox">` — **uncontrolled**: initial state via `defaultChecked`, internal DOM state drives truth thereafter
+
+---
+
+## TYPE SIGNATURE
+
+```ts
+type CheckboxProps = {
+  defaultChecked: boolean;               // REQUIRED — sets initial checked state via ref
+  id?: string;                           // auto-generated via createUniqueId() if omitted
+  name?: string;                         // for form submission grouping
+  value?: string;                        // form submission value (overridden when indeterminate)
+  indeterminate?: boolean;               // renders dash/minus visual state; blocks toggling
+  disabled?: boolean;                    // prevents interaction
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  color?: 'default' | 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'error';
+  class?: string;                        // extra classes on <input>
+  onChange?: (checked: boolean | null) => void;
+};
+```
+
+---
+
+## DEFAULT VALUES (via `mergeProps`)
+
+| Prop           | Default                  |
+|----------------|--------------------------|
+| `size`         | `'xs'`                   |
+| `color`        | `'primary'`              |
+| `id`           | `createUniqueId()` — auto-generated unique string |
+| `defaultChecked` | `false`               |
+
+---
+
+## PROP REFERENCE
+
+| Prop             | Type                                                                  | Required | Description                                                                               |
+|------------------|-----------------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------|
+| `defaultChecked` | `boolean`                                                             | ✅ YES   | Sets initial `checked` state via DOM ref on mount — does NOT reactively update after mount |
+| `id`             | `string`                                                              | ❌ NO    | `id` on `<input>` — auto-generated if omitted; used with external `<label for="...">`    |
+| `name`           | `string`                                                              | ❌ NO    | `name` attribute for native form grouping/submission                                      |
+| `value`          | `string`                                                              | ❌ NO    | `value` submitted with form data. Overridden to `'inteterminate'` when `indeterminate` is true |
+| `indeterminate`  | `boolean`                                                             | ❌ NO    | Shows dash/minus visual; blocks user toggling; sets `data-indeterminate="true"` on input  |
+| `disabled`       | `boolean`                                                             | ❌ NO    | Disables the input; prevents `onChange` from firing                                       |
+| `size`           | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                              | ❌ NO    | Visual size of the checkbox                                                               |
+| `color`          | `'default' \| 'neutral' \| 'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | ❌ NO | Checkbox fill color when checked |
+| `class`          | `string`                                                              | ❌ NO    | Extra Tailwind classes appended directly to `<input>`                                     |
+| `onChange`       | `(checked: boolean \| null) => void`                                  | ❌ NO    | Fires on change with `e.target.checked` value. NOT fired when `indeterminate` or `disabled` |
+
+---
+
+## SIZE REFERENCE
+
+| Value | CSS `--size` | Pixel size |
+|-------|-------------|------------|
+| `'xs'`| `14px`      | 14 × 14px  |
+| `'sm'`| `16px`      | 16 × 16px  |
+| `'md'`| `18px`      | 18 × 18px  |
+| `'lg'`| `20px`      | 20 × 20px  |
+| `'xl'`| `22px`      | 22 × 22px  |
+
+---
+
+## COLOR REFERENCE
+
+| Value         | DaisyUI class        | Fill color when checked      |
+|---------------|----------------------|------------------------------|
+| `'default'`   | *(no class)*         | Default DaisyUI checkbox color |
+| `'neutral'`   | `checkbox-neutral`   | Neutral                      |
+| `'primary'`   | `checkbox-primary`   | Primary (default)            |
+| `'secondary'` | `checkbox-secondary` | Secondary                    |
+| `'accent'`    | `checkbox-accent`    | Accent                       |
+| `'info'`      | `checkbox-info`      | Info                         |
+| `'success'`   | `checkbox-success`   | Success                      |
+| `'warning'`   | `checkbox-warning`   | Warning                      |
+| `'error'`     | `checkbox-error`     | Error                        |
+
+---
+
+## UNCONTROLLED BEHAVIOR — Critical for agents
+
+This component is **uncontrolled** by design:
+
+- `defaultChecked` sets `ref.checked = value` once at mount via a `ref` callback
+- After mount, the DOM input's `checked` state is **the source of truth**
+- There is **no reactive signal** tracking checked state internally
+- Changing `defaultChecked` after mount does **nothing** — the DOM state is not updated
+- To read current checked state, use `onChange` callback or query the DOM via `ref`
+
+```tsx
+// ✅ Correct: read state through onChange
+const [checked, setChecked] = createSignal(false);
+
+<Checkbox
+  defaultChecked={false}
+  onChange={val => setChecked(val)}
+/>
+
+// ❌ Wrong: changing defaultChecked after mount has no effect
+const [init, setInit] = createSignal(false);
+<Checkbox defaultChecked={init()} />  // reactive update ignored after first render
+```
+
+---
+
+## INDETERMINATE STATE
+
+When `indeterminate={true}`:
+- Renders a **dash/minus** visual (clip-path polygon in CSS)
+- `data-indeterminate="true"` is set on the `<input>`
+- `value` prop is overridden to `'inteterminate'` (note: typo in source — single 'r')
+- `onClick` calls `e.preventDefault()` — **user cannot toggle** the checkbox
+- `onChange` is **never fired** (click is blocked)
+- Useful for "select all" parent checkboxes when only some children are selected
+
+```tsx
+// Indeterminate "select all" pattern
+const allChecked = () => items().every(i => i.checked);
+const someChecked = () => items().some(i => i.checked);
+
+<Checkbox
+  defaultChecked={allChecked()}
+  indeterminate={someChecked() && !allChecked()}
+  onChange={val => items().forEach(i => i.setChecked(val))}
+/>
+```
+
+> ⚠️ Because `indeterminate` blocks user toggling, the state change must be driven externally (e.g. by updating items and re-rendering).
+
+---
+
+## ADDING A LABEL
+
+`Checkbox` renders only an `<input>` — no label wrapper is included. Use a native `<label>` element:
+
+### Label to the right (most common)
+```tsx
+<label class="flex cursor-pointer items-center gap-2">
+  <Checkbox defaultChecked={false} color="primary" size="md" />
+  <span>Accept terms</span>
+</label>
+```
+
+### Label to the left
+```tsx
+<label class="flex cursor-pointer items-center gap-2">
+  <span>Accept terms</span>
+  <Checkbox defaultChecked={false} color="primary" size="md" />
+</label>
+```
+
+### Label below
+```tsx
+<label class="flex w-fit cursor-pointer flex-col items-center gap-1">
+  <Checkbox defaultChecked={false} color="primary" size="md" />
+  <span class="text-sm">Agree</span>
+</label>
+```
+
+### External label via `id`
+```tsx
+<label for="terms-cb" class="cursor-pointer text-sm">Accept terms</label>
+<Checkbox id="terms-cb" defaultChecked={false} color="primary" />
+```
+
+> ℹ️ Always add `cursor-pointer` to `<label>` for correct UX.
+
+---
+
+## FORM USAGE
+
+Use `name` and `value` props for native HTML form submission:
+
+```tsx
+<form onSubmit={e => {
+  e.preventDefault();
+  const data = new FormData(e.currentTarget);
+  console.log(Object.fromEntries(data.entries()));
+}}>
+  <label class="flex cursor-pointer items-center gap-2">
+    <Checkbox name="interests" value="technology" defaultChecked={false} />
+    <span>Technology</span>
+  </label>
+  <label class="flex cursor-pointer items-center gap-2">
+    <Checkbox name="interests" value="design" defaultChecked={false} />
+    <span>Design</span>
+  </label>
+  <button type="submit">Submit</button>
+</form>
+```
+
+> ⚠️ When `indeterminate={true}`, `value` is automatically overridden to `'inteterminate'` regardless of what was passed.
+
+---
+
+## INTERNAL DOM STRUCTURE
+
+```
+<input
+  type="checkbox"
+  id="{id | auto}"
+  class="checkbox checkbox-{size} checkbox-{color} [class]"
+  disabled={disabled}
+  name="{name}"                          ← only if name prop provided
+  data-indeterminate="true"              ← only if indeterminate={true}
+  value="{value | 'inteterminate'}"
+  onClick={...}                          ← preventDefault when indeterminate or disabled
+  onChange={...}                         ← fires p.onChange with e.target.checked
+/>
+```
+
+---
+
+## BEHAVIOR NOTES FOR AGENTS
+
+1. **Uncontrolled — `defaultChecked` is mount-only** — do not pass a reactive signal to `defaultChecked` expecting it to control the checkbox. Use `onChange` to lift state up.
+
+2. **`id` is auto-generated** — every `Checkbox` without an explicit `id` gets a unique ID from SolidJS `createUniqueId()`. No collision risk, but the value is not predictable. Pass explicit `id` when you need `<label for="...">` linkage.
+
+3. **`indeterminate` blocks both click and `onChange`** — `onClick` calls `e.preventDefault()`, so `onChange` never fires. The indeterminate state must be managed entirely by the parent.
+
+4. **`disabled` and `indeterminate` together** — both conditions independently call `e.preventDefault()` in the same `onClick` handler. Either alone is sufficient to block toggling.
+
+5. **`name` is conditionally spread** — if `name` is `undefined`, the attribute is NOT rendered on the DOM (using `{...(p.name && { name: p.name })}`). This avoids empty `name=""` on the input.
+
+6. **`class` appends to generated classes** — CVA generates `checkbox checkbox-{size} checkbox-{color}`, then `p.class` is appended via `cn()`. Use for shape overrides (`rounded-full`), border tweaks, shadows, etc.
+
+7. **`onChange` receives `boolean | null`** — the signature accepts `null` for future indeterminate support, but current implementation always passes `e.target.checked` (boolean). Handle both types defensively.
+
+---
+
+## COMMON MISTAKES TO AVOID
+
+| Mistake | Correct approach |
+|---|---|
+| Treating `defaultChecked` as reactive | It's mount-only — use `onChange` to track state in a signal |
+| Expecting `onChange` to fire when `indeterminate={true}` | `onClick` is blocked — `onChange` never fires in indeterminate state |
+| Omitting `cursor-pointer` on wrapping `<label>` | Always add `cursor-pointer` to `<label>` for correct UX |
+| Passing `value="inteterminate"` manually | When `indeterminate={true}`, value is auto-set — no need to pass it |
+| Using `color="default"` expecting a specific color | `'default'` applies no color class — checkbox uses browser/DaisyUI base style |
+| Relying on `id` being stable without explicit prop | Auto-generated IDs are unique but unpredictable — pass explicit `id` when needed for `<label for>` |
+
+---
+
+## FULL EXAMPLE — All features
+
+```tsx
+import { Checkbox } from 'solid-tom-ui';
+import { createSignal } from 'solid-js';
+
+// 1. Basic with label
+<label class="flex cursor-pointer items-center gap-2">
+  <Checkbox defaultChecked={false} color="primary" size="md" />
+  <span>Accept terms and conditions</span>
+</label>
+
+// 2. Controlled state via onChange
+const [agreed, setAgreed] = createSignal(false);
+
+<label class="flex cursor-pointer items-center gap-2">
+  <Checkbox
+    defaultChecked={false}
+    color="success"
+    size="sm"
+    onChange={val => setAgreed(val)}
+  />
+  <span>I agree ({agreed() ? 'Yes' : 'No'})</span>
+</label>
+
+// 3. Indeterminate — select all pattern
+const [items, setItems] = createSignal([
+  { label: 'Item A', checked: true },
+  { label: 'Item B', checked: false },
+]);
+const allChecked = () => items().every(i => i.checked);
+const someChecked = () => items().some(i => i.checked);
+
+<label class="flex cursor-pointer items-center gap-2">
+  <Checkbox
+    defaultChecked={allChecked()}
+    indeterminate={someChecked() && !allChecked()}
+    color="primary"
+    size="md"
+  />
+  <span class="font-semibold">Select all</span>
+</label>
+
+// 4. Disabled
+<label class="flex cursor-pointer items-center gap-2 opacity-50">
+  <Checkbox defaultChecked={true} color="neutral" size="md" disabled />
+  <span>Cannot change</span>
+</label>
+
+// 5. Form with name + value
+<form onSubmit={e => { e.preventDefault(); console.log([...new FormData(e.currentTarget)]); }}>
+  <label class="flex cursor-pointer items-center gap-2">
+    <Checkbox name="lang" value="typescript" defaultChecked={true} size="sm" />
+    <span>TypeScript</span>
+  </label>
+  <label class="flex cursor-pointer items-center gap-2">
+    <Checkbox name="lang" value="rust" defaultChecked={false} size="sm" />
+    <span>Rust</span>
+  </label>
+  <button type="submit" class="btn btn-sm btn-primary mt-2">Submit</button>
+</form>
+
+// 6. Custom styling
+<label class="flex cursor-pointer items-center gap-2">
+  <Checkbox
+    defaultChecked={true}
+    color="accent"
+    size="lg"
+    class="rounded-full shadow-lg"
+  />
+  <span>Rounded pill checkbox</span>
+</label>
+```
+---
+
+## Component Conventions
+
+> **CSS encoding**: internal CSS classes use short encoded names (e.g. `cx01`, `cx02`) per project convention.