@realadvisor-sites/kit-core 0.4.2 → 0.5.1

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 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: an Astro 5
4
- site deployed as a Cloudflare Worker. This file is the engineering half of
5
- the job; `DESIGN.md` is the design half. Read both before you write markup.
6
- The kit's files (`DESIGN.md`, `fixtures/`, the sources) are in
7
- `node_modules/@realadvisor/sites-kit-core/`.
8
- Twelve finished example sites are in `/vercel/sandbox/examples` (start
9
- with its `README.md`): adapt their code, never copy their data or text.
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
- middleware, security headers, the deploy gate) and a few ready parts
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 `ra`.
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 package
61
- `@realadvisor/sites-kit-core`. Import its parts, never copy them. To change how
62
- a kit component looks, theme it (tokens, slots, props); if a page needs a
63
- different version, copy that one file into `src/components/` and own it.
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
- site.json country, locale, locales, developmentsPath, redirects (301s). Set it first.
67
- astro.config.mjs cloudflare() + sitesKit(). Keep sitesKit() in integrations.
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
- Kit parts (`@realadvisor/sites-kit-core/<part>`):
85
+ Shared parts (`@realadvisor/sites-kit-core/<part>`):
78
86
 
79
87
  ```
80
- ra THE data client (section 3).
81
- env Worker env per request (SITE_MODE, data API, ANALYTICS_ID). Set by the kit middleware.
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, runSearch, searchHref: the state behind ListingsSearch.
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
- Imports: `import { ra } from '@realadvisor/sites-kit-astro/ra'`,
100
- `import RaImage from '@realadvisor/sites-kit-astro/components/RaImage.astro'`,
101
- `import type { Listing } from '@realadvisor/sites-kit-core'`.
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 (scoped `<style>` plus one global file with tokens). No Tailwind,
104
- React, Vue, Svelte or UI kits; add a dependency only when you truly need
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` | `astro check` + production build. Must pass. |
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 in `src/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, `set:html`, 404s, legal links. A FAIL blocks publishing. |
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 `ra`
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
- import { ra, allListings } from '@realadvisor/sites-kit-astro/ra';
120
- const agency = await ra.agency(); // name, logo, phone, email, address, brand, socials, description, legal
121
- const agents = await ra.agents();
122
- const { data, pagination } = await ra.listings({ offer_type: 'buy', status: 'available', limit: 24, offset: 0 });
123
- const listing = await ra.listing(slugOrId); // or null
124
- const devs = await ra.developments(); // without units
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 else reads the
134
- fixture in `src/data/` (`pnpm dev`, `pnpm check` copy the CRM's data or the
135
- kit's Demo Agency there when it is empty). A `development-<slug>.json` in
136
- `src/data/` adds its development to `ra.developments()`.
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 `ra`, server side. Never `fetch` the API
141
- yourself, never read `src/data/*.json` directly, never import `ra` in a
142
- client `<script>`, never hardcode listings, prices, names, phones or
143
- emails. The same code must work on live data with different listings.
144
- - `ra.listings()` returns at most 200 items; `allListings(q)` pages for
145
- you (search, sitemap, agent pages).
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 with
157
- `<div class="prose" set:html={sanitizeHtml(listing.description)} />`
158
- (`sanitizeHtml` from `@realadvisor/sites-kit-core`). Any other `set:html` with
159
- data fails check:deploy. For cards and meta descriptions use
160
- `description_text` (plain), clamped with CSS. Never strip tags yourself.
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: `ra.agency()` and `ra.agents()`, nothing else.**
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 (`export const prerender = false;`); static text pages may stay
179
- prerendered. No `Cache-Control` headers, no `getStaticPaths` for listings.
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 block of
182
- `src/pages/listings/[slug].astro`; `src/pages/404.astro` stays
183
- `prerender = false`. check:deploy requests missing pages.
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
- `ra.developments()` is not empty (no developments: do not link it).
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` (Base renders it). Keep it; never write your own banner.
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
- `@realadvisor/sites-kit-astro/components/EnquiryForm.astro`.** Never another
215
- form, a third-party form service or `mailto:` as a form: check:deploy fails
216
- them and publish deploys nothing.
217
-
218
- ```astro
219
- <EnquiryForm listingId={listing.id} agentId={listing.agent?.id} agentName={listing.agent?.first_name}
220
- message={t('interested', { title: listing.title, ref: listingRef(listing) })} />
221
- <EnquiryForm contactReason="other" /> <!-- contact page -->
222
- <EnquiryForm id="valuation" contactReason="valuation" /> <!-- a second form: its own id -->
223
- <EnquiryForm developmentId={dev.id} units={unitOptions(dev.units)} selectedUnit={lotFromUrl} />
224
- <EnquiryForm developmentId={dev.id} lotId={unit.id} /> <!-- one unit -->
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 (check:deploy fails a development form without
233
- them). Never a plain form with the development's name in the message.
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`, fed by `search` (wiring in
249
- `src/pages/listings/index.astro`):
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 in the slot;
263
- theme it with its tokens (`--accent`, `--text`, `--surface`, `--line`,
264
- `--rs-columns`, ...: the list is in the component's header). Props:
265
- `result`, `base` (a renamed path such as `/proprietes`), `locale`,
266
- `contactHref`, `valuationHref`, `tellUsHref`, `listingHref`, `price`,
267
- `filters`, `sold`; slot `empty`. The page owns the `h1` and title, built
268
- from every active filter (section 8).
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 uses `Base` (directly or through your layout) with `title`,
281
- `description` and `image` (`img(url, { w: 1200, h: 630 })` of the page's
282
- main photo). Base writes canonical, OG and JSON-LD (`jsonLd` prop,
283
- escaped by `safeJsonLd`).
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 `src/pages/sitemap.xml.ts`.
292
- Internal links are real `<a href>`.
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) and `locale` to `Base`, and the
302
- legal pages exist per language (`src/pages/[lang]/`). `ra` then reads
303
- listing and unit texts in the page's language by itself (the CRM's
304
- translations, else the original): put `lang={l.text_locale}` on the
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 `ra.development(DEVELOPMENT_ID)`
314
- on every page. Never `developments()[0]`, never a slug guessed from the
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
- `src/pages/listings/` and `src/pages/developments/` and their links;
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 `ra.agency()`. Sample data:
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 (`src/pages/developments/`) use the
336
- same helpers and the same enquiry rules.
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. One fix round, then `pnpm check` and `pnpm screenshot -- <changed
350
- paths>` once more.
351
- 4. `pnpm check:deploy` once: a FAIL means the site cannot be published.
352
- 5. Run `git diff --stat` and name the files you changed; never claim a fix
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 client code; add a
359
- service binding, secret or API key (publish sets `SITES_API_URL` and `SITES_API_KEY`).
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 `sitesKit()` in astro.config.mjs.
362
- - Inline scripts: plain `<script>` only (bundled). Never `is:inline` with a
363
- body, `define:vars` or `on*=` attributes (the CSP blocks them;
364
- check:deploy fails them). No iframes, frames, embeds or objects.
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
- - `set:html` with data except `sanitizeHtml(...)` and `safeJsonLd(...)`.
369
- - Copy the kit's `ra`, `env`, `legal`, the middleware or `EnquiryForm` into
370
- the site; change `src/pages/api/enquiry.ts` or `wrangler.jsonc` unless
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,48 @@ 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.1
15
+
16
+ - kit-react: the dev server can always be framed by the CRM preview, whatever
17
+ `SITE_MODE` says. The CRM sandbox runs dev with `SITE_MODE=production` (so
18
+ preview enquiries send), which made the React kit send
19
+ `X-Frame-Options: DENY` and the preview stayed blank. Published sites keep
20
+ their headers unchanged.
21
+
22
+ ## 0.5.0
23
+
24
+ - React Router is the default: `template/` is now a React Router 7 starter,
25
+ the Astro starter moved to `template-astro/`.
26
+ - The rules split in three: `kit-core/AGENTS.md` (every site),
27
+ `kit-react/AGENTS.md` and `kit-astro/AGENTS.md` (the framework).
28
+ - Taste judge: `kit-core/TASTE.md` (13-line rubric against the chosen
29
+ example), `kit-core/critic/CRITIC.md` and `sites-kit critic` (inputs for a
30
+ separate critic), `sites-kit critic calibrate`, and `taste:` checks in
31
+ `pnpm screenshot` (header height, logo by shape, saturated fields, accent
32
+ hues, line length, body size, soft photos, lede styles, font families,
33
+ grid).
34
+ - Logo size by shape: a tall or square mark is 40–72px tall; a wide
35
+ wordmark keeps the 100px minimum width, at most 72px tall.
36
+ - kit-react: `RaImage` preloads with a hoisted `<link>` (no `react-dom`
37
+ import, which the dev server loaded as raw CommonJS); dev-only preview
38
+ bridge through `SITES_PREVIEW_BRIDGE`.
39
+ - `sites-kit fixture` writes `app/data/fixture.json` on a React Router site.
40
+
41
+ ### Upgrade
42
+
43
+ 1. Astro site: in `CLAUDE.md`, after the line
44
+ `@node_modules/@realadvisor/sites-kit-core/AGENTS.md`, add
45
+ `@node_modules/@realadvisor/sites-kit-astro/AGENTS.md`; after
46
+ `@node_modules/@realadvisor/sites-kit-core/DESIGN.md`, add
47
+ `@node_modules/@realadvisor/sites-kit-core/TASTE.md`.
48
+ 2. React Router site: in `CLAUDE.md`, after the line
49
+ `@node_modules/@realadvisor/sites-kit-core/AGENTS.md`, add
50
+ `@node_modules/@realadvisor/sites-kit-react/AGENTS.md` (when missing);
51
+ after `@node_modules/@realadvisor/sites-kit-core/DESIGN.md`, add
52
+ `@node_modules/@realadvisor/sites-kit-core/TASTE.md`.
53
+ 3. Run `pnpm screenshot` and fix any new `taste:` line, or name the reason
54
+ to keep it in `DESIGN-NOTES.md`.
55
+
14
56
  ## 0.4.2
15
57
 
16
58
  - 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 `src/styles/tokens.css` and use
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 in the layout
54
- frontmatter (the CSP blocks Google Fonts links and font CDNs). At most 2
55
- families and 2 weights per family (a variable font counts as one), latin
56
- subset, `font-display: swap`, and the above-the-fold font preloaded:
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`. At 1440 at least 32px tall and 100px wide (140–180px wide
69
- for a script or detailed logo); at 390 at least 28px tall.
70
- `pnpm screenshot` flags a logo off its file's ratio or below these sizes.
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, a stacked numeral) 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. Never
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.