@scayver/specshot-mcp-server 0.11.0 → 0.13.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/skills.js ADDED
@@ -0,0 +1,476 @@
1
+ // GENERATED FILE: do not edit by hand. The design skills, from packages/shared/src/skills through apps/web/src/lib/mcp/skills.ts.
2
+ //
3
+ // apps/mcp-server publishes standalone to npm, so it cannot import @specshot/shared or the hosted
4
+ // registry. This copy is written from them by apps/web/src/lib/__tests__/mcp-stdio-sync.test.ts,
5
+ // which fails whenever the two differ. To regenerate after changing the source:
6
+ // cd apps/web && SPECSHOT_WRITE_GENERATED=1 npx vitest run src/lib/__tests__/mcp-stdio-sync.test.ts
7
+ /** The list_skills answer, exactly as the hosted tool gives it. */
8
+ export const SKILL_LIST = {
9
+ "skills": [
10
+ {
11
+ "id": "page-composition",
12
+ "title": "Page composition",
13
+ "kind": "page",
14
+ "when": "Load before planning any whole page: which sections it has, in what order, on which ground, at what density."
15
+ },
16
+ {
17
+ "id": "direction-by-niche",
18
+ "title": "Choosing a direction by niche",
19
+ "kind": "page",
20
+ "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."
21
+ },
22
+ {
23
+ "id": "navigation-header",
24
+ "title": "Navigation and headers",
25
+ "kind": "section",
26
+ "when": "Load before building the site header, the main navigation, a mobile menu or any sub-navigation."
27
+ },
28
+ {
29
+ "id": "hero",
30
+ "title": "Hero sections",
31
+ "kind": "section",
32
+ "when": "Load before building the first section of any page: a hero, an intro, a page header or a landing block."
33
+ },
34
+ {
35
+ "id": "content-long-text",
36
+ "title": "Content sections and long text",
37
+ "kind": "section",
38
+ "when": "Load before building features, services, how it works, about, story, blog posts, case studies, legal pages or any section that is mostly words."
39
+ },
40
+ {
41
+ "id": "social-proof",
42
+ "title": "Testimonials and social proof",
43
+ "kind": "section",
44
+ "when": "Load before building testimonials, reviews, client logos, case study teasers, stats, ratings, awards or press mentions."
45
+ },
46
+ {
47
+ "id": "pricing",
48
+ "title": "Pricing",
49
+ "kind": "section",
50
+ "when": "Load before building any pricing table, plan comparison, rate card, package list or quote explainer."
51
+ },
52
+ {
53
+ "id": "faq",
54
+ "title": "FAQ",
55
+ "kind": "section",
56
+ "when": "Load before building an FAQ, a questions and answers block, an objections section or any accordion."
57
+ },
58
+ {
59
+ "id": "footer",
60
+ "title": "Footers",
61
+ "kind": "section",
62
+ "when": "Load before building any site footer, and the closing call to action that usually sits above it."
63
+ },
64
+ {
65
+ "id": "components-variants",
66
+ "title": "Components and variants",
67
+ "kind": "component",
68
+ "when": "Load before building a second page, a components page, or any part that appears more than once: buttons, cards, fields, quotes, headers and footers."
69
+ },
70
+ {
71
+ "id": "buttons-links",
72
+ "title": "Buttons and links",
73
+ "kind": "component",
74
+ "when": "Load before building any call to action, button, link or link-styled control."
75
+ },
76
+ {
77
+ "id": "cards",
78
+ "title": "Cards",
79
+ "kind": "component",
80
+ "when": "Load before building any card, tile, feature grid, team grid, product grid or post list."
81
+ },
82
+ {
83
+ "id": "forms",
84
+ "title": "Forms",
85
+ "kind": "component",
86
+ "when": "Load before building any form: contact, booking, quote, newsletter, sign up, sign in or checkout."
87
+ },
88
+ {
89
+ "id": "icons",
90
+ "title": "Icons",
91
+ "kind": "component",
92
+ "when": "Load before drawing any icon, icon button, feature mark, list bullet or social link."
93
+ },
94
+ {
95
+ "id": "imagery-art-direction",
96
+ "title": "Imagery and art direction",
97
+ "kind": "component",
98
+ "when": "Load before placing any image, hero visual, gallery, product shot, portrait, diagram or background."
99
+ },
100
+ {
101
+ "id": "typography",
102
+ "title": "Typography",
103
+ "kind": "foundation",
104
+ "when": "Load before choosing faces or sizing any text, and whenever a page reads flat, crowded or generic."
105
+ },
106
+ {
107
+ "id": "spacing-rhythm",
108
+ "title": "Spacing and rhythm",
109
+ "kind": "foundation",
110
+ "when": "Load before laying out any section, and whenever a page feels cramped, loose or monotonous."
111
+ },
112
+ {
113
+ "id": "layout-grids",
114
+ "title": "Layout and grids",
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."
117
+ },
118
+ {
119
+ "id": "color-contrast",
120
+ "title": "Color assignment and contrast",
121
+ "kind": "foundation",
122
+ "when": "Load before assigning any color to text, a surface, a control or an icon, and before calling a page accessible."
123
+ },
124
+ {
125
+ "id": "surfaces-elevation",
126
+ "title": "Surfaces and elevation",
127
+ "kind": "foundation",
128
+ "when": "Load before giving anything a background, border, shadow, radius, divider or overlay."
129
+ },
130
+ {
131
+ "id": "motion",
132
+ "title": "Motion and animation",
133
+ "kind": "foundation",
134
+ "when": "Load before adding any transition, entrance, hover effect, animated chart or signature interaction."
135
+ },
136
+ {
137
+ "id": "accessibility",
138
+ "title": "Accessibility",
139
+ "kind": "foundation",
140
+ "when": "Load before building any page, and before calling one finished: the audit at the end is part of the job."
141
+ },
142
+ {
143
+ "id": "responsive",
144
+ "title": "Responsive behavior",
145
+ "kind": "foundation",
146
+ "when": "Load before building any page, and for the responsive pass before saving: SpecShot's frame is dragged to every width."
147
+ },
148
+ {
149
+ "id": "etch-acss-build",
150
+ "title": "The Etch and ACSS build",
151
+ "kind": "build",
152
+ "when": "Load before building any page or section that will go to Etch, which is every SpecShot design, and before running get_etch_build."
153
+ },
154
+ {
155
+ "id": "agency-process",
156
+ "title": "The agency process",
157
+ "kind": "page",
158
+ "when": "Load at the start of any client project, before starting or finishing a phase, and before anything is drafted for a client."
159
+ },
160
+ {
161
+ "id": "discovery-interview",
162
+ "title": "The discovery interview",
163
+ "kind": "page",
164
+ "when": "Load when the owner says new client or start discovery, before interviewing anyone about a client, a project or its brief."
165
+ },
166
+ {
167
+ "id": "copy-and-wireframe",
168
+ "title": "Copy and wireframe",
169
+ "kind": "page",
170
+ "when": "Load when the owner says start copywriting, and before writing page copy or building a wireframe for a client page."
171
+ },
172
+ {
173
+ "id": "design-for-acss",
174
+ "title": "Design for ACSS",
175
+ "kind": "foundation",
176
+ "when": "Load when the owner says start design, before the Design Direction board, and before designing any page from an approved wireframe."
177
+ },
178
+ {
179
+ "id": "section-authorship",
180
+ "title": "Section authorship",
181
+ "kind": "page",
182
+ "when": "Load before planning or reviewing the sections of any page: each section's job, its anchor and its archetype, and the rules that keep a page from repeating itself."
183
+ },
184
+ {
185
+ "id": "design-qa-gate",
186
+ "title": "Design QA gate",
187
+ "kind": "page",
188
+ "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."
189
+ },
190
+ {
191
+ "id": "etch-development",
192
+ "title": "Etch development",
193
+ "kind": "build",
194
+ "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."
195
+ },
196
+ {
197
+ "id": "etch-structure",
198
+ "title": "Etch structure",
199
+ "kind": "build",
200
+ "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."
201
+ },
202
+ {
203
+ "id": "etch-css",
204
+ "title": "Etch CSS",
205
+ "kind": "build",
206
+ "when": "Load before writing or changing styles in Etch, by hand or through the Etch Connector, and before choosing a button or a variable on an ACSS site."
207
+ },
208
+ {
209
+ "id": "etch-connector-runtime",
210
+ "title": "Etch Connector runtime",
211
+ "kind": "build",
212
+ "when": "Load before driving an Etch tab through the Etch Connector: editing components, classes, loops or data, saving, navigating, or working on Etch Studio."
213
+ },
214
+ {
215
+ "id": "etch-connector-gotchas",
216
+ "title": "Etch Connector gotchas",
217
+ "kind": "build",
218
+ "when": "Load before editing an Etch page through the Etch Connector after a SpecShot build: the script cadence, where CSS really ships, the classes a save drops, and how to verify."
219
+ }
220
+ ],
221
+ "workflow": "THE WORKFLOW FOR A PAGE. Work in this order, and do not skip a step:\n1. DIRECTION. Build to the project's approved direction and its brand. With neither, commit to one direction (a named palette, a real type pairing, a spacing scale) and hold it on every section; a neutral default is the failure, not the safe option.\n2. BRIEF AND CLIENT RULES. Read the client's rules first, then the brief, this page's goal and required sections, the approved copy and the references. The client's rules beat every default, never the boundary against copying or the anti-slop bans.\n3. TOKENS. Declare the canonical tokens once in :root with the brand's values, every type and space step a clamp(), and read them everywhere with a literal fallback. Change values, never names.\n4. COMPONENTS. Define the shared parts once (header, footer, buttons, cards, fields) as BEM blocks with a modifier per variant and every state, and reuse them by the same name on every page.\n5. SECTIONS. Plan every section before markup (its skeleton, ground and padding, so no two neighbors match, one theme runs from header to footer and every section starts on one content edge), then build each with the skill for its kind.\n6. THE PAGE. Assemble the whole page in one piece: header, every section in order, footer, one h1, headings that tell the story, the primary action three times with the same verb. Never a placeholder where markup belongs, and never an invented client fact: a price, date, number or credential nobody gave is a clearly labeled gap, [GAP: what is missing], and one stated but not confirmed is [UNVERIFIED: what].\n7. RESPONSIVE PASS. Check every width from 360 to 1920, 390, 768 and 1440 first: no sideways scroll, body at least 1rem, 2.75rem targets, every hover effect reachable on touch.\n8. LAW CHECK. Walk the anti-slop list and the production gate yourself. When the design is saved to SpecShot, its law check returns designLaw: block findings are clear slop, warn findings are worth fixing.\n9. ONE REPAIR ROUND. Fix every block finding, and the warn findings you can, in one batch, keeping every section, the copy and the structure. Then stop and report what is left.\n10. REVIEW. Review it honestly before calling it done: grade typography, color, hierarchy, animation, mobile and copy, and say what is verified and what still needs the client.",
222
+ "workflowPrompts": {
223
+ "page": "build_a_page",
224
+ "revision": "revise_a_page",
225
+ "section": "rebuild_from_capture"
226
+ },
227
+ "howToUse": "Plan the page with page-composition, then load the skill for each section kind and each part you build (get_skill with its id). get_wireframe_context names the skills that fit each page. A skill adds detail to the design law and never overrides it, and the client's rules beat both."
228
+ };
229
+ /** Every get_skill answer, by id, exactly as the hosted tool gives it. */
230
+ export const SKILL_BODIES = {
231
+ "page-composition": {
232
+ "id": "page-composition",
233
+ "title": "Page composition",
234
+ "kind": "page",
235
+ "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?"
237
+ },
238
+ "direction-by-niche": {
239
+ "id": "direction-by-niche",
240
+ "title": "Choosing a direction by niche",
241
+ "kind": "page",
242
+ "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?"
244
+ },
245
+ "navigation-header": {
246
+ "id": "navigation-header",
247
+ "title": "Navigation and headers",
248
+ "kind": "section",
249
+ "when": "Load before building the site header, the main navigation, a mobile menu or any sub-navigation.",
250
+ "body": "# Navigation and headers\n\nThe header answers two questions on every page: where am I, and where can I go. It is the most reused component on the site, so it is built once.\n\n## Content\n\n- The logo or wordmark on the left, linking home, with an accessible name (\"Northwind, home\").\n- Four to six items, named in the visitor's words (\"Pricing\", \"Our work\", \"Contact\"), never the company's internal names. More than six means the site map needs grouping, not a longer bar.\n- The primary action as a button at the end, the same verb as the page's primary action.\n- The current page marked: `aria-current=\"page\"` plus a visible cue (weight, an underline, or a dot), never color alone.\n- A secondary link (Sign in, a phone number) sits before the button and is quieter.\n\n## Layout\n\n- Height around 4rem, content aligned to the page's grid and `--content` width.\n- Sticky at the top with glass only where content scrolls beneath it: a ground at 72 to 80 percent opacity with `backdrop-filter: blur(16px) saturate(140%)`, a solid fallback, and a hairline that appears once the page has scrolled. Sticky elements take `scroll-margin-top` into account for anchors.\n- The header never covers focus: anchored sections get `scroll-margin-top` equal to the header height.\n- Respect safe-area insets on phones with a notch.\n\n## The phone menu\n\n- Below the width where the items no longer fit, the items fold into a menu. That is a real breakpoint; place it where the layout breaks, not at a stock width.\n- Build it with `<details>` and `<summary>`: it opens and closes with no script, announces its state, and works in the preview. A scripted menu button carries `aria-expanded` and `aria-controls`.\n- The menu button has an accessible name (\"Menu\") and a 2.75rem target. Its icon is drawn inline.\n- Items in the open menu are large and well spaced, each at least 2.75rem tall, with the primary action last and full width.\n- The open menu is reachable and closable by keyboard, and a long menu scrolls inside itself.\n\n## Sub-navigation\n\n- A section with many pages gets a secondary navigation inside the page (tabs or a side list), not a mega menu, unless the site truly has dozens of destinations.\n- Breadcrumbs for anything three levels deep, in a `<nav aria-label=\"Breadcrumb\">`.\n- A dropdown opens on click or keyboard, never on hover alone: anything that only exists on hover is unreachable on a phone.\n\n## One component\n\n- The header is a shared component with the same name on every page. Over MCP, list_components shows the one already registered; reuse it rather than re-authoring it on the next page. How it is 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).\n- Variants are modifiers on the one block (`.site-header--sticky`), never a second header.\n\n## Example\n\n```html\n<header class=\"site-header\">\n <a class=\"site-header__logo\" href=\"/\" aria-label=\"Northwind, home\">Northwind</a>\n <nav class=\"site-header__nav\" aria-label=\"Main\">\n <a class=\"site-header__link\" href=\"/work\" aria-current=\"page\">Our work</a>\n <a class=\"site-header__link\" href=\"/pricing\">Pricing</a>\n </nav>\n <a class=\"button button--primary\" href=\"/book\">Book a site survey</a>\n <details class=\"site-header__menu\"><summary class=\"site-header__toggle\" aria-label=\"Menu\"></summary></details>\n</header>\n```\n\n## Check before you save\n\n- Is the current page marked with aria-current and a visible cue?\n- Does the phone menu open with no script and give every item a 2.75rem target?\n- Is the header the same component, by name, on every page?"
251
+ },
252
+ "hero": {
253
+ "id": "hero",
254
+ "title": "Hero sections",
255
+ "kind": "section",
256
+ "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?"
258
+ },
259
+ "content-long-text": {
260
+ "id": "content-long-text",
261
+ "title": "Content sections and long text",
262
+ "kind": "section",
263
+ "when": "Load before building features, services, how it works, about, story, blog posts, case studies, legal pages or any section that is mostly words.",
264
+ "body": "# Content sections and long text\n\nMost of a website is words. The difference between a template and a real site is mostly whether those words say something specific, and whether they are easy to read.\n\n## The headline test\n\n- Read only the headings, top to bottom. They should tell the whole story.\n- If they read as labels (\"Features\", \"About us\", \"Our process\"), rewrite them as claims: \"Surveys that arrive before your architect asks\", \"Twelve years measuring Sydney's terraces\".\n- Use the client's approved copy word for word where it exists; prefer their draft copy over anything you would write.\n\n## Copy\n\n- Say what the thing does. Concrete nouns and verbs, the customer as the subject.\n- No buzzwords: never streamline, empower, supercharge, seamless, elevate or unlock. No lorem, no bracketed filler presented as copy, no invented facts.\n- Short paragraphs: two to four sentences. One idea each.\n- Lists for things that are lists; a sentence for things that are not.\n- Numbers as numerals, with units, and uneven where they are real.\n\n## Reading comfort\n\n- Body at least 1rem, line height 1.5 to 1.7, measure 65ch, never past 75 characters.\n- Paragraph spacing about 1em; more space above a subheading than below it.\n- `text-wrap: pretty` on paragraphs, real typographic quotes and apostrophes.\n- Links underlined in body text.\n- Left-aligned. Centered paragraphs are hard to read past two lines.\n\n## Breaking up long text\n\n- An editorial column: a 60ch text column beside an oversized numeral, a pull quote, a key figure or a small diagram.\n- A sticky narrative: the section heading sticks on one side while the paragraphs scroll past on the other.\n- Pull quotes set at `--step-2` or `--step-3` in the display face, quoting the text itself, never repeating it twice in a row.\n- Figures with captions, tables for tabular data, callouts for warnings. Not a box around every paragraph.\n\n## Features and services\n\n- Lead with the few that matter most, each with a claim as its heading and one or two sentences of proof.\n- Vary the skeleton: a bento with one lead, an asymmetric split per feature, or a list with icons. Never three identical icon cards as the default.\n- Each feature says what the customer gets, not what the product has.\n\n## How it works\n\n- Numbered steps, three to five, the numbers set in type, each with a short heading and one sentence. No numbered circles and no dotted connector: they are ornament standing in for order.\n- Use an ordered list (`<ol>`) so the order is real for screen readers.\n\n## Articles and legal pages\n\n- A clear title, the date and author where real, a reading time if helpful, and a table of contents for anything long.\n- Headings in order (h2, h3), never skipped for size. Anchors on headings so sections can be linked.\n- Legal text stays readable: the same body size and measure as everything else.\n\n## Example\n\n```css\n.story { display: grid; grid-template-columns: repeat(12, minmax(0, 1fr)); gap: var(--space-l, 2rem); }\n.story__figure { grid-column: 1 / span 4; font: 400 var(--step-6, 3.25rem) / 1 var(--font-display, ui-serif, Georgia, serif); }\n.story__text { grid-column: 6 / span 7; max-width: var(--measure, 65ch); }\n```\n\n## Check before you save\n\n- Do the headings alone tell the story?\n- Is there any buzzword, filler or invented fact in the copy?\n- Is every long passage at 65ch with a break before it becomes a wall?"
265
+ },
266
+ "social-proof": {
267
+ "id": "social-proof",
268
+ "title": "Testimonials and social proof",
269
+ "kind": "section",
270
+ "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?"
272
+ },
273
+ "pricing": {
274
+ "id": "pricing",
275
+ "title": "Pricing",
276
+ "kind": "section",
277
+ "when": "Load before building any pricing table, plan comparison, rate card, package list or quote explainer.",
278
+ "body": "# Pricing\n\nThe pricing section answers the question every visitor came with. Hiding the answer reads as hiding something.\n\n## The number\n\n- Show the real price, or say plainly how it is quoted (\"Quoted per site after a free 20 minute call\"). Never invent a price, a discount or a \"most popular\" claim the client has not given you; mark a missing one `[GAP: price]` and an unconfirmed one `[UNVERIFIED: price]`.\n- The price at `--step-4` with `font-variant-numeric: tabular-nums`, the currency smaller and the period (\"per month\", \"per site\") in `--ink-2` beside it.\n- Annual and monthly: a two-option toggle only if both are real. Built with radio inputs and labels, it works with no script and announces its state.\n- Taxes, minimums and what is excluded, in one honest line under the tiers.\n\n## Tiers\n\n- Two to four tiers. More than four means the product needs a \"talk to us\" tier, not a fifth column.\n- Each tier: its name, who it is for in one line, the price, the three to five differences that matter, and an action.\n- Lead with what differs. A list of fifteen identical ticks under every tier hides the choice.\n- One tier may be featured: a raised shadow step or a tint, and a short line naming why (\"For teams of five or more\") set as text, never a badge. Never a second accent color and never a thick stripe down one side.\n- Order from smallest to largest, left to right; on a phone the featured tier comes first.\n\n## Actions\n\n- Each tier's button names what happens: \"Start the Studio plan\", \"Book a scoping call\". The featured tier's button is the page's primary style; the others are secondary.\n- The page's primary action still appears in the hero and the close with the same words.\n\n## Detail and objections\n\n- A comparison table below the tiers for the full feature list: real `<table>` markup, `<th scope=\"col\">` for tiers and `<th scope=\"row\">` for features, the header row sticky, ticks drawn as SVG with text for screen readers (\"Included\", \"Not included\").\n- On a phone, the table scrolls inside its own container, never the page.\n- A FAQ next to pricing answers the hard questions: contracts, cancellation, what happens at the limit, refunds. Answer them plainly.\n- Proof next to the ask: a short testimonial about value, or a real count of customers on the plan.\n\n## Layout\n\n- Tiers in a grid that reflows: `repeat(auto-fit, minmax(min(100%, 16rem), 1fr))`.\n- Each tier is a card: one elevation, never a card within a card, the action pinned to the bottom so buttons align across tiers.\n- The section is dense (`--pad-dense`) when it sits inside a long page, open when it is the page's main event.\n\n## Example\n\n```html\n<article class=\"tier tier--featured\">\n <h3 class=\"tier__name\">Studio</h3>\n <p class=\"tier__for\">For practices with several projects a month.</p>\n <p class=\"tier__price\"><span class=\"tier__amount\">[price from client]</span> <span class=\"tier__period\">per month</span></p>\n <ul class=\"tier__features\"><li class=\"tier__feature\">Surveys within two working days</li></ul>\n <a class=\"button button--primary tier__action\" href=\"/start?plan=studio\">Start the Studio plan</a>\n</article>\n```\n\n## Check before you save\n\n- Is every price real, or clearly marked as waiting on the client?\n- Does each tier say who it is for and what differs?\n- Is there an answer nearby to the question \"what is the catch\"?"
279
+ },
280
+ "faq": {
281
+ "id": "faq",
282
+ "title": "FAQ",
283
+ "kind": "section",
284
+ "when": "Load before building an FAQ, a questions and answers block, an objections section or any accordion.",
285
+ "body": "# FAQ\n\nAn FAQ is where a visitor's doubts get answered before they become a reason to leave. Answer the questions people actually hesitate on, not the ones that flatter the business.\n\n## Questions\n\n- The hard ones first: what it costs and how it is quoted, contracts and cancellation, how long it takes, what happens when something goes wrong, who it is not for.\n- Five to eight questions. More belongs on a help page with search, grouped by topic.\n- Written as the visitor would ask them: \"Can I cancel after the first month?\", not \"Cancellation policy\".\n- Use the client's real answers. Where a policy is unknown, mark the answer `[GAP: cancellation policy]` rather than inventing terms.\n\n## Answers\n\n- Start with the answer, then the detail: \"Yes. You can cancel any time before your next billing date, and we refund unused weeks.\"\n- Two to four sentences, at the body size, at a measure of 65ch.\n- Link to the page that has the rest, with link text that names it.\n- No marketing in answers. A question answered with a sales line reads as evasion.\n\n## The disclosure\n\n- Each item is a `<details>` with a `<summary>`: it opens with no script, works in the preview, and announces its state. A scripted accordion carries `aria-expanded` and `aria-controls` on a real button.\n- The summary is the full question, at `--step-1` weight 600, with a 2.75rem tall target.\n- The marker is a drawn SVG chevron or plus, turned with `transform: rotate()` over `--dur-2`; hide the default marker with `list-style: none` on the summary and its `::-webkit-details-marker`.\n- Items separated by hairlines in `--line`, not boxed in cards. Space carries the grouping.\n- The open item's answer has room: `--space-s` above, `--space-m` below.\n- Never animate the height. If the opening moves, fade and slide the answer's content a few pixels with transform.\n- Wrap it in `<section>` with an h2, and give each item an `id` so a question can be linked directly.\n\n## Layout\n\n- Not centered. A two-column split works well: a sticky heading and a contact line (\"Still unsure? Call the studio\") on one side, the questions on the other.\n- On a phone, one column, the contact line after the questions.\n- Dense rather than open padding when it sits near pricing.\n\n## Example\n\n```html\n<section class=\"faq\" aria-labelledby=\"faq-title\">\n <h2 class=\"faq__title\" id=\"faq-title\">What people ask before they book</h2>\n <details class=\"faq__item\" id=\"faq-cancel\">\n <summary class=\"faq__question\">Can I cancel after the first month?</summary>\n <div class=\"faq__answer\"><p class=\"faq__text\">[Answer from the client's cancellation terms]</p></div>\n </details>\n</section>\n```\n\n```css\n.faq__question { list-style: none; display: flex; justify-content: space-between; gap: var(--space-s, 1rem); min-height: 2.75rem; cursor: pointer; }\n.faq__question::-webkit-details-marker { display: none; }\n```\n\n## Check before you save\n\n- Are the hard questions here, answered first and plainly?\n- Does every item open with no script and announce its state?\n- Is any answer invented where the client's terms are unknown?"
286
+ },
287
+ "footer": {
288
+ "id": "footer",
289
+ "title": "Footers",
290
+ "kind": "section",
291
+ "when": "Load before building any site footer, and the closing call to action that usually sits above it.",
292
+ "body": "# Footers\n\nVisitors who reach the footer are looking for something: a contact line, a page they could not find, proof the business is real. Give it to them.\n\n## Content\n\n- The logo or wordmark, and one sentence on what the business does, in its voice.\n- Link columns grouped by intent: the work (services or products), the company (about, careers, press), help (contact, FAQ, support). Three or four columns, three to seven links each, headed in plain words.\n- Contact lines that work: a `tel:` link, a `mailto:` link, the address in an `<address>` element, opening hours when they matter.\n- Social links as labeled icons, drawn inline in currentColor.\n- A legal row: the year, the registered business name, privacy and terms links, and any license or registration number the client must show. Only the client's real details; mark one that is missing with a `[GAP: registration number]` marker rather than inventing it.\n- A newsletter field only when the client actually sends one.\n- The agency credit, only when the agency turned it on for its workspace: one small line at the very end, \"Site by\" and the agency's name, linked to the agency's own site, set in the legal row's small print. SpecShot adds it to the pages it generates and gives an agent the exact words. Never add an agency, tool or \"Made with\" credit nobody asked for, because the site and its footer belong to the client.\n\n## The close above it\n\n- Most pages end with a closing statement just above the footer: a short claim set large, the primary action with the same verb as the hero, and one line of proof. It stays inside its own section, never pulled over the footer.\n- It is one of the two places a centered layout is right. Keep it short.\n\n## Layout\n\n- On the page's own theme: a deeper tint (`--paper-3`) or paper with a hairline above. A dark footer belongs only to a dark theme, never to a light page.\n- A grid of columns that reflows with `repeat(auto-fit, minmax(min(100%, 12rem), 1fr))`, the brand column wider.\n- Generous padding (`--pad-dense` at least), links at `--step--1` or `--step-0` with 2.75rem tall targets on touch, column headings at `--step-0` in weight 600.\n- The legal row separated by a hairline and set at `--step--1` in `--ink-3`, still at 4.5:1.\n\n## Accessibility\n\n- `<footer>` holds a `<nav aria-label=\"Footer\">` for the link columns.\n- Column headings are real headings (h2 or a level that fits the outline) or a labeled list, not bold text.\n- Every icon-only social link has an `aria-label` with the network's name.\n\n## One component\n\n- The footer is a shared component with the same name on every page. Reuse it; never re-author it per page. A page that needs less uses a modifier (`.site-footer--compact`) of the same block.\n\n## Example\n\n```html\n<footer class=\"site-footer\">\n <div class=\"site-footer__brand\"><a class=\"site-footer__logo\" href=\"/\">Northwind</a><p class=\"site-footer__about\">Measured surveys for architects and builders.</p></div>\n <nav class=\"site-footer__nav\" aria-label=\"Footer\"><h2 class=\"site-footer__heading\">Services</h2></nav>\n <address class=\"site-footer__contact\"><a class=\"site-footer__link\" href=\"tel:+61200000000\">Call the studio</a></address>\n <p class=\"site-footer__legal\">Northwind Surveys Pty Ltd. Privacy. Terms.</p>\n</footer>\n```\n\n## Check before you save\n\n- Can a visitor call, email and find the address from the footer?\n- Are the columns real links grouped by intent, with no invented pages?\n- Is the legal row the client's real business name, or a `[GAP]` marker where a detail is missing?"
293
+ },
294
+ "components-variants": {
295
+ "id": "components-variants",
296
+ "title": "Components and variants",
297
+ "kind": "component",
298
+ "when": "Load before building a second page, a components page, or any part that appears more than once: buttons, cards, fields, quotes, headers and footers.",
299
+ "body": "# Components and variants\n\nA website is a few parts used many times. When each page re-authors its header, its buttons and its cards, the site drifts until the header on Pricing is no longer the header on Home. Design parts once and reuse them by name.\n\n## Find what exists first\n\n- Over MCP, call list_components before building another page. It names the project's shared components and which of them have drifted. Reuse a registered component under the same name; never invent a fourth header.\n- When saving a page, record which sections are instances of a shared component, with the same component name on every page. That is what makes drift detectable later.\n- When the project has a components page (a page of kind \"components\"), build new parts there first, then compose screens from them.\n\n## One block, many variants\n\n- A component is one block. Its variants are modifiers of that block: `.button--primary`, `.button--quiet`, `.plan--featured`, `.site-header--sticky`. Never a near-copy with a new name.\n- Name a block for what it is (`.plan`, `.service-card`, `.team-member`), never a bare `.card` or `.grid`: a generic name says nothing and collides with every other one on the site.\n- Decide the variants by job, not by look: primary and secondary actions, a featured tier, a compact footer. If two variants differ in one value, it is one variant with a local property.\n- Sizes are variants too (`.button--large`), set by changing the local properties the block reads, not by rewriting the rules.\n- A variant never breaks the system: the same tokens, the same radius family, the same type steps.\n\n## Every state, designed\n\nEach interactive component ships the full set, and each data component its data states:\n\n- Default, hover, focus-visible, active, disabled.\n- Loading: a skeleton that matches the layout it replaces, so nothing jumps.\n- Empty: a composed getting-started with a next step, never the word \"None\".\n- Error: names the problem and the recovery.\n- Selected or current, where it applies (a tab, a nav item, a chosen plan).\n\nOn a components page, show every variant in every state side by side, built from the project's real tokens and copy, so the owner can approve a button they have actually seen.\n\n## Content inside components\n\n- A component holds real content in the design: the client's words, real names, real numbers or `[GAP]` markers for what the client has not given. A component library is not a place for lorem.\n- Repeated content (a list of tiers, a grid of posts, a set of quotes) is one component repeated, every instance the same structure with different content.\n\n## Structure for the build\n\nHow a component is structured for Etch (its slots, its loops, its props and the class workflow) 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 decides what the parts are and how they look and behave; the build law decides how they are wired. Where they seem to disagree, the build law wins for structure and the design law wins for the look.\n\n## Naming\n\n- Name blocks for what they are (`pricing`, `tier`, `quote`, `site-header`), never for where they sit (`left-box`) or how they look (`blue-card`).\n- Elements are the block's parts (`tier__price`); modifiers are its variants (`tier--featured`).\n- The same name everywhere: in the markup, in the sections list you save, and in the component registry.\n\n## Check before you save\n\n- Did you reuse every registered component that fits, by the same name?\n- Is every variant a modifier of one block?\n- Does every interactive part have all five interaction states, and every data part its loading, empty and error states?"
300
+ },
301
+ "buttons-links": {
302
+ "id": "buttons-links",
303
+ "title": "Buttons and links",
304
+ "kind": "component",
305
+ "when": "Load before building any call to action, button, link or link-styled control.",
306
+ "body": "# Buttons and links\n\nA button says what happens next. A page has one main thing it wants a visitor to do, and it says so the same way every time.\n\n## One primary action\n\n- Each screen has one primary action, and it is the only accent-filled button in view.\n- Secondary actions are quieter: an outline in `--line-strong`, or a tint of `--accent-quiet`. Never a second accent fill.\n- Anything less important than that is a link.\n- The primary action appears at least three times on a page (in the hero, part way down, and in the closing panel), always with the same words.\n\n## Words\n\n- A verb and an object that say what happens: \"Book a site survey\", \"Start the free trial\", \"Download the price list\".\n- Never \"Submit\" and never \"Click here\". \"Learn more\" alone tells nobody anything; if it must exist, finish the sentence as a link: \"Learn more about pricing\".\n- Sentence case, no closing punctuation.\n\n## Building the block\n\n- One block, `.button`, with a modifier per variant: `.button--primary`, `.button--secondary`, `.button--quiet`, and `.button--large` when a size is needed. One class per rule.\n- At least 2.75rem tall and wide, so it is a comfortable touch target. Padding comes from the space tokens.\n- The radius is the scale's small step, `--radius-s`. Pills are for chips and tags, never buttons, and never a 50 percent radius on a wide button.\n- An icon inside a button is decorative (`aria-hidden=\"true\"`), because the label already names the action.\n- `<button>` for actions, `<a href>` for going somewhere. Never a clickable div.\n\n## On an Automatic.css site\n\nWhen the site runs Automatic.css, the buttons are the site's:\n\n- ACSS's own classes: `btn--primary`, `btn--secondary`, `btn--tertiary`, `btn--accent`, `btn--outline`, sizes `btn--xs` to `btn--xxl`. No `.btn` base class and no invented modifier.\n- ACSS's global focus ring (`--focus-color`, `--focus-width`, `--focus-offset`), never a per-button focus rule.\n- A one-off change overrides the `--btn-*` variables on a scoped selector.\n- Everywhere else, the `.button` block below.\n\n## Color\n\n- The primary fill is `--accent` and its text is `--on-accent`, measured to 4.5:1 against that accent. Do not assume white text works on every accent.\n- The fill itself needs 3:1 against the ground it sits on.\n- In a dark theme, a paper-colored button with ink text can be the clearer primary. Measure both options.\n\n## States, on every button\n\n- Hover: the button rises 1px and an overlay in `--accent-hover` fades in, over `--dur-2`. Only transform and opacity move.\n- Press: it scales to 0.98, over `--dur-1`.\n- Focus: on `:focus-visible`, a 2px accent ring 2px outside the edge. Never remove the outline without putting a ring in its place.\n- Disabled: clearly muted but still readable, with `disabled` or `aria-disabled`, and a nearby line saying why.\n- Waiting: when an action takes time, the label stays, a small spinner joins it, and the width does not change.\n\n## Links\n\n- Links inside running text are underlined; color alone does not mark a link.\n- On hover, draw the underline in with a pseudo-element, `transform: scaleX(0)` to `scaleX(1)`.\n- A link that leaves the site says so in its text or with a labeled icon.\n\n## Example\n\n```css\n.button { position: relative; isolation: isolate; display: inline-flex; align-items: center; gap: var(--space-2xs, 0.5rem); min-height: 2.75rem; padding: var(--space-xs, 0.75rem) var(--space-m, 1.5rem); border-radius: var(--radius-s, 6px); font-weight: 600; }\n.button::after { content: \"\"; position: absolute; inset: 0; z-index: -1; border-radius: inherit; background: var(--accent-hover, oklch(47% 0.13 255)); opacity: 0; }\n.button--primary { background: var(--accent, oklch(52% 0.14 255)); color: var(--on-accent, oklch(98% 0.006 80)); }\n@media (prefers-reduced-motion: no-preference) {\n .button { transition: transform var(--dur-2, 240ms) var(--ease-out, cubic-bezier(0.16, 1, 0.3, 1)); }\n .button::after { transition: opacity var(--dur-2, 240ms) var(--ease-out, cubic-bezier(0.16, 1, 0.3, 1)); }\n .button:hover { transform: translateY(-1px); }\n .button:active { transform: scale(0.98); }\n}\n.button--primary:hover::after { opacity: 1; }\n.button:focus-visible { outline: 2px solid var(--accent, oklch(52% 0.14 255)); outline-offset: 2px; }\n```\n\n## Check before you save\n\n- Is there exactly one accent-filled button on each screen?\n- Is the primary action worded the same everywhere it appears?\n- Does every button have hover, press, focus-visible and disabled styles?"
307
+ },
308
+ "cards": {
309
+ "id": "cards",
310
+ "title": "Cards",
311
+ "kind": "component",
312
+ "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?"
314
+ },
315
+ "forms": {
316
+ "id": "forms",
317
+ "title": "Forms",
318
+ "kind": "component",
319
+ "when": "Load before building any form: contact, booking, quote, newsletter, sign up, sign in or checkout.",
320
+ "body": "# Forms\n\nEach field costs the visitor something. A strong form asks for little and explains whatever it does ask.\n\n## What to ask\n\n- Only what the business will actually use. If nobody will call, the phone number is optional or gone.\n- One column. Two short fields that belong together, like first and last name, may share a row on a wide screen and stack on a narrow one.\n- Long forms are grouped with `<fieldset>` and `<legend>`, or split into steps with a visible progress line.\n- The right control for the answer: radio buttons for a few choices, a select for many, a checkbox for a single yes. Native inputs with the right `type`, `inputmode` and `autocomplete`.\n\n## Labels and help\n\n- A visible `<label>` above every field, tied to it with `for`. A placeholder is not a label, because it disappears the moment someone types.\n- When most fields are required, mark the optional ones.\n- Helper text sits under the label in `--ink-2` at `--step--1`, linked with `aria-describedby`.\n- Any placeholder is an example, not an instruction, and still meets 4.5:1.\n\n## Controls\n\n- At least 2.75rem tall and as wide as the column.\n- Edges in `--line-strong`, which holds 3:1 against the ground; radius `--radius-s`; ground `--paper` or a `--paper-3` well.\n- Focus is unmistakable: the 2px accent ring at a 2px offset that every focusable element uses. Never remove the outline without a replacement.\n- Checkboxes and radio buttons at a size people can hit, with the whole label clickable.\n\n## States\n\nDesign each one; a form that only shows the empty state is unfinished.\n\n- Error: the field's edge and a short message right beside it, in an error color that meets 4.5:1 and with an icon, so color is not the only signal. The message names the problem and the fix: \"Enter a postcode, like 2000\", never \"Invalid input\".\n- On a long form, an error summary at the top with `role=\"alert\"`, linking to each field.\n- Disabled and read-only fields look different and stay readable.\n- Sending: the submit button keeps its label, adds a spinner and keeps its width.\n- Success: a composed message saying what happens next and when (\"We will call within one working day\"), in place of the form or above it.\n\n## The submit button\n\n- It names the outcome: \"Request my quote\", \"Book the call\", \"Join the list\". Never \"Submit\".\n- It uses the primary button style and sits right under the last field.\n- When the form asks for personal details, one line near the button says what happens to them.\n\n## In SpecShot\n\n- The preview shows a form but never sends it. Build the real form, and give the error, sending and success states their own modifiers (`.form__field--error`, `.form--sent`) so a reviewer can see them.\n- Style the form with its own BEM classes, so it keeps its look whatever tool the agency connects it to on the site.\n- Never keep or show values a visitor typed on a captured site.\n\n## Example\n\n```html\n<form class=\"form\" novalidate>\n <div class=\"form__field\">\n <label class=\"form__label\" for=\"postcode\">Postcode</label>\n <input class=\"form__input\" id=\"postcode\" name=\"postcode\" inputmode=\"numeric\" autocomplete=\"postal-code\" aria-describedby=\"postcode-help\">\n <p class=\"form__help\" id=\"postcode-help\">We use it to send the nearest surveyor.</p>\n </div>\n <button class=\"button button--primary\" type=\"submit\">Request my quote</button>\n</form>\n```\n\n## Check before you save\n\n- Does every field have a visible label and a reason to be there?\n- Are the error, sending and success states designed?\n- Is every control at least 2.75rem tall, with a 3:1 edge?"
321
+ },
322
+ "icons": {
323
+ "id": "icons",
324
+ "title": "Icons",
325
+ "kind": "component",
326
+ "when": "Load before drawing any icon, icon button, feature mark, list bullet or social link.",
327
+ "body": "# Icons\n\nIcons help people find their way. A mix of icon styles makes a page look assembled from parts, and an emoji in place of an icon makes it look unfinished.\n\n## One family\n\n- Inline SVG, drawn in the design. The preview strips icon fonts, sprite sheets and linked icon files.\n- The same family everywhere on the page: a 24 by 24 viewBox, a 1.5 stroke, round caps and joins, no fill unless the whole family is filled, and `stroke=\"currentColor\"` so each icon follows the text color around it.\n- Never emoji or unicode symbols as icons. They look different on every device, and SpecShot's law check flags them.\n- Keep shapes simple enough to read at a glance. An icon that needs a caption to make sense should be replaced by the caption.\n\n## Size and weight\n\n- Inline with text, size icons in em (about 1em to 1.25em) so they grow with the label.\n- Feature marks sit at one fixed size across a set, around 2.5rem.\n- Large icons keep the same line weight as small ones: `vector-effect: non-scaling-stroke` on the paths.\n\n## Marks for a set of features\n\n- A set of equal features can carry a mark each: the icon alone, or the icon on a small tinted disc or square from the radius family. Pick one treatment for the whole set.\n- The tint comes from a role (`--accent-quiet`, `--paper-3`, or `--night-2` in a dark theme) and the icon is colored to keep 3:1 against it.\n- One icon in a box next to one paragraph is decoration. Use marks where they help people scan a set.\n\n## Accessibility\n\n- An icon beside a label is decorative: `aria-hidden=\"true\"` and `focusable=\"false\"`.\n- An icon-only control (a menu button, a close button, a social link) has a name in `aria-label` and a target at least 2.75rem square, however small the drawing.\n- An icon that carries meaning keeps 3:1 contrast against what is behind it.\n- Status icons for success, warning or error always come with words. Color and shape are not enough on their own.\n\n## Social links and logos\n\n- Social links are simple single-color marks in currentColor, each labeled with the network's name.\n- The client's own logo is redrawn as inline SVG from their real mark, or set as a wordmark in the display face. Never a linked image file and never a made-up symbol.\n\n## Example\n\n```html\n<a class=\"footer__social\" href=\"https://www.linkedin.com/company/example\" aria-label=\"LinkedIn\">\n <svg class=\"icon\" viewBox=\"0 0 24 24\" aria-hidden=\"true\" focusable=\"false\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.5\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><rect x=\"3\" y=\"3\" width=\"18\" height=\"18\" rx=\"3\"/><path d=\"M8 11v5M8 8v.01M12 16v-5M16 16v-3a2 2 0 0 0-4 0\"/></svg>\n</a>\n```\n\n```css\n.icon { inline-size: 1.25em; block-size: 1.25em; flex: none; }\n.footer__social { display: inline-grid; place-items: center; min-inline-size: 2.75rem; min-block-size: 2.75rem; color: var(--ink-2, oklch(37% 0.015 60)); }\n```\n\n## Check before you save\n\n- Is every icon inline SVG from one family, with no emoji anywhere on the page?\n- Does every icon-only control have an aria-label and a 2.75rem target?\n- Does every meaningful icon keep 3:1 against its background?"
328
+ },
329
+ "imagery-art-direction": {
330
+ "id": "imagery-art-direction",
331
+ "title": "Imagery and art direction",
332
+ "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?"
335
+ },
336
+ "typography": {
337
+ "id": "typography",
338
+ "title": "Typography",
339
+ "kind": "foundation",
340
+ "when": "Load before choosing faces or sizing any text, and whenever a page reads flat, crowded or generic.",
341
+ "body": "# Typography\n\nMost of what makes a page look expensive is type. Settle it once, as tokens, and every section reads from the same voice.\n\n## Choosing the faces\n\n- The faces come from the client, never from a default. First the faces the brand's tokens name. Then the faces the client's captures and inspiration use: SpecShot lists them as type facts in the brief, and get_wireframe_context lists each capture's fonts. With neither, choose a Google Fonts pairing that matches the character of the references (their weight, width, contrast and era), and name it in your summary as a proposal.\n- There is no house pairing to pick from. A face handed to every page reads as generated, however good it is.\n- How the faces are used follows the brand and the references too: a serif or a sans on the headings, the weights, how tight the display is set.\n- Never Inter, Roboto, Arial, Geist, Fraunces, Plus Jakarta Sans, Space Grotesk or a system face by reflex: every generated page reaches for them, so the page reads as generated at a glance. A brand that names one keeps it. Never one family doing every job at one weight either, unless the brand does exactly that.\n- Two families in all, and four weights at most across both, unless the brand sets more.\n- Embed both faces. The preview strips linked fonts, so a face that is named but not embedded shows as a fallback and nobody can say why the page feels cheap. Over MCP, get_font_faces returns the @font-face rules to paste at the top of the style block.\n- Declare them once as `--font-display` and `--font-text`, each with a fallback stack.\n\n## Sizing\n\n- Every size reads a token from the contract: `--step--1` for captions and small labels, `--step-0` for body, `--step-1` for lead text, `--step-2` and `--step-3` for headings, `--step-4` for big numbers, `--step-5` for the hero headline, `--step-6` for type used as image.\n- Each token is a clamp() between a 360px phone and a 1440px desktop. A media query never resizes text.\n- At least a 1.25 ratio between neighboring text steps, so the hierarchy is obvious at a glance. The display steps can leap further.\n- Body text is at least 1rem at every width, the phone included. Interface text never drops below 0.6875rem.\n- The biggest type on the page is at least four times the body size.\n\n## Lines and measure\n\n- Body line height between 1.5 and 1.7.\n- Headings at h3 size and smaller keep a line height of 1.3 or more. The hero headline, at `--step-5`, sits tighter, between 1.02 and 1.1, with letter spacing between -0.02em and -0.035em.\n- Lines of body text stop at `var(--measure, 65ch)` and never pass 75 characters.\n- A headline takes two or three lines. When it wants four, widen its column and step it down.\n- Leave more room above a heading than below it, so it belongs to the text it introduces.\n\n## Hierarchy\n\n- Make levels differ in size and weight. Two headings that differ only in color are the same level.\n- Body at 400, labels and buttons at 500 to 600, display at whatever weight the face looks best.\n- One h1 per page, and heading levels in order with none skipped.\n- A small label above a heading only where the brand or the client's references set one, never as an eyebrow or kicker by reflex. The heading stands on its own.\n- The headline is upright. Never an oversized italic serif, and never an italic or colored word as the headline's trick: emphasis is size and weight.\n\n## Finishing\n\n- `text-wrap: balance` on headings and `text-wrap: pretty` on paragraphs.\n- `font-variant-numeric: tabular-nums` wherever numbers are compared: prices, stats, tables.\n- Real quotation marks and apostrophes, with `hanging-punctuation: first` on pull quotes.\n- Tight tracking on large display type; a little extra tracking on small capitals.\n\n## Example\n\n```css\n.hero__title {\n font-family: var(--font-display, ui-sans-serif, sans-serif);\n font-size: var(--step-5, 2.75rem);\n line-height: 1.05;\n letter-spacing: -0.025em;\n text-wrap: balance;\n}\n.hero__lead { font-size: var(--step-1, 1.125rem); max-width: 52ch; text-wrap: pretty; }\n```\n\n## Check before you save\n\n- Are the faces the brand's or the references', both embedded, with none a banned default the brand does not name?\n- Does every font size read a --step token with a literal fallback?\n- Is the body at least 1rem at 360px?\n- Read only the headings: do they tell the story?"
342
+ },
343
+ "spacing-rhythm": {
344
+ "id": "spacing-rhythm",
345
+ "title": "Spacing and rhythm",
346
+ "kind": "foundation",
347
+ "when": "Load before laying out any section, and whenever a page feels cramped, loose or monotonous.",
348
+ "body": "# Spacing and rhythm\n\nSpace does the structural work first. Before a border, a card or a color, the gaps already say what belongs together.\n\n## The tokens\n\n- Gaps, padding and margins read the space tokens, `--space-3xs` through `--space-3xl`, each a clamp() from a 360px phone to a 1440px desktop.\n- Section padding reads `--pad-open` or `--pad-dense`, the same value above and below, and `--gutter` for the sides. Two tokens make one rhythm: five different paddings with no pattern is the measured tell of a generated page. Only a section that deliberately joins the next one changes its bottom.\n- Every use carries its phone value as a fallback: `gap: var(--space-m, 1.5rem)`.\n- Outside :root the only raw values are 0, 1px hairlines and grid percentages. A raw rem or px elsewhere is a value nobody can retune.\n- Tune the values to the brand and keep the names. Because the tokens are fluid, a media query never changes spacing.\n\n## Which step does what\n\n- `--space-3xs` and `--space-2xs`: an icon beside its label, the gap inside a chip.\n- `--space-xs`: inside a button or field, between list items.\n- `--space-s`: inside a card, between a heading and its paragraph.\n- `--space-m`: card padding, the gap between grid items.\n- `--space-l`: between groups inside one section.\n- `--space-xl`: between a section's heading and its content.\n- `--space-2xl` and `--space-3xl`: between large blocks, and the widest gap on the page.\n\n## Grouping\n\n- Close inside a group, open between groups. A reader sees the gap before the content, so proximity carries the grouping instead of a box.\n- A heading sits nearer to the text it introduces than to whatever came before it.\n- Put spacing between siblings on their parent as `gap`. Margins on every child need exceptions for the first and last.\n- A component that needs its own inner spacing declares a local property on its own class, named for it, such as `--quote-pad`.\n\n## Pace across the page\n\n- Alternate open sections (`--pad-open`) and dense ones (`--pad-dense`). One padding value everywhere gives the page one speed, and one speed reads as a template.\n- A change of ground already separates two sections. A divider between two sections on the same ground is the weaker choice.\n- When a section feels flat, change the space and the type. Do not wrap it in a box, and never put a card inside a card to make room.\n\n## Density by purpose\n\n- Pages people scan and compare (pricing tables, specifications, documentation) run dense.\n- Pages people read through (home, about, a case study) run open.\n- Most pages carry both. Decide each section's density when you plan the page, not while writing CSS.\n\n## Example\n\n```css\n.services { padding: var(--pad-open, 4.5rem) var(--gutter, 1.25rem); }\n.services__intro { margin-block-end: var(--space-xl, 3rem); }\n.services__list { display: grid; gap: var(--space-m, 1.5rem); }\n.service { --service-pad: var(--space-m, 1.5rem); padding: var(--service-pad); }\n```\n\n## Check before you save\n\n- Does every gap and padding read a token, with its phone value as fallback?\n- Does every section take one of the two padding tokens, the same above and below, and change between open and dense at least once?\n- Is each heading closer to its own content than to the block above it?"
349
+ },
350
+ "layout-grids": {
351
+ "id": "layout-grids",
352
+ "title": "Layout and grids",
353
+ "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?"
356
+ },
357
+ "color-contrast": {
358
+ "id": "color-contrast",
359
+ "title": "Color assignment and contrast",
360
+ "kind": "foundation",
361
+ "when": "Load before assigning any color to text, a surface, a control or an icon, and before calling a page accessible.",
362
+ "body": "# Color assignment and contrast\n\nColor is a handful of roles used consistently. Ask \"which role is this?\" before every color you write, and measure every place two roles meet.\n\n## The roles\n\n- Grounds: `--paper` for the page, `--paper-2` for alternate sections, `--paper-3` for wells and tracks. `--night` and `--night-2` are the grounds of a dark theme or a dark object such as a product window.\n- Text: `--ink`, then `--ink-2` for secondary text and `--ink-3` for muted text that still passes AA. On a dark ground, `--on-night` and `--on-night-2`.\n- Lines: `--line` for hairlines and `--line-strong` for the edges of controls.\n- The accent: `--accent`, `--accent-hover`, `--accent-quiet` for tinted surfaces and selected states, and `--on-accent` for text placed on it.\n- The brand's colors fill these roles. Change the values, keep the names, and never write a raw hex outside :root.\n\n## Proportion\n\n- 60 / 30 / 10: ground, then surfaces and text, then the accent.\n- The accent marks the primary action, links, focus rings and key numbers. Headings stay in ink. A screen with five accent buttons has no primary action.\n- One accent. A category is shown with a dot or a thin border, not a second palette.\n- One theme from header to footer. A light page takes its rhythm from paper, a tint and a deeper tint, and no three sections in a row share a ground. Never drop a dark band or a heavy dark block into a light page: it is a plain generated tell and outweighs everything around it.\n\n## Building the palette\n\n- Work in OKLCH. Neutrals form a ramp tinted toward the brand hue at a chroma of about 0.005 to 0.02, so grays feel alive.\n- Ink sits around 14 to 20 percent lightness and the page ground around 97 to 99 percent. Never pure black or pure white, for text or for a surface.\n- The accent's hover step mixes toward ink, `color-mix(in oklab, var(--accent) 88%, var(--ink))`, and its quiet step mixes toward the ground. Mix in oklab, never in srgb.\n- Gradients are surfaces only, never text: one hue, or two hues within 30 degrees, as a linear fill. No radial glow, spotlight or accent haze, and no grain.\n- A dark theme is designed rather than inverted: raised surfaces get lighter, and hairlines with a faint inner highlight take over from shadows.\n\n## Contrast\n\n- WCAG AA at least. Body and small text 4.5:1; large text (24px, or 18.66px bold) 3:1; the edges of controls, meaningful icons and focus rings 3:1 against what surrounds them.\n- Contrast means the WCAG contrast ratio, computed from relative luminance. How light two colors look in OKLCH is not a measurement; compute the ratio or read it from a tool.\n- Over MCP, get_brand_system returns `contrast`: every brand text and ground pair measured, failures first, and the readable text color for each brand color. Start there.\n- Text on the accent is `--on-accent`, chosen and measured for that accent. Do not assume white text works; bright accents often need dark text.\n- A filled button also needs 3:1 between its fill and the ground behind it, or it vanishes on a mid-tone section.\n- Measure muted text on each ground it actually appears on, tinted sections and dark objects included.\n- Never gray text on a colored ground: use that ground's own text role.\n\n## Example\n\n```css\n.cta { background: var(--accent, oklch(52% 0.14 255)); color: var(--on-accent, oklch(98% 0.006 80)); }\n.cta:hover { background: var(--accent-hover, oklch(47% 0.13 255)); }\n.plans { background: var(--paper-2, oklch(95.5% 0.01 80)); color: var(--ink, oklch(20% 0.015 60)); }\n```\n\n## Check before you save\n\n- Is every color in the rules a role token with a literal fallback?\n- Does the accent appear only where it belongs?\n- Has every text pair been measured, including muted text on tinted grounds?"
363
+ },
364
+ "surfaces-elevation": {
365
+ "id": "surfaces-elevation",
366
+ "title": "Surfaces and elevation",
367
+ "kind": "foundation",
368
+ "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?"
370
+ },
371
+ "motion": {
372
+ "id": "motion",
373
+ "title": "Motion and animation",
374
+ "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?"
377
+ },
378
+ "accessibility": {
379
+ "id": "accessibility",
380
+ "title": "Accessibility",
381
+ "kind": "foundation",
382
+ "when": "Load before building any page, and before calling one finished: the audit at the end is part of the job.",
383
+ "body": "# Accessibility\n\nAccessibility is part of how a page is built, not a pass at the end. The short audit at the bottom is how you show it was built that way.\n\n## Structure\n\n- Landmarks: one `<header>`, a `<nav>` for each navigation (with an `aria-label` when there is more than one), one `<main>`, a `<section>` with a heading for each section, one `<footer>`.\n- One h1 per page and headings in order. A card title under an h2 is an h3, whatever size it is drawn at.\n- Use the element that means the thing: lists for lists, tables with `<th scope>` for tabular data, `<button>` for actions, `<a href>` for links.\n- The order in the markup is the order on screen. Never move things with CSS so a screen reader hears them in a different order than people see them.\n- A `lang` attribute on the document, and on any passage in another language.\n\n## Contrast\n\nContrast is the WCAG contrast ratio, computed from relative luminance, never judged by eye.\n\n- Body and small text 4.5:1; large text (24px, or 18.66px bold) 3:1.\n- The edges of controls, meaningful icons, focus rings and chart marks 3:1 against what is next to them.\n- Check every text role on every ground it lands on: the page ground, each tinted ground, and any dark object or dark theme. Links and their hover state too.\n- A button gets two checks: its label against its fill (4.5:1) and its fill against the ground (3:1).\n- Over MCP, get_brand_system lists the brand's text and ground pairs already measured.\n\n## Keyboard and focus\n\n- Everything interactive is reachable with Tab in a sensible order and works with Enter or Space.\n- On `:focus-visible`, a 2px ring 2px outside the element, at 3:1 against the ground. On an Automatic.css site that ring is ACSS's global one (`--focus-color`, `--focus-width`, `--focus-offset`), so write no focus rule of your own there. Never remove an outline without a replacement, and never let a sticky header cover the focused element (anchors get `scroll-margin-top`).\n- A skip link to `<main>` comes first in the tab order.\n\n## Names and states\n\n- Every field has a visible `<label>`; a placeholder is not a label.\n- Every icon-only control has an `aria-label`; decorative SVG is `aria-hidden=\"true\"`.\n- A menu button or accordion reports `aria-expanded`; a `<details>` element does this by itself.\n- The current page in a navigation carries `aria-current=\"page\"`.\n- An overlay keeps focus inside while open, gives it back on close and closes on Escape.\n- Errors are announced: `role=\"alert\"` on a summary, `aria-invalid` and `aria-describedby` on the field.\n\n## Size\n\n- Body text at least 1rem; interface text never below 0.6875rem.\n- Touch targets at least 2.75rem square in every layout, with room between neighbors.\n- Content clears notches and rounded corners through safe-area insets.\n- Text still fits at 200 percent zoom and with wider line and paragraph spacing.\n\n## Motion and meaning\n\n- Every animation sits behind `prefers-reduced-motion: no-preference`. Nothing moves on its own for more than five seconds without a way to pause it.\n- Images have alt text that says what they show; decorative images have an empty alt.\n- Color is never the only signal. Errors, status and required fields also use words or an icon.\n- Links in running text are underlined.\n\n## The audit before you save\n\nState each line as pass or fail, with the element it concerns:\n\n1. Landmarks, one h1, headings in order.\n2. Every text pair at its threshold on every ground, button labels and muted text included.\n3. Every control: a name, a label, a focus ring, a 2.75rem target.\n4. Disclosures and overlays: aria-expanded, focus held, Escape closes.\n5. Reduced motion: the page complete and still."
384
+ },
385
+ "responsive": {
386
+ "id": "responsive",
387
+ "title": "Responsive behavior",
388
+ "kind": "foundation",
389
+ "when": "Load before building any page, and for the responsive pass before saving: SpecShot's frame is dragged to every width.",
390
+ "body": "# Responsive behavior\n\nSpecShot previews a design in a frame the owner drags to any width, continuously. A layout that holds at three widths and breaks at 900 has failed, and it is the most common way a design that looked fine falls apart on a real device.\n\n## Fluid first\n\n- Type and space come from the token contract, each a clamp() from a 360px phone to a 1440px desktop. A media query never changes a font size or a padding.\n- Grids reflow by content: `repeat(auto-fit, minmax(min(100%, 18rem), 1fr))` needs no breakpoint and is right at widths nobody tested.\n- Containers size with `min()`: `width: min(100% - 2 * var(--gutter, 1.25rem), var(--content, 76rem))`.\n- Every grid and flex child gets `min-width: 0`. That one line prevents most sideways scroll from a long word or a wide table.\n- Images and media: `max-width: 100%`, `height: auto` and an `aspect-ratio`, so nothing jumps.\n\n## Breakpoints, only where the layout changes\n\n- A breakpoint is the exception you justify: the navigation folding into a menu, a split becoming one column, a table becoming stacked rows.\n- Place it where the content breaks, found by dragging, not at a stock device width.\n- Prefer a container query for anything inside a component. A card in a sidebar and the same card in a hero are different widths at the same viewport, and only a container query gets both right.\n- Name what changes at each breakpoint in your notes. A design with ten breakpoints is a design that was not built fluid.\n\n## The pass\n\nBefore saving, drag through every width and look:\n\n1. 360 to 430: one column, the primary action visible on the first screen, no sideways scroll, text at least 1rem.\n2. 600 to 900: the awkward middle. Two-column splits often break here; grids should be at two columns, not stretched singles.\n3. 1024 to 1440: the designed layout.\n4. 1920 and wider: content held at `--content`, grounds and bleeds running to the edges, nothing floating in a sea of space.\n\n## Height and the device\n\n- dvh and dvw, never vh: on a phone vh measures past the toolbar and a full-screen hero is cut off. Use `min-height: min(100dvh, 56rem)` only when the content fills it.\n- Respect safe-area insets (`env(safe-area-inset-left)`) for anything at the screen edge.\n- Touch targets at least 2.75rem square in every layout.\n\n## Touch and pointer\n\n- Anything that only happens on hover is unreachable on a phone. Give it a tap, a visible default or a scroll equivalent.\n- A cursor-following effect does nothing on touch; its fallback is a calm static state.\n- `@media (hover: hover)` wraps hover-only polish, so touch devices do not get sticky hover states.\n\n## Wide content\n\n- The body never scrolls sideways. A wide table or code block scrolls inside its own container with `overflow-x: auto`, a visible edge hint and keyboard focus.\n- A rail of cards uses `scroll-snap-type: x mandatory` with the last card cut at the edge to say there is more.\n\n## Example\n\n```css\n.features__grid { display: grid; gap: var(--space-m, 1.5rem); grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr)); }\n.feature { min-width: 0; container-type: inline-size; }\n@container (width > 26rem) { .feature__inner { display: grid; grid-template-columns: auto 1fr; gap: var(--space-s, 1rem); } }\n```\n\n## Check before you save\n\n- Is there no sideways scroll at any width from 360 to 1920?\n- Does every breakpoint mark a real change of layout, and none resize type?\n- Can every hover effect be reached on touch?"
391
+ },
392
+ "etch-acss-build": {
393
+ "id": "etch-acss-build",
394
+ "title": "The Etch and ACSS build",
395
+ "kind": "build",
396
+ "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?"
398
+ },
399
+ "agency-process": {
400
+ "id": "agency-process",
401
+ "title": "The agency process",
402
+ "kind": "page",
403
+ "when": "Load at the start of any client project, before starting or finishing a phase, and before anything is drafted for a client.",
404
+ "body": "# The agency process\n\nThe owner's process for a client website, with SpecShot as the place it lives. The client, the project, the brief, the pages and their versions, the review rounds and every decision are in SpecShot, so each phase reads from the project and writes back to it.\n\n## Four phases, each behind a gate\n\n1. Discovery. The interview (get_skill discovery-interview) fills the brief with set_project_intelligence beside the answers the client gives in the portal (get_discovery_answers). The pages it implies are added with create_page, and the client accepts the plan in the portal.\n2. Copy and wireframe, together, page by page, Home first, as a version of each page on the canvas (get_skill copy-and-wireframe). The client approves each page's wireframe in a review round.\n3. Design, from the approved wireframes and never on them: the direction board first, then each page at full fidelity (get_skill design-for-acss). The client approves each page.\n4. Development. The approved design goes to Etch through Build in Etch, then is refined there (get_skill etch-development).\n\n- Before a phase starts, establish which project it is (list_projects), read where it stands (get_project_state), and confirm the client approved the phase before. If they did not, say so and stop.\n- Say in one sentence which phase this is and what it will produce.\n- An approved wireframe reads as an approved page in SpecShot's page states. Never build a wireframe in Etch: development starts from the approved design only.\n\n## Never invent a client fact\n\n- No price, date, statistic, year founded, certification, award, team size, lead time, service area or quote that did not come from the client.\n- Where one is missing, leave a visible marker in the copy, `[GAP: years in business]`. Where the owner said it but nothing confirms it, mark it `[UNVERIFIED: 24-hour callout]`. Never `[placeholder]`, TBD or lorem, which the law check blocks.\n- List every gap in the brief's open questions (set_project_intelligence, openQuestions) and say how many are open whenever you report.\n- A plausible guess in client copy is worse than a blank. Proof especially: when it is thin, say so and ask for it.\n- A client's written answers outrank notes given from memory. Where they differ, quote the written one and ask.\n\n## The client's voice, and no filler\n\n- Client work is written in the client's voice, from the brief and the words they chose for how the site should come across, never in the agency's own voice.\n- Unconfirmed information is left out or asked for, never filled with something that sounds right.\n- No em dashes in client work: briefs, page copy, headlines, calls to action, wireframe and interface text, meta descriptions. Use commas, colons, periods or parentheses. Emails and internal notes are not covered.\n\n## The gates are the owner's\n\n- Nothing reaches a client without the owner reading it first. You draft; sending a review round, approving and confirming a page live are for people only.\n- A client does not reorder the process. If a client asks for an extra approval step or a different order, report it to the owner and do not offer to accommodate it.\n- Going backwards costs money. When a request would move a project back a phase, say how far back it reaches and which approved work it invalidates. Never name a fee: that is the owner's call.\n- Scale decides it. Changing a word of approved copy is nothing; rewriting whole sections is a step back.\n\n## Decisions are written down\n\n- Record a decision the day it is made. A standing project decision, constraint or instruction goes in the brief with set_project_intelligence (read the brief first and keep every field you did not change). Taste a person stated goes in with save_decision, in their words, saying who said it.\n- Approvals and requested changes are recorded by SpecShot when people decide in the portal; read them with get_project_memory and never record one yourself.\n- When a decision is superseded, replace it rather than stacking a contradiction under it. Never record a guess as confirmed.\n\n## Finishing a phase\n\nSay what was produced and where it is in SpecShot, how many questions are open with the two or three that matter, and what the next phase needs first, which is usually the client's approval that the owner sends."
405
+ },
406
+ "discovery-interview": {
407
+ "id": "discovery-interview",
408
+ "title": "The discovery interview",
409
+ "kind": "page",
410
+ "when": "Load when the owner says new client or start discovery, before interviewing anyone about a client, a project or its brief.",
411
+ "body": "# The discovery interview\n\nHow to run discovery as a conversation, and how the answers become the project's brief in SpecShot. The brief is the source of truth for every later phase.\n\n## Before the first question\n\n- Establish the project (list_projects, then get_project_state) and read what exists: get_project_intelligence, and the client's own answers to the portal questionnaire (get_discovery_answers). Never ask again what the client already answered; confirm it or ask what changed.\n- Ask whether you are talking to the business owner or to someone relaying the client's answers. It changes how hard to push, and pushing a client directly is the owner's call.\n\n## How to ask\n\n- One to three related questions per turn, then wait. Never paste the question list, and never answer your own question.\n- Answers often arrive long, because many people dictate. Read each one fully before moving on; most of the next questions are already answered in it.\n- Refuse vague answers. \"Professionals\", \"high quality\" and \"we care more\" are not answers: ask for a name, a number, a real customer, a sentence someone actually said.\n- When a word you were given does not parse, ask rather than guess.\n- When the owner hedges (\"I think\", \"about\", \"I'd have to check\"), it is not a fact. Record it as unverified and say so.\n- Do not ask about timelines or budget. By discovery the money is settled, and discovery is input for the marketing, the copy and the design only.\n\n## What to cover, in the questionnaire's order\n\n1. Goals: what the site has to do, what a convinced visitor does next, how the client will know it worked.\n2. The offer: what they sell in a customer's words, what to push hardest, who they do not want.\n3. The audience: the best customer, their problem, the main objection, words a customer actually used, who signs off.\n4. The market: two or three competitors, and why someone picks this business over them.\n5. The pages the site needs, and what each one must do.\n6. The brand: three words for how it should come across, a site they love and one they cannot stand, the logo, colors and fonts they have, anything off-limits.\n7. Proof: named results, real numbers, photos and documents, and anything they may not legally say.\n\n## A new client\n\nBefore the first project of a new client, a person creates the client and the project in SpecShot (Clients, then Projects). Then interview the owner, one question at a time, and stop when another question would only produce detail nobody needs:\n\n- Who they are: what the business does, its customers, its size, where it is, its website.\n- The people: names, exact titles, who has final say, who handles the day to day, anyone outside the company involved.\n- Approvals: who approves what, where, and how quickly they answer.\n- Money: only what the owner offers, recorded exactly, never rounded.\n- What is happening now: open work, recent work, what waits on whom.\n- The voice: who they speak to, how they sound, words they use or avoid, the page that shows them at their best.\n- The site: what it runs on, anything custom or fragile, and the platform for the build, Etch on WordPress or Etch Studio. Ask it outright, never infer it, and ask early when a decision depends on it (membership, a shop, a plugin feature, rebuilding a WordPress site in place).\n- Anything else: contract status, history, and \"anything I have not asked about?\"\n\n## Write as you go\n\n- After every section, write it to the brief with set_project_intelligence: the question and answer pairs under discovery (they append), and the fields the section fills (businessGoals, targetAudience, pageGoals, constraints, platformPreferences). A dropped session then costs one section.\n- Mark every unknown as an open question (openQuestions). Never fill a field with something plausible.\n- Use `[UNVERIFIED]` for something stated but not confirmed and `[GAP]` for something unknown, the same markers the copy uses. Never a third option.\n- For a regulated field (legal, medical, financial), list the claims that must never be written without a document behind them in constraints.\n- Add the pages the brief implies with create_page once the owner agrees the list. The client accepts the plan in the portal.\n\n## When you finish\n\nSay how many questions are open (a number), which three or four matter most and why, and what the client still has to send. Never contact the client, never set a price, and never touch a site."
412
+ },
413
+ "copy-and-wireframe": {
414
+ "id": "copy-and-wireframe",
415
+ "title": "Copy and wireframe",
416
+ "kind": "page",
417
+ "when": "Load when the owner says start copywriting, and before writing page copy or building a wireframe for a client page.",
418
+ "body": "# Copy and wireframe\n\nCopy and the wireframe are one phase. A page of copy in a text file is hard to judge, because whether a headline carries a section or a proof block lands only shows when it is laid out. So the copy is written straight into a wireframe on SpecShot's canvas, page by page, and the client approves it there.\n\n## Before you start\n\n- Confirm the client accepted the brief and the page plan (get_project_state). If not, say so and stop.\n- Which page? Home first, then About, the services overview, each service page, then the rest. Home sets the voice, the structure and the proof pattern the others borrow.\n- SpecShot's direction gate holds page designs until a direction is agreed, and in this process the wireframes come first. So once per project, ask the owner to confirm that the gate is waived for the wireframe round only, and record it in the brief's decisions with set_project_intelligence.\n\n## Build the wireframe in SpecShot\n\n- Read the brief and the client's rules first (get_wireframe_context), then write the copy into the page as you lay it out. Never draft a full set of copy as text and offer to wireframe it afterward.\n- The wireframe is the whole page, header to footer, in the client's voice, with every missing fact a visible `[GAP]` marker. Layout, hierarchy and words are what the client approves; the brand direction comes in design.\n- Publish it as a version of its page with publish_page_version (pageSlug, and the sections in order), named for what it is, for example \"Home wireframe\", so nobody mistakes it for the design.\n- Work in small steps, one section at a time, and look at the result between them.\n- Revise with revise_wireframe and the baseVersion you read, never by starting the page again.\n\n## The wireframe is the source of truth for copy\n\n- The words on the approved wireframe are the copy. Never present an older version's words as current: read the version first (get_design_versions).\n- Where per-section copy in the project (get_project_copy) says something different, say what differs and ask the owner which is current. Never pick one silently.\n- Design edits copy too. A headline shortened to fit is a copy change: say so when the design goes for review.\n\n## Wireframe habits worth keeping\n\n- A set of short items (features, values, steps) comes in a number that fills its rows evenly at every width.\n- The header does not repeat an action: a Contact button means no Contact link beside it.\n- If the agency credits itself in client footers, put the credit in every wireframe from the start.\n- Shared parts (the header, the footer, a notice bar) are built once and reused by the same name (list_components), never redrawn.\n\n## Approval\n\n- The owner reads the wireframes and sends them to the client in a review round; sending is theirs.\n- Design does not start on a wireframe the client has not approved.\n- The approved wireframe stays as the record of what the client approved. Design builds a new design for the page beside it and never edits it; a plain factual slip, such as a wrong page name, may be fixed there, and you say so.\n\n## If the agency also sketches in Paper\n\n- SpecShot's version is what the client approves, so anything settled in Paper is published to the canvas before review.\n- Paper's connection loads only when Paper is open before the session starts. In Paper, write a container and its children in one call, give a bold word its own text node, and use inline SVG or an https image, because local file images do not render."
419
+ },
420
+ "design-for-acss": {
421
+ "id": "design-for-acss",
422
+ "title": "Design for ACSS",
423
+ "kind": "foundation",
424
+ "when": "Load when the owner says start design, before the Design Direction board, and before designing any page from an approved wireframe.",
425
+ "body": "# Design for ACSS\n\nHow the design phase sets up a site so Automatic.css can build it with nothing translated. Decide these at the start of design, on the project's Design Direction board (the design_direction prompt), and record the numbers there.\n\n## Colors as ACSS families\n\n- Map the brand to ACSS's roles: primary (the main action color), secondary, and optionally tertiary and accent, plus base (dark text and dark sections) and neutral.\n- SpecShot's `--accent` token is the site's primary action color, and the export maps it to ACSS's `--primary`. ACSS's own accent family is a different color: label it as such on the board.\n- Tints and shades come from those colors the way ACSS makes them: ultra-light, light, semi-light, semi-dark, dark, ultra-dark.\n- Never invent a color outside the brand palette. A light background is a light shade of a brand color.\n\n## A fluid type scale\n\n- Set a base size and a ratio for desktop and another pair for mobile, for headings and for text. Every size in the design is a step of that scale, and SpecShot's `--step-*` tokens are those steps as clamp() values from the mobile size to the desktop size.\n- Only use sizes on the scale. A one-off size that looks better is what breaks the handoff.\n- On phones ACSS pins h5 and h6 to the text scale, so anything that must read as a heading on a phone is h4 or larger.\n- A size that dips at tablet and rises again on a phone cannot be one fluid value. Decide it in design.\n\n## Space, radius and buttons\n\n- Spacing comes from the space scale and the section space steps: SpecShot's `--space-*` and `--pad-*` tokens follow ACSS's space and section space on export.\n- One radius family, and consistent borders.\n- Buttons as ACSS variants: primary, secondary, outline, at one size unless a difference is deliberate.\n- Record on the board the base and ratio pairs, the color families with their values, the fonts, the button style and the radius. Development types these into ACSS or turns them into a settings file.\n\n## Designing from the approved wireframes\n\n- Design starts from the approved wireframes and never edits them. Each page's design is a new design beside its wireframe (publish_page_version with the page's slug).\n- Text on a design matches the approved wireframe exactly. Add nothing, not even a label; if the design seems to need text the wireframe lacks, ask.\n- Page by page, Home first. Several directions for one page side by side are normal, and a second direction is a different design, not the same layout restyled.\n- Shared parts (the header, the footer, a notice bar) are built once and reused by the same name, never redrawn, so small differences cannot creep in.\n- Images are chosen during design from the client's images (list_images), not left for development. A slot still waiting for a photo the client owes is light gray, never a brand color block, and the review says what it waits for.\n- Superseded designs are archived, never deleted.\n- When a build decision later overrules a design, update the design the same day, so design and site never disagree.\n- No unrequested polish: change what was asked and flag anything else."
426
+ },
427
+ "section-authorship": {
428
+ "id": "section-authorship",
429
+ "title": "Section authorship",
430
+ "kind": "page",
431
+ "when": "Load before planning or reviewing the sections of any page: each section's job, its anchor and its archetype, and the rules that keep a page from repeating itself.",
432
+ "body": "# Section authorship\n\nHow each section on a page earns its place. Page composition (get_skill page-composition) orders the sections; this skill decides what each one is.\n\n## One job, one anchor\n\n- Each section has one communication job: the one question it answers for the visitor. Write it as one sentence before any markup. A section that answers two questions becomes two sections, and one that answers none is cut.\n- Each section has one dominant anchor, the thing seen first: a headline, a real image, a working surface, a route of steps, a piece of evidence, a person, a decision control or a set of numbers.\n- Every section has a heading that makes its claim and a reason from the brief to exist.\n\n## Archetypes\n\nName each section's arrangement with one archetype. The screenshot analysis uses the same words, so a capture and a page compare directly:\n\nnavigation bar, centered stack, editorial split, offset stage, layered field, even grid, controlled mosaic, editorial shelf, long rail, evidence pairing, comparison plane, reading column, converging close.\n\n## Variety by rule\n\n- One archetype appears at most twice on a page.\n- Two neighboring sections never share an archetype or a dominant anchor.\n- Never place two mosaics, two carousels or two inverted stages side by side.\n- A mosaic has unequal regions and one clear dominant item. Equal tiles are an even grid, and an even grid is never the answer for every list.\n- Never repeat one hero, proof strip, process layout or closing section across the pages of a site. Each kind of page gets its own entry composition.\n- Never give every section the same heading cadence, or headings where only the noun changes.\n\n## Never fill to a number\n\nA long page earns its length with real content. If the verified content cannot carry another section, stop: never add a section, a card or a statistic to reach a count. A short page is better than a padded one.\n\n## Decide before you build a section\n\n| Decision | What to write down |\n| --- | --- |\n| Job | The question it answers. |\n| Anchor | What the eye lands on first. |\n| Archetype | One name from the list above. |\n| Content | Where the words, items and media come from, and who owns them. |\n| Media | What the image proves or explains. Decoration alone is not a job. |\n| Action | What the visitor can do next, and why here. |\n| Motion | The one change that carries meaning, or none. |\n| Phone | How it recomposes for touch, not only how it stacks. |\n| Extremes | Long titles, missing media, missing proof, an empty list. |\n| Static | How it reads with no motion and no script. |\n| Veto | Which nearby archetype, anchor or motion it must not repeat. |\n\n## Rejected on sight\n\n- An eyebrow or kicker above a heading by reflex: never. The heading carries its own weight, and a small label stays only where the brand or the client's references set one.\n- A row of three equal feature cards, a wall of repeated cards, or a card inside a card: never.\n- An invented number, quote, logo, award or availability claim. A missing fact is a labeled gap, never a guess.\n- A fake dashboard or interface built from boxes to look busy: never.\n- Repeated filler copy, and one identical entrance animation on every section: never.\n\n## Check before you save\n\n- Can you state each section's job and anchor in one line?\n- Does any archetype appear more than twice, or twice in a row?\n- Would each section still hold up with its real words and its media missing?"
433
+ },
434
+ "design-qa-gate": {
435
+ "id": "design-qa-gate",
436
+ "title": "Design QA gate",
437
+ "kind": "page",
438
+ "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."
440
+ },
441
+ "etch-development": {
442
+ "id": "etch-development",
443
+ "title": "Etch development",
444
+ "kind": "build",
445
+ "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."
447
+ },
448
+ "etch-structure": {
449
+ "id": "etch-structure",
450
+ "title": "Etch structure",
451
+ "kind": "build",
452
+ "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."
454
+ },
455
+ "etch-css": {
456
+ "id": "etch-css",
457
+ "title": "Etch CSS",
458
+ "kind": "build",
459
+ "when": "Load before writing or changing styles in Etch, by hand or through the Etch Connector, and before choosing a button or a variable on an ACSS site.",
460
+ "body": "# Etch CSS\n\nThe owner's CSS rules for Etch with Automatic.css. In a SpecShot design, tokens keep their canonical names and the export maps them to ACSS (etch-acss-build). In Etch itself, after the build, styles read the site's own ACSS variables.\n\n## Selectors\n\n- Flat, element-level selectors: each BEM element is its own rule. No `&__` stemming and no descendant selectors.\n- Nest only pseudo-classes, pseudo-elements and media or container queries inside an element's own rule.\n- Logical properties: padding-block, margin-inline, inline-size.\n- Anything animated carries a reduced-motion block in its own rule.\n- A value repeated across elements becomes one local custom property on their nearest shared ancestor.\n- Prefer vanilla CSS and avoid JavaScript and custom PHP: details for accordions, scroll snap for sliders, `:has()` and `:checked` for state. If something truly needs script, stop and ask first.\n\n## Traps Etch sets\n\n- Never combine two custom media queries in one media rule, such as `(--m-up) and (--l-down)`. Etch expands custom media and can drop the second name silently, so use single names and let the larger breakpoint override.\n- A `:has()` nested inside `:has()` drops the whole rule silently.\n- Keyframes go in an Etch stylesheet, never in a style record.\n- Write a zero length in a custom property as `0px` when a calc() may read it.\n\n## ACSS variables in Etch\n\n- Every design value is an ACSS custom property, and only a name that exists in this site's ACSS.\n- Ask the builder first: `etch.skills.list()`, and when an acss skill is listed, read it and its references. It reflects the ACSS actually installed, so it beats any other source.\n- Otherwise use the ACSS documentation (https://docs.automaticcss.com), and on Etch Studio confirm the ACSS stylesheet is in the project before writing any variable.\n- On WordPress, do not look for ACSS tokens through the builder's variables or stylesheets: ACSS loads outside the builder, so they come back empty.\n- Check that a variable exists before using it. A missing one fails silently: a gap computes to 0 and a color to nothing. Default ACSS 4 has no `--space-xxs` below `--space-xs`, and a family that is switched off (base, neutral) resolves to nothing.\n- Hard-coded values are for layout geometry only: grid fractions, aspect ratios, z-index.\n- Never reassign an ACSS variable globally and never redefine a `btn--*` class for a one-off. Override the `--btn-*` variables on a scoped selector instead.\n- If an ACSS setting does the job, use the setting, not CSS.\n- Focus rings: ACSS ships a global focus-visible ring built on `--focus-color`, `--focus-width` and `--focus-offset`. Never write per-element focus CSS in Etch; where a color must differ, set `--focus-color` on the element.\n\n## Buttons belong to ACSS\n\n- Solid: `btn--primary`, `btn--secondary`, `btn--tertiary`, `btn--accent`, `btn--base`, `btn--neutral`. Outline: add `btn--outline`. Size: `btn--xs` to `btn--xxl`.\n- No `.btn` base class and no invented modifiers. Ask which variant the site's buttons are before building the first one, and check that family is enabled.\n- A button element with a `btn--*` class can lose ACSS's font weight to Etch's reset. Put `font-weight: var(--btn-font-weight)` back on its own class.\n\n## Clickable cards\n\n- The title is the link. Put ACSS's clickable-parent and focus-parent recipe CSS on the card's own style record.\n- Recipes are an editor feature typed into a CSS input, so the connector cannot apply them. Hand the owner the selector to expand, or write the expanded CSS.\n- If ACSS's external link indicator is on and the link opens a new tab, add the link's class to the indicator's exclusions, or the card stops being clickable."
461
+ },
462
+ "etch-connector-runtime": {
463
+ "id": "etch-connector-runtime",
464
+ "title": "Etch Connector runtime",
465
+ "kind": "build",
466
+ "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."
468
+ },
469
+ "etch-connector-gotchas": {
470
+ "id": "etch-connector-gotchas",
471
+ "title": "Etch Connector gotchas",
472
+ "kind": "build",
473
+ "when": "Load before editing an Etch page through the Etch Connector after a SpecShot build: the script cadence, where CSS really ships, the classes a save drops, and how to verify.",
474
+ "body": "# Etch Connector gotchas\n\nVerified facts about the Etch API that apply once a SpecShot build is in Etch. Read etch-connector-runtime too (get_skill each).\n\n## The cadence\n\n1. One script for structural changes: create, delete, move and class changes.\n2. One script for the class pass.\n3. One script for the save.\n\nNever put structure and the save in one script: the builder settles structural changes between scripts, and a save in the same script can store a half-built tree. Read the tree again after every delete, never deleting from one stale snapshot. SpecShot's build script already saves and pauses between its own passes, so run it on its own and start your edits in a fresh script after it reports.\n\n## Scripts\n\n- No backticks anywhere in a connector script, comments included. Join strings with + and \\n.\n- `etch.components.list()` is synchronous. Loops are `etch.loops.getAll()`, never `list()`. `etch.styles.create(selector, css)` takes two arguments, not an object, and there is no `etch.styles.get`: use `list().find()`.\n- `createAsync` makes an empty component and ignores any blocks. Create it, then `updateAsync` it with the tree.\n- `etch.loops.update` takes the whole loop object, its config included, never a part of it.\n- If every script times out while the connector still runs, the builder tab hung. Reload it.\n\n## Where CSS ships\n\n- Etch prints a Class Manager style only for elements on the page itself. A class that lives only inside a component may never ship from there, so SpecShot's build also writes those rules into the design's named stylesheet. Edit them there.\n- A named stylesheet ships in full and wins over a Class Manager style for the same selector. Before editing a class, search the named stylesheets for its selector, because an edit in the losing place changes nothing. SpecShot's build renames a design class that the site's own stylesheet already styles.\n- A rule that must ship whatever classes a script adds later (theme, state) belongs in a named stylesheet.\n- When a rule loses the cascade, find the winning rule and change it there. Never add a fixes sheet on top.\n\n## Classes a save drops\n\n- A builder save strips every class with no linked style record, even a save with no changes: wrappers, script hooks and classes styled only from a parent rule. Give each one its own record, holding a harmless custom property when the class only exists for a script, and link it. SpecShot's build does this for the classes inside its components.\n- `addClass` mangles a dynamic class such as `card--{item.layout}`. Set dynamic modifiers in the class attribute with `setAttribute`, and keep `addClass` for static classes.\n- After adding a new static class inside a component, check that `getJson(id).styles` holds its style id. If it does not, relink it with `etch.blocks.replace` and the styles array.\n- After `enterComponentEditMode`, the instance has a new id. Find it again by its component id.\n\n## Loops and data\n\n- Never name a loop item post: it collides with WordPress's own post. SpecShot uses item.\n- Loop children read `{item.*}`, or the loop's own item name. Templates read `{this.*}`. Built-in keys are camelCase, such as `user.loggedIn`.\n- Query arguments belong in the loop definition, never in a block's loop parameters.\n\n## ACSS v4 names\n\n- No `--radius-pill`: use `--radius-circle`. No `link--*` classes.\n- Color variables have no color- prefix: `--primary`, not `--color-primary`.\n- Section padding reads `--section-space-*`; `--space-*` is for gaps and padding inside a section.\n- The extended scale (2xs, 2xl and beyond) exists only where the site turned it on.\n\n## Verify\n\nA saved record is not a shipped rule. After a reload that skips the cache, read the computed style of the live element, in each theme the design ships, and check the saved post content, not only the builder."
475
+ }
476
+ };