@cocoar/vue-ui 3.1.0 → 3.2.0-beta.6

package/skills/cocoar-vue-ui/references/foundations/design-principles.md

@@ -0,0 +1,115 @@
+<!-- Generated from apps/docs/foundations/design-principles.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Design Principles
+
+The foundation of the Cocoar Design System — six principles that guide every design decision across our Vue 3 component library.
+
+---
+
+### Clarity
+
+Every element has a clear purpose. Reduce visual noise and make the important thing obvious.
+
+- Consistent spacing creates visual rhythm that guides scanning
+- Typography hierarchy directs attention to what matters most
+- Limit each view to one primary action to reduce decision fatigue
+- Use whitespace generously — empty space is not wasted space
+
+---
+
+### Consistency
+
+Use the same patterns, tokens, and components everywhere. Predictability reduces cognitive load and builds trust.
+
+- Shared token vocabulary across colors, spacing, radius, and motion
+- Uniform component API patterns — props, events, and slots follow conventions
+- Consistent interaction models — similar controls behave identically
+- One way to do things, not many — fewer choices lead to better outcomes
+
+---
+
+### Accessibility
+
+Design for everyone. Meet WCAG AA standards at minimum. Keyboard navigation is not optional — it is a core feature.
+
+- **4.5 : 1** minimum contrast ratio for all text content
+- Full keyboard navigation built into every interactive component
+- Screen reader support with proper ARIA attributes
+- Focus indicators that are visible and consistent
+- Respect `prefers-reduced-motion` for users who need it
+
+---
+
+### Touch-First
+
+All components work with **touch and focus** — hover is an enhancement, not a requirement. This is **tablet-first** design: touch interaction with desktop-appropriate information density. Not mobile-first — mobile phones have different constraints (small screens, portrait orientation, one-handed use). Tablets have similar screen real estate to laptops but use touch instead of mouse.
+
+- Minimum **44 x 44 px** touch targets on all interactive elements
+- Appropriate tap spacing to prevent accidental activation
+- No hover-only interactions — every feature is reachable via tap or keyboard
+- Use dimmed states instead of hiding; on focus/hover elements become prominent
+- Desktop gets additional polish (hover states) as progressive enhancement
+
+---
+
+### Performance
+
+Ship less, load faster. Icons are inlined SVGs. Components are tree-shakeable. CSS theming uses custom properties for zero runtime cost.
+
+- Inline SVG icons eliminate icon font overhead
+- Individual component imports enable dead-code elimination
+- CSS custom property theming — no JavaScript at render time
+- Lightweight component architecture with minimal dependencies
+
+---
+
+### Developer Experience
+
+Strong TypeScript types. Composable APIs. Predictable naming. The system should be a joy to use, not a chore to learn.
+
+- Full TypeScript support with exported types for every component
+- Consistent `v-model` patterns across all form controls
+- Self-documenting prop names — no guessing what `mode="3"` means
+- Composable utilities (`useDialog`, `useToast`) for programmatic control
+
+---
+
+## Design Token Architecture
+
+Cocoar uses a **two-layer token system**: raw primitives are referenced by semantic tokens. Always use semantic tokens in your components — they adapt automatically to light and dark mode.
+
+| Category | Token Prefix | Description |
+|---|---|---|
+| **Color** | `--coar-color-*` | Raw color primitives (gray, slate, accent, green, red, amber) |
+| **Background** | `--coar-background-*` | Semantic surface tokens for accent, brand, neutral, and status |
+| **Text** | `--coar-text-*` | Text color tokens for all states and emphasis levels |
+| **Border** | `--coar-border-*` | Border color tokens for interactive and structural elements |
+| **Spacing** | `--coar-spacing-*` | Space scale from `xxs` (2 px) to `xxxl` (64 px) on a 4 px grid |
+| **Radius** | `--coar-radius-*` | Border radius from `xxs` (1 px) to `full` (999 px) |
+| **Shadow** | `--coar-shadow-*` | Elevation shadows `xs`–`xl` plus a focus ring |
+| **Typography** | `--coar-titles-*` / `--coar-headings-*` / `--coar-body-*` | Font family, size, and weight tokens for each text role |
+| **Motion** | `--coar-duration-*` / `--coar-ease-*` / `--coar-transition-*` | Duration, easing, and pre-composed transition tokens |
+
+## Do's and Don'ts
+
+> **Tip: Do**
+>
+> - Use semantic tokens — `--coar-text-neutral-primary`, not a raw hex value
+> - Follow the **4 px spacing grid** for all layout dimensions
+> - Use `v-model` for two-way binding on form controls
+> - Import components individually for tree-shaking: `import { CoarButton } from '@cocoar/vue-ui'`
+> - Test keyboard navigation for every interactive flow
+> - Provide `aria-label` for icon-only buttons
+
+> **Danger: Don't**
+>
+> - Hardcode colors or spacing values in component styles
+> - Use primitive tokens directly in components (`--coar-color-gray-500`)
+> - Override component internals with `:deep()` selectors
+> - Create hover-only interactions that exclude touch and keyboard users
+> - Mix spacing values that are not on the 4 px grid
+> - Ignore `prefers-reduced-motion` in custom animations
+
+> **Info: Dark Mode**
+>
+> Toggle dark mode by adding the `.dark-mode` class to `document.documentElement`. All tokens and components update automatically — no JavaScript required at render time.

