@se-studio/skills 1.0.5 → 1.0.11

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @se-studio/skills
 
+## 1.0.11
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.10
+
+### Patch Changes
+
+- Add site-workflows-contentful-vercel-setup skill
+
+## 1.0.9
+
+### Patch Changes
+
+- Add site-workflows-copy-doc-snapshot skill
+- Add site-workflows-new-project skill
+- Add site-workflows-project-cleanup skill
+
+## 1.0.8
+
+### Patch Changes
+
+- Add site-workflows-apply-design-snapshot skill
+
+## 1.0.7
+
+### Patch Changes
+
+- Add site-workflows-figma-design-snapshot skill
+
+## 1.0.6
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
 ## 1.0.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.0.5",
+  "version": "1.0.11",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",

package/skills/contentful-cms-setup/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: "contentful-cms:setup"
+description: "Guide a user through installing and configuring the cms-edit MCP server for Claude Desktop."
+---
+
+# Skill: cms-edit Setup
+
+Use this skill when the user wants to install or configure the `cms-edit` MCP server so Claude Desktop can read and edit Contentful content.
+
+## Overview
+
+The setup wizard handles everything automatically:
+- Collects the Contentful Management Token
+- Discovers spaces and environments via the Contentful API
+- Writes `~/.contentful-cms.json`
+- Updates the Claude Desktop config to register the `cms-edit` MCP server
+
+## Prerequisites
+
+The user needs:
+1. **Node.js** installed (LTS version from [nodejs.org](https://nodejs.org))
+2. **A Contentful Management Token** — see Step 1 below
+
+## Step 1: Get a Management Token
+
+Tell the user:
+
+> To get your Contentful Management Token:
+> 1. Log in to [contentful.com](https://app.contentful.com)
+> 2. Go to **Settings → API keys**
+> 3. Click the **Content management tokens** tab
+> 4. Click **Generate personal token**, name it `Claude Desktop`, and click **Generate**
+> 5. Copy the token — you won't see it again
+
+Ask them to confirm they have the token before continuing.
+
+## Step 2: Run the Setup Wizard
+
+Tell the user to open a terminal and run:
+
+```bash
+npx @se-studio/contentful-cms@latest setup
+```
+
+Walk them through what each prompt means:
+
+| Prompt | What to enter |
+|--------|--------------|
+| **Contentful Management Token** | The token they just copied (input will be hidden) |
+| **Which Contentful space?** | Only appears if the token has multiple spaces — pick the one they want to connect |
+| **Which environment?** | Auto-selects `master`; only asks if no `master` environment exists |
+| **Short name for this project** | A slug like `my-project` or `om1` — used as the key in the config file |
+| **Staging site URL** | Optional — their Vercel preview URL (e.g. `https://my-project.vercel.app`) |
+| **Vercel bypass token** | Optional — only if their staging site has deployment protection |
+
+## Step 3: Restart Claude Desktop
+
+After the wizard completes, tell the user:
+
+> Fully quit Claude Desktop and reopen it.
+> - **Mac:** Right-click the Dock icon → **Quit** (closing the window isn't enough)
+> - **Windows/Linux:** Close and reopen from the Start menu
+
+## Step 4: Verify
+
+Once they've reopened Claude Desktop, verify the setup worked by using the `cms_edit` tool:
+
+```
+cms_edit ["open", "/"]
+```
+
+If it returns a page structure, setup is complete. If it errors, see Troubleshooting below.
+
+## Troubleshooting
+
+**"Invalid management token"**
+→ The token may have been copied incorrectly or already expired. Generate a new one in Contentful and run the wizard again.
+
+**"No spaces found"**
+→ The token doesn't have access to any spaces. Check Contentful's token permissions — it needs at least read access to one space.
+
+**`cms_edit` tool not available after restart**
+→ Check the Claude Desktop config was written correctly:
+- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+It should contain an `mcpServers.cms-edit` entry. If missing, run the wizard again.
+
+**Adding another space**
+→ Run `npx @se-studio/contentful-cms@latest setup` again — it merges the new space into the existing config.

package/skills/site-workflows-apply-design-snapshot/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: site-workflows-apply-design-snapshot
+description: Reads design.md and applies the design tokens to the project — updating tailwind.config.json (colours + typography), handling custom fonts, and regenerating all downstream files via pnpm codegen. Run after /figma-design-snapshot to sync the codebase with the latest Figma changes.
+license: MIT
+metadata:
+  author: se-studio
+  version: "1.0.0"
+---
+
+# Apply Design Snapshot
+
+Reads `design.md` and applies its design tokens to the project. Run this after `/figma-design-snapshot` to keep the codebase in sync with Figma.
+
+## Usage
+
+```
+/apply-design-snapshot
+```
+
+No arguments needed. Reads `design.md` and `.design-snapshot.json` from the project root, updates `tailwind.config.json` and `globals.css`, then runs `pnpm codegen` to regenerate all typed token files.
+
+---
+
+## CRITICAL: The token pipeline
+
+```
+tailwind.config.json
+       ↓  pnpm codegen
+src/generated/colors.ts        ← typed colour lookups (auto-generated)
+src/generated/textStyles.ts    ← typed type-scale names (auto-generated)
+src/generated/setailwind.css   ← CSS custom properties + utilities (auto-generated)
+```
+
+**Never edit files in `src/generated/` directly** — they are always overwritten by `codegen`. Only edit `tailwind.config.json` and `globals.css`.
+
+---
+
+## Step 1 — Check prerequisites
+
+1. Check that `design.md` exists in the project root (or at `outputPath` from `.design-snapshot.json`).
+   - If missing: stop and tell the user to run `/figma-design-snapshot` first.
+2. Check that `tailwind.config.json` exists.
+   - If missing: stop and tell the user this skill requires the SE Studio token pipeline.
+
+---
+
+## Step 2 — Parse design.md
+
+Read `design.md` and extract:
+
+### Colours
+Find the `## Colour Palette` section. For every table row matching `| Token | Hex |`, extract the token name and hex value. Ignore swatch columns. Collect all colours regardless of group (Primary / Neutral / etc.).
+
+### Typography
+Find `## Typography`. Extract the **Desktop** table (lines under `### Desktop`) and the **Mobile** table (lines under `### Mobile`). For each row capture: style name, size (strip `px`), weight label, line-height, letter-spacing.
+
+Weight label → number mapping:
+- Regular → 400
+- Medium → 500
+- SemiBold → 600
+- Bold → 700
+
+Letter-spacing conversion (Figma `%` → CSS `em`): divide by 100. e.g. `−1.3%` → `-0.013em`. If the value is `0` keep it as `0`.
+
+Line-height conversion: strip `%` and divide by 100. e.g. `120%` → `1.2`. If already a decimal, keep as-is. If in `px`, keep as the px value.
+
+### Font family
+Find `**Font family:**` in the Typography section. Extract the font name (e.g. `Booton-TRIAL`).
+
+### Breakpoints
+Find `## Breakpoints & Canvas`. Extract rows — identify the desktop canvas width (largest) and mobile canvas width (smallest).
+
+---
+
+## Step 3 — Read current tailwind.config.json
+
+Read `tailwind.config.json` in full. Record:
+- `colorOptions` — the current colour map (must preserve all existing keys)
+- `fontTable.font` — the current font family string
+- `fontTable.weight` — the base font weight
+- `fontTable.styles` — the current style map (keys are class names used in the codebase — **never rename or remove them**)
+- `colorOpposites` — existing colour contrast pairs
+- `foregroundColors` — existing foreground colour list
+- `colorFile` — keep unchanged
+
+---
+
+## Step 4 — Ask about fonts
+
+Before modifying any file, ask the user this question (use `AskUserQuestion`):
+
+> The design uses **[font name from design.md]** (Regular 400, Medium 500, SemiBold 600).
+>
+> How should I handle the font?
+>
+> **A)** I have the font files — tell me the path (relative to project root or absolute) and I'll copy them to `public/fonts/` and wire up `@font-face`.
+> **B)** I don't have the files yet — set up placeholder `@font-face` rules so I can drop files in later.
+> **C)** Skip fonts — only update colours and type sizes.
+
+Wait for the answer. Record as `fontStrategy` (A / B / C). If A, also record `fontSourcePath` from their reply.
+
+---
+
+## Step 5 — Build the colour patch
+
+Construct the updated `colorOptions` object:
+
+1. **Start with all existing entries** exactly as they are. The `Light` and `Dark` keys are especially critical — they feed `lookupColourString()`, `lookupOpposite()`, and `lookupColourClassNames()` throughout the component system.
+
+2. **Add new entries** from design.md. Skip any name that already exists (case-insensitive match). Use the exact name string from design.md as the key (the codegen tool kebab-cases it for CSS variables automatically).
+
+3. **Compute colour opposites** for each new colour using WCAG relative luminance:
+   1. Parse the hex value into R, G, B as integers 0–255, then normalise to 0–1 by dividing by 255.
+   2. Linearise each channel: if c ≤ 0.03928 → `c / 12.92`, else `((c + 0.055) / 1.055) ^ 2.4`.
+   3. Compute luminance: `L = 0.2126·R + 0.7152·G + 0.0722·B`.
+   4. If `L ≤ 0.179` → the colour is dark; opposite is `"Light"` (white/light text will be legible).
+      If `L > 0.179` → the colour is light; opposite is `"Dark"` (dark text will be legible).
+
+4. **Show the user** the full list of colours being added (name + hex + computed opposite) before writing anything. Ask them to confirm or correct any pairs.
+
+---
+
+## Step 6 — Build the typography patch
+
+Map Figma's style names to the existing project class names using this table. The left column is how the style appears in design.md; the right is the `fontTable.styles` key to update in `tailwind.config.json`.
+
+| design.md style | tailwind.config.json key |
+|---|---|
+| H1 (Desktop) | `h1` |
+| H2 (Desktop) | `h2` |
+| H3 (Desktop) | `h3` |
+| H4 (Desktop) | `h4` |
+| P1 (Desktop) | `p1` |
+| P2 (Desktop) | `p2` |
+| P3 (Desktop) | `p3` |
+| P4 (Desktop) | `p3Med` |
+| Button 1 (Desktop) | `large-button` |
+
+> **Note:** If your project uses different `fontTable.styles` keys, adjust the right-hand column to match what is in your `tailwind.config.json`. Keys not present in the table are left exactly as-is.
+
+For each mapped style, construct the updated `fontTable.styles` entry following these rules:
+
+- `"default"` = the **Mobile** size for that style (from the Mobile table in design.md)
+- `"desktop"` = the **Desktop** size (only include if it differs from `"default"`)
+- `"weight"` = only include when the weight is not the base `fontTable.weight` (typically 400)
+- `"lineHeight"` = converted value (see Step 2 conversion rules)
+- `"letterSpacing"` = converted value (see Step 2 conversion rules); omit if `0`
+- `"additional"` = **preserve exactly** from the existing entry (e.g. `text-transform: uppercase` on `h1`) — do not remove it
+- Style keys not in the mapping table above (e.g. `hHome`, `h2Med`, `h2plus`, `nav`, etc.) → **leave completely unchanged**
+
+Example output for `h2`:
+```json
+"h2": {
+  "weight": 500,
+  "letterSpacing": "-0.013em",
+  "lineHeight": 1.2,
+  "default": 40,
+  "desktop": 51
+}
+```
+
+---
+
+## Step 7 — Build the font patch
+
+### Strategy A — font files provided
+
+1. List all font files at `fontSourcePath` matching `*.woff2`, `*.woff`, `*.ttf`, `*.otf`.
+2. Create `public/fonts/` if it does not exist.
+3. Copy all matched files into `public/fonts/`.
+4. For each file, infer the face weight from the filename:
+   - Filename contains `Regular` or `400` → weight: 400, style: normal
+   - Contains `Medium` or `500` → weight: 500, style: normal
+   - Contains `SemiBold` or `Semi` or `600` → weight: 600, style: normal
+   - Contains `Bold` or `700` → weight: 700, style: normal
+   - Contains `Italic` → add `font-style: italic` alongside the matching weight
+5. Build `@font-face` blocks — prefer `woff2` format; fall back to `woff` then `ttf`.
+6. Insert the `@font-face` blocks into `globals.css` **before** the `@import "tailwindcss"` line (font declarations must precede Tailwind).
+7. Update `tailwind.config.json` → `fontTable.font` to the font family name from design.md.
+8. Update `globals.css` `@theme` block: replace the `--font-sans` value with `"[FontName]", system-ui, ui-sans-serif, sans-serif`.
+
+### Strategy B — placeholder
+
+1. Add the following block to `globals.css` before the `@import "tailwindcss"` line:
+
+```css
+/* TODO: Replace src with actual font files placed in public/fonts/ */
+@font-face {
+  font-family: "[FontName]";
+  src: local("[FontName]");
+  font-weight: 400;
+  font-style: normal;
+  font-display: swap;
+}
+@font-face {
+  font-family: "[FontName]";
+  src: local("[FontName]");
+  font-weight: 500;
+  font-style: normal;
+  font-display: swap;
+}
+@font-face {
+  font-family: "[FontName]";
+  src: local("[FontName]");
+  font-weight: 600;
+  font-style: normal;
+  font-display: swap;
+}
+```
+
+2. Update `tailwind.config.json` → `fontTable.font` to the font family name.
+3. Update `globals.css` `--font-sans` to `"[FontName]", system-ui, ui-sans-serif, sans-serif`.
+4. After writing, tell the user: *"Place your font files in `public/fonts/` and replace each `src: local(...)` line with `src: url('/fonts/YourFile.woff2') format('woff2')`."*
+
+### Strategy C — skip
+
+No font changes. Skip this step entirely.
+
+---
+
+## Step 8 — Apply all changes
+
+Write files in this order:
+
+1. **`tailwind.config.json`** — merge in the new `colorOptions`, updated `colorOpposites`, and updated `fontTable.styles`. All other fields (`sizes`, `colorFile`, `foregroundColors`, etc.) must be preserved exactly.
+2. **`src/app/globals.css`** — apply font changes (strategies A or B only).
+3. **`public/fonts/`** — copy font files (strategy A only).
+
+Before writing `tailwind.config.json`, do a final sanity check:
+- `Light` and `Dark` keys still present with their original hex values
+- No existing `fontTable.styles` keys removed
+- JSON is valid
+
+---
+
+## Step 9 — Regenerate
+
+```bash
+pnpm codegen
+```
+
+If this fails:
+- Show the error output
+- Diagnose the likely cause (invalid JSON in tailwind.config.json, unknown field, etc.)
+- Suggest a fix
+- Do NOT run `pnpm validate` until codegen succeeds
+
+---
+
+## Step 10 — Validate
+
+```bash
+pnpm validate
+```
+
+This runs Biome lint + TypeScript type-check. Report pass or fail. If it fails, show the errors.
+
+---
+
+## Step 11 — Report to user
+
+Summarise what happened:
+
+```
+✓ Colours added: [N] new colours (list names)
+✓ Typography updated: [list of class names updated]
+✓ Font: [registered as FontName / placeholder set up / skipped]
+✓ pnpm codegen: passed
+✓ pnpm validate: passed  (or: ✗ failed — see errors above)
+
+Next steps:
+  git diff tailwind.config.json   ← review the token changes
+  git diff src/app/globals.css    ← review font changes
+  git add -p && git commit -m "design: apply snapshot YYYY-MM-DD"
+```
+
+---
+
+## What this skill does NOT touch
+
+- `design.md` — read-only input, never modified
+- `.design-snapshot.json` — read-only config
+- `src/generated/*` — auto-regenerated by codegen, never edited directly
+- Any files in `src/project/` — components are not updated; only tokens change
+- Existing `fontTable.styles` keys not in the mapping table — left exactly as-is