@rayburst/cc 3.2.6 → 3.4.0

package/skills/design-tokens/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: rb:extract-tokens
+description: |
+  Analyze all designs across the organization's feature atlas, discover repeating CSS values,
+  and propose centralized design tokens. Creates approved tokens and auto-links them to designs.
+  Triggers: "extract tokens", "rb extract tokens", "discover tokens", "find design tokens", "tokenize designs".
+user-invocable: true
+---
+
+# rb:extract-tokens — Extract Design Tokens from Existing Designs
+
+Scans all feature designs in the organization, identifies repeating CSS values (colors, spacing,
+typography, etc.), and proposes them as centralized design tokens. Approved tokens are created
+and linked to the designs that use them.
+
+## MCP Tool Prefix
+
+All MCP tools use: `mcp__plugin_rayburst_rayburst__`
+
+---
+
+## CRITICAL RULES
+
+1. **Never create tokens without user approval** — always present the full list of suggestions and wait for the user to confirm which ones to create.
+2. **Minimum threshold: 2+ usages** — only propose values that appear in at least 2 different designs.
+3. **Don't duplicate existing tokens** — always check `rb_list_design_tokens` first and skip values that already have a centralized token.
+4. **Auto-categorize accurately** — use the regex rules in Step 3 to assign the correct category.
+
+---
+
+## Workflow
+
+### Step 1: Gather all designs
+
+1. Call `rb_list_features` with a broad search (empty string) to get all features.
+2. For each feature, call `rb_list_designs` to get design metadata.
+3. For each design that has `toonContent`, call `rb_get_design` to fetch the full design data.
+4. Also call `rb_list_design_tokens` to get existing centralized tokens.
+
+**Rate limit note**: Batch API calls in groups of 4-5 to stay within the 60 req/min limit.
+
+---
+
+### Step 2: Collect all CSS values
+
+For each fetched design, collect values from:
+- `designTokens` — all values from the key-value pairs
+- `cssProperties` — all values from the CSS rule declarations (decode TOON if needed)
+
+Build a frequency map: `Map<normalizedValue, { count: number, designs: Set<designId>, properties: Set<cssPropertyName> }>`.
+
+Normalize values by:
+- Trimming whitespace
+- Lowercasing hex colors (e.g. `#3B82F6` → `#3b82f6`)
+- Normalizing rgb/rgba spacing (e.g. `rgb( 255, 255, 255 )` → `rgb(255, 255, 255)`)
+
+---
+
+### Step 3: Auto-categorize and name suggestions
+
+For each value appearing 2+ times, auto-categorize:
+
+| Pattern | Category | Name suggestion |
+|---------|----------|----------------|
+| `#hex`, `rgb(...)`, `rgba(...)`, `hsl(...)`, `oklch(...)` | `color` | `color.<semantic-hint>` |
+| `Npx`, `Nrem`, `Nem`, `N%` (for padding, margin, gap) | `spacing` | `spacing.<size>` |
+| Font family strings, `Npx`/`Nrem` font-size, font-weight numbers | `typography` | `typography.<role>` |
+| `Npx` border-width, border-radius values | `border` | `border.<property>` |
+| `box-shadow` values | `shadow` | `shadow.<level>` |
+| `0.N` opacity values | `opacity` | `opacity.<level>` |
+| Everything else | `other` | `other.<name>` |
+
+For name suggestions, try to infer semantic meaning:
+- If the CSS property name gives a clue (e.g. `background-color` → `color.bg`, `font-size` → `typography.size`)
+- Use size labels: `xs`, `sm`, `md`, `lg`, `xl` based on relative values
+- For colors, try to identify role: `primary`, `secondary`, `surface`, `text`, `border`
+
+---
+
+### Step 4: Filter and present suggestions
+
+1. Remove values that already match an existing centralized token (by exact value match).
+2. Sort suggestions by usage count (highest first).
+3. Present to the user in a clear table:
+
+```
+Found N repeating values across M designs:
+
+ # | Name (suggested)      | Category   | Value        | Used in
+---|-----------------------|------------|--------------|--------
+ 1 | color.primary         | color      | #3b82f6      | 5 designs
+ 2 | spacing.md            | spacing    | 16px         | 4 designs
+ 3 | typography.body.size  | typography | 14px         | 3 designs
+ ...
+
+Which tokens would you like to create? (e.g. "1,2,3" or "all" or "none")
+```
+
+---
+
+### Step 5: Create approved tokens and link designs
+
+For each approved suggestion:
+
+1. Call `rb_create_design_token` with the name, category, value, and a description like "Auto-extracted from N designs".
+2. For each design that uses this value, call `rb_link_design_token` with the design ID, token ID, and the CSS property name.
+
+---
+
+### Step 6: Report
+
+Output a summary:
+
+```
+✅ Created N design tokens, linked to M designs.
+
+Created tokens:
+- color.primary (#3b82f6) — linked to 5 designs
+- spacing.md (16px) — linked to 4 designs
+- ...
+
+View your design system at: /features/design-system
+```
+
+---
+
+## Constraints
+
+- Stay within the 60 req/min MCP rate limit — batch calls in groups of 4-5.
+- For large organizations with many features/designs, process in batches and show progress.
+- If no repeating values are found, say so: "No repeating CSS values found across designs. Create tokens manually via /features/design-system or rb_create_design_token."

