@se-studio/skills 1.9.15 → 1.9.16

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/skills
 
+## 1.9.16
+
+### Patch Changes
+
+- 049abbb: Document how to place a designed HTML page: site chrome stays in the template, editor-owned or repeated sections become registered components, and HtmlComponent is only for a developer-owned island. Specimens drop embedded fonts, a second colour palette, raw forms, and hand-rolled analytics.
+
 ## 1.9.15
 
 ### Patch Changes

package/package.json

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

package/references/contentful-cms-cms-guidelines/html-component-authoring.md

@@ -9,9 +9,32 @@ metadata:
 
 # HtmlComponent Authoring Guide
 
-`HtmlComponent` is a CMS content type that renders developer-authored HTML directly into the page. It bypasses the standard component registration system and is intended for one-off or highly custom layouts that the structured component library cannot produce.
+`HtmlComponent` is a CMS content type that renders developer-authored HTML directly into the page. It bypasses the standard component registration system.
 
-**Last resort, not the default remake path.** Prefer a registered `componentType` / `collectionType` + Tailwind tokens. Do not use HtmlComponent + `customCss` to reconstruct a Webflow page when a registered component would work. See `se-marketing-sites-customer-simplicity` and PHILOSOPHY §5a.
+Author it only after the recorded call is **keep**. That call is in `packages/contentful-cms/docs/editor-tasks/create-html-component.md`. A layout the library cannot produce does not keep the section. A registered type that could render it does not promote the section. Do not use HtmlComponent + `customCss` to reconstruct a Webflow page. See `se-marketing-sites-customer-simplicity` and PHILOSOPHY §5a.
+
+---
+
+## From a designed page file
+
+A self-contained HTML file (nav, page, footer, embedded font) is a specimen. Do not paste it into `rawHtml`. The shelf decision is in `packages/contentful-cms/docs/editor-tasks/create-html-component.md` (`cms-edit://customer/task-create-html-component`):
+
+| Shelf | When |
+|-----|------|
+| Site layout | Nav, footer, menu, contact panel. Leave them in the file. |
+| Registered component | An editor will change the words, media, or links, or the section repeats (on this page or another). Build or reuse a component. Do not author it here. |
+| `HtmlComponent` | The recorded call is **keep**: a developer will own it, editors will not change the words, media, or links, and it does not repeat. A layout match does not decide this. A first version gets the same keep-or-promote call. Continue below only after **keep**. |
+
+When the shelf is `HtmlComponent`:
+
+- Drop `@font-face` and embedded font files. The site already loads the brand font.
+- Drop a second `:root` palette. Use the named colour and type classes in the project style guide. Motion that those classes cannot express goes in `customCss`, using the site’s existing tokens.
+- Do not paste a `<form>`. Forms use the site’s registered form.
+- Do not push to `dataLayer` from `customJs`. `HtmlComponent` does not emit analytics. Clicks that must be measured are registered links.
+- One page has one `h1`. Set `isHero` only when this block is that heading.
+- Fill `markdownContent` with the visible sentences.
+
+Regenerate `html-component-style-guide.md` only when that site’s tokens have changed.
 
 ---
 

package/skills/se-marketing-sites-create-component/SKILL.md

@@ -1,12 +1,20 @@
 ---
 name: se-marketing-sites-create-component
-description: "Guide for creating new CMS-driven components in the SE Core Product monorepo. Use this skill when asked to create a new component, ensuring adherence to the 4-layer architecture."
+description: "Guide for creating new CMS-driven components in the SE Core Product monorepo. Use this skill when asked to create a new component, or when a designed HTML page needs a registered section. Ensures adherence to the 4-layer architecture."
 ---
 
 # Creating CMS Components
 
 This guide explains how to build new CMS-driven components following the established architecture patterns in this codebase.
 
+## When the brief is a designed HTML page
+
+Read `packages/contentful-cms/docs/editor-tasks/create-html-component.md` and record **keep** or **promote** for each section before writing code. A first version with no designed file gets the same call. Do not start the four layers until the call is **promote**. Do not open the HTML playbook until the call is **keep**.
+
+**Promote** is required when an editor will change the words, media, or links, or the section repeats (on this page or another). Then follow the four layers below. Do not paste the HTML document in as the component. Leave nav, footer, menu, and the contact panel to the page template.
+
+**Keep** is allowed only when a developer will own it, an editor will not change the words, media, or links, and it does not repeat. Motion, a tool demo, or vendor JS can be that island. A layout match does not promote it, and a new layout does not keep it. The keep path is the playbook above, including the project HTML style guide.
+
 ## Architecture Overview
 
 All components follow a **four-layer architecture** and must remain **Server Components** by default.
@@ -254,4 +262,4 @@ export const MyNewRegistration = defineComponent({
     *   Do **not** flatten body/`additionalCopy` for layout; use `<RtfOrString>`.
     *   Do **not** invent or filter CMS `links` into roles unless Nick asks.
     *   Prefer Tailwind tokens over new `globals.css` layout rules; CSS islands are debt.
-    *   Empty field → omit UI (**fail closed**). Load `se-marketing-sites-customer-simplicity` on remake tasks.
+    *   Empty field → omit UI (**fail closed**). Load `se-marketing-sites-customer-simplicity` on remake tasks. Its HtmlComponent escape hatch does not move a section onto or off HtmlComponent after **keep** or **promote** is recorded.

package/skills/se-marketing-sites-customer-simplicity/SKILL.md

@@ -34,7 +34,7 @@ Canonical: `docs/PHILOSOPHY.md` §5a. Review: `customer-code-review.md`. Session
 ## Escape hatches (narrow)
 
 - `globals.css`: shared primitives only (keyframes, RTF element maps, true design-system utilities) — **not** per-page layout ports
-- HtmlComponent + `customCss`: last resort when a registered type cannot express the interaction — **not** the default Webflow remake path
+- HtmlComponent + `customCss`: only when the recorded call is **keep** (`create-html-component.md`). A layout a registered type cannot express does not make that call. Do not move a section onto or off HtmlComponent after **keep** or **promote** is recorded. **Not** the default Webflow remake path.
 
 ## Related