@realadvisor-sites/kit-core 0.4.2 → 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 +151 -148
- package/CHANGELOG.md +34 -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 +2 -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/AGENTS.md
CHANGED
|
@@ -1,12 +1,25 @@
|
|
|
1
1
|
# AGENTS.md — how to build a RealAdvisor agency site
|
|
2
2
|
|
|
3
|
-
You are building the public website of one real estate agency
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
3
|
+
You are building the public website of one real estate agency, deployed as
|
|
4
|
+
a Cloudflare Worker. The site is a **React Router 7** site (`app/`,
|
|
5
|
+
`react-router.config.ts`: the default) or an **Astro 5** site (`src/`,
|
|
6
|
+
`astro.config.mjs`); look at the site root and keep the framework it has.
|
|
7
|
+
Never convert a site to the other framework unless the user asks.
|
|
8
|
+
|
|
9
|
+
Three files tell you how to build it. Read all three before you write markup:
|
|
10
|
+
|
|
11
|
+
- this file: the rules every site follows, whatever the framework;
|
|
12
|
+
- your kit's `AGENTS.md`: the files, imports, commands and code of your
|
|
13
|
+
framework (`node_modules/@realadvisor/sites-kit-react/AGENTS.md` or
|
|
14
|
+
`node_modules/@realadvisor/sites-kit-astro/AGENTS.md`). Where this file
|
|
15
|
+
says "your kit", it means that one;
|
|
16
|
+
- `DESIGN.md`: the design half of the job.
|
|
17
|
+
|
|
18
|
+
The shared kit (`DESIGN.md`, `fixtures/`, the sources) is in
|
|
19
|
+
`node_modules/@realadvisor/sites-kit-core/`. Twelve finished example sites
|
|
20
|
+
are in `/vercel/sandbox/examples`, each built twice, in `react/<name>` and
|
|
21
|
+
`astro/<name>` (start with its `README.md`): read the version in your
|
|
22
|
+
framework, adapt its code, never copy its data or text.
|
|
10
23
|
|
|
11
24
|
The bar: the agency owner opens the site on desktop and phone and believes a
|
|
12
25
|
good studio built it, with their real listings, real agents and a contact
|
|
@@ -16,7 +29,7 @@ You work alone and nobody will answer questions. Make reasonable decisions,
|
|
|
16
29
|
finish the whole site and verify it yourself (section 10).
|
|
17
30
|
|
|
18
31
|
**You are free to write any code.** The kit gives you the platform (data,
|
|
19
|
-
|
|
32
|
+
the Worker, security headers, the deploy gate) and a few ready parts
|
|
20
33
|
(listings search and map, enquiry form, legal pages, images). The rules
|
|
21
34
|
below that say MUST are about data, law, security and enquiries; everything
|
|
22
35
|
else (layout, components, sections, interactions) is yours to build.
|
|
@@ -53,76 +66,68 @@ Write `BRAND.md` at the site root: logo file, brand colours (hex), fonts,
|
|
|
53
66
|
tone. Save the logo (the best version: SVG, else the largest PNG, else
|
|
54
67
|
`agency.logo`) to `public/brand/`. Take short phrases from their site at
|
|
55
68
|
most; never copy paragraphs, HTML, CSS or JS, never hotlink their images,
|
|
56
|
-
and never take listings, people or numbers from it: those come from
|
|
69
|
+
and never take listings, people or numbers from it: those come from the
|
|
70
|
+
data client (section 3).
|
|
57
71
|
|
|
58
72
|
## 2. Project layout
|
|
59
73
|
|
|
60
|
-
The site holds only its own files; shared code is the
|
|
61
|
-
`@realadvisor/sites-kit-core
|
|
62
|
-
|
|
63
|
-
|
|
74
|
+
The site holds only its own files; shared code is in the packages
|
|
75
|
+
`@realadvisor/sites-kit-core` (both frameworks), `@realadvisor/sites-kit-react`
|
|
76
|
+
or `@realadvisor/sites-kit-astro` (your kit) and `@realadvisor/sites-sdk`
|
|
77
|
+
(the data types). Import their parts, never copy them. To change how a kit
|
|
78
|
+
component looks, theme it (tokens, props, classes); if a page needs a
|
|
79
|
+
different version, copy that one component into the site and own it.
|
|
64
80
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
wrangler.jsonc Worker config. No secrets here.
|
|
69
|
-
src/layouts/Base.astro <head>: title, description, canonical, hreflang, OG, JSON-LD; consent banner.
|
|
70
|
-
src/pages/ Routes. The pages are bare wiring examples: replace their markup.
|
|
71
|
-
src/pages/api/enquiry.ts POST endpoint behind EnquiryForm. Keep it.
|
|
72
|
-
src/pages/legal.astro, privacy.astro, [lang]/ Legal notice and privacy policy. Keep the content.
|
|
73
|
-
src/pages/sitemap.xml.ts, robots.txt.ts Keep; add new static pages to STATIC_PATHS.
|
|
74
|
-
src/data/*.json Fixture data (dev, build time). Production reads live data.
|
|
75
|
-
```
|
|
81
|
+
`site.json` (country, locale, locales, developmentsPath, redirects as 301s)
|
|
82
|
+
is the same in both frameworks: set it first. Your kit's `AGENTS.md` lists
|
|
83
|
+
the other files, the imports and the commands.
|
|
76
84
|
|
|
77
|
-
|
|
85
|
+
Shared parts (`@realadvisor/sites-kit-core/<part>`):
|
|
78
86
|
|
|
79
87
|
```
|
|
80
|
-
|
|
81
|
-
env Worker env per request (SITE_MODE, data API, ANALYTICS_ID). Set by the kit
|
|
88
|
+
agency agencyOf(organisation, team): the agency record of legal, JSON-LD and footer.
|
|
89
|
+
env Worker env per request (SITE_MODE, data API, ANALYTICS_ID). Set by the kit's Worker.
|
|
82
90
|
i18n Strings (form, legal, consent, map, labels) in de/fr/it/es/en; t(), count(), *Label(), legalPath().
|
|
83
91
|
legal Legal notice and privacy text from agency data.
|
|
84
92
|
format formatPrice, formatSurface, formatAmount, listingUrl, LOCALE.
|
|
85
93
|
image img() / srcset(): resized photo URLs (for og:image, logo, <picture>).
|
|
86
|
-
search parseSearch,
|
|
94
|
+
search parseSearch, searchHref: the state behind the listings search.
|
|
87
95
|
seo canonicalUrl, safeJsonLd, agencyJsonLd, listingJsonLd, listingTitle, listingRef.
|
|
88
96
|
developments Unit labels, prices, status, options and URLs for development pages (section 9).
|
|
89
97
|
security Allowed hosts and security headers. There is no way to add hosts.
|
|
90
|
-
components/ListingsSearch.astro /listings: filters, chips, count, sort, list/map, pagination, empty states.
|
|
91
|
-
components/ListingsMap.astro, ListingsPager.astro The listings map (no library) and pager; ListingsSearch wires both.
|
|
92
|
-
components/EnquiryForm.astro THE enquiry form (section 6).
|
|
93
|
-
components/RaImage.astro Photos: resized, srcset, sizes, lazy, `priority` for the LCP image.
|
|
94
|
-
components/LegalContent.astro Body of the legal pages.
|
|
95
|
-
components/ConsentBanner.astro Analytics consent; Base renders it when ANALYTICS_ID is set.
|
|
96
|
-
components/form/ Input, Select, Combobox, Button (styles/form.css): optional controls with one shared look.
|
|
97
98
|
```
|
|
98
99
|
|
|
99
|
-
|
|
100
|
-
`
|
|
101
|
-
`
|
|
100
|
+
Ready parts in both kits, same names, markup, classes and `data-*` hooks:
|
|
101
|
+
`ListingsSearch` (with `ListingsMap`, `ListingsPager`), `EnquiryForm`,
|
|
102
|
+
`RaImage`, `LegalContent`, `ConsentBanner`, `form/*` (`Input`, `Select`,
|
|
103
|
+
`Combobox`, `Button`).
|
|
102
104
|
|
|
103
|
-
Plain CSS
|
|
104
|
-
|
|
105
|
-
one (`@fontsource/*` fonts are fine).
|
|
105
|
+
Plain CSS: one global file with the tokens, plus one stylesheet per
|
|
106
|
+
component or page. No Tailwind, CSS-in-JS, Vue, Svelte or UI kits; add a
|
|
107
|
+
dependency only when you truly need one (`@fontsource/*` fonts are fine).
|
|
106
108
|
|
|
107
109
|
| Command | What |
|
|
108
110
|
| --- | --- |
|
|
109
111
|
| `pnpm dev` | Dev server on http://localhost:4321 |
|
|
110
|
-
| `pnpm check` |
|
|
112
|
+
| `pnpm check` | Types + production build. Must pass. |
|
|
111
113
|
| `pnpm screenshot` | Every route at 1440 and 390, a contact sheet and a problem report (your eyes) |
|
|
112
|
-
| `pnpm fixture <name>` | Switch the sample data
|
|
114
|
+
| `pnpm fixture <name>` | Switch the sample data (the fixture) |
|
|
113
115
|
| `pnpm kit test map` | Browser test of the listings map against a running site |
|
|
114
|
-
| `pnpm check:deploy` | The safety gate publish runs: security headers, hosts, forms, scripts, iframes,
|
|
116
|
+
| `pnpm check:deploy` | The safety gate publish runs: security headers, hosts, forms, scripts, iframes, unsafe HTML, 404s, legal links. A FAIL blocks publishing. |
|
|
115
117
|
|
|
116
|
-
## 3. Data: only through
|
|
118
|
+
## 3. Data: only through the data client
|
|
119
|
+
|
|
120
|
+
The site has one data client, server side: `sites` (React Router,
|
|
121
|
+
`app/lib/data.server.ts`) or `ra` (Astro, `@realadvisor/sites-kit-astro/ra`).
|
|
122
|
+
Both have the SDK's methods (your kit's `AGENTS.md` shows the calls):
|
|
117
123
|
|
|
118
124
|
```ts
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
const dev = await ra.development(idOrSlug); // with units, or null
|
|
125
|
+
organisation(), teams(), agents() // whose site this is (the template's agency() combines them)
|
|
126
|
+
listings({ offer_type: 'buy', status: 'available', limit: 24, offset: 0 }) // { data, pagination }
|
|
127
|
+
allListings(q) // every page of listings(q)
|
|
128
|
+
listing(slugOrId) // or null
|
|
129
|
+
developments() // without units
|
|
130
|
+
development(idOrSlug) // with units, or null
|
|
126
131
|
```
|
|
127
132
|
|
|
128
133
|
Field reference (the API's snake_case): `node_modules/@realadvisor/sites-sdk/src/types.ts`.
|
|
@@ -130,19 +135,20 @@ Field reference (the API's snake_case): `node_modules/@realadvisor/sites-sdk/src
|
|
|
130
135
|
Where data comes from (you never configure it): production uses
|
|
131
136
|
`SITES_API_URL` + `SITES_API_KEY`, set at publish (live, cached 60 s by the
|
|
132
137
|
RealAdvisor API); the CRM preview uses the same two from `.dev.vars` (a
|
|
133
|
-
placeholder key: never print, log or send it anywhere else); everything
|
|
134
|
-
|
|
135
|
-
kit's Demo Agency there when it is empty)
|
|
136
|
-
`src/data/`
|
|
138
|
+
placeholder key: never print, log or send it anywhere else); everything
|
|
139
|
+
else reads the fixture (`pnpm dev`, `pnpm check` copy the CRM's data or the
|
|
140
|
+
kit's Demo Agency there when it is empty): `app/data/fixture.json` on
|
|
141
|
+
React Router, `src/data/` on Astro.
|
|
137
142
|
|
|
138
143
|
Rules:
|
|
139
144
|
|
|
140
|
-
- Read data **only** through
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
145
|
+
- Read data **only** through the data client, server side (React Router:
|
|
146
|
+
loaders; Astro: page frontmatter). Never `fetch` the API yourself, never
|
|
147
|
+
read the fixture file directly, never import the data client into
|
|
148
|
+
browser code, never hardcode listings, prices, names, phones or emails.
|
|
149
|
+
The same code must work on live data with different listings.
|
|
150
|
+
- `listings()` returns at most 200 items; `allListings(q)` pages for you
|
|
151
|
+
(search, sitemap, agent pages).
|
|
146
152
|
- Listings and units carry the CRM's facts (energy class, year built,
|
|
147
153
|
outdoor surfaces, floor, orientation, charges, parkings, move-in date,
|
|
148
154
|
...; sdk/README.md lists them) and developments their developer,
|
|
@@ -153,11 +159,11 @@ Rules:
|
|
|
153
159
|
be empty: `l.photos[0]?.url`, and a neutral tile when there is no photo.
|
|
154
160
|
One unguarded listing breaks every page that lists it.
|
|
155
161
|
- **HTML from data** (`description` of listings, developments and units):
|
|
156
|
-
the SDK already sanitized it (markdown converted). Render it only
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
162
|
+
the SDK already sanitized it (markdown converted). Render it only the
|
|
163
|
+
way your kit's `AGENTS.md` shows (React Router: `<SafeHtml>`; Astro:
|
|
164
|
+
`set:html={sanitizeHtml(...)}`); any other raw HTML with data fails
|
|
165
|
+
check:deploy. For cards and meta descriptions use `description_text`
|
|
166
|
+
(plain), clamped with CSS. Never strip tags yourself.
|
|
161
167
|
- Codes are never shown: `propertyTypeLabel`, `offerTypeLabel`,
|
|
162
168
|
`featureLabel` from `i18n`; the reference is `listingRef(listing)`, never
|
|
163
169
|
`listing.id`; prices `formatPrice(l)` (hidden and on-request included).
|
|
@@ -165,7 +171,8 @@ Rules:
|
|
|
165
171
|
`offer_type: 'buy'` query with that query's `pagination.total`. A live site can have
|
|
166
172
|
only rentals, only sales or nothing: drop or switch a section that would
|
|
167
173
|
be empty; never "See all 0 properties".
|
|
168
|
-
- **Whose site this is:
|
|
174
|
+
- **Whose site this is: the organisation, its teams and its agents from
|
|
175
|
+
the data client, nothing else.**
|
|
169
176
|
Never take the agency's name or contacts from a listing, a development,
|
|
170
177
|
another site or memory. When the data is the kit's fictional Demo Agency
|
|
171
178
|
(example.com emails, +41 00 000 00 0x), build on it as it is and say so.
|
|
@@ -175,13 +182,12 @@ Rules:
|
|
|
175
182
|
## 4. Rendering and errors
|
|
176
183
|
|
|
177
184
|
- Pages that show listings, agents, developments or a form render on
|
|
178
|
-
request
|
|
179
|
-
|
|
185
|
+
request, never at build time: no `Cache-Control` headers, no static
|
|
186
|
+
paths for listings (your kit's `AGENTS.md` says how).
|
|
180
187
|
- Unknown listing or development: a real 404 (410 for a listing that left)
|
|
181
|
-
with the site's 404 page. Keep the not-found
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
- A page that throws answers a logged 500 (the kit middleware), never an
|
|
188
|
+
with the site's 404 page. Keep the not-found code of the template's
|
|
189
|
+
listing page. check:deploy requests missing pages.
|
|
190
|
+
- A page that throws answers a logged 500 (the kit's Worker), never an
|
|
185
191
|
empty 200.
|
|
186
192
|
|
|
187
193
|
## 5. Pages and legal
|
|
@@ -191,7 +197,7 @@ Every agency site has, linked from the header or footer: `/` (home),
|
|
|
191
197
|
description, agent, enquiry form), `/team` (agents with `tel:` and
|
|
192
198
|
`mailto:`), `/contact` (address, phone, email, enquiry form), `/legal`,
|
|
193
199
|
`/privacy`, `/404`, and `/developments` + `/developments/[slug]` when
|
|
194
|
-
`
|
|
200
|
+
`developments()` is not empty (no developments: do not link it).
|
|
195
201
|
|
|
196
202
|
**Legal: never write your own text.** No invented company numbers, VAT or
|
|
197
203
|
register entries, disclaimers, cookie lists or terms. `/legal` and
|
|
@@ -206,35 +212,31 @@ check:deploy fails a page linking another language's legal page).
|
|
|
206
212
|
Cookies and analytics: the site sets no cookies of its own and loads no
|
|
207
213
|
analytics, tag manager, chat or tracking script. Analytics is a RealAdvisor
|
|
208
214
|
setting (`ANALYTICS_ID`) and loads only after consent, through
|
|
209
|
-
`ConsentBanner` (
|
|
215
|
+
`ConsentBanner` (the template's document shell renders it). Keep it; never
|
|
216
|
+
write your own banner.
|
|
210
217
|
|
|
211
218
|
## 6. Enquiries
|
|
212
219
|
|
|
213
|
-
**Every form that sends a message to the agency MUST be
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
- Props: `id`, `listingId`, `agentId`, `agentName`, `contactReason`
|
|
228
|
-
(`buy` | `sell` | `valuation` | `other`), `message`, `developmentId`,
|
|
229
|
-
`lotId`, `units`, `selectedUnit`, `submitLabel`, `class`. Its page renders
|
|
230
|
-
on request.
|
|
220
|
+
**Every form that sends a message to the agency MUST be the kit's
|
|
221
|
+
`EnquiryForm`.** Never another form, a third-party form service or
|
|
222
|
+
`mailto:` as a form: check:deploy fails them and publish deploys nothing.
|
|
223
|
+
Your kit's `AGENTS.md` shows the calls; the props are the same in both:
|
|
224
|
+
|
|
225
|
+
- `id`, `listingId`, `agentId`, `agentName`, `contactReason` (`buy` |
|
|
226
|
+
`sell` | `valuation` | `other`), `message`, `developmentId`, `lotId`,
|
|
227
|
+
`units`, `selectedUnit`, `submitLabel`, `locale`, a class. A listing page
|
|
228
|
+
passes `listingId`, `agentId`, `agentName` and
|
|
229
|
+
`message={t('interested', { title, ref: listingRef(listing) })}`; a
|
|
230
|
+
contact page `contactReason="other"`; a second form on one page its own
|
|
231
|
+
`id`.
|
|
231
232
|
- A development enquiry always passes `developmentId`, plus `lotId` or the
|
|
232
|
-
required `units` select (
|
|
233
|
-
|
|
233
|
+
required `units` select (`unitOptions(dev.units)`, `selectedUnit` from
|
|
234
|
+
`?lot=`; check:deploy fails a development form without them). Never a
|
|
235
|
+
plain form with the development's name in the message.
|
|
234
236
|
- It already validates, posts to `/api/enquiry`, works without JS, carries
|
|
235
237
|
Turnstile bot protection (never add another captcha or a honeypot) and
|
|
236
238
|
links the privacy page. Preview sites never send ("Preview: not sent"):
|
|
237
|
-
that is expected.
|
|
239
|
+
that is expected. Keep the site's `/api/enquiry` route as it is.
|
|
238
240
|
- Style it with the form tokens (DESIGN.md); never change its fields or
|
|
239
241
|
script.
|
|
240
242
|
|
|
@@ -245,27 +247,20 @@ accessible either way.
|
|
|
245
247
|
|
|
246
248
|
## 7. Listings search and map
|
|
247
249
|
|
|
248
|
-
`/listings` renders `ListingsSearch
|
|
249
|
-
`
|
|
250
|
-
|
|
251
|
-
```astro
|
|
252
|
-
const params = parseSearch(Astro.url.searchParams);
|
|
253
|
-
const result = runSearch(await allListings(), params, { locale: LOCALE });
|
|
254
|
-
<h1 data-rs-sync="h1">{heading}</h1>
|
|
255
|
-
<ListingsSearch result={result} contactHref="/contact" valuationHref="/contact#valuation">
|
|
256
|
-
{(l, i) => <ListingCard listing={l} priority={i === 0} />}
|
|
257
|
-
</ListingsSearch>
|
|
258
|
-
```
|
|
250
|
+
`/listings` renders `ListingsSearch` over one pool (`allListings()`) and
|
|
251
|
+
the search state (`parseSearch` of the URL); the template's listings page
|
|
252
|
+
is the wiring, your kit's `AGENTS.md` the code.
|
|
259
253
|
|
|
260
254
|
It is the whole search: GET filters that work without JS, chips, count,
|
|
261
255
|
sort, list and map views (`?view=map`, moving the map filters by `?bbox=`),
|
|
262
|
-
pagination, sold listings, empty states. Pass your own card
|
|
263
|
-
theme it with its tokens
|
|
264
|
-
`--rs-columns`, ...: the list
|
|
265
|
-
`result`, `base` (a renamed path such
|
|
266
|
-
`
|
|
267
|
-
`filters`, `sold
|
|
268
|
-
from every active filter
|
|
256
|
+
pagination, sold listings, empty states. Pass your own card as its child
|
|
257
|
+
(a render function of the listing and its index); theme it with its tokens
|
|
258
|
+
(`--accent`, `--text`, `--surface`, `--line`, `--rs-columns`, ...: the list
|
|
259
|
+
is in the component's header). Props: `result`, `base` (a renamed path such
|
|
260
|
+
as `/proprietes`), `locale`, `contactHref`, `valuationHref`, `tellUsHref`,
|
|
261
|
+
`listingHref`, `price`, `filters`, `sold`, `empty`. The page owns the `h1`
|
|
262
|
+
(with `data-rs-sync="h1"`) and title, built from every active filter
|
|
263
|
+
(section 8).
|
|
269
264
|
|
|
270
265
|
You may build another search, but keep its URLs GET and crawlable, its
|
|
271
266
|
counts true and its empty states real. For any listings map use
|
|
@@ -277,10 +272,10 @@ After changing the search or map, run `pnpm kit test map` against
|
|
|
277
272
|
|
|
278
273
|
## 8. SEO, routes and i18n
|
|
279
274
|
|
|
280
|
-
- Every page
|
|
281
|
-
`
|
|
282
|
-
|
|
283
|
-
|
|
275
|
+
- Every page goes through the site layout with `title`, `description` and
|
|
276
|
+
`image` (`img(url, { w: 1200, h: 630 })` of the page's main photo); the
|
|
277
|
+
layout writes canonical, OG and JSON-LD (`jsonLd`, escaped by
|
|
278
|
+
`safeJsonLd`) with the kit's SEO part (your kit's `AGENTS.md`).
|
|
284
279
|
- Titles are unique on every URL, filtered and paged ones included: build
|
|
285
280
|
title, `h1` and description from every active filter ("Mieten in Morges
|
|
286
281
|
– Seite 2 | Demo Agency"). Listing pages:
|
|
@@ -288,8 +283,8 @@ After changing the search or map, run `pnpm kit test map` against
|
|
|
288
283
|
- One `<h1>` per page, headings in order, `alt` on every image (from the
|
|
289
284
|
data; `alt=""` only for decoration). Listing pages pass
|
|
290
285
|
`listingJsonLd`, home and contact `agencyJsonLd`.
|
|
291
|
-
- Add every new route to `STATIC_PATHS` in
|
|
292
|
-
|
|
286
|
+
- Add every new route to `STATIC_PATHS` in the sitemap route. Internal
|
|
287
|
+
links are real `<a href>`.
|
|
293
288
|
- A redesign of an agency that already has a site keeps its main URL paths
|
|
294
289
|
working: rename routes to match or add 301s in `redirects` in site.json.
|
|
295
290
|
- Language: the agency's (from `agency.address.country` and the agents'
|
|
@@ -298,11 +293,11 @@ After changing the search or map, run `pnpm kit test map` against
|
|
|
298
293
|
separate words.
|
|
299
294
|
- Multi-language sites (only when asked): one URL per language
|
|
300
295
|
(`/fr/...`, `/de/...`), `locales` in site.json (default first), every
|
|
301
|
-
page passes `alternates` (all versions)
|
|
302
|
-
|
|
303
|
-
listing and unit texts in the page's language by itself
|
|
304
|
-
translations, else the original): put `lang={l.text_locale}`
|
|
305
|
-
element that shows them.
|
|
296
|
+
page passes `alternates` (all versions) to the layout, and the legal pages
|
|
297
|
+
exist per language (the template's `:lang` / `[lang]` routes). The data
|
|
298
|
+
client then reads listing and unit texts in the page's language by itself
|
|
299
|
+
(the CRM's translations, else the original): put `lang={l.text_locale}`
|
|
300
|
+
on the element that shows them.
|
|
306
301
|
|
|
307
302
|
## 9. One-development site
|
|
308
303
|
|
|
@@ -310,15 +305,14 @@ When the run names one development (its id and title), the whole site is
|
|
|
310
305
|
that development; the agency markets it.
|
|
311
306
|
|
|
312
307
|
- Load it by the id from the prompt: one constant
|
|
313
|
-
(`export const DEVELOPMENT_ID = '<id>'`) and
|
|
314
|
-
on every page. Never `developments()[0]`,
|
|
315
|
-
name.
|
|
308
|
+
(`export const DEVELOPMENT_ID = '<id>'`) and
|
|
309
|
+
`development(DEVELOPMENT_ID)` on every page. Never `developments()[0]`,
|
|
310
|
+
never a slug guessed from the name.
|
|
316
311
|
- Pages: `/` (the development), `/lots/[id]` (one unit; `noindex` when
|
|
317
312
|
sold), `/contact` (enquiry form with `developmentId` and the unit select,
|
|
318
313
|
the broker), `/legal`, `/privacy`, `/404`, `/sitemap.xml` (`/`,
|
|
319
|
-
`/contact`, legal pages, every unit not sold). Delete
|
|
320
|
-
|
|
321
|
-
keep `src/pages/api/`.
|
|
314
|
+
`/contact`, legal pages, every unit not sold). Delete the template's
|
|
315
|
+
listings and developments routes and their links; keep `/api/enquiry`.
|
|
322
316
|
- Helpers from `@realadvisor/sites-kit-core/developments`: `sortUnits`,
|
|
323
317
|
`unitLabel`, `unitPrice` (sold and reserved units never show a price),
|
|
324
318
|
`unitStatusLabel`, `unitOptions` (for EnquiryForm), `unitEnquiryUrl`,
|
|
@@ -329,11 +323,12 @@ that development; the agency markets it.
|
|
|
329
323
|
Facts the CRM lacks (architect, milestones, places nearby) come only from
|
|
330
324
|
the user's message; a section without data is left out, never shown
|
|
331
325
|
empty. No urgency claims ("only 2 left").
|
|
332
|
-
- The agency of a development is
|
|
326
|
+
- The agency of a development is the site's organisation and team (the
|
|
327
|
+
template's `agency()`). Sample data:
|
|
333
328
|
`pnpm fixture development-residence-exemple`.
|
|
334
329
|
|
|
335
|
-
An agency site's development pages
|
|
336
|
-
|
|
330
|
+
An agency site's development pages use the same helpers and the same
|
|
331
|
+
enquiry rules.
|
|
337
332
|
|
|
338
333
|
## 10. Self-check (first build, new page or layout change)
|
|
339
334
|
|
|
@@ -346,28 +341,36 @@ minutes for a new site.
|
|
|
346
341
|
ratio and resolution, controls, clicks blocked by an invisible overlay).
|
|
347
342
|
Read `screenshots/contact-sheet.png` once; at most 3
|
|
348
343
|
`screenshots/sheet-<route>.png` for detail.
|
|
349
|
-
3.
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
344
|
+
3. Judge the screenshots for taste with `TASTE.md` (next to this file):
|
|
345
|
+
the thirteen rubric lines against the chosen style's screenshots, and every
|
|
346
|
+
`taste:` line `pnpm screenshot` printed. Fix what scores under 2. When
|
|
347
|
+
the run has a critic, `pnpm kit critic -- <path> --anchor <example url>`
|
|
348
|
+
writes its inputs (`critic-input/`, see `critic/CRITIC.md`); apply its
|
|
349
|
+
fixes, at most two rounds.
|
|
350
|
+
4. One fix round, then `pnpm check` and `pnpm screenshot -- <changed paths>`
|
|
351
|
+
once more.
|
|
352
|
+
5. `pnpm check:deploy` once: a FAIL means the site cannot be published.
|
|
353
|
+
6. Run `git diff --stat` and name the files you changed; never claim a fix
|
|
353
354
|
you did not make. Finish with a short summary: pages built, design
|
|
354
355
|
direction, anything you could not do.
|
|
355
356
|
|
|
356
357
|
## 11. Do not
|
|
357
358
|
|
|
358
|
-
- Commit secrets, add `.env` values, or put any key in
|
|
359
|
-
service binding, secret or API key (publish sets `SITES_API_URL` and
|
|
359
|
+
- Commit secrets, add `.env` values, or put any key in browser code; add a
|
|
360
|
+
service binding, secret or API key (publish sets `SITES_API_URL` and
|
|
361
|
+
`SITES_API_KEY`).
|
|
360
362
|
- Weaken the security headers: no new hosts, no `unsafe-eval`, no
|
|
361
|
-
`'unsafe-inline'` in script-src; keep
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
363
|
+
`'unsafe-inline'` in script-src; keep the kit's plugin or integration in
|
|
364
|
+
the build config.
|
|
365
|
+
- Inline scripts or `on*=` attributes: browser code is one bundled script
|
|
366
|
+
(your kit's `AGENTS.md`). No iframes, frames, embeds or objects.
|
|
365
367
|
- Load anything from hosts outside the kit's `security` list: photos go
|
|
366
368
|
through `RaImage` / `img()` (never an original photo URL in `src`), fonts
|
|
367
369
|
are self-hosted (`@fontsource/*`), no CDNs.
|
|
368
|
-
-
|
|
369
|
-
-
|
|
370
|
-
|
|
370
|
+
- Raw HTML from data other than the kit's sanitized way (section 3) and
|
|
371
|
+
JSON-LD through the kit.
|
|
372
|
+
- Copy the kit's data client, `env`, `legal`, the Worker or `EnquiryForm`
|
|
373
|
+
into the site; change the `/api/enquiry` route or `wrangler.jsonc` unless
|
|
371
374
|
something is broken; touch the CRM preview's injected scripts.
|
|
372
375
|
- Deploy, push, or call external services (RealAdvisor publishes), or leave
|
|
373
376
|
wiring-example markup and placeholder labels.
|
package/CHANGELOG.md
CHANGED
|
@@ -11,6 +11,40 @@ the versions is enough.
|
|
|
11
11
|
To upgrade a site, read every entry newer than the site's current version,
|
|
12
12
|
oldest first, and apply each Upgrade step in order.
|
|
13
13
|
|
|
14
|
+
## 0.5.0
|
|
15
|
+
|
|
16
|
+
- React Router is the default: `template/` is now a React Router 7 starter,
|
|
17
|
+
the Astro starter moved to `template-astro/`.
|
|
18
|
+
- The rules split in three: `kit-core/AGENTS.md` (every site),
|
|
19
|
+
`kit-react/AGENTS.md` and `kit-astro/AGENTS.md` (the framework).
|
|
20
|
+
- Taste judge: `kit-core/TASTE.md` (13-line rubric against the chosen
|
|
21
|
+
example), `kit-core/critic/CRITIC.md` and `sites-kit critic` (inputs for a
|
|
22
|
+
separate critic), `sites-kit critic calibrate`, and `taste:` checks in
|
|
23
|
+
`pnpm screenshot` (header height, logo by shape, saturated fields, accent
|
|
24
|
+
hues, line length, body size, soft photos, lede styles, font families,
|
|
25
|
+
grid).
|
|
26
|
+
- Logo size by shape: a tall or square mark is 40–72px tall; a wide
|
|
27
|
+
wordmark keeps the 100px minimum width, at most 72px tall.
|
|
28
|
+
- kit-react: `RaImage` preloads with a hoisted `<link>` (no `react-dom`
|
|
29
|
+
import, which the dev server loaded as raw CommonJS); dev-only preview
|
|
30
|
+
bridge through `SITES_PREVIEW_BRIDGE`.
|
|
31
|
+
- `sites-kit fixture` writes `app/data/fixture.json` on a React Router site.
|
|
32
|
+
|
|
33
|
+
### Upgrade
|
|
34
|
+
|
|
35
|
+
1. Astro site: in `CLAUDE.md`, after the line
|
|
36
|
+
`@node_modules/@realadvisor/sites-kit-core/AGENTS.md`, add
|
|
37
|
+
`@node_modules/@realadvisor/sites-kit-astro/AGENTS.md`; after
|
|
38
|
+
`@node_modules/@realadvisor/sites-kit-core/DESIGN.md`, add
|
|
39
|
+
`@node_modules/@realadvisor/sites-kit-core/TASTE.md`.
|
|
40
|
+
2. React Router site: in `CLAUDE.md`, after the line
|
|
41
|
+
`@node_modules/@realadvisor/sites-kit-core/AGENTS.md`, add
|
|
42
|
+
`@node_modules/@realadvisor/sites-kit-react/AGENTS.md` (when missing);
|
|
43
|
+
after `@node_modules/@realadvisor/sites-kit-core/DESIGN.md`, add
|
|
44
|
+
`@node_modules/@realadvisor/sites-kit-core/TASTE.md`.
|
|
45
|
+
3. Run `pnpm screenshot` and fix any new `taste:` line, or name the reason
|
|
46
|
+
to keep it in `DESIGN-NOTES.md`.
|
|
47
|
+
|
|
14
48
|
## 0.4.2
|
|
15
49
|
|
|
16
50
|
- This changelog, shipped in kit-core.
|
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.
|