@se-studio/skills 1.0.6 → 1.0.12

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @se-studio/skills
 
+## 1.0.12
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 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

package/package.json

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

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

@@ -130,7 +130,7 @@ cms-edit set @root items <id1>,<id2>,<id3> --links
 
 **Rich text fields** (body, additionalCopy):
 ```bash
-printf '## Why it matters\n\nOur platform helps teams **move faster** with [confidence](https://example.com).\n\n- Instant setup\n- No code required\n- 99.9%% uptime\n' | cms-edit rtf @c1 body -
+printf '## Why it matters\n\nOur platform helps teams **move faster** with [confidence](https://example.com).\n\n- Instant setup\n- No code required\n- 99.9%% uptime\n' | cms-edit rtf @c1 body --markdown -
 ```
 
 Markdown support:
@@ -146,17 +146,17 @@ For any content with multiple paragraphs or newlines, use `printf` piped to stdi
 
 ```bash
 # Correct — printf interprets \n properly
-printf '## Why it matters\n\nOur platform helps teams **move faster**.\n\n- Instant setup\n- No code required\n' | cms-edit rtf @c1 body -
+printf '## Why it matters\n\nOur platform helps teams **move faster**.\n\n- Instant setup\n- No code required\n' | cms-edit rtf @c1 body --markdown -
 
 # Also correct — file input
-cms-edit rtf @c1 body --file path/to/file.md
-cms-edit rtf @c1 body - < path/to/file.md
+cms-edit rtf @c1 body --markdown --file path/to/file.md
+cms-edit rtf @c1 body --markdown - < path/to/file.md
 ```
 
 Single-line content (no newlines) can be passed as a quoted argument directly:
 
 ```bash
-cms-edit rtf @c1 body "Simple single-paragraph body text with **bold**."
+cms-edit rtf @c1 body --markdown "Simple single-paragraph body text with **bold**."
 ```
 
 **Surgical rich text replace** (compliance / quidget tokens — does not re-import the whole field):
@@ -237,7 +237,7 @@ Same as Component plus:
 When adding body content and a CTA (e.g. PDF download) to an article:
 
 1. `cms-edit open <article-slug>` (or `open <id> --id`)
-2. Set body: `cms-edit rtf @<ref> body "..."` or `--file path/to.md`. If you need to add a body component first, use `add` then `rtf`.
+2. Set body: `cms-edit rtf @<ref> body --markdown "..."` or `--markdown --file path/to.md`. If you need to add a body component first, use `add` then `rtf`.
 3. `cms-edit add CTA --target bottomContent`
 4. Set CTA links: use `--type external --label "Download PDF" --href <url>` for an external PDF URL, or `--type download --label "Download PDF" --asset-id <asset-id>` for a Contentful asset (get the ID from `cms-edit asset search "..."` or `asset info <id>`).
 5. `cms-edit save`
@@ -442,7 +442,7 @@ cms-edit read @c0
 cms-edit set @c0 heading "We build for the future"
 
 # 5. Update the body copy (use printf for multiline content)
-printf '## Our mission\n\nWe help companies **ship faster** and _smarter_.\n\n- Founded in 2018\n- 500+ clients\n- [Join us](/careers)\n' | cms-edit rtf @c0 body -
+printf '## Our mission\n\nWe help companies **ship faster** and _smarter_.\n\n- Founded in 2018\n- 500+ clients\n- [Join us](/careers)\n' | cms-edit rtf @c0 body --markdown -
 
 # 6. Review
 cms-edit diff
@@ -469,7 +469,7 @@ cms-edit open /products
 cms-edit types component  # discover what's available
 cms-edit add CTA --after @c3
 cms-edit set @c4 heading "Ready to get started?"
-cms-edit rtf @c4 body "Join thousands of teams who trust us."
+cms-edit rtf @c4 body --markdown "Join thousands of teams who trust us."
 cms-edit links add @c4 --type external --label "Start free trial" --href https://app.example.com
 cms-edit save
 ```
@@ -763,7 +763,7 @@ cat page.json | cms-edit create from-json             # Pipe from stdin
 - Any component entry in `components` or `items` may use `{ existingId }` to link an existing entry instead of creating a new one.
 - The same applies to `links` entries — use `{ existingId }` to attach an existing link entry.
 - `cmsLabel` sets the human-readable label shown in Contentful's entry list. Defaults to `type` or `contentType` if omitted. **Always set `cmsLabel` on components when a page has multiple instances of the same type** (e.g. three CTAs) — editors need to distinguish them.
-- String `fields` values are converted to Contentful rich text when they match the Markdown heuristic: contains `\n\n` or `**` or `_`, starts with `#`, starts with `- `, or starts with `> ` (blockquote with a space). **Plain single-line text with none of those patterns is not converted** — for RichText fields, add `\n\n` or a heading line, or use `cms-edit rtf` afterwards.
+- String `fields` values become Rich Text when they auto-detect as Markdown (same heuristic), HTML (tag-like), or Rich Text JSON (`nodeType: document`). Otherwise strings stay as-is — use `{ "value": "…", "format": "text"|"markdown"|"html"|"json" }` or `cms-edit rtf` with `--text|--markdown|--html|--json`.
 - `target` sets which content array to use: `topContent`, `content` (default), or `bottomContent`.
 - Slugs must not have a trailing slash — `from-json` strips it with a warning, but avoid it in source JSON.
 - All entries are created as **drafts**. A human must publish in Contentful.

package/skills/contentful-cms-rich-text/SKILL.md

@@ -9,10 +9,10 @@ Use this skill when editing **rich text** fields (body, additionalCopy) and inse
 
 ## Rich text (rtf)
 
-- **Replace** body with Markdown (single paragraph, no newlines): `cms-edit rtf @c1 body "Simple body with **bold** and [link](https://example.com)."`
+- **Replace** body with Markdown (single paragraph, no newlines): `cms-edit rtf @c1 body --markdown "Simple body with **bold** and [link](https://example.com)."`
 - **Multiline content** — use `printf` piped to stdin; `\n` in a double-quoted shell string is **not** a newline in bash:
   ```bash
-  printf '## Heading\n\nParagraph with **bold** and [link](https://example.com).\n' | cms-edit rtf @c1 body -
+  printf '## Heading\n\nParagraph with **bold** and [link](https://example.com).\n' | cms-edit rtf @c1 body --markdown -
   ```
 - Use `--file path/to/file.md` or stdin (`-`) for long content.
 - Markdown supported: headings, bold/italic, links, lists, blockquote, inline code, `---`.
@@ -86,7 +86,7 @@ Add `--dry-run` to count matches without writing.
 Replace an entire rich text field by piping Markdown from stdin. Avoids shell quoting issues for long content.
 
 ```bash
-echo "## New heading\n\nNew body text." | cms-edit rtf edit @c1 body
+echo "## New heading\n\nNew body text." | cms-edit rtf edit @c1 body --markdown
 ```
 
 In human (interactive) mode, the command prints the current Markdown to stdout first, then reads the replacement from stdin.

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