@yh-ui/yh-ui-skill 1.0.39 → 1.0.42

package/assets/skills/yh-ui/references/recipes-table.md

@@ -1,83 +1,134 @@
 # Deep Recipe: YhTable
 
-Use this recipe when the user asks for data tables, admin list pages, exports, selection, pagination, or large datasets.
+Use this recipe when building complex data tables, admin list views, large datasets with virtualization, custom cell layouts, context menus, data export, or printing.
 
 ## Default Choice
 
-Use `YhTable` with a stable `columns` array and typed row data. Add `YhPagination` only when pagination is not handled through `YhTable`'s `pagination` prop.
+Use `YhTable` with a statically defined `columns` array. Let `YhTable` handle pagination internally through the `pagination` configuration property.
 
 ## Source-Aligned API Highlights
 
-- Props: `data`, `columns`, `rowKey`, `loading`, `pagination`, `selectionConfig`, `sortConfig`, `filterConfig`, `virtualConfig`, `toolbarConfig`, `emptyConfig`, `height`, `maxHeight`, `border`, `stripe`, `showIndex`.
-- Events: `sort-change`, `filter-change`, `page-change`, `selection-change`, `row-click`, `cell-click`, `scroll`, `update:data`.
-- Expose: `refresh`, `clearSelection`, `getSelectionRows`, `sort`, `clearSort`, `filter`, `clearFilter`, `exportData`, `print`, `scrollTo`, `doLayout`.
+- **Props**: `data`, `columns`, `rowKey`, `loading`, `pagination`, `height`, `maxHeight`, `border`, `stripe`, `virtualConfig`, `toolbarConfig`, `rowConfig`, `expandConfig`, `selectionConfig`, `sortConfig`, `filterConfig`.
+- **Events**: `sort-change`, `filter-change`, `page-change`, `selection-change`, `row-click`, `cell-click`, `scroll`, `update:data`.
+- **Slots**: `default` (column definitions), `toolbar`, `toolbar-left`, `toolbar-right`, `toolbar-left-prefix`, `toolbar-right-suffix`.
+- **Exposed APIs**: `refresh()`, `clearSelection()`, `getSelectionRows()`, `exportData(options)`, `importData(options)`, `print(options)`, `scrollTo(options)`, `doLayout()`, `setColumnVisible(prop, visible)`.
 
