@se-studio/skills 1.0.6 → 1.0.11

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"
+```

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

@@ -0,0 +1,362 @@
+---
+name: site-workflows-project-cleanup
+description: Strip an existing SE Studio Next.js/Contentful project to a bare-bones baseline — black/white color system, system font, only Generic Component, Generic Collection, and Related Articles Collection registered, with minimal navigation and footer stubs. Run this when you need to clean a customer project down to a reusable template.
+license: MIT
+metadata:
+  author: se-studio
+  version: "1.0.0"
+---
+
+# SE Project Cleanup
+
+Strips an existing SE Studio project to a bare-bones baseline. After this skill runs you will have:
+- **Colors**: White (`Light`) and Black (`Dark`) only
+- **Font**: system-ui (no custom or Google fonts)
+- **Components**: Generic Component only
+- **Collections**: Generic Collection + Related Articles Collection
+- **Nav/Footer**: Minimal HTML stubs
+- **Contentful schema**: `componentType` and `collectionType` enums trimmed to match
+
+Run `pnpm validate` at the end to confirm a clean TypeScript build.
+
+---
+
+## Step 1 — Update `tailwind.config.json`
+
+Replace `colorOptions` with black and white only, update font family, and remove OpenType feature settings:
+
+```json
+{
+  "colorOptions": {
+    "Light": "#FFFFFF",
+    "Dark": "#000000"
+  },
+  "colorFile": "./colors.ts",
+  "foregroundColors": ["Dark", "Light"],
+  "colorOpposites": {
+    "Light": "Dark",
+    "Dark": "Light"
+  },
+  "sizes": { /* keep existing sizes unchanged */ },
+  "fontTable": {
+    "font": "system-ui",
+    "weight": 400,
+    "lineHeight": 1.2,
+    "styles": { /* see below */ }
+  }
+}
+```
+
+In `fontTable.styles`:
+- Remove the top-level `"additional"` block (which has `font-feature-settings`)
+- For every style that has an `"additional"` block containing `font-feature-settings`, remove that `additional` block entirely
+- Keep any `"additional"` blocks that contain only `text-transform` (those are still valid with system fonts)
+- Keep all size values, weight overrides, lineHeight, and letterSpacing values unchanged
+
+After this change the font table will reference `system-ui` but retain all the responsive size scales.
+
+---
+
+## Step 2 — Update `src/project/font.ts`
+
+Delete the entire file. It exports `noiVariableFlex` (local font) and `ibmPlexMono` (Google font) — both unused after cleanup.
+
+---
+
+## Step 3 — Update `src/app/layout.tsx`
+
+1. Remove the import line: `import { ibmPlexMono, noiVariableFlex } from '@/project/font';`
+2. In the `html` element's `className`, remove `noiVariableFlex.variable` and `ibmPlexMono.variable`
+
+The html element should look like:
+```tsx
+<html
+  lang="en"
+  suppressHydrationWarning
+  className={cn(
+    'antialiased',
+    process.env.DEBUG_TAILWIND === 'true' && 'debug-screens',
+    process.env.SHOW_SECTION_OUTLINE === 'true' && 'show-section-outline',
+  )}
+>
+```
+
+---
+
+## Step 4 — Update `src/app/globals.css`
+
+### In the `@theme` block, make these changes:
+
+**Replace** the `--font-sans` and `--font-serif` lines with:
+```css
+--font-sans: system-ui, ui-sans-serif, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+--font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif;
+```
+
+**Remove** all `--animate-*` custom properties:
+```
+--animate-cardRotate
+--animate-linkRotate
+--animate-ticker
+--animate-fadeInGrow
+--animate-shapeShiftClip
+--animate-shapeShiftSpin
+--animate-clipReveal
+--animate-filmGrainShift
+```
+
+### Remove these `@utility` blocks entirely:
+- `animate-ticker`
+- `animate-fade-in-grow`
+- `animate-shape-shift`
+- `animate-card-rotate`
+- `animate-clip-reveal`
+- `film-grain`
+- `image-item-h` (ArticleBrowser-specific)
+- `visual-cols` (VisualsCollection-specific)
+- `visual-width` (VisualsCollection-specific)
+
+### Remove all `@keyframes` blocks:
+- `cardRotate`
+- `linkRotate`
+- `ticker`
+- `growFade`
+- `shapeShiftClip`
+- `shapeShiftSpin`
+- `clipReveal`
+- `filmGrainShift`
+
+### Remove the view transition media query block:
+```css
+@media (prefers-reduced-motion: no-preference) {
+  ::view-transition-group(*) { ... }
+  ::view-transition-old(root) { ... }
+  ::view-transition-new(root) { ... }
+}
+```
+
+### In the RTF classes, replace `bg-yellow/20` with `bg-dark/10`:
+Three occurrences — in `.rtf-standard > blockquote`, `.rtf-article > blockquote`, and `.rtf-legal > blockquote`.
+
+### Remove the dead-code block at the bottom:
+```css
+.dark-component .standard-rtf { ... }
+.light-component .standard-rtf { ... }
+```
+
+### Remove the Orejime scroll-lock workaround if not using Orejime consent:
+The block starting with `.orejimeHtml-WithModalOpen.orejimeHtml-WithModalOpen body { ... }` — remove if the project does not use the Orejime consent banner.
+
+---
+
+## Step 5 — Update `src/lib/registrations.ts`
+
+Keep only these three registrations:
+
+```typescript
+import { GenericComponentRegistration } from '@/project/components/TemplateComponent';
+import { GenericCollectionRegistration } from '@/project/collections/TemplateCollection';
+import { RelatedArticlesCollectionRegistration } from '@/project/collections/RelatedArticlesCollection';
+
+export const componentRegistrationsList = [
+  GenericComponentRegistration,
+] as const;
+
+export const collectionRegistrationsList = [
+  GenericCollectionRegistration,
+  RelatedArticlesCollectionRegistration,
+] as const;
+
+export const externalComponentRegistrationsList = [] as const;
+```
+
+Remove all other imports and registrations.
+
+---
+
+## Step 6 — Delete component files
+
+Delete these files from `src/project/components/`:
+- `ArticleDescription.tsx`
+- `ArticleHero.tsx`
+- `ArticleRichText.tsx`
+- `Quote.tsx`
+- `SimpleParagraph.tsx`
+- `TwoColumnRichText.tsx`
+- `ViewTransitionTrackedLink.tsx`
+
+Also delete these files from `src/project/components/Navigation/`:
+- `NavMenu.tsx`
+- `MobileNav.tsx`
+- `ContactNavItem.tsx`
+
+Keep: `TemplateComponent.tsx`, `Navigation/index.tsx` (will be replaced in Step 8), `Navigation/types.ts`, `Footer/index.tsx` (will be replaced in Step 9), `Footer/types.ts`
+
+---
+
+## Step 7 — Delete collection files
+
+Delete these from `src/project/collections/`:
+- `ArticleBrowser/` (entire directory)
+- `ProcessListCollection.tsx`
+- `SeparatedVisualsCollection.tsx`
+- `TeamGridCollection.tsx`
+- `TextAndCarouselCollection.tsx`
+- `TextAndCarouselCarousel.tsx`
+- `VisualsCollection.tsx`
+
+Keep: `TemplateCollection.tsx`, `LinkCard.tsx` (used internally by TemplateCollection), `RelatedArticlesCollection.tsx`
+
+---
+
+## Step 8 — Delete external component files
+
+Delete all files in `src/project/externalComponents/` (IFrame and Pardot integrations).
+
+---
+
+## Step 9 — Replace Navigation with minimal stub
+
+Replace `src/project/components/Navigation/index.tsx` with:
+
+```tsx
+'use client';
+import type { INavigation } from '@se-studio/core-data-types';
+import type { NavigationProps } from './types';
+
+export const Navigation: React.FC<NavigationProps> = ({ navigation: _navigation }) => {
+  return (
+    <header className="fixed top-0 left-0 right-0 z-50 h-[var(--nav-height)] bg-light border-b border-dark/10 flex items-center px-4">
+      <nav>
+        <span className="p2 font-semibold">Site Name</span>
+      </nav>
+    </header>
+  );
+};
+
+export default Navigation;
+```
+
+---
+
+## Step 10 — Replace Footer with minimal stub
+
+Replace `src/project/components/Footer/index.tsx` with:
+
+```tsx
+'use client';
+import type { FooterProps } from './types';
+
+export const Footer: React.FC<FooterProps> = ({ navigation: _navigation }) => {
+  return (
+    <footer className="bg-dark text-light py-8 px-4 text-center">
+      <p className="p3">&copy; {new Date().getFullYear()} Site Name</p>
+    </footer>
+  );
+};
+
+export default Footer;
+```
+
+Delete `src/project/components/Footer/MobileFooter.tsx` if it exists.
+
+---
+
+## Step 11 — Clean up Contentful schema
+
+Create `scripts/clean-schema.js` (or update it if it already exists):
+
+```js
+#!/usr/bin/env node
+'use strict';
+const fs = require('node:fs');
+
+const inputPath = 'scripts/master-schema.json';
+const outputPath = 'scripts/clean-schema.json';
+
+if (!fs.existsSync(inputPath)) {
+  console.error(`Input file not found: ${inputPath}`);
+  console.error('Export the schema first: contentful space export --skip-content --content-file scripts/master-schema.json');
+  process.exit(1);
+}
+
+const schema = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+
+// Trim componentType to bare-bones set
+const component = schema.contentTypes.find(ct => ct.sys.id === 'component');
+if (component) {
+  const field = component.fields.find(f => f.id === 'componentType');
+  if (field) {
+    field.validations = field.validations.map(v => v.in ? { in: ['Generic'] } : v);
+  }
+}
+
+// Trim collectionType to bare-bones set
+const collection = schema.contentTypes.find(ct => ct.sys.id === 'collection');
+if (collection) {
+  const field = collection.fields.find(f => f.id === 'collectionType');
+  if (field) {
+    field.validations = field.validations.map(v =>
+      v.in ? { in: ['Generic', 'Related articles'] } : v
+    );
+  }
+}
+
+// Clear externalComponentType (no external components in bare-bones setup)
+const ext = schema.contentTypes.find(ct => ct.sys.id === 'externalComponent');
+if (ext) {
+  const field = ext.fields.find(f => f.id === 'externalComponentType');
+  if (field) {
+    field.validations = field.validations.map(v => v.in ? { in: [] } : v);
+  }
+}
+
+fs.writeFileSync(outputPath, JSON.stringify(schema, null, 2));
+console.log(`Clean schema written to ${outputPath}`);
+console.log('Component types kept:', ['Generic']);
+console.log('Collection types kept:', ['Generic', 'Related articles']);
+```
+
+Run it:
+```bash
+node scripts/clean-schema.js
+```
+
+Then import to the target Contentful space (use the space ID from `.env.local`):
+```bash
+contentful space import \
+  --space-id <TARGET_SPACE_ID> \
+  --environment-id master \
+  --content-file scripts/clean-schema.json
+```
+
+> If cleaning an **existing** space (not a new one), use the Contentful Management API or UI to update the `componentType` and `collectionType` field validations directly, rather than importing. Importing to an existing space with live content can cause conflicts.
+
+---
+
+## Step 12 — Regenerate and validate
+
+```bash
+pnpm codegen
+```
+
+This regenerates `src/generated/colors.ts` (now only `Light` and `Dark`) and `src/generated/setailwind.css` (system font, updated color variables).
+
+```bash
+pnpm validate
+```
+
+Fix any TypeScript errors that surface from the removed imports. Common issues:
+- References to deleted components in other files (check `src/lib/` for any direct imports)
+- `viewTransitions.ts` may import from `ViewTransitionTrackedLink` — remove those imports
+- Any analytics wrappers that reference removed component names
+
+---
+
+## What is deliberately left untouched
+
+- `src/app/(cms-routes)/` — all routing is left as-is; the CMS routes work with whatever is registered
+- `src/lib/constants.ts` — site title/description stays as-is for cleanup; update manually for new projects
+- `src/project/STYLING.md` and `src/project/ANIMATION.md` — left for human review; update to reflect the new bare-bones system
+- `src/project/font.ts` — deleted (step 2 above)
+- `scripts/master-schema.json` — never modified, always kept as the original export