create-yss-spec 2.1.9 → 2.1.11

package/template/.cursor/skills/yss-source-index/scripts/refresh-yss-skill-index.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { access, mkdir, readdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
+const FRONTEND={"yss-ui":["components","hooks","skills"],"yss-components":["components"],"yss-hook":["hooks"],"yss-page-module-development":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
+const URLS={components:"http://192.168.164.27:3200/components",hooks:"http://192.168.164.27:3200/hooks",skills:"http://192.168.164.27:3200/skills"};
+const KEYS=["Audit","Cache","Clear","Command","Configuration","Controller","DTO","Data","Enable","Excel","Handler","Interceptor","Jdbc","Mapper","Mybatis","Page","Properties","Query","Repository","Request","Response","Result","Update","Aspect","Leaf","Id","Dir","Dic","Dictionary","File","Upload","Log","Message","Mail","Liquibase","Circuit","Breaker","Sql","Tpl","Tag","Task","Flow","Report","Validation","Validator","Security","Crypto","User","Variable","Quality","Search","Similarity","Scheduler","Runner","Duck","Dynamic","Factory","Client","Feign","Gateway","Convertor","Adapter","Advice","Bridge","Route","Uploader","Sftp","Minio","Parser","Express","Rule","Template","Generator","Importer","Engine","Event","Submitter","Executor","Context","Status","Type","State"];
+const DOCS=new Set(["README.md","readme.md","HELP.md","TECHNICAL_DESIGN.md"]);
+const exists=async p=>{try{await access(p);return true}catch{return false}};
+async function walk(root){if(!await exists(root))return[];const out=[];for(const item of await readdir(root,{withFileTypes:true})){const p=path.join(root,item.name);if(item.isDirectory())out.push(...await walk(p));else if(item.isFile())out.push(p)}return out}
+const relative=(root,p)=>{const value=path.relative(root,p);return value&&!value.startsWith("..")?value:p};
+function state(root){try{const run=args=>execFileSync("git",["-C",root,...args],{encoding:"utf8",stdio:["ignore","pipe","ignore"]}).trim();return[run(["rev-parse","HEAD"]),run(["status","--porcelain"])?"dirty":"clean"]}catch{return["unavailable","unknown"]}}
+async function sourceRoot(){if(process.env.YSS_SOURCE_ROOT){const root=path.resolve(process.env.YSS_SOURCE_ROOT);if(await exists(path.join(root,"yss-microservice-components")))return root;throw new Error(`YSS_SOURCE_ROOT must point to the repository root containing \`yss-microservice-components\`: ${root}`)}const home=os.homedir(),candidates=[process.cwd(),...ancestors(process.cwd()),path.join(home,"Documents/yss-project/yss-cloud-microservice"),path.join(home,"Documents/yss-project"),path.join(home,"Projects/yss-cloud-microservice"),path.join(home,"Projects")];for(const base of [path.join(home,"Projects"),path.join(home,"Documents"),path.join(home,"Documents/yss-project")])if(await exists(base))for(const entry of await readdir(base,{withFileTypes:true}))if(entry.isDirectory())candidates.push(path.join(base,entry.name));for(const root of candidates)if(await exists(path.join(root,"yss-microservice-components")))return path.resolve(root);throw new Error("Could not find a YSS source repository containing `yss-microservice-components`. Export YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice and rerun.")}
+function ancestors(start){const out=[];let current=path.resolve(start);while(path.dirname(current)!==current){current=path.dirname(current);out.push(current)}return out}
+async function files(bases){const out={docs:[],poms:[],java:[]};for(const base of bases)for(const p of await walk(base)){if(DOCS.has(path.basename(p)))out.docs.push(p);else if(path.basename(p)==="pom.xml")out.poms.push(p);else if(p.endsWith(".java")&&p.includes(`${path.sep}src${path.sep}main${path.sep}java${path.sep}`))out.java.push(p)}for(const a of Object.values(out))a.sort();return out}
+export async function refresh({skillsRoot,source,now=new Date().toISOString(),frontend=true}){const [commit,worktree]=state(source);for(const [skill,parts]of Object.entries(BACKEND)){const bases=parts.map(item=>path.join(source,item));const found=await files(bases);const java=found.java.filter(p=>KEYS.some(key=>path.basename(p,".java").includes(key))).slice(0,120);const list=(items,map,empty)=>items.length?items.map(map):[empty];const baseHints=await Promise.all(bases.map(async p=>`- \`${relative(source,p)}\` (${await exists(p)?"existed":"missing"} when indexed)`));const lines=[`# ${skill} Source Index`,``,`Generated: ${now}`,`Source commit: \`${commit}\``,`Source worktree: \`${worktree}\``,`Indexed source root: resolved at refresh time; set \`YSS_SOURCE_ROOT\` to reproduce or refresh.`,``,`This file is generated by \`yss-source-index/scripts/refresh-yss-skill-index.mjs\`. Do not hand-edit generated sections.`,``,`Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using \`YSS_SOURCE_ROOT\`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.`,``,`## Component Path Hints`,``,...baseHints,``,`## Documentation Files`,``,...list(found.docs,p=>`- \`${relative(source,p)}\``,"- No component documentation files found."),``,`## Maven Modules`,``,...list(found.poms,p=>`- \`${relative(source,path.dirname(p))}\``,"- No Maven modules found."),``,`## Key Java Entry Points`,``,...list(java,p=>`- \`${relative(source,p)}\``,"- No key Java entry points matched the configured name patterns."),``,`## Recommended Next Reads`,``,`- Start with the documentation files above when learning component usage.`,`- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.`,`- Prefer existing component extension points over rewriting framework logic in business modules.`,``];const target=path.join(skillsRoot,skill,"references","source-index.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,lines.join("\n"),"utf8")}
+ if(frontend)for(const[skill,keys]of Object.entries(FRONTEND)){if(!await exists(path.join(skillsRoot,skill)))continue;const target=path.join(skillsRoot,skill,"references","frontend-docs.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,[`# ${skill} Frontend Documentation`,``,`Generated: ${now}`,``,`Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.`,``,...keys.map(key=>`- ${key}: ${URLS[key]}`),``,`When documentation and local code differ, inspect the current project code before editing and prefer established local usage.`,``].join("\n"),"utf8")}
+ return{backend:Object.keys(BACKEND).length,frontend:frontend?Object.keys(FRONTEND).length:0}}
+async function main(){try{const script=path.dirname(fileURLToPath(import.meta.url));const result=await refresh({skillsRoot:path.resolve(process.env.YSS_SKILLS_ROOT||path.join(script,"../..")),source:await sourceRoot(),frontend:!["0","false","no"].includes((process.env.YSS_REFRESH_FRONTEND||"true").toLowerCase())});console.log(`Updated ${result.backend} backend indexes and ${result.frontend} frontend doc references.`)}catch(error){console.error(error.message);process.exitCode=1}}
+if(process.argv[1]===fileURLToPath(import.meta.url))await main();

package/template/.cursor/skills/yss-source-index/scripts/refresh-yss-skill-index.test.mjs

@@ -0,0 +1,15 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { refresh } from "./refresh-yss-skill-index.mjs";
+
+test("writes Node-labelled generated indexes", async () => {
+  const root=await mkdtemp(path.join(tmpdir(),"yss-index-")); const source=path.join(root,"source"); const skills=path.join(root,"skills");
+  await mkdir(path.join(source,"yss-microservice-components/yss-component-cache-parent/src/main/java/demo"),{recursive:true}); await writeFile(path.join(source,"yss-microservice-components/yss-component-cache-parent/src/main/java/demo/CacheConfiguration.java"),"class CacheConfiguration {}");
+  for(const name of ["yss-cache","yss-ui"])await mkdir(path.join(skills,name),{recursive:true});
+  await refresh({skillsRoot:skills,source,now:"2026-01-01T00:00:00Z"});
+  assert.match(await readFile(path.join(skills,"yss-cache/references/source-index.md"),"utf8"),/refresh-yss-skill-index\.mjs/);
+  assert.match(await readFile(path.join(skills,"yss-ui/references/frontend-docs.md"),"utf8"),/components/);
+});

package/template/.cursor/skills/yss-ui/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: "yss-ui"
+description: Use when implementing or reviewing YSS Vue pages that combine YSS wrappers with Ant Design Vue, including component selection, version compatibility, layout, Formily, tables, trees, hooks, overlays, themes, accessibility, API integration, and delivery verification.
+---
+
+# YSS UI 统一路由与交付门禁
+
+本技能是 YSS Vue 生产页面的统一入口。它负责组件路由、版本预检、跨组件约束和交付证据；具体组件、请求、表单和高度实现交给最小专项 skill，避免重复维护 API 细节。
+
+## 1. 权威事实顺序
+
+发生冲突时按以下顺序决策：
+
+1. 冻结的项目工程基线和批准的 Slice Implementation Contract。
+2. lockfile 中实际安装版本与 TypeScript 类型。
+3. 当前项目已通过测试的既有用法。
+4. 与安装版本匹配的 YSS UI 文档和本地快照。
+5. 与安装版本匹配的 Ant Design Vue 官方文档。
+6. 最新官网只用于发现信息，不直接作为生产 API 依据。
+
+内部文档入口见 `references/frontend-docs.md`。Ant Design Vue 组件概览是底层补充资料，不得越过 YSS 组件映射和项目基线。
+
+## 2. 执行前版本预检
+
+进入实现前从前端工程根目录执行：
+
+```bash
+pnpm why vue @yss-ui/components @yss-ui/hooks ant-design-vue vxe-table
+```
+
+记录实际版本、lockfile、验证命令和环境阻塞。完整策略见 `references/antdv-compatibility.md`。
+
+产品设计使用的 Ant Design v6 视觉/token 语义，不等于 Vue 生产实现 API。生产代码必须使用项目安装的 Ant Design Vue 4.x API，禁止复制 React hook、props 或组件写法。
+
+## 3. 组件选型门禁
+
+决策顺序：
+
+1. 查询 `references/component-routing.md`。
+2. YSS 标记为 `required` 的封装必须使用 `@yss-ui/components`。
+3. YSS 未封装时才允许直接使用 `ant-design-vue`。
+4. YSS 封装缺少必要能力时，可以受控回退，但必须记录能力缺口、依赖版本和验证证据。
+5. 禁止引入其他重型表格、树或表单方案绕过 YSS。
+
+典型强制路由：
+
+- `YTable` 替代 AntDV `Table`，列使用 `field/type` 和字段同名插槽。
+- `YTree` 替代 AntDV `Tree`。
+- `YssFormily` 是新代码 canonical name；`YFormily` 仅作为已确认导出的 deprecated alias。
+- `YSplitPane`、`YButton`、`YCard` 等已有封装优先使用 YSS。
+
+## 4. 最小专项 skill 路由
+
+| 任务 | 必须路由 |
+|---|---|
+| 完整页面模块 | `yss-page-module-development` |
+| 页面布局、组件和交互 | `yss-components` |
+| 请求、分页、参数、树数据映射 | `yss-hook` |
+| Formily schema、联动、校验、详情态 | `yss-formily` |
+| 表格高度 | `yss-use-table-height` |
+| 树高度 | `yss-use-tree-height` |
+| Orval、API、useRequest 接入 | `api-integration` |
+| 视觉、token、响应式体验 | `yss-design-system` |
+
+不得引用不存在的复数 Hook skill 名称。
+
+## 5. 页面职责边界
+
+```text
+views/PageName/
+  components/
+  hooks/
+  schemas/
+  index.vue
+  style.less
+```
+
+- `index.vue` 只做页面编排和事件转发。
+- `components/` 承载区块展示和局部交互。
+- `hooks/` 承载请求、分页、参数单一来源、映射和错误兜底。
+- `schemas/` 承载 `YssFormily` schema。
+- 页面内禁止复制请求流程、分页状态和复杂字段转换。
+
+## 6. 跨组件强制约束
+
+### 数据与状态
+
+- 列表查询统一维护 `currentParams`；新查询回到第一页，翻页保留筛选条件。
+- 页面至少处理 `loading`、`empty`、`error`、`disabled/no-access` 和依赖上下文的 `selected` 状态。
+- 成功和失败均需反馈与数据兜底。
+- OpenAPI 未冻结时不得把生成客户端当作稳定契约。
+
+### 主题、locale 与浮层
+
+- 主题、暗色和紧凑模式通过项目 `ConfigProvider`、YSS theme 或语义 token 实现。
+- 禁止页面级硬编码主题色、任意 z-index 或自行反转暗色。
+- locale、时区、日期库和金额/日期格式化由项目统一配置。
+- Modal、Drawer、Dropdown、Tooltip、Select 等遵循项目 popup container、Teleport 和微应用根节点策略。
+
+详细规则见 `references/theme-locale-overlay.md`。
+
+### 可访问性与性能
+
+- 图标按钮提供可访问名称，状态不得只依赖颜色。
+- Modal/Drawer 处理焦点进入、捕获和关闭后的恢复。
+- Table/Tree 大数据量使用项目已验证的虚拟化能力。
+- 远程搜索节流或防抖，复杂组件按需加载。
+- 窄屏明确布局降级、横向滚动和操作收敛策略。
+
+详见 `references/accessibility.md`。
+
+## 7. AntDV 受控回退记录
+
+直接使用 AntDV 时，实施记录至少包含：
+
+```yaml
+component: Select
+yss_wrapper: none
+fallback_reason: YSS 当前无独立 Select 封装
+antdv_version: 4.x.x
+theme_locale_overlay_checked: true
+verification: pnpm type-check
+```
+
+`message`、`notification`、Modal 等服务式 API 仍需确认是否通过项目 `App` / `ConfigProvider` 获取上下文。
+
+## 8. 实施顺序
+
+1. 读取批准合同、项目版本和组件映射。
+2. 选择最小专项 skills。
+3. 搭页面目录和布局。
+4. 接 `YssFormily`、`YTable`、`YTree` 等 YSS 主体组件。
+5. 下沉请求、分页和映射到 `yss-hook`。
+6. 接高度、主题、locale、浮层和无障碍约束。
+7. 联调冻结 API、Mock、路由和权限。
+8. 按 `references/verification.md` 完成分层验证。
+
+## 9. 最小验收
+
+- [ ] 已记录 Vue、YSS UI、AntDV、VXE 实际版本。
+- [ ] 组件选型符合 `component-routing.md`，回退有证据。
+- [ ] 新代码使用 `YssFormily` 和真实存在的 `yss-hook`。
+- [ ] YTable/YTree/Formily/高度 Hook 遵循专项 skill。
+- [ ] 主题、locale、浮层容器和微应用隔离已检查。
+- [ ] loading/empty/error/no-access/selected 状态按影响面覆盖。
+- [ ] 键盘、焦点、标签和颜色对比度已检查。
+- [ ] 已执行 lint、type-check、组件测试及必要的 E2E/视觉回归。
+- [ ] 未执行项记录 `not-applicable` 或环境阻塞原因。
+- [ ] 返回 YSS Skill Execution Result 所需 changed/evidence/verification 信息。
+
+## 10. 按需读取
+
+- 组件路由：`references/component-routing.md`
+- 版本兼容：`references/antdv-compatibility.md`
+- 主题/locale/浮层：`references/theme-locale-overlay.md`
+- 可访问性与性能：`references/accessibility.md`
+- 验证：`references/verification.md`
+- AntDV 迁移与 Demo 审计：`references/migration-antdv-to-yss.md`
+- 快速范例：`references/quick-recipes.md`
+- 交付清单：`references/checklist.md`
+- 本地文档与 Demo 索引：`assets/reference-index.md`、`assets/scenario-index.md`、`assets/keyword-index.md`
+
+## 11. 禁止项
+
+- 禁止根据 AntDV 最新官网直接覆盖项目已安装版本事实。
+- 禁止在已有 YSS required wrapper 时直接使用底层同类组件。
+- 禁止把 React Ant Design v6 API 写入 Vue 生产代码。
+- 禁止引用不存在的 skill、未验证 Demo 或未冻结 API 契约。
+- 禁止省略错误、权限、空态、焦点和验证证据。

package/template/.cursor/skills/yss-ui/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS UI"
+  short_description: "YSS 页面、组件、Hook 与 API 一体化规范"
+  default_prompt: "Use $yss-ui to build a YSS page with standard layout, query form, table, tree, hooks, and API integration."

package/template/.cursor/skills/yss-ui/assets/demos/button/auth-basic.vue

@@ -0,0 +1,24 @@
+<template>
+  <div style="display: flex; gap: 12px; align-items: center">
+    <YButton permission-code="r_security-m_security_datamask-b_datamask_add" type="primary" @click="log('add')">
+      新建
+    </YButton>
+    <YButton
+      permission-code="r_1security-m_security_classification-b_classification_add"
+      :fallback="'disable'"
+      @click="log('edit')"
+    >
+      编辑（无权限禁用）
+    </YButton>
+    <YButton @click="log('normal')">普通按钮（无校验）</YButton>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { YButton } from '@yss-ui/components';
+
+const log = (msg: string) => console.log('[auth-basic]', msg);
+
+// 在浏览器控制台可手动模拟：
+// localStorage.setItem('auth_btns', JSON.stringify([{ btnCode:'USER_ADD', btnName:'新建' }]))
+</script>

package/template/.cursor/skills/yss-ui/assets/demos/button/auth-dropdown.vue

@@ -0,0 +1,29 @@
+<template>
+  <div style="display: flex; gap: 12px; align-items: center">
+    <!--  permissionCode="r_security-m_security_level-b_securitylevel_edit" -->
+    <!-- 当给AuthorityDropdown 组件传入permissionCode时，如果无权限，则不显示 -->
+    <AuthorityDropdown :dropdown-items="items" :options="{ label: 'text', value: 'id' }" @command="onCmd">
+      更多操作
+    </AuthorityDropdown>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { AuthorityDropdown } from '@yss-ui/components';
+
+const items = [
+  { text: '查看', id: 'view' },
+  { text: '编辑', id: 'edit', permissionCode: 'r_security-m_security_datamask-b_datamask_edit' },
+  { text: '删除', id: 'delete', permissionCode: 'DELETE' },
+];
+
+const onCmd = (rec: any) => {
+  console.log('[auth-dropdown]', rec);
+};
+
+// 模拟权限：
+// localStorage.setItem('auth_btns', JSON.stringify([
+//   { btnCode:'r_security-m_security_level-b_securitylevel_edit', btnName:'更多操作' },
+//   { btnCode:'r_security-m_security_datamask-b_datamask_edit', btnName:'编辑' }
+// ]))
+</script>

package/template/.cursor/skills/yss-ui/assets/demos/button/permission.vue

@@ -0,0 +1,10 @@
+<script setup lang="ts">
+import { YButton } from '@yss-ui/components';
+</script>
+
+<template>
+  <div style="display: flex; gap: 12px; align-items: center">
+    <YButton permission-code="USER_ADD" type="primary">新建</YButton>
+    <YButton permission-code="USER_EDIT" :fallback="'disable'">编辑（无权限禁用）</YButton>
+  </div>
+</template>

package/template/.cursor/skills/yss-ui/assets/demos/button/size.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import { YButton } from '@yss-ui/components';
+</script>
+
+<template>
+  <div style="display: flex; gap: 12px; align-items: center">
+    <YButton size="small">Small</YButton>
+    <YButton size="middle">Middle</YButton>
+    <YButton size="large">Large</YButton>
+    <YButton block>Block（铺满）</YButton>
+  </div>
+</template>

package/template/.cursor/skills/yss-ui/assets/demos/button/states.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import { YButton } from '@yss-ui/components';
+</script>
+
+<template>
+  <div style="display: flex; gap: 12px; align-items: center">
+    <YButton type="primary" loading>加载中</YButton>
+    <YButton disabled>禁用</YButton>
+    <YButton ghost type="primary">幽灵</YButton>
+    <YButton danger type="primary">危险</YButton>
+  </div>
+</template>

package/template/.cursor/skills/yss-ui/assets/demos/card/basic/index.vue

@@ -0,0 +1,54 @@
+<script setup lang="ts">
+import { YCard } from '@yss-ui/components';
+import './style.less';
+</script>
+
+<template>
+  <div class="basic-demo">
+    <div class="cards-grid">
+      <!-- 1. 基础卡片 -->
+      <YCard title="基础卡片">
+        <p>这是一个基础的卡片组件，使用默认的样式和配置。</p>
+        <p>内容区域使用默认的内边距（16px）。</p>
+      </YCard>
+
+      <!-- 2. 自定义 padding -->
+      <YCard title="自定义 Padding" :padding="32">
+        <p>这个卡片使用了自定义的 padding 属性。</p>
+        <p>padding 设置为 32px，内容区域有更大的内边距。</p>
+      </YCard>
+
+      <!-- 3. 标题插槽 -->
+      <YCard>
+        <template #title>
+          <span style="color: var(--primary-color, #1890ff); font-weight: 600"> 标题插槽 </span>
+        </template>
+        <p>这个卡片使用了标题插槽，可以自定义标题的样式和内容。</p>
+        <p>标题使用了自定义颜色和字体粗细。</p>
+      </YCard>
+
+      <!-- 4. 自定义 customStyle 样式 -->
+      <YCard
+        title="自定义 Style"
+        :custom-style="{
+          background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+          color: '#fff',
+          border: 'none',
+        }"
+      >
+        <p style="color: rgb(255 255 255 / 90%)">这个卡片使用了 customStyle 属性，直接设置样式对象。</p>
+        <p style="color: rgb(255 255 255 / 90%)">可以设置背景、颜色、边框等任何 CSS 样式。</p>
+      </YCard>
+
+      <!-- 5. 自定义 className 样式 -->
+      <YCard title="自定义 ClassName" class-name="custom-card-style">
+        <p>这个卡片使用了 className 属性，通过 CSS 类名来定制样式。</p>
+        <p>适合需要复用样式或使用主题变量的场景。</p>
+      </YCard>
+    </div>
+  </div>
+</template>
+
+<style scoped lang="less">
+@import url('./style.less');
+</style>

package/template/.cursor/skills/yss-ui/assets/demos/card/basic/style.less

@@ -0,0 +1,41 @@
+.basic-demo {
+  padding: var(--spacing-lg, 24px);
+
+  .cards-grid {
+    display: grid;
+
+    /* 使用 auto-fit 实现自适应布局，最小卡片宽度 280px */
+    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+    gap: var(--spacing-lg, 24px);
+  }
+
+  /* 自定义 className 样式示例 */
+  /deep/ .custom-card-style {
+    background: var(--primary-color-bg, #e6f7ff);
+    border-color: var(--primary-color, #1890ff);
+    border-width: 2px;
+
+    .ant-card-head {
+      background: var(--primary-color-light, #bae7ff);
+      border-bottom-color: var(--primary-color, #1890ff);
+    }
+
+    .ant-card-head-title {
+      color: var(--primary-color, #1890ff);
+      font-weight: 600;
+    }
+  }
+}
+
+/* 响应式优化 */
+@media (max-width: 768px) {
+  .basic-demo {
+    padding: var(--spacing-md, 16px);
+
+    .cards-grid {
+      /* 小屏幕：强制单列 */
+      grid-template-columns: 1fr;
+      gap: var(--spacing-md, 16px);
+    }
+  }
+}

package/template/.cursor/skills/yss-ui/assets/demos/card/cover/index.vue

@@ -0,0 +1,25 @@
+<script setup lang="ts">
+import { YCard } from '@yss-ui/components';
+import { Avatar } from 'ant-design-vue';
+import { SettingOutlined, EditOutlined, EllipsisOutlined } from '@ant-design/icons-vue';
+</script>
+
+<template>
+  <YCard hoverable style="width: 300px">
+    <template #cover>
+      <img alt="example" src="https://gw.alipayobjects.com/zos/rmsportal/JiqGstEfoWAOHiTxclqi.png" />
+    </template>
+    <template #actions>
+      <SettingOutlined key="setting" />
+      <EditOutlined key="edit" />
+      <EllipsisOutlined key="ellipsis" />
+    </template>
+    <template #meta-title>Card title</template>
+    <template #meta-description>This is the description</template>
+    <template #meta-avatar>
+      <Avatar src="https://joeschmoe.io/api/v1/random" />
+    </template>
+  </YCard>
+</template>
+
+<style scoped lang="less"></style>

package/template/.cursor/skills/yss-ui/assets/demos/card/flexible-layout/index.vue

@@ -0,0 +1,122 @@
+<script setup lang="ts">
+import { YCard } from '@yss-ui/components';
+import { ref } from 'vue';
+import './style.less';
+
+/** 定义示例数据 */
+const metricsData = ref([
+  {
+    id: 1,
+    title: 'CPU 使用率',
+    value: '65%',
+    trend: '+2.5%',
+    trendType: 'up',
+    description: '当前系统 CPU 平均使用率',
+  },
+  {
+    id: 2,
+    title: '内存使用',
+    value: '8.2 GB',
+    subValue: '/ 16 GB',
+    trend: '+0.8 GB',
+    trendType: 'up',
+    description: '系统内存占用情况',
+  },
+  {
+    id: 3,
+    title: '活跃连接',
+    value: '1,247',
+    trend: '+156',
+    trendType: 'up',
+    description: '当前活跃网络连接数',
+  },
+  {
+    id: 4,
+    title: '磁盘 I/O',
+    value: '256 MB/s',
+    trend: '-12 MB/s',
+    trendType: 'down',
+    description: '磁盘读写速度',
+  },
+  {
+    id: 5,
+    title: '网络流量',
+    value: '1.2 TB',
+    subValue: '今日',
+    trend: '+0.3 TB',
+    trendType: 'up',
+    description: '累计网络传输流量',
+  },
+  {
+    id: 6,
+    title: '响应时间',
+    value: '128ms',
+    trend: '-15ms',
+    trendType: 'down',
+    description: '平均 API 响应延迟',
+  },
+]);
+
+/**
+ * 获取趋势样式类
+ * @param trendType - 趋势类型
+ * @returns 样式类名
+ */
+const getTrendClass = (trendType: string) => {
+  return `trend-${trendType}`;
+};
+</script>
+
+<template>
+  <div class="flexible-layout-demo">
+    <div class="layout-info">
+      <h3>自适应卡片布局</h3>
+      <p>
+        此布局使用 CSS Grid 的 <code>auto-fit</code> 特性，根据容器宽度自动调整列数。 卡片最小宽度为
+        280px，确保内容的可读性。
+      </p>
+    </div>
+
+    <!-- 自适应网格布局 -->
+    <div class="flexible-grid">
+      <YCard v-for="metric in metricsData" :key="metric.id" class="metric-card" hoverable>
+        <template #title>
+          <div class="metric-title">{{ metric.title }}</div>
+        </template>
+
+        <div class="metric-content">
+          <div class="metric-value">
+            {{ metric.value }}
+            <span v-if="metric.subValue" class="sub-value">{{ metric.subValue }}</span>
+          </div>
+
+          <div class="metric-trend">
+            <span :class="['trend-indicator', getTrendClass(metric.trendType)]">
+              {{ metric.trend }}
+            </span>
+          </div>
+
+          <div class="metric-description">
+            {{ metric.description }}
+          </div>
+        </div>
+      </YCard>
+    </div>
+
+    <!-- 布局说明 -->
+    <div class="layout-explanation">
+      <YCard title="布局特性">
+        <ul class="feature-list">
+          <li><strong>自适应列数：</strong>根据屏幕宽度自动调整列数（1-4列）</li>
+          <li><strong>最小宽度保护：</strong>确保卡片最小宽度 280px，保证内容可读性</li>
+          <li><strong>响应式间距：</strong>不同屏幕尺寸下使用不同的间距值</li>
+          <li><strong>内容适配：</strong>卡片内容自动适应宽度变化</li>
+        </ul>
+      </YCard>
+    </div>
+  </div>
+</template>
+
+<style scoped lang="less">
+@import url('./style.less');
+</style>