@scayver/specshot-mcp-server 0.14.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 +53 -10
- package/dist/build-standard.js +135 -58
- package/dist/client.js +53 -3
- package/dist/index.js +28 -3
- package/dist/skills.js +156 -43
- package/dist/tool-descriptions.js +62 -13
- 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 +23 -1
- package/dist/tools/etch-ai.js +37 -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 +30 -4
- package/dist/tools/site.js +23 -0
- package/dist/tools/skills.js +25 -7
- 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,223 +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, image spot, hero visual, figure, 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 layout or building any grid, and when a page reads as a run of identical bands."
|
|
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, reveal, hover state, floating figure, marquee, animated chart or signature interaction."
|
|
154
|
+
"when": "Load before adding any transition, entrance, reveal, hover state, floating figure, marquee, animated chart or signature interaction.",
|
|
155
|
+
"parts": 1
|
|
135
156
|
},
|
|
136
157
|
{
|
|
137
158
|
"id": "copywriting",
|
|
138
159
|
"title": "Website copy that converts",
|
|
139
160
|
"kind": "foundation",
|
|
140
|
-
"when": "Load before writing or rewriting any words on a page: headlines, sections, calls to action, proof, forms and messages."
|
|
161
|
+
"when": "Load before writing or rewriting any words on a page: headlines, sections, calls to action, proof, forms and messages.",
|
|
162
|
+
"parts": 1
|
|
141
163
|
},
|
|
142
164
|
{
|
|
143
165
|
"id": "seo",
|
|
144
166
|
"title": "On-page SEO and AI search visibility",
|
|
145
167
|
"kind": "foundation",
|
|
146
|
-
"when": "Load before designing any page, and before writing its headings, links, image text or FAQ."
|
|
168
|
+
"when": "Load before designing any page, and before writing its headings, links, image text or FAQ.",
|
|
169
|
+
"parts": 1
|
|
147
170
|
},
|
|
148
171
|
{
|
|
149
172
|
"id": "accessibility",
|
|
150
173
|
"title": "Accessibility",
|
|
151
174
|
"kind": "foundation",
|
|
152
|
-
"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
|
|
153
177
|
},
|
|
154
178
|
{
|
|
155
179
|
"id": "responsive",
|
|
156
180
|
"title": "Responsive behavior",
|
|
157
181
|
"kind": "foundation",
|
|
158
|
-
"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
|
|
159
191
|
},
|
|
160
192
|
{
|
|
161
193
|
"id": "etch-acss-build",
|
|
162
194
|
"title": "The Etch and ACSS build",
|
|
163
195
|
"kind": "build",
|
|
164
|
-
"when": "Load before building any page or section that will go to Etch, which is every SpecShot design, and before running get_etch_build."
|
|
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
|
|
165
205
|
},
|
|
166
206
|
{
|
|
167
207
|
"id": "agency-process",
|
|
168
208
|
"title": "The agency process",
|
|
169
209
|
"kind": "page",
|
|
170
|
-
"when": "Load at the start of any client project, before starting or finishing a phase, and before anything is drafted for a client."
|
|
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
|
|
171
212
|
},
|
|
172
213
|
{
|
|
173
214
|
"id": "discovery-interview",
|
|
174
215
|
"title": "The discovery interview",
|
|
175
216
|
"kind": "page",
|
|
176
|
-
"when": "Load when the owner says new client or start discovery, before interviewing anyone about a client, a project or its brief."
|
|
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
|
|
177
219
|
},
|
|
178
220
|
{
|
|
179
221
|
"id": "copy-and-wireframe",
|
|
180
222
|
"title": "Copy and wireframe",
|
|
181
223
|
"kind": "page",
|
|
182
|
-
"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
|
|
183
226
|
},
|
|
184
227
|
{
|
|
185
228
|
"id": "design-for-acss",
|
|
186
229
|
"title": "Design for ACSS",
|
|
187
230
|
"kind": "foundation",
|
|
188
|
-
"when": "Load when the owner says start design, before the Design Direction board, and before designing any page from an approved wireframe."
|
|
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
|
|
189
233
|
},
|
|
190
234
|
{
|
|
191
235
|
"id": "section-authorship",
|
|
192
236
|
"title": "Section authorship",
|
|
193
237
|
"kind": "page",
|
|
194
|
-
"when": "Load before planning or reviewing the sections of any page: each section's job, its anchor and its archetype, and the rules that keep a page from repeating itself."
|
|
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
|
|
195
240
|
},
|
|
196
241
|
{
|
|
197
242
|
"id": "design-qa-gate",
|
|
198
243
|
"title": "Design QA gate",
|
|
199
244
|
"kind": "page",
|
|
200
|
-
"when": "Load before calling a page done or handing it to a client: the per-page checks, content stress cases, media rules and performance budgets, each with its evidence."
|
|
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
|
|
201
247
|
},
|
|
202
248
|
{
|
|
203
249
|
"id": "etch-development",
|
|
204
250
|
"title": "Etch development",
|
|
205
251
|
"kind": "build",
|
|
206
|
-
"when": "Load when the owner says start development, before building an approved design into Etch, and before driving an Etch tab through the Etch Connector."
|
|
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
|
|
207
254
|
},
|
|
208
255
|
{
|
|
209
256
|
"id": "etch-structure",
|
|
210
257
|
"title": "Etch structure",
|
|
211
258
|
"kind": "build",
|
|
212
|
-
"when": "Load before writing the markup of any page or section that goes to Etch, and before changing structure in Etch through the Etch Connector."
|
|
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
|
|
213
261
|
},
|
|
214
262
|
{
|
|
215
263
|
"id": "etch-css",
|
|
216
264
|
"title": "Etch CSS",
|
|
217
265
|
"kind": "build",
|
|
218
|
-
"when": "Load before writing or changing styles in Etch, by hand or through the Etch Connector, and before choosing a button or a variable on an ACSS site."
|
|
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
|
|
219
268
|
},
|
|
220
269
|
{
|
|
221
270
|
"id": "etch-connector-runtime",
|
|
222
271
|
"title": "Etch Connector runtime",
|
|
223
272
|
"kind": "build",
|
|
224
|
-
"when": "Load before driving an Etch tab through the Etch Connector: editing components, classes, loops or data, saving, navigating, or working on Etch Studio."
|
|
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
|
|
225
275
|
},
|
|
226
276
|
{
|
|
227
277
|
"id": "etch-connector-gotchas",
|
|
228
278
|
"title": "Etch Connector gotchas",
|
|
229
279
|
"kind": "build",
|
|
230
|
-
"when": "Load before editing an Etch page through the Etch Connector after a SpecShot build: the script cadence, where CSS really ships, the classes a save drops, and how to verify."
|
|
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"
|
|
231
323
|
}
|
|
232
324
|
],
|
|
233
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.",
|
|
@@ -236,7 +328,7 @@ export const SKILL_LIST = {
|
|
|
236
328
|
"revision": "revise_a_page",
|
|
237
329
|
"section": "rebuild_from_capture"
|
|
238
330
|
},
|
|
239
|
-
"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."
|
|
240
332
|
};
|
|
241
333
|
/** Every get_skill answer, by id, exactly as the hosted tool gives it. */
|
|
242
334
|
export const SKILL_BODIES = {
|
|
@@ -385,7 +477,7 @@ export const SKILL_BODIES = {
|
|
|
385
477
|
"title": "Motion and animation",
|
|
386
478
|
"kind": "foundation",
|
|
387
479
|
"when": "Load before adding any transition, entrance, reveal, hover state, floating figure, marquee, animated chart or signature interaction.",
|
|
388
|
-
"body": "# Motion and animation\n\nThe owner rated a still page 10 out of 100. A page is alive: it settles on load, its sections arrive as they scroll in, its figures move, and everything answers the pointer. It is also smooth: nothing jumps, nothing lags, and with motion switched off the page is whole.\n\n## Tokens\n\n- `--ease-out: cubic-bezier(0.16, 1, 0.3, 1)` for entrances and interface motion. `--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1)` for a floating figure.\n- `--dur-1` 150ms press, `--dur-2` 240ms hover and focus, `--dur-3` 400ms a panel, `--dur-4` 700ms entrances, `--dur-5` 1200ms a figure drawing in, `--stagger` 80ms.\n- Never bounce, overshoot or elastic. Never linear for interface motion: linear only for a marquee or a continuous rotation.\n\n## 1. The load entrance\n\nThe hero's heading, text, actions and visual enter in sequence, each over `--dur-4`, staggered by `--stagger` through a `--i` index. The floating chips arrive last.\n\n```css\n@media (prefers-reduced-motion: no-preference) {\n .hero__copy > * { animation: hero-copy-settle var(--dur-4) var(--ease-out) both; animation-delay: calc(var(--i, 0) * var(--stagger)); }\n}\n@keyframes hero-copy-settle { from { opacity: 0; transform: translateY(1.25rem); } }\n```\n\n## 2. Scroll reveals, in the safe form only\n\n```css\n@media screen and (prefers-reduced-motion: no-preference) {\n @supports (animation-timeline: view()) {\n .bento__tile { animation: bento-tile-rise var(--ease-out) both; animation-timeline: view(); animation-range: entry 5% entry 60%; }\n }\n}\n@keyframes bento-tile-rise { from { opacity: 0; transform: translateY(2.5rem) scale(0.97); } }\n```\n\n- The base style is visible. The hidden look lives only in the keyframe's from block, so a print, a capture, a canvas frame and an older browser show the finished page.\n- Each section reveals its own way: a rise, a scale-in, a slide from the side the content sits on, children staggered by `--i`. Never one reveal on every section, never linear, and never a class that hides content until a script adds another.\n\n## 3. Moving figures, two to four\n\n- A floating chip or card: translateY 6 to 12px, 5 to 9s, `--ease-in-out`, alternate, infinite.\n- A chart line that draws itself: `stroke-dashoffset` over `--dur-5`, once, then holds.\n- A slow orbit of a ring around the hero visual: 20 to 40s, linear.\n- A bar or progress fill that grows to its value on reveal, with `transform: scaleX()`.\n- A marquee band of the client's real names: the second copy `aria-hidden=\"true\"`, the edges masked, 30 to 60s, paused on hover and on focus-within.\n- Every figure shows something from the page: a panel, a labeled chart, a flow from the copy. Never an abstract blob, and never a loop under 4 seconds on anything but a loader.\n\n```css\n@media (prefers-reduced-motion: no-preference) {\n .hero__chip { animation: hero-chip-float 7s var(--ease-in-out) infinite alternate; }\n .marquee__track { animation: marquee-track-slide 40s linear infinite; }\n .marquee:hover .marquee__track, .marquee:focus-within .marquee__track { animation-play-state: paused; }\n}\n@keyframes hero-chip-float { to { transform: translateY(-10px); } }\n@keyframes marquee-track-slide { to { transform: translateX(-50%); } }\n```\n\n## 4. The interaction system\n\n- Buttons lift 1 to 2px on hover and press to `scale(0.98)`.\n- Cards and tiles lift 4px while a pseudo-element carrying `--shadow-2` fades in. Never animate box-shadow itself.\n- An image in a frame scales to 1.04 on hover over `--dur-4`. Links draw their underline with `scaleX`.\n- Every focusable element shows a 2px accent ring at a 2px offset on `:focus-visible`.\n\n## 5. Smoothness\n\n- Every state change has a transition. Nothing faster than 150ms, and no entrance slower than 1200ms.\n- Animate transform and opacity only. Never width, height, top, left, margin, padding, box-shadow or filter.\n- Name each keyframe for what it serves, never a bare fadeIn: names are global on the client's site.\n- Every animation sits under `prefers-reduced-motion: no-preference`, or a reduce block names its selectors. Never a global reset on `*`.\n\n## Check before you save\n\n- Does the hero settle on load, does each section reveal its own way, and do two to four figures move?\n- Is every reveal in the safe form, with the page whole when motion is off?\n- Does every button, card and link answer hover, press and focus?"
|
|
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?"
|
|
389
481
|
},
|
|
390
482
|
"copywriting": {
|
|
391
483
|
"id": "copywriting",
|
|
@@ -415,12 +507,26 @@ export const SKILL_BODIES = {
|
|
|
415
507
|
"when": "Load before building any page, and for the responsive pass before saving: SpecShot's frame is dragged to every width.",
|
|
416
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?"
|
|
417
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
|
+
},
|
|
418
517
|
"etch-acss-build": {
|
|
419
518
|
"id": "etch-acss-build",
|
|
420
519
|
"title": "The Etch and ACSS build",
|
|
421
520
|
"kind": "build",
|
|
422
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.",
|
|
423
|
-
"body": "# The Etch and ACSS build\n\nEvery SpecShot design has to build into Etch with nothing lost. When the page is written the way the export reads it, the agency gets something they can edit in Etch rather than something they rebuild.\n\n## Write it the way Etch reads it\n\n- One class per rule, named in BEM: `.block`, `.block__element`, `.block--modifier`. States and pseudo-elements on that class are fine. A single-class rule becomes an Etch class style the agency can find and edit; `.hero h1` or `section > div` ends up as a page-level rule nobody can find.\n-
|
|
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"
|
|
424
530
|
},
|
|
425
531
|
"agency-process": {
|
|
426
532
|
"id": "agency-process",
|
|
@@ -434,7 +540,7 @@ export const SKILL_BODIES = {
|
|
|
434
540
|
"title": "The discovery interview",
|
|
435
541
|
"kind": "page",
|
|
436
542
|
"when": "Load when the owner says new client or start discovery, before interviewing anyone about a client, a project or its brief.",
|
|
437
|
-
"body": "# The discovery interview\n\nHow to run discovery as a conversation, and how the answers become the project's brief in SpecShot. The brief is the source of truth for every later phase.\n\n## Before the first question\n\n- Establish the project (list_projects, then get_project_state) and read what exists: get_project_intelligence, and the client's own answers to the portal questionnaire (get_discovery_answers). Never ask again what the client already answered; confirm it or ask what changed.\n- Ask whether you are talking to the business owner or to someone relaying the client's answers. It changes how hard to push, and pushing a client directly is the owner's call.\n\n## How to ask\n\n- One to three related questions per turn, then wait. Never paste the question list, and never answer your own question.\n- Answers often arrive long, because many people dictate. Read each one fully before moving on; most of the next questions are already answered in it.\n- Refuse vague answers. \"Professionals\", \"high quality\" and \"we care more\" are not answers: ask for a name, a number, a real customer, a sentence someone actually said.\n- When a word you were given does not parse, ask rather than guess.\n- When the owner hedges (\"I think\", \"about\", \"I'd have to check\"), it is not a fact. Record it as unverified and say so.\n- Do not ask about timelines or budget. By discovery the money is settled, and discovery is input for the marketing, the copy and the design only.\n\n## What to cover, in the questionnaire's order\n\n1. Goals: what the site has to do, what a convinced visitor does next, how the client will know it worked.\n2. The offer: what they sell in a customer's words, what to push hardest, who they do not want.\n3. The audience: the best customer, their problem, the main objection, words a customer actually used, who signs off.\n4. The market: two or three competitors, and why someone picks this business over them.\n5. The pages the site needs, and what each one must do.\n6. The brand: three words for how it should come across, a site they love and one they cannot stand, the logo, colors and fonts they have, anything off-limits.\n7. Proof: named results, real numbers, photos and documents, and anything they may not legally say.\n\n## A new client\n\nBefore the first project of a new client,
|
|
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."
|
|
438
544
|
},
|
|
439
545
|
"copy-and-wireframe": {
|
|
440
546
|
"id": "copy-and-wireframe",
|
|
@@ -476,7 +582,7 @@ export const SKILL_BODIES = {
|
|
|
476
582
|
"title": "Etch structure",
|
|
477
583
|
"kind": "build",
|
|
478
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.",
|
|
479
|
-
"body": "# Etch structure\n\nThe owner's rules for the structure of a site built in Etch: class names, the elements Etch expects, components and accessibility. They hold for the SpecShot design that goes to Etch and for every change made in Etch afterward. The export contract (tokens, the project prefix, the ACSS map) is etch-acss-build, and how a design marks its components, slots and loops follows the build law (docs/BUILD-LAW.md in the SpecShot repository, and the structure part of the design law the design_law prompt serves).\n\n## Flat BEM names\n\n- Block `hero`, element `hero__heading`, modifier `featured-card--highlighted`, for true visual variants only.\n- One level deep: `featured__title`, never `featured__header__title`, however deep the markup.\n- A repeating component is its own block, not an element of its section: a card in the featured section is `featured-card` with `featured-card__title`, never `featured__card`.\n- No prefix of our own (the export adds the project's), but avoid generic single words a theme or plugin might also use, such as card or grid. Give them a second word: `service-card`.\n- Structural roles (section, container) and ACSS classes never get a BEM class of ours.\n- Name parts the same way everywhere: a section's heading is `__heading`, the text under it `__lede`, a card's text `__description`, an image and its wrapper `__media` and `__media-wrapper`. Rename a class and its name in the builder together.\n\n## The structure Etch expects\n\n- `section` is full bleed and always carries the block class.\n- `container` is the width-constrained inner wrapper, `__inner` by default. Borders and edges that line up with the content go here, never on the full-bleed section.\n- Child zones doing real layout work are plain `div` elements with a class of their own, named with a `-wrapper` suffix. Etch's `flex-div` is deprecated: never build with it.\n- Use the most semantic element available: figure, article, ul, nav.\n- Collapse any wrapper with no CSS of its own.\n- A set of repeated things is a ul with li children, and a card component's root is the li.\n- A card's title is a real heading with the link inside it, never the whole card wrapped in a link. Make the heading level a property, h3 by default.\n- Write the HTML in reading order and set the visual order with CSS (order, grid areas), never the other way round.\n\n## Components\n\n- A section component's root is the section itself, with its block class and a property that picks its context, for example `bg--dark` or `bg--light`.\n- Never nest a section component inside another section component. Cards inside a list are fine.\n- Extra content one page needs inside a shared component is a slot, not a property.\n- Leave a property blank on an instance when the default is right. A typed value pins it, and later changes to the default no longer reach that page.\n- Label select options for the decision, not the mechanism: \"Lede beside the heading\", not \"two-thirds and one-third\". Fewer options mean fewer inconsistencies.\n- Delete classes and components that stop doing work, with their style records.\n- Dynamic data stays dynamic: nothing about a CMS item is typed onto a page. Company details (name, phone, email, address, social links) bind to one source, an options page or a one-record JSON loop; ask which exists before typing any.\n\n## Accessibility defaults\n\n- One h1 per page, on the hero. Every section opens with an h2, and no level is skipped.\n- Every image has a real src, alt (empty when decorative), width, height, loading and decoding.\n- Landmarks: header, nav with an aria-label, main with the id the skip link points at, footer.\n- Icon-only buttons get an aria-label; decorative SVG gets `aria-hidden=\"true\"`.\n- Name a section landmark with a short aria-label rather than aria-labelledby pointing at a long heading.\n- On a phone, h5 and h6 are body sizes, so h4 is the smallest reliable heading."
|
|
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."
|
|
480
586
|
},
|
|
481
587
|
"etch-css": {
|
|
482
588
|
"id": "etch-css",
|
|
@@ -490,7 +596,7 @@ export const SKILL_BODIES = {
|
|
|
490
596
|
"title": "Etch Connector runtime",
|
|
491
597
|
"kind": "build",
|
|
492
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.",
|
|
493
|
-
"body": "# Etch Connector runtime\n\nFacts about the Etch runtime that cost time to discover, for an agent driving the Etch Connector after a SpecShot build. Read etch-development first, and Etch's own guide for agents (https://docs.etchwp.com/etch-connector/ai-agent-guide) when a method is in doubt.\n\n## Components and classes\n\n- Read a component with `etch.components.getJson(id)` and patch it with `updateAsync(id, { blocks })`. Strip id and parentId from each block but keep every styles array, which is what links classes: `styles: []` drops the class attribute.\n- A class
|
|
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."
|
|
494
600
|
},
|
|
495
601
|
"etch-connector-gotchas": {
|
|
496
602
|
"id": "etch-connector-gotchas",
|
|
@@ -498,5 +604,12 @@ export const SKILL_BODIES = {
|
|
|
498
604
|
"kind": "build",
|
|
499
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.",
|
|
500
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."
|
|
501
614
|
}
|
|
502
615
|
};
|