@scayver/specshot-mcp-server 0.11.0 → 0.14.0

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