-## Pattern: Request-Driven Table
+## Pattern: Advanced Admin Table
+
+This example demonstrates request-driven loading, cell custom slot rendering, toolbars, virtual scrolling for large datasets, printing, and Excel exporting:
 
 ```vue
 <script setup lang="ts">
-import { computed, ref } from 'vue'
-import { YhButton, YhEmpty, YhForm, YhFormItem, YhInput, YhTable } from '@yh-ui/components'
+import { ref, computed } from 'vue'
+import { YhTable, YhButton, YhTag, YhMessage, YhPopconfirm } from '@yh-ui/components'
 import { createRequest, useRequest } from '@yh-ui/request'
 
-interface UserRow {
+interface LogRow {
   id: number
-  name: string
-  email: string
-  status: string
+  username: string
+  action: string
+  status: 'success' | 'failed'
+  ip: string
+  createdTime: string
 }
 
 const api = createRequest({ baseURL: '/api' })
-const keyword = ref('')
-const page = ref({ currentPage: 1, pageSize: 20, total: 0 })
+const tableRef = ref<InstanceType<typeof YhTable> | null>(null)
+const page = ref({ currentPage: 1, pageSize: 50, total: 0 })
 
+// Static columns definition - keep outside template
 const columns = [
-  { prop: 'name', label: 'Name', minWidth: 160 },
-  { prop: 'email', label: 'Email', minWidth: 220 },
-  { prop: 'status', label: 'Status', width: 120 }
+  { prop: 'username', label: 'User', width: 150, sortable: true },
+  { prop: 'action', label: 'Action Description', minWidth: 200 },
+  { prop: 'status', label: 'Status', width: 120, slot: 'status' },
+  { prop: 'ip', label: 'IP Address', width: 140 },
+  { prop: 'createdTime', label: 'Timestamp', width: 180 },
+  { prop: 'operations', label: 'Operations', width: 120, slot: 'operations' }
 ]
 
-const { data, loading, error, refresh } = useRequest(async () => {
-  const result = await api.get<{ list: UserRow[]; total: number }>('/users', {
-    params: { keyword: keyword.value, page: page.value.currentPage, pageSize: page.value.pageSize }
+// Request client using useRequest
+const { data, loading, refresh } = useRequest(async () => {
+  const result = await api.get<{ list: LogRow[]; total: number }>('/audit/logs', {
+    params: { page: page.value.currentPage, limit: page.value.pageSize }
   })
   page.value.total = result.total
   return result.list
 })
 
 const rows = computed(() => data.value || [])
+
+// Native Excel Export using YhTable exposed method
+function exportExcel() {
+  if (!tableRef.value) return
+  tableRef.value.exportData({
+    filename: 'audit_logs',
+    type: 'xlsx',
+    original: true
+  })
+  YhMessage.success('Exporting file...')
+}
+
+// Native Print using YhTable exposed method
+function printTable() {
+  if (!tableRef.value) return
+  tableRef.value.print({
+    title: 'Audit Activity Report',
+    showPageNumber: true
+  })
+}
+
+function deleteRow(row: LogRow) {
+  YhMessage.success(`Deleted log: ${row.id}`)
+  refresh()
+}
 </script>
 
 <template>
-  <YhForm inline>
-    <YhFormItem label="Keyword">
-      <YhInput v-model="keyword" clearable placeholder="Search users" />
-    </YhFormItem>
-    <YhFormItem>
-      <YhButton type="primary" :loading="loading" @click="refresh">Search</YhButton>
-    </YhFormItem>
-  </YhForm>
-
-  <YhTable
-    row-key="id"
-    :data="rows"
-    :columns="columns"
-    :loading="loading"
-    :pagination="page"
-    border
-    stripe
-    @page-change="refresh"
-  />
-
-  <YhEmpty v-if="!loading && !rows.length && !error" description="No users found" />
+  <div class="table-container">
+    <YhTable
+      ref="tableRef"
+      row-key="id"
+      :data="rows"
+      :columns="columns"
+      :loading="loading"
+      :pagination="page"
+      height="600px"
+      border
+      stripe
+      :virtual-config="{ enabled: true, itemHeight: 45 }"
+      @page-change="refresh"
+    >
+      <!-- Custom Left Toolbar Slot -->
+      <template #toolbar-left>
+        <YhButton type="primary" icon="mdi:refresh" @click="refresh">Refresh Logs</YhButton>
+        <YhButton type="success" icon="mdi:file-excel" @click="exportExcel"
+          >Export to Excel</YhButton
+        >
+        <YhButton icon="mdi:printer" @click="printTable">Print Report</YhButton>
+      </template>
+
+      <!-- Custom Cell Slots mapped via column.slot -->
+      <template #status="{ row }">
+        <YhTag :type="row.status === 'success' ? 'success' : 'danger'">
+          {{ row.status === 'success' ? 'Success' : 'Failed' }}
+        </YhTag>
+      </template>
+
+      <template #operations="{ row }">
+        <YhPopconfirm title="Are you sure you want to delete this log?" @confirm="deleteRow(row)">
+          <template #reference>
+            <YhButton type="text" danger icon="mdi:delete" />
+          </template>
+        </YhPopconfirm>
+      </template>
+    </YhTable>
+  </div>
 </template>
 ```
 
 ## Agent Rules
 
-- Keep `columns` outside the template.
-- Use `rowKey` whenever rows have identity.
-- Use `virtualConfig` for large local datasets.
-- Use `loading` and `emptyConfig`/`YhEmpty` for async states.
-- Use table events for remote sort/filter/page behavior.
-- Do not invent `YhDataTable`; use `YhTable`.
+- **Static Columns**: Always define the `columns` array inside `<script setup>` as a constant or a reactive `computed` array; never define arrays inline inside the template to prevent duplicate component re-renders.
+- **Set Table Height**: When enabling `virtual-config` for large datasets, an explicit `height` or `max-height` (e.g. `600px` or `100%`) must be set on `YhTable` to calculate viewport slots correctly.
+- **Row Identity**: Always pass a unique `row-key` prop (e.g. `id`, `uuid`) to help Vue track element identity during sort, select, and virtual updates.
+- **Avoid wrapper components**: Do not invent a custom `YhDataTable` or wrapper component. Always use the native `YhTable` from `@yh-ui/components`.

package/assets/skills/yh-ui/references/recipes-theme.md

