@se-studio/skills 1.0.6 → 1.0.11

package/skills/site-workflows-copy-doc-snapshot/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: site-workflows-copy-doc-snapshot
+description: Syncs content/copy/*.md files from the Google Docs copy document. Run whenever the copy doc is updated to pull changes into git. Produces a diff-friendly merge — CMS annotations and sync-to-CMS state are never touched.
+license: MIT
+metadata:
+  author: se-studio
+  version: "1.0.0"
+---
+
+# Copy Doc Snapshot
+
+Pulls the current state of the Google Docs copy document and merges it into the local `content/copy/*.md` files. Running the skill twice with no doc changes produces no diff — only real copy edits show up in git.
+
+## Usage
+
+```
+/copy-doc-snapshot
+```
+
+No arguments — reads config from `.copy-doc-sync.json` in the project root.
+
+---
+
+## Step 1 — Read config
+
+Read `.copy-doc-sync.json` from the project root. Shape:
+
+```json
+{
+  "googleDocId": "...",
+  "outputDir": "content/copy",
+  "pages": {
+    "Homepage": { "file": "homepage.md", "slug": "/", "title": "Site Homepage" }
+  }
+}
+```
+
+If the file does not exist, stop and tell the user: "`.copy-doc-sync.json` not found. Create it in the project root with a `googleDocId` and `pages` map."
+
+---
+
+## Step 2 — Fetch the Google Doc
+
+Call `mcp__claude_ai_Google_Drive__read_file_content` with `fileId` set to `googleDocId` from config.
+
+If the call fails, stop immediately — do not proceed with stale or partial data. Report the error.
+
+Store the full document text as `docText`.
+
+---
+
+## Step 3 — Parse the doc into pages and sections
+
+The Google Docs MCP returns the document as markdown-like plain text. The structure uses:
+
+- `# Page Name` — H1 line = page boundary. The text after `#` is the page name.
+- `**Section Name**` — A standalone bold line (nothing before or after the `**...**` on the line) = component/section heading.
+- `**Field:** value` or `**Field:**` (labeled line) — field label. Value follows on the same line or on the next non-empty line.
+- Plain text lines after a `**Copy:**` or `**Header:**` label = field value content.
+- `\[placeholder\]` and `TBC` in field values = content not yet confirmed.
+
+**Stop processing at `# Current website copy`** — everything from that H1 onwards is reference material and must be ignored.
+
+### Parsing pass
+
+Split `docText` on H1 headings (`^# .+`) to get page segments. For each page segment:
+
+1. The page name is the H1 text (trimmed, without the `#`).
+2. Split the page body on standalone bold lines (`^\*\*[A-Z][^*:]+\*\*\s*$`) to get section segments.
+   - A "standalone bold line" is bold text with no other content on the same line and no colon inside it.
+3. For each section segment, extract:
+   - `name` — the bold line text (strip `**` markers)
+   - `heading` — value after `**Header:**` label (same line or next non-empty line); `null` if not present
+   - `subheading` — the first plain-text line after the heading line that is NOT a labeled field; `null` if not present. (Used to detect section-level subtitles like "Studio technology, evidence generation...")
+   - `body` — all lines between `**Copy:**` and the next labeled field or section header; joined as paragraphs
+   - `links` — all lines between `**CTAs:**` and the next labeled field or section header; one link per line
+   - `items` — if the body contains sub-section structure (nested bold names like `**Studio**`, `**Evidence**`), extract each as a sub-item with its own `name`, `subheading`, and `body`
+   - `isTBC` — `true` if the `heading` value is literally `TBC` AND the `body` is empty or also `TBC`
+
+### Recognising collection items within a section
+
+Some sections (e.g. "What We Do", "Featured Research", "From The Blog") contain multiple items structured as:
+
+```
+**Item Name**
+Subtitle line (optional)
+Body copy here.
+```
+
+Detect this pattern: after the section-level `**Header:**` and `**Copy:**`, if the body contains lines that are standalone bold (`**...**`) followed by non-bold lines, treat each bold+following-text block as a separate item with:
+- `name` = bold text
+- `subheading` = first non-bold line (if short and no verb — likely a descriptor like "Technology & software")
+- `body` = remaining non-bold lines before the next bold item
+
+---
+
+## Step 4 — For each page in config, merge doc content into the markdown file
+
+Work through each entry in `config.pages`. For each page:
+
+### 4a. Locate doc content
+
+Find the parsed page segment whose name matches the config key (case-insensitive). If not found, note it in the report as "not found in doc" and skip to the next page — do not modify the file.
+
+### 4b. Read the existing markdown file
+
+Read `{outputDir}/{file}`. If it does not exist, create a minimal stub:
+
+```markdown
+---
+slug: {slug}
+title: {title}
+description: TBC
+indexed: true
+---
+
+# {title}
+
+> Last synced from Google Docs: never
+> Last synced to CMS: never
+```
+
+Then proceed to 4c using just the doc content (no existing sections to merge with).
+
+If it does exist, parse it to identify:
+- The YAML frontmatter block (lines between first `---` pair)
+- The `> Last synced from Google Docs:` line (may be absent — treat as `never`)
+- The `> Last synced to CMS:` line
+- Each `## Section` block with its `<!-- ... -->` annotation line and all fields
+- Each `### Item` block within collections, with their `<!-- item ... -->` annotation lines
+
+### 4c. Merge doc sections into existing file structure
+
+For each `## Section` in the existing file:
+
+**Case 1 — Section found in doc (name match, case-insensitive):**
+- Update `**heading:**` with doc `heading` value (or remove the field if `null`)
+- Update `**body:**` with doc `body` text, reflowed as markdown paragraphs
+- Update `**links:**` with doc `links`, one bullet per line, preserving any `(internal: ...)` or `(external: ...)` annotations that already exist in the file for links with matching labels
+- For collection sections with items: recursively apply the same logic to each `### Item` — match by item name, update `heading`, `preHeading` (from doc `subheading`), `body`
+- **Preserve unchanged:** the `<!-- component: ... | cmsLabel: ... -->` annotation, the `<!-- item | cmsLabel: ... -->` annotations, any `**preHeading:**` fields not provided by the doc, and any `<!-- note: ... -->` lines already present
+
+**Case 2 — Section is TBC in doc (`isTBC` is true):**
+- Do NOT update any content fields — leave them exactly as they are
+- Add `<!-- note: TBC in Google Doc as of {today} -->` on the line after the `<!-- component: ... -->` annotation, but only if such a note is not already present
+
+**Case 3 — Section exists in file but is NOT in the doc:**
+- Preserve the section and all its content unchanged
+- Add `<!-- note: Not found in Google Doc as of {today} — verify still needed -->` after the section's annotation comment, but only if such a note is not already present
+- Flag this section in the report
+
+**Case 4 — Section exists in doc but NOT in the existing file:**
+- Append a new `## Section` block at the end of the file (before any Footer section) using the doc content
+- Use this annotation as placeholder: `<!-- component: Generic Component | cmsLabel: {SECTION_NAME} — {PAGE_TITLE} -->`
+- Flag this in the report as "new section — annotation needs review"
+
+### 4d. Preserve these elements unchanged in all cases
+
+- The entire YAML frontmatter block
+- `> Last synced to CMS:` line (never touch this)
+- `<!-- component: ... | cmsLabel: ... -->` annotation content
+- `<!-- item | cmsLabel: ... -->` annotation content
+- Any `<!-- note: ... -->` lines already in the file (do not duplicate them)
+- The `## Footer` section (it is reference-only and managed separately via `cms-edit nav`)
+
+### 4e. Update the sync date
+
+Get today's date: run `date -u +"%Y-%m-%d"` via Bash. Update the `> Last synced from Google Docs:` line to this date. If the line does not exist in the file, insert it immediately after the H1 heading line and before the first `---` separator.
+
+---
+
+## Step 5 — Write files
+
+For each page, compare the updated content to the file on disk. If the content is identical (character-for-character), skip writing — do not produce a noisy no-op diff.
+
+Otherwise, write the updated content to the file path. Do not reformat YAML frontmatter or alter indentation in sections that were not modified.
+
+---
+
+## Step 6 — Report
+
+After all pages are processed, print a summary in this format:
+
+```
+copy-doc-snapshot complete (YYYY-MM-DD)
+
+homepage.md     — updated: Hero body, Trusted By body
+about-us.md     — no changes (TBC in doc)
+contact-us.md   — no changes (TBC in doc)
+
+Attention needed:
+  homepage.md › Footer: not found in Google Doc — verify still needed
+  homepage.md › Services: new section in doc — annotation placeholder added, review cmsLabel
+  
+New pages in doc not in config (add to .copy-doc-sync.json to enable syncing):
+  (none)
+```
+
+If there are no attention items, omit the "Attention needed" block.
+
+Finally, suggest the commit message: `git add content/copy && git commit -m "copy: sync from Google Doc (YYYY-MM-DD)"`
+
+---
+
+## Idempotency rules
+
+Running the skill twice on the same day with no doc changes must produce identical files and an identical report:
+
+- Never include anything in file content that changes between runs except the `> Last synced from Google Docs:` date line — and that only changes once per day
+- Do not reorder sections, items, or links relative to their existing order in the file
+- Preserve exact whitespace in sections that were not modified
+- Do not add duplicate `<!-- note: ... -->` comments — check if the note already exists before inserting
+
+---
+
+## Notes
+
+- The skill **never touches** `> Last synced to CMS:` — that line is owned by the `contentful-cms-core` workflow
+- The skill **never creates** new page files unless they were already in config — a new page in the doc requires a human to add it to `.copy-doc-sync.json` with its slug
+- The `# Current website copy` section in the doc is legacy reference material — always ignore it and everything after it
+- Bold lines that are subtitles (e.g., `**Homepage copy**`) rather than section headings can be identified because they appear immediately after a page H1 and contain no matching section in the file — ignore them
+- The `.copy-doc-sync.json` config should be committed to git so any team member can regenerate the snapshot

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

@@ -0,0 +1,390 @@
+---
+name: "Figma Design Snapshot"
+description: "Regenerates design.md from Figma by extracting all design tokens, typography, and component specs. Produces a deterministic, git-diffable output — run on any day to see what designers have changed."
+metadata:
+  author: se-studio
+  version: "1.0.0"
+---
+
+# Figma Design Snapshot
+
+Regenerates `design.md` from Figma. Every run produces output in the same format and order, so `git diff design.md` shows exactly what designers changed between snapshots.
+
+## Usage
+
+```
+/site-workflows-figma-design-snapshot
+```
+
+No arguments needed — reads config from `.design-snapshot.json` in the project root.
+
+---
+
+## Step 1 — Read config
+
+Read `.design-snapshot.json` from the project root. It has this shape:
+
+```json
+{
+  "figmaFileKey": "<your-figma-file-key>",
+  "figmaPageId": "<page-node-id>",
+  "outputPath": "design.md",
+  "componentFrameIds": {
+    "Components": "<frame-node-id>"
+  }
+}
+```
+
+If the file does not exist, ask the user:
+- Figma file URL (extract `fileKey` from it)
+- Which frame on the page contains the component library (name and node ID)
+- Desired output path (default: `design.md`)
+
+Then write `.design-snapshot.json` before continuing.
+
+---
+
+## Step 2 — Extract tokens via Figma Plugin API
+
+Call `use_figma` with the `fileKey` from config and the following JavaScript. This extracts all design tokens deterministically. **Do not deviate from this script** — it produces the stable, sorted output that makes git diffs useful.
+
+```javascript
+function round1(n) { return Math.round(n * 10) / 10; }
+
+function hexFromColor(c, opacity) {
+  const hex = '#' + [c.r, c.g, c.b]
+    .map(v => Math.round(v * 255).toString(16).padStart(2, '0'))
+    .join('');
+  if (opacity !== undefined && Math.round(opacity * 100) < 100) {
+    return hex + ' / ' + Math.round(opacity * 100) + '%';
+  }
+  return hex;
+}
+
+// — Colors (sorted alphabetically by name) —
+const colors = figma.getLocalPaintStyles()
+  .map(s => {
+    const p = s.paints[0];
+    if (!p) return null;
+    return {
+      name: s.name,
+      type: p.type,
+      value: p.type === 'SOLID' ? hexFromColor(p.color, p.opacity) : p.type,
+    };
+  })
+  .filter(Boolean)
+  .sort((a, b) => a.name.localeCompare(b.name));
+
+// — Text styles (sorted alphabetically by name) —
+const typeStyles = figma.getLocalTextStyles()
+  .map(s => ({
+    name: s.name,
+    family: s.fontName.family,
+    style: s.fontName.style,
+    size: s.fontSize,
+    lineHeight: s.lineHeight.unit === 'PERCENT'
+      ? Math.round(s.lineHeight.value) + '%'
+      : s.lineHeight.unit === 'PIXELS'
+        ? round1(s.lineHeight.value) + 'px'
+        : 'AUTO',
+    letterSpacing: s.letterSpacing.unit === 'PERCENT'
+      ? round1(s.letterSpacing.value) + '%'
+      : round1(s.letterSpacing.value) + 'px',
+    textCase: s.textCase,
+  }))
+  .sort((a, b) => a.name.localeCompare(b.name));
+
+// — Variables (sorted by collection/name) —
+const varCollections = figma.variables.getLocalVariableCollections();
+const vars = figma.variables.getLocalVariables()
+  .map(v => {
+    const col = varCollections.find(vc => vc.variableIds.includes(v.id));
+    const values = {};
+    for (const [modeId, val] of Object.entries(v.valuesByMode)) {
+      const mode = col?.modes.find(m => m.modeId === modeId);
+      const key = mode?.name || modeId;
+      if (val && typeof val === 'object' && 'type' in val && val.type === 'VARIABLE_ALIAS') {
+        const ref = figma.variables.getVariableById(val.id);
+        values[key] = '→ ' + (ref?.name || val.id);
+      } else if (val && typeof val === 'object' && 'r' in val) {
+        values[key] = hexFromColor(val);
+      } else {
+        values[key] = String(val);
+      }
+    }
+    return {
+      collection: col?.name || '',
+      name: v.name,
+      type: v.resolvedType,
+      values,
+    };
+  })
+  .sort((a, b) => (a.collection + '/' + a.name).localeCompare(b.collection + '/' + b.name));
+
+// — Top-level frames on this page (sorted by name) —
+const frames = figma.currentPage.children
+  .filter(n => n.type === 'FRAME' || n.type === 'COMPONENT' || n.type === 'COMPONENT_SET')
+  .map(n => ({ id: n.id, name: n.name, width: Math.round(n.width), height: Math.round(n.height) }))
+  .sort((a, b) => a.name.localeCompare(b.name));
+
+return JSON.stringify({ colors, typeStyles, vars, frames }, null, 2);
+```
+
+Store the parsed result as `tokens`.
+
+---
+
+## Step 3 — Extract component frame properties
+
+For each entry in `componentFrameIds` from config, call `use_figma` with this script, replacing `TARGET_ID` with the frame's node ID:
+
+```javascript
+function round1(n) { return Math.round(n * 10) / 10; }
+
+function hexFromColor(c, a) {
+  const hex = '#' + [c.r, c.g, c.b]
+    .map(v => Math.round(v * 255).toString(16).padStart(2, '0'))
+    .join('');
+  return (a !== undefined && Math.round(a * 100) < 100) ? hex + ' / ' + Math.round(a * 100) + '%' : hex;
+}
+
+function extractLayout(node) {
+  const out = {
+    id: node.id,
+    name: node.name,
+    type: node.type,
+    width: round1(node.width),
+    height: round1(node.height),
+  };
+
+  // Border radius
+  if (typeof node.cornerRadius === 'number' && node.cornerRadius > 0) {
+    out.cornerRadius = node.cornerRadius;
+  } else if ('topLeftRadius' in node) {
+    const radii = [node.topLeftRadius, node.topRightRadius, node.bottomRightRadius, node.bottomLeftRadius];
+    if (radii.some(r => r > 0)) out.cornerRadius = radii.join(' ');
+  }
+
+  // Fill colours
+  if ('fills' in node && Array.isArray(node.fills)) {
+    const fills = node.fills.filter(f => f.visible !== false && f.type === 'SOLID');
+    if (fills.length > 0) out.fill = hexFromColor(fills[0].color, fills[0].opacity);
+  }
+
+  // Strokes / borders
+  if ('strokes' in node && node.strokes.length > 0) {
+    const strokes = node.strokes.filter(s => s.visible !== false && s.type === 'SOLID');
+    if (strokes.length > 0) {
+      out.stroke = hexFromColor(strokes[0].color);
+      // Individual stroke weights (three-sided buttons etc.)
+      if ('strokeTopWeight' in node) {
+        out.strokeWeights = {
+          top: node.strokeTopWeight,
+          right: node.strokeRightWeight,
+          bottom: node.strokeBottomWeight,
+          left: node.strokeLeftWeight,
+        };
+      } else if ('strokeWeight' in node) {
+        out.strokeWeight = node.strokeWeight;
+      }
+    }
+  }
+
+  // Auto-layout (padding + gap)
+  if ('layoutMode' in node && node.layoutMode !== 'NONE') {
+    out.layout = {
+      direction: node.layoutMode,
+      paddingTop: node.paddingTop,
+      paddingRight: node.paddingRight,
+      paddingBottom: node.paddingBottom,
+      paddingLeft: node.paddingLeft,
+      gap: node.itemSpacing,
+      wrap: node.layoutWrap === 'WRAP',
+    };
+  }
+
+  // Recurse into named children (skip hidden, unnamed, or pure graphic nodes)
+  if ('children' in node) {
+    const namedChildren = node.children.filter(c =>
+      c.visible !== false &&
+      c.name &&
+      !c.name.startsWith('_') &&
+      (c.type === 'FRAME' || c.type === 'COMPONENT' || c.type === 'INSTANCE' || c.type === 'GROUP')
+    );
+    if (namedChildren.length > 0) {
+      out.children = namedChildren.map(extractLayout);
+    }
+  }
+
+  return out;
+}
+
+const node = figma.getNodeById('TARGET_ID');
+if (!node) return JSON.stringify({ error: 'Node not found: TARGET_ID' });
+return JSON.stringify(extractLayout(node), null, 2);
+```
+
+Store results as `componentFrames[frameName]`.
+
+---
+
+## Step 4 — Get today's date
+
+Run `date -u +"%Y-%m-%d"` via Bash to get today's UTC date. Store as `snapshotDate`.
+
+---
+
+## Step 5 — Write design.md
+
+Write the output file to `outputPath` from config. Use **exactly this structure and section order** every run — consistent ordering is what makes git diffs useful.
+
+### Rules for determinism
+
+- **Colors**: output in alphabetical order by `name`. Within each group (Primary / Neutral), sort alphabetically.
+- **Typography**: output sorted by `name` (alphabetical). Because names follow the `DSK/H1` / `MBL/H1` pattern, this naturally groups desktop then mobile.
+- **Variables**: output sorted by `collection/name`.
+- **Frame inventory**: sorted by name.
+- **Numbers**: always round to 1 decimal place. Drop `.0` (e.g. `12` not `12.0`). Exception: font sizes are always whole numbers.
+- **Never include Figma asset URLs** — they expire in 7 days and will always produce diff noise.
+- **No screenshots** — text and tables only.
+
+### Output template
+
+```markdown
+# [Page Name] — Design Reference
+
+> Source: Figma file `[fileKey]` · Page `[figmaPageId]` · Snapshot: [snapshotDate]
+
+---
+
+## Colour Palette
+
+### [Group name — derived from paint style name prefix, e.g. "Pedestal Mini/..." → "Pedestal Mini"]
+
+If all styles share the same prefix (e.g. `Pedestal Mini/Black`) group them under that prefix.
+If styles have no prefix group, list them all under a single "Colours" heading.
+
+| Token | Hex | Swatch |
+|-------|-----|--------|
+| [name (without prefix)] | `[hex]` | <div style="width:48px;height:24px;background:[hex];border:1px solid #e0e0e0;border-radius:4px"></div> |
+
+Repeat for each group, sorted alphabetically within each group.
+
+---
+
+## Typography
+
+**Font family:** [family name(s), comma-separated if multiple]
+**Weights used:** [list weights as Regular (400), Medium (500), etc.]
+
+### Desktop
+
+| Style | Size | Weight | Line Height | Letter Spacing |
+|-------|------|--------|-------------|----------------|
+[one row per DSK/* style, sorted by name]
+
+### Mobile
+
+| Style | Size | Weight | Line Height | Letter Spacing |
+|-------|------|--------|-------------|----------------|
+[one row per MBL/* style, sorted by name]
+
+[If styles use a different naming convention than DSK/MBL, use a single unsplit table instead]
+
+---
+
+## Variables
+
+[Only include this section if vars.length > 0]
+
+### [Collection name]
+
+| Variable | Type | [Mode 1] | [Mode 2] |
+|----------|------|----------|----------|
+[one row per variable, sorted by name within collection]
+
+---
+
+## Breakpoints & Canvas
+
+| Breakpoint | Canvas Width |
+|------------|-------------|
+[derived from frames — look for the widest desktop frame and widest mobile frame]
+
+---
+
+## Spacing & Layout
+
+Extract these values from the component frame data. Produce a flat table — one row per spacing token.
+Derive tokens by inspecting named component frames for padding/gap values.
+
+| Token | Desktop | Mobile |
+|-------|---------|--------|
+| Page side padding | [px] | [px] |
+| Nav vertical padding | [px] | [px] |
+| Section vertical padding | [px] | [px] |
+| [etc — only include rows you have data for] | | |
+
+---
+
+## Components
+
+For each named top-level child of the component frame, write a subsection.
+Use the frame name as the heading. Include:
+- A spec table of key layout properties (padding, gap, border-radius, fill, stroke, dimensions)
+- A brief plain-English description of the component's visual behaviour (1–2 sentences)
+
+### [Component Name]
+
+[1–2 sentence description]
+
+| Property | Value |
+|----------|-------|
+| Width | [px] |
+| Height | [px] |
+| Border radius | [px] |
+| Fill | [hex or "none"] |
+| Stroke | [hex, weight, sides] |
+| Padding | [top / right / bottom / left in px] |
+| Gap | [px] |
+
+---
+
+## Frame Inventory
+
+All top-level frames on this Figma page, sorted alphabetically.
+
+| Frame | Node ID | Width | Height |
+|-------|---------|-------|--------|
+[one row per frame from tokens.frames]
+
+---
+
+## Figma Source
+
+| Field | Value |
+|-------|-------|
+| File key | `[fileKey]` |
+| Page ID | `[figmaPageId]` |
+| Component frame | `[name]` (`[nodeId]`) |
+| Snapshot date | [snapshotDate] |
+```
+
+---
+
+## Step 6 — Verify
+
+After writing the file:
+1. Confirm the file was written successfully.
+2. Report which sections were populated and which were empty (e.g. "0 variables found").
+3. Tell the user the snapshot date and how to commit it: `git add design.md && git commit -m "design: snapshot [date]"`.
+
+---
+
+## Notes for future runs
+
+- The output is intentionally **idempotent**: running the skill twice on the same day with no Figma changes should produce an identical file (no diff).
+- Running it after a designer makes changes will produce a clean, readable diff showing exactly what tokens or component values changed.
+- The `.design-snapshot.json` config file should also be committed so any team member can regenerate the snapshot.
+- If the Figma file gains new paint styles, text styles, or component frames, they will appear in the diff as additions.
+- If items are renamed in Figma, they will appear as a deletion + addition in the diff (because output is sorted by name).