@scayver/specshot-mcp-server 0.13.0 → 0.22.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/README.md +67 -10
- package/dist/build-standard.js +1070 -743
- package/dist/client.js +53 -3
- package/dist/index.js +37 -3
- package/dist/skills.js +193 -54
- package/dist/tool-descriptions.js +73 -12
- package/dist/tools/agent-loop.js +5 -0
- package/dist/tools/brand.js +64 -0
- package/dist/tools/canvas.js +2 -2
- package/dist/tools/concepts.js +28 -1
- package/dist/tools/etch-ai.js +37 -0
- package/dist/tools/etch-audit.js +30 -0
- package/dist/tools/knowledge.js +60 -0
- package/dist/tools/library.js +71 -0
- package/dist/tools/live.js +94 -0
- package/dist/tools/offline.js +16 -0
- package/dist/tools/project-edit.js +55 -0
- package/dist/tools/references.js +106 -0
- package/dist/tools/review.js +10 -0
- package/dist/tools/search-console.js +25 -0
- package/dist/tools/seo.js +82 -0
- package/dist/tools/site.js +23 -0
- package/dist/tools/skills.js +25 -7
- package/dist/tools/tasks.js +60 -0
- package/dist/tools/wireframe.js +27 -0
- package/dist/tools/wordpress.js +33 -3
- package/package.json +1 -1
package/dist/skills.js
CHANGED
|
@@ -11,211 +11,315 @@ export const SKILL_LIST = {
|
|
|
11
11
|
"id": "page-composition",
|
|
12
12
|
"title": "Page composition",
|
|
13
13
|
"kind": "page",
|
|
14
|
-
"when": "Load before planning any whole page: which sections it has, in what order, on which ground, at what density."
|
|
14
|
+
"when": "Load before planning any whole page: which sections it has, in what order, on which ground, at what density.",
|
|
15
|
+
"parts": 1
|
|
15
16
|
},
|
|
16
17
|
{
|
|
17
18
|
"id": "direction-by-niche",
|
|
18
19
|
"title": "Choosing a direction by niche",
|
|
19
20
|
"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
|
+
"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.",
|
|
22
|
+
"parts": 1
|
|
21
23
|
},
|
|
22
24
|
{
|
|
23
25
|
"id": "navigation-header",
|
|
24
26
|
"title": "Navigation and headers",
|
|
25
27
|
"kind": "section",
|
|
26
|
-
"when": "Load before building the site header, the main navigation, a mobile menu or any sub-navigation."
|
|
28
|
+
"when": "Load before building the site header, the main navigation, a mobile menu or any sub-navigation.",
|
|
29
|
+
"parts": 1
|
|
27
30
|
},
|
|
28
31
|
{
|
|
29
32
|
"id": "hero",
|
|
30
33
|
"title": "Hero sections",
|
|
31
34
|
"kind": "section",
|
|
32
|
-
"when": "Load before building the first section of any page: a hero, an intro, a page header or a landing block."
|
|
35
|
+
"when": "Load before building the first section of any page: a hero, an intro, a page header or a landing block.",
|
|
36
|
+
"parts": 1
|
|
33
37
|
},
|
|
34
38
|
{
|
|
35
39
|
"id": "content-long-text",
|
|
36
40
|
"title": "Content sections and long text",
|
|
37
41
|
"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."
|
|
42
|
+
"when": "Load before building features, services, how it works, about, story, blog posts, case studies, legal pages or any section that is mostly words.",
|
|
43
|
+
"parts": 1
|
|
39
44
|
},
|
|
40
45
|
{
|
|
41
46
|
"id": "social-proof",
|
|
42
47
|
"title": "Testimonials and social proof",
|
|
43
48
|
"kind": "section",
|
|
44
|
-
"when": "Load before building testimonials, reviews, client logos, case study teasers, stats, ratings, awards or press mentions."
|
|
49
|
+
"when": "Load before building testimonials, reviews, client logos, case study teasers, stats, ratings, awards or press mentions.",
|
|
50
|
+
"parts": 1
|
|
45
51
|
},
|
|
46
52
|
{
|
|
47
53
|
"id": "pricing",
|
|
48
54
|
"title": "Pricing",
|
|
49
55
|
"kind": "section",
|
|
50
|
-
"when": "Load before building any pricing table, plan comparison, rate card, package list or quote explainer."
|
|
56
|
+
"when": "Load before building any pricing table, plan comparison, rate card, package list or quote explainer.",
|
|
57
|
+
"parts": 1
|
|
51
58
|
},
|
|
52
59
|
{
|
|
53
60
|
"id": "faq",
|
|
54
61
|
"title": "FAQ",
|
|
55
62
|
"kind": "section",
|
|
56
|
-
"when": "Load before building an FAQ, a questions and answers block, an objections section or any accordion."
|
|
63
|
+
"when": "Load before building an FAQ, a questions and answers block, an objections section or any accordion.",
|
|
64
|
+
"parts": 1
|
|
57
65
|
},
|
|
58
66
|
{
|
|
59
67
|
"id": "footer",
|
|
60
68
|
"title": "Footers",
|
|
61
69
|
"kind": "section",
|
|
62
|
-
"when": "Load before building any site footer, and the closing call to action that usually sits above it."
|
|
70
|
+
"when": "Load before building any site footer, and the closing call to action that usually sits above it.",
|
|
71
|
+
"parts": 1
|
|
63
72
|
},
|
|
64
73
|
{
|
|
65
74
|
"id": "components-variants",
|
|
66
75
|
"title": "Components and variants",
|
|
67
76
|
"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."
|
|
77
|
+
"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.",
|
|
78
|
+
"parts": 1
|
|
69
79
|
},
|
|
70
80
|
{
|
|
71
81
|
"id": "buttons-links",
|
|
72
82
|
"title": "Buttons and links",
|
|
73
83
|
"kind": "component",
|
|
74
|
-
"when": "Load before building any call to action, button, link or link-styled control."
|
|
84
|
+
"when": "Load before building any call to action, button, link or link-styled control.",
|
|
85
|
+
"parts": 1
|
|
75
86
|
},
|
|
76
87
|
{
|
|
77
88
|
"id": "cards",
|
|
78
89
|
"title": "Cards",
|
|
79
90
|
"kind": "component",
|
|
80
|
-
"when": "Load before building any card, tile, feature grid, team grid, product grid or post list."
|
|
91
|
+
"when": "Load before building any card, tile, feature grid, team grid, product grid or post list.",
|
|
92
|
+
"parts": 1
|
|
81
93
|
},
|
|
82
94
|
{
|
|
83
95
|
"id": "forms",
|
|
84
96
|
"title": "Forms",
|
|
85
97
|
"kind": "component",
|
|
86
|
-
"when": "Load before building any form: contact, booking, quote, newsletter, sign up, sign in or checkout."
|
|
98
|
+
"when": "Load before building any form: contact, booking, quote, newsletter, sign up, sign in or checkout.",
|
|
99
|
+
"parts": 1
|
|
87
100
|
},
|
|
88
101
|
{
|
|
89
102
|
"id": "icons",
|
|
90
103
|
"title": "Icons",
|
|
91
104
|
"kind": "component",
|
|
92
|
-
"when": "Load before drawing any icon, icon button, feature mark, list bullet or social link."
|
|
105
|
+
"when": "Load before drawing any icon, icon button, feature mark, list bullet or social link.",
|
|
106
|
+
"parts": 1
|
|
93
107
|
},
|
|
94
108
|
{
|
|
95
109
|
"id": "imagery-art-direction",
|
|
96
110
|
"title": "Imagery and art direction",
|
|
97
111
|
"kind": "component",
|
|
98
|
-
"when": "Load before placing any image, hero visual, gallery, product shot, portrait, diagram or background."
|
|
112
|
+
"when": "Load before placing any image, image spot, hero visual, figure, gallery, product shot, portrait, diagram or background.",
|
|
113
|
+
"parts": 1
|
|
99
114
|
},
|
|
100
115
|
{
|
|
101
116
|
"id": "typography",
|
|
102
117
|
"title": "Typography",
|
|
103
118
|
"kind": "foundation",
|
|
104
|
-
"when": "Load before choosing faces or sizing any text, and whenever a page reads flat, crowded or generic."
|
|
119
|
+
"when": "Load before choosing faces or sizing any text, and whenever a page reads flat, crowded or generic.",
|
|
120
|
+
"parts": 1
|
|
105
121
|
},
|
|
106
122
|
{
|
|
107
123
|
"id": "spacing-rhythm",
|
|
108
124
|
"title": "Spacing and rhythm",
|
|
109
125
|
"kind": "foundation",
|
|
110
|
-
"when": "Load before laying out any section, and whenever a page feels cramped, loose or monotonous."
|
|
126
|
+
"when": "Load before laying out any section, and whenever a page feels cramped, loose or monotonous.",
|
|
127
|
+
"parts": 1
|
|
111
128
|
},
|
|
112
129
|
{
|
|
113
130
|
"id": "layout-grids",
|
|
114
131
|
"title": "Layout and grids",
|
|
115
132
|
"kind": "foundation",
|
|
116
|
-
"when": "Load before choosing a section's
|
|
133
|
+
"when": "Load before choosing a section's layout or building any grid, and when a page reads as a run of identical bands.",
|
|
134
|
+
"parts": 1
|
|
117
135
|
},
|
|
118
136
|
{
|
|
119
137
|
"id": "color-contrast",
|
|
120
138
|
"title": "Color assignment and contrast",
|
|
121
139
|
"kind": "foundation",
|
|
122
|
-
"when": "Load before assigning any color to text, a surface, a control or an icon, and before calling a page accessible."
|
|
140
|
+
"when": "Load before assigning any color to text, a surface, a control or an icon, and before calling a page accessible.",
|
|
141
|
+
"parts": 1
|
|
123
142
|
},
|
|
124
143
|
{
|
|
125
144
|
"id": "surfaces-elevation",
|
|
126
145
|
"title": "Surfaces and elevation",
|
|
127
146
|
"kind": "foundation",
|
|
128
|
-
"when": "Load before giving anything a background, border, shadow, radius, divider or overlay."
|
|
147
|
+
"when": "Load before giving anything a background, border, shadow, radius, divider or overlay.",
|
|
148
|
+
"parts": 1
|
|
129
149
|
},
|
|
130
150
|
{
|
|
131
151
|
"id": "motion",
|
|
132
152
|
"title": "Motion and animation",
|
|
133
153
|
"kind": "foundation",
|
|
134
|
-
"when": "Load before adding any transition, entrance, hover
|
|
154
|
+
"when": "Load before adding any transition, entrance, reveal, hover state, floating figure, marquee, animated chart or signature interaction.",
|
|
155
|
+
"parts": 1
|
|
156
|
+
},
|
|
157
|
+
{
|
|
158
|
+
"id": "copywriting",
|
|
159
|
+
"title": "Website copy that converts",
|
|
160
|
+
"kind": "foundation",
|
|
161
|
+
"when": "Load before writing or rewriting any words on a page: headlines, sections, calls to action, proof, forms and messages.",
|
|
162
|
+
"parts": 1
|
|
163
|
+
},
|
|
164
|
+
{
|
|
165
|
+
"id": "seo",
|
|
166
|
+
"title": "On-page SEO and AI search visibility",
|
|
167
|
+
"kind": "foundation",
|
|
168
|
+
"when": "Load before designing any page, and before writing its headings, links, image text or FAQ.",
|
|
169
|
+
"parts": 1
|
|
135
170
|
},
|
|
136
171
|
{
|
|
137
172
|
"id": "accessibility",
|
|
138
173
|
"title": "Accessibility",
|
|
139
174
|
"kind": "foundation",
|
|
140
|
-
"when": "Load before building any page, and before calling one finished: the audit at the end is part of the job."
|
|
175
|
+
"when": "Load before building any page, and before calling one finished: the audit at the end is part of the job.",
|
|
176
|
+
"parts": 1
|
|
141
177
|
},
|
|
142
178
|
{
|
|
143
179
|
"id": "responsive",
|
|
144
180
|
"title": "Responsive behavior",
|
|
145
181
|
"kind": "foundation",
|
|
146
|
-
"when": "Load before building any page, and for the responsive pass before saving: SpecShot's frame is dragged to every width."
|
|
182
|
+
"when": "Load before building any page, and for the responsive pass before saving: SpecShot's frame is dragged to every width.",
|
|
183
|
+
"parts": 1
|
|
184
|
+
},
|
|
185
|
+
{
|
|
186
|
+
"id": "content-model",
|
|
187
|
+
"title": "Content model first",
|
|
188
|
+
"kind": "build",
|
|
189
|
+
"when": "Load before planning or building a whole site, a page that belongs to a family (docs, blog, changelog, legal, services, features), or any type's archive, single or category design.",
|
|
190
|
+
"parts": 1
|
|
147
191
|
},
|
|
148
192
|
{
|
|
149
193
|
"id": "etch-acss-build",
|
|
150
194
|
"title": "The Etch and ACSS build",
|
|
151
195
|
"kind": "build",
|
|
152
|
-
"when": "Load before building any page or section that will go to Etch, which is every SpecShot design, and before running get_etch_build."
|
|
196
|
+
"when": "Load before building any page or section that will go to Etch, which is every SpecShot design, and before running get_etch_build.",
|
|
197
|
+
"parts": 1
|
|
198
|
+
},
|
|
199
|
+
{
|
|
200
|
+
"id": "etch-clean-build",
|
|
201
|
+
"title": "The clean Etch build",
|
|
202
|
+
"kind": "build",
|
|
203
|
+
"when": "Load before building pages into Etch with get_etch_build, get_etch_template_build or send_to_wordpress, and before reading the law findings they return.",
|
|
204
|
+
"parts": 1
|
|
153
205
|
},
|
|
154
206
|
{
|
|
155
207
|
"id": "agency-process",
|
|
156
208
|
"title": "The agency process",
|
|
157
209
|
"kind": "page",
|
|
158
|
-
"when": "Load at the start of any client project, before starting or finishing a phase, and before anything is drafted for a client."
|
|
210
|
+
"when": "Load at the start of any client project, before starting or finishing a phase, and before anything is drafted for a client.",
|
|
211
|
+
"parts": 1
|
|
159
212
|
},
|
|
160
213
|
{
|
|
161
214
|
"id": "discovery-interview",
|
|
162
215
|
"title": "The discovery interview",
|
|
163
216
|
"kind": "page",
|
|
164
|
-
"when": "Load when the owner says new client or start discovery, before interviewing anyone about a client, a project or its brief."
|
|
217
|
+
"when": "Load when the owner says new client or start discovery, before interviewing anyone about a client, a project or its brief.",
|
|
218
|
+
"parts": 1
|
|
165
219
|
},
|
|
166
220
|
{
|
|
167
221
|
"id": "copy-and-wireframe",
|
|
168
222
|
"title": "Copy and wireframe",
|
|
169
223
|
"kind": "page",
|
|
170
|
-
"when": "Load when the owner says start copywriting, and before writing page copy or building a wireframe for a client page."
|
|
224
|
+
"when": "Load when the owner says start copywriting, and before writing page copy or building a wireframe for a client page.",
|
|
225
|
+
"parts": 1
|
|
171
226
|
},
|
|
172
227
|
{
|
|
173
228
|
"id": "design-for-acss",
|
|
174
229
|
"title": "Design for ACSS",
|
|
175
230
|
"kind": "foundation",
|
|
176
|
-
"when": "Load when the owner says start design, before the Design Direction board, and before designing any page from an approved wireframe."
|
|
231
|
+
"when": "Load when the owner says start design, before the Design Direction board, and before designing any page from an approved wireframe.",
|
|
232
|
+
"parts": 1
|
|
177
233
|
},
|
|
178
234
|
{
|
|
179
235
|
"id": "section-authorship",
|
|
180
236
|
"title": "Section authorship",
|
|
181
237
|
"kind": "page",
|
|
182
|
-
"when": "Load before planning or reviewing the sections of any page: each section's job, its anchor and its archetype, and the rules that keep a page from repeating itself."
|
|
238
|
+
"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.",
|
|
239
|
+
"parts": 1
|
|
183
240
|
},
|
|
184
241
|
{
|
|
185
242
|
"id": "design-qa-gate",
|
|
186
243
|
"title": "Design QA gate",
|
|
187
244
|
"kind": "page",
|
|
188
|
-
"when": "Load before calling a page done or handing it to a client: the per-page checks, content stress cases, media rules and performance budgets, each with its evidence."
|
|
245
|
+
"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.",
|
|
246
|
+
"parts": 1
|
|
189
247
|
},
|
|
190
248
|
{
|
|
191
249
|
"id": "etch-development",
|
|
192
250
|
"title": "Etch development",
|
|
193
251
|
"kind": "build",
|
|
194
|
-
"when": "Load when the owner says start development, before building an approved design into Etch, and before driving an Etch tab through the Etch Connector."
|
|
252
|
+
"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.",
|
|
253
|
+
"parts": 1
|
|
195
254
|
},
|
|
196
255
|
{
|
|
197
256
|
"id": "etch-structure",
|
|
198
257
|
"title": "Etch structure",
|
|
199
258
|
"kind": "build",
|
|
200
|
-
"when": "Load before writing the markup of any page or section that goes to Etch, and before changing structure in Etch through the Etch Connector."
|
|
259
|
+
"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.",
|
|
260
|
+
"parts": 1
|
|
201
261
|
},
|
|
202
262
|
{
|
|
203
263
|
"id": "etch-css",
|
|
204
264
|
"title": "Etch CSS",
|
|
205
265
|
"kind": "build",
|
|
206
|
-
"when": "Load before writing or changing styles in Etch, by hand or through the Etch Connector, and before choosing a button or a variable on an ACSS site."
|
|
266
|
+
"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.",
|
|
267
|
+
"parts": 1
|
|
207
268
|
},
|
|
208
269
|
{
|
|
209
270
|
"id": "etch-connector-runtime",
|
|
210
271
|
"title": "Etch Connector runtime",
|
|
211
272
|
"kind": "build",
|
|
212
|
-
"when": "Load before driving an Etch tab through the Etch Connector: editing components, classes, loops or data, saving, navigating, or working on Etch Studio."
|
|
273
|
+
"when": "Load before driving an Etch tab through the Etch Connector: editing components, classes, loops or data, saving, navigating, or working on Etch Studio.",
|
|
274
|
+
"parts": 1
|
|
213
275
|
},
|
|
214
276
|
{
|
|
215
277
|
"id": "etch-connector-gotchas",
|
|
216
278
|
"title": "Etch Connector gotchas",
|
|
217
279
|
"kind": "build",
|
|
218
|
-
"when": "Load before editing an Etch page through the Etch Connector after a SpecShot build: the script cadence, where CSS really ships, the classes a save drops, and how to verify."
|
|
280
|
+
"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.",
|
|
281
|
+
"parts": 1
|
|
282
|
+
},
|
|
283
|
+
{
|
|
284
|
+
"id": "smooth-motion",
|
|
285
|
+
"title": "Smooth motion",
|
|
286
|
+
"kind": "foundation",
|
|
287
|
+
"when": "Load before adding a reveal, a scroll effect, a page transition, a looping figure or a blur to a built site, and when a page feels slow, rough or janky.",
|
|
288
|
+
"parts": 1
|
|
289
|
+
}
|
|
290
|
+
],
|
|
291
|
+
"laws": [
|
|
292
|
+
{
|
|
293
|
+
"id": "design-law",
|
|
294
|
+
"title": "The design law",
|
|
295
|
+
"kind": "build",
|
|
296
|
+
"when": "Read before any design or build work on a project: what done looks like, the token contract, the structure and Etch rules, the anti-slop list.",
|
|
297
|
+
"parts": 11,
|
|
298
|
+
"category": "law"
|
|
299
|
+
},
|
|
300
|
+
{
|
|
301
|
+
"id": "build-standard",
|
|
302
|
+
"title": "The build standard",
|
|
303
|
+
"kind": "build",
|
|
304
|
+
"when": "Read before building a page: the page workflow and the standard every saved design is checked against.",
|
|
305
|
+
"parts": 3,
|
|
306
|
+
"category": "law"
|
|
307
|
+
},
|
|
308
|
+
{
|
|
309
|
+
"id": "premium-craft",
|
|
310
|
+
"title": "Premium craft",
|
|
311
|
+
"kind": "build",
|
|
312
|
+
"when": "Read before building a page the client will see: the craft that makes it premium and alive.",
|
|
313
|
+
"parts": 3,
|
|
314
|
+
"category": "law"
|
|
315
|
+
},
|
|
316
|
+
{
|
|
317
|
+
"id": "etch-ready",
|
|
318
|
+
"title": "Etch ready",
|
|
319
|
+
"kind": "build",
|
|
320
|
+
"when": "Read before a page goes to Etch: the Etch and Automatic.css rules a design must meet to build cleanly.",
|
|
321
|
+
"parts": 4,
|
|
322
|
+
"category": "law"
|
|
219
323
|
}
|
|
220
324
|
],
|
|
221
325
|
"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.",
|
|
@@ -224,7 +328,7 @@ export const SKILL_LIST = {
|
|
|
224
328
|
"revision": "revise_a_page",
|
|
225
329
|
"section": "rebuild_from_capture"
|
|
226
330
|
},
|
|
227
|
-
"howToUse": "
|
|
331
|
+
"howToUse": "Call get_agent_briefing first on any project and read everything it lists. Then plan the page with page-composition and load the skill for each section kind and each part you build (get_skill with its id, every part). get_wireframe_context names the skills that fit each page. A skill adds detail to the laws; where they disagree, the design law wins."
|
|
228
332
|
};
|
|
229
333
|
/** Every get_skill answer, by id, exactly as the hosted tool gives it. */
|
|
230
334
|
export const SKILL_BODIES = {
|
|
@@ -233,14 +337,14 @@ export const SKILL_BODIES = {
|
|
|
233
337
|
"title": "Page composition",
|
|
234
338
|
"kind": "page",
|
|
235
339
|
"when": "Load before planning any whole page: which sections it has, in what order, on which ground, at what density.",
|
|
236
|
-
"body": "# Page composition\n\nA page makes an argument, one section at a time. Write the plan as a list first, so the markup has a shape to follow.\n\n## What goes in\n\n- The page's goal and required sections come first. They are the client's requirements for this page and outrank any general guidance, and each one appears under its own name.\n- Then whatever the brief, the approved copy and the references call for. A section with no reason behind it is padding.\n- A whole page has a header, every section in order and a footer, saved together. Never a comment where a section should be.\n\n## A sequence that works\n\nMost marketing pages make their case in this order. Change it when the brief says so, and know why.\n\n1. Hero: what it is, who it is for, why believe it, what to do next.\n2. What it does: the few features or services that matter, each heading a claim.\n3. Proof: a real number, client logos or a short quote, so the claims are believed.\n4. How it works: numbered steps, so the next action feels small.\n5. Depth: a case study, the people, whatever this audience needs before deciding.\n6. The offer: pricing or the package, with proof beside the ask.\n7. Questions: an FAQ that answers the hard ones.\n8. The close: a closing statement carrying the primary action.\n9. The footer: somewhere to go, not a strip.\n\nSpecShot's premium exemplar
|
|
340
|
+
"body": "# Page composition\n\nA page makes an argument, one section at a time. Write the plan as a list first, so the markup has a shape to follow.\n\n## What goes in\n\n- The page's goal and required sections come first. They are the client's requirements for this page and outrank any general guidance, and each one appears under its own name.\n- Then whatever the brief, the approved copy and the references call for. A section with no reason behind it is padding.\n- A whole page has a header, every section in order and a footer, saved together. Never a comment where a section should be.\n\n## A sequence that works\n\nMost marketing pages make their case in this order. Change it when the brief says so, and know why.\n\n1. Hero: what it is, who it is for, why believe it, what to do next, with a layered visual.\n2. What it does: the few features or services that matter, composed as a bento, each heading a claim.\n3. Proof: a real number, client logos in a marquee band or a short quote, so the claims are believed.\n4. How it works: numbered steps with a line that draws between them, so the next action feels small.\n5. Depth: a case study, the people, whatever this audience needs before deciding.\n6. The offer: pricing or the package, with proof beside the ask.\n7. Questions: an FAQ that answers the hard ones.\n8. The close: a closing statement carrying the primary action.\n9. The footer: somewhere to go, not a strip.\n\nSpecShot's premium exemplar (get_premium_exemplar over MCP) is a whole page built this way, in one theme from header to footer.\n\n## The plan\n\nBefore markup, one line per section: name, layout, visual, reveal, ground, padding.\n\n```text\nHero split image spot + chip load entrance paper dense\nServices bento a figure per tile tiles rise paper-2 open\nClients marquee band the names moves, pauses paper dense\nHow it works steps a drawn line slide from left paper-2 open\nProof testimonial wall image spot scale in paper open\nQuestions sticky stack none rise paper-2 dense\nClose form panel a drawn figure panel rises paper open\n```\n\nThen hold it to the premium bar:\n\n- No two neighbors share a layout, a home page has a bento, and no row of equal cards anywhere.\n- The hero and at least two more sections carry a visual: an image spot, a drawn figure or the client's image.\n- Each section reveals its own way, and two to four figures move across the page.\n- No three sections in a row share a ground, and the page keeps one theme. Never drop a dark band into a light page: it outweighs everything around it.\n- Section padding is `--pad-open` or `--pad-dense` only, the same above and below, alternating so the page changes pace.\n- Every section's content starts on the one content edge, and every overlap is on purpose, above what it crosses.\n- The openings vary: not every section is a heading on the left and an empty right half.\n\n## What runs through it\n\n- One primary action, worded the same, at least three times: the hero, the middle, the close.\n- Read only the headings and the story is there. Headings that read like labels (\"Features\", \"About\") get rewritten as claims.\n- The page is alive from top to bottom: a load entrance, a reveal per section, moving figures and the interaction system (the motion skill).\n- Each section earns its place: a layout, a heading that makes a claim, one dominant element, a visual, its states and a reason from the brief.\n\n## Saving it\n\n- The sections list you save names the page's sections in document order, so each becomes a region the owner and client can select and comment on.\n- Save a single section on its own only when the owner asked for exactly one. Otherwise build the whole page first.\n\n## Check before you save\n\n- Is every required section present, by name, in a sensible order?\n- Does the plan pass the layout, visual, reveal, ground, padding and edge rules?\n- Does the primary action appear three times with the same words?"
|
|
237
341
|
},
|
|
238
342
|
"direction-by-niche": {
|
|
239
343
|
"id": "direction-by-niche",
|
|
240
344
|
"title": "Choosing a direction by niche",
|
|
241
345
|
"kind": "page",
|
|
242
346
|
"when": "Load when a project has no brand system, or only part of one, and a direction has to be proposed before the first page.",
|
|
243
|
-
"body": "# Choosing a direction by niche\n\nA project with no brand is no excuse to decide nothing. Propose one direction that fits the business, carry it out precisely, and say clearly that the client still has to approve it.\n\n## What outranks what\n\n1. The client's rules and their brand: any color, face or value they already have.\n2. Part of a brand: use what exists (a logo suggests the type and the shapes; a color becomes the accent) and propose only the rest.\n3. An approved direction: once there is one, every page follows it.\n4. The starting points below, for whatever is still open.\n\n## Six starting points\n\nThese are the premium bar's direction recipes, each a complete system. Pick the one closest to the business and adapt it; never mix two. None names a face: each says the character of the type, and the faces come from the client's references (the brief's type facts), or a Google Fonts pairing matched to their character.\n\n- Editorial luxe, for studios, hospitality with a story, publishers and premium consumer brands: a display face set large and tight beside a face made for long reading, warm paper, a deep oxblood accent, hairlines instead of cards, radius 0.125 to 0.375rem,
|
|
347
|
+
"body": "# Choosing a direction by niche\n\nA project with no brand is no excuse to decide nothing. Propose one direction that fits the business, carry it out precisely, and say clearly that the client still has to approve it.\n\n## What outranks what\n\n1. The client's rules and their brand: any color, face or value they already have.\n2. Part of a brand: use what exists (a logo suggests the type and the shapes; a color becomes the accent) and propose only the rest.\n3. An approved direction: once there is one, every page follows it.\n4. The starting points below, for whatever is still open.\n\n## Six starting points\n\nThese are the premium bar's direction recipes, each a complete system. Pick the one closest to the business and adapt it; never mix two. None names a face: each says the character of the type, and the faces come from the client's references (the brief's type facts), or a Google Fonts pairing matched to their character.\n\n- Editorial luxe, for studios, hospitality with a story, publishers and premium consumer brands: a display face set large and tight beside a face made for long reading, warm paper, a deep oxblood accent, hairlines instead of cards, radius 0.125 to 0.375rem, slow staggered entrances and a line that draws itself.\n- Midnight precision, for software, data, security and research, as a dark theme for the whole site: a sturdy, engineered sans and a monospace for figures, surfaces stepping up in lightness, a cool accent used sparingly, a product interface as the hero visual, radius 0.5 to 0.75rem, crisp entrances, a chart that draws its data and floating status chips.\n- Swiss signal, for engineering, architecture, finance and professional services: a plain, strong grotesque doing every job, paper and near-black ink with one hot accent, a strict 12-column grid, very large numbers, everything flush left, radius 0 to 0.25rem, precise slides and bars that grow to their values.\n- Soft natural, for health, wellness, education, food and local services: a warm display face with soft forms and an open, friendly reading face, a sage-tinted ground, radius 1 to 1.5rem, soft layered shadows with a real offset, the client's photographs shown large, gentle rises and slow floating cards.\n- Noir atelier, for luxury, fashion, fine dining and hotels, as a dark theme for the whole site: a high-contrast display face with a light, quiet reading face, warm light text and a muted brass accent, full-bleed photographs, thin rules, very large white space, deep shadows, radius 0, long quiet entrances and a slow orbit around the hero visual.\n- Bright modern, for consumer apps, startups and friendly SaaS: a display face with personality and wide forms and a clean, even reading face, a bright ground and a vivid accent, a bento of mixed spans rounded 0.75 to 1rem, single-stroke icons, quick ease-out entrances, floating UI cards and a marquee band.\n\nNever Inter, Roboto, Arial, Geist, Fraunces, Plus Jakarta Sans or Space Grotesk by reflex, in any niche. Light or dark is the client's choice: the two dark directions are for a client who chose dark or left it to the designer. A dark direction is a theme for the whole site, never a dark band dropped into a light page.\n\n## Making it this client's\n\n- Change the values to suit the business: the accent hue, how dense the spacing runs, how dramatic the type scale is. Keep the token names.\n- Write a one-sentence mood metaphor a designer could argue with (\"a high-end travel magazine that happens to take bookings\"), not \"modern and clean\".\n- Say why the direction belongs to this business and what would break if a competitor used it. A direction that fits anyone has been picked, not designed.\n- Never fall back to a neutral sans on white with one accent. It is the failure mode, not the safe option.\n\n## Recording it\n\n- When the project uses the direction gate, build the proposal into the Design Direction board before any page.\n- Name the direction and its palette, faces, spacing and radius in your summary, labeled as a proposal.\n- When the owner approves it, record the approval so the next page inherits the decision instead of reopening it.\n\n## Check before you propose\n\n- Did everything the client already has win over the recipe?\n- Does the direction have real values: a named palette, a real pairing, a spacing scale and a radius family?\n- Is it clearly labeled as a proposal?"
|
|
244
348
|
},
|
|
245
349
|
"navigation-header": {
|
|
246
350
|
"id": "navigation-header",
|
|
@@ -254,7 +358,7 @@ export const SKILL_BODIES = {
|
|
|
254
358
|
"title": "Hero sections",
|
|
255
359
|
"kind": "section",
|
|
256
360
|
"when": "Load before building the first section of any page: a hero, an intro, a page header or a landing block.",
|
|
257
|
-
"body": "# Hero sections\n\nSomeone decides in five seconds whether to keep reading. The hero answers four questions before they scroll: what it is, who it is for, why to believe it, and what to do next.\n\n## Content\n\n- Headline: the outcome for the customer, not the feature.
|
|
361
|
+
"body": "# Hero sections\n\nSomeone decides in five seconds whether to keep reading. The hero answers four questions before they scroll: what it is, who it is for, why to believe it, and what to do next. It also shows, in those five seconds, that the page is alive.\n\n## Content\n\n- Headline: the outcome for the customer, not the feature. The page's one h1, carrying its topic in the client's words. Use approved copy word for word when it exists.\n- Supporting line: how, in one or two sentences, at most 52ch, at `--step-1`.\n- A primary action whose label says what happens (\"Book a site survey\"), a quieter secondary (\"See recent projects\"), and one short trust line beside them from the client's facts.\n- One piece of real proof inside the first screen: a real number, real client logos, a real rating with its source. No proof is better than invented proof.\n\n## Type\n\n- The headline at `--step-5`, two or three lines, line height 1.02 to 1.1, tracking -0.02em to -0.035em, `text-wrap: balance`.\n- Upright, in the display face. No oversized italic serif, and no italic or colored word as its trick: emphasis is size and weight.\n- A small label above the headline only where the brand or the client's references set one, never a kicker, eyebrow or tracked-caps label by reflex.\n\n## The visual, layered\n\n- An image spot (a figure with `data-ss-image`, `data-ss-aspect` and `data-ss-alt` around a drawn fallback), the client's photograph, or a drawn figure from the page's content: an interface panel, a labeled chart, the process in the copy.\n- Raised on `--shadow-4`, with at least one floating element (a stat chip, a UI card, a review, a badge) on `--shadow-3` crossing its edge. Never a heading beside an empty half.\n- Never a scene assembled from primitive shapes, never grain or a glow behind it, never an empty frame.\n- The hero's image loads at once: no `loading=\"lazy\"` on it, and `fetchpriority=\"high\"` on the one that paints first.\n\n## Layout\n\n- Asymmetric by default: copy over 6 or 7 columns, the visual over the rest. The visual's top edge starts on the headline's top line.\n- The copy starts on the page's one content edge, and both columns carry comparable weight.\n- A floating element may cross the visual's edge. Nothing hangs past the bottom of the hero to be covered by the next section.\n- `min-height: min(100dvh, 56rem)` only when the visual fills it, and never vh.\n\n## Motion\n\n- The hero settles on load: heading, text, actions and visual enter in sequence over `--dur-4`, staggered by `--stagger`. The floating elements arrive last, then float 6 to 12px over 5 to 9s.\n- A figure in the visual may draw itself in over `--dur-5`. All of it under `prefers-reduced-motion: no-preference`.\n\n## On a phone\n\n- Copy first, then the visual, then the proof. The primary action is visible without scrolling at 390 by 844.\n- Both actions full width or side by side, each at least 2.75rem tall.\n\n## Example\n\n```html\n<section class=\"hero\" aria-labelledby=\"hero-title\">\n <div class=\"hero__copy\">\n <h1 class=\"hero__title\" id=\"hero-title\" style=\"--i: 0\">Every room measured in two days</h1>\n <p class=\"hero__lead\" style=\"--i: 1\">Laser surveys drawn to scale, ready for your architect before the week is out.</p>\n <div class=\"hero__actions\" style=\"--i: 2\"><a class=\"button button--primary\" href=\"/book\">Book a site survey</a><a class=\"button button--quiet\" href=\"/work\">See recent projects</a></div>\n </div>\n <figure class=\"hero__media\" data-ss-image=\"A surveyor scanning a bright kitchen with a laser on a tripod, morning light, no text\" data-ss-aspect=\"4:3\" data-ss-alt=\"A surveyor scanning a kitchen\">\n <svg class=\"hero__plan\" viewBox=\"0 0 480 360\" role=\"img\" aria-label=\"A floor plan with measured rooms\"></svg>\n <p class=\"hero__chip\">Drawings in 2 days</p>\n </figure>\n</section>\n```\n\nEvery number in the hero is the client's real figure. Leave it out if there is none.\n\n## Check before you save\n\n- Can someone tell what, who, why and what next without scrolling?\n- Is the visual real and layered, with a floating element over its edge?\n- Does the hero settle on load, with the floating element arriving last?"
|
|
258
362
|
},
|
|
259
363
|
"content-long-text": {
|
|
260
364
|
"id": "content-long-text",
|
|
@@ -268,7 +372,7 @@ export const SKILL_BODIES = {
|
|
|
268
372
|
"title": "Testimonials and social proof",
|
|
269
373
|
"kind": "section",
|
|
270
374
|
"when": "Load before building testimonials, reviews, client logos, case study teasers, stats, ratings, awards or press mentions.",
|
|
271
|
-
"body": "# Testimonials and social proof\n\nProof is the reason to believe the headline. Invented proof is worse than none: a client, a competitor or a regulator can tell, and the whole page reads as invented.\n\n## Only real proof\n\n- A testimonial carries a real person's name, role and company, in their words, with permission. Never John Doe, never a first name and an initial standing in for a source, never a drawn face.\n- A stat carries a real number and, where it is not obvious, its source and period (\"212 surveys in 2025\").\n- A logo is the client's customer's real logo, used with permission, recreated as inline SVG in one tone.\n- When the client has not supplied proof yet, build the component with a visible marker (\"[GAP: testimonial from a client]\", or \"[UNVERIFIED: 4.9 rating]\" for one the client mentioned but has not shown) and say so in your summary. Never fill it with plausible fiction.\n- Uneven numbers read as measured. \"47.2 percent\" is believable; \"99.99 percent\" and \"10,000+ happy customers\" read as invented.\n\n## Forms of proof\n\n- Quote spotlight: one testimonial set large at `--step-3` in the display face, with name, role and company under it and a monogram or the client's photograph. One strong quote beats a carousel of five weak ones.\n- Quote grid: three to six short quotes of different lengths in a bento or masonry rhythm, each with its source. Never six identical cards.\n- Stats band: three or four real numbers at `--step-4` or larger with `tabular-nums`, each with a one-line label, on the page's own ground or a tint. Never a dark band dropped into a light page.\n- Logo wall: real logos in one tone (`--ink-3`), evenly optically sized
|
|
375
|
+
"body": "# Testimonials and social proof\n\nProof is the reason to believe the headline. Invented proof is worse than none: a client, a competitor or a regulator can tell, and the whole page reads as invented.\n\n## Only real proof\n\n- A testimonial carries a real person's name, role and company, in their words, with permission. Never John Doe, never a first name and an initial standing in for a source, never a drawn face.\n- A stat carries a real number and, where it is not obvious, its source and period (\"212 surveys in 2025\").\n- A logo is the client's customer's real logo, used with permission, recreated as inline SVG in one tone.\n- When the client has not supplied proof yet, build the component with a visible marker (\"[GAP: testimonial from a client]\", or \"[UNVERIFIED: 4.9 rating]\" for one the client mentioned but has not shown) and say so in your summary. Never fill it with plausible fiction.\n- Uneven numbers read as measured. \"47.2 percent\" is believable; \"99.99 percent\" and \"10,000+ happy customers\" read as invented.\n\n## Forms of proof\n\n- Quote spotlight: one testimonial set large at `--step-3` in the display face, with name, role and company under it and a monogram or the client's photograph. One strong quote beats a carousel of five weak ones.\n- Quote grid: three to six short quotes of different lengths in a bento or masonry rhythm, each with its source. Never six identical cards.\n- Stats band: three or four real numbers at `--step-4` or larger with `tabular-nums`, each with a one-line label, on the page's own ground or a tint. Never a dark band dropped into a light page.\n- Logo wall or marquee band: real logos or client names in one tone (`--ink-3`), evenly optically sized, with a line saying who they are (\"Trusted by practices across Sydney\"). A marquee band moves slowly (30 to 60s, linear), repeats its items in an `aria-hidden=\"true\"` copy, fades at its edges and pauses on hover and focus-within.\n- Case study teaser: the client's problem, what was done, the measured result, and a link to the story.\n- Rating: the score, the count and the platform (\"4.8 from 212 Google reviews\"), stars drawn in SVG with a text alternative.\n\n## Placement\n\n- Proof sits next to every ask: one line of proof beside the hero's action, a quote near pricing, a number in the closing panel.\n- A dedicated proof section works after the features and before pricing or the close, where a visitor is deciding.\n- Match the proof to the claim it supports: a quote about speed sits next to the claim about speed.\n\n## Type and layout\n\n- Quotes in real typographic quotation marks with `hanging-punctuation: first`, at a measure of about 40 to 60 characters when set large.\n- The quote is a `<blockquote>` inside a `<figure>` with the source in `<figcaption>`.\n- Name in weight 600, role and company in `--ink-2`.\n\n## Example\n\n```html\n<figure class=\"quote\">\n <blockquote class=\"quote__text\"><p class=\"quote__line\">[Testimonial from a client, to be supplied]</p></blockquote>\n <figcaption class=\"quote__source\"><span class=\"quote__name\">[Name]</span> <span class=\"quote__role\">[Role, Company]</span></figcaption>\n</figure>\n```\n\n## Check before you save\n\n- Is every name, quote, logo and number real, or clearly labeled as waiting on the client?\n- Does each ask on the page have proof beside it?\n- Is the logo wall still, with every logo visible at once?"
|
|
272
376
|
},
|
|
273
377
|
"pricing": {
|
|
274
378
|
"id": "pricing",
|
|
@@ -310,7 +414,7 @@ export const SKILL_BODIES = {
|
|
|
310
414
|
"title": "Cards",
|
|
311
415
|
"kind": "component",
|
|
312
416
|
"when": "Load before building any card, tile, feature grid, team grid, product grid or post list.",
|
|
313
|
-
"body": "# Cards\n\nA card frames one option a visitor might pick. If nothing in it can be picked, it probably does not need to be a card.\n\n## When a card is right\n\n- For sets of comparable choices: services, products, plans, articles, people.\n- Not for text that is only read. Three cards of an icon and a paragraph is the most common template on the web; a list, a table or plain columns often say it better.\n- Vary the grid. A bento
|
|
417
|
+
"body": "# Cards\n\nA card frames one option a visitor might pick. If nothing in it can be picked, it probably does not need to be a card.\n\n## When a card is right\n\n- For sets of comparable choices: services, products, plans, articles, people.\n- Not for text that is only read. Three cards of an icon and a paragraph is the most common template on the web; a list, a table or plain columns often say it better.\n- Vary the grid. A bento reads as designed: 4 to 7 tiles in at least 3 sizes, one spanning 2 columns or 2 rows, tiles that differ in content type (a stat, a mini chart, a figure, an image, a quote, a list), each with its own small visual. A row of identical tiles only suits more than three truly equal items.\n\n## Anatomy\n\n- One block named for what the card holds: `.service-card`, `.team-member`, `.plan`, `.post-card`. Never a bare `.card`, and never a bare `.grid` for the list that holds them: the list is its section's element (`.services__list`). A generic name says nothing about what it is, and on an Etch site it collides with every other card.\n- Its elements carry the block's name: `.service-card__media`, `.service-card__title`, `.service-card__body`, `.service-card__meta` and `.service-card__action`, with modifiers such as `.service-card--featured` or `.service-card--wide`.\n- Top to bottom: media, title, a line or two of body, quiet metadata, then the action. The title is the strongest thing in the card.\n- Inner padding from a local property on the block, `--service-card-pad: var(--space-m, 1.5rem)`; title to body `--space-s`.\n- The title's heading level follows the page outline, usually an h3 under the section's h2, at `--step-2`.\n\n## Surface\n\n- One elevation: a hairline in `--line` or `--shadow-1`, never both. A `--paper-2` card on the page ground may need neither.\n- Radius `--radius-m`. Media inside the card takes the card's radius minus the padding, or the card's radius on its top corners when it runs to the edge.\n- Never a card inside a card; inside, separate parts with space or a hairline.\n- Never a thick colored stripe down one side.\n\n## Media\n\n- A fixed `aspect-ratio` such as 4 / 3 or 16 / 10, `object-fit: cover`, and alt text that says what is shown.\n- The client's image, an image spot (`data-ss-image`, `data-ss-aspect`, `data-ss-alt` around a drawn fallback), or a figure drawn from the card's own content: a fragment of interface, a small chart, type set large. Never an empty frame or a decorative pattern.\n- On hover the image scales to 1.04 inside `overflow: hidden`.\n- A person with no photograph becomes a monogram: initials in the display face on an `--accent-quiet` disc.\n\n## Color\n\n- Title in `--ink`, body in `--ink-2`, metadata in `--ink-3`. The accent is saved for the action, a link or a key number, never the title.\n- A featured card stands out through a higher shadow step, a tint or extra size, not a second accent and not a dark card among light ones.\n\n## Interaction\n\n- A card with a single destination is a single link: the title's link stretches over the whole card through a pseudo-element, so screen readers hear one link and the whole card responds.\n- A card with several actions keeps each as its own control and is not itself a link.\n- On hover the card rises 4px while a pseudo-element carrying `--shadow-2` fades in, under `prefers-reduced-motion: no-preference`. The focus ring of the link outlines the whole card.\n- Tiles reveal as they scroll in, in the safe form the motion skill gives, each grid its own way.\n\n## Example\n\n```html\n<article class=\"service-card\">\n <div class=\"service-card__media\"><svg aria-hidden=\"true\" viewBox=\"0 0 320 200\"></svg></div>\n <h3 class=\"service-card__title\"><a class=\"service-card__link\" href=\"/services/survey\">Site surveys</a></h3>\n <p class=\"service-card__body\">A measured survey of every room in two days, drawn to scale.</p>\n <p class=\"service-card__meta\">Residential and commercial</p>\n</article>\n```\n\n```css\n.service-card { position: relative; }\n.service-card__link::after { content: \"\"; position: absolute; inset: 0; border-radius: inherit; }\n```\n\n## Check before you save\n\n- Is every card a real choice, and would a list or table read better?\n- Does any card carry both a border and a shadow, or sit inside another card?\n- Does each card's media have a fixed ratio and honest alt text?"
|
|
314
418
|
},
|
|
315
419
|
"forms": {
|
|
316
420
|
"id": "forms",
|
|
@@ -330,8 +434,8 @@ export const SKILL_BODIES = {
|
|
|
330
434
|
"id": "imagery-art-direction",
|
|
331
435
|
"title": "Imagery and art direction",
|
|
332
436
|
"kind": "component",
|
|
333
|
-
"when": "Load before placing any image, hero visual, gallery, product shot, portrait, diagram or background.",
|
|
334
|
-
"body": "# Imagery and art direction\n\
|
|
437
|
+
"when": "Load before placing any image, image spot, hero visual, figure, gallery, product shot, portrait, diagram or background.",
|
|
438
|
+
"body": "# Imagery and art direction\n\nThe owner asked for \"different images and figures that move that bring the design and website to life\". A page with no pictures reads as a draft, and a drawing that pretends to be a photograph reads as clip art. Every page uses two kinds, and the hero and at least two more sections carry one.\n\n## Drawn figures\n\nIn SVG and CSS, from the page's own content:\n\n- An interface panel built from the page's own words: the service list as a dashboard, the booking as a calendar card.\n- A chart with the page's numbers and their labels, drawn so its line or bars can animate in.\n- A diagram of the process the copy describes, with the copy's step names on it.\n- A device frame holding one of the above.\n\nA figure is complete on its own and it moves (the motion skill). It is the fallback inside every image spot.\n\n## Image spots\n\nSpecShot fills a spot with a photo it generates on the workspace's own image key after the page is saved. The markup, exactly:\n\n```html\n<figure class=\"hero__media\" data-ss-image=\"A sunlit dental clinic reception with a patient checking in at a tablet, warm natural light, shallow depth of field, no text\" data-ss-aspect=\"4:3\" data-ss-alt=\"A patient checking in at the front desk\">\n <!-- the drawn fallback figure, complete and good on its own -->\n</figure>\n```\n\n- `data-ss-image` is the photo prompt: what it shows, the setting, the light and the mood. No text, logos or brand names in the photo.\n- `data-ss-aspect` is one of 16:9, 4:3, 1:1, 3:4 or 9:16. `data-ss-alt` is the alt text.\n- At most four spots on a page and one in a section: the hero first, then the sections that most need a photo.\n- The figure takes its size from its layout (an `aspect-ratio` or a grid area), never from the photo.\n- Never write an img for a spot and never style `.ss-image`: SpecShot inserts the image and its style.\n\n## Sources, in order\n\n1. The client's own pictures, from the placeable images, go straight into a src.\n2. Image spots for the photos nobody supplied. Over MCP, generate_image makes one now.\n3. Drawn figures everywhere else, and as every spot's fallback.\n\nNever a placeholder image host and never a hotlinked image: the preview strips external images.\n\n## What never stands in for a picture\n\n- Never a scene assembled from primitive shapes: circles and rectangles arranged into a building, a garden or a person. Geometry is welcome only when it says something: a chart, a diagram, a plan with real labels.\n- No grain or noise over a ground (no feTurbulence filter), and no dot grid or stripe behind a section.\n- No radial glow or soft blob standing in for a visual, and never an empty frame.\n\n## Placing pictures\n\n- Show an image large: at least half the row on a desktop. A fixed `aspect-ratio`, `object-fit: cover`, real alt text.\n- Layer it: a stat chip or a review card over its edge on `--shadow-3`, the picture itself on `--shadow-4` in the hero.\n- Text on a photograph sits on an overlay drawn from the ground color, measured at 4.5:1.\n- The hero's image loads at once (no `loading=\"lazy\"`, `fetchpriority=\"high\"`). Every image below the first screen takes `loading=\"lazy\"` and `decoding=\"async\"`.\n- One treatment across the page: the same warmth, contrast, radius and crop habit.\n- People without photographs are monograms: initials in the display face on an `--accent-quiet` disc.\n\n## Check before you save\n\n- Do the hero and at least two more sections carry a figure, a spot or a real image?\n- Does every spot carry all three attributes and a drawn fallback, with no img inside it?\n- Is every figure drawn from the page's own content, with no shape-built scene and no empty box?"
|
|
335
439
|
},
|
|
336
440
|
"typography": {
|
|
337
441
|
"id": "typography",
|
|
@@ -351,8 +455,8 @@ export const SKILL_BODIES = {
|
|
|
351
455
|
"id": "layout-grids",
|
|
352
456
|
"title": "Layout and grids",
|
|
353
457
|
"kind": "foundation",
|
|
354
|
-
"when": "Load before choosing a section's
|
|
355
|
-
"body": "# Layout and grids\n\nA careful model's default page is a stack of full-width bands, each a centered heading over a row of equal cards. That is the slab, and it is the first thing a client notices. Layout is where you
|
|
458
|
+
"when": "Load before choosing a section's layout or building any grid, and when a page reads as a run of identical bands.",
|
|
459
|
+
"body": "# Layout and grids\n\nA careful model's default page is a stack of full-width bands, each a centered heading over a row of equal cards. That is the slab, and it is the first thing a client notices. Layout is where you compose the page on purpose: a different shape in every section, a bento, layers that overlap, all on one calm edge.\n\n## The grid and the edge\n\n- Twelve columns. Content no wider than `var(--content, 76rem)`, sides at `var(--gutter, 1.25rem)`, running text at `var(--measure, 65ch)`.\n- One content edge: every section's content and every heading start on that container's line, unless the section is deliberately centered or an image deliberately bleeds to the viewport edge.\n- Grid for two dimensions, flexbox for a single row. Never fake columns with percentage widths.\n\n## A layout for every section\n\nWrite the section list first and give each section one of these. Neighbors never share one.\n\n- Split: copy over 7 columns, media over 5, the media layered with a floating chip.\n- Bento: 4 to 7 tiles in at least 3 sizes, one spanning 2 columns or 2 rows, the tiles differing in content type (a stat, a mini chart, a figure, an image, a quote, a list). Every home page has one.\n- Sticky stack: the heading holds on one side while cards stack past it on the other.\n- Marquee band: the client's real names moving in a strip, paused on hover.\n- Full-bleed media: a photo or a figure edge to edge, the text over a scrim.\n- Timeline or steps: numbered in type, with a line that draws between them.\n- Also: a comparison, a testimonial wall of mixed lengths, a form panel raised beside its promise.\n- A section that is only a heading, a paragraph and a list is a draft, not a design.\n\n## Spacing and rhythm\n\n- Section padding is `var(--pad-open)` or `var(--pad-dense)` and nothing else, the same above and below, alternating so the page has two speeds.\n- Every gap, margin and padding inside reads a `--space` token. More space goes above a heading than below it.\n\n## Overlap, on purpose\n\n- At least one overlap per page: a chip over the hero visual's edge, a stat on an image corner, media rising into the section above with a negative margin.\n- The layer that crosses sits above what it crosses: `position: relative` and a z-index inside an `isolation: isolate` stack, with the section it enters padded to make room. The next section never covers it.\n\n## Balance\n\n- In a two-column row both columns carry comparable weight. A much shorter column is centered or anchored on purpose.\n- Vary the openings: not every section is a heading on the left with an empty right half.\n- One element dominates each section. No row of equal cards: use the bento, a zig-zag or a list.\n- Left-align at least half the sections. Centering suits short statements, not everything.\n\n## Reflow without breakpoints\n\n- `grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr))` fits every width without a media query.\n- `min-width: 0` on every grid and flex child, so a long word cannot push the page sideways.\n- A breakpoint only where the layout itself changes. Inside a component, prefer a container query.\n\n## Example\n\n```css\n.bento { container-type: inline-size; display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); grid-auto-rows: minmax(11rem, auto); gap: var(--space-m, 1.5rem); }\n.bento__tile--lead { grid-column: span 2; grid-row: span 2; }\n.bento__tile--wide { grid-column: span 2; }\n@container (width < 48rem) { .bento__tile--lead, .bento__tile--wide { grid-column: span 4; grid-row: auto; } }\n```\n\nEach class here is one block or element. How blocks, slots and loops are structured for the build follows the build law (docs/BUILD-LAW.md in the SpecShot repository, and the structure part of the design law the design_law prompt serves), which this skill leaves to it.\n\n## Check before you save\n\n- Does each pair of neighboring sections use a different layout, with a bento on a home page?\n- Does every section's content start on one edge, with every overlap on purpose and above what it crosses?\n- Is every section padded from the two rhythm tokens, the same above and below?"
|
|
356
460
|
},
|
|
357
461
|
"color-contrast": {
|
|
358
462
|
"id": "color-contrast",
|
|
@@ -366,14 +470,28 @@ export const SKILL_BODIES = {
|
|
|
366
470
|
"title": "Surfaces and elevation",
|
|
367
471
|
"kind": "foundation",
|
|
368
472
|
"when": "Load before giving anything a background, border, shadow, radius, divider or overlay.",
|
|
369
|
-
"body": "# Surfaces and elevation\n\nDepth tells a visitor what sits on top of what. Keep it to a few tokens and use them by name; never invent a shadow or a radius inside a component.\n\n## Shadows\n\n-
|
|
473
|
+
"body": "# Surfaces and elevation\n\nDepth tells a visitor what sits on top of what, and the owner asked for it by name: \"dark shadows\". Keep it to a few tokens and use them by name; never invent a shadow or a radius inside a component.\n\n## Shadows\n\n- Four tokens: `--shadow-1` for cards at rest, `--shadow-2` for raised and hovered things, `--shadow-3` for a floating chip or card over another layer, `--shadow-4` for the hero visual.\n- Each is two or three layers: a tight contact shadow (small offset and blur, higher opacity) and a wide ambient one (large offset and blur, low opacity), tinted with the ink hue. Every shadow has an offset and a blur. Never a colored glow with no offset, never a radial spotlight.\n- On a dark page the shadows are deep: black tinted toward the brand hue at 40 to 70 percent, and a raised surface may add a 1px inset highlight along its top edge.\n- An element carries a border or a shadow, never both. The inset highlight is not a border.\n- To lift something on hover, fade in a pseudo-element that holds the bigger shadow. Never transition box-shadow directly.\n\n## Layers\n\n- Surfaces step in lightness: the ground, a panel, a card, a floating element, a few points apart and tinted toward the brand hue.\n- At least one overlap on a page: a stat chip over the hero visual's edge on `--shadow-3`, media rising into the section above with a negative margin. The layer that crosses sits above what it crosses, with `position: relative` and a z-index inside an isolated stack, and the next section never covers it.\n\n## Lines\n\n- Hairlines are 1px in `--line`, a low-opacity ink. The edges of controls use `--line-strong`, which keeps 3:1 against the ground.\n- Use a divider only where space has not already separated two things.\n- Never a thick colored stripe down one side of a card. That side-tab is one of the plainest template tells.\n\n## Radius\n\n- One scale, all tokens: `--radius-s` for controls and buttons, `--radius-m` for cards, panels and pictures, `--radius-l` for a very large panel, `--radius-pill` for chips and tags only. Use two on a page, a small and a large.\n- A 50 percent radius bends a wide shape into an ellipse, so keep it for true circles such as monograms.\n- Curves stay concentric: an inner radius is the outer radius minus the padding between them.\n\n## Grounds\n\n- A surface needs a reason: `--paper-2` for an alternate section, `--paper-3` for a well or a track. The `--night` roles belong to a dark theme for the whole page or a dark object such as a product window, never a dark band dropped into a light page.\n- Fewer boxes. A card is for something a person opens or picks, and never a card inside a card.\n- No grain, noise texture or feTurbulence filter, and no ornament. A flat color with a real shadow is a finished surface.\n\n## Overlays\n\n- Text over an image sits on a gradient overlay drawn from the ground color, strongest under the text.\n- Glass only where content moves underneath, such as a sticky header: `backdrop-filter: blur(16px)` over a ground at 72 to 80 percent opacity, with a solid ground for browsers without it.\n- A dialog or sheet takes `--shadow-3`, keeps focus inside while open and closes on Escape.\n\n## Example\n\n```css\n.panel { position: relative; background: var(--paper, oklch(98% 0.006 80)); border-radius: var(--radius-m, 0.875rem); box-shadow: var(--shadow-1, 0 1px 2px oklch(20% 0.015 60 / 0.08), 0 4px 12px -4px oklch(20% 0.015 60 / 0.08)); }\n.panel::after { content: \"\"; position: absolute; inset: 0; border-radius: inherit; box-shadow: var(--shadow-2, 0 2px 4px oklch(20% 0.015 60 / 0.08), 0 12px 24px -8px oklch(20% 0.015 60 / 0.14)); opacity: 0; transition: opacity var(--dur-2, 240ms) var(--ease-out, cubic-bezier(0.16, 1, 0.3, 1)); }\n.panel:hover::after { opacity: 1; }\n```\n\n## Check before you save\n\n- Does every raised surface use a layered elevation token, and does one layer overlap another?\n- Does any element have both a border and a shadow, or a card inside a card?\n- Are there two radii, a small and a large, all of them tokens, with pills only on chips?"
|
|
370
474
|
},
|
|
371
475
|
"motion": {
|
|
372
476
|
"id": "motion",
|
|
373
477
|
"title": "Motion and animation",
|
|
374
478
|
"kind": "foundation",
|
|
375
|
-
"when": "Load before adding any transition, entrance, hover
|
|
376
|
-
"body": "# Motion and animation\n\
|
|
479
|
+
"when": "Load before adding any transition, entrance, reveal, hover state, floating figure, marquee, animated chart or signature interaction.",
|
|
480
|
+
"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\nWhat all of this costs, and the reveal feel the owner approved after measuring a site for smoothness: the smooth-motion skill.\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?"
|
|
481
|
+
},
|
|
482
|
+
"copywriting": {
|
|
483
|
+
"id": "copywriting",
|
|
484
|
+
"title": "Website copy that converts",
|
|
485
|
+
"kind": "foundation",
|
|
486
|
+
"when": "Load before writing or rewriting any words on a page: headlines, sections, calls to action, proof, forms and messages.",
|
|
487
|
+
"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."
|
|
488
|
+
},
|
|
489
|
+
"seo": {
|
|
490
|
+
"id": "seo",
|
|
491
|
+
"title": "On-page SEO and AI search visibility",
|
|
492
|
+
"kind": "foundation",
|
|
493
|
+
"when": "Load before designing any page, and before writing its headings, links, image text or FAQ.",
|
|
494
|
+
"body": "# On-page SEO and AI search visibility\n\nA page is read by people, by search engines and by AI assistants. All three reward the same things: a clear topic, facts stated plainly, a structure that says what each part answers, and a page that loads fast without shifting. Nothing here is a trick.\n\n## Structure\n\n- One `h1`, carrying the page's main topic in the client's own words. For a local business it names the service and the place: \"Dental implants in Austin\", not \"Smiles that last\".\n- Headings in order with no skipped level. Each `h2` names what its section answers or proves.\n- Landmarks: one `header`, one `nav` for the main menu, one `main`, one `footer`.\n- Every fact, heading and link is text in the markup. Never only in an image, a CSS `content` value or an SVG without a text equivalent.\n\n## Words search reads\n\n- The main topic appears in the `h1`, in the first paragraph and in one `h2`, naturally. Related terms go in other headings and the body. Never repeat a phrase to rank.\n- Answer first: each section opens with one plain sentence that answers its question, then the detail. That sentence is what a search snippet or an assistant quotes.\n- Service and home pages carry an FAQ of the questions customers really ask, from the brief or the client's copy: each answer 40 to 60 words, its first sentence the answer itself.\n- Facts the client gave are stated plainly, once, and the same everywhere: services, area served, hours, phone, address, prices. A missing fact is left out, never invented.\n\n## Links\n\n- Internal links say where they go: \"See implant pricing\", \"Read how a visit works\". Never \"click here\" alone, and \"Learn more\" only beside a heading that names the topic.\n- A page links to at least three related pages: in the content, the actions and the footer. Something that navigates is an `a` with a real `href`, not a button.\n\n## Images and media\n\n- Every meaningful image has alt text that says what it shows and why it is there. A decorative image has `alt=\"\"`, a decorative SVG `aria-hidden=\"true\"`. An image spot carries its alt text in `data-ss-alt`.\n- Every image and media frame has a size before it loads (`width` and `height`, or an `aspect-ratio`), so nothing shifts. Images below the first screen load lazily. The hero's image never does.\n\n## Speed is part of SEO\n\n- No layout shift from fonts or images. Fonts swap in with a matched fallback.\n- Motion moves transform and opacity only, and no large area carries a heavy blur or filter.\n- The page is complete and readable with no script.\n\n## Head and structured data\n\nThe plugin's SEO suite writes the title, the meta description and the structured data when the site is deployed. The design makes them true:\n\n- The page's topic and the client's facts are visible on the page, so the title (50 to 60 characters, the topic then the brand), the description (140 to 160 characters, with a reason to click) and the structured data all match what a visitor reads.\n- Structured data only ever restates visible facts: the business (name, phone, address, area served, hours), its services, the FAQ exactly as shown, and breadcrumbs on inner pages.\n\n## Never\n\n- Hidden text, keyword stuffing, text written for crawlers or assistants, invented reviews, ratings, awards or credentials. They get a site penalized and they break the client's trust."
|
|
377
495
|
},
|
|
378
496
|
"accessibility": {
|
|
379
497
|
"id": "accessibility",
|
|
@@ -389,12 +507,26 @@ export const SKILL_BODIES = {
|
|
|
389
507
|
"when": "Load before building any page, and for the responsive pass before saving: SpecShot's frame is dragged to every width.",
|
|
390
508
|
"body": "# Responsive behavior\n\nSpecShot previews a design in a frame the owner drags to any width, continuously. A layout that holds at three widths and breaks at 900 has failed, and it is the most common way a design that looked fine falls apart on a real device.\n\n## Fluid first\n\n- Type and space come from the token contract, each a clamp() from a 360px phone to a 1440px desktop. A media query never changes a font size or a padding.\n- Grids reflow by content: `repeat(auto-fit, minmax(min(100%, 18rem), 1fr))` needs no breakpoint and is right at widths nobody tested.\n- Containers size with `min()`: `width: min(100% - 2 * var(--gutter, 1.25rem), var(--content, 76rem))`.\n- Every grid and flex child gets `min-width: 0`. That one line prevents most sideways scroll from a long word or a wide table.\n- Images and media: `max-width: 100%`, `height: auto` and an `aspect-ratio`, so nothing jumps.\n\n## Breakpoints, only where the layout changes\n\n- A breakpoint is the exception you justify: the navigation folding into a menu, a split becoming one column, a table becoming stacked rows.\n- Place it where the content breaks, found by dragging, not at a stock device width.\n- Prefer a container query for anything inside a component. A card in a sidebar and the same card in a hero are different widths at the same viewport, and only a container query gets both right.\n- Name what changes at each breakpoint in your notes. A design with ten breakpoints is a design that was not built fluid.\n\n## The pass\n\nBefore saving, drag through every width and look:\n\n1. 360 to 430: one column, the primary action visible on the first screen, no sideways scroll, text at least 1rem.\n2. 600 to 900: the awkward middle. Two-column splits often break here; grids should be at two columns, not stretched singles.\n3. 1024 to 1440: the designed layout.\n4. 1920 and wider: content held at `--content`, grounds and bleeds running to the edges, nothing floating in a sea of space.\n\n## Height and the device\n\n- dvh and dvw, never vh: on a phone vh measures past the toolbar and a full-screen hero is cut off. Use `min-height: min(100dvh, 56rem)` only when the content fills it.\n- Respect safe-area insets (`env(safe-area-inset-left)`) for anything at the screen edge.\n- Touch targets at least 2.75rem square in every layout.\n\n## Touch and pointer\n\n- Anything that only happens on hover is unreachable on a phone. Give it a tap, a visible default or a scroll equivalent.\n- A cursor-following effect does nothing on touch; its fallback is a calm static state.\n- `@media (hover: hover)` wraps hover-only polish, so touch devices do not get sticky hover states.\n\n## Wide content\n\n- The body never scrolls sideways. A wide table or code block scrolls inside its own container with `overflow-x: auto`, a visible edge hint and keyboard focus.\n- A rail of cards uses `scroll-snap-type: x mandatory` with the last card cut at the edge to say there is more.\n\n## Example\n\n```css\n.features__grid { display: grid; gap: var(--space-m, 1.5rem); grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr)); }\n.feature { min-width: 0; container-type: inline-size; }\n@container (width > 26rem) { .feature__inner { display: grid; grid-template-columns: auto 1fr; gap: var(--space-s, 1rem); } }\n```\n\n## Check before you save\n\n- Is there no sideways scroll at any width from 360 to 1920?\n- Does every breakpoint mark a real change of layout, and none resize type?\n- Can every hover effect be reached on touch?"
|
|
391
509
|
},
|
|
510
|
+
"content-model": {
|
|
511
|
+
"id": "content-model",
|
|
512
|
+
"title": "Content model first",
|
|
513
|
+
"kind": "build",
|
|
514
|
+
"when": "Load before planning or building a whole site, a page that belongs to a family (docs, blog, changelog, legal, services, features), or any type's archive, single or category design.",
|
|
515
|
+
"body": "# Content model first\n\nThe owner's rule for every site SpecShot builds in Etch: maintainable, easy to manage and easy to navigate. So the content is modeled before any page is built, and the Pages list stays short.\n\n## Every page has one role\n\n- **Page**: unique (home, about, pricing, contact). The home page is the front page.\n- **Archive**: the list of all items of a type (\"Docs\", \"Blog\", \"Features\").\n- **Single**: the design every item of a type uses (\"Docs article\", \"Blog post\").\n- **Category page**: one category of a type (\"Docs category\").\n- **Item**: a real item of a type (\"MCP\", \"Privacy Policy\"), with its own content and field values.\n- **Site template**: not found (404) and search results.\n\nTwo or more pages that do one job are a content type, never a row of plain Pages: docs, a blog, a changelog, legal pages, services, case studies, features. A group of one stays a Page. SpecShot detects the structure for any project and the agency confirms or corrects it in SpecShot (Design, then Structure).\n\n## Mark a type's designs for their templates\n\n- A single design marks what every item fills in: `data-bind=\"title\"` on its title, `data-bind=\"field:summary\"` on each value the items share, `data-bind=\"excerpt\"`, `\"date\"`, `\"image\"` (on the img) or `\"url\"` (on a link), and `data-bind=\"content\"` on the element that holds the item's own body. Everything unmarked is the template.\n- An archive, category or search design puts `data-loop=\"main\"` on its list and keeps one card inside it, its parts marked with data-bind. The build makes it Etch's Main Query loop, which lists the real items with pagination.\n- A list of a type's items on another page (the latest posts on Home) is a loop of its own over that type, never a copy of the items and never `data-loop=\"main\"`.\n- Each item keeps its own composition inside its content. A family's pages are never one skeleton stamped across: every page keeps the kit's parts and the type's bindings and chooses its own composition.\n\nThe save check warns a single design with no title binding (`template-bindings`) and an archive with no Main Query loop (`archive-loop`).\n\n## Templates, built from the designs\n\n- **index** first: the header component, `main` with Post Content, and the footer component. Every other template places the same two components and no page keeps a copy.\n- **single** for every type, **archive** for every type with a list, **taxonomy** for every category with pages, plus **404** and **search**.\n- The header and footer are the site kit's components. On the canvas a design still shows the whole page, header to footer.\n\n## Where the types live\n\n- Etch's own post types and fields come first, read as `{this.etch.key}`. Its documented fields are text, textarea, number and yes or no.\n- SpecShot suggests ACF, with the reason, when a type needs an image, gallery, link, date, select, relationship or repeater field, site-wide values, or the site has many types. ACF fields are read as `{this.acf.key}`. The agency picks.\n- Categories: ACF creates them for you, while Etch's own categories are made by hand in its Content Manager for now.\n- On Etch Studio: a content type per type, a static route for the list and a dynamic route under it served by the single template.\n\n## Check before you build\n\n- Does every family of two or more pages have a type, and does the Pages list hold only unique pages?\n- Does each single design bind its title and its body, and each archive carry one card in `data-loop=\"main\"`?\n- Are the header and footer the kit's components, never a copy on a page?"
|
|
516
|
+
},
|
|
392
517
|
"etch-acss-build": {
|
|
393
518
|
"id": "etch-acss-build",
|
|
394
519
|
"title": "The Etch and ACSS build",
|
|
395
520
|
"kind": "build",
|
|
396
521
|
"when": "Load before building any page or section that will go to Etch, which is every SpecShot design, and before running get_etch_build.",
|
|
397
|
-
"body": "# The Etch and ACSS build\n\nEvery SpecShot design has to build into Etch with nothing lost. When the page is written the way the export reads it, the agency gets something they can edit in Etch rather than something they rebuild.\n\n## Write it the way Etch reads it\n\n- One class per rule, named in BEM: `.block`, `.block__element`, `.block--modifier`. States and pseudo-elements on that class are fine. A single-class rule becomes an Etch class style the agency can find and edit; `.hero h1` or `section > div` ends up as a page-level rule nobody can find.\n-
|
|
522
|
+
"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- 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 blocks 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- Sections at the top: on the canvas 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. Then load etch-clean-build.\n\n## Content model first\n\nA whole site gets its content model before Etch (load content-model): families are content types with archive and single templates, a single design marks data-bind, an archive data-loop=\"main\", and the header and footer are kit components in the index template.\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, and a builder reads it with `etch.skills.get(\"acss\")`.\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- 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?"
|
|
523
|
+
},
|
|
524
|
+
"etch-clean-build": {
|
|
525
|
+
"id": "etch-clean-build",
|
|
526
|
+
"title": "The clean Etch build",
|
|
527
|
+
"kind": "build",
|
|
528
|
+
"when": "Load before building pages into Etch with get_etch_build, get_etch_template_build or send_to_wordpress, and before reading the law findings they return.",
|
|
529
|
+
"body": "# The clean Etch build\n\nWhat SpecShot's build makes of a page in Etch, and what the Etch build law checks on every plan. The owner's standard: a page in Etch's structure panel is a short list of components named in plain words, and nothing else.\n\n## The page and the template\n\n- The page's top level is its sections, side by side. The header and footer live in the site's template, around Etch's Post Content, once for every page.\n- Through the Etch Connector: build the template once with get_etch_template_build, into the template the pages show with. It builds only into a template that holds nothing of the site's own, and says so otherwise. Then build each page with get_etch_build and chrome: template.\n- On a WordPress site with the SpecShot plugin: send_to_wordpress sends the pages, and when a person presses Apply as drafts in WordPress the site builds SpecShot's own page template and every page as drafts. The template comes from the approved site kit, or the approved home page, when it has a header and footer.\n- A page built with its own header and footer puts them beside its sections. The law says so in every answer.\n\n## What a WordPress deploy builds (plugin 0.5.13)\n\n- Each section is its own component, named for its page and its `data-section` key: SP Pricing FAQ, and on the home page SP Hero. Give every section a key in plain words (hero, pricing, faq).\n- No section, component or part name carries a tag, a version, a hash or a cut-off sentence.\n- Every part inside a component is named in the structure panel in plain words for its element (`sp-mcp-hero__title` is Title, `sp-docs-hero__palette-hit-link` is Palette Hit Link), or in a plain word where it has no class (Heading, Link, Image). Never by its class string: Etch shows the class beside the name, so it would read twice. The build law's rule `class-name` flags any part named by its own class.\n- A section's texts and links are its component's fields with the design's words as defaults, grouped by the section's parts and named from their classes (a group such as Card 1, a field such as Title or Button 2 label). A person edits them in the component's properties.\n- A heading, a line of text or a link whose words are plain becomes a field. A paragraph that mixes words with links stays in the structure, and so does a code sample and what a loop repeats. Words that read as a script link (\"JavaScript: the good parts\") stay text.\n\n## What the Connector tools build\n\nget_etch_build and get_etch_template_build build the labeled form that the extension and the plugin's panel build too: each top-level block is named `SpecShot: <name> [<tag>]`, so each tool finds and replaces its own build. Its sections are not components and have no fields yet. That changes for every tool together.\n\n## The law's findings\n\nget_etch_build, get_etch_template_build and send_to_wordpress return `law`: each place a plan breaks a rule, where it is and what to change. Fix the design where a finding is the design's (a class name, a px value, a section with no key), and tell the person the rest before they build or apply.\n"
|
|
398
530
|
},
|
|
399
531
|
"agency-process": {
|
|
400
532
|
"id": "agency-process",
|
|
@@ -408,7 +540,7 @@ export const SKILL_BODIES = {
|
|
|
408
540
|
"title": "The discovery interview",
|
|
409
541
|
"kind": "page",
|
|
410
542
|
"when": "Load when the owner says new client or start discovery, before interviewing anyone about a client, a project or its brief.",
|
|
411
|
-
"body": "# The discovery interview\n\nHow to run discovery as a conversation, and how the answers become the project's brief in SpecShot. The brief is the source of truth for every later phase.\n\n## Before the first question\n\n- Establish the project (list_projects, then get_project_state) and read what exists: get_project_intelligence, and the client's own answers to the portal questionnaire (get_discovery_answers). Never ask again what the client already answered; confirm it or ask what changed.\n- Ask whether you are talking to the business owner or to someone relaying the client's answers. It changes how hard to push, and pushing a client directly is the owner's call.\n\n## How to ask\n\n- One to three related questions per turn, then wait. Never paste the question list, and never answer your own question.\n- Answers often arrive long, because many people dictate. Read each one fully before moving on; most of the next questions are already answered in it.\n- Refuse vague answers. \"Professionals\", \"high quality\" and \"we care more\" are not answers: ask for a name, a number, a real customer, a sentence someone actually said.\n- When a word you were given does not parse, ask rather than guess.\n- When the owner hedges (\"I think\", \"about\", \"I'd have to check\"), it is not a fact. Record it as unverified and say so.\n- Do not ask about timelines or budget. By discovery the money is settled, and discovery is input for the marketing, the copy and the design only.\n\n## What to cover, in the questionnaire's order\n\n1. Goals: what the site has to do, what a convinced visitor does next, how the client will know it worked.\n2. The offer: what they sell in a customer's words, what to push hardest, who they do not want.\n3. The audience: the best customer, their problem, the main objection, words a customer actually used, who signs off.\n4. The market: two or three competitors, and why someone picks this business over them.\n5. The pages the site needs, and what each one must do.\n6. The brand: three words for how it should come across, a site they love and one they cannot stand, the logo, colors and fonts they have, anything off-limits.\n7. Proof: named results, real numbers, photos and documents, and anything they may not legally say.\n\n## A new client\n\nBefore the first project of a new client,
|
|
543
|
+
"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, the client and the project are in SpecShot: a person adds them (Clients, then Projects), or you add them when the owner asks (create_client after list_clients shows the client is not there yet, then create_project). Then interview the owner, one question at a time, and stop when another question would only produce detail nobody needs:\n\n- Who they are: what the business does, its customers, its size, where it is, its website.\n- The people: names, exact titles, who has final say, who handles the day to day, anyone outside the company involved.\n- Approvals: who approves what, where, and how quickly they answer.\n- Money: only what the owner offers, recorded exactly, never rounded.\n- What is happening now: open work, recent work, what waits on whom.\n- The voice: who they speak to, how they sound, words they use or avoid, the page that shows them at their best.\n- The site: what it runs on, anything custom or fragile, and the platform for the build, Etch on WordPress or Etch Studio. Ask it outright, never infer it, and ask early when a decision depends on it (membership, a shop, a plugin feature, rebuilding a WordPress site in place).\n- Anything else: contract status, history, and \"anything I have not asked about?\"\n\n## Write as you go\n\n- After every section, write it to the brief with set_project_intelligence: the question and answer pairs under discovery (they append), and the fields the section fills (businessGoals, targetAudience, pageGoals, constraints, platformPreferences). A dropped session then costs one section.\n- Mark every unknown as an open question (openQuestions). Never fill a field with something plausible.\n- Use `[UNVERIFIED]` for something stated but not confirmed and `[GAP]` for something unknown, the same markers the copy uses. Never a third option.\n- For a regulated field (legal, medical, financial), list the claims that must never be written without a document behind them in constraints.\n- Add the pages the brief implies with create_page once the owner agrees the list. The client accepts the plan in the portal.\n\n## When you finish\n\nSay how many questions are open (a number), which three or four matter most and why, and what the client still has to send. Never contact the client, never set a price, and never touch a site."
|
|
412
544
|
},
|
|
413
545
|
"copy-and-wireframe": {
|
|
414
546
|
"id": "copy-and-wireframe",
|
|
@@ -436,21 +568,21 @@ export const SKILL_BODIES = {
|
|
|
436
568
|
"title": "Design QA gate",
|
|
437
569
|
"kind": "page",
|
|
438
570
|
"when": "Load before calling a page done or handing it to a client: the per-page checks, content stress cases, media rules and performance budgets, each with its evidence.",
|
|
439
|
-
"body": "# Design QA gate\n\nWhat a page passes before anyone calls it done. Record each check as Pass, Fail, Blocked or Not applicable, with the screenshot, render or source that shows it. A saved page alone is not evidence, and every Fail gets an owner and a retest. The design_review prompt grades the craft; this gate checks that the page works.\n\n## Purpose and content\n\n- The page's purpose fits in one sentence, and one primary action dominates. Secondary actions never compete with it.\n- The H1 states the page's promise or task, and the first screen says who the page is for and what happens next.\n- Every claim, number, quote, logo and award is verified or left out. No fake urgency, scarcity or proof.\n- No gap marker is left in copy that goes live.\n- The existing templates and components were read before anything changed.\n\n## Content stress\n\n- Long, short, missing and empty content each still look intentional.\n- Long headings, long links, long names and translated text about a third longer were tried.\n- Missing media, missing optional fields and an empty list were tried. An optional field leaves no empty wrapper or stray separator, and an empty list collapses or shows its empty state.\n\n## Widths and zoom\n\n- The page is composed on purpose at 360 and 390 pixels wide, across tablet widths, on a laptop and on a desktop. On an ultrawide screen the content stays bounded.\n- At 200 percent zoom every control still works, and narrow reflow causes no sideways scroll.\n- Sticky headers and a phone's safe areas never cover content or the focus ring.\n\n## Access\n\n- A skip link reaches the main content. One main landmark, one H1, headings in order.\n- The keyboard path works forward and back, focus is always visible, and color is never the only signal.\n- Text and controls pass contrast in every theme the design ships. Icon-only controls have names, a dialog holds and returns focus, and a form has visible labels, the right input types, autocomplete and errors tied to their fields.\n- With reduced motion, content and function stay. The core task works without scripts, or has another route.\n\n## Motion\n\n-
|
|
571
|
+
"body": "# Design QA gate\n\nWhat a page passes before anyone calls it done. Record each check as Pass, Fail, Blocked or Not applicable, with the screenshot, render or source that shows it. A saved page alone is not evidence, and every Fail gets an owner and a retest. The design_review prompt grades the craft; this gate checks that the page works.\n\n## Purpose and content\n\n- The page's purpose fits in one sentence, and one primary action dominates. Secondary actions never compete with it.\n- The H1 states the page's promise or task, and the first screen says who the page is for and what happens next.\n- Every claim, number, quote, logo and award is verified or left out. No fake urgency, scarcity or proof.\n- No gap marker is left in copy that goes live.\n- The existing templates and components were read before anything changed.\n\n## Content stress\n\n- Long, short, missing and empty content each still look intentional.\n- Long headings, long links, long names and translated text about a third longer were tried.\n- Missing media, missing optional fields and an empty list were tried. An optional field leaves no empty wrapper or stray separator, and an empty list collapses or shows its empty state.\n\n## Widths and zoom\n\n- The page is composed on purpose at 360 and 390 pixels wide, across tablet widths, on a laptop and on a desktop. On an ultrawide screen the content stays bounded.\n- At 200 percent zoom every control still works, and narrow reflow causes no sideways scroll.\n- Sticky headers and a phone's safe areas never cover content or the focus ring.\n\n## Access\n\n- A skip link reaches the main content. One main landmark, one H1, headings in order.\n- The keyboard path works forward and back, focus is always visible, and color is never the only signal.\n- Text and controls pass contrast in every theme the design ships. Icon-only controls have names, a dialog holds and returns focus, and a form has visible labels, the right input types, autocomplete and errors tied to their fields.\n- With reduced motion, content and function stay. The core task works without scripts, or has another route.\n\n## Motion\n\n- The page is alive: a load entrance, scroll reveals that differ by section in the safe form, two to four moving figures, and hover, press and focus on every control. Each animation has a purpose.\n- Motion runs on transform and opacity, and touch and keyboard get what a pointer gets.\n- No scroll hijacking, no fake delay, no bounce easing.\n\n## Media\n\n- Every image has a job, a source and the right to use it. No fabricated customer, result, testimonial, interface or partner.\n- Width and height or an aspect ratio are reserved, images are responsive and in modern formats, and each crop works at every width.\n- Text over an image stays live text and stays legible in every theme.\n\n## Performance budgets\n\nMeet each budget, or record the named blocker that stops it:\n\n- Largest contentful paint (LCP) 2.5 seconds or less.\n- Interaction to next paint (INP) 200 milliseconds or less.\n- Cumulative layout shift (CLS) 0.1 or less.\n- Delivered CSS 150 KB or less.\n- The first view weighs 1.5 MB or less.\n\nAlso: the H1 and the primary action render without waiting for motion or media, no motion script ships without a named reason, a failed third-party script leaves the page usable, a form blocks a double submit and offers recovery, and no credential, private data, staging address or internal note appears.\n\n## Search and consent\n\n- One search intent owns the page. Title, description, slug, H1, canonical and internal links agree, and structured data matches what is visible.\n- Analytics respect consent, and privacy and legal wording matches what the site really does.\n\n## Evidence, then approval\n\n- The saved source, the computed styles and a real render in Chromium and WebKit were checked at the widths above. On WordPress, check_built_page compares the built page with the approved design.\n- Keyboard and reduced-motion checks are recorded, and a form was sent end to end.\n- Passing this gate approves the page. Publishing is a separate decision, and it is the owner's."
|
|
440
572
|
},
|
|
441
573
|
"etch-development": {
|
|
442
574
|
"id": "etch-development",
|
|
443
575
|
"title": "Etch development",
|
|
444
576
|
"kind": "build",
|
|
445
577
|
"when": "Load when the owner says start development, before building an approved design into Etch, and before driving an Etch tab through the Etch Connector.",
|
|
446
|
-
"body": "# Etch development\n\nHow the development phase runs. The approved SpecShot design is built into Etch, then refined there through the Etch Connector. The structure and CSS rules are etch-structure and etch-css, and the runtime facts are etch-connector-runtime.\n\n## Starting development\n\n1. Confirm the project and that the client approved the design for each page (get_project_state). Build the approved design, never a wireframe.\n2. Confirm the platform: Etch on WordPress or Etch Studio. Ask outright; never infer it from a default.\n3. Confirm what the site is: a new build, a rebuild, staging or live production. It decides what may be touched, and anything unclear is production.\n4. Build the design with Build in Etch. Over MCP, read the etch_ready prompt and call get_etch_build with dryRun first, then run its script with the connector. The owner may instead press Build in Etch in the extension's side panel, in the canvas dialog, or in the SpecShot plugin's Etch panel on WordPress (list_wordpress_sites shows whether a site is connected).\n5. For work by hand, start the connector every session with `npx @digital-gravy/etch-connector serve`, even when the builder's AI button still looks on. Read `etch-connector --help` in full, and use the tab the owner names, checking `tabs` for duplicate names before working on two sites.\n\n## What may be touched\n\n- Without asking per change: a new build, a rebuild on a development or staging site, the agency's own sites.\n- Ask every time: a client's live production site.\n- Never, on any site: logins, plugin installs or updates, theme files, hosting, DNS, publishing or deploying. Draft it and hand it over.\n\n## How the work runs\n\n- Read before you write: query the blocks and styles and return them first.\n- Make small, reviewable changes, one section or component at a time. Say what is about to happen, do it, and say what changed.\n- Batch, then save. Blocks, styles and loops persist only on `await etch.saveAsync()`; stylesheets, components and fields write at once.\n- Verify on the front end, not only in the builder, which can show a change the page does not have yet. On WordPress, check_built_page compares the built page with the approved design once the build is recorded.\n- Flag every inference (a button color, a breakpoint, a variable) as an inference.\n- Stop and ask before anything destructive: deleting blocks, replacing a section, or changing a global stylesheet or a component other pages use.\n- Record progress with update_concept_status (sent when the build starts, built when it is complete) and add_build_note.\n\n## Scripts and names\n\n- Run a script with `etch-connector eval -t <tab> \"<js>\"`, or `-f file.js` for anything longer, kept in the client's local scratch folder. In zsh, wrap the command in a function rather than a string variable.\n- A script runs as an async function: await, and return a value, which comes back as JSON. Read state before mutating it.\n- Tabs run in safe mode: the etch global and standard JavaScript only, with no window and no document.\n- The Etch API is experimental. Ask the runtime instead of guessing: `etch.environment` lists the product, capabilities and block types (when it is missing, assume everything is available), and `typeof etch.x.method === \"function\"` checks one method.\n- Errors come back as EtchApiError with a code, such as BLOCK_NOT_FOUND, READONLY, INVALID_ARGUMENT or NOT_AVAILABLE. Read it, report it plainly and stop, unknown codes included.\n- Never invent an API method, a block type or a variable name.\n\n## An ACSS settings file from the design\n\n1. On WordPress with the SpecShot plugin, prefer its brand pass: it maps the brand to ACSS settings with a dry run and a per-key diff, and the owner applies it with an automatic backup.\n2. Otherwise ask the owner for an ACSS settings export from one of their sites. It is the template: never write a settings file from scratch or invent a key.\n3. Read the design's numbers from the Design Direction board and the brand (get_brand_system): colors, fonts, the heading and text scales (base and ratio, desktop and mobile), the button style, the radius.\n4. Change only keys that already exist in the export. A color often appears in several forms (hex, OKLCH, sometimes HSL), so update every form until they agree. Font file paths point at the old site: flag them.\n5. Save it in the client's local folder with a short list of every change in plain words, so it can also be done by hand. Importing is the owner's, since it changes a site's settings."
|
|
578
|
+
"body": "# Etch development\n\nHow the development phase runs. The approved SpecShot design is built into Etch, then refined there through the Etch Connector. The structure and CSS rules are etch-structure and etch-css, and the runtime facts are etch-connector-runtime.\n\n## Starting development\n\n1. Confirm the project and that the client approved the design for each page (get_project_state). Build the approved design, never a wireframe.\n2. Confirm the platform: Etch on WordPress or Etch Studio. Ask outright; never infer it from a default.\n3. Confirm what the site is: a new build, a rebuild, staging or live production. It decides what may be touched, and anything unclear is production.\n4. Build the design with Build in Etch. Over MCP, read the etch_ready prompt and call get_etch_build with dryRun first, then run its script with the connector. The owner may instead press Build in Etch in the extension's side panel, in the canvas dialog, or in the SpecShot plugin's Etch panel on WordPress (list_wordpress_sites shows whether a site is connected).\n5. For work by hand, start the connector every session with `npx @digital-gravy/etch-connector serve`, even when the builder's AI button still looks on. Read `etch-connector --help` in full, and use the tab the owner names, checking `tabs` for duplicate names before working on two sites.\n\n## What may be touched\n\n- Without asking per change: a new build, a rebuild on a development or staging site, the agency's own sites.\n- Ask every time: a client's live production site.\n- Never, on any site: logins, plugin installs or updates, theme files, hosting, DNS, publishing or deploying. Draft it and hand it over.\n\n## How the work runs\n\n- Read before you write: query the blocks and styles and return them first.\n- Make small, reviewable changes, one section or component at a time. Say what is about to happen, do it, and say what changed.\n- Batch, then save. Blocks, styles and loops persist only on `await etch.saveAsync()`; stylesheets, components and fields write at once.\n- Verify on the front end, not only in the builder, which can show a change the page does not have yet. On WordPress, check_built_page compares the built page with the approved design once the build is recorded.\n- Flag every inference (a button color, a breakpoint, a variable) as an inference.\n- Stop and ask before anything destructive: deleting blocks, replacing a section, or changing a global stylesheet or a component other pages use.\n- Record progress with update_concept_status (sent when the build starts, built when it is complete) and add_build_note.\n\n## Scripts and names\n\n- Run a script with `etch-connector eval -t <tab> --timeout <ms> \"<js>\"`, or `-f file.js` for anything longer, kept in the client's local scratch folder. Every run names its tab and a timeout. In zsh, wrap the command in a function rather than a string variable.\n- A script runs as an async function: await, and return a value, which comes back as JSON. Read state before mutating it.\n- Tabs run in safe mode: the etch global and standard JavaScript only, with no window and no document.\n- The Etch API is experimental. Ask the runtime instead of guessing: `etch.environment` lists the product, capabilities and block types (when it is missing, assume everything is available), and `typeof etch.x.method === \"function\"` checks one method.\n- Errors come back as EtchApiError with a code, such as BLOCK_NOT_FOUND, READONLY, INVALID_ARGUMENT or NOT_AVAILABLE. Read it, report it plainly and stop, unknown codes included.\n- Never invent an API method, a block type or a variable name.\n\n## An ACSS settings file from the design\n\n1. On WordPress with the SpecShot plugin, prefer its brand pass: it maps the brand to ACSS settings with a dry run and a per-key diff, and the owner applies it with an automatic backup.\n2. Otherwise ask the owner for an ACSS settings export from one of their sites. It is the template: never write a settings file from scratch or invent a key.\n3. Read the design's numbers from the Design Direction board and the brand (get_brand_system): colors, fonts, the heading and text scales (base and ratio, desktop and mobile), the button style, the radius.\n4. Change only keys that already exist in the export. A color often appears in several forms (hex, OKLCH, sometimes HSL), so update every form until they agree. Font file paths point at the old site: flag them.\n5. Save it in the client's local folder with a short list of every change in plain words, so it can also be done by hand. Importing is the owner's, since it changes a site's settings."
|
|
447
579
|
},
|
|
448
580
|
"etch-structure": {
|
|
449
581
|
"id": "etch-structure",
|
|
450
582
|
"title": "Etch structure",
|
|
451
583
|
"kind": "build",
|
|
452
584
|
"when": "Load before writing the markup of any page or section that goes to Etch, and before changing structure in Etch through the Etch Connector.",
|
|
453
|
-
"body": "# Etch structure\n\nThe owner's rules for the structure of a site built in Etch: class names, the elements Etch expects, components and accessibility. They hold for the SpecShot design that goes to Etch and for every change made in Etch afterward. The export contract (tokens, the project prefix, the ACSS map) is etch-acss-build, and how a design marks its components, slots and loops follows the build law (docs/BUILD-LAW.md in the SpecShot repository, and the structure part of the design law the design_law prompt serves).\n\n## Flat BEM names\n\n- Block `hero`, element `hero__heading`, modifier `featured-card--highlighted`, for true visual variants only.\n- One level deep: `featured__title`, never `featured__header__title`, however deep the markup.\n- A repeating component is its own block, not an element of its section: a card in the featured section is `featured-card` with `featured-card__title`, never `featured__card`.\n- No prefix of our own (the export adds the project's), but avoid generic single words a theme or plugin might also use, such as card or grid. Give them a second word: `service-card`.\n- Structural roles (section, container
|
|
585
|
+
"body": "# Etch structure\n\nThe owner's rules for the structure of a site built in Etch: the content model, 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## Content model first\n\n- A system or page that repeats follows Etch's templates. Two or more pages that do one job (docs, a blog, a changelog, legal pages, services) are a custom post type with an archive and a single template, never a row of Pages. The Pages section stays short.\n- The index template holds the header and footer components around `main` with Post Content; every other template places the same two components.\n- Etch's own post types and fields first; ACF when the project's complexity needs it. Load content-model for the roles and the data-bind and `data-loop=\"main\"` marks.\n\n## Flat BEM names\n\n- Block `hero`, element `hero__heading`, modifier `featured-card--highlighted`, for true visual variants only.\n- One level deep: `featured__title`, never `featured__header__title`, however deep the markup.\n- A repeating component is its own block, not an element of its section: a card in the featured section is `featured-card` with `featured-card__title`, never `featured__card`.\n- No prefix of our own (the export adds the project's), but avoid generic single words a theme or plugin might also use, such as card or grid. Give them a second word: `service-card`.\n- Structural roles (section, container) and ACSS classes never get a BEM class of ours.\n- Name parts the same way everywhere: a section's heading is `__heading`, the text under it `__lede`, a card's text `__description`, an image and its wrapper `__media` and `__media-wrapper`. Rename a class and its name in the builder together.\n\n## The structure Etch expects\n\n- `section` is full bleed and always carries the block class.\n- `container` is the width-constrained inner wrapper, `__inner` by default. Borders and edges that line up with the content go here, never on the full-bleed section.\n- Child zones doing real layout work are plain `div` elements with a class of their own, named with a `-wrapper` suffix. Etch's `flex-div` is deprecated: never build with it.\n- Use the most semantic element available: figure, article, ul, nav.\n- Collapse any wrapper with no CSS of its own.\n- A set of repeated things is a ul with li children, and a card component's root is the li.\n- A card's title is a real heading with the link inside it, never the whole card wrapped in a link. Make the heading level a property, h3 by default.\n- Write the HTML in reading order and set the visual order with CSS (order, grid areas), never the other way round.\n\n## Components\n\n- A section component's root is the section itself, with its block class and a property that picks its context, for example `bg--dark` or `bg--light`.\n- Never nest a section component inside another section component. Cards inside a list are fine.\n- Extra content one page needs inside a shared component is a slot, not a property.\n- Leave a property blank on an instance when the default is right. A typed value pins it, and later changes to the default no longer reach that page.\n- Label select options for the decision, not the mechanism: \"Lede beside the heading\", not \"two-thirds and one-third\". Fewer options mean fewer inconsistencies.\n- Delete classes and components that stop doing work, with their style records.\n- Dynamic data stays dynamic: nothing about a CMS item is typed onto a page. Company details (name, phone, email, address, social links) bind to one source, an options page or a one-record JSON loop; ask which exists before typing any.\n\n## Accessibility defaults\n\n- One h1 per page, on the hero. Every section opens with an h2, and no level is skipped.\n- Every image has a real src, alt (empty when decorative), width, height, loading and decoding.\n- Landmarks: header, nav with an aria-label, main with the id the skip link points at, footer.\n- Icon-only buttons get an aria-label; decorative SVG gets `aria-hidden=\"true\"`.\n- Name a section landmark with a short aria-label rather than aria-labelledby pointing at a long heading.\n- On a phone, h5 and h6 are body sizes, so h4 is the smallest reliable heading."
|
|
454
586
|
},
|
|
455
587
|
"etch-css": {
|
|
456
588
|
"id": "etch-css",
|
|
@@ -464,7 +596,7 @@ export const SKILL_BODIES = {
|
|
|
464
596
|
"title": "Etch Connector runtime",
|
|
465
597
|
"kind": "build",
|
|
466
598
|
"when": "Load before driving an Etch tab through the Etch Connector: editing components, classes, loops or data, saving, navigating, or working on Etch Studio.",
|
|
467
|
-
"body": "# Etch Connector runtime\n\nFacts about the Etch runtime that cost time to discover, for an agent driving the Etch Connector after a SpecShot build. Read etch-development first, and Etch's own guide for agents (https://docs.etchwp.com/etch-connector/ai-agent-guide) when a method is in doubt.\n\n## Components and classes\n\n- Read a component with `etch.components.getJson(id)` and patch it with `updateAsync(id, { blocks })`. Strip id and parentId from each block but keep every styles array, which is what links classes: `styles: []` drops the class attribute.\n- A class
|
|
599
|
+
"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 links through the block's styles array, set only when the block is made (create, replace, paste). `addClass` or an attribute edit later links nothing, so no CSS prints. Put classes in the JSON you create; to add one later, use `blocks.replace`.\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- 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.\n- The tab disconnects when the builder reloads or navigates by hand. Wait, check `tabs` and retry.\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.\n- If a safety check refuses a script that deletes blocks on shared templates, hand the owner the command; never reshape it to get past the check.\n\n## Templates, types and loops\n\n- No public API call creates a post type, taxonomy or template on WordPress; the SpecShot plugin makes them, then the builder fills them.\n- An archive, category or search template loops the Main Query (`mainQuery`); a list on an ordinary page is a WP Query loop over the type, never a JSON copy of posts.\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.\n- Data resolves at build time. Stale data on a deployed site means deploy again; say so plainly to a client.\n- Deploying is the owner's.\n- Studio publishes only the assets the build references directly. A CSS url() to an asset fails, so use a percent-encoded data URI for small icons in CSS.\n- Never put JavaScript in an etch/raw-html block on Studio, where braces are read as data expressions. Page scripts go in a component's script.\n- Check that ACSS's on-visible effects animate on the deployed site. If elements stay invisible, the effects script is missing."
|
|
468
600
|
},
|
|
469
601
|
"etch-connector-gotchas": {
|
|
470
602
|
"id": "etch-connector-gotchas",
|
|
@@ -472,5 +604,12 @@ export const SKILL_BODIES = {
|
|
|
472
604
|
"kind": "build",
|
|
473
605
|
"when": "Load before editing an Etch page through the Etch Connector after a SpecShot build: the script cadence, where CSS really ships, the classes a save drops, and how to verify.",
|
|
474
606
|
"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."
|
|
607
|
+
},
|
|
608
|
+
"smooth-motion": {
|
|
609
|
+
"id": "smooth-motion",
|
|
610
|
+
"title": "Smooth motion",
|
|
611
|
+
"kind": "foundation",
|
|
612
|
+
"when": "Load before adding a reveal, a scroll effect, a page transition, a looping figure or a blur to a built site, and when a page feels slow, rough or janky.",
|
|
613
|
+
"body": "# Smooth motion\n\nHow a built site should feel in the hand: scroll that glides, reveals that arrive without a jolt, and no dropped frames. On the site the owner measured, smoothness came from two things, small fast reveals and a light page, and never from more animation. The motion skill says what moves. This one says what moving costs and how a reveal should feel.\n\n## 1. The frame budget\n\n- The screen sets the frame rate, not the site. Every frame's main-thread work fits 8.3ms, one frame at 120Hz.\n- Measure on a CPU slowed four times, about a mid-range phone: at most 10% late frames (over 33ms) while scrolling, none while idle.\n- Measure before and after every change, run each variant twice and compare like with like. Scroll a probe with `behavior: \"instant\"`: a smooth-scroll setting makes a slow page look fast.\n- Headless paint numbers run pessimistic, because the raster is software. Trust the style and script numbers.\n\n## 2. What may move\n\n- Animate `transform`, `translate`, `scale`, `rotate` and `opacity` only. Never `color`, `background-color`, `box-shadow`, `filter`, `top`, `left`, `inset`, `width` or `height`, and never a registered custom property on a loop. To change a color in motion, cross-fade two layers.\n- Nothing loops forever unless it is transform or opacity: a marquee, a slow rotation, a pulse of scale. A color cycle runs once and rests. A decorative spin runs on hover or focus only.\n- No script writes a style on every scroll frame: not a custom property on `html`, `main` or a section, not `inset`, not a variable per item. A scroll effect runs on a CSS `scroll()` or `view()` timeline, off the main thread, in the safe form the motion skill shows: inside `@media screen and (prefers-reduced-motion: no-preference)` and `@supports (animation-timeline: view())`. A script is only the fallback behind `!CSS.supports(\"animation-timeline: scroll()\")`, and then it writes to the one element that reads the value, skips a value that did not change, and reads every rect before it writes any.\n- A custom property written on a large container restyles everything inside it, every frame. One page went from 87% late frames to 20% when that write moved to a scroll timeline.\n- An animated drawing moves a few grouped paths, never dozens of lines rewritten each frame. Labels over it move with `transform`, never with `top` or `left`.\n\n## 3. Reveals that feel smooth\n\n- One-shot and time-based. Never scroll-scrubbed opacity on content.\n- Reveal meaningful chunks: a card, a heading with its text, an image, a short list as one unit. Nothing smaller than about 3.5rem moves on its own. A page of many tiny moving pieces reads as rough even when every frame is on time.\n- Start a reveal as the item enters the screen, not deep into it, and keep the cascade short: about 70ms between items and at most six in a batch. A late trigger with a long cascade reads as a page that loads slowly.\n- The feel the owner approved: opacity over about 700ms and a rise of 1.5 to 2rem over about 1000ms on an ease-out, and an image inside a card settling from a scale of 1.06. A large rise, a scale and a steep curve together read as a jolt. A rise of about 1rem read as too little.\n- Hidden is never the default. Content on screen at load is never hidden, a page without script shows everything, print shows everything, and an item still waiting when the scroll reaches the bottom of the page is revealed there.\n- Leave carousels, tickers and sliders out of reveals: an off-screen slide never enters the screen and would stay invisible.\n- Reveals sit under `prefers-reduced-motion: no-preference`, as the design law requires, and the page is whole without them. On an Automatic.css site, its reduce-motion option prints a global override that snaps every transition when reduced motion is on: know which way the site is set before you judge a reveal.\n\n## 4. The heavy things\n\n- Blur (`backdrop-filter`) only on the header, menus, drawers and dialogs. Never on anything over or beside moving content (a video, a slider, a panning image, an animated figure, a rotating word): the blur is computed again every frame. Taking two small blurs off one hero took it from 66 to 95% late frames to under 2%. Use a slightly stronger translucent fill instead.\n- Find the expensive rule, not the big file. One small stylesheet of `:nth-child(... of :has(...))` rules cost every page a whole-document restyle while styling nothing on any of them. Never ship `:nth-child(... of :has(...))`, `:has()` on `html` or `body`, or a counter on `body`.\n- Every stylesheet printed on every page makes every small style change more expensive. Keep each style with its class and retire stylesheets nothing uses.\n- Never run an animation on an element taller than the screen: it becomes a giant layer on the graphics card.\n- Keep motion scripts small and inline, with no animation library downloaded for what CSS can do.\n\n## 5. Between pages and parts\n\n- Page transitions use cross-document view transitions (`@view-transition { navigation: auto; }`): the old page fades in about 160ms, the new one rises 0.5rem in about 240ms, and the header stays pinned.\n- An accordion slides with `::details-content` and `interpolate-size: allow-keywords` in about 280ms, never with a script setting its height.\n- Interface states (hover, press, focus) take 120 to 240ms.\n\n## Check before you ship a section\n\n- Motion is transform and opacity only, states take 120 to 240ms, reveals 1000ms at most, on an ease-out with no bounce.\n- No script writes styles on scroll, and every scroll effect is a CSS timeline behind a supports check.\n- Items sit in a grid or flex container so they cascade, and carousels are left out of reveals.\n- Checked with reduced motion on and off, with script off, at the bottom of the page and in print.\n- Measured at 390 and 1440 wide on a slowed CPU: at most 10% late frames scrolling and none idle, with both themes looked at."
|
|
475
614
|
}
|
|
476
615
|
};
|