@@ -0,0 +1,141 @@
+# Deep Recipe: YH-UI Theme System
+
+Use this recipe when integrating or customising themes, dark mode, responsive scaling, compact density, or color-blind friendly palettes using `@yh-ui/theme`.
+
+## Default Choice
+
+Use `ThemePlugin` during app registration and access reactive theme state using `useTheme` or `useThemeVars`.
+
+## Setup
+
+```ts
+import { createApp } from 'vue'
+import { ThemePlugin } from '@yh-ui/theme'
+import App from './App.vue'
+
+const app = createApp(App)
+
+app.use(ThemePlugin, {
+  preset: 'default', // 'default' | 'dark' | 'blue' | 'green' | 'purple' | 'orange' | 'rose' | 'amber' | 'teal' | 'indigo' | 'slate' | 'zinc'
+  dark: false, // Initial mode
+  persist: true, // Save theme choices to localStorage automatically
+  persistKey: 'yh-ui-theme',
+  followSystem: true, // Follow OS dark/light mode preference
+  radius: 'md', // 'none' | 'sm' | 'md' | 'lg' | 'full'
+  density: 'comfortable', // 'comfortable' | 'compact' | 'dense'
+  colorBlindMode: 'none', // 'none' | 'protanopia' | 'deuteranopia' | 'tritanopia' | 'achromatopsia'
+  algorithm: 'default' // 'default' | 'vibrant' | 'muted' | 'pastel'
+})
+
+app.mount('#app')
+```
+
+## Composition APIs
+
+Use `useTheme` to get the ThemeManager instance or `useThemeVars` for Vue-friendly reactive properties:
+
+```vue
+<script setup lang="ts">
+import { useTheme, useThemeVars } from '@yh-ui/theme'
+
+// Option 1: Accessing the ThemeManager
+const theme = useTheme()
+
+function toggleDark() {
+  theme.toggleDarkMode()
+}
+
+function selectPreset(name: 'blue' | 'green' | 'purple') {
+  theme.setPreset(name)
+}
+
+function selectDensity(density: 'comfortable' | 'compact' | 'dense') {
+  theme.setDensity(density)
+}
+
+// Option 2: Using reactive variables directly
+const { dark, theme: currentPreset, density, colorBlindMode } = useThemeVars()
+</script>
+
+<template>
+  <div class="settings">
+    <p>Current Theme: {{ currentPreset }} (Dark mode: {{ dark }})</p>
+    <p>Density Factor: {{ density }}</p>
+    <p>Accessibility Mode: {{ colorBlindMode }}</p>
+
+    <button @click="toggleDark">Toggle Dark Mode</button>
+    <button @click="selectPreset('blue')">Blue Preset</button>
+    <button @click="selectDensity('compact')">Compact Layout</button>
+  </div>
+</template>
+```
+
+## Advanced Theme Customization
+
+### Smart Palette Generation
+
+Generate complete secondary semantic status colors (success, warning, danger, info) automatically from a single primary brand color:
+
+```ts
+import { useTheme } from '@yh-ui/theme'
+
+const theme = useTheme()
+// Generates and applies primary/success/warning/danger/info hex color scale
+theme.applyFromPrimary('#722ed1')
+```
+
+### Color Contrast Checks (WCAG 2.1 AA/AAA)
+
+Ensure generated colors meet user accessibility contrast guidelines:
+
+```ts
+import { checkContrast, getTextColorForBackground } from '@yh-ui/theme'
+
+// Returns true if contrast ratio is >= 4.5 (or >= 7 for AAA)
+const isAccessible = checkContrast('#ffffff', '#1890ff', 'AA')
+
+// Returns '#ffffff' or '#000000' based on contrast luminance
+const suitableTextColor = getTextColorForBackground('#1890ff')
+```
+
+### Component-Level Custom Styles
+
+You can override specific design tokens for a single component globally or dynamically:
+
+```ts
+import { useTheme } from '@yh-ui/theme'
+
+const theme = useTheme()
+theme.apply({
+  components: {
+    YhButton: {
+      '--yh-button-font-weight': '600',
+      '--yh-button-border-radius': '8px'
+    }
+  }
+})
+```
+
+## CSS Variable Usage
+
+Instead of hardcoding color hexes, border-radii, spacing, or typography values, always leverage YH-UI's global theme tokens:
+
+```vue
+<style scoped>
+.custom-card {
+  color: var(--yh-text-color-primary);
+  background-color: var(--yh-bg-color);
+  border: 1px solid var(--yh-border-color);
+  border-radius: var(--yh-border-radius-base);
+  padding: calc(var(--yh-spacing-unit) * 2);
+
+  /* Font size and line height scales dynamically with density setting */
+  font-size: var(--yh-font-size-base);
+  line-height: var(--yh-line-height-base);
+}
+
+.custom-card:hover {
+  border-color: var(--yh-color-primary-hover);
+}
+</style>
+```

