@bcelep/capint 0.4.2 → 0.6.5

package/skills/craft-authoring/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: craft-authoring
+description: 执行 /craft 时必读：提供 Workflow / Skill / Prompt 的脚手架模板、防护语法、填充与验证清单；长模板与自检细节不在 craft workflow 内重复，一律以本 skill 为准。
+---
+
+# Craft Authoring — 脚手架与自检
+
+本 skill 承接 **`/craft` workflow** 中「怎么写」的细节；`/craft` 只保留仪式与步骤路由。**禁止**在 workflow 里复述本节全文。
+
+## Workflow 骨架（最小可用）
+
+```markdown
+---
+description: [一句话，列表展示用]
+---
+
+# /name
+
+<phase_context>
+你是 **[角色]**。
+**使命**：…
+**能力**：…
+**限制**：…
+**原则**：…
+**与用户的关系**：…
+**Output Goal**: `路径`
+</phase_context>
+
+---
+
+## CRITICAL …
+
+> [!IMPORTANT]
+> **为什么**：…
+> - …
+> - …
+
+---
+
+## Step 1: …
+
+**目标**：…
+
+> [!IMPORTANT]
+> 你**必须**… **为什么？** …
+
+**思考引导**:
+1. …
+2. …
+
+---
+
+<completion_criteria>
+- …
+</completion_criteria>
+```
+
+## Skill 骨架（description 必须是触发条件）
+
+```markdown
+---
+name: kebab-name
+description: 当 [具体触发场景] 时加载。[一句话能力概括]
+---
+
+# 标题
+
+## 硬边界 / 原则
+…
+
+## 输入 / 输出契约
+…
+```
+
+**description 忌**：泛泛「我能处理 PDF」；**宜**：「当用户要读取/编辑 PDF 时」。
+
+## Prompt 骨架
+
+```markdown
+# 标题
+
+## 角色
+…
+
+## 任务
+…
+
+## 约束
+…
+
+## 输出格式
+…
+```
+
+## 防护语法速查
+
+
+| 机制                      | 用途       |
+| ----------------------- | -------- |
+| `[!IMPORTANT]`          | 不可跳过节点   |
+| `##  CRITICAL`        | 边界醒目     |
+| `你**必须**`               | 强制动作     |
+| 具体引导问题                  | 替代「好好想想」 |
+| `<completion_criteria>` | 完成定义     |
+
+
+重要约束建议包含：**做什么 / 为什么 / 违反时长什么样**。
+
+## 填充内容（Step 5 等价）
+
+用 `sequential-thinking` 组织 **3–5 个 thought**，覆盖：目标、最易错点、每步 I/O、引导问题、模板复用、调研结论如何打入文档。
+
+**质量扫一眼**：目标是否逐步清晰、约束是否有「为什么」、是否有输出模板、关键处有 / 对照（如需）。
+
+## 验证清单（输出前）
+
+**结构**：frontmatter、`phase_context`（workflow）、CRITICAL 块、每步有目标、`<completion_criteria>`。
+
+**内容**：路径含 `.prismx/v{N}/` 若适用、kebab-case、工具调用语法正确。
+
+## 自我批评（输出前最后一道）
+
+用 `sequential-thinking` **3–5 thought**：用户会在哪卡住？AI 可能在哪偷懒跳过？与 `/challenge` 级质量相比缺什么？随后迭代修复再交付。

package/skills/create-design-system-rules/SKILL.md

