@scayver/specshot-mcp-server 0.13.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -18,6 +18,9 @@ import { registerPrototypeTools } from "./tools/prototype.js";
18
18
  import { registerRenderTools } from "./tools/render.js";
19
19
  import { registerAgentLoopTools } from "./tools/agent-loop.js";
20
20
  import { registerSiteTools } from "./tools/site.js";
21
+ import { registerSeoTools } from "./tools/seo.js";
22
+ import { registerTaskTools } from "./tools/tasks.js";
23
+ import { registerEtchAuditTools } from "./tools/etch-audit.js";
21
24
  import { CONNECT_INSTRUCTIONS, MCP_PROMPTS } from "./build-standard.js";
22
25
  import { createRequire } from "node:module";
23
26
  /**
@@ -111,5 +114,11 @@ registerRenderTools(server, client);
111
114
  registerAgentLoopTools(server, client);
112
115
  // Whole-site generation for agents (docs/WHOLE-SITE-GENERATION-PLAN.md, "Agents over MCP").
113
116
  registerSiteTools(server, client);
117
+ // SEO fixes for agents (docs/SEO-PORTAL-PLAN.md, phase 5).
118
+ registerSeoTools(server, client);
119
+ // Project tasks for agents (docs/PROJECT-FLOW-PLAN.md, Phase 4).
120
+ registerTaskTools(server, client);
121
+ // The Etch site audit (docs/ETCH-TOOLKIT-LESSONS.md, item 3).
122
+ registerEtchAuditTools(server, client);
114
123
  const transport = new StdioServerTransport();
115
124
  await server.connect(transport);
package/dist/skills.js CHANGED
@@ -95,7 +95,7 @@ export const SKILL_LIST = {
95
95
  "id": "imagery-art-direction",
96
96
  "title": "Imagery and art direction",
97
97
  "kind": "component",
98
- "when": "Load before placing any image, hero visual, gallery, product shot, portrait, diagram or background."
98
+ "when": "Load before placing any image, image spot, hero visual, figure, gallery, product shot, portrait, diagram or background."
99
99
  },
100
100
  {
101
101
  "id": "typography",
@@ -113,7 +113,7 @@ export const SKILL_LIST = {
113
113
  "id": "layout-grids",
114
114
  "title": "Layout and grids",
115
115
  "kind": "foundation",
116
- "when": "Load before choosing a section's skeleton or building any grid, and when a page reads as a run of identical bands."
116
+ "when": "Load before choosing a section's layout or building any grid, and when a page reads as a run of identical bands."
117
117
  },
118
118
  {
119
119
  "id": "color-contrast",
@@ -131,7 +131,19 @@ export const SKILL_LIST = {
131
131
  "id": "motion",
132
132
  "title": "Motion and animation",
133
133
  "kind": "foundation",
134
- "when": "Load before adding any transition, entrance, hover effect, animated chart or signature interaction."
134
+ "when": "Load before adding any transition, entrance, reveal, hover state, floating figure, marquee, animated chart or signature interaction."
135
+ },
136
+ {
137
+ "id": "copywriting",
138
+ "title": "Website copy that converts",
139
+ "kind": "foundation",
140
+ "when": "Load before writing or rewriting any words on a page: headlines, sections, calls to action, proof, forms and messages."
141
+ },
142
+ {
143
+ "id": "seo",
144
+ "title": "On-page SEO and AI search visibility",
145
+ "kind": "foundation",
146
+ "when": "Load before designing any page, and before writing its headings, links, image text or FAQ."
135
147
  },
136
148
  {
137
149
  "id": "accessibility",
@@ -233,14 +245,14 @@ export const SKILL_BODIES = {
233
245
  "title": "Page composition",
234
246
  "kind": "page",
235
247
  "when": "Load before planning any whole page: which sections it has, in what order, on which ground, at what density.",
236
- "body": "# Page composition\n\nA page makes an argument, one section at a time. Write the plan as a list first, so the markup has a shape to follow.\n\n## What goes in\n\n- The page's goal and required sections come first. They are the client's requirements for this page and outrank any general guidance, and each one appears under its own name.\n- Then whatever the brief, the approved copy and the references call for. A section with no reason behind it is padding.\n- A whole page has a header, every section in order and a footer, saved together. Never a comment where a section should be.\n\n## A sequence that works\n\nMost marketing pages make their case in this order. Change it when the brief says so, and know why.\n\n1. Hero: what it is, who it is for, why believe it, what to do next.\n2. What it does: the few features or services that matter, each heading a claim.\n3. Proof: a real number, client logos or a short quote, so the claims are believed.\n4. How it works: numbered steps, so the next action feels small.\n5. Depth: a case study, the people, whatever this audience needs before deciding.\n6. The offer: pricing or the package, with proof beside the ask.\n7. Questions: an FAQ that answers the hard ones.\n8. The close: a closing statement carrying the primary action.\n9. The footer: somewhere to go, not a strip.\n\nSpecShot's premium exemplar runs: glass header, split hero with the product's report, an editorial feature grid, a stats band, numbered steps, a quote spotlight, a plan list, a sticky FAQ, a closing statement and the footer, all in one light theme.\n\n## The plan\n\nBefore markup, one line per section: name, skeleton, ground, padding.\n\n```text\nHero asymmetric split paper dense\nServices editorial grid paper-2 open\nResults stats band paper dense\nHow it works steps paper-2 open\nPricing comparison list paper open\nQuestions sticky narrative paper-2 dense\nClose closing statement paper open\n```\n\nThen hold it to the premium bar:\n\n- No two neighbors share a skeleton, and no row of equal cards anywhere.\n- No three sections in a row share a ground, and the page keeps one theme. Never drop a dark band into a light page: it outweighs everything around it.\n- Section padding is `--pad-open` or `--pad-dense` only, the same above and below, alternating so the page changes pace.\n- Every section's content starts on the one content edge, and nothing hangs past a section's edge.\n- The openings vary: not every section is a heading on the left and an empty right half.\n\n## What runs through it\n\n- One primary action, worded the same, at least three times: the hero, the middle, the close.\n- Read only the headings and the story is there. Headings that read like labels (\"Features\", \"About\") get rewritten as claims.\n- One signature move on the page, not one per section, and one authored motion moment at most.\n- Each section earns its place: a skeleton, a heading that makes a claim, one dominant element, its states and a reason from the brief.\n\n## Saving it\n\n- The sections list you save names the page's sections in document order, so each becomes a region the owner and client can select and comment on.\n- Save a single section on its own only when the owner asked for exactly one. Otherwise build the whole page first.\n\n## Check before you save\n\n- Is every required section present, by name, in a sensible order?\n- Does the plan pass the skeleton, ground, padding and edge rules?\n- Does the primary action appear three times with the same words?"
248
+ "body": "# Page composition\n\nA page makes an argument, one section at a time. Write the plan as a list first, so the markup has a shape to follow.\n\n## What goes in\n\n- The page's goal and required sections come first. They are the client's requirements for this page and outrank any general guidance, and each one appears under its own name.\n- Then whatever the brief, the approved copy and the references call for. A section with no reason behind it is padding.\n- A whole page has a header, every section in order and a footer, saved together. Never a comment where a section should be.\n\n## A sequence that works\n\nMost marketing pages make their case in this order. Change it when the brief says so, and know why.\n\n1. Hero: what it is, who it is for, why believe it, what to do next, with a layered visual.\n2. What it does: the few features or services that matter, composed as a bento, each heading a claim.\n3. Proof: a real number, client logos in a marquee band or a short quote, so the claims are believed.\n4. How it works: numbered steps with a line that draws between them, so the next action feels small.\n5. Depth: a case study, the people, whatever this audience needs before deciding.\n6. The offer: pricing or the package, with proof beside the ask.\n7. Questions: an FAQ that answers the hard ones.\n8. The close: a closing statement carrying the primary action.\n9. The footer: somewhere to go, not a strip.\n\nSpecShot's premium exemplar (get_premium_exemplar over MCP) is a whole page built this way, in one theme from header to footer.\n\n## The plan\n\nBefore markup, one line per section: name, layout, visual, reveal, ground, padding.\n\n```text\nHero split image spot + chip load entrance paper dense\nServices bento a figure per tile tiles rise paper-2 open\nClients marquee band the names moves, pauses paper dense\nHow it works steps a drawn line slide from left paper-2 open\nProof testimonial wall image spot scale in paper open\nQuestions sticky stack none rise paper-2 dense\nClose form panel a drawn figure panel rises paper open\n```\n\nThen hold it to the premium bar:\n\n- No two neighbors share a layout, a home page has a bento, and no row of equal cards anywhere.\n- The hero and at least two more sections carry a visual: an image spot, a drawn figure or the client's image.\n- Each section reveals its own way, and two to four figures move across the page.\n- No three sections in a row share a ground, and the page keeps one theme. Never drop a dark band into a light page: it outweighs everything around it.\n- Section padding is `--pad-open` or `--pad-dense` only, the same above and below, alternating so the page changes pace.\n- Every section's content starts on the one content edge, and every overlap is on purpose, above what it crosses.\n- The openings vary: not every section is a heading on the left and an empty right half.\n\n## What runs through it\n\n- One primary action, worded the same, at least three times: the hero, the middle, the close.\n- Read only the headings and the story is there. Headings that read like labels (\"Features\", \"About\") get rewritten as claims.\n- The page is alive from top to bottom: a load entrance, a reveal per section, moving figures and the interaction system (the motion skill).\n- Each section earns its place: a layout, a heading that makes a claim, one dominant element, a visual, its states and a reason from the brief.\n\n## Saving it\n\n- The sections list you save names the page's sections in document order, so each becomes a region the owner and client can select and comment on.\n- Save a single section on its own only when the owner asked for exactly one. Otherwise build the whole page first.\n\n## Check before you save\n\n- Is every required section present, by name, in a sensible order?\n- Does the plan pass the layout, visual, reveal, ground, padding and edge rules?\n- Does the primary action appear three times with the same words?"
237
249
  },
238
250
  "direction-by-niche": {
239
251
  "id": "direction-by-niche",
240
252
  "title": "Choosing a direction by niche",
241
253
  "kind": "page",
242
254
  "when": "Load when a project has no brand system, or only part of one, and a direction has to be proposed before the first page.",
243
- "body": "# Choosing a direction by niche\n\nA project with no brand is no excuse to decide nothing. Propose one direction that fits the business, carry it out precisely, and say clearly that the client still has to approve it.\n\n## What outranks what\n\n1. The client's rules and their brand: any color, face or value they already have.\n2. Part of a brand: use what exists (a logo suggests the type and the shapes; a color becomes the accent) and propose only the rest.\n3. An approved direction: once there is one, every page follows it.\n4. The starting points below, for whatever is still open.\n\n## Six starting points\n\nThese are the premium bar's direction recipes, each a complete system. Pick the one closest to the business and adapt it; never mix two. None names a face: each says the character of the type, and the faces come from the client's references (the brief's type facts), or a Google Fonts pairing matched to their character.\n\n- Editorial luxe, for studios, hospitality with a story, publishers and premium consumer brands: a display face set large and tight beside a face made for long reading, warm paper, a deep oxblood accent, hairlines instead of cards, radius 0.125 to 0.375rem, one slow staggered moment.\n- Midnight precision, for software, data, security and research, as a dark theme for the whole site: a sturdy, engineered sans and a monospace for figures, surfaces stepping up in lightness, a cool accent used sparingly, a product interface as the hero visual, radius 0.5 to 0.75rem, crisp motion.\n- Swiss signal, for engineering, architecture, finance and professional services: a plain, strong grotesque doing every job, paper and near-black ink with one hot accent, a strict 12-column grid, very large numbers, everything flush left, radius 0 to 0.25rem.\n- Soft natural, for health, wellness, education, food and local services: a warm display face with soft forms and an open, friendly reading face, a sage-tinted ground, radius 1 to 1.5rem, soft shadows with a real offset, the client's photographs shown large.\n- Noir atelier, for luxury, fashion, fine dining and hotels, as a dark theme for the whole site: a high-contrast display face with a light, quiet reading face, warm light text and a muted brass accent, full-bleed photographs, thin rules, very large white space, radius 0, one long quiet entrance.\n- Bright modern, for consumer apps, startups and friendly SaaS: a display face with personality and wide forms and a clean, even reading face, a bright ground and a vivid accent, a bento of mixed spans rounded 0.75 to 1rem, single-stroke icons, quick ease-out motion.\n\nNever Inter, Roboto, Arial, Geist, Fraunces, Plus Jakarta Sans or Space Grotesk by reflex, in any niche. Light or dark is the client's choice: the two dark directions are for a client who chose dark or left it to the designer. A dark direction is a theme for the whole site, never a dark band dropped into a light page.\n\n## Making it this client's\n\n- Change the values to suit the business: the accent hue, how dense the spacing runs, how dramatic the type scale is. Keep the token names.\n- Write a one-sentence mood metaphor a designer could argue with (\"a high-end travel magazine that happens to take bookings\"), not \"modern and clean\".\n- Say why the direction belongs to this business and what would break if a competitor used it. A direction that fits anyone has been picked, not designed.\n- Never fall back to a neutral sans on white with one accent. It is the failure mode, not the safe option.\n\n## Recording it\n\n- When the project uses the direction gate, build the proposal into the Design Direction board before any page.\n- Name the direction and its palette, faces, spacing and radius in your summary, labeled as a proposal.\n- When the owner approves it, record the approval so the next page inherits the decision instead of reopening it.\n\n## Check before you propose\n\n- Did everything the client already has win over the recipe?\n- Does the direction have real values: a named palette, a real pairing, a spacing scale and a radius family?\n- Is it clearly labeled as a proposal?"
255
+ "body": "# Choosing a direction by niche\n\nA project with no brand is no excuse to decide nothing. Propose one direction that fits the business, carry it out precisely, and say clearly that the client still has to approve it.\n\n## What outranks what\n\n1. The client's rules and their brand: any color, face or value they already have.\n2. Part of a brand: use what exists (a logo suggests the type and the shapes; a color becomes the accent) and propose only the rest.\n3. An approved direction: once there is one, every page follows it.\n4. The starting points below, for whatever is still open.\n\n## Six starting points\n\nThese are the premium bar's direction recipes, each a complete system. Pick the one closest to the business and adapt it; never mix two. None names a face: each says the character of the type, and the faces come from the client's references (the brief's type facts), or a Google Fonts pairing matched to their character.\n\n- Editorial luxe, for studios, hospitality with a story, publishers and premium consumer brands: a display face set large and tight beside a face made for long reading, warm paper, a deep oxblood accent, hairlines instead of cards, radius 0.125 to 0.375rem, slow staggered entrances and a line that draws itself.\n- Midnight precision, for software, data, security and research, as a dark theme for the whole site: a sturdy, engineered sans and a monospace for figures, surfaces stepping up in lightness, a cool accent used sparingly, a product interface as the hero visual, radius 0.5 to 0.75rem, crisp entrances, a chart that draws its data and floating status chips.\n- Swiss signal, for engineering, architecture, finance and professional services: a plain, strong grotesque doing every job, paper and near-black ink with one hot accent, a strict 12-column grid, very large numbers, everything flush left, radius 0 to 0.25rem, precise slides and bars that grow to their values.\n- Soft natural, for health, wellness, education, food and local services: a warm display face with soft forms and an open, friendly reading face, a sage-tinted ground, radius 1 to 1.5rem, soft layered shadows with a real offset, the client's photographs shown large, gentle rises and slow floating cards.\n- Noir atelier, for luxury, fashion, fine dining and hotels, as a dark theme for the whole site: a high-contrast display face with a light, quiet reading face, warm light text and a muted brass accent, full-bleed photographs, thin rules, very large white space, deep shadows, radius 0, long quiet entrances and a slow orbit around the hero visual.\n- Bright modern, for consumer apps, startups and friendly SaaS: a display face with personality and wide forms and a clean, even reading face, a bright ground and a vivid accent, a bento of mixed spans rounded 0.75 to 1rem, single-stroke icons, quick ease-out entrances, floating UI cards and a marquee band.\n\nNever Inter, Roboto, Arial, Geist, Fraunces, Plus Jakarta Sans or Space Grotesk by reflex, in any niche. Light or dark is the client's choice: the two dark directions are for a client who chose dark or left it to the designer. A dark direction is a theme for the whole site, never a dark band dropped into a light page.\n\n## Making it this client's\n\n- Change the values to suit the business: the accent hue, how dense the spacing runs, how dramatic the type scale is. Keep the token names.\n- Write a one-sentence mood metaphor a designer could argue with (\"a high-end travel magazine that happens to take bookings\"), not \"modern and clean\".\n- Say why the direction belongs to this business and what would break if a competitor used it. A direction that fits anyone has been picked, not designed.\n- Never fall back to a neutral sans on white with one accent. It is the failure mode, not the safe option.\n\n## Recording it\n\n- When the project uses the direction gate, build the proposal into the Design Direction board before any page.\n- Name the direction and its palette, faces, spacing and radius in your summary, labeled as a proposal.\n- When the owner approves it, record the approval so the next page inherits the decision instead of reopening it.\n\n## Check before you propose\n\n- Did everything the client already has win over the recipe?\n- Does the direction have real values: a named palette, a real pairing, a spacing scale and a radius family?\n- Is it clearly labeled as a proposal?"
244
256
  },
245
257
  "navigation-header": {
246
258
  "id": "navigation-header",
@@ -254,7 +266,7 @@ export const SKILL_BODIES = {
254
266
  "title": "Hero sections",
255
267
  "kind": "section",
256
268
  "when": "Load before building the first section of any page: a hero, an intro, a page header or a landing block.",
257
- "body": "# Hero sections\n\nSomeone decides in five seconds whether to keep reading. The hero answers four questions before they scroll: what it is, who it is for, why to believe it, and what to do next.\n\n## Content\n\n- Headline: the outcome for the customer, not the feature. \"Every room measured in two days\", not \"Advanced laser surveying\". Use approved copy word for word when it exists.\n- Supporting line: how, in one or two sentences, at most 52ch, at `--step-1`.\n- A primary action, a verb and an object (\"Book a site survey\"), and a quieter secondary (\"See recent projects\").\n- One piece of real proof inside the first screen: a real number, real client logos, a real rating with its source. No proof is better than invented proof.\n\n## Type\n\n- The headline at `--step-5`, two or three lines, line height 1.02 to 1.1, tracking -0.02em to -0.035em, `text-wrap: balance`. A short claim, never a full sentence at display size.\n- Upright, in the display face. No oversized italic serif, and no italic or colored word as its trick: emphasis is size and weight.\n- A small label above the headline only where the brand or the client's references set one, never a kicker, eyebrow or tracked-caps label by reflex.\n- The hero's image loads at once: no loading=\"lazy\" on it, and fetchpriority=\"high\" on the one that paints first.\n- Fix a long headline by widening its column and stepping down, never by letting it run to four lines.\n\n## Layout\n\n- Asymmetric by default: copy over 6 or 7 columns, the visual over the rest. A centered hero only when the direction is deliberately centered.\n- The visual's top edge starts on the headline's top line, so the two read as one composition.\n- The copy starts on the page's one content edge. Both columns carry comparable weight.\n- Nothing hangs past the bottom of the hero to be covered by the next section, and no negative margin pulls the visual over it.\n- Padding from the rhythm tokens, the same above and below. `min-height: min(100dvh, 56rem)` only when the visual fills it, and never vh.\n\n## The visual\n\nReal, or the type carries the hero alone.\n\n- The client's own photograph through a placeableUrl, or an image made for the project with generate_image, shown large.\n- A real diagram of the product at real detail: an interface in HTML and CSS, a chart in SVG from real-looking numbers.\n- A typographic hero, the headline set large on the grid with nothing beside it, is first-class.\n- Never a scene assembled from primitive shapes, never grain or a glow behind it, never an empty frame.\n\n## Motion\n\n- At most the page's one authored moment lives here, on time and staggered: the product's data settling into place, for example. Nothing in the hero waits for a scroll.\n\n## On a phone\n\n- Copy first, then the visual, then the proof. The primary action is visible without scrolling at 390 by 844.\n- Both actions full width or side by side, each at least 2.75rem tall.\n\n## Example\n\n```html\n<section class=\"hero\" aria-labelledby=\"hero-title\">\n <div class=\"hero__copy\">\n <h1 class=\"hero__title\" id=\"hero-title\">Every room measured in two days</h1>\n <p class=\"hero__lead\">Laser surveys drawn to scale, ready for your architect before the week is out.</p>\n <div class=\"hero__actions\"><a class=\"button button--primary\" href=\"/book\">Book a site survey</a><a class=\"button button--quiet\" href=\"/work\">See recent projects</a></div>\n <p class=\"hero__proof\">Rated 4.8 from 212 reviews on Google</p>\n </div>\n <figure class=\"hero__visual\"><img class=\"hero__image\" src=\"/api/img/...\" alt=\"A surveyor scanning a kitchen with a laser\" width=\"960\" height=\"720\"></figure>\n</section>\n```\n\nThe proof line is only ever the client's real figure and source. Leave it out if there is none.\n\n## Check before you save\n\n- Can someone tell what, who, why and what next without scrolling?\n- Is the visual real, starting on the headline's top line, with nothing past the section's edge?\n- Is every number and logo in the hero real?"
269
+ "body": "# Hero sections\n\nSomeone decides in five seconds whether to keep reading. The hero answers four questions before they scroll: what it is, who it is for, why to believe it, and what to do next. It also shows, in those five seconds, that the page is alive.\n\n## Content\n\n- Headline: the outcome for the customer, not the feature. The page's one h1, carrying its topic in the client's words. Use approved copy word for word when it exists.\n- Supporting line: how, in one or two sentences, at most 52ch, at `--step-1`.\n- A primary action whose label says what happens (\"Book a site survey\"), a quieter secondary (\"See recent projects\"), and one short trust line beside them from the client's facts.\n- One piece of real proof inside the first screen: a real number, real client logos, a real rating with its source. No proof is better than invented proof.\n\n## Type\n\n- The headline at `--step-5`, two or three lines, line height 1.02 to 1.1, tracking -0.02em to -0.035em, `text-wrap: balance`.\n- Upright, in the display face. No oversized italic serif, and no italic or colored word as its trick: emphasis is size and weight.\n- A small label above the headline only where the brand or the client's references set one, never a kicker, eyebrow or tracked-caps label by reflex.\n\n## The visual, layered\n\n- An image spot (a figure with `data-ss-image`, `data-ss-aspect` and `data-ss-alt` around a drawn fallback), the client's photograph, or a drawn figure from the page's content: an interface panel, a labeled chart, the process in the copy.\n- Raised on `--shadow-4`, with at least one floating element (a stat chip, a UI card, a review, a badge) on `--shadow-3` crossing its edge. Never a heading beside an empty half.\n- Never a scene assembled from primitive shapes, never grain or a glow behind it, never an empty frame.\n- The hero's image loads at once: no `loading=\"lazy\"` on it, and `fetchpriority=\"high\"` on the one that paints first.\n\n## Layout\n\n- Asymmetric by default: copy over 6 or 7 columns, the visual over the rest. The visual's top edge starts on the headline's top line.\n- The copy starts on the page's one content edge, and both columns carry comparable weight.\n- A floating element may cross the visual's edge. Nothing hangs past the bottom of the hero to be covered by the next section.\n- `min-height: min(100dvh, 56rem)` only when the visual fills it, and never vh.\n\n## Motion\n\n- The hero settles on load: heading, text, actions and visual enter in sequence over `--dur-4`, staggered by `--stagger`. The floating elements arrive last, then float 6 to 12px over 5 to 9s.\n- A figure in the visual may draw itself in over `--dur-5`. All of it under `prefers-reduced-motion: no-preference`.\n\n## On a phone\n\n- Copy first, then the visual, then the proof. The primary action is visible without scrolling at 390 by 844.\n- Both actions full width or side by side, each at least 2.75rem tall.\n\n## Example\n\n```html\n<section class=\"hero\" aria-labelledby=\"hero-title\">\n <div class=\"hero__copy\">\n <h1 class=\"hero__title\" id=\"hero-title\" style=\"--i: 0\">Every room measured in two days</h1>\n <p class=\"hero__lead\" style=\"--i: 1\">Laser surveys drawn to scale, ready for your architect before the week is out.</p>\n <div class=\"hero__actions\" style=\"--i: 2\"><a class=\"button button--primary\" href=\"/book\">Book a site survey</a><a class=\"button button--quiet\" href=\"/work\">See recent projects</a></div>\n </div>\n <figure class=\"hero__media\" data-ss-image=\"A surveyor scanning a bright kitchen with a laser on a tripod, morning light, no text\" data-ss-aspect=\"4:3\" data-ss-alt=\"A surveyor scanning a kitchen\">\n <svg class=\"hero__plan\" viewBox=\"0 0 480 360\" role=\"img\" aria-label=\"A floor plan with measured rooms\"></svg>\n <p class=\"hero__chip\">Drawings in 2 days</p>\n </figure>\n</section>\n```\n\nEvery number in the hero is the client's real figure. Leave it out if there is none.\n\n## Check before you save\n\n- Can someone tell what, who, why and what next without scrolling?\n- Is the visual real and layered, with a floating element over its edge?\n- Does the hero settle on load, with the floating element arriving last?"
258
270
  },
259
271
  "content-long-text": {
260
272
  "id": "content-long-text",
@@ -268,7 +280,7 @@ export const SKILL_BODIES = {
268
280
  "title": "Testimonials and social proof",
269
281
  "kind": "section",
270
282
  "when": "Load before building testimonials, reviews, client logos, case study teasers, stats, ratings, awards or press mentions.",
271
- "body": "# Testimonials and social proof\n\nProof is the reason to believe the headline. Invented proof is worse than none: a client, a competitor or a regulator can tell, and the whole page reads as invented.\n\n## Only real proof\n\n- A testimonial carries a real person's name, role and company, in their words, with permission. Never John Doe, never a first name and an initial standing in for a source, never a drawn face.\n- A stat carries a real number and, where it is not obvious, its source and period (\"212 surveys in 2025\").\n- A logo is the client's customer's real logo, used with permission, recreated as inline SVG in one tone.\n- When the client has not supplied proof yet, build the component with a visible marker (\"[GAP: testimonial from a client]\", or \"[UNVERIFIED: 4.9 rating]\" for one the client mentioned but has not shown) and say so in your summary. Never fill it with plausible fiction.\n- Uneven numbers read as measured. \"47.2 percent\" is believable; \"99.99 percent\" and \"10,000+ happy customers\" read as invented.\n\n## Forms of proof\n\n- Quote spotlight: one testimonial set large at `--step-3` in the display face, with name, role and company under it and a monogram or the client's photograph. One strong quote beats a carousel of five weak ones.\n- Quote grid: three to six short quotes of different lengths in a bento or masonry rhythm, each with its source. Never six identical cards.\n- Stats band: three or four real numbers at `--step-4` or larger with `tabular-nums`, each with a one-line label, on the page's own ground or a tint. Never a dark band dropped into a light page.\n- Logo wall: real logos in one tone (`--ink-3`), evenly optically sized and still, with a line saying who they are (\"Trusted by practices across Sydney\"). Never a marquee: it hides most of the logos at any moment and moves while people read.\n- Case study teaser: the client's problem, what was done, the measured result, and a link to the story.\n- Rating: the score, the count and the platform (\"4.8 from 212 Google reviews\"), stars drawn in SVG with a text alternative.\n\n## Placement\n\n- Proof sits next to every ask: one line of proof beside the hero's action, a quote near pricing, a number in the closing panel.\n- A dedicated proof section works after the features and before pricing or the close, where a visitor is deciding.\n- Match the proof to the claim it supports: a quote about speed sits next to the claim about speed.\n\n## Type and layout\n\n- Quotes in real typographic quotation marks with `hanging-punctuation: first`, at a measure of about 40 to 60 characters when set large.\n- The quote is a `<blockquote>` inside a `<figure>` with the source in `<figcaption>`.\n- Name in weight 600, role and company in `--ink-2`.\n\n## Example\n\n```html\n<figure class=\"quote\">\n <blockquote class=\"quote__text\"><p class=\"quote__line\">[Testimonial from a client, to be supplied]</p></blockquote>\n <figcaption class=\"quote__source\"><span class=\"quote__name\">[Name]</span> <span class=\"quote__role\">[Role, Company]</span></figcaption>\n</figure>\n```\n\n## Check before you save\n\n- Is every name, quote, logo and number real, or clearly labeled as waiting on the client?\n- Does each ask on the page have proof beside it?\n- Is the logo wall still, with every logo visible at once?"
283
+ "body": "# Testimonials and social proof\n\nProof is the reason to believe the headline. Invented proof is worse than none: a client, a competitor or a regulator can tell, and the whole page reads as invented.\n\n## Only real proof\n\n- A testimonial carries a real person's name, role and company, in their words, with permission. Never John Doe, never a first name and an initial standing in for a source, never a drawn face.\n- A stat carries a real number and, where it is not obvious, its source and period (\"212 surveys in 2025\").\n- A logo is the client's customer's real logo, used with permission, recreated as inline SVG in one tone.\n- When the client has not supplied proof yet, build the component with a visible marker (\"[GAP: testimonial from a client]\", or \"[UNVERIFIED: 4.9 rating]\" for one the client mentioned but has not shown) and say so in your summary. Never fill it with plausible fiction.\n- Uneven numbers read as measured. \"47.2 percent\" is believable; \"99.99 percent\" and \"10,000+ happy customers\" read as invented.\n\n## Forms of proof\n\n- Quote spotlight: one testimonial set large at `--step-3` in the display face, with name, role and company under it and a monogram or the client's photograph. One strong quote beats a carousel of five weak ones.\n- Quote grid: three to six short quotes of different lengths in a bento or masonry rhythm, each with its source. Never six identical cards.\n- Stats band: three or four real numbers at `--step-4` or larger with `tabular-nums`, each with a one-line label, on the page's own ground or a tint. Never a dark band dropped into a light page.\n- Logo wall or marquee band: real logos or client names in one tone (`--ink-3`), evenly optically sized, with a line saying who they are (\"Trusted by practices across Sydney\"). A marquee band moves slowly (30 to 60s, linear), repeats its items in an `aria-hidden=\"true\"` copy, fades at its edges and pauses on hover and focus-within.\n- Case study teaser: the client's problem, what was done, the measured result, and a link to the story.\n- Rating: the score, the count and the platform (\"4.8 from 212 Google reviews\"), stars drawn in SVG with a text alternative.\n\n## Placement\n\n- Proof sits next to every ask: one line of proof beside the hero's action, a quote near pricing, a number in the closing panel.\n- A dedicated proof section works after the features and before pricing or the close, where a visitor is deciding.\n- Match the proof to the claim it supports: a quote about speed sits next to the claim about speed.\n\n## Type and layout\n\n- Quotes in real typographic quotation marks with `hanging-punctuation: first`, at a measure of about 40 to 60 characters when set large.\n- The quote is a `<blockquote>` inside a `<figure>` with the source in `<figcaption>`.\n- Name in weight 600, role and company in `--ink-2`.\n\n## Example\n\n```html\n<figure class=\"quote\">\n <blockquote class=\"quote__text\"><p class=\"quote__line\">[Testimonial from a client, to be supplied]</p></blockquote>\n <figcaption class=\"quote__source\"><span class=\"quote__name\">[Name]</span> <span class=\"quote__role\">[Role, Company]</span></figcaption>\n</figure>\n```\n\n## Check before you save\n\n- Is every name, quote, logo and number real, or clearly labeled as waiting on the client?\n- Does each ask on the page have proof beside it?\n- Is the logo wall still, with every logo visible at once?"
272
284
  },
273
285
  "pricing": {
274
286
  "id": "pricing",
@@ -310,7 +322,7 @@ export const SKILL_BODIES = {
310
322
  "title": "Cards",
311
323
  "kind": "component",
312
324
  "when": "Load before building any card, tile, feature grid, team grid, product grid or post list.",
313
- "body": "# Cards\n\nA card frames one option a visitor might pick. If nothing in it can be picked, it probably does not need to be a card.\n\n## When a card is right\n\n- For sets of comparable choices: services, products, plans, articles, people.\n- Not for text that is only read. Three cards of an icon and a paragraph is the most common template on the web; a list, a table or plain columns often say it better.\n- Vary the grid. A bento with one large lead tile, or a featured card above smaller ones, reads as designed. A row of identical tiles only suits more than three truly equal items.\n\n## Anatomy\n\n- One block named for what the card holds: `.service-card`, `.team-member`, `.plan`, `.post-card`. Never a bare `.card`, and never a bare `.grid` for the list that holds them: the list is its section's element (`.services__list`). A generic name says nothing about what it is, and on an Etch site it collides with every other card.\n- Its elements carry the block's name: `.service-card__media`, `.service-card__title`, `.service-card__body`, `.service-card__meta` and `.service-card__action`, with modifiers such as `.service-card--featured` or `.service-card--wide`.\n- Top to bottom: media, title, a line or two of body, quiet metadata, then the action. The title is the strongest thing in the card.\n- Inner padding from a local property on the block, `--service-card-pad: var(--space-m, 1.5rem)`; title to body `--space-s`.\n- The title's heading level follows the page outline, usually an h3 under the section's h2, at `--step-2`.\n\n## Surface\n\n- One elevation: a hairline in `--line` or `--shadow-1`, never both. A `--paper-2` card on the page ground may need neither.\n- Radius `--radius-m`. Media inside the card takes the card's radius minus the padding, or the card's radius on its top corners when it runs to the edge.\n- Never a card inside a card; inside, separate parts with space or a hairline.\n- Never a thick colored stripe down one side.\n\n## Media\n\n- A fixed `aspect-ratio` such as 4 / 3 or 16 / 10, `object-fit: cover`, and alt text that says what is shown.\n- Only images with a placeableUrl. Without one, draw the media: a pattern, a fragment of interface in HTML and SVG, or type set large. Never an empty frame.\n- On hover the image scales to 1.04 inside `overflow: hidden`.\n- A person with no photograph becomes a monogram: initials in the display face on an `--accent-quiet` disc.\n\n## Color\n\n- Title in `--ink`, body in `--ink-2`, metadata in `--ink-3`. The accent is saved for the action, a link or a key number, never the title.\n- A featured card stands out through a higher shadow step, a tint or extra size, not a second accent and not a dark card among light ones.\n\n## Interaction\n\n- A card with a single destination is a single link: the title's link stretches over the whole card through a pseudo-element, so screen readers hear one link and the whole card responds.\n- A card with several actions keeps each as its own control and is not itself a link.\n- On hover the card rises 4px while a pseudo-element carrying `--shadow-2` fades in. The focus ring of the link outlines the whole card.\n\n## Example\n\n```html\n<article class=\"service-card\">\n <div class=\"service-card__media\"><svg aria-hidden=\"true\" viewBox=\"0 0 320 200\"></svg></div>\n <h3 class=\"service-card__title\"><a class=\"service-card__link\" href=\"/services/survey\">Site surveys</a></h3>\n <p class=\"service-card__body\">A measured survey of every room in two days, drawn to scale.</p>\n <p class=\"service-card__meta\">Residential and commercial</p>\n</article>\n```\n\n```css\n.service-card { position: relative; }\n.service-card__link::after { content: \"\"; position: absolute; inset: 0; border-radius: inherit; }\n```\n\n## Check before you save\n\n- Is every card a real choice, and would a list or table read better?\n- Does any card carry both a border and a shadow, or sit inside another card?\n- Does each card's media have a fixed ratio and honest alt text?"
325
+ "body": "# Cards\n\nA card frames one option a visitor might pick. If nothing in it can be picked, it probably does not need to be a card.\n\n## When a card is right\n\n- For sets of comparable choices: services, products, plans, articles, people.\n- Not for text that is only read. Three cards of an icon and a paragraph is the most common template on the web; a list, a table or plain columns often say it better.\n- Vary the grid. A bento reads as designed: 4 to 7 tiles in at least 3 sizes, one spanning 2 columns or 2 rows, tiles that differ in content type (a stat, a mini chart, a figure, an image, a quote, a list), each with its own small visual. A row of identical tiles only suits more than three truly equal items.\n\n## Anatomy\n\n- One block named for what the card holds: `.service-card`, `.team-member`, `.plan`, `.post-card`. Never a bare `.card`, and never a bare `.grid` for the list that holds them: the list is its section's element (`.services__list`). A generic name says nothing about what it is, and on an Etch site it collides with every other card.\n- Its elements carry the block's name: `.service-card__media`, `.service-card__title`, `.service-card__body`, `.service-card__meta` and `.service-card__action`, with modifiers such as `.service-card--featured` or `.service-card--wide`.\n- Top to bottom: media, title, a line or two of body, quiet metadata, then the action. The title is the strongest thing in the card.\n- Inner padding from a local property on the block, `--service-card-pad: var(--space-m, 1.5rem)`; title to body `--space-s`.\n- The title's heading level follows the page outline, usually an h3 under the section's h2, at `--step-2`.\n\n## Surface\n\n- One elevation: a hairline in `--line` or `--shadow-1`, never both. A `--paper-2` card on the page ground may need neither.\n- Radius `--radius-m`. Media inside the card takes the card's radius minus the padding, or the card's radius on its top corners when it runs to the edge.\n- Never a card inside a card; inside, separate parts with space or a hairline.\n- Never a thick colored stripe down one side.\n\n## Media\n\n- A fixed `aspect-ratio` such as 4 / 3 or 16 / 10, `object-fit: cover`, and alt text that says what is shown.\n- The client's image, an image spot (`data-ss-image`, `data-ss-aspect`, `data-ss-alt` around a drawn fallback), or a figure drawn from the card's own content: a fragment of interface, a small chart, type set large. Never an empty frame or a decorative pattern.\n- On hover the image scales to 1.04 inside `overflow: hidden`.\n- A person with no photograph becomes a monogram: initials in the display face on an `--accent-quiet` disc.\n\n## Color\n\n- Title in `--ink`, body in `--ink-2`, metadata in `--ink-3`. The accent is saved for the action, a link or a key number, never the title.\n- A featured card stands out through a higher shadow step, a tint or extra size, not a second accent and not a dark card among light ones.\n\n## Interaction\n\n- A card with a single destination is a single link: the title's link stretches over the whole card through a pseudo-element, so screen readers hear one link and the whole card responds.\n- A card with several actions keeps each as its own control and is not itself a link.\n- On hover the card rises 4px while a pseudo-element carrying `--shadow-2` fades in, under `prefers-reduced-motion: no-preference`. The focus ring of the link outlines the whole card.\n- Tiles reveal as they scroll in, in the safe form the motion skill gives, each grid its own way.\n\n## Example\n\n```html\n<article class=\"service-card\">\n <div class=\"service-card__media\"><svg aria-hidden=\"true\" viewBox=\"0 0 320 200\"></svg></div>\n <h3 class=\"service-card__title\"><a class=\"service-card__link\" href=\"/services/survey\">Site surveys</a></h3>\n <p class=\"service-card__body\">A measured survey of every room in two days, drawn to scale.</p>\n <p class=\"service-card__meta\">Residential and commercial</p>\n</article>\n```\n\n```css\n.service-card { position: relative; }\n.service-card__link::after { content: \"\"; position: absolute; inset: 0; border-radius: inherit; }\n```\n\n## Check before you save\n\n- Is every card a real choice, and would a list or table read better?\n- Does any card carry both a border and a shadow, or sit inside another card?\n- Does each card's media have a fixed ratio and honest alt text?"
314
326
  },
315
327
  "forms": {
316
328
  "id": "forms",
@@ -330,8 +342,8 @@ export const SKILL_BODIES = {
330
342
  "id": "imagery-art-direction",
331
343
  "title": "Imagery and art direction",
332
344
  "kind": "component",
333
- "when": "Load before placing any image, hero visual, gallery, product shot, portrait, diagram or background.",
334
- "body": "# Imagery and art direction\n\nA gray box is the cheapest-looking thing a page can contain, and a drawing that pretends to be a picture is the second. Every image on the page is real, or the section is carried by type.\n\n## Sources, in order\n\n1. The client's own pictures: items that carry a placeableUrl. Nothing beats the client's real product, team or place.\n2. The project's images: generated or added for this project, listed as projectImages. Over MCP, when the page needs a photograph nobody supplied, make one with generate_image, wait for it with get_image, then place its placeableUrl.\n3. Real diagrams in inline SVG or HTML: a product interface at real detail, a chart from real-looking numbers, a plan, a timeline, a map.\n4. Type used as the image. A typographic hero, the headline large on a strong grid, is first-class.\n\nNever a placeholder image host and never a hotlinked image: the preview strips external images and shows a gray block. A reference captured from another company's site is for study only.\n\n## What never stands in for a picture\n\n- Never a scene assembled from primitive shapes: circles, arcs and rectangles arranged into a building, a garden, a bottle or a person. It reads as clip art at a glance. Geometry is welcome only when it is geometry: a chart, a diagram, a plan with real labels.\n- No grain or noise over a ground (no feTurbulence filter), and no dot grid, line grid or repeating stripe behind a section with nothing under it. A ground is a surface.\n- No radial glow or soft blob standing in for a visual, and never an empty frame.\n\n## Placing pictures\n\n- Show a real image large: at least half the row on a desktop, never a thumbnail beside a paragraph.\n- A fixed `aspect-ratio` and `object-fit: cover`, with `object-position` set so faces and products are not cropped.\n- A radius from the scale, or a full bleed to the viewport edge. Not both on one image.\n- Text on a photograph sits on an overlay: a gradient from the ground color under the text, measured at 4.5:1 at its worst point.\n- Real alt text that says what the image shows. A decorative image has an empty alt.\n- `width` and `height` attributes or an aspect ratio on every image.\n- The hero's image loads at once (no `loading=\"lazy\"`, and `fetchpriority=\"high\"` on the one that paints first). Every image below the first screen takes `loading=\"lazy\"` and `decoding=\"async\"`. SpecShot's law check reads both.\n\n## Art direction\n\n- One treatment across the page: the same warmth, contrast, radius and crop habit. Mixed treatments look like stock.\n- Crop tight on the subject, with room in the direction the subject faces.\n- People without photographs are monograms: initials in the display face on an `--accent-quiet` disc. Never a drawn face pretending to be a person.\n\n## Generated images\n\n- Describe the subject, the setting, the light and the crop. Match the brand's palette and the page's treatment.\n- Never generate a person presented as a real customer, employee or testimonial author.\n- Never generate a logo, a certificate or anything that reads as a real document.\n\n## Example\n\n```css\n.showcase__media { aspect-ratio: 16 / 10; overflow: hidden; border-radius: var(--radius-m, 14px); }\n.showcase__image { inline-size: 100%; block-size: 100%; object-fit: cover; }\n```\n\n## Check before you save\n\n- Is every image real (a placeableUrl, a real diagram or type), with no shape-built scene and no empty box?\n- Does every image have a fixed ratio and real alt text, and is it shown large?\n- Is every ground a plain surface, with no grain and no decorative grid?"
345
+ "when": "Load before placing any image, image spot, hero visual, figure, gallery, product shot, portrait, diagram or background.",
346
+ "body": "# Imagery and art direction\n\nThe owner asked for \"different images and figures that move that bring the design and website to life\". A page with no pictures reads as a draft, and a drawing that pretends to be a photograph reads as clip art. Every page uses two kinds, and the hero and at least two more sections carry one.\n\n## Drawn figures\n\nIn SVG and CSS, from the page's own content:\n\n- An interface panel built from the page's own words: the service list as a dashboard, the booking as a calendar card.\n- A chart with the page's numbers and their labels, drawn so its line or bars can animate in.\n- A diagram of the process the copy describes, with the copy's step names on it.\n- A device frame holding one of the above.\n\nA figure is complete on its own and it moves (the motion skill). It is the fallback inside every image spot.\n\n## Image spots\n\nSpecShot fills a spot with a photo it generates on the workspace's own image key after the page is saved. The markup, exactly:\n\n```html\n<figure class=\"hero__media\" data-ss-image=\"A sunlit dental clinic reception with a patient checking in at a tablet, warm natural light, shallow depth of field, no text\" data-ss-aspect=\"4:3\" data-ss-alt=\"A patient checking in at the front desk\">\n <!-- the drawn fallback figure, complete and good on its own -->\n</figure>\n```\n\n- `data-ss-image` is the photo prompt: what it shows, the setting, the light and the mood. No text, logos or brand names in the photo.\n- `data-ss-aspect` is one of 16:9, 4:3, 1:1, 3:4 or 9:16. `data-ss-alt` is the alt text.\n- At most four spots on a page and one in a section: the hero first, then the sections that most need a photo.\n- The figure takes its size from its layout (an `aspect-ratio` or a grid area), never from the photo.\n- Never write an img for a spot and never style `.ss-image`: SpecShot inserts the image and its style.\n\n## Sources, in order\n\n1. The client's own pictures, from the placeable images, go straight into a src.\n2. Image spots for the photos nobody supplied. Over MCP, generate_image makes one now.\n3. Drawn figures everywhere else, and as every spot's fallback.\n\nNever a placeholder image host and never a hotlinked image: the preview strips external images.\n\n## What never stands in for a picture\n\n- Never a scene assembled from primitive shapes: circles and rectangles arranged into a building, a garden or a person. Geometry is welcome only when it says something: a chart, a diagram, a plan with real labels.\n- No grain or noise over a ground (no feTurbulence filter), and no dot grid or stripe behind a section.\n- No radial glow or soft blob standing in for a visual, and never an empty frame.\n\n## Placing pictures\n\n- Show an image large: at least half the row on a desktop. A fixed `aspect-ratio`, `object-fit: cover`, real alt text.\n- Layer it: a stat chip or a review card over its edge on `--shadow-3`, the picture itself on `--shadow-4` in the hero.\n- Text on a photograph sits on an overlay drawn from the ground color, measured at 4.5:1.\n- The hero's image loads at once (no `loading=\"lazy\"`, `fetchpriority=\"high\"`). Every image below the first screen takes `loading=\"lazy\"` and `decoding=\"async\"`.\n- One treatment across the page: the same warmth, contrast, radius and crop habit.\n- People without photographs are monograms: initials in the display face on an `--accent-quiet` disc.\n\n## Check before you save\n\n- Do the hero and at least two more sections carry a figure, a spot or a real image?\n- Does every spot carry all three attributes and a drawn fallback, with no img inside it?\n- Is every figure drawn from the page's own content, with no shape-built scene and no empty box?"
335
347
  },
336
348
  "typography": {
337
349
  "id": "typography",
@@ -351,8 +363,8 @@ export const SKILL_BODIES = {
351
363
  "id": "layout-grids",
352
364
  "title": "Layout and grids",
353
365
  "kind": "foundation",
354
- "when": "Load before choosing a section's skeleton or building any grid, and when a page reads as a run of identical bands.",
355
- "body": "# Layout and grids\n\nA careful model's default page is a stack of full-width bands, each a centered heading over a row of equal cards. That is the slab, and it is the first thing a client notices. Layout is where you break it on purpose, and keep it calm while you do.\n\n## The grid and the edge\n\n- Twelve columns. Content no wider than `var(--content, 76rem)`, sides at `var(--gutter, 1.25rem)`, running text at `var(--measure, 65ch)`.\n- One content edge: every section's content and every heading start on that container's line, unless the section is deliberately centered or an image deliberately bleeds to the viewport edge.\n- Grid for two dimensions, flexbox for a single row. Never fake columns with percentage widths.\n\n## A skeleton for every section\n\nWrite the section list first and give each section one of these. Neighbors never share one.\n\n- Asymmetric split: copy over 7 columns, media over 5.\n- Bento: a lead item spanning 2 by 2 among smaller ones of mixed spans.\n- Editorial column: a large numeral or pull quote beside a 60ch column.\n- Sticky narrative: the heading holds still on one side while a list moves past on the other.\n- Zig-zag: media and text trading sides row by row.\n- Stats band: real figures with their labels, on the page's own ground or a tint.\n- Steps: numbered in type, in order, with no circles and no dotted connector.\n- Also: a comparison table, a quote spotlight, a still logo wall, a closing statement.\n- A horizontal rail only when the next item visibly peeks and the row says it scrolls. Otherwise a grid.\n\n## Spacing and rhythm\n\n- Section padding is `var(--pad-open)` or `var(--pad-dense)` and nothing else, the same above and below, alternating so the page has two speeds.\n- Every gap, margin and padding inside reads a `--space` token. Related items sit close, groups sit far apart, and more space goes above a heading than below it.\n- Nothing crosses a section's edge: no visual hanging past its section, no negative margin pulling a panel over the next one.\n\n## Balance and composition\n\n- In a two-column row, both columns carry comparable weight. A much shorter column is centered against the other or anchored on purpose.\n- Vary the openings: not every section is a heading on the left with an empty right half.\n- One element dominates each section, so the eye knows where to land.\n- No row of equal cards. Three equal boxes in a row is a default, not a decision: use a lead item, a zig-zag or a list.\n- Fewer boxes: a card only for something a person opens or picks. Group the rest with space and hairlines.\n- Left-align at least half the sections. Centering suits short statements, not everything.\n\n## Reflow without breakpoints\n\n- `grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr))` fits every width without a media query.\n- `min-width: 0` on every grid and flex child, so a long word cannot push the page sideways.\n- A breakpoint only where the layout itself changes. Inside a component, prefer a container query.\n\n## Example\n\n```css\n.split { container-type: inline-size; display: grid; grid-template-columns: repeat(12, minmax(0, 1fr)); gap: var(--space-l, 2rem); align-items: start; }\n.split__copy { grid-column: 1 / span 7; min-width: 0; }\n.split__media { grid-column: 8 / -1; }\n@container (width < 48rem) { .split__copy, .split__media { grid-column: 1 / -1; } }\n```\n\nEach class here is one block or element. How blocks, slots and loops are structured for the build follows the build law (docs/BUILD-LAW.md in the SpecShot repository, and the structure part of the design law the design_law prompt serves), which this skill leaves to it.\n\n## Check before you save\n\n- Does each pair of neighboring sections use a different skeleton?\n- Does every section's content start on one edge, with nothing past a section's edge or the viewport?\n- Is every section padded from the two rhythm tokens, the same above and below?"
366
+ "when": "Load before choosing a section's layout or building any grid, and when a page reads as a run of identical bands.",
367
+ "body": "# Layout and grids\n\nA careful model's default page is a stack of full-width bands, each a centered heading over a row of equal cards. That is the slab, and it is the first thing a client notices. Layout is where you compose the page on purpose: a different shape in every section, a bento, layers that overlap, all on one calm edge.\n\n## The grid and the edge\n\n- Twelve columns. Content no wider than `var(--content, 76rem)`, sides at `var(--gutter, 1.25rem)`, running text at `var(--measure, 65ch)`.\n- One content edge: every section's content and every heading start on that container's line, unless the section is deliberately centered or an image deliberately bleeds to the viewport edge.\n- Grid for two dimensions, flexbox for a single row. Never fake columns with percentage widths.\n\n## A layout for every section\n\nWrite the section list first and give each section one of these. Neighbors never share one.\n\n- Split: copy over 7 columns, media over 5, the media layered with a floating chip.\n- Bento: 4 to 7 tiles in at least 3 sizes, one spanning 2 columns or 2 rows, the tiles differing in content type (a stat, a mini chart, a figure, an image, a quote, a list). Every home page has one.\n- Sticky stack: the heading holds on one side while cards stack past it on the other.\n- Marquee band: the client's real names moving in a strip, paused on hover.\n- Full-bleed media: a photo or a figure edge to edge, the text over a scrim.\n- Timeline or steps: numbered in type, with a line that draws between them.\n- Also: a comparison, a testimonial wall of mixed lengths, a form panel raised beside its promise.\n- A section that is only a heading, a paragraph and a list is a draft, not a design.\n\n## Spacing and rhythm\n\n- Section padding is `var(--pad-open)` or `var(--pad-dense)` and nothing else, the same above and below, alternating so the page has two speeds.\n- Every gap, margin and padding inside reads a `--space` token. More space goes above a heading than below it.\n\n## Overlap, on purpose\n\n- At least one overlap per page: a chip over the hero visual's edge, a stat on an image corner, media rising into the section above with a negative margin.\n- The layer that crosses sits above what it crosses: `position: relative` and a z-index inside an `isolation: isolate` stack, with the section it enters padded to make room. The next section never covers it.\n\n## Balance\n\n- In a two-column row both columns carry comparable weight. A much shorter column is centered or anchored on purpose.\n- Vary the openings: not every section is a heading on the left with an empty right half.\n- One element dominates each section. No row of equal cards: use the bento, a zig-zag or a list.\n- Left-align at least half the sections. Centering suits short statements, not everything.\n\n## Reflow without breakpoints\n\n- `grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr))` fits every width without a media query.\n- `min-width: 0` on every grid and flex child, so a long word cannot push the page sideways.\n- A breakpoint only where the layout itself changes. Inside a component, prefer a container query.\n\n## Example\n\n```css\n.bento { container-type: inline-size; display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); grid-auto-rows: minmax(11rem, auto); gap: var(--space-m, 1.5rem); }\n.bento__tile--lead { grid-column: span 2; grid-row: span 2; }\n.bento__tile--wide { grid-column: span 2; }\n@container (width < 48rem) { .bento__tile--lead, .bento__tile--wide { grid-column: span 4; grid-row: auto; } }\n```\n\nEach class here is one block or element. How blocks, slots and loops are structured for the build follows the build law (docs/BUILD-LAW.md in the SpecShot repository, and the structure part of the design law the design_law prompt serves), which this skill leaves to it.\n\n## Check before you save\n\n- Does each pair of neighboring sections use a different layout, with a bento on a home page?\n- Does every section's content start on one edge, with every overlap on purpose and above what it crosses?\n- Is every section padded from the two rhythm tokens, the same above and below?"
356
368
  },
357
369
  "color-contrast": {
358
370
  "id": "color-contrast",
@@ -366,14 +378,28 @@ export const SKILL_BODIES = {
366
378
  "title": "Surfaces and elevation",
367
379
  "kind": "foundation",
368
380
  "when": "Load before giving anything a background, border, shadow, radius, divider or overlay.",
369
- "body": "# Surfaces and elevation\n\nDepth tells a visitor what sits on top of what. Keep it to a few tokens and use them by name; never invent a shadow or a radius inside a component.\n\n## Shadows\n\n- Three tokens: `--shadow-1` for cards at rest, `--shadow-2` for raised and hovered things, `--shadow-3` for overlays and a product visual.\n- Each one layers a close, crisp shadow with a wider, softer one, both tinted with the ink hue at low opacity. Every shadow has an offset and a blur. Never a colored glow with no offset, never a radial spotlight.\n- An element carries a border or a shadow, never both. A hairline usually reads better on a tinted ground; a soft shadow on the plain page ground.\n- To lift something on hover, fade in a pseudo-element that holds the bigger shadow. Never transition box-shadow directly.\n\n## Lines\n\n- Hairlines are 1px in `--line`, a low-opacity ink. The edges of controls use `--line-strong`, which keeps 3:1 against the ground.\n- On a dark ground, swap the shadow for a faint inner highlight along the top edge.\n- Use a divider only where space has not already separated two things. If the gap does the job, remove the line.\n- Never a thick colored stripe down one side of a card. That side-tab is one of the plainest template tells.\n\n## Radius\n\n- One scale, all tokens: `--radius-s` for controls and buttons, `--radius-m` for cards, panels and pictures, `--radius-l` for a very large panel, `--radius-pill` for chips and tags only. Use two on a page, a small and a large.\n- A chip uses `--radius-pill` (999px). A 50 percent radius bends a wide shape into an ellipse, so keep it for true circles such as monograms.\n- Curves stay concentric: an inner radius is the outer radius minus the padding between them.\n- The direction sets the family: almost square for editorial and Swiss work, softer for friendly brands, generous for soft and natural ones.\n\n## Grounds and surfaces\n\n- A surface needs a reason: `--paper-2` for an alternate section, `--paper-3` for a well or a track. The `--night` roles belong to a dark theme for the whole page or a dark object such as a product window, never a dark band dropped into a light page.\n- Fewer boxes. A card is for something a person opens or picks: a plan, a product, a post. Everything else is grouped by space, type and hairlines, and never a card inside a card.\n- No grain, noise texture or feTurbulence filter over a ground, and no ornament: no numbered circles on a dotted line, no badges, no divider flourish. A flat color is a finished surface.\n\n## Overlays\n\n- Text over an image sits on a gradient overlay drawn from the ground color, strongest under the text. Measure the text against the lightest or darkest point it crosses.\n- Glass belongs only where content moves underneath, such as a sticky header or a sheet: `backdrop-filter: blur(16px) saturate(140%)` over a ground at 72 to 80 percent opacity, with a solid ground for browsers without backdrop-filter.\n- A dialog or sheet takes `--shadow-3`, keeps focus inside while open and closes on Escape.\n\n## Example\n\n```css\n.panel { position: relative; background: var(--paper, oklch(98% 0.006 80)); border-radius: var(--radius-m, 14px); box-shadow: var(--shadow-1, 0 1px 2px oklch(20% 0.015 60 / 0.06)); }\n.panel::after { content: \"\"; position: absolute; inset: 0; border-radius: inherit; box-shadow: var(--shadow-2, 0 6px 16px -4px oklch(20% 0.015 60 / 0.1)); opacity: 0; transition: opacity var(--dur-2, 240ms) var(--ease-out, cubic-bezier(0.16, 1, 0.3, 1)); }\n.panel:hover::after { opacity: 1; }\n```\n\n## Check before you save\n\n- Does any element have both a border and a shadow?\n- Are there two radii, a small and a large, all of them tokens, with pills only on chips?\n- Is any card nested inside another card?"
381
+ "body": "# Surfaces and elevation\n\nDepth tells a visitor what sits on top of what, and the owner asked for it by name: \"dark shadows\". Keep it to a few tokens and use them by name; never invent a shadow or a radius inside a component.\n\n## Shadows\n\n- Four tokens: `--shadow-1` for cards at rest, `--shadow-2` for raised and hovered things, `--shadow-3` for a floating chip or card over another layer, `--shadow-4` for the hero visual.\n- Each is two or three layers: a tight contact shadow (small offset and blur, higher opacity) and a wide ambient one (large offset and blur, low opacity), tinted with the ink hue. Every shadow has an offset and a blur. Never a colored glow with no offset, never a radial spotlight.\n- On a dark page the shadows are deep: black tinted toward the brand hue at 40 to 70 percent, and a raised surface may add a 1px inset highlight along its top edge.\n- An element carries a border or a shadow, never both. The inset highlight is not a border.\n- To lift something on hover, fade in a pseudo-element that holds the bigger shadow. Never transition box-shadow directly.\n\n## Layers\n\n- Surfaces step in lightness: the ground, a panel, a card, a floating element, a few points apart and tinted toward the brand hue.\n- At least one overlap on a page: a stat chip over the hero visual's edge on `--shadow-3`, media rising into the section above with a negative margin. The layer that crosses sits above what it crosses, with `position: relative` and a z-index inside an isolated stack, and the next section never covers it.\n\n## Lines\n\n- Hairlines are 1px in `--line`, a low-opacity ink. The edges of controls use `--line-strong`, which keeps 3:1 against the ground.\n- Use a divider only where space has not already separated two things.\n- Never a thick colored stripe down one side of a card. That side-tab is one of the plainest template tells.\n\n## Radius\n\n- One scale, all tokens: `--radius-s` for controls and buttons, `--radius-m` for cards, panels and pictures, `--radius-l` for a very large panel, `--radius-pill` for chips and tags only. Use two on a page, a small and a large.\n- A 50 percent radius bends a wide shape into an ellipse, so keep it for true circles such as monograms.\n- Curves stay concentric: an inner radius is the outer radius minus the padding between them.\n\n## Grounds\n\n- A surface needs a reason: `--paper-2` for an alternate section, `--paper-3` for a well or a track. The `--night` roles belong to a dark theme for the whole page or a dark object such as a product window, never a dark band dropped into a light page.\n- Fewer boxes. A card is for something a person opens or picks, and never a card inside a card.\n- No grain, noise texture or feTurbulence filter, and no ornament. A flat color with a real shadow is a finished surface.\n\n## Overlays\n\n- Text over an image sits on a gradient overlay drawn from the ground color, strongest under the text.\n- Glass only where content moves underneath, such as a sticky header: `backdrop-filter: blur(16px)` over a ground at 72 to 80 percent opacity, with a solid ground for browsers without it.\n- A dialog or sheet takes `--shadow-3`, keeps focus inside while open and closes on Escape.\n\n## Example\n\n```css\n.panel { position: relative; background: var(--paper, oklch(98% 0.006 80)); border-radius: var(--radius-m, 0.875rem); box-shadow: var(--shadow-1, 0 1px 2px oklch(20% 0.015 60 / 0.08), 0 4px 12px -4px oklch(20% 0.015 60 / 0.08)); }\n.panel::after { content: \"\"; position: absolute; inset: 0; border-radius: inherit; box-shadow: var(--shadow-2, 0 2px 4px oklch(20% 0.015 60 / 0.08), 0 12px 24px -8px oklch(20% 0.015 60 / 0.14)); opacity: 0; transition: opacity var(--dur-2, 240ms) var(--ease-out, cubic-bezier(0.16, 1, 0.3, 1)); }\n.panel:hover::after { opacity: 1; }\n```\n\n## Check before you save\n\n- Does every raised surface use a layered elevation token, and does one layer overlap another?\n- Does any element have both a border and a shadow, or a card inside a card?\n- Are there two radii, a small and a large, all of them tokens, with pills only on chips?"
370
382
  },
371
383
  "motion": {
372
384
  "id": "motion",
373
385
  "title": "Motion and animation",
374
386
  "kind": "foundation",
375
- "when": "Load before adding any transition, entrance, hover effect, animated chart or signature interaction.",
376
- "body": "# Motion and animation\n\nMotion explains a change. It never carries content: with every animation switched off, the page is still whole, and nothing waits for a scroll to appear.\n\n## The rules\n\n- CSS only, and on time. The preview runs no scripts and the canvas never scrolls the design.\n- Move transform and opacity only. Animating width, height, top, left, margin, padding, box-shadow or filter makes the browser redo layout or paint on every frame, and it stutters on an ordinary phone.\n- One easing family and three durations: `--dur-1` (150ms) for presses and color changes, `--dur-2` (240ms) for hover, focus, open and close, `--dur-3` (400ms) for the authored moment, and `--dur-4` (80ms) as the stagger step between its items. Ease with `--ease-out`, never linear for interface motion.\n- No bounce, no overshoot, no elastic curves, and no slow fade that feels like lag.\n- Name each @keyframes for what it serves, such as `chart-grow` or `panel-open`, and never a generic name like fadeIn: keyframe names are global on the client's site and collide.\n- No glowing halos on hover. Emphasis comes from a small rise, a step up in shadow or an overlay.\n\n## The quiet system on every page\n\n- Buttons: lift 1px on hover and scale to 0.98 when pressed. The hover color arrives as a pseudo-element overlay fading in, so only opacity moves.\n- Links: the underline draws in from the left with a pseudo-element, `transform: scaleX(0)` to `scaleX(1)`.\n- A card a person can pick: a pseudo-element carrying `--shadow-2` fades in.\n- Focus: a 2px accent ring 2px outside every focusable element on `:focus-visible`.\n\n## One authored moment\n\nExactly one per page, tied to a state change: the product's key data arriving, a chart drawing its bars, the hero settling on load. Staggered, never all at once, and never repeated on every section.\n\n```css\n@media (prefers-reduced-motion: no-preference) {\n .chart__bar { animation: chart-grow var(--dur-3, 400ms) var(--ease-out, cubic-bezier(0.16, 1, 0.3, 1)) both; animation-delay: calc(var(--i, 0) * var(--dur-4, 80ms)); }\n}\n@keyframes chart-grow { from { transform: scaleX(0); } }\n```\n\n- The hidden look exists only in the keyframe's from block. The element's own style is its final, visible state, so older browsers, reduced-motion readers and the SpecShot canvas all see it.\n- Give it a still version for reduced motion, and a tap version for touch where it follows a pointer.\n\n## What never moves\n\n- Never scroll-driven content: no `animation-timeline: view()` reveal on sections. A canvas frame, a full-page screenshot and a print see half the page blank or faded, content left at opacity 0 for a scroll that never comes.\n- Never an element at `opacity: 0` in its base style.\n- No marquee, no pulsing dot, no fake typing cursor, no rotating mesh and no endless sweep. Only a real loading indicator runs until it is done.\n\n## Reduced motion, scoped\n\n- Put each animation and transition inside `@media (prefers-reduced-motion: no-preference)`, or switch it off in a reduce block that names its own selectors.\n- Never a global reset on `*`: it kills motion the brief asked to keep and hides which motion was authored.\n\n## Check before you save\n\n- With motion turned off, is every piece of content visible?\n- Is anything animated other than transform and opacity, or on more than one easing?\n- Is there exactly one authored moment, on time, with nothing scroll-driven and nothing looping?"
387
+ "when": "Load before adding any transition, entrance, reveal, hover state, floating figure, marquee, animated chart or signature interaction.",
388
+ "body": "# Motion and animation\n\nThe owner rated a still page 10 out of 100. A page is alive: it settles on load, its sections arrive as they scroll in, its figures move, and everything answers the pointer. It is also smooth: nothing jumps, nothing lags, and with motion switched off the page is whole.\n\n## Tokens\n\n- `--ease-out: cubic-bezier(0.16, 1, 0.3, 1)` for entrances and interface motion. `--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1)` for a floating figure.\n- `--dur-1` 150ms press, `--dur-2` 240ms hover and focus, `--dur-3` 400ms a panel, `--dur-4` 700ms entrances, `--dur-5` 1200ms a figure drawing in, `--stagger` 80ms.\n- Never bounce, overshoot or elastic. Never linear for interface motion: linear only for a marquee or a continuous rotation.\n\n## 1. The load entrance\n\nThe hero's heading, text, actions and visual enter in sequence, each over `--dur-4`, staggered by `--stagger` through a `--i` index. The floating chips arrive last.\n\n```css\n@media (prefers-reduced-motion: no-preference) {\n .hero__copy > * { animation: hero-copy-settle var(--dur-4) var(--ease-out) both; animation-delay: calc(var(--i, 0) * var(--stagger)); }\n}\n@keyframes hero-copy-settle { from { opacity: 0; transform: translateY(1.25rem); } }\n```\n\n## 2. Scroll reveals, in the safe form only\n\n```css\n@media screen and (prefers-reduced-motion: no-preference) {\n @supports (animation-timeline: view()) {\n .bento__tile { animation: bento-tile-rise var(--ease-out) both; animation-timeline: view(); animation-range: entry 5% entry 60%; }\n }\n}\n@keyframes bento-tile-rise { from { opacity: 0; transform: translateY(2.5rem) scale(0.97); } }\n```\n\n- The base style is visible. The hidden look lives only in the keyframe's from block, so a print, a capture, a canvas frame and an older browser show the finished page.\n- Each section reveals its own way: a rise, a scale-in, a slide from the side the content sits on, children staggered by `--i`. Never one reveal on every section, never linear, and never a class that hides content until a script adds another.\n\n## 3. Moving figures, two to four\n\n- A floating chip or card: translateY 6 to 12px, 5 to 9s, `--ease-in-out`, alternate, infinite.\n- A chart line that draws itself: `stroke-dashoffset` over `--dur-5`, once, then holds.\n- A slow orbit of a ring around the hero visual: 20 to 40s, linear.\n- A bar or progress fill that grows to its value on reveal, with `transform: scaleX()`.\n- A marquee band of the client's real names: the second copy `aria-hidden=\"true\"`, the edges masked, 30 to 60s, paused on hover and on focus-within.\n- Every figure shows something from the page: a panel, a labeled chart, a flow from the copy. Never an abstract blob, and never a loop under 4 seconds on anything but a loader.\n\n```css\n@media (prefers-reduced-motion: no-preference) {\n .hero__chip { animation: hero-chip-float 7s var(--ease-in-out) infinite alternate; }\n .marquee__track { animation: marquee-track-slide 40s linear infinite; }\n .marquee:hover .marquee__track, .marquee:focus-within .marquee__track { animation-play-state: paused; }\n}\n@keyframes hero-chip-float { to { transform: translateY(-10px); } }\n@keyframes marquee-track-slide { to { transform: translateX(-50%); } }\n```\n\n## 4. The interaction system\n\n- Buttons lift 1 to 2px on hover and press to `scale(0.98)`.\n- Cards and tiles lift 4px while a pseudo-element carrying `--shadow-2` fades in. Never animate box-shadow itself.\n- An image in a frame scales to 1.04 on hover over `--dur-4`. Links draw their underline with `scaleX`.\n- Every focusable element shows a 2px accent ring at a 2px offset on `:focus-visible`.\n\n## 5. Smoothness\n\n- Every state change has a transition. Nothing faster than 150ms, and no entrance slower than 1200ms.\n- Animate transform and opacity only. Never width, height, top, left, margin, padding, box-shadow or filter.\n- Name each keyframe for what it serves, never a bare fadeIn: names are global on the client's site.\n- Every animation sits under `prefers-reduced-motion: no-preference`, or a reduce block names its selectors. Never a global reset on `*`.\n\n## Check before you save\n\n- Does the hero settle on load, does each section reveal its own way, and do two to four figures move?\n- Is every reveal in the safe form, with the page whole when motion is off?\n- Does every button, card and link answer hover, press and focus?"
389
+ },
390
+ "copywriting": {
391
+ "id": "copywriting",
392
+ "title": "Website copy that converts",
393
+ "kind": "foundation",
394
+ "when": "Load before writing or rewriting any words on a page: headlines, sections, calls to action, proof, forms and messages.",
395
+ "body": "# Website copy that converts\n\nCopy carries the page. The design makes it easy to read; the words make the visitor act. Write for one reader, the client's customer, and say what they get.\n\n## Voice\n\n- The client's voice, from the brief and the copy blocks. An approved block is used word for word. A draft block beats anything you would write.\n- Human, clear, direct and practical. Short sentences, short paragraphs, active voice, simple words. Address the reader as \"you\".\n- No filler, no hype and no buzzwords (streamline, empower, supercharge, world-class, next-generation, seamless, elevate). No em dashes, no semicolons, no emojis. Every sentence ends with a period.\n\n## Headlines\n\n- A headline says the reader's outcome in the client's terms, in under ten words, in at most three lines. Specific beats clever: \"Same-week crowns, fitted in one visit\" says more than \"Smiles, reimagined\".\n- A section heading says what the section proves or answers. A visitor who reads only the headings should know the offer, the proof and the next step.\n\n## Body\n\n- Benefit first, then the proof: the feature, the number or the example that makes it true. Every paragraph answers \"so what for me\".\n- Numbers only from the client's own material: 47 reviews, 12 years, a 2-day turnaround. Never a round, made-up statistic. A missing fact is left out, never invented.\n- Scannable: one idea per paragraph, two or three sentences each, lists for steps and features, bold for a key phrase and never for a whole sentence.\n\n## Calls to action\n\n- One primary action per page, in the hero, in the middle and at the close, with the same words each time.\n- The label says what happens: \"Book a free consult\", \"Get my audit\". Never \"Submit\", and never \"Learn more\" as the main action.\n- Beside the primary action, a lower-commitment one (\"See pricing\", \"Read a case study\").\n- Near every primary action, one short trust line from the client's facts: how fast they answer, what it costs to start, what happens next.\n\n## Proof and objections\n\n- Testimonials, client names and logos come only from the client's material, attributed exactly as given. Without them, prove with the process, a guarantee the client offers, or facts they gave.\n- Answer the three questions that stop people (cost, time, risk) in the copy or the FAQ.\n\n## The order of a home page\n\nWho it is for and the outcome, with the action. Proof early. What the client offers. How it works. Proof again. The questions. The close, with the action and its trust line.\n\n## Small words\n\n- Form labels sit above their fields and say what to enter. Helper text says why a field is asked for.\n- An error says what went wrong and how to fix it. A success message says what happens next and when.\n- Empty states and buttons use the same plain verbs as the rest of the page."
396
+ },
397
+ "seo": {
398
+ "id": "seo",
399
+ "title": "On-page SEO and AI search visibility",
400
+ "kind": "foundation",
401
+ "when": "Load before designing any page, and before writing its headings, links, image text or FAQ.",
402
+ "body": "# On-page SEO and AI search visibility\n\nA page is read by people, by search engines and by AI assistants. All three reward the same things: a clear topic, facts stated plainly, a structure that says what each part answers, and a page that loads fast without shifting. Nothing here is a trick.\n\n## Structure\n\n- One `h1`, carrying the page's main topic in the client's own words. For a local business it names the service and the place: \"Dental implants in Austin\", not \"Smiles that last\".\n- Headings in order with no skipped level. Each `h2` names what its section answers or proves.\n- Landmarks: one `header`, one `nav` for the main menu, one `main`, one `footer`.\n- Every fact, heading and link is text in the markup. Never only in an image, a CSS `content` value or an SVG without a text equivalent.\n\n## Words search reads\n\n- The main topic appears in the `h1`, in the first paragraph and in one `h2`, naturally. Related terms go in other headings and the body. Never repeat a phrase to rank.\n- Answer first: each section opens with one plain sentence that answers its question, then the detail. That sentence is what a search snippet or an assistant quotes.\n- Service and home pages carry an FAQ of the questions customers really ask, from the brief or the client's copy: each answer 40 to 60 words, its first sentence the answer itself.\n- Facts the client gave are stated plainly, once, and the same everywhere: services, area served, hours, phone, address, prices. A missing fact is left out, never invented.\n\n## Links\n\n- Internal links say where they go: \"See implant pricing\", \"Read how a visit works\". Never \"click here\" alone, and \"Learn more\" only beside a heading that names the topic.\n- A page links to at least three related pages: in the content, the actions and the footer. Something that navigates is an `a` with a real `href`, not a button.\n\n## Images and media\n\n- Every meaningful image has alt text that says what it shows and why it is there. A decorative image has `alt=\"\"`, a decorative SVG `aria-hidden=\"true\"`. An image spot carries its alt text in `data-ss-alt`.\n- Every image and media frame has a size before it loads (`width` and `height`, or an `aspect-ratio`), so nothing shifts. Images below the first screen load lazily. The hero's image never does.\n\n## Speed is part of SEO\n\n- No layout shift from fonts or images. Fonts swap in with a matched fallback.\n- Motion moves transform and opacity only, and no large area carries a heavy blur or filter.\n- The page is complete and readable with no script.\n\n## Head and structured data\n\nThe plugin's SEO suite writes the title, the meta description and the structured data when the site is deployed. The design makes them true:\n\n- The page's topic and the client's facts are visible on the page, so the title (50 to 60 characters, the topic then the brand), the description (140 to 160 characters, with a reason to click) and the structured data all match what a visitor reads.\n- Structured data only ever restates visible facts: the business (name, phone, address, area served, hours), its services, the FAQ exactly as shown, and breadcrumbs on inner pages.\n\n## Never\n\n- Hidden text, keyword stuffing, text written for crawlers or assistants, invented reviews, ratings, awards or credentials. They get a site penalized and they break the client's trust."
377
403
  },
378
404
  "accessibility": {
379
405
  "id": "accessibility",
@@ -394,7 +420,7 @@ export const SKILL_BODIES = {
394
420
  "title": "The Etch and ACSS build",
395
421
  "kind": "build",
396
422
  "when": "Load before building any page or section that will go to Etch, which is every SpecShot design, and before running get_etch_build.",
397
- "body": "# The Etch and ACSS build\n\nEvery SpecShot design has to build into Etch with nothing lost. When the page is written the way the export reads it, the agency gets something they can edit in Etch rather than something they rebuild.\n\n## Write it the way Etch reads it\n\n- One class per rule, named in BEM: `.block`, `.block__element`, `.block--modifier`. States and pseudo-elements on that class are fine. A single-class rule becomes an Etch class style the agency can find and edit; `.hero h1` or `section > div` ends up as a page-level rule nobody can find.\n- Give the h1 a class instead of styling h1.\n- Inside `@supports`, `@container` and `@layer`, select by class only. Those blocks travel into the site's stylesheet whole, and a bare tag there restyles the whole site.\n- Name keyframes for their block (`hero-entrance`), because keyframe names are global on the site.\n- Theme dark mode with `@media (prefers-color-scheme: dark)` or a modifier on the design's own root (`.page--dark`). Never `:root[data-theme]` or `html[data-theme]`: in Etch the design is one block inside the client's page, and :root belongs to the site.\n- Never a font-size on html or :root (rem means the site's root size in Etch), never an `#id` selector, never `!important` outside a reduced-motion block.\n- One page, one root: body holds the header, main and footer, and nothing is positioned against html or body.\n\nHow components, slots, loops and the class workflow are structured for Etch follows the build law (docs/BUILD-LAW.md in the SpecShot repository, and the structure part of the design law the design_law prompt serves); this skill does not repeat it.\n\n## Tokens, and how ACSS sites take them\n\n- Declare the canonical tokens once in :root and read them everywhere with a literal fallback. One name per role, the contract's name.\n- On export, every token the design declares gets the project's prefix (`--space-m` becomes `--acme-space-m`), so nothing clashes with the site or with another design.\n- When the Etch page runs Automatic.css, the mapped tokens follow the site and keep the design's value as the fallback: `--space-xs` to `--space-xl` follow ACSS's spacing steps and `--space-2xl` its xxl, `--pad-open` follows `--section-space-m`, `--step-0` `--text-m`, `--step-3` `--h2`, `--step-5` `--h1`, `--radius-m` `--radius`, `--accent` `--primary`, `--ink` `--text-dark`, `--font-display` `--heading-font-family`. Where ACSS is absent, the design's own values apply.\n- Some tokens always keep the design's values because ACSS has no safe match: the grounds (`--paper`, `--night`), `--space-3xs`, `--space-2xs`, `--space-3xl`, `--step-4`, `--step-6`, `--radius-pill`, the shadows and the motion tokens.\n- SpecShot's `--accent` is the site's primary action color, which is why it follows ACSS's `--primary`.\n- Never write ACSS variable names by hand. A name the design reads but never declares is left as the site's own, so on a site without ACSS it resolves to nothing.\n- A design never changes the site's ACSS settings. Tuning the site is the agency's call, made in ACSS.\n\n## Images and fonts\n\n- Images only from a placeableUrl, and diagrams and icons as inline SVG. A placeable image becomes an asset the agency uploads to the media library; a linked image from elsewhere is a broken image on the site.\n- Embed the faces in the design so the preview shows them. The site installs the same families separately, and the build lists them.\n\n## Before it goes to Etch\n\n1. Save the design and read `designLaw`. Fix every `etch-*` finding and every block finding, then revise the same design.\n2. Over MCP, read the etch_ready prompt, then call get_etch_build with the design's id. Read the prefix, the renamed variables, the rules and the warnings, and pass on what they say.\n3. When the Etch page already holds an earlier build of this design, use dryRun first.\n4. Tell the owner which fonts to install and which images to upload.\n\n## Check before you save\n\n- Is every rule a single BEM class, with no ids, no html font-size and no stray !important?\n- Is every token a canonical name declared once, with no ACSS names written by hand?\n- Is every keyframe named for its block?"
423
+ "body": "# The Etch and ACSS build\n\nEvery SpecShot design has to build into Etch with nothing lost. When the page is written the way the export reads it, the agency gets something they can edit in Etch rather than something they rebuild.\n\n## Write it the way Etch reads it\n\n- One class per rule, named in BEM: `.block`, `.block__element`, `.block--modifier`. States and pseudo-elements on that class are fine. A single-class rule becomes an Etch class style the agency can find and edit; `.hero h1` or `section > div` ends up as a page-level rule nobody can find.\n- Give the h1 a class instead of styling h1.\n- Inside `@supports`, `@container` and `@layer`, select by class only. Those blocks travel into the site's stylesheet whole, and a bare tag there restyles the whole site.\n- Name keyframes for their block (`hero-entrance`), because keyframe names are global on the site.\n- Theme dark mode with `@media (prefers-color-scheme: dark)` or a modifier on the design's own root (`.page--dark`). Never `:root[data-theme]` or `html[data-theme]`: in Etch the design is one block inside the client's page, and :root belongs to the site.\n- Never a font-size on html or :root (rem means the site's root size in Etch), never an `#id` selector, never `!important` outside a reduced-motion block.\n- One page, one root: body holds the header, main and footer, and nothing is positioned against html or body.\n\nHow components, slots, loops and the class workflow are structured for Etch follows the build law (docs/BUILD-LAW.md in the SpecShot repository, and the structure part of the design law the design_law prompt serves); this skill does not repeat it.\n\n## Tokens, and how ACSS sites take them\n\n- Declare the canonical tokens once in :root and read them everywhere with a literal fallback. One name per role, the contract's name.\n- On export, every token the design declares gets the project's prefix (`--space-m` becomes `--acme-space-m`), so nothing clashes with the site or with another design.\n- When the Etch page runs Automatic.css, the mapped tokens follow the site and keep the design's value as the fallback: `--space-xs` to `--space-xl` follow ACSS's spacing steps and `--space-2xl` its xxl, `--pad-open` follows `--section-space-m`, `--step-0` `--text-m`, `--step-3` `--h2`, `--step-5` `--h1`, `--radius-m` `--radius`, `--gutter` `--gutter`, `--accent` `--primary`, `--ink` `--text-dark`, `--paper-2` `--bg-ultra-light`, `--night` `--bg-ultra-dark`, `--font-display` `--heading-font-family`. Where ACSS is absent, the design's own values apply. Whether the page runs ACSS is Etch's to say: its skills list names an acss skill only while ACSS is active.\n- Some tokens always keep the design's values because ACSS has no safe match: the page ground `--paper`, `--night-2`, `--space-3xs`, `--space-2xs`, `--space-3xl`, `--step-4`, `--step-6`, `--radius-pill`, the shadows and the motion tokens.\n- SpecShot's `--accent` is the site's primary action color, which is why it follows ACSS's `--primary`.\n- Never write ACSS variable names by hand. A name the design reads but never declares is left as the site's own, so on a site without ACSS it resolves to nothing.\n- A design never changes the site's ACSS settings. Tuning the site is the agency's call, made in ACSS.\n\n## Images and fonts\n\n- Images only from a placeableUrl, and diagrams and icons as inline SVG. A placeable image becomes an asset the agency uploads to the media library; a linked image from elsewhere is a broken image on the site.\n- Embed the faces in the design so the preview shows them. The site installs the same families separately, and the build lists them.\n\n## Before it goes to Etch\n\n1. Save the design and read `designLaw`. Fix every `etch-*` finding and every block finding, then revise the same design.\n2. Over MCP, read the etch_ready prompt, then call get_etch_build with the design's id. Read the prefix, the renamed variables, the rules and the warnings, and pass on what they say.\n3. When the Etch page already holds an earlier build of this design, use dryRun first.\n4. Tell the owner which fonts to install and which images to upload.\n\n## Check before you save\n\n- Is every rule a single BEM class, with no ids, no html font-size and no stray !important?\n- Is every token a canonical name declared once, with no ACSS names written by hand?\n- Is every keyframe named for its block?"
398
424
  },
399
425
  "agency-process": {
400
426
  "id": "agency-process",
@@ -436,21 +462,21 @@ export const SKILL_BODIES = {
436
462
  "title": "Design QA gate",
437
463
  "kind": "page",
438
464
  "when": "Load before calling a page done or handing it to a client: the per-page checks, content stress cases, media rules and performance budgets, each with its evidence.",
439
- "body": "# Design QA gate\n\nWhat a page passes before anyone calls it done. Record each check as Pass, Fail, Blocked or Not applicable, with the screenshot, render or source that shows it. A saved page alone is not evidence, and every Fail gets an owner and a retest. The design_review prompt grades the craft; this gate checks that the page works.\n\n## Purpose and content\n\n- The page's purpose fits in one sentence, and one primary action dominates. Secondary actions never compete with it.\n- The H1 states the page's promise or task, and the first screen says who the page is for and what happens next.\n- Every claim, number, quote, logo and award is verified or left out. No fake urgency, scarcity or proof.\n- No gap marker is left in copy that goes live.\n- The existing templates and components were read before anything changed.\n\n## Content stress\n\n- Long, short, missing and empty content each still look intentional.\n- Long headings, long links, long names and translated text about a third longer were tried.\n- Missing media, missing optional fields and an empty list were tried. An optional field leaves no empty wrapper or stray separator, and an empty list collapses or shows its empty state.\n\n## Widths and zoom\n\n- The page is composed on purpose at 360 and 390 pixels wide, across tablet widths, on a laptop and on a desktop. On an ultrawide screen the content stays bounded.\n- At 200 percent zoom every control still works, and narrow reflow causes no sideways scroll.\n- Sticky headers and a phone's safe areas never cover content or the focus ring.\n\n## Access\n\n- A skip link reaches the main content. One main landmark, one H1, headings in order.\n- The keyboard path works forward and back, focus is always visible, and color is never the only signal.\n- Text and controls pass contrast in every theme the design ships. Icon-only controls have names, a dialog holds and returns focus, and a form has visible labels, the right input types, autocomplete and errors tied to their fields.\n- With reduced motion, content and function stay. The core task works without scripts, or has another route.\n\n## Motion\n\n- Each animation has a purpose, and the page has at most one signature interaction.\n- Motion runs on transform and opacity, and touch and keyboard get what a pointer gets.\n- No scroll hijacking, no fake delay, no bounce easing.\n\n## Media\n\n- Every image has a job, a source and the right to use it. No fabricated customer, result, testimonial, interface or partner.\n- Width and height or an aspect ratio are reserved, images are responsive and in modern formats, and each crop works at every width.\n- Text over an image stays live text and stays legible in every theme.\n\n## Performance budgets\n\nMeet each budget, or record the named blocker that stops it:\n\n- Largest contentful paint (LCP) 2.5 seconds or less.\n- Interaction to next paint (INP) 200 milliseconds or less.\n- Cumulative layout shift (CLS) 0.1 or less.\n- Delivered CSS 150 KB or less.\n- The first view weighs 1.5 MB or less.\n\nAlso: the H1 and the primary action render without waiting for motion or media, no motion script ships without a named reason, a failed third-party script leaves the page usable, a form blocks a double submit and offers recovery, and no credential, private data, staging address or internal note appears.\n\n## Search and consent\n\n- One search intent owns the page. Title, description, slug, H1, canonical and internal links agree, and structured data matches what is visible.\n- Analytics respect consent, and privacy and legal wording matches what the site really does.\n\n## Evidence, then approval\n\n- The saved source, the computed styles and a real render in Chromium and WebKit were checked at the widths above. On WordPress, check_built_page compares the built page with the approved design.\n- Keyboard and reduced-motion checks are recorded, and a form was sent end to end.\n- Passing this gate approves the page. Publishing is a separate decision, and it is the owner's."
465
+ "body": "# Design QA gate\n\nWhat a page passes before anyone calls it done. Record each check as Pass, Fail, Blocked or Not applicable, with the screenshot, render or source that shows it. A saved page alone is not evidence, and every Fail gets an owner and a retest. The design_review prompt grades the craft; this gate checks that the page works.\n\n## Purpose and content\n\n- The page's purpose fits in one sentence, and one primary action dominates. Secondary actions never compete with it.\n- The H1 states the page's promise or task, and the first screen says who the page is for and what happens next.\n- Every claim, number, quote, logo and award is verified or left out. No fake urgency, scarcity or proof.\n- No gap marker is left in copy that goes live.\n- The existing templates and components were read before anything changed.\n\n## Content stress\n\n- Long, short, missing and empty content each still look intentional.\n- Long headings, long links, long names and translated text about a third longer were tried.\n- Missing media, missing optional fields and an empty list were tried. An optional field leaves no empty wrapper or stray separator, and an empty list collapses or shows its empty state.\n\n## Widths and zoom\n\n- The page is composed on purpose at 360 and 390 pixels wide, across tablet widths, on a laptop and on a desktop. On an ultrawide screen the content stays bounded.\n- At 200 percent zoom every control still works, and narrow reflow causes no sideways scroll.\n- Sticky headers and a phone's safe areas never cover content or the focus ring.\n\n## Access\n\n- A skip link reaches the main content. One main landmark, one H1, headings in order.\n- The keyboard path works forward and back, focus is always visible, and color is never the only signal.\n- Text and controls pass contrast in every theme the design ships. Icon-only controls have names, a dialog holds and returns focus, and a form has visible labels, the right input types, autocomplete and errors tied to their fields.\n- With reduced motion, content and function stay. The core task works without scripts, or has another route.\n\n## Motion\n\n- The page is alive: a load entrance, scroll reveals that differ by section in the safe form, two to four moving figures, and hover, press and focus on every control. Each animation has a purpose.\n- Motion runs on transform and opacity, and touch and keyboard get what a pointer gets.\n- No scroll hijacking, no fake delay, no bounce easing.\n\n## Media\n\n- Every image has a job, a source and the right to use it. No fabricated customer, result, testimonial, interface or partner.\n- Width and height or an aspect ratio are reserved, images are responsive and in modern formats, and each crop works at every width.\n- Text over an image stays live text and stays legible in every theme.\n\n## Performance budgets\n\nMeet each budget, or record the named blocker that stops it:\n\n- Largest contentful paint (LCP) 2.5 seconds or less.\n- Interaction to next paint (INP) 200 milliseconds or less.\n- Cumulative layout shift (CLS) 0.1 or less.\n- Delivered CSS 150 KB or less.\n- The first view weighs 1.5 MB or less.\n\nAlso: the H1 and the primary action render without waiting for motion or media, no motion script ships without a named reason, a failed third-party script leaves the page usable, a form blocks a double submit and offers recovery, and no credential, private data, staging address or internal note appears.\n\n## Search and consent\n\n- One search intent owns the page. Title, description, slug, H1, canonical and internal links agree, and structured data matches what is visible.\n- Analytics respect consent, and privacy and legal wording matches what the site really does.\n\n## Evidence, then approval\n\n- The saved source, the computed styles and a real render in Chromium and WebKit were checked at the widths above. On WordPress, check_built_page compares the built page with the approved design.\n- Keyboard and reduced-motion checks are recorded, and a form was sent end to end.\n- Passing this gate approves the page. Publishing is a separate decision, and it is the owner's."
440
466
  },
441
467
  "etch-development": {
442
468
  "id": "etch-development",
443
469
  "title": "Etch development",
444
470
  "kind": "build",
445
471
  "when": "Load when the owner says start development, before building an approved design into Etch, and before driving an Etch tab through the Etch Connector.",
446
- "body": "# Etch development\n\nHow the development phase runs. The approved SpecShot design is built into Etch, then refined there through the Etch Connector. The structure and CSS rules are etch-structure and etch-css, and the runtime facts are etch-connector-runtime.\n\n## Starting development\n\n1. Confirm the project and that the client approved the design for each page (get_project_state). Build the approved design, never a wireframe.\n2. Confirm the platform: Etch on WordPress or Etch Studio. Ask outright; never infer it from a default.\n3. Confirm what the site is: a new build, a rebuild, staging or live production. It decides what may be touched, and anything unclear is production.\n4. Build the design with Build in Etch. Over MCP, read the etch_ready prompt and call get_etch_build with dryRun first, then run its script with the connector. The owner may instead press Build in Etch in the extension's side panel, in the canvas dialog, or in the SpecShot plugin's Etch panel on WordPress (list_wordpress_sites shows whether a site is connected).\n5. For work by hand, start the connector every session with `npx @digital-gravy/etch-connector serve`, even when the builder's AI button still looks on. Read `etch-connector --help` in full, and use the tab the owner names, checking `tabs` for duplicate names before working on two sites.\n\n## What may be touched\n\n- Without asking per change: a new build, a rebuild on a development or staging site, the agency's own sites.\n- Ask every time: a client's live production site.\n- Never, on any site: logins, plugin installs or updates, theme files, hosting, DNS, publishing or deploying. Draft it and hand it over.\n\n## How the work runs\n\n- Read before you write: query the blocks and styles and return them first.\n- Make small, reviewable changes, one section or component at a time. Say what is about to happen, do it, and say what changed.\n- Batch, then save. Blocks, styles and loops persist only on `await etch.saveAsync()`; stylesheets, components and fields write at once.\n- Verify on the front end, not only in the builder, which can show a change the page does not have yet. On WordPress, check_built_page compares the built page with the approved design once the build is recorded.\n- Flag every inference (a button color, a breakpoint, a variable) as an inference.\n- Stop and ask before anything destructive: deleting blocks, replacing a section, or changing a global stylesheet or a component other pages use.\n- Record progress with update_concept_status (sent when the build starts, built when it is complete) and add_build_note.\n\n## Scripts and names\n\n- Run a script with `etch-connector eval -t <tab> \"<js>\"`, or `-f file.js` for anything longer, kept in the client's local scratch folder. In zsh, wrap the command in a function rather than a string variable.\n- A script runs as an async function: await, and return a value, which comes back as JSON. Read state before mutating it.\n- Tabs run in safe mode: the etch global and standard JavaScript only, with no window and no document.\n- The Etch API is experimental. Ask the runtime instead of guessing: `etch.environment` lists the product, capabilities and block types (when it is missing, assume everything is available), and `typeof etch.x.method === \"function\"` checks one method.\n- Errors come back as EtchApiError with a code, such as BLOCK_NOT_FOUND, READONLY, INVALID_ARGUMENT or NOT_AVAILABLE. Read it, report it plainly and stop, unknown codes included.\n- Never invent an API method, a block type or a variable name.\n\n## An ACSS settings file from the design\n\n1. On WordPress with the SpecShot plugin, prefer its brand pass: it maps the brand to ACSS settings with a dry run and a per-key diff, and the owner applies it with an automatic backup.\n2. Otherwise ask the owner for an ACSS settings export from one of their sites. It is the template: never write a settings file from scratch or invent a key.\n3. Read the design's numbers from the Design Direction board and the brand (get_brand_system): colors, fonts, the heading and text scales (base and ratio, desktop and mobile), the button style, the radius.\n4. Change only keys that already exist in the export. A color often appears in several forms (hex, OKLCH, sometimes HSL), so update every form until they agree. Font file paths point at the old site: flag them.\n5. Save it in the client's local folder with a short list of every change in plain words, so it can also be done by hand. Importing is the owner's, since it changes a site's settings."
472
+ "body": "# Etch development\n\nHow the development phase runs. The approved SpecShot design is built into Etch, then refined there through the Etch Connector. The structure and CSS rules are etch-structure and etch-css, and the runtime facts are etch-connector-runtime.\n\n## Starting development\n\n1. Confirm the project and that the client approved the design for each page (get_project_state). Build the approved design, never a wireframe.\n2. Confirm the platform: Etch on WordPress or Etch Studio. Ask outright; never infer it from a default.\n3. Confirm what the site is: a new build, a rebuild, staging or live production. It decides what may be touched, and anything unclear is production.\n4. Build the design with Build in Etch. Over MCP, read the etch_ready prompt and call get_etch_build with dryRun first, then run its script with the connector. The owner may instead press Build in Etch in the extension's side panel, in the canvas dialog, or in the SpecShot plugin's Etch panel on WordPress (list_wordpress_sites shows whether a site is connected).\n5. For work by hand, start the connector every session with `npx @digital-gravy/etch-connector serve`, even when the builder's AI button still looks on. Read `etch-connector --help` in full, and use the tab the owner names, checking `tabs` for duplicate names before working on two sites.\n\n## What may be touched\n\n- Without asking per change: a new build, a rebuild on a development or staging site, the agency's own sites.\n- Ask every time: a client's live production site.\n- Never, on any site: logins, plugin installs or updates, theme files, hosting, DNS, publishing or deploying. Draft it and hand it over.\n\n## How the work runs\n\n- Read before you write: query the blocks and styles and return them first.\n- Make small, reviewable changes, one section or component at a time. Say what is about to happen, do it, and say what changed.\n- Batch, then save. Blocks, styles and loops persist only on `await etch.saveAsync()`; stylesheets, components and fields write at once.\n- Verify on the front end, not only in the builder, which can show a change the page does not have yet. On WordPress, check_built_page compares the built page with the approved design once the build is recorded.\n- Flag every inference (a button color, a breakpoint, a variable) as an inference.\n- Stop and ask before anything destructive: deleting blocks, replacing a section, or changing a global stylesheet or a component other pages use.\n- Record progress with update_concept_status (sent when the build starts, built when it is complete) and add_build_note.\n\n## Scripts and names\n\n- Run a script with `etch-connector eval -t <tab> --timeout <ms> \"<js>\"`, or `-f file.js` for anything longer, kept in the client's local scratch folder. Every run names its tab and a timeout. In zsh, wrap the command in a function rather than a string variable.\n- A script runs as an async function: await, and return a value, which comes back as JSON. Read state before mutating it.\n- Tabs run in safe mode: the etch global and standard JavaScript only, with no window and no document.\n- The Etch API is experimental. Ask the runtime instead of guessing: `etch.environment` lists the product, capabilities and block types (when it is missing, assume everything is available), and `typeof etch.x.method === \"function\"` checks one method.\n- Errors come back as EtchApiError with a code, such as BLOCK_NOT_FOUND, READONLY, INVALID_ARGUMENT or NOT_AVAILABLE. Read it, report it plainly and stop, unknown codes included.\n- Never invent an API method, a block type or a variable name.\n\n## An ACSS settings file from the design\n\n1. On WordPress with the SpecShot plugin, prefer its brand pass: it maps the brand to ACSS settings with a dry run and a per-key diff, and the owner applies it with an automatic backup.\n2. Otherwise ask the owner for an ACSS settings export from one of their sites. It is the template: never write a settings file from scratch or invent a key.\n3. Read the design's numbers from the Design Direction board and the brand (get_brand_system): colors, fonts, the heading and text scales (base and ratio, desktop and mobile), the button style, the radius.\n4. Change only keys that already exist in the export. A color often appears in several forms (hex, OKLCH, sometimes HSL), so update every form until they agree. Font file paths point at the old site: flag them.\n5. Save it in the client's local folder with a short list of every change in plain words, so it can also be done by hand. Importing is the owner's, since it changes a site's settings."
447
473
  },
448
474
  "etch-structure": {
449
475
  "id": "etch-structure",
450
476
  "title": "Etch structure",
451
477
  "kind": "build",
452
478
  "when": "Load before writing the markup of any page or section that goes to Etch, and before changing structure in Etch through the Etch Connector.",
453
- "body": "# Etch structure\n\nThe owner's rules for the structure of a site built in Etch: class names, the elements Etch expects, components and accessibility. They hold for the SpecShot design that goes to Etch and for every change made in Etch afterward. The export contract (tokens, the project prefix, the ACSS map) is etch-acss-build, and how a design marks its components, slots and loops follows the build law (docs/BUILD-LAW.md in the SpecShot repository, and the structure part of the design law the design_law prompt serves).\n\n## Flat BEM names\n\n- Block `hero`, element `hero__heading`, modifier `featured-card--highlighted`, for true visual variants only.\n- One level deep: `featured__title`, never `featured__header__title`, however deep the markup.\n- A repeating component is its own block, not an element of its section: a card in the featured section is `featured-card` with `featured-card__title`, never `featured__card`.\n- No prefix of our own (the export adds the project's), but avoid generic single words a theme or plugin might also use, such as card or grid. Give them a second word: `service-card`.\n- Structural roles (section, container, flex-div) and ACSS classes never get a BEM class of ours.\n- Name parts the same way everywhere: a section's heading is `__heading`, the text under it `__lede`, a card's text `__description`, an image and its wrapper `__media` and `__media-wrapper`. Rename a class and its name in the builder together.\n\n## The structure Etch expects\n\n- `section` is full bleed and always carries the block class.\n- `container` is the width-constrained inner wrapper, `__inner` by default. Borders and edges that line up with the content go here, never on the full-bleed section.\n- `flex-div` holds child zones doing real layout work, named with a `-wrapper` suffix.\n- Use the most semantic element available: figure, article, ul, nav.\n- Collapse any wrapper with no CSS of its own.\n- A set of repeated things is a ul with li children, and a card component's root is the li.\n- A card's title is a real heading with the link inside it, never the whole card wrapped in a link. Make the heading level a property, h3 by default.\n- Write the HTML in reading order and set the visual order with CSS (order, grid areas), never the other way round.\n\n## Components\n\n- A section component's root is the section itself, with its block class and a property that picks its context, for example `bg--dark` or `bg--light`.\n- Never nest a section component inside another section component. Cards inside a list are fine.\n- Extra content one page needs inside a shared component is a slot, not a property.\n- Leave a property blank on an instance when the default is right. A typed value pins it, and later changes to the default no longer reach that page.\n- Label select options for the decision, not the mechanism: \"Lede beside the heading\", not \"two-thirds and one-third\". Fewer options mean fewer inconsistencies.\n- Delete classes and components that stop doing work, with their style records.\n- Dynamic data stays dynamic: nothing about a CMS item is typed onto a page. Company details (name, phone, email, address, social links) bind to one source, an options page or a one-record JSON loop; ask which exists before typing any.\n\n## Accessibility defaults\n\n- One h1 per page, on the hero. Every section opens with an h2, and no level is skipped.\n- Every image has a real src, alt (empty when decorative), width, height, loading and decoding.\n- Landmarks: header, nav with an aria-label, main with the id the skip link points at, footer.\n- Icon-only buttons get an aria-label; decorative SVG gets `aria-hidden=\"true\"`.\n- Name a section landmark with a short aria-label rather than aria-labelledby pointing at a long heading.\n- On a phone, h5 and h6 are body sizes, so h4 is the smallest reliable heading."
479
+ "body": "# Etch structure\n\nThe owner's rules for the structure of a site built in Etch: class names, the elements Etch expects, components and accessibility. They hold for the SpecShot design that goes to Etch and for every change made in Etch afterward. The export contract (tokens, the project prefix, the ACSS map) is etch-acss-build, and how a design marks its components, slots and loops follows the build law (docs/BUILD-LAW.md in the SpecShot repository, and the structure part of the design law the design_law prompt serves).\n\n## Flat BEM names\n\n- Block `hero`, element `hero__heading`, modifier `featured-card--highlighted`, for true visual variants only.\n- One level deep: `featured__title`, never `featured__header__title`, however deep the markup.\n- A repeating component is its own block, not an element of its section: a card in the featured section is `featured-card` with `featured-card__title`, never `featured__card`.\n- No prefix of our own (the export adds the project's), but avoid generic single words a theme or plugin might also use, such as card or grid. Give them a second word: `service-card`.\n- Structural roles (section, container) and ACSS classes never get a BEM class of ours.\n- Name parts the same way everywhere: a section's heading is `__heading`, the text under it `__lede`, a card's text `__description`, an image and its wrapper `__media` and `__media-wrapper`. Rename a class and its name in the builder together.\n\n## The structure Etch expects\n\n- `section` is full bleed and always carries the block class.\n- `container` is the width-constrained inner wrapper, `__inner` by default. Borders and edges that line up with the content go here, never on the full-bleed section.\n- Child zones doing real layout work are plain `div` elements with a class of their own, named with a `-wrapper` suffix. Etch's `flex-div` is deprecated: never build with it.\n- Use the most semantic element available: figure, article, ul, nav.\n- Collapse any wrapper with no CSS of its own.\n- A set of repeated things is a ul with li children, and a card component's root is the li.\n- A card's title is a real heading with the link inside it, never the whole card wrapped in a link. Make the heading level a property, h3 by default.\n- Write the HTML in reading order and set the visual order with CSS (order, grid areas), never the other way round.\n\n## Components\n\n- A section component's root is the section itself, with its block class and a property that picks its context, for example `bg--dark` or `bg--light`.\n- Never nest a section component inside another section component. Cards inside a list are fine.\n- Extra content one page needs inside a shared component is a slot, not a property.\n- Leave a property blank on an instance when the default is right. A typed value pins it, and later changes to the default no longer reach that page.\n- Label select options for the decision, not the mechanism: \"Lede beside the heading\", not \"two-thirds and one-third\". Fewer options mean fewer inconsistencies.\n- Delete classes and components that stop doing work, with their style records.\n- Dynamic data stays dynamic: nothing about a CMS item is typed onto a page. Company details (name, phone, email, address, social links) bind to one source, an options page or a one-record JSON loop; ask which exists before typing any.\n\n## Accessibility defaults\n\n- One h1 per page, on the hero. Every section opens with an h2, and no level is skipped.\n- Every image has a real src, alt (empty when decorative), width, height, loading and decoding.\n- Landmarks: header, nav with an aria-label, main with the id the skip link points at, footer.\n- Icon-only buttons get an aria-label; decorative SVG gets `aria-hidden=\"true\"`.\n- Name a section landmark with a short aria-label rather than aria-labelledby pointing at a long heading.\n- On a phone, h5 and h6 are body sizes, so h4 is the smallest reliable heading."
454
480
  },
455
481
  "etch-css": {
456
482
  "id": "etch-css",
@@ -464,7 +490,7 @@ export const SKILL_BODIES = {
464
490
  "title": "Etch Connector runtime",
465
491
  "kind": "build",
466
492
  "when": "Load before driving an Etch tab through the Etch Connector: editing components, classes, loops or data, saving, navigating, or working on Etch Studio.",
467
- "body": "# Etch Connector runtime\n\nFacts about the Etch runtime that cost time to discover, for an agent driving the Etch Connector after a SpecShot build. Read etch-development first, and Etch's own guide for agents (https://docs.etchwp.com/etch-connector/ai-agent-guide) when a method is in doubt.\n\n## Components and classes\n\n- Read a component with `etch.components.getJson(id)` and patch it with `updateAsync(id, { blocks })`. Strip id and parentId from each block but keep every styles array, which is what links classes: `styles: []` drops the class attribute.\n- A class is linked through the block's styles array, not its class attribute. Editing the attribute alone silently reverts.\n- On page blocks, `blocks.create()` drops the class attribute. Create, save, then `addClass` by class name (not style id) in a second pass, save, and read it back.\n- Never add and remove a class on the same block in one script. Use separate saved passes.\n- `addClass` with a name that has no style record creates an empty record. Create the record first or skip the class.\n- Component edit mode overwrites class changes made with `components.updateAsync` on the next save. Check `etch.blocks.isInComponentEditMode()` first, and leave it or work inside it.\n- Removing a property strands the instances that still set it. Clear it on every instance first.\n- Etch keys components in PascalCase, so look components up by name.\n- A blank property bound into an attribute renders an empty attribute (`id=\"\"`). Bind properties only where empty is harmless.\n- Text properties hold one paragraph. Rich content belongs in post content or a loop.\n\n## Saving and the tab\n\n- Never fire saved passes back to back. Wait a few seconds after `saveAsync()` before the next script or navigation, or a save can be lost, and verify each page on the front end.\n- `etch.navigation` shows what the builder is on (`getActivePostId()`, `isEditingTemplate()`) and moves it (`openPostAsync`, `openTemplateAsync`) without dropping the connection. The address `tabs` prints goes stale.\n- The tab disconnects when the builder reloads or navigates by hand. Wait, check `tabs` and retry; a tab can also go quiet for a minute and come back.\n- A builder tab left open overnight fails saves with a 403. Reload the builder.\n- If a safety check refuses a script that deletes blocks on shared templates, leave the script in the scratch folder and hand the owner the command rather than reshaping it to get past the check.\n\n## Loops, data and expressions\n\n- Only literal loop parameters reach a loop's query. To vary a loop per page, loop everything and filter with an etch/condition on the item.\n- `etch.loops.getAll()` is keyed by loop id and the loop objects carry no id, so use `Object.entries()`.\n- Use single quotes inside dynamic expressions (`split(' ')`). A double quote closes the HTML attribute and the expression renders as nothing.\n- In conditions, use strict `!==` when a field that was never saved must count as true.\n- An etch/text block escapes HTML and runs shortcodes; an etch/raw-html block renders HTML but strips shortcodes.\n- On WordPress, ACF fields are invisible to `etch.fields`. Reference them as `{item.acf.field}` in a loop, `{this.acf.field}` in a template and `{options.acf.field}` for an options page.\n- Etch's stock previous and next post links follow the publish date, not the menu order.\n\n## Assets\n\n- Etch strips `</` from stylesheet CSS, which breaks raw SVG data URIs. Percent-encode them.\n- Etch caches an etch/svg by its src. Replacing the file under the same name changes nothing, so change the address.\n\n## Etch Studio\n\nEverything above applies to Studio, which has the same API surface. What differs:\n\n- Studio builds a static site and never hosts it. Deploys go to Cloudflare Workers or a downloaded site.zip, within 25 MB in total, and large images are the usual cause of going over.\n- Data resolves at build time. Stale data on a deployed site means deploy again; say so plainly to a client.\n- Deploying is the owner's.\n- Studio publishes only the assets the build references directly. A CSS url() to an asset fails, so use a percent-encoded data URI for small icons in CSS.\n- Never put JavaScript in an etch/raw-html block on Studio, where braces are read as data expressions. Page scripts go in a component's script.\n- Check that ACSS's on-visible effects animate on the deployed site. If elements stay invisible, the effects script is missing."
493
+ "body": "# Etch Connector runtime\n\nFacts about the Etch runtime that cost time to discover, for an agent driving the Etch Connector after a SpecShot build. Read etch-development first, and Etch's own guide for agents (https://docs.etchwp.com/etch-connector/ai-agent-guide) when a method is in doubt.\n\n## Components and classes\n\n- Read a component with `etch.components.getJson(id)` and patch it with `updateAsync(id, { blocks })`. Strip id and parentId from each block but keep every styles array, which is what links classes: `styles: []` drops the class attribute.\n- A class is linked through the block's styles array, not its class attribute. Editing the attribute alone silently reverts.\n- On page blocks, `blocks.create()` drops the class attribute. Create, save, then `addClass` by class name (not style id) in a second pass, save, and read it back.\n- Never add and remove a class on the same block in one script. Use separate saved passes.\n- `addClass` with a name that has no style record creates an empty record. Create the record first or skip the class.\n- Component edit mode overwrites class changes made with `components.updateAsync` on the next save. Check `etch.blocks.isInComponentEditMode()` first, and leave it or work inside it.\n- Removing a property strands the instances that still set it. Clear it on every instance first.\n- Etch keys components in PascalCase, so look components up by name.\n- A blank property bound into an attribute renders an empty attribute (`id=\"\"`). Bind properties only where empty is harmless.\n- Text properties hold one paragraph. Rich content belongs in post content or a loop.\n\n## Saving and the tab\n\n- Never fire saved passes back to back. Wait a few seconds after `saveAsync()` before the next script or navigation, or a save can be lost, and verify each page on the front end.\n- `etch.navigation` shows what the builder is on (`getActivePostId()`, `isEditingTemplate()`) and moves it (`openPostAsync`, `openTemplateAsync`) without dropping the connection. The address `tabs` prints goes stale.\n- The tab disconnects when the builder reloads or navigates by hand. Wait, check `tabs` and retry; a tab can also go quiet for a minute and come back.\n- A builder tab left open overnight fails saves with a 403. Reload the builder.\n- Read `etch.ai.getState()` before writing: anything but idle is another agent at work, so wait. get_etch_build's `check.script` reads it and changes nothing.\n- If a safety check refuses a script that deletes blocks on shared templates, leave the script in the scratch folder and hand the owner the command rather than reshaping it to get past the check.\n\n## Loops, data and expressions\n\n- Only literal loop parameters reach a loop's query. To vary a loop per page, loop everything and filter with an etch/condition on the item.\n- `etch.loops.getAll()` is keyed by loop id and the loop objects carry no id, so use `Object.entries()`.\n- Use single quotes inside dynamic expressions (`split(' ')`). A double quote closes the HTML attribute and the expression renders as nothing.\n- In conditions, use strict `!==` when a field that was never saved must count as true.\n- An etch/text block escapes HTML and runs shortcodes; an etch/raw-html block renders HTML but strips shortcodes.\n- On WordPress, ACF fields are invisible to `etch.fields`. Reference them as `{item.acf.field}` in a loop, `{this.acf.field}` in a template and `{options.acf.field}` for an options page.\n- Etch's stock previous and next post links follow the publish date, not the menu order.\n\n## Assets\n\n- Etch strips `</` from stylesheet CSS, which breaks raw SVG data URIs. Percent-encode them.\n- Etch caches an etch/svg by its src. Replacing the file under the same name changes nothing, so change the address.\n\n## Etch Studio\n\nEverything above applies to Studio, which has the same API surface. What differs:\n\n- Studio builds a static site and never hosts it. Deploys go to Cloudflare Workers or a downloaded site.zip, within 25 MB in total, and large images are the usual cause of going over.\n- Data resolves at build time. Stale data on a deployed site means deploy again; say so plainly to a client.\n- Deploying is the owner's.\n- Studio publishes only the assets the build references directly. A CSS url() to an asset fails, so use a percent-encoded data URI for small icons in CSS.\n- Never put JavaScript in an etch/raw-html block on Studio, where braces are read as data expressions. Page scripts go in a component's script.\n- Check that ACSS's on-visible effects animate on the deployed site. If elements stay invisible, the effects script is missing."
468
494
  },
469
495
  "etch-connector-gotchas": {
470
496
  "id": "etch-connector-gotchas",