@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/build-standard.js
CHANGED
|
@@ -5,15 +5,17 @@
|
|
|
5
5
|
// which fails whenever the two differ. To regenerate after changing the source:
|
|
6
6
|
// cd apps/web && SPECSHOT_WRITE_GENERATED=1 npx vitest run src/lib/__tests__/mcp-stdio-sync.test.ts
|
|
7
7
|
/** The connect-time instructions: the design law on one screen, then the short workflow and the skills. */
|
|
8
|
-
export const CONNECT_INSTRUCTIONS = `
|
|
8
|
+
export const CONNECT_INSTRUCTIONS = `BEFORE ANY WORK ON A PROJECT: call get_agent_briefing with its projectId and read every entry it lists, every part, with get_skill: the process, the design law, the clean Etch build and the skills for the project's stage. Read it again when its knowledgeVersion changes.
|
|
9
|
+
|
|
10
|
+
Build full-fidelity, approvable website designs, never gray placeholders or bare skeletons. SAVE WHOLE PAGES, never a lone section or component: header, every section in order, footer. Assemble the page, then save it once: every save REPLACES the page, so saving only the part you changed deletes the rest. Read the project first (get_wireframe_context): use its real brand tokens, approved copy, and references. Its brief opens with CLIENT RULES, the client's and the agency's own instructions: follow every one. They beat every default here, never the boundary against copying another company's work or the anti-slop bans. STUDY every inspiration image before you build. Real SVG icons, the client's light or dark choice (both when unset), WCAG AA. FLUID RESPONSIVE IS THE LAW: correct at EVERY width, not three: clamp() type and space, auto-fit grids, min-width:0 on flex and grid children, container queries for components. NO AI TELLS: no Inter, Roboto, Arial, Geist, Fraunces, Plus Jakarta Sans or Space Grotesk by reflex (faces from the brand, then the references), no italic serif hero, no label above a heading by reflex, no purple-to-cyan gradient, no radial glow, never pure #000/#fff, no gray-on-color, no gradient text, no side-tab border, no cards nested in cards, no row of equal cards, no bounce easing, no emoji icons, no semicolons or em dashes in copy. Design every state (hover, focus, loading, empty, error) on its component, and show only the default state on the page. Inline all CSS and fonts: the preview strips external ones and runs no script. REAL IMAGES come from one source only: a placeableUrl in get_wireframe_context, on the client's own assets and the project's generated images. A reference captured from somebody else's page has placeableUrl null on purpose: study it and BUILD the section, never ship a picture of another company's page. Any other image URL is still stripped to a gray box. NUMBERS: body text at least 1rem, UI text never under 0.6875rem, line-height 1.5-1.7, 65-75 characters per line, at least a 1.25 type scale, headlines 2-3 lines, dvh never vh, touch targets at least 2.75rem. NEVER a placeholder comment in place of markup: a page with "rest of sections here" where its footer belongs is broken. PREMIUM AND ALIVE: a different layout per section and a bento on a home page, one content edge, one theme, a layered hero visual with a floating chip, imagery in the hero and two more sections (image spots with data-ss-image, data-ss-aspect and data-ss-alt over a drawn fallback, never a shape-built scene or grain), layered --shadow-1 to --shadow-4, embedded fonts, a load entrance, safe scroll reveals (@media screen, no-preference, @supports), two to four slow moving figures, lift, press and focus, transform and opacity only, headings that make claims. Call the premium_craft prompt before building, and the build_a_page prompt for the full standard.
|
|
9
11
|
|
|
10
12
|
TOKENS: one :root block with the canonical names, every value read as var(--name, literal). Type --step--1 to --step-6 and space --space-3xs to --space-3xl, each a clamp() from 360px to 1440px. Section padding is --pad-open or --pad-dense only, equal above and below; --gutter, --content, --measure; --radius-s/m/l/pill; --shadow-1 to --shadow-4 (layered); --dur-1 to --dur-5, --stagger, --ease-out, --ease-in-out; color roles --paper, --paper-2, --ink, --ink-2, --ink-3, --line, --accent (+ -hover, -quiet), --on-accent, --night, --on-night; faces --font-display and --font-text from the brand, then the references. No raw px or hex outside :root. Fluid first: a breakpoint only where the layout truly changes.
|
|
11
13
|
|
|
12
|
-
STRUCTURE: anything repeated twice or more (cards, tiers, FAQ items
|
|
14
|
+
CONTENT MODEL FIRST: two or more pages that do one job (docs, blog, changelog, legal, services) are a content type, never plain Pages. A type's single design marks data-bind="title", data-bind="field:<key>" and data-bind="content" on the body; its archive puts data-loop="main" on its list with one card. The header and footer are kit components. STRUCTURE: anything repeated twice or more (cards, tiers, FAQ items) is a component: data-component="PricingTier" (PascalCase) on each instance's root, data-prop="title" (camelCase) on what varies (data-prop-type url, image, boolean with data-prop-class, or attr with data-prop-attr), data-slot="actions" on child content that differs, data-optional on a prop some instances leave empty, and data-loop="tiers" on the container of a list of instances. Everything unmarked is identical in every instance. One BEM block per component (.pricing-tier), states as .block.is-open, no invented utilities, no inline styles, no layout that depends on position. Fluid: never px font sizes, @media only for page layout, no fixed widths over 20rem, text capped in ch, img with width and height or aspect-ratio. Components read semantic tokens, never raw values.
|
|
13
15
|
|
|
14
|
-
ETCH-READY: one class per rule with BEM names (block__element--modifier), no tag selectors inside @supports, @container or @layer, keyframes named for their block (chart-grow, never fadeIn), dark theme
|
|
16
|
+
ETCH-READY: one class per rule with BEM names (block__element--modifier), no tag selectors inside @supports, @container or @layer, keyframes named for their block (chart-grow, never fadeIn), dark theme by prefers-color-scheme or a class on the section (never :root[data-theme]), no html font-size, no #id selectors, no !important outside reduced motion, tokens declared once in :root with the canonical names (never write ACSS names by hand: the export maps them), sections side by side in main, one container each, never wrapped or nested. Flat BEM one level deep (never a__b__c), a repeated card its own block (.service-card) whose title heading holds its link (no Read more links), one custom media name per @media, no :has() inside :has(), @keyframes at the top level, SVG data URIs percent-encoded (%3Csvg), single quotes inside Etch expressions.
|
|
15
17
|
|
|
16
|
-
LAW CHECK: every save returns designLaw (score 0 to 100, findings with code, severity and fix). BLOCK, clear slop or a sure Etch break to fix before anything is called ready: emoji-icon, placeholder-image, placeholder-copy, text-contrast, fluid-type (no fluid type at all), grain, hidden-reveal, etch-custom-media, etch-expression-quotes. WARN: fluid-space, token-density, off-token-color, radius-sprawl, generic-gradient, center-everything, border-and-shadow, nested-cards, side-tab, eyebrow-sprawl, buzzwords, form-controls, pure-black-white, broad-will-change, mask-without-size, custom-cursor, italic-serif-hero, banned-face, svg-scene, radial-glow, dark-section, equal-cards, section-spacing, same-entrance, reveal-form, marquee, endless-animation, linear-easing, layout-motion, global-motion-reset, image-loading, unsourced-claim (a claim the brief does not give: mark it [GAP: what is missing], or [UNVERIFIED: what] when stated but unconfirmed), px-font-size, fixed-width, tap-target, image-ratio, repeated-structure, component-drift, loop-items, structure-scope, structure-names, component-block, component-tokens, invented-utility, inline-style,
|
|
18
|
+
LAW CHECK: every save returns designLaw (score 0 to 100, findings with code, severity and fix). BLOCK, clear slop or a sure Etch break to fix before anything is called ready: emoji-icon, placeholder-image, placeholder-copy, text-contrast, fluid-type (no fluid type at all), grain, hidden-reveal, etch-custom-media, etch-expression-quotes. WARN: fluid-space, token-density, off-token-color, radius-sprawl, generic-gradient, center-everything, border-and-shadow, nested-cards, side-tab, eyebrow-sprawl, buzzwords, form-controls, pure-black-white, broad-will-change, mask-without-size, custom-cursor, italic-serif-hero, banned-face, svg-scene, radial-glow, dark-section, equal-cards, section-spacing, same-entrance, reveal-form, marquee, endless-animation, linear-easing, layout-motion, global-motion-reset, image-loading, unsourced-claim (a claim the brief does not give: mark it [GAP: what is missing], or [UNVERIFIED: what] when stated but unconfirmed), px-font-size, fixed-width, tap-target, image-ratio, repeated-structure, component-drift, loop-items, structure-scope, structure-names, component-block, component-tokens, invented-utility, inline-style, template-bindings, archive-loop, every other etch-* code, and on ACSS sites the acss-* codes. INFO: open-client-facts (open markers), percent-column-math, stale-year, semicolons, radius-scale. A save is never refused.
|
|
17
19
|
|
|
18
20
|
IMAGES YOU NEED: a photo or illustration nobody supplied is made, not hotlinked. generate_image (the workspace's own OpenAI or Google key) or add_image, poll get_image until ready, then place its placeableUrl with real alt text. get_wireframe_context lists the project's ready images under projectImages.
|
|
19
21
|
|
|
@@ -640,15 +642,19 @@ SpecShot builds a whole site in three stages, so every page shares one system an
|
|
|
640
642
|
|
|
641
643
|
1. Read the plan. Call get_site_plan with the projectId. It returns the site map, the families, the site system, the open run and where each reference goes, and next, the one thing to do now. If a run of SpecShot's own generator is open, stop and say so: the site is being made in SpecShot.
|
|
642
644
|
|
|
643
|
-
|
|
645
|
+
CONTENT MODEL FIRST. Read the site structure with get_site_structure: which pages stay unique Pages, and which are a content type's archive (the list of all items), single (the design every item uses), category pages and items. Two or more pages that do one job (docs, a blog, a changelog, legal pages, services, features) are a type, never plain Pages, and Etch's own post types come first with ACF suggested when the project needs it. Propose corrections with set_site_structure; a person confirms the structure in SpecShot (Build, then Structure). Every whole-site build and deploy is refused while the structure is unconfirmed or a block finding of the structure check stands, with the sentence and the fix. Load the content-model skill with get_skill.
|
|
646
|
+
|
|
647
|
+
2. The site system. With an approved kit, read it once with get_site_kit and detail: "full", so every component's definition is whole. With none, save one now with save_site_kit, or start the run (step 4), whose first item is the site system. Write one style guide: the site header and footer outside <main>, one <style> with the token :root, and every part marked with data-component and data-prop (the item's parts list names them). Take the faces from the TYPE FACTS, never a default face. Fix every block finding in kitFindings, designLaw and layoutCheck, and save again.
|
|
644
648
|
|
|
645
|
-
3. The families. Call set_page_families with groupByCode: true to group the pages by their addresses. Then give each family its job, its hero
|
|
649
|
+
3. The families. Call set_page_families with groupByCode: true to group the pages by their addresses. Then give each family its job, its hero idea (no two families share one), its signature interaction, its section plan (the jobs a page of the family does, each with a key, a name, its purpose and the material it needs, a layout that fits as one option, and optional where a page may leave it out) and its kit components, and pick its pilot: the page with the most real material. The plan says what the pages cover, never how: every page composes its own. A change that adds an error to the plan is refused with its findings, and nothing is written.
|
|
646
650
|
|
|
647
|
-
4. Start. Call next_site_page with start: true. It starts an agent-driven run of every page that is not approved yet. Approved pages are never touched.
|
|
651
|
+
4. Start. Call next_site_page with start: true. It starts an agent-driven run of every page that is not approved yet. Approved pages are never touched, unless the owner asks for them again: start: true with their pageIds and redesign: true makes each as a new design that is approved again.
|
|
648
652
|
|
|
649
653
|
5. The loop. Call next_site_page and do what its item asks.
|
|
650
654
|
- The site system item: write the style guide and save it with save_site_kit and the itemId.
|
|
651
|
-
- A pilot or a page: read the blocks in order (the site brief with the client's rules first, the kit, the family
|
|
655
|
+
- A pilot or a page: read the blocks in order (the site brief with the client's rules first, the kit, the family block, the skills, the TYPE FACTS, then the page's own facts and copy), and open the image references. Then write only mainHtml and pageCss and publish them with publish_page_version, sending projectId, itemId, mainHtml, pageCss and the sections the item names. SpecShot composes the page from the kit and checks it.
|
|
656
|
+
- Every page keeps the kit's parts and its type's bindings and chooses its own composition: never copy the pilot's sections, their order or their layouts. A type's single design marks data-bind="title", data-bind="field:<key>" and data-bind="content" on the body; its archive puts data-loop="main" on its list with one card. The law check warns template-bindings and archive-loop when they are missing.
|
|
657
|
+
- A Copy button on a command or config carries data-ss-copy, and a contact form is <form data-ss-form="contact"> with fields name, email and message, one submit button and no action: the SpecShot plugin makes both work.
|
|
652
658
|
- Read the findings. A first publish with a block finding stays yours for one fix: correct exactly those findings and publish again with the same itemId. That publish finishes the page, flagged if a block finding is left.
|
|
653
659
|
- Pass known with the fingerprints of the blocks you already hold, so a family's later pages send only their own words.
|
|
654
660
|
|
|
@@ -1751,8 +1757,8 @@ components or loops yet, the same build lands as plain blocks and says so.
|
|
|
1751
1757
|
The marks:
|
|
1752
1758
|
|
|
1753
1759
|
- \`data-component="PricingTier"\` on each instance's root (PascalCase).
|
|
1754
|
-
- \`data-prop="title"\` inside it (camelCase): text by default, \`data-prop-type="url"\`, \`"image"
|
|
1755
|
-
\`"boolean"\` with \`data-prop-class
|
|
1760
|
+
- \`data-prop="title"\` inside it (camelCase): text by default, \`data-prop-type="url"\`, \`"image"\`,
|
|
1761
|
+
\`"boolean"\` with \`data-prop-class\`, or \`"attr"\` with \`data-prop-attr="placeholder"\`.
|
|
1756
1762
|
- \`data-slot="actions"\` on the element whose children differ per instance.
|
|
1757
1763
|
- \`data-loop="tiers"\` on the container of the instances (or of one repeated structure).
|
|
1758
1764
|
- \`data-optional\` on a prop element some instances leave empty or leave out.
|
|
@@ -1776,6 +1782,24 @@ The marks:
|
|
|
1776
1782
|
</ul>
|
|
1777
1783
|
\`\`\`
|
|
1778
1784
|
|
|
1785
|
+
## Content model
|
|
1786
|
+
|
|
1787
|
+
1. Model the content first. A page is a unique Page (home, about, pricing, contact) or part of a content type: two or more pages that do one job (docs, a blog, legal pages, services) are a type with an archive, a single, category pages and items, never plain Pages. Not found and search are site templates.
|
|
1788
|
+
Why: The owner, 2026-11-08. Etch builds every item of a type from one single template and lists them on one archive template (docs.etchwp.com /templates).
|
|
1789
|
+
A whole-site build stops on it.
|
|
1790
|
+
|
|
1791
|
+
2. A type's single design marks data-bind="title", data-bind="field:<key>" on each value the items share (also excerpt, date, image and url), and data-bind="content" on the element that holds the item's own body.
|
|
1792
|
+
Why: Etch reads them as {this.title}, the type's fields and Post Content; unmarked, every item shows the sample words.
|
|
1793
|
+
Checked at save as \`template-bindings\`.
|
|
1794
|
+
|
|
1795
|
+
3. A type's archive, category or search design puts data-loop="main" on its list with ONE card whose props are post fields.
|
|
1796
|
+
Why: It becomes Etch's Main Query loop over the real items, with pagination (docs.etchwp.com /loops/main-query). A JSON copy never changes when a post is added.
|
|
1797
|
+
Checked at save as \`archive-loop\`.
|
|
1798
|
+
|
|
1799
|
+
4. Etch's own post types and fields first; ACF is suggested, with the reason, for images, dates, relationships or repeaters. ACF creates categories for you; Etch's own are made by hand for now.
|
|
1800
|
+
Why: The owner, 2026-11-08. Etch documents only text, textarea, number and yes or no fields, and calls its own types a proof of concept.
|
|
1801
|
+
Nobody checks this but you.
|
|
1802
|
+
|
|
1779
1803
|
## Components
|
|
1780
1804
|
|
|
1781
1805
|
1. Make a component of anything that repeats twice or more on a page, or that the site uses across pages: cards, pricing tiers, team members, FAQ items, testimonials, feature rows, nav items, buttons. Mark its root with data-component and a PascalCase name (data-component="PricingTier"). Every instance with that name has the same structure, and the first one is the definition.
|
|
@@ -1812,8 +1836,8 @@ The marks:
|
|
|
1812
1836
|
|
|
1813
1837
|
## Logic
|
|
1814
1838
|
|
|
1815
|
-
1. Repeat items with a loop: data-loop and a camelCase name on the container whose children are all instances of one component, or all one repeated structure with data-prop marks (data-loop="tiers"). Write the real items; the export builds the loop's JSON from them. A loop sits on the page or in a slot, never inside a component's definition.
|
|
1816
|
-
Why: In Etch the container holds one loop block over JSON items built from the instances' properties, so
|
|
1839
|
+
1. Repeat items with a loop: data-loop and a camelCase name on the container whose children are all instances of one component, or all one repeated structure with data-prop marks, which may hold components with their own values (data-loop="tiers"). Write the real items; the export builds the loop's JSON from them. A loop sits on the page or in a slot, never inside a component's definition.
|
|
1840
|
+
Why: In Etch the container holds one loop block over JSON items built from the instances' properties, so a fourth tier is one more item.
|
|
1817
1841
|
Checked at save as \`loop-items\`.
|
|
1818
1842
|
|
|
1819
1843
|
2. An optional part is a condition (data-optional), never a second copy of the block without it. No copy-pasted near-identical blocks anywhere on the page: make them one component with a variant, or one loop.
|
|
@@ -1852,8 +1876,8 @@ The marks:
|
|
|
1852
1876
|
Why: The export nests .faq-item.is-open inside the block's Etch style as &.is-open, so the state sits beside the block in the style manager, and any script or Etch interaction toggles the same class.
|
|
1853
1877
|
Nobody checks this but you.
|
|
1854
1878
|
|
|
1855
|
-
3.
|
|
1856
|
-
Why: An invented utility is a second design system
|
|
1879
|
+
3. No utility classes of your own (.mt-4, .flex, .text-center, a copy of an ACSS utility): style an element with its own BEM class. On an ACSS 4 site use only the classes it still ships (btn--primary, section--l, text--m) and its variables in your class (var(--grid-3)); its 3.x utilities (grid--3, pad--m) are gone.
|
|
1880
|
+
Why: An invented utility is a second design system nobody maintains, and ACSS 4 removed most of its own utilities (docs.automaticcss.com /setup/working-in-acss-4).
|
|
1857
1881
|
Checked at save as \`invented-utility\`.
|
|
1858
1882
|
|
|
1859
1883
|
4. No inline style attributes. The one exception is a custom property that carries data (style="--i: 2" for a stagger index).
|
|
@@ -1870,7 +1894,7 @@ The marks:
|
|
|
1870
1894
|
Why: A component that reads roles follows the brand and the theme from one place, and its own token is the one dial the agency turns for that component alone.
|
|
1871
1895
|
Nobody checks this but you.
|
|
1872
1896
|
|
|
1873
|
-
2. Inside a component's rules every color, size, radius and shadow reads a token with a literal fallback: var(--ink, ...), var(--space-m, 1.5rem), var(--radius-m,
|
|
1897
|
+
2. Inside a component's rules every color, size, radius and shadow reads a token with a literal fallback: var(--ink, ...), var(--space-m, 1.5rem), var(--radius-m, 1rem). No raw hex, rgb, oklch, px or rem where a token exists.
|
|
1874
1898
|
Why: A raw value inside a component is the one place a rebrand or an ACSS retune never reaches, and every instance carries it.
|
|
1875
1899
|
Checked at save as \`component-tokens\`.
|
|
1876
1900
|
|
|
@@ -1899,19 +1923,19 @@ edit in Etch rather than one they have to rebuild.
|
|
|
1899
1923
|
Checked at save as \`etch-selectors\`.
|
|
1900
1924
|
|
|
1901
1925
|
2. Inside @supports, @container and @layer, select by class only. No tag, universal or attribute-led selectors there.
|
|
1902
|
-
Why: Those at-rules travel into the site's stylesheet whole. A bare h2 rule inside @supports restyles every h2 on the client's site, not just this design's. SpecShot scopes them to the design's
|
|
1926
|
+
Why: Those at-rules travel into the site's stylesheet whole. A bare h2 rule inside @supports restyles every h2 on the client's site, not just this design's. SpecShot scopes them to the design's sections on export, but a design that is only safe because the exporter rescued it is a design that breaks in any other builder.
|
|
1903
1927
|
Checked at save as \`etch-atrule-tags\`.
|
|
1904
1928
|
|
|
1905
1929
|
3. Name every @keyframes for its block: hero-settle, chart-grow, faq-open. Never fadeIn, rise, spin or float.
|
|
1906
1930
|
Why: Keyframe names are global on the site. A design's fadeIn replaces the theme's fadeIn, or is replaced by it. SpecShot also prefixes keyframes with the project's prefix on export.
|
|
1907
1931
|
Checked at save as \`etch-keyframes\`.
|
|
1908
1932
|
|
|
1909
|
-
4. Theme with @media (prefers-color-scheme: dark), or with a modifier class on the
|
|
1910
|
-
Why: In Etch the design
|
|
1933
|
+
4. Theme with @media (prefers-color-scheme: dark), or with a modifier class on the section it changes (.cta-band--night). Never :root[data-theme=dark] or html[data-theme=dark].
|
|
1934
|
+
Why: In Etch the design's sections sit inside the client's page, and :root and html belong to the site, so a :root[data-theme] selector never matches there. The exporter carries the attribute onto each top-level section, which works only where they hold it.
|
|
1911
1935
|
Checked at save as \`etch-root-theme\`.
|
|
1912
1936
|
|
|
1913
1937
|
5. Never set font-size on html or :root. Size type with the --step tokens.
|
|
1914
|
-
Why: In Etch, rem means the site's root size. The exporter moves html and :root declarations onto the design's
|
|
1938
|
+
Why: In Etch, rem means the site's root size. The exporter moves html and :root declarations onto the design's sections, where font-size no longer drives rem, so a design that changed the root size renders at a different scale on the site.
|
|
1915
1939
|
Checked at save as \`etch-html-font-size\`.
|
|
1916
1940
|
|
|
1917
1941
|
6. Style with classes only: no #id selectors, and no !important outside a prefers-reduced-motion block.
|
|
@@ -1925,8 +1949,8 @@ edit in Etch rather than one they have to rebuild.
|
|
|
1925
1949
|
Why: A placeable image becomes an asset in the Etch build: a temporary link that the agency uploads to the site's media library, after which the build binds it as a responsive Etch image. A hotlink renders as a gray box in the preview and a broken image on the site.
|
|
1926
1950
|
Checked at save as \`placeholder-image\`.
|
|
1927
1951
|
|
|
1928
|
-
9.
|
|
1929
|
-
Why:
|
|
1952
|
+
9. Sections at the top: body holds the header, main and footer; main holds the sections side by side, never nested or wrapped, each with one container. Nothing is positioned against html or body. In a whole-site build the header and footer are kit components.
|
|
1953
|
+
Why: Each section becomes its own top-level block in Etch, Etch's own Section and Container, where Automatic.css sets spacing, gutter and width. A rebuild replaces only those.
|
|
1930
1954
|
|
|
1931
1955
|
10. Embed the faces in the design (get_font_faces) so the preview renders them; know that the site installs them separately.
|
|
1932
1956
|
Why: Embedded data: fonts are left out of the Etch build and named in its warnings, so the agency installs the same families on the site. A face the design names but never embeds renders in a fallback everywhere.
|
|
@@ -2124,7 +2148,12 @@ any of them; the score is how a revision is seen to move.
|
|
|
2124
2148
|
- :has() inside :has(), checked by law check \`etch-nested-has\` [WARN].
|
|
2125
2149
|
- @keyframes inside a rule, checked by law check \`etch-nested-keyframes\` [WARN].
|
|
2126
2150
|
- Raw SVG markup in a CSS data URI, checked by law check \`etch-svg-data-uri\` [WARN].
|
|
2127
|
-
- A double quote inside an Etch expression, checked by law check \`etch-expression-quotes\` [BLOCK]
|
|
2151
|
+
- A double quote inside an Etch expression, checked by law check \`etch-expression-quotes\` [BLOCK].
|
|
2152
|
+
- A type's single design with no data-bind="title", checked by law check \`template-bindings\` [WARN].
|
|
2153
|
+
- A type's archive design with no data-loop="main", checked by law check \`archive-loop\` [WARN].
|
|
2154
|
+
- On an ACSS site, a class or token ACSS 4 removed or already ships (grid--3, --primary-trans-50, a hidden-text class), checked by law check \`acss-classes\` [WARN].
|
|
2155
|
+
- On an ACSS site, a section with no single inner wrapper, checked by law check \`acss-sections\` [WARN].
|
|
2156
|
+
- On an ACSS site, dark mode that fixes ACSS's color tokens to literal values, checked by law check \`acss-color-scheme\` [WARN].`,
|
|
2128
2157
|
},
|
|
2129
2158
|
{
|
|
2130
2159
|
name: "premium_craft",
|
|
@@ -2536,19 +2565,19 @@ edit in Etch rather than one they have to rebuild.
|
|
|
2536
2565
|
Checked at save as \`etch-selectors\`.
|
|
2537
2566
|
|
|
2538
2567
|
2. Inside @supports, @container and @layer, select by class only. No tag, universal or attribute-led selectors there.
|
|
2539
|
-
Why: Those at-rules travel into the site's stylesheet whole. A bare h2 rule inside @supports restyles every h2 on the client's site, not just this design's. SpecShot scopes them to the design's
|
|
2568
|
+
Why: Those at-rules travel into the site's stylesheet whole. A bare h2 rule inside @supports restyles every h2 on the client's site, not just this design's. SpecShot scopes them to the design's sections on export, but a design that is only safe because the exporter rescued it is a design that breaks in any other builder.
|
|
2540
2569
|
Checked at save as \`etch-atrule-tags\`.
|
|
2541
2570
|
|
|
2542
2571
|
3. Name every @keyframes for its block: hero-settle, chart-grow, faq-open. Never fadeIn, rise, spin or float.
|
|
2543
2572
|
Why: Keyframe names are global on the site. A design's fadeIn replaces the theme's fadeIn, or is replaced by it. SpecShot also prefixes keyframes with the project's prefix on export.
|
|
2544
2573
|
Checked at save as \`etch-keyframes\`.
|
|
2545
2574
|
|
|
2546
|
-
4. Theme with @media (prefers-color-scheme: dark), or with a modifier class on the
|
|
2547
|
-
Why: In Etch the design
|
|
2575
|
+
4. Theme with @media (prefers-color-scheme: dark), or with a modifier class on the section it changes (.cta-band--night). Never :root[data-theme=dark] or html[data-theme=dark].
|
|
2576
|
+
Why: In Etch the design's sections sit inside the client's page, and :root and html belong to the site, so a :root[data-theme] selector never matches there. The exporter carries the attribute onto each top-level section, which works only where they hold it.
|
|
2548
2577
|
Checked at save as \`etch-root-theme\`.
|
|
2549
2578
|
|
|
2550
2579
|
5. Never set font-size on html or :root. Size type with the --step tokens.
|
|
2551
|
-
Why: In Etch, rem means the site's root size. The exporter moves html and :root declarations onto the design's
|
|
2580
|
+
Why: In Etch, rem means the site's root size. The exporter moves html and :root declarations onto the design's sections, where font-size no longer drives rem, so a design that changed the root size renders at a different scale on the site.
|
|
2552
2581
|
Checked at save as \`etch-html-font-size\`.
|
|
2553
2582
|
|
|
2554
2583
|
6. Style with classes only: no #id selectors, and no !important outside a prefers-reduced-motion block.
|
|
@@ -2562,8 +2591,8 @@ edit in Etch rather than one they have to rebuild.
|
|
|
2562
2591
|
Why: A placeable image becomes an asset in the Etch build: a temporary link that the agency uploads to the site's media library, after which the build binds it as a responsive Etch image. A hotlink renders as a gray box in the preview and a broken image on the site.
|
|
2563
2592
|
Checked at save as \`placeholder-image\`.
|
|
2564
2593
|
|
|
2565
|
-
9.
|
|
2566
|
-
Why:
|
|
2594
|
+
9. Sections at the top: body holds the header, main and footer; main holds the sections side by side, never nested or wrapped, each with one container. Nothing is positioned against html or body. In a whole-site build the header and footer are kit components.
|
|
2595
|
+
Why: Each section becomes its own top-level block in Etch, Etch's own Section and Container, where Automatic.css sets spacing, gutter and width. A rebuild replaces only those.
|
|
2567
2596
|
|
|
2568
2597
|
10. Embed the faces in the design (get_font_faces) so the preview renders them; know that the site installs them separately.
|
|
2569
2598
|
Why: Embedded data: fonts are left out of the Etch build and named in its warnings, so the agency installs the same families on the site. A face the design names but never embeds renders in a fallback everywhere.
|
|
@@ -2633,8 +2662,8 @@ components or loops yet, the same build lands as plain blocks and says so.
|
|
|
2633
2662
|
The marks:
|
|
2634
2663
|
|
|
2635
2664
|
- \`data-component="PricingTier"\` on each instance's root (PascalCase).
|
|
2636
|
-
- \`data-prop="title"\` inside it (camelCase): text by default, \`data-prop-type="url"\`, \`"image"
|
|
2637
|
-
\`"boolean"\` with \`data-prop-class
|
|
2665
|
+
- \`data-prop="title"\` inside it (camelCase): text by default, \`data-prop-type="url"\`, \`"image"\`,
|
|
2666
|
+
\`"boolean"\` with \`data-prop-class\`, or \`"attr"\` with \`data-prop-attr="placeholder"\`.
|
|
2638
2667
|
- \`data-slot="actions"\` on the element whose children differ per instance.
|
|
2639
2668
|
- \`data-loop="tiers"\` on the container of the instances (or of one repeated structure).
|
|
2640
2669
|
- \`data-optional\` on a prop element some instances leave empty or leave out.
|
|
@@ -2658,6 +2687,24 @@ The marks:
|
|
|
2658
2687
|
</ul>
|
|
2659
2688
|
\`\`\`
|
|
2660
2689
|
|
|
2690
|
+
## Content model
|
|
2691
|
+
|
|
2692
|
+
1. Model the content first. A page is a unique Page (home, about, pricing, contact) or part of a content type: two or more pages that do one job (docs, a blog, legal pages, services) are a type with an archive, a single, category pages and items, never plain Pages. Not found and search are site templates.
|
|
2693
|
+
Why: The owner, 2026-11-08. Etch builds every item of a type from one single template and lists them on one archive template (docs.etchwp.com /templates).
|
|
2694
|
+
A whole-site build stops on it.
|
|
2695
|
+
|
|
2696
|
+
2. A type's single design marks data-bind="title", data-bind="field:<key>" on each value the items share (also excerpt, date, image and url), and data-bind="content" on the element that holds the item's own body.
|
|
2697
|
+
Why: Etch reads them as {this.title}, the type's fields and Post Content; unmarked, every item shows the sample words.
|
|
2698
|
+
Checked at save as \`template-bindings\`.
|
|
2699
|
+
|
|
2700
|
+
3. A type's archive, category or search design puts data-loop="main" on its list with ONE card whose props are post fields.
|
|
2701
|
+
Why: It becomes Etch's Main Query loop over the real items, with pagination (docs.etchwp.com /loops/main-query). A JSON copy never changes when a post is added.
|
|
2702
|
+
Checked at save as \`archive-loop\`.
|
|
2703
|
+
|
|
2704
|
+
4. Etch's own post types and fields first; ACF is suggested, with the reason, for images, dates, relationships or repeaters. ACF creates categories for you; Etch's own are made by hand for now.
|
|
2705
|
+
Why: The owner, 2026-11-08. Etch documents only text, textarea, number and yes or no fields, and calls its own types a proof of concept.
|
|
2706
|
+
Nobody checks this but you.
|
|
2707
|
+
|
|
2661
2708
|
## Components
|
|
2662
2709
|
|
|
2663
2710
|
1. Make a component of anything that repeats twice or more on a page, or that the site uses across pages: cards, pricing tiers, team members, FAQ items, testimonials, feature rows, nav items, buttons. Mark its root with data-component and a PascalCase name (data-component="PricingTier"). Every instance with that name has the same structure, and the first one is the definition.
|
|
@@ -2694,8 +2741,8 @@ The marks:
|
|
|
2694
2741
|
|
|
2695
2742
|
## Logic
|
|
2696
2743
|
|
|
2697
|
-
1. Repeat items with a loop: data-loop and a camelCase name on the container whose children are all instances of one component, or all one repeated structure with data-prop marks (data-loop="tiers"). Write the real items; the export builds the loop's JSON from them. A loop sits on the page or in a slot, never inside a component's definition.
|
|
2698
|
-
Why: In Etch the container holds one loop block over JSON items built from the instances' properties, so
|
|
2744
|
+
1. Repeat items with a loop: data-loop and a camelCase name on the container whose children are all instances of one component, or all one repeated structure with data-prop marks, which may hold components with their own values (data-loop="tiers"). Write the real items; the export builds the loop's JSON from them. A loop sits on the page or in a slot, never inside a component's definition.
|
|
2745
|
+
Why: In Etch the container holds one loop block over JSON items built from the instances' properties, so a fourth tier is one more item.
|
|
2699
2746
|
Checked at save as \`loop-items\`.
|
|
2700
2747
|
|
|
2701
2748
|
2. An optional part is a condition (data-optional), never a second copy of the block without it. No copy-pasted near-identical blocks anywhere on the page: make them one component with a variant, or one loop.
|
|
@@ -2734,8 +2781,8 @@ The marks:
|
|
|
2734
2781
|
Why: The export nests .faq-item.is-open inside the block's Etch style as &.is-open, so the state sits beside the block in the style manager, and any script or Etch interaction toggles the same class.
|
|
2735
2782
|
Nobody checks this but you.
|
|
2736
2783
|
|
|
2737
|
-
3.
|
|
2738
|
-
Why: An invented utility is a second design system
|
|
2784
|
+
3. No utility classes of your own (.mt-4, .flex, .text-center, a copy of an ACSS utility): style an element with its own BEM class. On an ACSS 4 site use only the classes it still ships (btn--primary, section--l, text--m) and its variables in your class (var(--grid-3)); its 3.x utilities (grid--3, pad--m) are gone.
|
|
2785
|
+
Why: An invented utility is a second design system nobody maintains, and ACSS 4 removed most of its own utilities (docs.automaticcss.com /setup/working-in-acss-4).
|
|
2739
2786
|
Checked at save as \`invented-utility\`.
|
|
2740
2787
|
|
|
2741
2788
|
4. No inline style attributes. The one exception is a custom property that carries data (style="--i: 2" for a stagger index).
|
|
@@ -2752,7 +2799,7 @@ The marks:
|
|
|
2752
2799
|
Why: A component that reads roles follows the brand and the theme from one place, and its own token is the one dial the agency turns for that component alone.
|
|
2753
2800
|
Nobody checks this but you.
|
|
2754
2801
|
|
|
2755
|
-
2. Inside a component's rules every color, size, radius and shadow reads a token with a literal fallback: var(--ink, ...), var(--space-m, 1.5rem), var(--radius-m,
|
|
2802
|
+
2. Inside a component's rules every color, size, radius and shadow reads a token with a literal fallback: var(--ink, ...), var(--space-m, 1.5rem), var(--radius-m, 1rem). No raw hex, rgb, oklch, px or rem where a token exists.
|
|
2756
2803
|
Why: A raw value inside a component is the one place a rebrand or an ACSS retune never reaches, and every instance carries it.
|
|
2757
2804
|
Checked at save as \`component-tokens\`.
|
|
2758
2805
|
|
|
@@ -3448,21 +3495,28 @@ Never: Copying the reference. Take only its structure and layout. Never reuse it
|
|
|
3448
3495
|
|
|
3449
3496
|
Say "rebuilt from" or "used as a reference". Never "cloned" or "copied".
|
|
3450
3497
|
|
|
3498
|
+
## When the task says Match the capture's look is on
|
|
3499
|
+
|
|
3500
|
+
The owner asked for the capture's exact look, or the capture is the client's own website. For that task only, you may match the capture's exact colors and fonts, which replaces those two limits in the boundary above and in step 6 below. The words never come from the capture, even then: every client gets words written for them, so write every word new for this project as step 4 says, and read the capture's text only for the length, tone and hierarchy to aim for. get_wireframe_context and get_capture then give you the whole capture, with a matchLook note on it. save_wireframe still holds six or more of its words in a row, one of its headings and an image from its site as block findings, and reports its colors, faces and class names in the originality line instead. Its images, logos and icons still come from the project, and everything else below stands.
|
|
3501
|
+
|
|
3502
|
+
REBUILT FROM A CAPTURE, also checked on every save:
|
|
3503
|
+
- In a section rebuilt from a capture, anything of the reference's but its structure and layout: six or more of its words in a row or one of its headings, an image from its site, a brand color or a face of its that the project's brand does not share, or one of its own class names. SpecShot reads the capture on the server and checks the rebuild against it, checked by law check \`originality\` [BLOCK].
|
|
3504
|
+
|
|
3451
3505
|
## The steps
|
|
3452
3506
|
|
|
3453
3507
|
1. READ THE TASK. Call get_agent_tasks with the projectId and status "queued". The rebuild task's description names the capture id, the exact name to save under, the page it is for (if any) and the owner's note. Set it to "running" with update_agent_task, so the owner sees you have it.
|
|
3454
3508
|
|
|
3455
|
-
2. READ THE PROJECT. Call get_wireframe_context with the projectId. When its BRIEF opens with CLIENT RULES, those are the client's and the agency's own instructions: what is off-limits, what they may not legally say, how the site should come across, the brand assets they have. They apply to this section too, and they beat every default here, but never the boundary above. Find the capture by its id under captures
|
|
3509
|
+
2. READ THE PROJECT. Call get_wireframe_context with the projectId. When its BRIEF opens with CLIENT RULES, those are the client's and the agency's own instructions: what is off-limits, what they may not legally say, how the site should come across, the brand assets they have. They apply to this section too, and they beat every default here, but never the boundary above. Find the capture by its id under captures. While this task is open it carries only what a rebuild may take from it, the same reference SpecShot's own generator gets: its imageUrl (a screenshot to look at if you can see images, never to place), its sectionType and its layout's shape. Do not go looking for more: get_capture answers with the same reference, and the capture's text, colors, faces, styles and markup are not yours to use. Note the brand tokens, the copyBlocks, the projectImages and etch.prefix (the prefix every token you declare carries in Etch). If the task names a page, read that page's goal in the page list. get_brand_system has the whole brand when you need more of it.
|
|
3456
3510
|
|
|
3457
|
-
3. STUDY THE REFERENCE FOR STRUCTURE ONLY. Before any markup, write down: how many columns, the order of the parts, what is grouped with what, which part dominates, the alignment
|
|
3511
|
+
3. STUDY THE REFERENCE FOR STRUCTURE ONLY. Before any markup, write down: how many columns, the order of the parts, what is grouped with what, which part dominates, the alignment and the density. Ignore its words, its colors, its type, its pictures and its logo.
|
|
3458
3512
|
|
|
3459
3513
|
4. WRITE THE COPY FOR THIS PROJECT. Use an approved copy block word for word where one fits, prefer a draft block over anything you would invent, and otherwise write plain, specific copy for this project. Real, uneven numbers. Never lorem, never buzzwords, never a word of the reference's text, and never a claim the CLIENT RULES put off-limits.
|
|
3460
3514
|
|
|
3461
3515
|
5. IMAGERY. Use a project image (projectImages, or list_images) by its placeableUrl, or make one with generate_image (it runs on the workspace's own key; poll get_image until it is ready, then use its placeableUrl with real alt text). Draw icons as inline SVG. Never a placeholder image host, and never the capture's screenshot.
|
|
3462
3516
|
|
|
3463
|
-
6. BUILD ONE SECTION UNDER THE LAW. One <section> root carrying one BEM block class named for what it is (class="pricing"), single-class BEM selectors throughout, and one <style> block with the token :root at its top: every type and space step a clamp() with a literal fallback, under the token contract's names. Theme on the section's own root (never :root[data-theme] or html), no html font size, no ids, no !important, keyframes named for the block, no emoji as icons, and every state (hover, focus, active, disabled).
|
|
3517
|
+
6. BUILD ONE SECTION UNDER THE LAW. One <section> root carrying one BEM block class named for what it is (class="pricing"), single-class BEM selectors throughout, and one <style> block with the token :root at its top: every type and space step a clamp() with a literal fallback, under the token contract's names. Theme on the section's own root (never :root[data-theme] or html), no html font size, no ids, no !important, keyframes named for the block, no emoji as icons, and every state (hover, focus, active, disabled). The faces are the project's: the ones the brand names (get_brand_system), else the approved site kit's; with neither, choose a Google Fonts pairing for this project, never a banned default and never a face from the reference, and tell the owner the brand names no font. Embed them with get_font_faces. Every color comes from the brand's tokens. No header, navigation, footer or main around it: the page it joins already has them.
|
|
3464
3518
|
|
|
3465
|
-
7. SAVE IT AS A SECTION. Call save_wireframe with the projectId, the exact name from the task (for example "Pricing section, rebuilt from linear.app"), the html, pageType "section" and sections set to the section's one name, and NO pageSlug or pageId. A section filed under a page would stand in for that page's design. Do not use publish_page_version for it. Read designLaw in the response and revise_wireframe (with baseVersion) until it has no block findings.
|
|
3519
|
+
7. SAVE IT AS A SECTION. Call save_wireframe with the projectId, the exact name from the task (for example "Pricing section, rebuilt from linear.app"), the html, pageType "section" and sections set to the section's one name, and NO pageSlug or pageId. A section filed under a page would stand in for that page's design. Do not use publish_page_version for it. SpecShot holds every save of it against the capture, on the server: six or more of its words in a row, one of its headings, an image from its site, one of its brand colors or faces, or one of its class names is a block finding under the code originality, and the response's originality line says what it found. Read designLaw in the response and revise_wireframe (with baseVersion) until it has no block findings.
|
|
3466
3520
|
|
|
3467
3521
|
8. CLOSE THE TASK. Call update_agent_task with status "completed" and an outputSummary naming the design and its id.
|
|
3468
3522
|
|
|
@@ -4569,8 +4623,8 @@ components or loops yet, the same build lands as plain blocks and says so.
|
|
|
4569
4623
|
The marks:
|
|
4570
4624
|
|
|
4571
4625
|
- \`data-component="PricingTier"\` on each instance's root (PascalCase).
|
|
4572
|
-
- \`data-prop="title"\` inside it (camelCase): text by default, \`data-prop-type="url"\`, \`"image"
|
|
4573
|
-
\`"boolean"\` with \`data-prop-class
|
|
4626
|
+
- \`data-prop="title"\` inside it (camelCase): text by default, \`data-prop-type="url"\`, \`"image"\`,
|
|
4627
|
+
\`"boolean"\` with \`data-prop-class\`, or \`"attr"\` with \`data-prop-attr="placeholder"\`.
|
|
4574
4628
|
- \`data-slot="actions"\` on the element whose children differ per instance.
|
|
4575
4629
|
- \`data-loop="tiers"\` on the container of the instances (or of one repeated structure).
|
|
4576
4630
|
- \`data-optional\` on a prop element some instances leave empty or leave out.
|
|
@@ -4594,6 +4648,24 @@ The marks:
|
|
|
4594
4648
|
</ul>
|
|
4595
4649
|
\`\`\`
|
|
4596
4650
|
|
|
4651
|
+
## Content model
|
|
4652
|
+
|
|
4653
|
+
1. Model the content first. A page is a unique Page (home, about, pricing, contact) or part of a content type: two or more pages that do one job (docs, a blog, legal pages, services) are a type with an archive, a single, category pages and items, never plain Pages. Not found and search are site templates.
|
|
4654
|
+
Why: The owner, 2026-11-08. Etch builds every item of a type from one single template and lists them on one archive template (docs.etchwp.com /templates).
|
|
4655
|
+
A whole-site build stops on it.
|
|
4656
|
+
|
|
4657
|
+
2. A type's single design marks data-bind="title", data-bind="field:<key>" on each value the items share (also excerpt, date, image and url), and data-bind="content" on the element that holds the item's own body.
|
|
4658
|
+
Why: Etch reads them as {this.title}, the type's fields and Post Content; unmarked, every item shows the sample words.
|
|
4659
|
+
Checked at save as \`template-bindings\`.
|
|
4660
|
+
|
|
4661
|
+
3. A type's archive, category or search design puts data-loop="main" on its list with ONE card whose props are post fields.
|
|
4662
|
+
Why: It becomes Etch's Main Query loop over the real items, with pagination (docs.etchwp.com /loops/main-query). A JSON copy never changes when a post is added.
|
|
4663
|
+
Checked at save as \`archive-loop\`.
|
|
4664
|
+
|
|
4665
|
+
4. Etch's own post types and fields first; ACF is suggested, with the reason, for images, dates, relationships or repeaters. ACF creates categories for you; Etch's own are made by hand for now.
|
|
4666
|
+
Why: The owner, 2026-11-08. Etch documents only text, textarea, number and yes or no fields, and calls its own types a proof of concept.
|
|
4667
|
+
Nobody checks this but you.
|
|
4668
|
+
|
|
4597
4669
|
## Components
|
|
4598
4670
|
|
|
4599
4671
|
1. Make a component of anything that repeats twice or more on a page, or that the site uses across pages: cards, pricing tiers, team members, FAQ items, testimonials, feature rows, nav items, buttons. Mark its root with data-component and a PascalCase name (data-component="PricingTier"). Every instance with that name has the same structure, and the first one is the definition.
|
|
@@ -4630,8 +4702,8 @@ The marks:
|
|
|
4630
4702
|
|
|
4631
4703
|
## Logic
|
|
4632
4704
|
|
|
4633
|
-
1. Repeat items with a loop: data-loop and a camelCase name on the container whose children are all instances of one component, or all one repeated structure with data-prop marks (data-loop="tiers"). Write the real items; the export builds the loop's JSON from them. A loop sits on the page or in a slot, never inside a component's definition.
|
|
4634
|
-
Why: In Etch the container holds one loop block over JSON items built from the instances' properties, so
|
|
4705
|
+
1. Repeat items with a loop: data-loop and a camelCase name on the container whose children are all instances of one component, or all one repeated structure with data-prop marks, which may hold components with their own values (data-loop="tiers"). Write the real items; the export builds the loop's JSON from them. A loop sits on the page or in a slot, never inside a component's definition.
|
|
4706
|
+
Why: In Etch the container holds one loop block over JSON items built from the instances' properties, so a fourth tier is one more item.
|
|
4635
4707
|
Checked at save as \`loop-items\`.
|
|
4636
4708
|
|
|
4637
4709
|
2. An optional part is a condition (data-optional), never a second copy of the block without it. No copy-pasted near-identical blocks anywhere on the page: make them one component with a variant, or one loop.
|
|
@@ -4670,8 +4742,8 @@ The marks:
|
|
|
4670
4742
|
Why: The export nests .faq-item.is-open inside the block's Etch style as &.is-open, so the state sits beside the block in the style manager, and any script or Etch interaction toggles the same class.
|
|
4671
4743
|
Nobody checks this but you.
|
|
4672
4744
|
|
|
4673
|
-
3.
|
|
4674
|
-
Why: An invented utility is a second design system
|
|
4745
|
+
3. No utility classes of your own (.mt-4, .flex, .text-center, a copy of an ACSS utility): style an element with its own BEM class. On an ACSS 4 site use only the classes it still ships (btn--primary, section--l, text--m) and its variables in your class (var(--grid-3)); its 3.x utilities (grid--3, pad--m) are gone.
|
|
4746
|
+
Why: An invented utility is a second design system nobody maintains, and ACSS 4 removed most of its own utilities (docs.automaticcss.com /setup/working-in-acss-4).
|
|
4675
4747
|
Checked at save as \`invented-utility\`.
|
|
4676
4748
|
|
|
4677
4749
|
4. No inline style attributes. The one exception is a custom property that carries data (style="--i: 2" for a stagger index).
|
|
@@ -4688,7 +4760,7 @@ The marks:
|
|
|
4688
4760
|
Why: A component that reads roles follows the brand and the theme from one place, and its own token is the one dial the agency turns for that component alone.
|
|
4689
4761
|
Nobody checks this but you.
|
|
4690
4762
|
|
|
4691
|
-
2. Inside a component's rules every color, size, radius and shadow reads a token with a literal fallback: var(--ink, ...), var(--space-m, 1.5rem), var(--radius-m,
|
|
4763
|
+
2. Inside a component's rules every color, size, radius and shadow reads a token with a literal fallback: var(--ink, ...), var(--space-m, 1.5rem), var(--radius-m, 1rem). No raw hex, rgb, oklch, px or rem where a token exists.
|
|
4692
4764
|
Why: A raw value inside a component is the one place a rebrand or an ACSS retune never reaches, and every instance carries it.
|
|
4693
4765
|
Checked at save as \`component-tokens\`.
|
|
4694
4766
|
|
|
@@ -4717,19 +4789,19 @@ edit in Etch rather than one they have to rebuild.
|
|
|
4717
4789
|
Checked at save as \`etch-selectors\`.
|
|
4718
4790
|
|
|
4719
4791
|
2. Inside @supports, @container and @layer, select by class only. No tag, universal or attribute-led selectors there.
|
|
4720
|
-
Why: Those at-rules travel into the site's stylesheet whole. A bare h2 rule inside @supports restyles every h2 on the client's site, not just this design's. SpecShot scopes them to the design's
|
|
4792
|
+
Why: Those at-rules travel into the site's stylesheet whole. A bare h2 rule inside @supports restyles every h2 on the client's site, not just this design's. SpecShot scopes them to the design's sections on export, but a design that is only safe because the exporter rescued it is a design that breaks in any other builder.
|
|
4721
4793
|
Checked at save as \`etch-atrule-tags\`.
|
|
4722
4794
|
|
|
4723
4795
|
3. Name every @keyframes for its block: hero-settle, chart-grow, faq-open. Never fadeIn, rise, spin or float.
|
|
4724
4796
|
Why: Keyframe names are global on the site. A design's fadeIn replaces the theme's fadeIn, or is replaced by it. SpecShot also prefixes keyframes with the project's prefix on export.
|
|
4725
4797
|
Checked at save as \`etch-keyframes\`.
|
|
4726
4798
|
|
|
4727
|
-
4. Theme with @media (prefers-color-scheme: dark), or with a modifier class on the
|
|
4728
|
-
Why: In Etch the design
|
|
4799
|
+
4. Theme with @media (prefers-color-scheme: dark), or with a modifier class on the section it changes (.cta-band--night). Never :root[data-theme=dark] or html[data-theme=dark].
|
|
4800
|
+
Why: In Etch the design's sections sit inside the client's page, and :root and html belong to the site, so a :root[data-theme] selector never matches there. The exporter carries the attribute onto each top-level section, which works only where they hold it.
|
|
4729
4801
|
Checked at save as \`etch-root-theme\`.
|
|
4730
4802
|
|
|
4731
4803
|
5. Never set font-size on html or :root. Size type with the --step tokens.
|
|
4732
|
-
Why: In Etch, rem means the site's root size. The exporter moves html and :root declarations onto the design's
|
|
4804
|
+
Why: In Etch, rem means the site's root size. The exporter moves html and :root declarations onto the design's sections, where font-size no longer drives rem, so a design that changed the root size renders at a different scale on the site.
|
|
4733
4805
|
Checked at save as \`etch-html-font-size\`.
|
|
4734
4806
|
|
|
4735
4807
|
6. Style with classes only: no #id selectors, and no !important outside a prefers-reduced-motion block.
|
|
@@ -4743,8 +4815,8 @@ edit in Etch rather than one they have to rebuild.
|
|
|
4743
4815
|
Why: A placeable image becomes an asset in the Etch build: a temporary link that the agency uploads to the site's media library, after which the build binds it as a responsive Etch image. A hotlink renders as a gray box in the preview and a broken image on the site.
|
|
4744
4816
|
Checked at save as \`placeholder-image\`.
|
|
4745
4817
|
|
|
4746
|
-
9.
|
|
4747
|
-
Why:
|
|
4818
|
+
9. Sections at the top: body holds the header, main and footer; main holds the sections side by side, never nested or wrapped, each with one container. Nothing is positioned against html or body. In a whole-site build the header and footer are kit components.
|
|
4819
|
+
Why: Each section becomes its own top-level block in Etch, Etch's own Section and Container, where Automatic.css sets spacing, gutter and width. A rebuild replaces only those.
|
|
4748
4820
|
|
|
4749
4821
|
10. Embed the faces in the design (get_font_faces) so the preview renders them; know that the site installs them separately.
|
|
4750
4822
|
Why: Embedded data: fonts are left out of the Etch build and named in its warnings, so the agency installs the same families on the site. A face the design names but never embeds renders in a fallback everywhere.
|
|
@@ -4942,7 +5014,12 @@ any of them; the score is how a revision is seen to move.
|
|
|
4942
5014
|
- :has() inside :has(), checked by law check \`etch-nested-has\` [WARN].
|
|
4943
5015
|
- @keyframes inside a rule, checked by law check \`etch-nested-keyframes\` [WARN].
|
|
4944
5016
|
- Raw SVG markup in a CSS data URI, checked by law check \`etch-svg-data-uri\` [WARN].
|
|
4945
|
-
- A double quote inside an Etch expression, checked by law check \`etch-expression-quotes\` [BLOCK]
|
|
5017
|
+
- A double quote inside an Etch expression, checked by law check \`etch-expression-quotes\` [BLOCK].
|
|
5018
|
+
- A type's single design with no data-bind="title", checked by law check \`template-bindings\` [WARN].
|
|
5019
|
+
- A type's archive design with no data-loop="main", checked by law check \`archive-loop\` [WARN].
|
|
5020
|
+
- On an ACSS site, a class or token ACSS 4 removed or already ships (grid--3, --primary-trans-50, a hidden-text class), checked by law check \`acss-classes\` [WARN].
|
|
5021
|
+
- On an ACSS site, a section with no single inner wrapper, checked by law check \`acss-sections\` [WARN].
|
|
5022
|
+
- On an ACSS site, dark mode that fixes ACSS's color tokens to literal values, checked by law check \`acss-color-scheme\` [WARN].`,
|
|
4946
5023
|
},
|
|
4947
5024
|
{
|
|
4948
5025
|
name: "new_client",
|
|
@@ -4954,10 +5031,10 @@ The owner has a new client. Get what the owner knows about them into SpecShot, w
|
|
|
4954
5031
|
|
|
4955
5032
|
Load the agency-process skill with get_skill first if you have not this session. It holds the phases, their gates, and the rule that a client fact nobody gave is a labeled gap, never an invented value.
|
|
4956
5033
|
|
|
4957
|
-
1.
|
|
5034
|
+
1. Find the client with list_clients first, so it is never made twice. When it is not there and the owner asks you to add it, create it with create_client, sending only what the owner said: the name, and the website, notes and first contact only when given. Find its project with list_projects. When it has none yet and the owner asks for one, create it with create_project, linking the client by its clientFolderId and sending only what the owner said. Read the project with get_project_state and get_project_intelligence.
|
|
4958
5035
|
2. Interview the owner one question at a time, by the new client part of the skill below. Push on vague answers, and stop when another question would only produce detail nobody needs.
|
|
4959
5036
|
3. Write what the brief holds with set_project_intelligence as you go: answers as question and answer pairs under discovery, the platform in platformPreferences, hard limits and claims that need a document in constraints, choices already made in decisions, and every unknown in openQuestions. Mark a fact stated but unconfirmed [UNVERIFIED] and an unknown one [GAP].
|
|
4960
|
-
4. Contact names,
|
|
5037
|
+
4. Contact names, roles and who approves designs belong on the client's record. Read who is there with list_client_contacts, then add a person the owner named with add_client_contact, or correct one with update_client_contact, sending only what the owner said. When your token's seat may not make the change, give the owner the lines to add under Clients.
|
|
4961
5038
|
5. Taste a person stated in their own words goes in with save_decision, saying who said it.
|
|
4962
5039
|
6. Finish with how many gaps are open (a number) and the three or four that matter most. Never contact the client, never set a price and never touch a site.
|
|
4963
5040
|
|
|
@@ -4993,7 +5070,7 @@ How to run discovery as a conversation, and how the answers become the project's
|
|
|
4993
5070
|
|
|
4994
5071
|
## A new client
|
|
4995
5072
|
|
|
4996
|
-
Before the first project of a new client,
|
|
5073
|
+
Before 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:
|
|
4997
5074
|
|
|
4998
5075
|
- Who they are: what the business does, its customers, its size, where it is, its website.
|
|
4999
5076
|
- The people: names, exact titles, who has final say, who handles the day to day, anyone outside the company involved.
|
|
@@ -5065,7 +5142,7 @@ How to run discovery as a conversation, and how the answers become the project's
|
|
|
5065
5142
|
|
|
5066
5143
|
## A new client
|
|
5067
5144
|
|
|
5068
|
-
Before the first project of a new client,
|
|
5145
|
+
Before 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:
|
|
5069
5146
|
|
|
5070
5147
|
- Who they are: what the business does, its customers, its size, where it is, its website.
|
|
5071
5148
|
- The people: names, exact titles, who has final say, who handles the day to day, anyone outside the company involved.
|
|
@@ -5219,7 +5296,7 @@ Load the agency-process skill with get_skill first if you have not this session.
|
|
|
5219
5296
|
4. Read the etch_ready prompt. The owner runs the Etch Connector, turns on the AI Connector in Etch, opens the page and clicks Etch's AI button. Call get_etch_build with dryRun first, run its script with the connector, and tell the owner which fonts to install and which images to upload. The owner may instead press Build in Etch in the extension's side panel, the canvas dialog or the plugin's Etch panel.
|
|
5220
5297
|
5. Refine by hand through the connector by the skill below, etch-structure, etch-css, etch-connector-runtime and etch-connector-gotchas (get_skill each).
|
|
5221
5298
|
6. Record progress with update_concept_status (sent when you start, built when it is complete) and add_build_note. On WordPress, check_built_page compares the built page with the approved design.
|
|
5222
|
-
7. Never publish
|
|
5299
|
+
7. Never publish and never go live, and never touch logins, plugins, themes, hosting or DNS: draft it and hand it over. When the owner asks, send drafts: send_to_wordpress takes the approved pages to their paired WordPress site as drafts, and get_wordpress_deploy says when the drafts are ready to review in WordPress. Going live is the owner's: they review the drafts there and press Go live in SpecShot.
|
|
5223
5300
|
|
|
5224
5301
|
---
|
|
5225
5302
|
|
package/dist/client.js
CHANGED
|
@@ -1,3 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The base address the token is sent to, or an error in plain words.
|
|
3
|
+
*
|
|
4
|
+
* The API token travels in a header on every request, so a plain http address would send it in the
|
|
5
|
+
* clear. Only https is accepted, except on this machine (localhost and 127.0.0.1, for development).
|
|
6
|
+
*/
|
|
7
|
+
export function checkedBaseUrl(raw) {
|
|
8
|
+
let parsed;
|
|
9
|
+
try {
|
|
10
|
+
parsed = new URL(raw);
|
|
11
|
+
}
|
|
12
|
+
catch {
|
|
13
|
+
return { ok: false, error: "SPECSHOT_APP_URL is not a web address. Use https://specshot.cc or leave it unset." };
|
|
14
|
+
}
|
|
15
|
+
const local = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
|
|
16
|
+
if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && local)) {
|
|
17
|
+
return { ok: false, error: "SPECSHOT_APP_URL must start with https://. A plain http address would send your API token unprotected." };
|
|
18
|
+
}
|
|
19
|
+
if (parsed.username || parsed.password)
|
|
20
|
+
return { ok: false, error: "SPECSHOT_APP_URL must not hold a user name or password." };
|
|
21
|
+
return { ok: true, url: raw.replace(/\/$/, "") };
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* A request path, checked. Throws when it could reach another route than the one its tool names.
|
|
25
|
+
*
|
|
26
|
+
* Tools put ids from their arguments into the path (`/api/mcp/concepts/<id>/...`). An id such as
|
|
27
|
+
* `../projects/<id>/intelligence?` would turn a call the person approved into a call to another
|
|
28
|
+
* route with the same method. A path built from real ids never holds a `.` or `..` segment, a
|
|
29
|
+
* query, a fragment, a backslash or a space, so those are refused here, once, for every tool.
|
|
30
|
+
* Query values go through the `params` argument, which encodes them.
|
|
31
|
+
*/
|
|
32
|
+
export function safePath(path) {
|
|
33
|
+
const bad = !path.startsWith("/api/mcp/") ||
|
|
34
|
+
/[?#\\\s]/.test(path) ||
|
|
35
|
+
[...path].some((c) => c.charCodeAt(0) < 0x20) ||
|
|
36
|
+
path.split("/").some((segment) => {
|
|
37
|
+
let decoded = segment;
|
|
38
|
+
try {
|
|
39
|
+
decoded = decodeURIComponent(segment);
|
|
40
|
+
}
|
|
41
|
+
catch {
|
|
42
|
+
return true;
|
|
43
|
+
}
|
|
44
|
+
return decoded === "." || decoded === ".." || decoded.includes("/") || decoded.includes("\\");
|
|
45
|
+
}) ||
|
|
46
|
+
path.includes("//");
|
|
47
|
+
if (bad)
|
|
48
|
+
throw new Error("One of the ids is not valid. Pass ids exactly as SpecShot gave them.");
|
|
49
|
+
return path;
|
|
50
|
+
}
|
|
1
51
|
/** Thin HTTP client for the SpecShot /api/mcp/* routes, authed by an API token. */
|
|
2
52
|
export class SpecShotClient {
|
|
3
53
|
baseUrl;
|
|
@@ -7,7 +57,7 @@ export class SpecShotClient {
|
|
|
7
57
|
this.token = token;
|
|
8
58
|
}
|
|
9
59
|
async get(path, params) {
|
|
10
|
-
const url = new URL(`${this.baseUrl}${path}`);
|
|
60
|
+
const url = new URL(`${this.baseUrl}${safePath(path)}`);
|
|
11
61
|
if (params) {
|
|
12
62
|
for (const [k, v] of Object.entries(params)) {
|
|
13
63
|
if (v !== undefined && v !== "")
|
|
@@ -24,7 +74,7 @@ export class SpecShotClient {
|
|
|
24
74
|
return res.json();
|
|
25
75
|
}
|
|
26
76
|
async patch(path, body) {
|
|
27
|
-
const res = await fetch(`${this.baseUrl}${path}`, {
|
|
77
|
+
const res = await fetch(`${this.baseUrl}${safePath(path)}`, {
|
|
28
78
|
method: "PATCH",
|
|
29
79
|
headers: {
|
|
30
80
|
Authorization: `Bearer ${this.token}`,
|
|
@@ -39,7 +89,7 @@ export class SpecShotClient {
|
|
|
39
89
|
return res.json();
|
|
40
90
|
}
|
|
41
91
|
async post(path, body) {
|
|
42
|
-
const res = await fetch(`${this.baseUrl}${path}`, {
|
|
92
|
+
const res = await fetch(`${this.baseUrl}${safePath(path)}`, {
|
|
43
93
|
method: "POST",
|
|
44
94
|
headers: {
|
|
45
95
|
Authorization: `Bearer ${this.token}`,
|