vunor 0.1.2 → 0.1.4

package/skills/vunor/rules.md

@@ -1,263 +0,0 @@
-# UnoCSS custom rules — vunor
-
-> All 15 custom UnoCSS rules provided by `presetVunor`: palette/scope/current-color rules, spacing/typography/card/fingertip rules, and i8 input styling rules.
-
-## Concepts
-
-Vunor's `presetVunor()` registers custom UnoCSS rules that power the color scope system, typography-aware spacing, card sizing, touch targets, and input styling. These rules generate CSS custom properties that compose together — e.g., `scope-primary` sets palette variables, `current-bg-scope-color-500` reads them, and `bg-current` applies the result.
-
-Rules are organized in three groups:
-1. **Palette rules** (8) — color scoping, current-color system, icon utilities
-2. **Spacing rules** (4) — text margins, card spacing, fingertip sizing
-3. **Input rules** (3) — i8 border/bg/outline configuration
-
-## Palette rules
-
-### `scope-{color}`
-
-Sets `--scope-color-*` CSS custom properties for the entire subtree.
-
-**Pattern:** `/^scope-(.*)$/`
-
-Generates variables for all 10 main shades (50–900), 5 light layers (0–4), 5 dark layers (0–4), and sets `--current-hl` to the 500 shade. Valid colors: `primary`, `secondary`, `good`, `warn`, `error`, `grey`, `neutral`.
-
-```html
-<div class="scope-primary">
-  <!-- --scope-color-50 through --scope-color-900 are now set -->
-  <!-- --scope-light-0 through --scope-light-4 -->
-  <!-- --scope-dark-0 through --scope-dark-4 -->
-  <!-- --current-hl = primary-500 -->
-</div>
-```
-
-### `current-{target}-{source}`
-
-Sets a `--current-{target}` CSS variable to a specific color.
-
-**Pattern:** `/^current-(text|bg|icon|border|outline|caret|hl)-(.+)$/`
-
-| Source type | Example | Result |
-|-------------|---------|--------|
-| Scope reference | `current-bg-scope-color-500` | `--current-bg: var(--scope-color-500)` |
-| Highlight alias | `current-text-hl` | `--current-text: var(--current-hl)` |
-| Theme color | `current-bg-primary-500` | `--current-bg: <rgb values>` |
-
-```html
-<div class="current-bg-primary-500 current-text-primary-50">
-  <div class="bg-current text-current">Styled via CSS vars</div>
-</div>
-```
-
-### `{target}-current` / `{target}-current-{source}` / `{target}-current/{opacity}`
-
-Applies a `--current-*` color to a CSS property.
-
-**Pattern:** `/^(text|bg|icon|border|outline|caret|fill|shadow|ring)-current(-text|-bg|-icon|-border|-outline|-caret|-hl)?(\/\d{1,3})?$/`
-
-```html
-<div class="text-current">          <!-- color: rgb(var(--current-text) / 1) -->
-<div class="bg-current/50">         <!-- background-color: rgb(var(--current-bg) / 0.5) -->
-<div class="border-current-hl">     <!-- border-color uses --current-hl -->
-<div class="icon-current">          <!-- sets --un-icon-opacity: 1 -->
-<div class="shadow-current-border"> <!-- --un-shadow-color from --current-border -->
-```
-
-Special behavior for `icon` target: sets `--un-icon-opacity` but applies color through the `icon-color` rule, not directly.
-
-### `{target}-scope-{source}` / `{target}-scope-{source}/{opacity}`
-
-Applies a scoped palette color directly to a CSS property without going through `--current-*`.
-
-**Pattern:** `/^(bg|text|fill|stroke|border|outline|icon|caret)-scope-((?:color|dark|light|text|bg|white|black|icon)(?:-\d+)?)(\/\d{1,3})?$/`
-
-```html
-<div class="bg-scope-color-100">     <!-- background: --scope-color-100 -->
-<div class="text-scope-dark-2">      <!-- color: --scope-dark-2 -->
-<div class="border-scope-light-1/50"> <!-- border: --scope-light-1 at 50% -->
-```
-
-### `icon-opacity-{0-100}`
-
-Sets `--un-icon-opacity`.
-
-**Pattern:** `/^icon-opacity-(\d{1,3})$/`
-
-```html
-<div class="icon-opacity-50"> <!-- --un-icon-opacity: 0.5 -->
-```
-
-### `icon-color`
-
-Applies the current icon color with icon opacity.
-
-**Pattern:** exact match `icon-color`
-
-```css
-.icon-color { color: rgb(var(--current-icon) / var(--un-icon-opacity, 1)); }
-```
-
-### `icon-size-{value}` / `icon-size`
-
-Sets or applies icon dimensions.
-
-**Pattern:** `/^icon-size-(.*)$/` and exact match `icon-size`
-
-| Class | Result |
-|-------|--------|
-| `icon-size-[2em]` | `--icon-size: 2em` |
-| `icon-size-4` | `--icon-size: 1rem` (from theme.spacing) |
-| `icon-size` | `width/height: var(--icon-size, 1em)` |
-
-## Spacing rules
-
-### `text-m{t|b|y}-{size}`
-
-Text margins with line-height compensation. Adjusts top/bottom margins using `--font-tc` (top correction) and `--font-bc` (bottom correction) so spacing between typographic elements is optically correct.
-
-**Pattern:** `/^text-m([bty])?-(.*)$/`
-
-| Suffix | Applies to |
-|--------|-----------|
-| `t` | top only |
-| `b` | bottom only |
-| `y` | top and bottom |
-| _(none)_ | all four sides |
-
-```html
-<h1 class="text-h1 text-mb-$m">Title</h1>
-<!-- margin-bottom: calc(1em + var(--font-bc)) -->
-
-<p class="text-body text-mt-$s">Paragraph</p>
-<!-- margin-top: calc(0.62em + var(--font-tc)) -->
-```
-
-Size values: spacing tokens (`$s`, `$m`, `$l`...), theme spacing keys, or numbers (multiplied by 0.25rem if unitless).
-
-### `card-dense`
-
-Switches card spacing to the dense variant.
-
-**Pattern:** exact match `card-dense`
-
-```css
-.card-dense { --card-spacing: var(--card-spacing-dense); }
-```
-
-### `card-{typography}`
-
-Sets `--card-spacing` proportional to a typography level's corrected font size.
-
-**Pattern:** `/^card-(.*)$/` (matches any valid `theme.fontSize` key)
-
-```html
-<div class="card-h3">
-  <!-- --card-spacing: <h3 corrected size * cardSpacingFactor.regular> -->
-  <!-- --card-spacing-dense: <h3 corrected size * cardSpacingFactor.dense> -->
-  <!-- --card-heading-size, --card-heading-bold, etc. also set -->
-  <!-- padding: var(--card-spacing) -->
-</div>
-```
-
-Valid keys: `h1`–`h6`, `subheading`, `body`, `body-l`, `body-s`, `callout`, `label`, `caption`, `overline`.
-
-### `fingertip-{size}`
-
-Sets touch target height via `--v-fingertip` and `--v-fingertip-half`.
-
-**Pattern:** `/^fingertip-(.*)/`
-
-| Class | Source |
-|-------|--------|
-| `fingertip-xs` / `s` / `m` / `l` / `xl` | Named sizes from preset config |
-| `fingertip-4` | `theme.spacing['4']` |
-| `fingertip-[2.5rem]` | Bracket value used directly |
-
-```css
-.fingertip-m { --v-fingertip: 3em; --v-fingertip-half: 1.5em; }
-```
-
-## Input (i8) rules
-
-### `i8-{target}-{value}`
-
-Configures input border, outline, or background via CSS custom properties.
-
-**Pattern:** `/^i8-(border|outline|bg)-(.+)$/`
-
-| Value type | Example | CSS generated |
-|-----------|---------|---------------|
-| `none` | `i8-border-none` | `--i8-border-width: 0` |
-| `transparent` | `i8-bg-transparent` | `--i8-bg-color: 0` |
-| Scope ref | `i8-border-scope-color-500` | `--i8-border-color: var(--scope-color-500)` |
-| Theme color | `i8-border-primary` | `--i8-border-color: <rgb>` |
-| Width (px/em/rem) | `i8-border-2px` | `--i8-border-width: 2px` |
-| Bracket color | `i8-outline-[#ff0000]` | `--i8-outline-color: #ff0000` |
-| Bracket width | `i8-border-[0.5em]` | `--i8-border-width: 0.5em` |
-
-### `i8-{target}-opacity-{0-100}`
-
-Sets opacity for input border, outline, or background.
-
-**Pattern:** `/^i8-(border|outline|bg)-opacity-(\d{1,3})$/`
-
-```html
-<div class="i8-border-opacity-50"> <!-- --i8-border-opacity: 0.5 -->
-```
-
-### `i8-apply-{target}`
-
-Applies the configured i8 values to actual CSS properties. This is the final rendering step — used internally by `i8-flat`, `i8-filled`, `i8-round` shortcuts.
-
-**Pattern:** `/^i8-apply-(border|outline|bg)$/`
-
-| Class | CSS | Defaults |
-|-------|-----|----------|
-| `i8-apply-bg` | `background-color: rgb(var(--i8-bg-color, var(--current-bg)) / var(--i8-bg-opacity, 1))` | opacity: 1 |
-| `i8-apply-border` | `border-color: rgb(...)` + `border-width: var(--i8-border-width, 1px)` | opacity: 0.2, width: 1px |
-| `i8-apply-outline` | `outline-color: rgb(...)` + `outline-width: var(--i8-outline-width, 2px)` | opacity: 0.5, width: 2px |
-
-## CSS custom properties reference
-
-Properties set by these rules:
-
-| Variable | Set by | Used by |
-|----------|--------|---------|
-| `--scope-color-{step}` | `scope-*` | `current-*-scope-*`, `*-scope-*` |
-| `--scope-light-{0-4}` | `scope-*` | `layer-*`, `*-scope-light-*` |
-| `--scope-dark-{0-4}` | `scope-*` | `layer-*`, `*-scope-dark-*` |
-| `--current-text` | `current-text-*` | `text-current` |
-| `--current-bg` | `current-bg-*` | `bg-current` |
-| `--current-icon` | `current-icon-*` | `icon-current`, `icon-color` |
-| `--current-border` | `current-border-*` | `border-current` |
-| `--current-hl` | `scope-*`, `current-hl-*` | `*-current-hl` |
-| `--font-tc` / `--font-bc` | `text-*` typography utilities | `text-mt-*`, `text-mb-*` |
-| `--card-spacing` | `card-*` | Card component padding |
-| `--card-spacing-dense` | `card-*` | `card-dense` |
-| `--v-fingertip` | `fingertip-*` | `h-fingertip`, button/input heights |
-| `--v-fingertip-half` | `fingertip-*` | `px-fingertip-half`, rounded buttons |
-| `--i8-border-color` | `i8-border-*` | `i8-apply-border` |
-| `--i8-border-width` | `i8-border-*` | `i8-apply-border` |
-| `--i8-border-opacity` | `i8-border-opacity-*` | `i8-apply-border` |
-| `--i8-bg-color` | `i8-bg-*` | `i8-apply-bg` |
-| `--i8-bg-opacity` | `i8-bg-opacity-*` | `i8-apply-bg` |
-| `--i8-outline-color` | `i8-outline-*` | `i8-apply-outline` |
-| `--i8-outline-width` | `i8-outline-*` | `i8-apply-outline` |
-| `--i8-outline-opacity` | `i8-outline-opacity-*` | `i8-apply-outline` |
-| `--un-icon-opacity` | `icon-opacity-*`, `icon-current` | `icon-color` |
-| `--icon-size` | `icon-size-*` | `icon-size` |
-
-## Best practices
-
-- Use `scope-{color}` at the highest ancestor that shares a palette — avoids redundant variable declarations.
-- Prefer `text-mt-*` / `text-mb-*` over plain `mt-*` / `mb-*` between typographic elements — the font corrections produce optically correct spacing.
-- The `i8-*` rules are low-level — most of the time, use `i8-flat` / `i8-filled` / `i8-round` shortcuts which compose these rules internally.
-- `card-{typography}` sets `padding` directly — don't add extra padding classes on the same element.
-
-## Gotchas
-
-- `scope-{color}` only sets CSS variables — it doesn't apply any visible styles. You need `layer-*`, `surface-*`, `bg-current`, or `*-scope-*` classes to consume the scope.
-- `icon-current` does **not** set `color` directly — it sets `--un-icon-opacity`. Use `icon-color` alongside it, or use the `icon-color icon-size` classes that components already include.
-- `i8-apply-border` defaults to `border-opacity: 0.2` and `width: 1px`. If you set `i8-border-primary` but see no visible border, check that `border-style` (e.g. `border-solid`) is also applied.
-- `text-m-$m` applies margins to **all four sides** (not just top/bottom). Use `text-my-$m` for vertical-only.
-- `fingertip-m` sets the CSS variable but doesn't apply height — use `h-fingertip` to consume it.
-- `card-dense` requires a `card-{typography}` rule on the same element (or ancestor) to have set `--card-spacing-dense`.

