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

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

@@ -0,0 +1,330 @@
+<!-- Generated from apps/docs/foundations/spacing.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Spacing & Effects
+
+Layout rhythm, corner shapes, and depth — the visual building blocks that give the system its feel.
+
+## Border Radius
+
+Seven radius tokens shape everything from subtle input rounding to fully circular avatars.
+
+**Demo — `spacing/demos/BorderRadius.vue`**
+
+```vue
+<template>
+  <div class="radius-showcase">
+    <div
+      v-for="token in radiusTokens"
+      :key="token.name"
+      class="radius-card"
+    >
+      <div
+        class="radius-shape"
+        :style="{ borderRadius: token.value }"
+      />
+      <div class="radius-meta">
+        <span class="radius-name">{{ token.name }}</span>
+        <code class="radius-value">{{ token.value }}</code>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+const radiusTokens = [
+  { name: 'XXS', value: '1px' },
+  { name: 'XS', value: '2px' },
+  { name: 'S', value: '3px' },
+  { name: 'M', value: '4px' },
+  { name: 'L', value: '5px' },
+  { name: 'XL', value: '6px' },
+  { name: 'Full', value: '999px' },
+];
+</script>
+
+<style scoped>
+.radius-showcase {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 20px;
+  padding: 8px 0;
+}
+
+.radius-card {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 12px;
+}
+
+.radius-shape {
+  width: 72px;
+  height: 72px;
+  background: var(--vp-c-brand-soft);
+  transition: transform 0.2s ease;
+}
+
+.radius-shape:hover {
+  transform: scale(1.08);
+}
+
+.radius-meta {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 2px;
+}
+
+.radius-name {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--vp-c-text-1);
+}
+
+.radius-value {
+  font-size: 11px;
+  color: var(--vp-c-text-3);
+  font-family: var(--vp-font-family-mono);
+  background: none !important;
+}
+</style>
+```
+
+## Spacing Scale
+
+All spacing is built on a **4 px grid**. These tokens control padding, margins, and gaps throughout the system.
+
+**Demo — `spacing/demos/SpacingScale.vue`**
+
+```vue
+<template>
+  <div class="spacing-scale">
+    <div
+      v-for="token in spacingTokens"
+      :key="token.name"
+      class="spacing-row"
+    >
+      <div class="spacing-label">
+        <span class="spacing-name">{{ token.name }}</span>
+        <code class="spacing-value">{{ token.value }}</code>
+      </div>
+      <div class="spacing-track">
+        <div
+          class="spacing-bar"
+          :style="{ width: token.value }"
+        />
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+const spacingTokens = [
+  { name: 'XXS', value: '2px' },
+  { name: 'XS', value: '4px' },
+  { name: 'S', value: '8px' },
+  { name: 'M', value: '16px' },
+  { name: 'L', value: '24px' },
+  { name: 'XL', value: '32px' },
+  { name: 'XXL', value: '48px' },
+  { name: 'XXXL', value: '64px' },
+];
+</script>
+
+<style scoped>
+.spacing-scale {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 4px 0;
+}
+
+.spacing-row {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.spacing-label {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  min-width: 100px;
+  flex-shrink: 0;
+}
+
+.spacing-name {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--vp-c-text-1);
+  min-width: 36px;
+}
+
+.spacing-value {
+  font-size: 11px;
+  color: var(--vp-c-text-3);
+  font-family: var(--vp-font-family-mono);
+  background: none !important;
+}
+
+.spacing-track {
+  flex: 1;
+  height: 24px;
+  background: var(--vp-c-bg-soft);
+  border-radius: 6px;
+  display: flex;
+  align-items: center;
+  padding: 0 4px;
+  overflow: hidden;
+}
+
+.spacing-bar {
+  height: 14px;
+  min-width: 2px;
+  background: var(--vp-c-brand-1);
+  border-radius: 4px;
+  transition: width 0.4s cubic-bezier(0.22, 1, 0.36, 1);
+}
+</style>
+```
+
+## Stroke Width
+
+Border thickness for dividers, outlines, and component borders.
+
+| Token | Value | Use case |
+|-------|-------|----------|
+| `--coar-stroke-width-xs` | 0.5 px | Hairline dividers |
+| `--coar-stroke-width-s` | 1 px | Default borders |
+| `--coar-stroke-width-m` | 2 px | Emphasis borders |
+| `--coar-stroke-width-l` | 4 px | Heavy accents |
+
+## Shadows & Elevation
+
+Six shadow levels create the illusion of depth. The shadow _is_ the demo — notice how each card lifts further off the surface.
+
+**Demo — `spacing/demos/Shadows.vue`**
+
+```vue
+<template>
+  <div class="shadow-showcase">
+    <div class="shadow-surface">
+      <div
+        v-for="token in shadowTokens"
+        :key="token.name"
+        class="shadow-card-wrap"
+      >
+        <div
+          class="shadow-card"
+          :style="{ boxShadow: `var(${token.variable})` }"
+        />
+        <div class="shadow-meta">
+          <span class="shadow-name">{{ token.name }}</span>
+          <span class="shadow-desc">{{ token.description }}</span>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+const shadowTokens = [
+  { name: 'XS', variable: '--coar-shadow-xs', description: 'Hover states' },
+  { name: 'S', variable: '--coar-shadow-s', description: 'Cards' },
+  { name: 'M', variable: '--coar-shadow-m', description: 'Dropdowns' },
+  { name: 'L', variable: '--coar-shadow-l', description: 'Modals' },
+  { name: 'XL', variable: '--coar-shadow-xl', description: 'Overlays' },
+  { name: 'Focus', variable: '--coar-shadow-focus', description: 'Focus ring' },
+];
+</script>
+
+<style scoped>
+.shadow-showcase {
+  padding: 8px 0;
+}
+
+.shadow-surface {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  gap: 32px;
+  padding: 32px 16px;
+  background: var(--vp-c-bg-soft);
+  border-radius: 12px;
+}
+
+.shadow-card-wrap {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+}
+
+.shadow-card {
+  width: 88px;
+  height: 88px;
+  background: var(--vp-c-bg);
+  border-radius: 10px;
+  transition: transform 0.25s ease;
+}
+
+.shadow-card:hover {
+  transform: translateY(-2px);
+}
+
+.shadow-meta {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 2px;
+}
+
+.shadow-name {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--vp-c-text-1);
+}
+
+.shadow-desc {
+  font-size: 11px;
+  color: var(--vp-c-text-3);
+}
+</style>
+```
+
+## Token Reference
+
+### Spacing
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--coar-spacing-xxs` | 2 px | Tight inner gaps |
+| `--coar-spacing-xs` | 4 px | Small padding, icon gaps |
+| `--coar-spacing-s` | 8 px | Compact padding, list gaps |
+| `--coar-spacing-m` | 16 px | Default padding and gaps |
+| `--coar-spacing-l` | 24 px | Section padding |
+| `--coar-spacing-xl` | 32 px | Large section gaps |
+| `--coar-spacing-xxl` | 48 px | Page-level spacing |
+| `--coar-spacing-xxxl` | 64 px | Hero / splash spacing |
+
+### Border Radius
+
+| Token | Value |
+|-------|-------|
+| `--coar-radius-xxs` | 1 px |
+| `--coar-radius-xs` | 2 px |
+| `--coar-radius-s` | 3 px |
+| `--coar-radius-m` | 4 px |
+| `--coar-radius-l` | 5 px |
+| `--coar-radius-xl` | 6 px |
+| `--coar-radius-full` | 999 px |
+
+### Shadows
+
+| Token | Usage |
+|-------|-------|
+| `--coar-shadow-xs` | Subtle lift for hover states |
+| `--coar-shadow-s` | Cards and raised elements |
+| `--coar-shadow-m` | Dropdowns and popovers |
+| `--coar-shadow-l` | Modals and dialogs |
+| `--coar-shadow-xl` | Elevated overlays |
+| `--coar-shadow-focus` | Keyboard focus ring |

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

@@ -0,0 +1,140 @@
+<!-- Generated from apps/docs/foundations/theming.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Theme Editor
+
+The **Theme Editor** is a live token editor built into every Cocoar app. It lets you explore the entire token system — from raw palette shades all the way to semantic roles — and export a ready-to-paste CSS snippet.
+
+> The editor is visible as a small icon in the bottom-right corner of this page. Click it to try everything described here in real time.
+
+## Setup
+
+Add `CoarThemeEditor` to your app's layout. It renders as a floating panel — no wrapper or portal needed.
+
+```ts
+import CoarThemeEditor from '@cocoar/vue-ui/theme-editor';
+```
+
+```vue
+<!-- In your root layout -->
+<CoarThemeEditor />
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `hideDarkToggle` | `boolean` | `false` | Hides the light/dark toggle. Set to `true` when your app manages dark mode itself. |
+
+## The Token Tree
+
+Cocoar's token system has three layers. Each layer builds on the one above it.
+
+```
+Layer 1 — Primitives
+  --coar-color-red-600          oklch-formula of --coar-error
+
+Layer 2 — Semantic
+  --coar-background-semantic-error-bold   → var(--coar-color-red-600)
+
+Layer 3 — Component
+  --coar-button-danger-bg                 → var(--coar-background-semantic-error-bold)
+```
+
+Changing a primitive ripples through semantic tokens, which ripple through every component that uses them. The Theme Editor exposes all three layers.
+
+## Tabs
+
+### Presets
+
+Four built-in starting points: **Enterprise** (default), **Modern SaaS** (rounded), **Playful** (pill buttons, vivid accent), and **Minimal** (sharp corners, no shadows). Selecting a preset resets all other tabs to the preset's values.
+
+### Brand
+
+Sets the five base hue values that anchor the entire palette:
+
+| Token | Default | Purpose |
+|-------|---------|---------|
+| `--coar-accent` | `#1183CD` | Primary actions, links, focus rings |
+| `--coar-success` | `#1e8f48` | Positive feedback |
+| `--coar-error` | `#d63b3b` | Errors, destructive actions |
+| `--coar-warning` | `#cc821f` | Caution |
+| `--coar-info` | `#5e6b84` | Neutral informational |
+
+Each color opens a **palette editor** (floating panel) where you can fine-tune the L (lightness) and C (chroma) for individual steps 50–900 using oklch relative color syntax.
+
+### Semantic
+
+Maps semantic roles to palette entries. Each row shows the resolved color, lets you pick a palette (Accent / Red / Green / Amber / Slate) and a step (50–900), and has a reset button that turns accent-colored when changed.
+
+This is the layer that connects intent to color: `--coar-background-semantic-error-bold` points at `Red / 600` by default. Reassigning it to `Amber / 600` would make all error surfaces amber — including form field borders, toast backgrounds, and the danger button — without touching any component code.
+
+### Corners
+
+Controls the global radius scale (`xxs` → `xl`) plus per-component-group overrides for buttons, inputs, cards, menus, popovers, dialogs, and toasts. Select from named scale steps or `Full` (pill shape).
+
+### Type
+
+Font family for body text and headings, chosen from a curated list of Google Fonts. Fonts load on demand when selected.
+
+### Spacing
+
+Component density slider: **Compact** (0.75×), **Default** (1×), or **Comfortable** (1.33×). Scales horizontal padding on all interactive components.
+
+### Depth
+
+Box shadow per component group (buttons never have shadows; cards, menus, dialogs, and toasts do).
+
+### Motion
+
+A single duration multiplier that scales all `--coar-duration-*` tokens proportionally. Set to 0 for instant transitions, or push it above 2× to slow everything down for testing.
+
+## Exporting
+
+Type a class name into the name field at the bottom of the editor (default: `custom`), then click **Download CSS** to get a scoped block containing only the tokens you changed:
+
+```css
+/* coar-theme--myapp.css */
+.coar-theme--myapp {
+  --coar-accent: #7C3AED;
+  --coar-button-radius: var(--coar-radius-m);
+  --coar-input-radius: var(--coar-radius-m);
+}
+```
+
+Drop it into your app after the Cocoar stylesheet and apply the class to your root element:
+
+```html
+<!-- index.html -->
+<html class="coar-theme--myapp">
+<head>
+  <link rel="stylesheet" href="@cocoar/vue-ui/styles" />
+  <link rel="stylesheet" href="/coar-theme--myapp.css" />
+</head>
+```
+
+Or import in your entry file:
+
+```ts
+import '@cocoar/vue-ui/styles';
+import './coar-theme--myapp.css';
+```
+
+Because themes are classes, you can apply different themes to different subtrees:
+
+```html
+<html class="coar-theme--myapp">
+  <!-- most of the app uses the custom theme -->
+
+  <div class="coar-theme--compact">
+    <!-- this section uses a separate theme -->
+  </div>
+
+  <div class="coar-theme-none">
+    <!-- this section always uses library defaults -->
+  </div>
+</html>
+```
+
+### `.coar-theme-none`
+
+The library ships a built-in reset class. Apply `.coar-theme-none` to any element to restore all themeable tokens to their library defaults inside that subtree, regardless of what theme class is set on an ancestor. Useful for "always default" widgets like admin panels or embedded forms.

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

