@realadvisor-sites/kit-core 0.4.1 → 0.5.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/AGENTS.md +158 -148
- package/CHANGELOG.md +91 -0
- package/DESIGN.md +70 -9
- package/README.md +3 -3
- package/bin/sites-kit.mjs +5 -1
- package/lib/render-error.ts +6 -0
- package/package.json +3 -2
- package/tools/critic-calibrate.mjs +95 -0
- package/tools/critic.mjs +397 -0
- package/tools/screenshot.mjs +198 -1
- package/tools/search-map-test.mjs +8 -3
- package/tools/use-fixture.mjs +13 -8
package/DESIGN.md
CHANGED
|
@@ -32,7 +32,8 @@ No current website or BRAND.md says "CRM data only": use `agency.logo` and
|
|
|
32
32
|
|
|
33
33
|
## 2. Tokens
|
|
34
34
|
|
|
35
|
-
Put colours, fonts, radii and spacing in
|
|
35
|
+
Put colours, fonts, radii and spacing in one tokens file
|
|
36
|
+
(`app/styles/tokens.css` on React Router, `src/styles/tokens.css` on Astro) and use
|
|
36
37
|
only tokens in components. The kit parts read these (all have fallbacks):
|
|
37
38
|
|
|
38
39
|
```css
|
|
@@ -47,17 +48,39 @@ only tokens in components. The kit parts read these (all have fallbacks):
|
|
|
47
48
|
- Text contrast >= 4.5:1 (3:1 for text >= 24px), white text on `--accent`
|
|
48
49
|
included.
|
|
49
50
|
- Use `clamp()` for type between phone and desktop.
|
|
51
|
+
- Colour restraint: mostly neutrals, one accent in small doses. A vivid
|
|
52
|
+
brand colour (an electric blue, a signal red) goes in small marks only;
|
|
53
|
+
bands, buttons and large fields take a deep or muted shade of it, the ink
|
|
54
|
+
colour or a neutral surface. TASTE.md is how the result is judged.
|
|
50
55
|
|
|
51
56
|
## 3. Fonts
|
|
52
57
|
|
|
53
|
-
Self-hosted only, with `@fontsource/<family>` imported
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
58
|
+
Self-hosted only, with `@fontsource/<family>` imported where the document
|
|
59
|
+
shell is (React Router: `app/root.tsx`; Astro: the layout frontmatter; the
|
|
60
|
+
CSP blocks Google Fonts links and font CDNs). At most 2 families and 2
|
|
61
|
+
weights per family (a variable font counts as one), latin subset,
|
|
62
|
+
`font-display: swap`, and the above-the-fold font preloaded.
|
|
63
|
+
|
|
64
|
+
Choose the pair against the logo, not only from the example: the type
|
|
65
|
+
echoes the logo's character (weight, width, construction, mood) or
|
|
66
|
+
contrasts with it on purpose, and DESIGN-NOTES.md names which (TASTE.md
|
|
67
|
+
line 6). Swapping the example's fonts is expected when the logo is of
|
|
68
|
+
another kind; any open font on @fontsource is allowed.
|
|
69
|
+
|
|
70
|
+
Import and preload:
|
|
71
|
+
|
|
72
|
+
```tsx
|
|
73
|
+
// app/root.tsx
|
|
74
|
+
import '@fontsource/lato/latin-400.css';
|
|
75
|
+
import lato900 from '@fontsource/lato/files/lato-latin-900-normal.woff2?url';
|
|
76
|
+
<link rel="preload" as="font" type="font/woff2" crossOrigin="" href={lato900} /> {/* in <head> */}
|
|
77
|
+
```
|
|
57
78
|
|
|
58
79
|
```astro
|
|
80
|
+
---
|
|
59
81
|
import '@fontsource/lato/latin-400.css';
|
|
60
82
|
import lato900 from '@fontsource/lato/files/lato-latin-900-normal.woff2?url';
|
|
83
|
+
---
|
|
61
84
|
<link slot="head" rel="preload" as="font" type="font/woff2" crossorigin href={lato900} />
|
|
62
85
|
```
|
|
63
86
|
|
|
@@ -65,9 +88,12 @@ import lato900 from '@fontsource/lato/files/lato-latin-900-normal.woff2?url';
|
|
|
65
88
|
|
|
66
89
|
- The `<img data-logo>` sets only its height (or only its width), the
|
|
67
90
|
other side `auto`: no fixed box, no `object-fit: cover`, no
|
|
68
|
-
`aspect-ratio`.
|
|
69
|
-
for a script or detailed logo)
|
|
70
|
-
|
|
91
|
+
`aspect-ratio`. Size it by its shape: a wide wordmark at 1440 at least
|
|
92
|
+
100px wide and 32px tall (140–180px wide for a script or detailed logo),
|
|
93
|
+
at most 72px tall; a tall or square mark (a monogram, 3³) 40–72px tall.
|
|
94
|
+
At 390 at least 28px tall. The header stays slim: at most 12% of the
|
|
95
|
+
screen. `pnpm screenshot` flags a logo off its file's ratio or outside
|
|
96
|
+
these sizes.
|
|
71
97
|
- Sharp: request 2x the rendered width,
|
|
72
98
|
`img(agency.logo.url, { w: 360, fit: 'fit', quality: 90 })` for a 180px
|
|
73
99
|
logo; an SVG in `public/brand/` as is.
|
|
@@ -157,7 +183,42 @@ wrap.
|
|
|
157
183
|
photo 2"); `alt=""` only for decoration.
|
|
158
184
|
- No layout shift: every image has `width`/`height` or `aspect-ratio`.
|
|
159
185
|
|
|
160
|
-
## 10.
|
|
186
|
+
## 10. Craft defaults
|
|
187
|
+
|
|
188
|
+
Defaults for everything the chosen example does not decide. Where the
|
|
189
|
+
example does something else on purpose, the example wins (TASTE.md judges
|
|
190
|
+
against it); `pnpm screenshot` measures the ones marked (measured).
|
|
191
|
+
|
|
192
|
+
- **Scales, not values.** Spacing, type sizes, radii, borders and shadows
|
|
193
|
+
each come from one scale in the tokens file. No one-off `margin: 37px`.
|
|
194
|
+
A type scale has clear steps: two sizes of one family within 7% of each
|
|
195
|
+
other on the same page read as a mistake.
|
|
196
|
+
- **One grid.** Lay sections out on CSS grid or the `.wrap` container with
|
|
197
|
+
the same gutters; every block starts or ends on an edge another block
|
|
198
|
+
uses. A block aligned to nothing (a link floating in an empty field) is a
|
|
199
|
+
mistake (measured).
|
|
200
|
+
- **Text blocks.** Body text left-aligned with a ragged right edge, never
|
|
201
|
+
justified (measured). Caps only for labels of four words or fewer, never
|
|
202
|
+
for sentences (measured). Emphasis by one means at a time: weight or
|
|
203
|
+
colour or size.
|
|
204
|
+
- **Near-black, not black.** Text and ink in a near-black with a slight
|
|
205
|
+
hue (`#141517`, `#1b1a17`); `#000` only inside the logo or a photo.
|
|
206
|
+
- **Shadows mean raised.** A shadow only on something that floats or
|
|
207
|
+
responds (a menu sheet, a hovered card), one light direction, from the
|
|
208
|
+
shadow scale. Flat surfaces stay flat.
|
|
209
|
+
- **Typographic details** in the page's language:
|
|
210
|
+
- quotation marks „…“ (de), « … » with a thin space (fr), «…» (it, es),
|
|
211
|
+
“…” (en): never straight `"` in text (measured);
|
|
212
|
+
- an en dash for ranges (2–4 Zimmer, 9–18 Uhr), with no spaces;
|
|
213
|
+
- a non-breaking space between a number and its unit or currency
|
|
214
|
+
(`CHF 1'100'000`, `257 m²`, `4.5 Zimmer`): the kit's `formatPrice()`
|
|
215
|
+
and `formatSurface()` already do it;
|
|
216
|
+
- tabular figures (`font-variant-numeric: tabular-nums`) for prices and
|
|
217
|
+
counts in lists, so columns of numbers line up.
|
|
218
|
+
- **States.** Empty, loading and error states are designed like the rest
|
|
219
|
+
(AGENTS.md section 3): a sentence and a way on, never a blank box.
|
|
220
|
+
|
|
221
|
+
## 11. Never
|
|
161
222
|
|
|
162
223
|
- Invented content: lorem ipsum, testimonials, awards, statistics, agents,
|
|
163
224
|
stock handshakes. No data, no section.
|
package/README.md
CHANGED
|
@@ -6,9 +6,9 @@ The framework-neutral core of a RealAdvisor site, shared by the Astro kit
|
|
|
6
6
|
version, and never copies it:
|
|
7
7
|
|
|
8
8
|
```json
|
|
9
|
-
"@realadvisor/sites-kit-core": "npm:@realadvisor-sites/kit-core@^0.
|
|
10
|
-
"@realadvisor/sites-kit-astro": "npm:@realadvisor-sites/kit-astro@^0.
|
|
11
|
-
"@realadvisor/sites-sdk": "npm:@realadvisor-sites/sdk@^0.
|
|
9
|
+
"@realadvisor/sites-kit-core": "npm:@realadvisor-sites/kit-core@^0.5.0",
|
|
10
|
+
"@realadvisor/sites-kit-astro": "npm:@realadvisor-sites/kit-astro@^0.5.0",
|
|
11
|
+
"@realadvisor/sites-sdk": "npm:@realadvisor-sites/sdk@^0.5.0"
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
In this repo the template and examples use paths instead (`file:../kit-core`).
|
package/bin/sites-kit.mjs
CHANGED
|
@@ -4,8 +4,10 @@
|
|
|
4
4
|
* site's package scripts). Every tool lives in the package, never in the
|
|
5
5
|
* site: a site always runs the kit's current version.
|
|
6
6
|
*
|
|
7
|
-
* sites-kit fixture [name | file.json] [--if-empty] sample data into src/data/
|
|
7
|
+
* sites-kit fixture [name | file.json] [--if-empty] sample data into src/data/ (React: app/data/fixture.json)
|
|
8
8
|
* sites-kit screenshot [paths...] [options] screenshots (your eyes)
|
|
9
|
+
* sites-kit critic [path] [--anchor url | --anchor-shots a.png,b.png] inputs for the taste critic (TASTE.md)
|
|
10
|
+
* sites-kit critic calibrate prepare --url <example> | score does the critic still catch known faults
|
|
9
11
|
* sites-kit check deploy [--no-build] the deploy gate (pnpm check:deploy)
|
|
10
12
|
* sites-kit test map [--url ...] [--path ...] browser test of the listings map
|
|
11
13
|
*/
|
|
@@ -15,6 +17,8 @@ import { fileURLToPath } from 'node:url';
|
|
|
15
17
|
const TOOLS = {
|
|
16
18
|
fixture: 'use-fixture.mjs',
|
|
17
19
|
screenshot: 'screenshot.mjs',
|
|
20
|
+
critic: 'critic.mjs',
|
|
21
|
+
'critic calibrate': 'critic-calibrate.mjs',
|
|
18
22
|
'check deploy': 'check-deploy.mjs',
|
|
19
23
|
'test map': 'search-map-test.mjs',
|
|
20
24
|
};
|
package/lib/render-error.ts
CHANGED
|
@@ -21,6 +21,12 @@ const TEXT = {
|
|
|
21
21
|
en: ['Page temporarily unavailable', 'Please try again in a few minutes.', 'Back to home'],
|
|
22
22
|
} as const;
|
|
23
23
|
|
|
24
|
+
/** Title, text and home-link label of the 500 page in a language (a framework's own error page uses them too). */
|
|
25
|
+
export const serverErrorText = (l: keyof typeof TEXT = lang()) => {
|
|
26
|
+
const [title, body, home] = TEXT[l];
|
|
27
|
+
return { title, body, home };
|
|
28
|
+
};
|
|
29
|
+
|
|
24
30
|
export function renderFailed(path: string, err: unknown): Response {
|
|
25
31
|
const e = err instanceof Error ? err : new Error(String(err));
|
|
26
32
|
const msg = err instanceof SitesApiError && err.code === 'site_key' ? `page render failed: ${SITE_KEY_REJECTED}` : 'page render failed';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@realadvisor-sites/kit-core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "The framework-neutral core of a RealAdvisor site, shared by the Astro kit and the React kit: data helpers over @realadvisor/sites-sdk (a peer), i18n, formatting, legal texts, SEO, search, images, security headers, the browser scripts (listing search and map, enquiry, consent), the sites-kit tools (fixture, screenshot, deploy check) and the rules the coding agent follows (AGENTS.md, DESIGN.md).",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -19,6 +19,7 @@
|
|
|
19
19
|
"*.mjs",
|
|
20
20
|
"*.mts",
|
|
21
21
|
"AGENTS.md",
|
|
22
|
+
"CHANGELOG.md",
|
|
22
23
|
"DESIGN.md",
|
|
23
24
|
"README.md",
|
|
24
25
|
"LICENSE",
|
|
@@ -54,7 +55,7 @@
|
|
|
54
55
|
"test": "node --experimental-strip-types --no-warnings=ExperimentalWarning --test \"test/*.test.mjs\" \"test/*.test.ts\""
|
|
55
56
|
},
|
|
56
57
|
"peerDependencies": {
|
|
57
|
-
"@realadvisor/sites-sdk": "^0.
|
|
58
|
+
"@realadvisor/sites-sdk": "^0.5.0",
|
|
58
59
|
"playwright": "^1.64.1"
|
|
59
60
|
},
|
|
60
61
|
"peerDependenciesMeta": {
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Calibrate the taste critic (TASTE.md section 5): does it still catch every
|
|
4
|
+
* fault a user once had to point out, and leave the clean example alone?
|
|
5
|
+
*
|
|
6
|
+
* sites-kit critic calibrate prepare --url http://localhost:4511 [--out critic-calibration]
|
|
7
|
+
* one critic-input/ folder per case in critic/calibration/cases.json,
|
|
8
|
+
* for the example running at --url (the anchor is the same page, clean)
|
|
9
|
+
* (the run harness gives each <out>/<case>/INDEX.md to the critic and saves
|
|
10
|
+
* its answer as <out>/<case>/answer.md)
|
|
11
|
+
* sites-kit critic calibrate score [--out critic-calibration]
|
|
12
|
+
* compares every answer.md with the case's expected scores; exit 1 on a miss
|
|
13
|
+
*/
|
|
14
|
+
import { spawnSync } from 'node:child_process';
|
|
15
|
+
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
|
|
16
|
+
import { join, resolve } from 'node:path';
|
|
17
|
+
import { fileURLToPath } from 'node:url';
|
|
18
|
+
|
|
19
|
+
/** Scores from a critic answer: { lines: { 1: 2, ... }, total }. */
|
|
20
|
+
export function parseScores(md) {
|
|
21
|
+
const lines = {};
|
|
22
|
+
const section = md.split(/^## Scores\s*$/m)[1]?.split(/^## /m)[0] ?? md;
|
|
23
|
+
for (const m of section.matchAll(/^\s*(\d{1,2})\.\s+[^\n]*?\s([012])\s*:/gm)) lines[Number(m[1])] = Number(m[2]);
|
|
24
|
+
const t = md.match(/Total:\s*(\d+)\s*\/\s*(\d+)/);
|
|
25
|
+
const sum = Object.values(lines).reduce((a, b) => a + b, 0);
|
|
26
|
+
return { lines, total: t ? Number(t[1]) : sum, outOf: t ? Number(t[2]) : null };
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** Problems of one case's scores against its expectations ([] = pass). */
|
|
30
|
+
export function checkCase(scores, expect) {
|
|
31
|
+
const out = [];
|
|
32
|
+
const test = (name, v, e) => {
|
|
33
|
+
if (v === undefined) return out.push(`line ${name}: no score found`);
|
|
34
|
+
if (e.min !== undefined && v < e.min) out.push(`line ${name}: ${v}, expected at least ${e.min}`);
|
|
35
|
+
if (e.max !== undefined && v > e.max) out.push(`line ${name}: ${v}, expected at most ${e.max}`);
|
|
36
|
+
};
|
|
37
|
+
for (const [k, e] of Object.entries(expect)) {
|
|
38
|
+
if (k === 'total') {
|
|
39
|
+
if (e.min !== undefined && scores.total < e.min) out.push(`total ${scores.total}, expected at least ${e.min}`);
|
|
40
|
+
if (e.max !== undefined && scores.total > e.max) out.push(`total ${scores.total}, expected at most ${e.max}`);
|
|
41
|
+
} else if (k === 'all') {
|
|
42
|
+
for (const [n, v] of Object.entries(scores.lines)) test(n, v, e);
|
|
43
|
+
} else test(k, scores.lines[Number(k)], e);
|
|
44
|
+
}
|
|
45
|
+
return out;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
|
|
49
|
+
if (isMain) {
|
|
50
|
+
const args = process.argv.slice(2).filter((a) => a !== '--');
|
|
51
|
+
const opt = (name, def) => {
|
|
52
|
+
const i = args.indexOf(`--${name}`);
|
|
53
|
+
return i === -1 ? def : args.splice(i, 2)[1];
|
|
54
|
+
};
|
|
55
|
+
const OUT = resolve(opt('out', 'critic-calibration'));
|
|
56
|
+
const URL_ = opt('url', '');
|
|
57
|
+
const dir = fileURLToPath(new URL('../critic/calibration/', import.meta.url));
|
|
58
|
+
const { cases } = JSON.parse(readFileSync(join(dir, 'cases.json'), 'utf8'));
|
|
59
|
+
const cmd = args[0];
|
|
60
|
+
if (cmd === 'prepare') {
|
|
61
|
+
if (!URL_) {
|
|
62
|
+
console.error('--url: the example of the cases running (e.g. studio-vey: pnpm --dir examples/react/studio-vey dev)');
|
|
63
|
+
process.exit(2);
|
|
64
|
+
}
|
|
65
|
+
for (const c of cases) {
|
|
66
|
+
const out = join(OUT, c.id);
|
|
67
|
+
const inject = c.inject ? ['--inject', join(dir, c.inject)] : [];
|
|
68
|
+
const run = spawnSync(process.execPath, [fileURLToPath(new URL('./critic.mjs', import.meta.url)), c.path, '--url', URL_, '--anchor', URL_, '--anchor-path', c.path, '--out', out, ...inject], { stdio: 'inherit' });
|
|
69
|
+
if (run.status) process.exit(run.status);
|
|
70
|
+
}
|
|
71
|
+
console.log(`\n${cases.length} cases in ${OUT}/. Give each <case>/INDEX.md to the critic (a separate model, nothing else), save its answer as <case>/answer.md, then run: sites-kit critic calibrate score`);
|
|
72
|
+
} else if (cmd === 'score') {
|
|
73
|
+
let misses = 0;
|
|
74
|
+
const report = [];
|
|
75
|
+
for (const c of cases) {
|
|
76
|
+
const f = join(OUT, c.id, 'answer.md');
|
|
77
|
+
if (!existsSync(f)) {
|
|
78
|
+
misses++;
|
|
79
|
+
console.log(`✗ ${c.id}: no answer.md`);
|
|
80
|
+
continue;
|
|
81
|
+
}
|
|
82
|
+
const scores = parseScores(readFileSync(f, 'utf8'));
|
|
83
|
+
const problems = checkCase(scores, c.expect);
|
|
84
|
+
if (problems.length) misses++;
|
|
85
|
+
report.push({ id: c.id, fault: c.fault, scores, problems });
|
|
86
|
+
console.log(`${problems.length ? '✗' : '✓'} ${c.id} (${c.fault}): total ${scores.total}${scores.outOf ? `/${scores.outOf}` : ''}${problems.map((p) => `\n ${p}`).join('')}`);
|
|
87
|
+
}
|
|
88
|
+
writeFileSync(join(OUT, 'score.json'), JSON.stringify(report, null, 2));
|
|
89
|
+
console.log(`\n${cases.length - misses}/${cases.length} cases pass.`);
|
|
90
|
+
process.exit(misses ? 1 : 0);
|
|
91
|
+
} else {
|
|
92
|
+
console.error('Usage: sites-kit critic calibrate prepare --url <example url> | score [--out dir]');
|
|
93
|
+
process.exit(2);
|
|
94
|
+
}
|
|
95
|
+
}
|