SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场ss-component

ss-component

前端与建站

查看项目

更新于 10-15 14:28

技能介绍

用途

ss-component 是 StyleSeed 体系中的一个技能，用于按照 StyleSeed 的设计约定生成一个新的 UI 组件。它面向已经配置了 StyleSeed React/Tailwind v4 组件系统的项目，帮助在既有设计令牌与组件 API 的基础上新增组件，而不是从零发明样式。

主要能力

  • 执行一次性的会话更新预检（once-per-session update preflight）。
  • 处理注册表优先（registry-first）的产物边界：当 .styleseed/project.json 或 .styleseed/artifacts/index.json 存在时，要求完整有效的注册表，并在写组件前解析请求的 artifact ID；若范围不明确则先询问。
  • 通过 ss-resolve 技能目录中的 resolve-context.mjs 脚本进行只读检查，并在编译输出缺失或过期时重新生成后再检查。
  • 读取编译后的方法与来源信息（.styleseed/bundles/<artifact-id>.md 与 .styleseed/manifests/<artifact-id>.json）。
  • 对旧版项目，在注册表文件均不存在时使用 --from-lock STYLESEED.md 路径，并读取 .styleseed/effective-rules.md 与 .styleseed/manifest.json。
  • 读取实际实现上下文：从 artifact 的 implementation.sourceRoots 与 implementation.tokenFiles 出发，沿样式表导入找到令牌定义与配方辅助函数，并参考附近已有原语（如按钮）的真实导入、props、变体与状态。
  • 在已有组件已满足需求时复用现有组件。
  • 严格遵循项目约定生成组件代码。

使用方式

先应用注册表/旧版边界，再读取实际实现上下文。注册表 artifact 从 implementation.sourceRoots 与 implementation.tokenFiles 开始；旧版项目从项目源码中发现已有的组件与样式表入口。沿活动样式表导入找到该 artifact 使用的令牌定义与配方辅助函数（css/theme.css 与 css/recipes.css 只是示例，并非必需位置）。阅读附近已有原语及其真实导入、props、变体和状态。保留项目已批准的令牌与组件 API；若缺少必要上下文或不受支持，应在发明文件、别名、令牌或替代物之前报告缺口。

注册表检查命令（只读）：

node "<ss-resolve>/scripts/resolve-context.mjs" --project-root . --artifact <artifact-id> --agent <agent> --check

对于有效注册表但编译输出缺失或过期的情况，运行同一命令但不带 --check，然后再次检查。遇到无效配置或安装错误时停止；不要为了让检查通过而更改已批准的选择。成功后，只读取选定的 .styleseed/bundles/<artifact-id>.md 与 .styleseed/manifests/<artifact-id>.json 作为编译方法与来源。影响多个 artifact 的共享组件需要分别解析并检查每个受影响的 artifact，而不是合并它们的 bundle。

旧版项目路径（仅当两个注册表文件都不存在时）：

node "<ss-resolve>/scripts/resolve-context.mjs" --project-root . --from-lock STYLESEED.md --agent <agent> --check

对于缺失或过期的旧版输出，运行同一命令但不带 --check，然后再次检查。仅在成功后读取 .styleseed/effective-rules.md 与 .styleseed/manifest.json。

生成组件时遵循的约定：

  • 使用函数声明（不是 const）
  • 添加 data-slot="component-name" 属性
  • 使用项目已有的 cn() 工具及其已验证的导入路径进行 className 合并
  • 使用 React.ComponentProps<> 进行 prop 类型标注
  • 始终支持 className prop 以便覆盖
  • 若组件有变体，使用 CVA（class-variance-authority）
  • 使用语义化颜色令牌（bg-card、text-foreground），绝不使用内联十六进制

设计令牌用法：

  • 颜色：text-foreground、bg-card、text-brand、text-muted-foreground、border-border
  • 图案表面：ss-pattern-surface；内嵌/控件/图标使用匹配的 ss-* 类
  • 原语使用项目令牌尺度；不要硬编码某一种圆角或阴影个性
  • 间距遵循一个可重复的选定配方节奏
  • 动效：duration-[var(--duration-fast)]、ease-[var(--ease-default)]

排版规则：

  • Display（36-48px）：leading-none tracking-[-0.02em]
  • Heading（18-24px）：leading-snug tracking-[-0.01em]
  • Body（14-17px）：leading-normal（默认字距）
  • Caption 大写（10-13px）：tracking-[0.05em]
  • 使用 size-* 简写代替 w-* h-*
  • 使用 ms-/me- 代替 ml-/mr-（逻辑属性）

无障碍要求：

  • 触摸命中区域：最小 44x44px（min-h-11 min-w-11）；以指针为主的桌面控件可使用契约批准的 36–40px 尺寸，同时保留键盘访问与适用的无障碍下限
  • 支持 aria-* 属性透传
  • 使用 focus-visible:ring-2 focus-visible:ring-ring 实现键盘焦点
  • 动画尊重 prefers-reduced-motion
  • 将组件作为命名导出（不是默认导出）
  • 将文件放在第 1 步确定的现有组件目录中，位于受影响 artifact 的实现范围内。src/components/ui/ 是常见布局，并非每个项目都要创建的路径。组合式模式请路由到 /ss-pattern。

适用场景

  • 在已配置 StyleSeed React/Tailwind v4 组件系统的项目中新增单个 UI 组件。
  • 需要遵循项目既有设计令牌、组件 API 与无障碍约定的组件生成。

限制

以下情况不应使用本技能：

  • 整页脚手架 → 使用 /ss-page
  • 组合式多组件模式 → 使用 /ss-pattern
  • 调整已有组件 —— 直接编辑文件即可
  • 未配置 StyleSeed React/Tailwind v4 组件系统的项目

其他限制：注册表不完整、无效或没有编译输出时，绝不回退到全局旧版 bundle、创建 STYLESEED.md 或重启设置；遇到无效配置或安装错误时停止，不得更改已批准的选择以通过检查。若缺少必要上下文或不受支持，应先报告缺口，而不是发明文件、别名、令牌或替代物。