package/skills/vunor/shortcuts.md

@@ -1,239 +0,0 @@
-# Shortcut objects — vunor
-
-> The structured shortcut system for defining and customizing component styles: defineShortcuts, mergeVunorShortcuts, c8/i8 style systems, and overriding built-in styles.
-
-## Concepts
-
-Instead of flat UnoCSS shortcut strings, Vunor uses **structured nested objects** where keys are variant prefixes and values are the classes to apply. This makes styles readable, deeply mergeable, and surgically overridable.
-
-The key insight: when two shortcut objects define the same key, `mergeVunorShortcuts()` deep-merges them with later entries winning. You can override a single variant of a built-in style without rewriting the whole shortcut.
-
-### How it works
-
-```
-defineShortcuts({ ... })   →   Shortcut object (nested)
-         ↓
-toUnoShortcut(obj)         →   Flat UnoCSS string
-         ↓
-mergeVunorShortcuts([...]) →   Merged array (later wins)
-         ↓
-vunorShortcuts(overrides)  →   Final UnoCSS shortcuts config
-```
-
-## API Reference
-
-### `defineShortcuts(obj)`
-
-Creates a typed shortcut object. Keys are shortcut names (CSS classes), values are variant-prefix objects.
-
-```ts
-import { defineShortcuts } from 'vunor/theme'
-
-const shortcuts = defineShortcuts({
-  'btn': {
-    '': 'h-fingertip flex items-center',     // base classes (no prefix)
-    'hover:': 'bg-current/05',               // → "hover:bg-current/05"
-    'dark:': 'text-white',                   // → "dark:text-white"
-    '[&.btn-round]:': 'rounded-full',        // → "[&.btn-round]:rounded-full"
-  },
-})
-```
-
-Each key is a **variant prefix** that gets prepended to every class in the value.
-
-### Compound variants
-
-Nesting goes deeper for compound states:
-
-```ts
-defineShortcuts({
-  'c8-filled': {
-    '': 'current-bg-scope-color-500 text-white rounded-base',
-    'hover:': 'current-bg-scope-color-400',
-    'dark:': {
-      '': 'text-white/90',
-      'hover:': 'current-bg-scope-color-600 border-solid',
-      // produces: "dark:text-white/90 dark:hover:current-bg-scope-color-600 dark:hover:border-solid"
-    },
-  },
-})
-```
-
-### `toUnoShortcut(obj)`
-
-Flattens a shortcut object into a single UnoCSS string. Called internally but can be used directly for debugging.
-
-```ts
-import { toUnoShortcut } from 'vunor/theme'
-
-const flat = toUnoShortcut({
-  '': 'flex items-center',
-  'hover:': 'bg-blue-100',
-})
-// → "flex items-center hover:bg-blue-100"
-```
-
-### `mergeVunorShortcuts(arrays)`
-
-Deep-merges multiple shortcut arrays. Later arrays win on conflict.
-
-```ts
-import { mergeVunorShortcuts } from 'vunor/theme'
-
-const merged = mergeVunorShortcuts([defaultShortcuts, myOverrides])
-```
-
-### `vunorShortcuts(overrides?, baseShortcuts?)`
-
-Returns the final merged shortcuts for UnoCSS config. This is what you put in `shortcuts: [...]`.
-
-```ts
-import { vunorShortcuts } from 'vunor/theme'
-
-// Default styles
-shortcuts: [vunorShortcuts()]
-
-// With overrides (overrides take priority)
-shortcuts: [vunorShortcuts(myCustomShortcuts)]
-```
-
-## Built-in style systems
-
-### c8 — Clickable styles
-
-Four visual variants for buttons and interactive elements. Use with `scope-{color}` to set the palette.
-
-| Class | Description |
-|-------|-------------|
-| `c8-filled` | Solid background, white text |
-| `c8-flat` | Transparent background, colored text, subtle hover |
-| `c8-outlined` | Border + colored text, transparent fill |
-| `c8-light` | Light tinted background, colored text |
-
-Each includes hover, active, focus, and disabled states.
-
-```html
-<button class="scope-primary c8-filled">Save</button>
-<button class="scope-error c8-flat">Cancel</button>
-<button class="scope-good c8-outlined">Confirm</button>
-<button class="scope-warn c8-light">Warning</button>
-```
-
-### i8 — Input styles
-
-Three visual variants for form inputs.
-
-| Class | Description |
-|-------|-------------|
-| `i8-flat` | Bottom border only (minimal) |
-| `i8-filled` | Full border with background |
-| `i8-round` | Pill-shaped (fully rounded) |
-
-Sub-shortcuts used within input components:
-
-| Class | Purpose |
-|-------|---------|
-| `i8-input` | The `<input>` element itself |
-| `i8-textarea` | The `<textarea>` element |
-| `i8-label` | Floating label |
-| `i8-label-wrapper` | Label container for positioning |
-| `i8-hint` | Hint text below input |
-| `i8-counter` | Character counter |
-| `i8-prepend` / `i8-append` | Side icons/content (inside border) |
-| `i8-before` / `i8-after` | Side content (outside border) |
-| `i8-underline` | Bottom border element |
-
-### Other built-in shortcuts
-
-| Prefix | Components |
-|--------|-----------|
-| `btn` | Button — `btn`, `btn-round`, `btn-square`, `btn-icon`, `btn-label` |
-| `card` | Card — `card`, `card-header`, `card-dense` |
-| `checkbox` | Checkbox — `checkbox-root`, `checkbox`, `checkbox-indicator`, `checkbox-icon`, `checkbox-label` |
-| `rb` | RadioGroup — `rb-container`, `rb-root`, `rb-item`, `rb-item-indicator`, `rb-item-label` |
-| `select` | Select — `select-content`, `select-item`, `select-grp-label`, `select-separator` |
-| `dialog` | Dialog — `dialog-overlay`, `dialog-card`, `dialog-header`, `dialog-title`, `dialog-close`, `dialog-footer` |
-| `tabs` | Tabs — `tabs-indicator`, `tab` |
-| `menu` | Menu — `menu-root`, `menu-item` |
-| `loading` | Loading — `loading-indicator`, `loading-indicator-wrapper`, `inner-loading` |
-| `toast` | Toasts — `toast-root`, `toasts-viewport` |
-| `progress` | ProgressBar — `progress-bar` |
-
-## Common patterns
-
-### Pattern: Override a single variant
-
-Change only the base classes of `c8-filled` while keeping all hover/dark/active variants intact:
-
-```ts
-import { vunorShortcuts, defineShortcuts } from 'vunor/theme'
-
-const myOverrides = defineShortcuts({
-  'c8-filled': {
-    '': 'rounded-full',  // only overrides base — hover, dark, etc. stay
-  },
-})
-
-export default defineConfig({
-  presets: [presetVunor()],
-  shortcuts: [vunorShortcuts(myOverrides)],
-})
-```
-
-### Pattern: Override input underline style
-
-```ts
-const myOverrides = defineShortcuts({
-  'i8-flat': {
-    '': 'border-b-2',  // thicker bottom border
-  },
-})
-```
-
-### Pattern: Add a new shortcut
-
-```ts
-const myShortcuts = defineShortcuts({
-  'badge': {
-    '': 'inline-flex items-center px-$xs py-$xxs text-caption rounded-full',
-    'dark:': 'bg-white/10',
-  },
-})
-
-shortcuts: [vunorShortcuts(myShortcuts)]
-```
-
-### Pattern: Override component-specific shortcuts
-
-```ts
-const myOverrides = defineShortcuts({
-  'btn': {
-    '': 'uppercase tracking-wider',  // make all buttons uppercase
-  },
-  'card': {
-    '': 'shadow-lg',  // add shadow to all cards
-  },
-})
-```
-
-## Integration
-
-- Shortcuts are consumed by UnoCSS — they expand to utility classes at build time.
-- The `c8-*` and `i8-*` systems are used internally by Vunor components (`VuButton` uses `c8-*`, `VuInput` uses `i8-*`).
-- You can use `c8-*` and `i8-*` classes on any HTML element, not just Vunor components.
-- `scope-{color}` must be set on an ancestor (or the element itself) for `c8-*` and `i8-*` to pick up colors.
-
-## Best practices
-
-- Always pass overrides through `vunorShortcuts(overrides)` — don't try to manually merge with the defaults.
-- Override at the most specific variant level possible. Replacing `''` (base) is safe; replacing the entire shortcut object loses all variant handling.
-- Use `defineShortcuts()` for type safety — it validates the structure at the TypeScript level.
-- Keep custom shortcuts in a separate file (e.g., `shortcuts.custom.ts`) for clarity.
-
-## Gotchas
-
-- Shortcut keys are **variant prefixes**, not CSS pseudo-classes. The key `'hover:'` (with colon) prepends `hover:` to each class in the value string.
-- The empty string key `''` is the base (no-prefix) classes. It's required for every shortcut.
-- `mergeVunorShortcuts` does **deep merge**, not replacement. If you need to completely replace a shortcut, set every key explicitly.
-- Shortcut names become CSS class names. Adding a shortcut `'my-card'` means you use `class="my-card"`.
-- The `i8` rules (`i8-border-*`, `i8-bg-*`, `i8-outline-*`) are separate UnoCSS rules, not shortcuts. They set CSS custom properties (`--i8-border-color`, `--i8-bg-color`) consumed by the `i8-*` shortcuts.