@@ -0,0 +1,530 @@
+---
+name: create-design-system-rules
+description: Generates custom design system rules for the user's codebase. Use when user says "create design system rules", "generate rules for my project", "set up design rules", "customize design system guidelines", or wants to establish project-specific conventions for Figma-to-code workflows. Requires Figma MCP server connection.
+metadata:
+  mcp-server: figma
+  version: '1.0.1'
+origin: verdent
+prismx_bundle: verdent
+prismx_imported_at: 2026-05-27
+---
+
+# Create Design System Rules
+
+## Overview
+
+This skill helps you generate custom design system rules tailored to your project's specific needs. These rules guide AI coding agents to produce consistent, high-quality code when implementing Figma designs, ensuring that your team's conventions, component patterns, and architectural decisions are followed automatically.
+
+### Supported Rule Files
+
+Design system rules should be saved as project-level rule files that AI coding agents can automatically load. Common conventions include:
+
+- A rules file in the project root (e.g., `RULES.md`, `DESIGN_SYSTEM.md`)
+- A dedicated rules directory (e.g., `.rules/figma-design-system.md`)
+
+Choose a location that fits your project's conventions. The key is that the rules are committed to version control and easily discoverable by the agent.
+
+## What Are Design System Rules?
+
+Design system rules are project-level instructions that encode the "unwritten knowledge" of your codebase - the kind of expertise that experienced developers know and would pass on to new team members:
+
+- Which layout primitives and components to use
+- Where component files should be located
+- How components should be named and structured
+- What should never be hardcoded
+- How to handle design tokens and styling
+- Project-specific architectural patterns
+
+Once defined, these rules dramatically reduce repetitive prompting and ensure consistent output across all Figma implementation tasks.
+
+## Prerequisites
+
+- Figma MCP server must be connected and accessible
+  - Before proceeding, verify the Figma MCP server is connected by checking if Figma MCP tools (e.g., `create_design_system_rules`) are available.
+  - If the tools are not available, the Figma MCP server may not be enabled. Guide the user to enable the Figma MCP server that is included with the plugin. They may need to restart their MCP client afterward.
+- Access to the project codebase for analysis
+- Understanding of your team's component conventions (or willingness to establish them)
+
+## When to Use This Skill
+
+Use this skill when:
+
+- Starting a new project that will use Figma designs
+- Onboarding an AI coding agent to an existing project with established patterns
+- Standardizing Figma-to-code workflows across your team
+- Updating or refining existing design system conventions
+- Users explicitly request: "create design system rules", "set up Figma guidelines", "customize rules for my project"
+
+## Required Workflow
+
+**Follow these steps in order. Do not skip steps.**
+
+### Step 1: Run the Create Design System Rules Tool
+
+Call the Figma MCP server's `create_design_system_rules` tool to get the foundational prompt and template.
+
+**Parameters:**
+
+- `clientLanguages`: Comma-separated list of languages used in the project (e.g., "typescript,javascript", "python", "javascript")
+- `clientFrameworks`: Framework being used (e.g., "react", "vue", "svelte", "angular", "unknown")
+
+This tool returns guidance and a template for creating design system rules.
+
+Structure your design system rules following the template format provided in the tool's response.
+
+### Step 2: Analyze the Codebase
+
+Before finalizing rules, analyze the project to understand existing patterns:
+
+**Component Organization:**
+
+- Where are UI components located? (e.g., `src/components/`, `app/ui/`, `lib/components/`)
+- Is there a dedicated design system directory?
+- How are components organized? (by feature, by type, flat structure)
+
+**Styling Approach:**
+
+- What CSS framework or approach is used? (Tailwind, CSS Modules, styled-components, etc.)
+- Where are design tokens defined? (CSS variables, theme files, config files)
+- Are there existing color, typography, or spacing tokens?
+
+**Component Patterns:**
+
+- What naming conventions are used? (PascalCase, kebab-case, prefixes)
+- How are component props typically structured?
+- Are there common composition patterns?
+
+**Architecture Decisions:**
+
+- How is state management handled?
+- What routing system is used?
+- Are there specific import patterns or path aliases?
+
+### Step 3: Generate Project-Specific Rules
+
+Based on your codebase analysis, create a comprehensive set of rules. Include:
+
+#### General Component Rules
+
+```markdown
+- IMPORTANT: Always use components from `[YOUR_PATH]` when possible
+- Place new UI components in `[COMPONENT_DIRECTORY]`
+- Follow `[NAMING_CONVENTION]` for component names
+- Components must export as `[EXPORT_PATTERN]`
+```
+
+#### Styling Rules
+
+```markdown
+- Use `[CSS_FRAMEWORK/APPROACH]` for styling
+- Design tokens are defined in `[TOKEN_LOCATION]`
+- IMPORTANT: Never hardcode colors - always use tokens from `[TOKEN_FILE]`
+- Spacing values must use the `[SPACING_SYSTEM]` scale
+- Typography follows the scale defined in `[TYPOGRAPHY_LOCATION]`
+```
+
+#### Figma MCP Integration Rules
+
+```markdown
+## Figma MCP Integration Rules
+
+These rules define how to translate Figma inputs into code for this project and must be followed for every Figma-driven change.
+
+### Required Flow (do not skip)
+
+1. Run get_design_context first to fetch the structured representation for the exact node(s)
+2. If the response is too large or truncated, run get_metadata to get the high-level node map, then re-fetch only the required node(s) with get_design_context
+3. Run get_screenshot for a visual reference of the node variant being implemented
+4. Only after you have both get_design_context and get_screenshot, download any assets needed and start implementation
+5. Translate the output (usually React + Tailwind) into this project's conventions, styles, and framework
+6. Validate against Figma for 1:1 look and behavior before marking complete
+
+### Implementation Rules
+
+- Treat the Figma MCP output (React + Tailwind) as a representation of design and behavior, not as final code style
+- Replace Tailwind utility classes with `[YOUR_STYLING_APPROACH]` when applicable
+- Reuse existing components from `[COMPONENT_PATH]` instead of duplicating functionality
+- Use the project's color system, typography scale, and spacing tokens consistently
+- Respect existing routing, state management, and data-fetch patterns
+- Strive for 1:1 visual parity with the Figma design
+- Validate the final UI against the Figma screenshot for both look and behavior
+```
+
+#### Asset Handling Rules
+
+```markdown
+## Asset Handling
+
+- The Figma MCP server provides an assets endpoint which can serve image and SVG assets
+- IMPORTANT: If the Figma MCP server returns a localhost source for an image or SVG, use that source directly
+- IMPORTANT: DO NOT import/add new icon packages - all assets should be in the Figma payload
+- IMPORTANT: DO NOT use or create placeholders if a localhost source is provided
+- Store downloaded assets in `[ASSET_DIRECTORY]`
+```
+
+#### Project-Specific Conventions
+
+```markdown
+## Project-Specific Conventions
+
+- [Add any unique architectural patterns]
+- [Add any special import requirements]
+- [Add any testing requirements]
+- [Add any accessibility standards]
+- [Add any performance considerations]
+```
+
+### Step 4: Save Rules to the Project
+
+Save the generated rules to a project-level rule file so they are automatically loaded in future sessions.
+
+**Recommended locations:**
+- Project root: `DESIGN_SYSTEM_RULES.md` — simple, easy to find
+- Dedicated directory: `.rules/figma-design-system.md` — better for projects with many rule files
+
+If the project already has an existing rules file, append the design system rules as a new section.
+
+After saving, the rules will be automatically loaded by the agent and applied to all Figma implementation tasks.
+
+### Step 5: Validate and Iterate
+
+After creating rules:
+
+1. Test with a simple Figma component implementation
+2. Verify the agent follows the rules correctly
+3. Refine any rules that aren't working as expected
+4. Share with team members for feedback
+5. Update rules as the project evolves
+
+## Rule Categories and Examples
+
+### Essential Rules (Always Include)
+
+**Component Discovery:**
+
+```markdown
+- UI components are located in `src/components/ui/`
+- Feature components are in `src/components/features/`
+- Layout primitives are in `src/components/layout/`
+```
+
+**Design Token Usage:**
+
+```markdown
+- Colors are defined as CSS variables in `src/styles/tokens.css`
+- Never hardcode hex colors - use `var(--color-*)` tokens
+- Spacing uses the 4px base scale: `--space-1` (4px), `--space-2` (8px), etc.
+```
+
+**Styling Approach:**
+
+```markdown
+- Use Tailwind utility classes for styling
+- Custom styles go in component-level CSS modules
+- Theme customization is in `tailwind.config.js`
+```
+
+### Recommended Rules (Highly Valuable)
+
+**Component Patterns:**
+
+```markdown
+- All components must accept a `className` prop for composition
+- Variant props should use union types: `variant: 'primary' | 'secondary'`
+- Icon components should accept `size` and `color` props
+```
+
+**Import Conventions:**
+
+```markdown
+- Use path aliases: `@/components`, `@/styles`, `@/utils`
+- Group imports: React, third-party, internal, types
+- No relative imports beyond parent directory
+```
+
+**Code Quality:**
+
+```markdown
+- Add JSDoc comments for exported components
+- Include PropTypes or TypeScript types for all props
+- Extract magic numbers to named constants
+```
+
+### Optional Rules (Project-Specific)
+
+**Accessibility:**
+
+```markdown
+- All interactive elements must have aria-labels
+- Color contrast must meet WCAG AA standards
+- Keyboard navigation required for all interactions
+```
+
+**Performance:**
+
+```markdown
+- Lazy load images with the `Image` component from `@/components/Image`
+- Use React.memo for components that receive complex props
+- Icons should be SVG components, not icon fonts
+```
+
+**Testing:**
+
+```markdown
+- Include unit tests for new components in `__tests__/` directory
+- Use Testing Library queries (getByRole, getByLabelText)
+- Test all interactive states and variants
+```
+
+## Examples
+
+### Example 1: React + Tailwind Project
+
+User says: "Create design system rules for my React project"
+
+**Actions:**
+
+1. Run `create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="react")`
+2. Analyze codebase structure
+3. Generate rules:
+
+```markdown
+# Figma MCP Integration Rules
+
+## Component Organization
+
+- UI components are in `src/components/ui/`
+- Page components are in `src/app/`
+- Use Tailwind for styling
+
+## Figma Implementation Flow
+
+1. Run get_design_context for the node
+2. Run get_screenshot for visual reference
+3. Map Figma colors to Tailwind colors defined in `tailwind.config.js`
+4. Reuse components from `src/components/ui/` when possible
+5. Validate against screenshot before completing
+
+## Styling Rules
+
+- IMPORTANT: Use Tailwind utility classes, not inline styles
+- Colors are defined in `tailwind.config.js` theme.colors
+- Spacing uses Tailwind's default scale
+- Custom components go in `src/components/ui/`
+
+## Asset Rules
+
+- IMPORTANT: Use localhost sources from Figma MCP server directly
+- Store static assets in `public/assets/`
+- DO NOT install new icon libraries
+```
+
+4. Save to the appropriate rule file for the user's agent
+5. Test with a simple button implementation
+
+**Result:** The agent now consistently follows the project's conventions when implementing Figma designs.
+
+### Example 2: Vue + Custom CSS Project
+
+User says: "Set up Figma rules for my Vue app"
+
+**Actions:**
+
+1. Run `create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="vue")`
+2. Discover that project uses CSS modules and a custom design token system
+3. Generate rules:
+
+```markdown
+# Figma MCP Integration Rules
+
+## Component Organization
+
+- Components are in `src/components/`
+- Composables are in `src/composables/`
+- Vue SFC structure: <script setup>, <template>, <style scoped>
+
+## Design Tokens
+
+- IMPORTANT: All colors defined in `src/styles/tokens.css` as CSS variables
+- Use `var(--color-primary)`, `var(--color-secondary)`, etc.
+- Spacing: `var(--space-xs)` through `var(--space-xl)`
+- Typography: `var(--text-sm)` through `var(--text-2xl)`
+
+## Figma Implementation Flow
+
+1. Run get_design_context and get_screenshot
+2. Translate React output to Vue 3 Composition API
+3. Map Figma colors to CSS variables in `src/styles/tokens.css`
+4. Use CSS Modules for component styles
+5. Check for existing components in `src/components/` before creating new ones
+
+## Styling Rules
+
+- Use CSS Modules (`.module.css` files)
+- IMPORTANT: Reference design tokens, never hardcode values
+- Scoped styles with CSS modules
+```
+
+4. Save to the appropriate rule file for the user's agent
+5. Validate with a card component
+
+**Result:** The agent now correctly translates Figma designs to Vue components using the project's design token system.
+
+### Example 3: Design System Team
+
+User says: "Generate rules for our design system library"
+
+**Actions:**
+
+1. Run `create_design_system_rules(clientLanguages="typescript", clientFrameworks="react")`
+2. Analyze the monorepo structure with design system package
+3. Generate comprehensive rules:
+
+```markdown
+# Design System Rules
+
+## Repository Structure
+
+- Design system components: `packages/design-system/src/components/`
+- Documentation: `packages/docs/`
+- Design tokens: `packages/tokens/src/`
+
+## Component Development
+
+- IMPORTANT: All components must be in `packages/design-system/src/components/`
+- Component file structure: `ComponentName/index.tsx`, `ComponentName.stories.tsx`, `ComponentName.test.tsx`
+- Export all components from `packages/design-system/src/index.ts`
+
+## Design Tokens
+
+- Colors: `packages/tokens/src/colors.ts`
+- Typography: `packages/tokens/src/typography.ts`
+- Spacing: `packages/tokens/src/spacing.ts`
+- IMPORTANT: Never hardcode values - import from tokens package
+
+## Documentation Requirements
+
+- Add Storybook story for every component
+- Include JSDoc with @example
+- Document all props with descriptions
+- Add accessibility notes
+
+## Figma Integration
+
+1. Get design context and screenshot from Figma
+2. Map Figma tokens to design system tokens
+3. Create or extend component in design system package
+4. Add Storybook stories showing all variants
+5. Validate against Figma screenshot
+6. Update documentation
+```
+
+4. Save to the appropriate rule file and share with team
+5. Add to team documentation
+
+**Result:** Entire team follows consistent patterns when adding components from Figma to the design system.
+
+## Best Practices
+
+### Start Simple, Iterate
+
+Don't try to capture every rule upfront. Start with the most important conventions and add rules as you encounter inconsistencies.
+
+### Be Specific
+
+Instead of: "Use the design system"
+Write: "Always use Button components from `src/components/ui/Button.tsx` with variant prop ('primary' | 'secondary' | 'ghost')"
+
+### Make Rules Actionable
+
+Each rule should tell the agent exactly what to do, not just what to avoid.
+
+Good: "Colors are defined in `src/theme/colors.ts` - import and use these constants"
+Bad: "Don't hardcode colors"
+
+### Use IMPORTANT for Critical Rules
+
+Prefix rules that must never be violated with "IMPORTANT:" to ensure the agent prioritizes them.
+
+```markdown
+- IMPORTANT: Never expose API keys in client-side code
+- IMPORTANT: Always sanitize user input before rendering
+```
+
+### Document the Why
+
+When rules seem arbitrary, explain the reasoning:
+
+```markdown
+- Place all data-fetching in server components (reduces client bundle size and improves performance)
+- Use absolute imports with `@/` alias (makes refactoring easier and prevents broken relative paths)
+```
+
+## Common Issues and Solutions
+
+### Issue: The agent isn't following the rules
+
+**Cause:** Rules may be too vague or not properly loaded by the agent.
+**Solution:**
+
+- Make rules more specific and actionable
+- Verify rules are saved in the correct configuration file
+- Restart your agent or IDE to reload rules
+- Add "IMPORTANT:" prefix to critical rules
+
+### Issue: Rules conflict with each other
+
+**Cause:** Contradictory or overlapping rules.
+**Solution:**
+
+- Review all rules for conflicts
+- Establish a clear priority hierarchy
+- Remove redundant rules
+- Consolidate related rules into single, clear statements
+
+### Issue: Too many rules increase latency
+
+**Cause:** Excessive rules increase context size and processing time.
+**Solution:**
+
+- Focus on the 20% of rules that solve 80% of consistency issues
+- Remove overly specific rules that rarely apply
+- Combine related rules
+- Use progressive disclosure (basic rules first, advanced rules in linked files)
+
+### Issue: Rules become outdated as project evolves
+
+**Cause:** Codebase changes but rules don't.
+**Solution:**
+
+- Schedule periodic rule reviews (monthly or quarterly)
+- Update rules when architectural decisions change
+- Version control your rule files
+- Document rule changes in commit messages
+
+## Understanding Design System Rules
+
+Design system rules transform how AI coding agents work with your Figma designs:
+
+**Before rules:**
+
+- The agent makes assumptions about component structure
+- Inconsistent styling approaches across implementations
+- Hardcoded values that don't match design tokens
+- Components created in random locations
+- Repetitive explanations of project conventions
+
+**After rules:**
+
+- The agent automatically follows your conventions
+- Consistent component structure and styling
+- Proper use of design tokens from the start
+- Components organized correctly
+- Zero repetitive prompting
+
+The time invested in creating good rules pays off exponentially across every Figma implementation task.
+
+## Additional Resources
+
+- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server/)
+- [Figma Variables and Design Tokens](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma)

package/skills/create-design-system-rules/agents/verdent.yaml

@@ -0,0 +1,11 @@
+category: Design
+interface:
+  display_name: Design System Rules
+  short_description: Generate project-specific design system rules from Figma designs.
+  icon_dark: './assets/icon-dark.png'
+  icon_light: './assets/icon-light.png'
+  default_prompt: Create design system rules for my project.
+  label:
+    - design-system
+    - figma
+    - frontend