package/skills/cocoar-vue-ui/references/foundations/icons.md

@@ -0,0 +1,381 @@
+<!-- Generated from apps/docs/foundations/icons.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Icons
+
+A flexible icon system with built-in SVG icons. Icons support multiple sizes, colors, rotation, and animations.
+
+```ts
+import { CoarIcon } from '@cocoar/vue-ui';
+```
+
+## Icon Gallery
+
+**Demo — `icons/demos/IconGallery.vue`**
+
+```vue
+<template>
+  <div>
+    <p style="margin: 0 0 8px; font-size: 14px; color: var(--coar-text-neutral-secondary);">
+      Browse all {{ allIcons.length }} available icons. Click an icon to copy its name.
+    </p>
+    <div class="search-wrapper">
+      <CoarTextInput v-model="search" placeholder="Search icons..." :clearable="true" />
+    </div>
+
+    <div v-if="filteredIcons.length > 0" class="icons-grid">
+      <button
+        v-for="icon in filteredIcons"
+        :key="icon"
+        class="icon-item"
+        :class="{ 'icon-item--copied': copiedIcon === icon }"
+        :title="`Click to copy: ${icon}`"
+        @click="copyIconName(icon)"
+      >
+        <CoarIcon :name="icon" size="l" />
+        <span class="icon-name">{{ icon }}</span>
+        <span v-if="copiedIcon === icon" class="icon-copied">Copied!</span>
+      </button>
+    </div>
+    <p v-else style="color: var(--coar-text-neutral-secondary); font-size: 14px; margin-top: 16px;">
+      No icons match "{{ search }}"
+    </p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { CoarTextInput, CoarIcon, CORE_ICONS } from '@cocoar/vue-ui';
+
+const search = ref('');
+const copiedIcon = ref<string | null>(null);
+
+const allIcons = Object.keys(CORE_ICONS);
+
+const filteredIcons = computed(() => {
+  const q = search.value.toLowerCase().trim();
+  return q ? allIcons.filter(name => name.includes(q)) : allIcons;
+});
+
+function copyIconName(name: string) {
+  navigator.clipboard.writeText(name).catch(() => {});
+  copiedIcon.value = name;
+  setTimeout(() => { copiedIcon.value = null; }, 1500);
+}
+</script>
+
+<style scoped>
+.search-wrapper {
+  margin-bottom: 16px;
+}
+
+.icons-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(90px, 1fr));
+  gap: 4px;
+  max-height: 480px;
+  overflow-y: auto;
+}
+
+.icon-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+  padding: 8px;
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: var(--coar-radius-s);
+  cursor: pointer;
+  transition: background 100ms ease-out;
+  color: var(--coar-text-neutral-primary);
+  position: relative;
+}
+
+.icon-item:hover {
+  background: var(--coar-background-neutral-tertiary);
+  border-color: var(--coar-border-neutral-secondary);
+}
+
+.icon-item--copied {
+  background: var(--coar-background-semantic-success-subtle);
+  border-color: var(--coar-background-semantic-success-bold);
+}
+
+.icon-name {
+  font-size: 10px;
+  color: var(--coar-text-neutral-tertiary);
+  text-align: center;
+  word-break: break-all;
+  font-family: 'Consolas', 'Monaco', monospace;
+}
+
+.icon-copied {
+  position: absolute;
+  bottom: 2px;
+  font-size: 9px;
+  color: var(--coar-text-neutral-secondary);
+  font-weight: 600;
+}
+</style>
+```
+
+## Sizes
+
+Icons come in 5 preset sizes and can use any valid CSS value.
+
+**Demo — `icons/demos/IconSizes.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 24px; align-items: flex-end;">
+    <div v-for="size in sizes" :key="size" class="size-item">
+      <CoarIcon name="settings" :size="size" />
+      <span class="size-label">{{ size }} ({{ sizeLabels[size] }})</span>
+    </div>
+    <div class="size-item">
+      <CoarIcon name="settings" size="48px" />
+      <span class="size-label">custom (48px)</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarIcon } from '@cocoar/vue-ui';
+
+const sizes = ['xs', 's', 'm', 'l', 'xl'] as const;
+const sizeLabels: Record<string, string> = { xs: '12px', s: '16px', m: '20px', l: '24px', xl: '32px' };
+</script>
+
+<style scoped>
+.size-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+
+.size-label {
+  font-size: 11px;
+  color: var(--coar-text-neutral-tertiary);
+  font-family: monospace;
+  white-space: nowrap;
+}
+</style>
+```
+
+## Colors
+
+Icons inherit color by default. Override with any valid CSS color value.
+
+**Demo — `icons/demos/IconColors.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 24px; align-items: center;">
+    <div class="color-item"><CoarIcon name="check" size="l" color="green" /><span class="color-label">green</span></div>
+    <div class="color-item"><CoarIcon name="x" size="l" color="red" /><span class="color-label">red</span></div>
+    <div class="color-item"><CoarIcon name="triangle-alert" size="l" color="orange" /><span class="color-label">orange</span></div>
+    <div class="color-item"><CoarIcon name="circle-help" size="l" color="blue" /><span class="color-label">blue</span></div>
+    <div class="color-item"><CoarIcon name="settings" size="l" color="#888" /><span class="color-label">#888</span></div>
+    <div class="color-item"><CoarIcon name="user" size="l" color="var(--coar-text-accent-primary)" /><span class="color-label">accent</span></div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarIcon } from '@cocoar/vue-ui';
+</script>
+
+<style scoped>
+.color-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+
+.color-label {
+  font-size: 11px;
+  color: var(--coar-text-neutral-tertiary);
+  font-family: monospace;
+  white-space: nowrap;
+}
+</style>
+```
+
+## Rotation
+
+Rotate icons to any angle using the `rotate` prop.
+
+**Demo — `icons/demos/IconRotation.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 24px; align-items: center;">
+    <div class="rotation-item"><CoarIcon name="chevron-right" size="l" :rotate="0" /><span class="rotation-label">0&deg;</span></div>
+    <div class="rotation-item"><CoarIcon name="chevron-right" size="l" :rotate="90" /><span class="rotation-label">90&deg;</span></div>
+    <div class="rotation-item"><CoarIcon name="chevron-right" size="l" :rotate="180" /><span class="rotation-label">180&deg;</span></div>
+    <div class="rotation-item"><CoarIcon name="chevron-right" size="l" :rotate="270" /><span class="rotation-label">270&deg;</span></div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarIcon } from '@cocoar/vue-ui';
+</script>
+
+<style scoped>
+.rotation-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+
+.rotation-label {
+  font-size: 11px;
+  color: var(--coar-text-neutral-tertiary);
+  font-family: monospace;
+  white-space: nowrap;
+}
+</style>
+```
+
+## Spin Animation
+
+Enable continuous spinning for loading indicators.
+
+**Demo — `icons/demos/IconSpin.vue`**
+
+```vue
+<template>
+  <div style="display: flex; flex-wrap: wrap; gap: 32px; align-items: flex-start;">
+    <div class="spin-item">
+      <CoarIcon name="loader-circle" size="xl" :spin="true" />
+      <span style="font-size: 14px;">Loading...</span>
+    </div>
+    <div class="spin-item">
+      <CoarIcon name="settings" size="l" :spin="true" />
+      <span style="font-size: 14px;">Processing</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CoarIcon } from '@cocoar/vue-ui';
+</script>
+
+<style scoped>
+.spin-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+}
+</style>
+```
+
+## Custom Icon Sources
+
+Register your own icons alongside the built-in set. Cocoar supports multiple icon sources with automatic fallback.
+
+### SVG Map (Inline Icons)
+
+Register a set of SVG strings — resolved synchronously, no network requests.
+
+```ts
+// main.ts
+import { CoarIconPlugin, CoarIconMapSource } from '@cocoar/vue-ui';
+
+app.use(CoarIconPlugin, {
+  sources: [
+    {
+      key: 'app',
+      source: new CoarIconMapSource({
+        'logo': '<svg viewBox="0 0 24 24">...</svg>',
+        'dashboard': '<svg viewBox="0 0 24 24">...</svg>',
+      }),
+    },
+  ],
+  defaultSource: 'app', // check custom icons first
+});
+```
+
+```vue
+<template>
+  <!-- Resolves from 'app' source first, then built-in -->
+  <CoarIcon name="logo" size="xl" />
+
+  <!-- Explicitly target a source -->
+  <CoarIcon name="settings" source="coar-builtin" />
+</template>
+```
+
+### HTTP Source (Remote Icons)
+
+Load icons on demand from a URL. Responses are cached automatically.
+
+```ts
+import { CoarIconPlugin, CoarHttpIconSource } from '@cocoar/vue-ui';
+
+app.use(CoarIconPlugin, {
+  sources: [
+    {
+      key: 'cdn',
+      source: new CoarHttpIconSource(
+        (name) => `https://cdn.example.com/icons/${name}.svg`,
+      ),
+    },
+  ],
+});
+```
+
+```vue
+<!-- Fetched async, shows nothing while loading -->
+<CoarIcon name="custom-icon" source="cdn" />
+```
+
+### Override Built-in Icons
+
+Replace specific built-in icons without creating a full source:
+
+```ts
+app.use(CoarIconPlugin, {
+  builtInOverrides: {
+    'settings': '<svg viewBox="0 0 24 24"><!-- your custom settings icon --></svg>',
+  },
+});
+```
+
+### Resolution Order
+
+When no `source` prop is specified, icons are resolved in this order:
+1. **Default source** (set via `defaultSource` option)
+2. **Additional sources** (in registration order)
+3. **Built-in icons** (`coar-builtin`)
+
+The first source that returns a match wins. Use the `source` prop to bypass fallback and target a specific source directly.
+
+## API
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | `—` | Icon name from the registered icon set |
+| `source` | `string` | — | Target a specific icon source (bypasses fallback) |
+| `size` | `'xs' \| 's' \| 'm' \| 'l' \| 'xl' \| string` | `'m'` | Icon size (preset or custom CSS value) |
+| `color` | `string` | `'inherit'` | Icon color (any valid CSS color) |
+| `strokeWidth` | `number` | — | Override stroke width for stroke-based icons |
+| `rotate` | `number` | `0` | Rotation angle in degrees |
+| `rotateTransition` | `number \| string` | — | Rotation animation (ms or CSS transition) |
+| `spin` | `boolean` | `false` | Enable continuous spinning animation |
+| `label` | `string \| number` | — | Text label displayed next to the icon |
+
+### Size Reference
+
+| Size | Pixels |
+|------|--------|
+| `xs` | 12px |
+| `s` | 16px |
+| `m` | 20px |
+| `l` | 24px |
+| `xl` | 32px |