@@ -0,0 +1,206 @@
+<!-- Generated from apps/docs/foundations/typography.md by apps/docs/scripts/sync-skill.mjs. Do not edit; edit the docs page. -->
+
+# Typography
+
+Our type system creates clear visual hierarchy and ensures readability across all interfaces. Eleven styles cover everything from large display headings to fine-print footnotes.
+
+## Type Scale
+
+Each row shows the style rendered at its actual size, with font metadata alongside.
+
+**Demo — `typography/demos/TypeScale.vue`**
+
+```vue
+<template>
+  <div class="type-scale">
+    <div v-for="item in typeScale" :key="item.label" class="type-row">
+      <div class="type-meta">
+        <span class="type-label">{{ item.label }}</span>
+        <span class="type-spec">{{ item.spec }}</span>
+      </div>
+      <div class="type-sample-wrap">
+        <p :class="item.class" class="type-sample">{{ item.text }}</p>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+const typeScale = [
+  { label: 'Display', class: 'coar-display', text: 'Display', spec: 'Inter / 72px / Bold' },
+  { label: 'Title', class: 'coar-title', text: 'Title', spec: 'Inter / 48px / Bold' },
+  { label: 'Subtitle', class: 'coar-subtitle', text: 'Subtitle', spec: 'Inter / 32px / Regular' },
+  { label: 'Heading', class: 'coar-heading', text: 'Heading', spec: 'Poppins / 24px / SemiBold' },
+  { label: 'Subheading', class: 'coar-subheading', text: 'Subheading', spec: 'Poppins / 20px / Regular' },
+  { label: 'Body', class: 'coar-body', text: 'The quick brown fox jumps over the lazy dog.', spec: 'Poppins / 16px / Regular' },
+  { label: 'Body Bold', class: 'coar-body-bold', text: 'The quick brown fox jumps over the lazy dog.', spec: 'Poppins / 16px / Bold' },
+  { label: 'Body Small', class: 'coar-body-small', text: 'The quick brown fox jumps over the lazy dog.', spec: 'Poppins / 14px / Regular' },
+  { label: 'Body Small Bold', class: 'coar-body-small-bold', text: 'The quick brown fox jumps over the lazy dog.', spec: 'Poppins / 14px / Bold' },
+  { label: 'Caption', class: 'coar-caption', text: 'Caption Text', spec: 'Poppins / 12px / Medium / Uppercase' },
+  { label: 'Footnote', class: 'coar-footnote', text: 'Footnote — Small print and legal copy.', spec: 'Poppins / 10px / Regular' },
+];
+</script>
+
+<style scoped>
+.type-scale {
+  display: flex;
+  flex-direction: column;
+}
+
+.type-row {
+  display: flex;
+  align-items: center;
+  gap: 32px;
+  padding: 20px 0;
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+
+.type-row:last-child {
+  border-bottom: none;
+}
+
+.type-meta {
+  flex: 0 0 180px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.type-label {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--vp-c-text-1);
+}
+
+.type-spec {
+  font-size: 12px;
+  color: var(--vp-c-text-3);
+  font-family: var(--vp-font-family-mono);
+}
+
+.type-sample-wrap {
+  flex: 1;
+  min-width: 0;
+}
+
+.type-sample {
+  margin: 0;
+  color: var(--vp-c-text-1);
+  line-height: 1.5;
+}
+
+@media (max-width: 640px) {
+  .type-row {
+    flex-direction: column;
+    gap: 8px;
+    align-items: flex-start;
+  }
+
+  .type-meta {
+    flex: none;
+  }
+}
+</style>
+```
+
+## Usage Example
+
+Typography hierarchy applied to a realistic article layout — caption, title, subtitle, body, and footnote working together.
+
+**Demo — `typography/demos/TypographyExample.vue`**
+
+```vue
+<template>
+  <div class="article-example">
+    <span class="coar-caption">DESIGN SYSTEMS &middot; 5 MIN READ</span>
+    <h1 class="coar-title article-title">Building Consistent Interfaces</h1>
+    <p class="coar-subtitle article-subtitle">
+      How a shared type system improves readability and reduces design debt
+    </p>
+    <div class="article-body">
+      <p class="coar-body">
+        Typography is the backbone of any design system. A well-defined type scale creates
+        clear visual hierarchy, helps users scan content quickly, and ensures readability
+        across every screen size and device.
+      </p>
+      <p class="coar-body">
+        <span class="coar-body-bold">Consistency matters.</span> When every heading, label, and
+        body paragraph follows the same rules, the interface feels cohesive and professional.
+        Users develop intuition for what each level of text means — they stop reading
+        and start scanning.
+      </p>
+    </div>
+    <div class="article-footer">
+      <span class="coar-footnote">Last updated March 2026</span>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.article-example {
+  max-width: 640px;
+  padding: 32px;
+  border-radius: 12px;
+  background: var(--vp-c-bg-soft);
+}
+
+.article-title {
+  margin: 12px 0 4px;
+}
+
+.article-subtitle {
+  margin: 0 0 24px;
+  color: var(--vp-c-text-2);
+}
+
+.article-body {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.article-body p {
+  margin: 0;
+  line-height: 1.7;
+  color: var(--vp-c-text-1);
+}
+
+.article-footer {
+  margin-top: 24px;
+  padding-top: 16px;
+  border-top: 1px solid var(--vp-c-divider);
+  color: var(--vp-c-text-3);
+}
+</style>
+```
+
+## CSS Classes Reference
+
+Apply these utility classes directly to any HTML element.
+
+| Class | Role | Font | Size | Weight |
+|---|---|---|---|---|
+| `.coar-display` | Display | Inter | 72 px | Bold |
+| `.coar-title` | Title | Inter | 48 px | Bold |
+| `.coar-subtitle` | Subtitle | Inter | 32 px | Regular |
+| `.coar-heading` | Heading | Poppins | 24 px | SemiBold |
+| `.coar-subheading` | Subheading | Poppins | 20 px | Regular |
+| `.coar-body` | Body | Poppins | 16 px | Regular |
+| `.coar-body-bold` | Body Bold | Poppins | 16 px | Bold |
+| `.coar-body-small` | Body Small | Poppins | 14 px | Regular |
+| `.coar-body-small-bold` | Body Small Bold | Poppins | 14 px | Bold |
+| `.coar-caption` | Caption | Poppins | 12 px | Medium, Uppercase |
+| `.coar-footnote` | Footnote | Poppins | 10 px | Regular |
+
+## Usage
+
+```html
+<h1 class="coar-title">Page Title</h1>
+<p class="coar-subtitle">Supporting subtitle text</p>
+<p class="coar-body">Main body content goes here.</p>
+<span class="coar-caption">LABEL TEXT</span>
+```
+
+> **Tip: Font Loading**
+>
+> The type scale uses **Inter** for display-level text and **Poppins** for body and UI text. Import `@cocoar/vue-ui/fonts` to self-host both fonts — no external CDN required.