package/skills/designs/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: rb:capture-design
+description: |
+  Capture the visual design of a feature's UI component from source code and save it
+  as a TOON-encoded design in the Rayburst feature atlas.
+  Triggers: "capture design", "rb capture design", "save design", "snapshot design", "add design to feature".
+user-invocable: true
+---
+
+# rb:capture-design — Capture Component Design from Code
+
+Reads a UI component's source code, builds a structured design representation in TOON format,
+and saves it to the feature's Designs tab via `create_design`.
+
+## MCP Tool Prefix
+
+All MCP tools use: `mcp__plugin_rayburst_rayburst__`
+
+---
+
+## CRITICAL RULES
+
+1. **Never invent visual data** — only encode what is explicitly present in the source code (CSS classes, inline styles, Tailwind classes, CSS variables). If a value is computed at runtime, note it as `"dynamic"`.
+2. **Always confirm the feature** before creating the design — ask the user if unsure which feature this component belongs to.
+3. **Source is "code-analysis"** — always set `source: "code-analysis"` when calling `rb_create_design`.
+4. **TOON encoding** — encode the design data object using `@toon-format/toon`'s `encode()` function before saving as `toonContent`.
+
+---
+
+## Workflow
+
+### Step 1: Identify the feature and component
+
+If the user specified a component file path and/or feature, use those directly.
+Otherwise:
+1. Ask the user: "Which component or UI area do you want to capture?"
+2. Call `rb_list_features` to find the matching feature.
+3. Confirm with the user: "I'll capture the design for feature **[title]** from `[file path]`. Proceed?"
+
+---
+
+### Step 2: Read the component source
+
+Read the component file(s). Extract:
+- **Element structure**: HTML/JSX element types, nesting, key classNames
+- **CSS properties**: All Tailwind classes, inline styles, CSS variables resolved to their values where possible
+- **Layout**: flex/grid direction, gap, padding, margin, width, height
+- **Typography**: font-size, font-weight, font-family, line-height, color
+- **Visual**: background, border, border-radius, box-shadow, opacity
+- **States**: hover, focus, active, disabled variants (from Tailwind or CSS)
+
+---
+
+### Step 3: Build the design data object
+
+Construct a JavaScript object with this shape:
+
+```javascript
+const designData = {
+  name: "<ComponentName> — <FeatureTitle>",  // e.g. "Tab Bar — Page Tab Bar"
+  componentTree: {
+    type: "div",  // root element type — MUST be a real HTML tag (div, span, button, etc.)
+                  // or a PascalCase React component name. Never use Figma types.
+    className: "<classes>",
+    children: [
+      { type: "button", className: "<classes>", variant: "active", children: [] },
+      { type: "button", className: "<classes>", variant: "inactive", children: [] },
+    ]
+  },
+  cssProperties: {
+    // Styles grouped by selector or variant
+    ".tab-active": { background: "rgba(255,255,255,0.15)", color: "#fff", borderRadius: "9999px", padding: "8px 36px" },
+    ".tab-inactive": { color: "rgba(255,255,255,0.6)", padding: "8px 36px" },
+  },
+  designTokens: {
+    // CSS variables or design tokens resolved to values
+    // e.g. "--color-primary": "#3b82f6"
+  }
+}
+```
+
+Then encode as TOON using the `ctx_execute` MCP tool (context-mode) or equivalent:
+```javascript
+import { encode } from '@toon-format/toon'
+const toonContent = encode(designData)
+```
+
+---
+
+### Step 4: Save the design
+
+Call `rb_create_design` with:
+```
+featureId:      <feature UUID>
+name:           "<ComponentName> — <FeatureTitle>"
+source:         "code-analysis"
+componentTree:  <componentTree object>
+cssProperties:  <cssProperties object>
+designTokens:   <designTokens object>
+toonContent:    <encoded TOON string>
+```
+
+---
+
+### Step 4.5: Link centralized design tokens
+
+After saving the design, automatically link any matching centralized tokens:
+
+1. Call `rb_list_design_tokens` to fetch all org-level design tokens.
+2. For each centralized token, check if its `value` appears anywhere in the design's `cssProperties` or `designTokens`.
+3. For each match, call `rb_link_design_token` with the `designId`, `tokenId`, and the matching `cssProperty` name.
+4. Track counts: how many existing tokens were linked, and how many repeated CSS values could become new tokens (values appearing in the design that aren't yet centralized).
+
+---
+
+### Step 5: Confirm
+
+After successful creation, output:
+```
+✅ Design captured: "<name>"
+Feature: <feature title> (<featureId>)
+Design ID: <designId>
+
+Linked N centralized tokens.
+M CSS values could become new design tokens — run /rb:extract-tokens to review.
+
+The design is now visible in the Designs tab of the feature.
+To update it later, run /rb:capture-design again or use rb_update_design.
+```
+
+---
+
+## Constraints
+
+- Only extract styles statically present in source — do not hallucinate values.
+- If the component uses Tailwind, resolve class names to actual CSS values where known (e.g. `bg-blue-500` → `#3b82f6`).
+- If multiple variants exist (e.g. active/inactive tabs), capture all variants in `componentTree` and `cssProperties`.
+- `componentTree.type` MUST be a real HTML tag (`div`, `span`, `button`, `img`, `input`, etc.) or a PascalCase React component name — never Figma node types (`frame`, `text`, `group`, `rectangle`).

package/skills/review/SKILL.md

@@ -24,7 +24,7 @@ All MCP tools use: `mcp__plugin_rayburst_rayburst__`
 1. **One change per AskUserQuestion prompt** — never batch multiple proposals together.
 2. **Never apply a change without user approval** — every write, update, or delete requires an explicit "Apply" answer.
 3. **Never delete a feature or criterion** that the user skips — move immediately to the next proposal.
-4. **Present proposals in this order**: deletions first (highest impact), then updates, then additions.
+4. **Present proposals in this order**: deletions first (highest impact), then updates, then additions, then visual migrations (🎨 MIGRATE) last.
 
 ---
 
@@ -35,6 +35,7 @@ All MCP tools use: `mcp__plugin_rayburst_rayburst__`
 | 🗑️     | DELETE (red)     | Removing a feature or criterion              |
 | ✏️     | UPDATE (yellow)  | Changing description, title, or status       |
 | ➕     | ADD (green)      | Adding a new criterion to an existing feature|
+| 🎨     | MIGRATE (purple) | Visual criterion that belongs in Designs     |
 | ℹ️     | INFO (blue)      | Context shown to the user, no action needed  |
 
 Always prefix the AskUserQuestion `question` text with the relevant icon and a short action label in CAPS, e.g.:
@@ -140,6 +141,22 @@ NEW CRITERION:
 Reason: <one-line explanation of the behavior being captured>
 ```
 
+**🎨 MIGRATE — Visual criterion (belongs in Designs)**
+A criterion that describes appearance rather than behavior — e.g. it mentions colors, spacing,
+font sizes, border radii, shadows, animation durations, or layout measurements.
+These belong in feature Designs (TOON-encoded snapshots), not acceptance criteria.
+Propose deleting the criterion and remind the user to run /rb:capture-design to capture the
+appearance instead.
+
+*Preview format:*
+```
+Feature: "<title>"
+Criterion (visual — should be a Design):
+  "<criterion description>"
+
+Reason: Describes appearance, not behavior. Run /rb:capture-design to capture the visual design.
+```
+
 ---
 
 ### Step 3: Present Changes One at a Time
@@ -162,7 +179,8 @@ For each item in the change queue, call **AskUserQuestion** with:
 
 - If **Apply** → execute the appropriate MCP call (`rb_update_feature`, `rb_update_criterion`,
   `rb_add_criterion`, `rb_delete_criterion`, `rb_delete_feature`) and confirm success with a
-  one-line acknowledgement before presenting the next change.
+  one-line acknowledgement before presenting the next change. For 🎨 MIGRATE proposals, use
+  `rb_delete_criterion` and remind the user to run /rb:capture-design.
 - If **Skip** → acknowledge with a one-line "Skipped." and immediately present the next change.
 
 ---