package/assets/skills/yh-ui/references/request.md

@@ -13,13 +13,41 @@ const api = createRequest({
   retry: 2
 })
 
-api.interceptors.request.use((config) => {
-  config.headers = {
-    ...config.headers,
-    Authorization: `Bearer ${getToken()}`
+api.interceptors.request.use(
+  (config) => {
+    const token = localStorage.getItem('token')
+    if (token) {
+      config.headers = {
+        ...config.headers,
+        Authorization: `Bearer ${token}`
+      }
+    }
+    return config
+  },
+  (error) => Promise.reject(error)
+)
+
+api.interceptors.response.use(
+  (response) => response,
+  async (error) => {
+    const originalRequest = error.config
+    // Automatic JWT token refresh flow
+    if (error.response?.status === 401 && !originalRequest._retry) {
+      originalRequest._retry = true
+      try {
+        const { token } = await api.post('/auth/refresh')
+        localStorage.setItem('token', token)
+        originalRequest.headers['Authorization'] = `Bearer ${token}`
+        return api(originalRequest)
+      } catch (refreshError) {
+        // Redirect to login or clear token on fail
+        localStorage.removeItem('token')
+        return Promise.reject(refreshError)
+      }
+    }
+    return Promise.reject(error)
   }
-  return config
-})
+)
 ```
 
 ## useRequest
@@ -27,6 +55,7 @@ api.interceptors.request.use((config) => {
 ```vue
 <script setup lang="ts">
 import { createRequest, useRequest } from '@yh-ui/request'
+import { YhButton, YhMessage } from '@yh-ui/components'
 
 interface User {
   id: number
@@ -34,37 +63,87 @@ interface User {
 }
 
 const api = createRequest({ baseURL: '/api' })
-const { data, loading, error, refresh, run } = useRequest<User[]>(() => api.get<User[]>('/users'))
+
+// useRequest returns reactive state and trigger helpers
+const { data, loading, error, refresh, run } = useRequest<User[]>(() => api.get<User[]>('/users'), {
+  immediate: true,
+  onSuccess: (data) => {
+    YhMessage.success(`Loaded ${data.length} users successfully`)
+  },
+  onError: (err) => {
+    YhMessage.error(`Failed to load users: ${err.message}`)
+  }
+})
 </script>
 
 <template>
-  <YhButton :loading="loading" @click="refresh">Refresh</YhButton>
-  <YhButton @click="run()">Run</YhButton>
-  <pre v-if="error">{{ error.message }}</pre>
-  <ul>
+  <div class="action-bar">
+    <YhButton :loading="loading" type="primary" @click="refresh">Refresh</YhButton>
+    <YhButton @click="run()">Force Run</YhButton>
+  </div>
+
+  <div v-if="loading" class="loading-state">Loading users...</div>
+  <div v-else-if="error" class="error-state">{{ error.message }}</div>
+  <ul v-else class="user-list">
     <li v-for="user in data" :key="user.id">{{ user.name }}</li>
   </ul>
 </template>
 ```
 
-## SSE
+## SSE (Server-Sent Events)
 
-```ts
+Use `useSSE` for real-time streaming notifications, logs, or updates. It handles connection lifecycles, retries, and errors automatically:
+
+```vue
+<script setup lang="ts">
+import { ref, onUnmounted } from 'vue'
 import { useSSE } from '@yh-ui/request'
 
+interface EventPayload {
+  msg: string
+  time: string
+}
+
+const events = ref<EventPayload[]>([])
+
 const { isConnected, connect, disconnect, error } = useSSE('/api/events', {
   reconnect: true,
   reconnectInterval: 3000,
+  maxReconnectAttempts: 5,
   onMessage: (event) => {
-    console.log(event.data)
+    const payload = JSON.parse(event.data) as EventPayload
+    events.value.push(payload)
+  },
+  onError: (err) => {
+    console.error('SSE Error:', err)
   }
 })
+
+// Always clean up connections when component is unmounted
+onUnmounted(() => {
+  disconnect()
+})
+</script>
+
+<template>
+  <div>
+    <p
+      >Status:
+      <span :class="{ connected: isConnected }">{{
+        isConnected ? 'Connected' : 'Disconnected'
+      }}</span></p
+    >
+    <p v-if="error">Connection error: {{ error.message }}</p>
+    <ul>
+      <li v-for="item in events" :key="item.time">[{{ item.time }}] {{ item.msg }}</li>
+    </ul>
+  </div>
+</template>
 ```
 
 ## Agent Rules
 
-- Use `createRequest`, not old names.
-- Prefer `useRequest` for component state instead of manually maintaining `loading`, `data`, and `error`.
-- Use `useSSE` or `useAIStream` for streaming responses.
-- Use pagination/load-more hooks when building list pages.
-- Keep auth token handling in request interceptors or server middleware.
+- Use `createRequest`, not old/legacy API clients.
+- Always prefer `useRequest` for fetching state in Vue components instead of manual `ref(true)` loading flags.
+- Use `useSSE` for server streaming logs/updates, and make sure to clean up connection via `disconnect()` in `onUnmounted`.
+- Place global request interception logic (like auth header additions) inside the central request client, not scattered around views.

package/assets/skills/yh-ui/references/vue-component-practices.md

@@ -4,20 +4,43 @@ Use these rules when generating or reviewing YH-UI Vue 3 code. They combine Vue
 
 ## SFC Structure
 
-- Prefer `<script setup lang="ts">` for application examples and small components.
-- Order SFC blocks as `<script>`, `<template>`, then `<style>`.
-- Keep imports at the top, then types, props/emits/models, state, computed values, watchers, lifecycle hooks, and functions grouped by feature.
-- Use `scoped` styles for page/example CSS unless the task intentionally edits global theme CSS.
-- Avoid large inline template expressions. Move non-trivial logic to computed values or functions.
+- Prefer `<script setup lang="ts">` for all application pages and component definitions.
+- Always order SFC blocks as `<script>`, `<template>`, then `<style scoped>`.
+- Internal setup block sequence:
+  1. Module/library imports (separate external dependencies from local `@yh-ui` packages).
+  2. TypeScript types & interfaces.
+  3. `defineProps`, `defineEmits`, and `defineModel`.
+  4. Reactive state & refs.
+  5. Computed properties.
+  6. Watchers (`watch` / `watchEffect`).
+  7. Lifecycle hooks (`onMounted`, `onUnmounted`, etc.).
+  8. Action functions / methods.
+- Use `scoped` styles to prevent styling leakages. Never use raw global selector tags inside SFC styles.
+- Keep templates clean: move calculations, complex conditions, or array mapping out of the template into computed variables.
 
 ## Props, Emits, And v-model
 
-- Type props with TypeScript interfaces or inline type literals.
-- Use `withDefaults(defineProps<Props>(), defaults)` when defaults are needed.
-- Use typed `defineEmits` for custom events.
-- For two-way binding, prefer `defineModel` in new Vue 3.4+ examples when the target project supports it; otherwise use `modelValue` and `update:modelValue`.
-- Never mutate props directly. Emit events or copy prop values into local state when local edits are needed.
-- Keep event names explicit and user-action oriented, such as `submit`, `cancel`, `refresh`, or `update:filters`.
+- Always type props with clear TypeScript interfaces. Use type-only imports (`import type { ... }`) for external type models.
+- For **Vue 3.5+**, prefer reactive props destructuring:
+  ```ts
+  const { size = 'medium', disabled = false, data = () => [] } = defineProps<Props>()
+  ```
+  This is the official Vue 3.5+ best practice and avoids verbose `withDefaults`.
+- For Vue < 3.5 or projects without destructure support, fallback to `withDefaults(defineProps<Props>(), defaults)`.
+- Use typed `defineEmits` or `defineModel` for two-way bindings:
+
+  ```ts
+  // Two-way binding model (Vue 3.4+)
+  const modelValue = defineModel<string>({ default: '' })
+
+  // Typed custom events
+  const emit = defineEmits<{
+    change: [value: string]
+    submit: []
+  }>()
+  ```
+
+- Never mutate props. If props need internal modifications, copy them to a local `ref` or compile them via `computed` getters/setters.
 
 ## Slots And Composition
 
@@ -26,14 +49,20 @@ Use these rules when generating or reviewing YH-UI Vue 3 code. They combine Vue
 - In app pages, compose YH-UI components directly instead of wrapping every component in a thin local abstraction.
 - Create composables only when stateful logic is reused or complex enough to deserve a named boundary.
 
-## Reactivity
-
-- Use `ref` for primitives and replaceable values.
-- Use `reactive` for stable object state that is mutated by field.
-- Use `computed` for derived values instead of maintaining duplicated state.
-- Use `watch` for side effects, not for deriving values.
-- Avoid destructuring reactive objects unless using `toRefs`, `storeToRefs`, or Vue 3.5 reactive props destructure intentionally.
-- Use `shallowRef` for large immutable objects, external instances, editors, charts, or flow graphs when deep reactivity is unnecessary.
+## Reactivity & Lifecycle Cleanups
+
+- Use `ref` for primitive values, lists/arrays, or objects that will be completely overwritten.
+- Use `reactive` only for complex nested states that require deep property mutation.
+- Use `computed` for all derived values instead of writing sync watchers or manually maintaining double state variables.
+- Use `watch` or `watchEffect` solely for side-effects (e.g. storage sync, async API triggers). Always specify `immediate: true` or `deep: true` only if required.
+- Use `shallowRef` for heavy objects, DOM nodes, third-party library instances (ECharts, Monco Editor, Flow canvases), as deep reactivity on these will degrade performance.
+- **Critical Lifecycle Cleanups**: Always clean up timeouts, intervals, ResizeObservers, WebSocket event listeners, and custom event listeners in `onUnmounted`:
+  ```ts
+  const timer = setInterval(tick, 1000)
+  onUnmounted(() => {
+    clearInterval(timer)
+  })
+  ```
 
 ## Accessibility
 
@@ -76,6 +105,40 @@ Use these rules when generating or reviewing YH-UI Vue 3 code. They combine Vue
 - Use `useNamespace` for internal BEM-style component classes when editing package components.
 - Use `useZIndex`, `useLocale`, `useId`/`useYhId`, and config hooks instead of local one-off implementations.
 
+## YH-UI Prioritization & Extension Workflow
+
+To ensure we prioritize existing UI framework logic and do not write duplicate custom HTML/CSS controls, follow this decision tree when implementing user interface requests:
+
+1. **Verify Availability**: Search `references/source-truth.md` and `references/component-map.md`. If a component exists (e.g., `YhTable`, `YhDialog`, `YhConfigProvider`, `YhScrollbar`), you **must** use it. Do not write raw `<div class="custom-scroll">` or raw `<dialog>`.
+2. **Handle Feature Gaps (Encapsulation/Extension)**: If a component is missing a sub-feature, do not abandon the component. Apply extension patterns in order of priority:
+   - **Slot Customization**: Use slots (e.g., `#toolbar`, `#empty`, `#default` custom cells) to inject the custom logic.
+   - **Props & Event Listeners**: Use component event bindings and dynamic property configs to override behavior.
+   - **CSS Variable Injection**: Inject style variables (e.g. style overrides like `--yh-button-font-weight`) to alter theme aesthetics without altering core element code.
+   - **Composite Patterns**: Group multiple YH-UI components together (e.g. wrap a `YhTable` and `YhPagination` or nesting slots) before trying to write raw elements.
+3. **Raw Component Last Resort**: Only build a custom element from scratch if the functionality is entirely absent in the UI framework and cannot be composed/wrapped. You must document this reasoning in the code comments.
+
+## TypeScript Strict Standards
+
+To maintain clean typing boundaries and avoid runtime failures, follow these TS conventions:
+
+- **Type-only imports**: When importing interfaces, schemas, or types from YH-UI packages, use the `import type` syntax:
+  ```ts
+  import type { FormSchema } from '@yh-ui/components'
+  import type { FlowNode, FlowEdge } from '@yh-ui/flow'
+  import type { ThemeOptions } from '@yh-ui/theme'
+  ```
+- **Type Template Refs**: Never leave component template refs untyped (`const refVal = ref(null)`). Always use Vue's `InstanceType` utility to extract component exports:
+
+  ```ts
+  import { ref } from 'vue'
+  import { YhTable } from '@yh-ui/components'
+
+  const tableRef = ref<InstanceType<typeof YhTable> | null>(null)
+  ```
+
+- **Exposed APIs**: Access exposed methods on components strictly through these typed instances (e.g., `tableRef.value?.exportData(...)`, `formRef.value?.validate()`).
+- **Data Models**: Strongly type response objects and row lists using `interface` declarations; never pass `any` into data bindings or request helper promises.
+
 ## Testing Expectations
 
 - For reusable components, test props, emitted events, slots, keyboard/focus behavior, and important visual states.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yh-ui/yh-ui-skill",
-  "version": "1.0.39",
+  "version": "1.0.42",
   "description": "YH-UI skill installer for modern AI coding tools",
   "type": "module",
   "bin": {