@se-studio/skills 1.0.5 → 1.0.11

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).

package/skills/site-workflows-new-project/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: site-workflows-new-project
+description: Bootstrap a new SE Studio customer project from the SE Studio template. Runs full project cleanup (black/white colors, system font, minimal registrations), then sets up CLAUDE.md, AGENTS.md, README files, STYLING.md, ANIMATION.md, and updates project identity (site title, description, .cursorrules). Use this immediately after cloning the template for a new client.
+license: MIT
+metadata:
+  author: se-studio
+  version: "1.0.0"
+---
+
+# SE New Project Bootstrap
+
+Use this skill immediately after cloning the SE Studio customer project template for a new client.
+
+**Prerequisites:**
+- The project has been cloned/copied from the SE Studio customer project template
+- `.env.local` is configured with the new Contentful space credentials (`CONTENTFUL_SPACE_ID`, `CONTENTFUL_ACCESS_TOKEN`, `CONTENTFUL_MANAGEMENT_TOKEN`, `CONTENTFUL_PREVIEW_ACCESS_TOKEN`)
+- `pnpm install` has been run
+- A `scripts/master-schema.json` file exists (exported from the source Contentful space, or the new empty space)
+- You know: **customer/project name**, **site title**, **site description**
+
+---
+
+## Step 1 — Gather project identity
+
+Before making any changes, confirm the following with the user if not already provided:
+
+1. **Customer/project name** — used in README, CLAUDE.md header, and Navigation stub (e.g. "Acme Corp")
+2. **Site title** — used in `src/lib/constants.ts` and `<title>` tag (e.g. "Acme Corp — Engineering")
+3. **Site description** — used in meta description (1–2 sentences describing the site)
+4. **Domain** (optional) — used in sitemap and OG URLs if known
+
+---
+
+## Step 2 — Run the full cleanup
+
+Execute every step in the `site-workflows-project-cleanup` skill. This strips the template down to:
+- Black/white color system
+- System font
+- Generic Component, Generic Collection, Related Articles Collection only
+- Minimal Navigation and Footer stubs
+- Cleaned Contentful schema imported to the new space
+
+After cleanup, `pnpm validate` must pass before continuing.
+
+---
+
+## Step 3 — Update project identity in `src/lib/constants.ts`
+
+Read `src/lib/constants.ts` and update:
+- `siteTitle` → the confirmed site title
+- `siteDescription` → the confirmed site description
+- Any domain or URL constants → the confirmed domain (or leave as placeholder if unknown)
+
+---
+
+## Step 4 — Update the Navigation and Footer stubs
+
+In `src/project/components/Navigation/index.tsx`, replace `"Site Name"` with the customer/project name.
+
+In `src/project/components/Footer/index.tsx`, replace `"Site Name"` with the customer/project name.
+
+---
+
+## Step 5 — Create `CLAUDE.md`
+
+Write `CLAUDE.md` at the project root:
+
+```markdown
+@.cursorrules
+
+@AGENTS.md
+```
+
+---
+
+## Step 6 — Create `AGENTS.md`
+
+Write `AGENTS.md` at the project root. Fill in the user's email address (from memory if known, otherwise ask) and today's date:
+
+```markdown
+# Next.js: ALWAYS read docs before coding
+
+Before any Next.js work, find and read the relevant doc in `node_modules/next/dist/docs/`. Your training data is outdated — the docs are the source of truth.
+
+# userEmail
+The user's email address is [USER_EMAIL].
+
+# currentDate
+Today's date is [CURRENT_DATE].
+```
+
+---
+
+## Step 7 — Update `.cursorrules`
+
+Read `.cursorrules` and update the **Project Overview** section at the top:
+- Replace the previous project name with the new customer/project name
+- Update the "Key technologies" list if anything changed
+- Remove any project-specific notes about the previous customer
+
+Do not change the Code Style, Component Architecture, or other generic sections — those apply to all SE Studio projects.
+
+---
+
+## Step 8 — Create `src/project/components/README.md`
+
+Write the standard component development guide. This file should explain the four-layer architecture pattern used in this project. Reference the `se-marketing-sites-create-component` skill, which contains a comprehensive template.
+
+Key sections to include:
+- Architecture overview (four-layer pattern)
+- FIELD_KEYS / USED_FIELDS pattern
+- `getSizingInformation(index)` usage
+- `getPreviewFieldProps` usage
+- Client component isolation pattern
+- Checklist for new components
+
+---
+
+## Step 9 — Create `src/project/collections/README.md`
+
+Write the standard collection development guide. Reference the `se-marketing-sites-create-collection` skill.
+
+Key sections to include:
+- Five-layer architecture (Card, Core, Wrapper, Renderer, Registration)
+- Dual FIELD_KEYS pattern (collection-level + card-level)
+- `getSizingInformation(1)` for card titles (ChildElement)
+- Parent-child ID tracking for preview helpers
+- Client component isolation (carousels, filters)
+- Checklist for new collections
+
+---
+
+## Step 10 — Create `src/project/STYLING.md`
+
+Create a styling reference document for this project. Template:
+
+```markdown
+# Styling System — [Project Name]
+
+This project uses Tailwind CSS v4 with configuration driven by `tailwind.config.json`.
+
+## Colors
+
+Two named colors:
+
+| Name  | Hex     | Tailwind class  |
+|-------|---------|-----------------|
+| Light | #FFFFFF | `bg-light` / `text-light` |
+| Dark  | #000000 | `bg-dark` / `text-dark` |
+
+Use `lookupColourClassNames()` from `@/generated/colors` when applying background + text color pairs.
+
+## Typography
+
+Typography utility classes are generated from `tailwind.config.json`. Common classes:
+
+| Class    | Usage                      |
+|----------|----------------------------|
+| `h1`     | Hero headings (uppercase)  |
+| `h2`     | Section headings           |
+| `h3`     | Sub-headings               |
+| `h4`     | Small headings             |
+| `p1`     | Large body text            |
+| `p2`     | Default body text          |
+| `p3`     | Small/caption text         |
+| `nav`    | Navigation links           |
+
+Use `getSizingInformation(index)` from `@/lib/SizingInformation` for dynamic semantic headings.
+
+## Grid System
+
+| Breakpoint | Min-width | Columns |
+|-----------|-----------|---------|
+| mobile    | 0         | 6       |
+| tablet    | 768px     | 8       |
+| laptop    | 1024px    | 12      |
+| desktop   | 1440px    | 12      |
+
+Gap: 16px at all breakpoints. Margin: 16px at all breakpoints.
+
+Use `content-cols-grid` for standard content layout.
+
+## Section Spacing
+
+Standard vertical padding: `py-16 laptop:py-24`
+
+## RTF Classes
+
+| Class          | Usage                             |
+|----------------|-----------------------------------|
+| `.rtf-standard`| General rich text content         |
+| `.rtf-article` | Article/blog body text            |
+| `.rtf-legal`   | Terms, conditions, legal text     |
+```
+
+---
+
+## Step 11 — Create `src/project/ANIMATION.md`
+
+Create a minimal animation guide. Template:
+
+```markdown
+# Animation System — [Project Name]
+
+Animations use a two-part trigger pattern:
+
+1. Add `animate-when-seen` to pause the animation until the element is visible
+2. Add the animation class (e.g. `animate-text-in`)
+
+`Section` sets `data-seen` on the element when it enters the viewport.
+
+## Adding a New Animation
+
+1. Define `@keyframes` in `src/app/globals.css`
+2. Register a `--animate-*` CSS variable in the `@theme` block
+3. Create a `@utility animate-your-name` block that applies the animation
+4. Apply `animate-when-seen animate-your-name` to the element
+
+## Current Animations
+
+None — this is a bare-bones project. Add animations as the design is built out.
+```
+
+---
+
+## Step 12 — Verify the Contentful schema import
+
+Confirm the cleaned schema was successfully imported to the new space:
+
+1. Open the Contentful web app for the new space
+2. Navigate to Content model → Component → `componentType` field
+3. Verify the allowed values are: `Generic` only
+4. Navigate to Content model → Collection → `collectionType` field
+5. Verify the allowed values are: `Generic`, `Related articles`
+
+If the import did not run during cleanup (Step 2), run it now:
+```bash
+node scripts/clean-schema.js
+contentful space import \
+  --space-id $(grep CONTENTFUL_SPACE_ID .env.local | cut -d= -f2) \
+  --environment-id master \
+  --content-file scripts/clean-schema.json
+```
+
+---
+
+## Step 13 — Final validation
+
+```bash
+pnpm validate
+```
+
+All TypeScript errors must be resolved. Then start the dev server to confirm the site runs:
+
+```bash
+pnpm dev
+```
+
+Check:
+- `/` — home page loads (may show "not found" if no CMS content, that's fine)
+- `/cms/showcase` — shows only Generic Component, Generic Collection, Related Articles
+- `/cms/guidelines.md` — component guidelines render
+
+---
+
+## What to do next
+
+After bootstrap, the project is ready for:
+1. **CMS content setup** — use `contentful-cms-core` skill to create initial pages and navigation
+2. **Design system** — update `tailwind.config.json` with brand colors and typography when the design is ready
+3. **Components** — use `se-marketing-sites-create-component` and `se-marketing-sites-create-collection` skills to build project-specific components
+4. **Navigation/Footer** — replace the stubs with real components once the design is known
+
+Commit the bootstrapped state before starting component work:
+```bash
+git add -A
+git commit -m "Bootstrap new project from SE Studio template"
+```