@activatus/code-standards 3.2.0 → 3.2.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.
@@ -177,11 +177,12 @@ node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs --list rena
177
177
 
178
178
  ## Stage 4 — Constants
179
179
 
180
- Applies setup standard 12.1. Move every link into `r`, every piece of text into `s`, and every number into `numbers.ts`, all in `lib/constants/`. See [Constants](/docs/Structure/folder-structure#constants).
180
+ Applies setup standard 12.1. Move every link into `r`, every piece of text into `s`, every loose number into `numbers.ts`, motion into `animation.ts`, drawing layouts into `artwork.ts`, and class names shared between files into `classNames.ts`, all in `lib/constants/`. See [Constants](/docs/Structure/folder-structure#constants).
181
181
 
182
182
  - **Move the values, nothing else.** The page must look and work exactly as before.
183
183
  - **No component-level `constants.ts` survives this stage.**
184
- - **A list of items with links** keeps its words in `s` and its links in `r` under the same keys: see [the example](/docs/Structure/folder-structure#a-list-of-items-with-links).
184
+ - **Move motion and artwork objects whole.** Never pull their numbers out into `numbers.ts`. A topic file such as `motion.ts` or `durations.ts` is renamed or folded into the matching standard file.
185
+ - **A list of items with links** keeps its words in `s` and its links in `r` under the same keys, and a loop looks each one up by its id: see [the example](/docs/Structure/folder-structure#a-list-of-items-with-links). Delete lookup objects such as `PLAN_ROUTES`.
185
186
  - **Shared types move to `lib/types/`.** `lib/constants/` never imports from `lib/types/`.
186
187
 
187
188
  ## Stage 5 — Components
@@ -198,6 +199,8 @@ Applies setup standard 18. Two branches:
198
199
  1. **6a: the mechanical part.** Copy the [doc templates](/docs/templates#document-templates) and the [`docsSite/` viewer](/docs/Standards/documentation#-setting-it-up), move images into `docs/assets/`, and delete the old viewer's leftovers.
199
200
  2. **6b: rewrite the content as Decision Docs.** This is the part that needs judgement, so it is reviewed on its own. Follow [Converting existing docs](/docs/Standards/documentation#-converting-existing-docs).
200
201
 
202
+ **Keep every docs folder and file from the templates, even ones that do not apply yet.** This rule is final: no docs folder is deleted, whatever the size of the project. See [Setting it up](/docs/Standards/documentation#-setting-it-up).
203
+
201
204
  ## Stage 7 — AGENTS.md, skills and version
202
205
 
203
206
  Applies setup standard 21.
@@ -83,7 +83,7 @@ Tell me the numbers to skip or change, or say "all good".
83
83
  10. Node version set by .nvmrc and direnv
84
84
  11. Styling: Tailwind, flexbox first, colours only from the global palette
85
85
  12. Folder structure: folders at the project root; reusable helper functions in utils/ (no business rules, no outside calls)
86
- 12.1. Constants: r for every link, s for every piece of text, every number in numbers.ts, noData for stand-in data, all in lib/constants/
86
+ 12.1. Constants: r for every link, s for every piece of text, every loose number in numbers.ts, noData for stand-in data, animation, artwork and shared class names in their own files, all in lib/constants/
87
87
  13. Components live where they are used: components/ui/, components/shared/, or beside their page
88
88
  14. Component files in a fixed order, with index.ts exports, and server and client code in separate files
89
89
  15. Design System Components: every project builds the standard components with the same props
@@ -148,7 +148,7 @@ Would you like AI to ask you before every commit and push
148
148
  to git? Yes or no?
149
149
  ```
150
150
 
151
- **Record the answers** in the "Project workflow" section of `AGENTS.md`, from the template: each link they confirmed, and the status circles if they said yes. Delete the line for any link they said "None" to, and the status circles section if they said no. If they said yes to asking before committing, write under **Who commits**: "Ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only." If they said no, write nothing about it: the agent uses its own judgement. Write all four answers in `docs/development/coding-standards.md`, under "Details", so a later update knows not to ask again. See [Working with Agents](/docs/Standards/working-with-agents).
151
+ **Record the answers** in the "Project workflow" section of `AGENTS.md`, from the template: each link they confirmed, and the status circles if they said yes. Delete the line for any link they said "None" to, and the status circles section if they said no. If they said yes to asking before committing, write under **Who commits**: "Ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only." If they said no, write nothing about it: the agent uses its own judgement. Write all four answers in `docs/development/coding-standards.md`, under "Details", on one line, so a later update knows not to ask again: `- Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no] ([date]).` See [Working with Agents](/docs/Standards/working-with-agents).
152
152
 
153
153
  ## 5. Apply the standards
154
154
 
@@ -158,17 +158,17 @@ Do only the standards the person agreed to. Copy every file from `node_modules/@
158
158
 
159
159
  **An existing project with code already in it** also needs its code brought up to the standards. Do that with [Migrating an Existing Project](/docs/Guides/migrating), one stage at a time, after the config files below are in place.
160
160
 
161
- | Standard | What to set up |
162
- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
163
- | 6. ESLint | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`, and copy `static/templates/eslint.overrides.mjs` beside it. Install the packages listed on the [ESLint page](/docs/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"` |
164
- | 7. Prettier | `pnpm add -D prettier prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the `format` and `format:check` scripts exactly as on the [Prettier page](/docs/Standards/prettier#usage) |
165
- | 8. Stylelint | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/docs/Standards/stylelint) |
166
- | 9. EditorConfig | Copy `static/templates/.editorconfig` |
167
- | 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv) |
168
- | 11. Styling | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette |
169
- | 12.1. Constants | Create `lib/constants/` with `routes.ts` (`r`), `strings.ts` (`s`), `numbers.ts` and an `index.ts` that exports them. Create `noData.ts` later, once the data's shape is decided. If the project keeps them somewhere else, such as `app/constants/`, move them. See [Constants](/docs/Structure/folder-structure#constants) |
170
- | 18. Docs | Copy `static/templates/docs/` to `docs/` and `static/templates/docsSite/` to `docsSite/`. Add the `/docs` route from `static/templates/next.config.mjs`. See [Setting it up](/docs/Standards/documentation#-setting-it-up) |
171
- | 21. AGENTS.md and skills | Copy `static/templates/AGENTS.md` to the project root and fill in every `[placeholder]`. If the framework wrote its own `AGENTS.md` (Next.js does), keep any instruction it gives about reading the framework's own docs. Copy `static/templates/skills/` into `.agents/skills/`, and again into `.claude/commands/`. Add the `standards:check` script: see [Checking a project](#checking-a-project) |
161
+ | Standard | What to set up |
162
+ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
163
+ | 6. ESLint | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`, and copy `static/templates/eslint.overrides.mjs` beside it. Install the packages listed on the [ESLint page](/docs/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"` |
164
+ | 7. Prettier | `pnpm add -D prettier prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the `format` and `format:check` scripts exactly as on the [Prettier page](/docs/Standards/prettier#usage) |
165
+ | 8. Stylelint | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/docs/Standards/stylelint) |
166
+ | 9. EditorConfig | Copy `static/templates/.editorconfig` |
167
+ | 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv) |
168
+ | 11. Styling | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette |
169
+ | 12.1. Constants | Create `lib/constants/` with `routes.ts` (`r`), `strings.ts` (`s`), `numbers.ts` and an `index.ts` that exports them. Create `noData.ts` later, once the data's shape is decided, and `animation.ts`, `artwork.ts` and `classNames.ts` once there is something to put in them. If the project keeps them somewhere else, such as `app/constants/`, move them. See [Constants](/docs/Structure/folder-structure#constants) |
170
+ | 18. Docs | Copy `static/templates/docs/` to `docs/` and `static/templates/docsSite/` to `docsSite/`. Add the `/docs` route from `static/templates/next.config.mjs`. See [Setting it up](/docs/Standards/documentation#-setting-it-up) |
171
+ | 21. AGENTS.md and skills | Copy `static/templates/AGENTS.md` to the project root and fill in every `[placeholder]`. If the framework wrote its own `AGENTS.md` (Next.js does), keep any instruction it gives about reading the framework's own docs. Copy `static/templates/skills/` into `.agents/skills/`, and again into `.claude/commands/`. Add the `standards:check` script: see [Checking a project](#checking-a-project) |
172
172
 
173
173
  The other standards are rules for how code is written. There is nothing to install for them: follow them in every change.
174
174
 
@@ -208,7 +208,7 @@ The project's `AGENTS.md` has the same major version as the installed package, s
208
208
 
209
209
  The project already follows the standards, and a newer version is out.
210
210
 
211
- **A patch keeps the same version number.** When only the last or middle number changes, such as 3.0.0 → 3.0.1 or 3.0.9 → 3.1.0, the project's version in `AGENTS.md` stays the same, but there may still be work to do. Update the package, then read that version's **Fixes** list and do anything it asks for the project's version. Check it every time the package is updated, even when the version number has not changed.
211
+ **A fix or a minor version keeps the same version number.** When only the last number changes (a fix, such as 3.0.0 → 3.0.1) or the middle number changes (a minor version, such as 3.0.9 → 3.1.0), the project's version in `AGENTS.md` stays the same, but there may still be work to do. Update the package, then read that version's **Fixes** list and do anything it asks for the project's version. Check it every time the package is updated, even when the version number has not changed.
212
212
 
213
213
  1. **Note the project's version.** Read `**Code standards version:**` in `AGENTS.md`. This is the version the code follows.
214
214
  2. **Update the package:**
@@ -252,7 +252,10 @@ It reports, and never changes a file. Each finding gives the standard's number a
252
252
  | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
253
253
  | 21 | `AGENTS.md` has the code standards version and an unchanged Code standards section; the skills match the templates |
254
254
  | 6 to 10 | `eslint.config.mjs`, `prettier.config.mjs`, `stylelint.config.mjs`, `.editorconfig` and `.envrc` match the templates; `eslint.overrides.mjs`, `.nvmrc` and the format scripts are in place |
255
- | 12.1 | `lib/constants/` has `index.ts`, `routes.ts`, `strings.ts` and `numbers.ts`, and no component has its own `constants.ts` |
255
+ | 12.1 | `lib/constants/` has `index.ts`, `routes.ts`, `strings.ts` and `numbers.ts`, no component has its own `constants.ts`, and no other file sits beside the seven standard ones |
256
+ | 13 | Every sub-component sits flat in its root component's `components/` folder, and the homepage is in `app/(homepage)/` |
257
+ | 21 | `docs/development/coding-standards.md` records the four agent answers under "Details" |
258
+ | 11 | `docs/design/design-system.md` has a filled-in Colour palette table |
256
259
  | 15 | Every `components/ui/` component is on the Design System Components list, or recorded under "Components for the standards" |
257
260
  | 4 | Every file that exports a function or component has a test file beside it |
258
261
  | 18 | Every doc template is in place, and every doc has one "Group — Menu item" title matching its file name, a Status line, and Decision, Why and Related sections |
@@ -196,8 +196,8 @@ const config = [
196
196
  rules: { "max-lines": "off", "no-magic-numbers": "off" },
197
197
  },
198
198
  {
199
- // r, s, numbers and noData are lists, not logic, so they can be long.
200
- files: ["lib/constants/{routes,strings,numbers,noData}.{js,mjs}"],
199
+ // The seven constants files are data, not logic, so they can be long.
200
+ files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.{js,mjs}"],
201
201
  rules: { "max-lines": "off" },
202
202
  },
203
203
  {
@@ -392,8 +392,8 @@ const config = [
392
392
  },
393
393
  },
394
394
  {
395
- // r, s, numbers and noData are lists, not logic, so they can be long.
396
- files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
395
+ // The seven constants files are data, not logic, so they can be long.
396
+ files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
397
397
  rules: { "max-lines": "off" },
398
398
  },
399
399
  {
@@ -627,8 +627,8 @@ const config = [
627
627
  },
628
628
  },
629
629
  {
630
- // r, s, numbers and noData are lists, not logic, so they can be long.
631
- files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
630
+ // The seven constants files are data, not logic, so they can be long.
631
+ files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
632
632
  rules: { "max-lines": "off" },
633
633
  },
634
634
  {
@@ -864,8 +864,8 @@ const config = [
864
864
  },
865
865
  },
866
866
  {
867
- // r, s, numbers and noData are lists, not logic, so they can be long.
868
- files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
867
+ // The seven constants files are data, not logic, so they can be long.
868
+ files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
869
869
  rules: { "max-lines": "off" },
870
870
  },
871
871
  {
@@ -1023,7 +1023,7 @@ Every `eslint-disable` comment must say why, after `--`. A rule is never switche
1023
1023
 
1024
1024
  ### `max-lines: 300`
1025
1025
 
1026
- No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt, and so are `lib/constants/routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts`, which hold data only. See [Readable Code](/docs/Standards/readable-code#no-file-longer-than-300-lines).
1026
+ No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt, and so are the seven constants files in `lib/constants/` (`routes.ts`, `strings.ts`, `numbers.ts`, `noData.ts`, `animation.ts`, `artwork.ts` and `classNames.ts`), which hold data only. See [Readable Code](/docs/Standards/readable-code#no-file-longer-than-300-lines).
1027
1027
 
1028
1028
  ### `max-depth: 3`
1029
1029
 
@@ -43,7 +43,7 @@ A file over 300 lines is doing more than one job. Split it before it gets there:
43
43
 
44
44
  Blank lines and comments do not count towards the limit. **Test files are exempt** — a thorough test file can run long.
45
45
 
46
- **`routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` in `lib/constants/` are exempt too.** They are lists of data, not logic, and a big app has a lot of links and text. Splitting them would mean more places to look for one label. They stay data only: no functions in them. See [Constants](/docs/Structure/folder-structure#constants).
46
+ **The seven constants files in `lib/constants/` are exempt too**: `routes.ts`, `strings.ts`, `numbers.ts`, `noData.ts`, `animation.ts`, `artwork.ts` and `classNames.ts`. They are lists of data, not logic, and a big app has a lot of links, text and motion. Splitting them would mean more places to look for one label. They stay data only: no functions in them. See [Constants](/docs/Structure/folder-structure#constants).
47
47
 
48
48
  ---
49
49
 
@@ -313,7 +313,7 @@ if (order.status === "shipped") {
313
313
 
314
314
  **`-1`, `0` and `1` are allowed**, because they are part of how code works rather than a choice anyone makes: `0` is the start or nothing (`items[0]`, `length === 0`), `1` is one more or one less (`index + 1`), and `-1` is "not found" (`indexOf`). Any other number was chosen by someone, so its name says what it controls. Even `2` gets a name.
315
315
 
316
- Every named number lives in `lib/constants/numbers.ts`, even one only one file uses. See [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic) for where they go, and [Naming Conventions](/docs/Structure/naming-conventions#constants) for how to name them.
316
+ Every loose named number lives in `lib/constants/numbers.ts`, even one only one file uses. Numbers that only mean something together, such as the steps of an animation, stay whole as one object in `animation.ts` or `artwork.ts`. See [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic) for where they go, and [Naming Conventions](/docs/Structure/naming-conventions#constants) for how to name them.
317
317
 
318
318
  ---
319
319
 
@@ -71,7 +71,11 @@ project-root/
71
71
  │ ├── constants/ # Constants shared across the app: see Constants below
72
72
  │ │ ├── routes.ts # r: every link
73
73
  │ │ ├── strings.ts # s: every piece of static text
74
+ │ │ ├── numbers.ts # Every loose named number
74
75
  │ │ ├── noData.ts # Stand-in data for local development
76
+ │ │ ├── animation.ts # How things move, once there is any
77
+ │ │ ├── artwork.ts # What is drawn and where, once there is any
78
+ │ │ ├── classNames.ts # Class names shared between files, once there are any
75
79
  │ │ └── index.ts
76
80
  │ ├── errors/ # Error types and handlers shared across the app
77
81
  │ └── types/ # Types shared across the app; a component's own types stay in its types.ts
@@ -295,19 +299,34 @@ Add the export to `utils/index.ts` whenever you add a function.
295
299
 
296
300
  ---
297
301
 
298
- ## 🔤 Constants: `r`, `s`, noData and numbers {#constants}
302
+ ## 🔤 Constants: `r`, `s`, numbers, noData, animation, artwork and class names {#constants}
299
303
 
300
- Every link, every piece of text on screen, every named number and every piece of stand-in data lives in `lib/constants/`, never written straight into a component. **There is no component-level `constants.ts`**: even a value only one file uses goes here, so every piece of text is in one place when the site is translated into other languages, and every number is named the same way.
304
+ Every link, every piece of text on screen, every named number, every piece of stand-in data, and every motion, drawing and shared class name lives in `lib/constants/`, never written straight into a component. **There is no component-level `constants.ts`**: even a value only one file uses goes here, so every piece of text is in one place when the site is translated into other languages, and every project finds its values in the same seven files.
301
305
 
302
306
  ```text
303
307
  lib/constants/
304
308
  ├── routes.ts # r: every link
305
309
  ├── strings.ts # s: every piece of static text
306
- ├── numbers.ts # Every named number
310
+ ├── numbers.ts # Every loose named number
307
311
  ├── noData.ts # Stand-in data, once the data's shape is decided
312
+ ├── animation.ts # How things move, once there is any
313
+ ├── artwork.ts # What is drawn and where, once there is any
314
+ ├── classNames.ts # Class names shared between files, once there are any
308
315
  └── index.ts # Exports all of them
309
316
  ```
310
317
 
318
+ **These seven files are the only ones.** Each is one file, never split by topic: no `durations.ts`, `motion.ts` or `layout.ts`. `routes.ts`, `strings.ts`, `numbers.ts` and `index.ts` exist from the start; the other four are created only once the project has something to put in them.
319
+
320
+ | A value that is… | Goes in |
321
+ | ----------------------------------------------------------- | ------------------- |
322
+ | A link | `r` in `routes.ts` |
323
+ | Text shown on screen | `s` in `strings.ts` |
324
+ | A single number with one job | `numbers.ts` |
325
+ | Fake data shaped like a real response | `noData.ts` |
326
+ | A group of values that together say how something moves | `animation.ts` |
327
+ | A group of values that together say what is drawn and where | `artwork.ts` |
328
+ | A Tailwind class string used by more than one file | `classNames.ts` |
329
+
311
330
  A file outside the folder imports everything it needs in one line:
312
331
 
313
332
  ```tsx
@@ -378,7 +397,26 @@ export const r = {
378
397
  <Link href={r.plans.team}>{s.plans.team.action}</Link>
379
398
  ```
380
399
 
381
- **Write each key out by name**, `r.plans.starter`, never a key held in a variable such as `r.plans[planId]`. A reader can see exactly which words and which link each line uses.
400
+ **Write each key out by name** when you mean one item: `r.plans.starter`, never `r.plans[planId]`. A reader can see exactly which words and which link each line uses.
401
+
402
+ **Inside a loop over the list, look each item up by its key.** A loop cannot name its items, so it reads `r` and `s` with the item's id, typed from `r` itself:
403
+
404
+ ```ts title="lib/types/index.ts"
405
+ import type { r } from "@/lib/constants";
406
+
407
+ export type SourceIdType = keyof typeof r.sources;
408
+ ```
409
+
410
+ ```tsx title="app/(homepage)/components/sourceList/SourceList.tsx"
411
+ {sourceIds.map((sourceId) => (
412
+ <Link key={sourceId} href={r.sources[sourceId]}>
413
+ {s.sources[sourceId].title}
414
+ </Link>
415
+ ))}
416
+ ```
417
+
418
+ - **The type comes from `r`**, so a missing or misspelt id fails the type check.
419
+ - **No separate lookup objects**, such as `SOURCE_ROUTES` or `PLAN_ROUTES` mapping an id to its link. `r.sources` already is that lookup: a second one is a copy that drifts out of step.
382
420
 
383
421
  ### noData: stand-in data for local development
384
422
 
@@ -416,18 +454,72 @@ const insights =
416
454
 
417
455
  **A number other than `-1`, `0` or `1` gets a name**, such as `MAXIMUM_RETRY_ATTEMPTS`. Those three mean "nothing", "one more" and "not found", so they read clearly as they are. Any other number was chosen by someone, and its name says what it controls. ESLint checks this with `no-magic-numbers`.
418
456
 
419
- **Every named number lives in `lib/constants/numbers.ts`**, even one that only one file uses, so every project finds its numbers in the same place. There is no `n` object: each number is its own `SCREAMING_SNAKE_CASE` export.
457
+ **Every loose named number lives in `lib/constants/numbers.ts`**, even one that only one file uses, so every project finds its numbers in the same place. There is no `n` object: each number is its own `SCREAMING_SNAKE_CASE` export.
420
458
 
421
459
  ```ts title="lib/constants/numbers.ts"
422
460
  export const COOKIE_DURATION_DAYS = 30;
423
461
  export const MAXIMUM_RETRY_ATTEMPTS = 3;
424
462
  export const SESSION_TIMEOUT_MILLISECONDS = 900_000;
463
+ export const TOOLTIP_SIDE_OFFSET_PIXELS = 8;
425
464
  ```
426
465
 
427
466
  - **One file, never split by topic.** `numbers.ts` can run past 300 lines, like `r` and `s`.
467
+ - **Loose numbers only.** A number that only means something beside other values, such as one swing in a choreography, stays inside its object in `animation.ts` or `artwork.ts`. It is never lifted out into `numbers.ts`.
428
468
  - **Config files and scripts outside the app**, such as `eslint.config.mjs`, keep their numbers at the top of the file: they are not part of the app and do not import from it.
429
469
  - **Put the unit in the name**: `_MILLISECONDS`, `_DAYS`, `_PIXELS`.
430
470
 
471
+ ### Animation: how things move
472
+
473
+ **`animation.ts` holds every object that says how something moves**: motion and choreography (`*_MOTION`), entrances, scroll stops, drift, zoom, scroll pacing, and motion media queries.
474
+
475
+ ```ts title="lib/constants/animation.ts"
476
+ export const CONFIDENCE_MOTION = {
477
+ pivot: "bearing-west",
478
+ ease: "easeInOut",
479
+ rounds: [
480
+ { degrees: 12, seconds: 0.6 },
481
+ { degrees: -8, seconds: 0.4 },
482
+ ],
483
+ snapSeconds: 0.2,
484
+ };
485
+
486
+ export const REDUCED_MOTION_QUERY =
487
+ "(prefers-reduced-motion: reduce)";
488
+ ```
489
+
490
+ - **Each object stays whole.** Its numbers, part names and eases only mean something together, so they stay in one object, named by their keys (`snapSeconds`). Never lift its numbers out into `numbers.ts`: `CONFIDENCE_ROUND_ONE_SWING_ONE_DEGREES` is harder to read, and splits one movement across files.
491
+ - **Part names and eases are not text on screen.** They are never shown or translated, so they stay in the object, not in `s`.
492
+ - **Put the unit in the key**: `seconds`, `degrees`, `snapSeconds`.
493
+
494
+ ### Artwork: what is drawn and where
495
+
496
+ **`artwork.ts` holds every object that says what is drawn and where**: card layouts and pieces, backdrop tiles, canvas sizes, shape positions and image paths.
497
+
498
+ ```ts title="lib/constants/artwork.ts"
499
+ export const HERO_CANVAS = { widthPixels: 1440, heightPixels: 900 };
500
+
501
+ export const BACKDROP_TILES = [
502
+ { image: "/images/backdrop/tileOne.webp", x: 0, y: 0 },
503
+ { image: "/images/backdrop/tileTwo.webp", x: 480, y: 0 },
504
+ ];
505
+ ```
506
+
507
+ - **Each object stays whole**, the same as in `animation.ts`.
508
+ - **An SVG drawing is a component or a file, never a string here.** Long SVG paths go in an `.svg` file in `public/` or in an icon component in `components/ui/`. `artwork.ts` says where a drawing goes, not what its path is.
509
+
510
+ ### Class names shared between files
511
+
512
+ **`classNames.ts` holds a Tailwind class string that more than one file uses**, such as the face of a card that a card and its sub-components all draw.
513
+
514
+ ```ts title="lib/constants/classNames.ts"
515
+ export const CARD_FACE_CLASS_NAME =
516
+ "rounded-2xl border border-border bg-card shadow-sm";
517
+ ```
518
+
519
+ - **Make a component first.** A class string repeated across files usually means a component is missing, and the component is what makes the styling reusable. Use `classNames.ts` only when a component cannot hold the classes and they still repeat, such as when they go on different elements.
520
+ - **A class name used in one file stays inline in that file.**
521
+ - **Name each export after what it styles, ending in `_CLASS_NAME`.**
522
+
431
523
  ### Rules
432
524
 
433
525
  - **Named exports only:** `export const r`, `export const s`. No default exports.
@@ -435,7 +527,7 @@ export const SESSION_TIMEOUT_MILLISECONDS = 900_000;
435
527
  - **Files inside `lib/constants/` import each other directly**, `import { s } from "./strings";`, never through `index.ts`. See [Inside a folder, import files directly](/docs/Structure/import-organization#2-inside-a-folder-import-files-directly).
436
528
  - **`r` and `s` are the only single-letter names allowed anywhere.** See [Human-Readable Names](/docs/Standards/human-readable-names#r-and-s).
437
529
  - **Other constants**, such as numbers, are `SCREAMING_SNAKE_CASE`: see [Naming Conventions](/docs/Structure/naming-conventions#constants).
438
- - **`routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` can run past 300 lines.** They are data only, so ESLint does not apply `max-lines` to them. Keep each one a single file: never split them to get under the limit.
530
+ - **All seven files can run past 300 lines.** They are data only, so ESLint does not apply `max-lines` to them. Keep each one a single file: never split them to get under the limit.
439
531
  - **`lib/constants/` never imports from `lib/types/`.** `lib/types/` reads some of its types from the constants (`typeof s`), so an import the other way makes a loop. When a constant needs a type, write the type beside the constant, or read it from the constant.
440
532
 
441
533
  ---
@@ -27,7 +27,7 @@ sidebar_label: "Version History"
27
27
  8. **Run `pnpm standards:check`**, and fix what it finds. See [Checking a project](/docs/Guides/setup#checking-a-project).
28
28
  9. **Update the version number** in `AGENTS.md` once every change is done.
29
29
 
30
- **A patch keeps the same version number.** When only the last or middle number changes, such as 3.0.0 → 3.0.1 or 3.0.9 → 3.1.0, the project's version in `AGENTS.md` stays the same, but there may still be work to do. Update the package, then read that version's **Fixes** list and do anything it asks for the project's version. Check it every time the package is updated, even when the version number has not changed. A project already on the installed major version is never "nothing to do": follow [Already on this version](/docs/Guides/setup#already-on-this-version).
30
+ **A fix or a minor version keeps the same version number.** When only the last number changes (a fix, such as 3.0.0 → 3.0.1) or the middle number changes (a minor version, such as 3.0.9 → 3.1.0), the project's version in `AGENTS.md` stays the same, but there may still be work to do. Update the package, then read that version's **Fixes** list and do anything it asks for the project's version. Check it every time the package is updated, even when the version number has not changed. A project already on the installed major version is never "nothing to do": follow [Already on this version](/docs/Guides/setup#already-on-this-version).
31
31
 
32
32
  **When a change does not fit the project**, for example it renames a folder the project does not have, skip it. If you are not sure, ask; do not guess.
33
33
 
@@ -44,6 +44,7 @@ Anyone changing the standards adds a version, alongside the change:
44
44
  - **Pilot a version in a real project before releasing it.** Once the work-in-progress version is written, have one real project apply it exactly as written, reading only what the page says. Every judgement call the agent has to make, and every instruction that does not fit the project, is a missing sentence: fold it back into the version before publishing. Release only when the pilot runs without the agent asking a question the page does not answer.
45
45
  - **Fixing a released version** bumps only the last number: `3.0.0` → `3.0.1`. Update the version's changes in place, and list what was fixed under its **Fixes**. Projects keep the same version number in `AGENTS.md`. Write each fix so a project already on that version knows what to do.
46
46
  - **Adding something optional** to a released version, such as a new setup question, bumps the middle number: `3.0.9` → `3.1.0`. It is written up the same way as a fix, and projects keep the same version number in `AGENTS.md`.
47
+ - **Changes that move files are listed under Structural changes.** At the top of the version's Fixes, list each change that moves or renames files in a project, with a rough size, such as "moves every component `constants.ts`", so a project can plan the work and run a [regression check](/docs/Guides/regression-checks) first. For now, structural changes ship in fix and minor versions; once the standards settle, they will wait for the next major version.
47
48
  - **Every release commit is titled `docs: version N.N.N — <what changed>`**, such as `docs: version 3.0.9 — optional project links`, so releases are easy to find in the git log.
48
49
  - **Every patch number is published.** Publish each patch to npm as soon as its Fixes are written. A Fixes entry for a version that was never published sends a project to install something that does not exist.
49
50
  - **Judgement calls after release are fixes, not workarounds.** When a project's update needed a call the steps did not cover, add it under the version's Fixes so every other project gets it too. A project should never keep a private workaround for an unclear step.
@@ -52,12 +53,38 @@ Anyone changing the standards adds a version, alongside the change:
52
53
 
53
54
  ## Version 3
54
55
 
55
- **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.2.0
56
+ **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.2.1
56
57
 
57
58
  Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
58
59
 
60
+ **Fixes in 3.2.1.** If the project already applied 3.2.0, check these:
61
+
62
+ **Structural changes in 3.2.1.** These move files. Plan them, and run a [regression check](/docs/Guides/regression-checks) first:
63
+
64
+ - Every component `constants.ts` and every topic file in `lib/constants/` (`motion.ts`, `durations.ts`, `cardRail.ts`) moves into the seven standard files. Large on a site with many components: the Activatus homepage has 36 component files and 3 topic files. `pnpm standards:check` names the file each export goes to.
65
+ - Sub-component folders inside a grouping folder, such as `lifeActivated/outcomeArtwork/alignmentArtwork/`, move flat into the parent's `components/` folder. Small: the 3.1.1 step already moved most of them.
66
+
67
+ - **`lib/constants/` has seven standard files:** `routes.ts`, `strings.ts`, `numbers.ts`, `noData.ts`, and three new ones, created only once there is something to put in them:
68
+ - **`animation.ts`**: how things move. Motion and choreography objects (`*_MOTION`), entrances, scroll stops, drift, zoom, scroll pacing and motion media queries.
69
+ - **`artwork.ts`**: what is drawn and where. Layouts, card pieces, backdrop tiles, canvas sizes and image paths. Long SVG paths go in an `.svg` file in `public/` or an icon component, never here.
70
+ - **`classNames.ts`**: Tailwind class strings shared between files, only when a component cannot hold them and they still repeat. A class name one file uses stays inline.
71
+
72
+ Each animation and artwork object stays whole, its numbers named by their keys (`snapSeconds`). Never lift them out into `numbers.ts`, which keeps loose single numbers only. Lifting them out made names like `CONFIDENCE_ROUND_ONE_SWING_ONE_DEGREES` and split one movement across files; the reasons for one numbers file (translation, one place to look) do not apply to motion and drawing data. Each file is one file, never split by topic. See [Constants](/docs/Structure/folder-structure#constants).
73
+
74
+ **What to do:** move every component `constants.ts`, and every other file in `lib/constants/`, into the seven files. A topic file such as `motion.ts` is folded into `animation.ts`. Run `pnpm standards:check`: each finding names the file each export most likely belongs in; check each against the [Constants table](/docs/Structure/folder-structure#constants). In `eslint.config.mjs`, copy the template over it again: the `max-lines` block now reads `lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts`. Copy the Constants rules into `AGENTS.md` from the template.
75
+
76
+ - **A loop over a list looks each item up by its id.** Write a key out by name when you mean one item, `r.plans.starter`. Inside a loop over the list, use the item's id, typed from `r`: `keyof typeof r.sources`. Delete separate lookup objects that map an id to its link, such as `SOURCE_ROUTES` or `PLAN_ROUTES`: `r` already is that lookup. See [A list of items with links](/docs/Structure/folder-structure#a-list-of-items-with-links).
77
+
78
+ - **`pnpm standards:check` checks more of the How to check lists:** sub-components sit flat in their root component's `components/` folder; the homepage is in `app/(homepage)/`; `docs/development/coding-standards.md` records the four agent answers under "Details"; `docs/design/design-system.md` has a filled-in Colour palette table; and `lib/constants/` holds only the seven standard files. Fix what it finds.
79
+
80
+ - **Keep every docs folder.** 3.2.0's rule is final: no docs folder is deleted, even one that does not apply yet.
81
+
82
+ **How to check:** `pnpm standards:check` passes, or lists only recorded exceptions; `lib/constants/` holds only the seven standard files and `index.ts`; no component has its own `constants.ts`.
83
+
59
84
  **Fixes in 3.2.0.** If the project already applied 3.1.1, check these:
60
85
 
86
+ **Structural changes in 3.2.0.** Only one: restore any docs folder deleted under 3.1.1, from the templates. Small.
87
+
61
88
  - **A standards check ships with the package.** Add the script `"standards:check": "node node_modules/@activatus/code-standards/scripts/verifyStandards/verifyStandards.mjs"` to `package.json`, run `pnpm standards:check`, and fix what it finds. It follows the exceptions recorded in `docs/development/coding-standards.md`. See [Checking a project](/docs/Guides/setup#checking-a-project). Copy the Code standards section of `AGENTS.md` from the template again: it now says to run the check.
62
89
  - **Keep every docs folder and file**, even ones that do not apply yet. 3.1.1 allowed deleting a folder that could not apply; that is withdrawn, because the folders keep every project's docs laid out the same and a small project grows into them. Restore any folder deleted under 3.1.1 from the templates, and remove its entry from `coding-standards.md`.
63
90
  - **The React version lives in `eslint.overrides.mjs`.** A project on a React version other than 19 sets `{ settings: { react: { version: "19.2" } } }` there, and copies the template over `eslint.config.mjs` unchanged.
@@ -69,6 +96,14 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
69
96
 
70
97
  **Fixes in 3.1.1.** If the project already applied 3.1.0, check these:
71
98
 
99
+ **Structural changes in 3.1.1.** These move files. Plan them, and run a [regression check](/docs/Guides/regression-checks) first:
100
+
101
+ - The homepage moves into `app/(homepage)/`: `app/page.tsx` and the homepage's components. Small.
102
+ - The site frame moves into `components/layout/`: the navigation, header and footer. Small.
103
+ - Every component `constants.ts` moves into `lib/constants/`. Large on a site with many components: the Activatus homepage had 36. Follow the 3.2.1 rule, not this version's.
104
+ - Every nested sub-component folder moves flat into its parent's `components/` folder. Medium to large: the Activatus homepage had 28.
105
+ - `r` or `s` split into several files only to stay under 300 lines goes back into one file. Small.
106
+
72
107
  - **`routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` can run past 300 lines.** They hold data only, so `max-lines` no longer applies to them. Splitting `r` or `s` across files to stay under 300 lines only made labels harder to find. In `eslint.config.mjs`, add this block straight after the test-file block:
73
108
 
74
109
  ```js
@@ -93,8 +128,8 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
93
128
  - **The site frame lives in `components/layout/`**: navigation, header, footer and anything else that frames the pages. It may read `r` and `s`. Move those components there from `components/shared/` or `app/components/`. Layout primitives such as Duplex stay in `components/ui/`.
94
129
  - **A props-only component that is not on the Design System Components list stays in `components/ui/`.** Record it, with its props, in `docs/development/coding-standards.md`, under a new "Components for the standards" heading (copy it from the template), and tell the person. Move back into `components/ui/` any such component that was moved out only because it was not listed.
95
130
  - **Four components joined the list:** Brand Logo, Notification Card, Scroll Cue and Dropdown Menu. If the project has them, check their props match the [list](/docs/design-system-components).
96
- - **Every named number lives in `lib/constants/numbers.ts`**, even one only one file uses, in one file that is never split. Move numbers from the tops of app files and from any topic files (`durations.ts`, `limits.ts`) into it. Config files and scripts outside the app keep theirs at the top.
97
- - **No component-level `constants.ts`.** Every link, piece of text and number goes in `lib/constants/`, even if one file uses it, so all the text is in one place for translation. Move any component's `constants.ts` into `r`, `s` and `numbers.ts`.
131
+ - **Every named number lives in `lib/constants/numbers.ts`**, even one only one file uses, in one file that is never split. Move numbers from the tops of app files and from any topic files (`durations.ts`, `limits.ts`) into it. _Changed in 3.2.1: motion and artwork objects stay whole in `animation.ts` and `artwork.ts`. Do the 3.2.1 step instead of moving their numbers here._ Config files and scripts outside the app keep theirs at the top.
132
+ - **No component-level `constants.ts`.** Every link, piece of text and number goes in `lib/constants/`, even if one file uses it, so all the text is in one place for translation. Move any component's `constants.ts` into `r`, `s` and `numbers.ts`. _Changed in 3.2.1: there are seven constants files to move into. Do the 3.2.1 step instead._
98
133
  - **Write `r` and `s` keys out by name**, `r.plans.starter`, never `r.plans[planId]`. A list of items keeps its words in `s` and its links in `r` under the same keys. See [A list of items with links](/docs/Structure/folder-structure#a-list-of-items-with-links).
99
134
  - **No `"#"` placeholder links.** Show the text without a link and put `{/* TODO: … */}` above it until the page exists. Unfinished work is marked `// TODO: Message`.
100
135
  - **`lib/constants/` never imports from `lib/types/`.** Move any type it imports from there beside the constant.
@@ -103,7 +138,7 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
103
138
  - **The palette is listed in `docs/design/design-system.md`**: each colour's name, value, class names and use. `globals.css` holds only colours Tailwind does not have. Copy the Colour palette section from the template and fill it in.
104
139
  - **AGENTS.md: the Code standards section sits between `<!-- code-standards:start -->` and `<!-- code-standards:end -->`**, and an update replaces everything between them. Copy the section from the template, markers included. Move any project exception written into it into `docs/development/coding-standards.md`, and anything else the project added, such as a framework's block, outside the markers.
105
140
  - **Docs:** copy the new `docs/product/ontology.md` template if the project has none, and ask the person to review it. Fix the link in `overview/writing-docs.md` if `what-is-it.md` was renamed. Retitle `how-it-works.md` "Overview — How It Works". Delete any version 2 leftovers: `_category_.json`, the `sidebar_position`, `sidebar_label`, `slug`, `status` and `lastReviewed` front matter, and `docs/index.md`.
106
- - **Decision Docs are confirmed with the person** before an agent creates, changes or deletes one, unless `AGENTS.md` names an agent that manages them. A folder that cannot apply may be deleted with the person's yes, recorded in `coding-standards.md`. Moving or reformatting a doc does not change its Updated date.
141
+ - **Decision Docs are confirmed with the person** before an agent creates, changes or deletes one, unless `AGENTS.md` names an agent that manages them. ~~A folder that cannot apply may be deleted with the person's yes, recorded in `coding-standards.md`.~~ _Withdrawn in 3.2.0: keep every folder._ Moving or reformatting a doc does not change its Updated date.
107
142
  - **Stylelint configs name their export:** `const config = { … }; export default config;`. Change the project's `stylelint.config.mjs` to match.
108
143
  - **The Linear ticket prefix is the team's, not the project's.** In `AGENTS.md`, Project workflow, write the Linear workspace, team and project, such as `activatus-life`, team `ACT`, project Launchpad.
109
144
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@activatus/code-standards",
3
- "version": "3.2.0",
3
+ "version": "3.2.1",
4
4
  "description": "The Activatus code standards: the rules as Markdown, and the config files to copy. Install it so an AI agent can read the standards from node_modules.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -0,0 +1,127 @@
1
+ // Standard 12.1: lib/constants/ holds the seven standard files and
2
+ // nothing else, and no component keeps its own constants file.
3
+ import { readTextFile } from "./projectFiles.mjs";
4
+
5
+ const REQUIRED_FILES = [
6
+ "lib/constants/index.ts",
7
+ "lib/constants/routes.ts",
8
+ "lib/constants/strings.ts",
9
+ "lib/constants/numbers.ts",
10
+ ];
11
+ // Created only once the project has something to put in them.
12
+ const OPTIONAL_FILES = [
13
+ "lib/constants/noData.ts",
14
+ "lib/constants/animation.ts",
15
+ "lib/constants/artwork.ts",
16
+ "lib/constants/classNames.ts",
17
+ ];
18
+ const CONSTANTS_FOLDER = "lib/constants/";
19
+ const COMPONENT_CONSTANTS_PATTERN = /(^|\/)constants\.tsx?$/;
20
+ const CODE_FILE_PATTERN = /\.(?:ts|tsx|js|mjs)$/;
21
+ const EXPORT_PATTERN =
22
+ /^export const ([\w$]+)\s*(?::[^=]+)?=\s*(\S)/gm;
23
+ const MAXIMUM_NAMES_SHOWN = 3;
24
+ const PAGE = "docs/Structure/folder-structure.md#constants";
25
+
26
+ const UNSURE_HOME = "the file the Constants table names";
27
+
28
+ // The name says what most exports are; the first character of the
29
+ // value settles the rest. Checked in this order.
30
+ const NAME_HOMES = [
31
+ { pattern: /CLASS_NAMES?$/, home: "classNames.ts" },
32
+ {
33
+ pattern:
34
+ /MOTION|ANIMATION|ENTRANCE|SCROLL|DRIFT|ZOOM|EASE|SPRING|TRANSITION|KEYFRAME|QUERY|QUERIES/,
35
+ home: "animation.ts",
36
+ },
37
+ {
38
+ pattern:
39
+ /ARTWORK|LAYOUT|SHAPE|PATH|CANVAS|TILE|IMAGE|PIECE|GEOMETRY|SVG/,
40
+ home: "artwork.ts",
41
+ },
42
+ { pattern: /ROUTE|HREF|LINK|URL/, home: "r in routes.ts" },
43
+ { pattern: /^NO_DATA_|^DUMMY_/, home: "noData.ts" },
44
+ // Raw CSS is not text for s, and not a class name.
45
+ { pattern: /STYLES?$/, home: UNSURE_HOME },
46
+ ];
47
+ const VALUE_HOMES = [
48
+ { pattern: /[\d-]/, home: "numbers.ts" },
49
+ { pattern: /["'`]/, home: "s in strings.ts" },
50
+ ];
51
+
52
+ const findHome = ({ name, valueStart }) =>
53
+ NAME_HOMES.find(({ pattern }) => pattern.test(name))?.home ??
54
+ VALUE_HOMES.find(({ pattern }) => pattern.test(valueStart))?.home ??
55
+ UNSURE_HOME;
56
+
57
+ const describeNames = (names) => {
58
+ const shown = names.slice(0, MAXIMUM_NAMES_SHOWN).join(", ");
59
+ const hiddenCount = names.length - MAXIMUM_NAMES_SHOWN;
60
+ return hiddenCount > 0 ? `${shown} and ${hiddenCount} more` : shown;
61
+ };
62
+
63
+ // "Move CONFIDENCE_MOTION to animation.ts; CARD_FACE_CLASS_NAME to
64
+ // classNames.ts".
65
+ const suggestHomes = ({ projectDirectory, filePath }) => {
66
+ const source = readTextFile({ projectDirectory, filePath }) ?? "";
67
+ // Map.groupBy needs Node 21, and the package supports Node 20.
68
+ const namesByHome = new Map();
69
+ for (const [, name, valueStart] of source.matchAll(
70
+ EXPORT_PATTERN,
71
+ )) {
72
+ const home = findHome({ name, valueStart });
73
+ namesByHome.set(home, [...(namesByHome.get(home) ?? []), name]);
74
+ }
75
+ const moves = [...namesByHome].map(
76
+ ([home, names]) => `${describeNames(names)} to ${home}`,
77
+ );
78
+ return moves.length > 0
79
+ ? `Move ${moves.join("; ")}`
80
+ : "Move its values into the seven files in lib/constants/";
81
+ };
82
+
83
+ const checkMissingFiles = ({ projectFileSet }) =>
84
+ REQUIRED_FILES.filter(
85
+ (filePath) => !projectFileSet.has(filePath),
86
+ ).map((filePath) => ({
87
+ standard: "12.1",
88
+ message: `${filePath} is missing`,
89
+ page: PAGE,
90
+ }));
91
+
92
+ const checkExtraFiles = ({ projectDirectory, projectFiles }) => {
93
+ const standardFiles = new Set([
94
+ ...REQUIRED_FILES,
95
+ ...OPTIONAL_FILES,
96
+ ]);
97
+ return projectFiles
98
+ .filter((filePath) => filePath.startsWith(CONSTANTS_FOLDER))
99
+ .filter((filePath) => CODE_FILE_PATTERN.test(filePath))
100
+ .filter((filePath) => !filePath.includes(".test."))
101
+ .filter((filePath) => !standardFiles.has(filePath))
102
+ .map((filePath) => ({
103
+ standard: "12.1",
104
+ message: `${filePath} is not one of the seven constants files. ${suggestHomes({ projectDirectory, filePath })}`,
105
+ page: PAGE,
106
+ }));
107
+ };
108
+
109
+ const checkComponentFiles = ({ projectDirectory, projectFiles }) =>
110
+ projectFiles
111
+ .filter((filePath) => !filePath.startsWith(CONSTANTS_FOLDER))
112
+ .filter((filePath) => !filePath.startsWith("node_modules/"))
113
+ .filter((filePath) => COMPONENT_CONSTANTS_PATTERN.test(filePath))
114
+ .map((filePath) => ({
115
+ standard: "12.1",
116
+ message: `${filePath}: there is no component-level constants file. ${suggestHomes({ projectDirectory, filePath })}`,
117
+ page: PAGE,
118
+ }));
119
+
120
+ export const checkConstants = ({
121
+ projectDirectory,
122
+ projectFiles,
123
+ }) => [
124
+ ...checkMissingFiles({ projectFileSet: new Set(projectFiles) }),
125
+ ...checkExtraFiles({ projectDirectory, projectFiles }),
126
+ ...checkComponentFiles({ projectDirectory, projectFiles }),
127
+ ];
@@ -0,0 +1,83 @@
1
+ // What setup asks the person and writes down: the four agent answers
2
+ // (standard 21) and the colour palette (standard 11).
3
+ import {
4
+ CODING_STANDARDS_PATH,
5
+ readSection,
6
+ readTextFile,
7
+ } from "./projectFiles.mjs";
8
+
9
+ const DESIGN_SYSTEM_PATH = "docs/design/design-system.md";
10
+ const AGENT_ANSWERS = [
11
+ { name: "the GitHub repo", pattern: /github/i },
12
+ { name: "the Linear project", pattern: /linear/i },
13
+ { name: "the status circles", pattern: /status circles?/i },
14
+ { name: "asking before committing", pattern: /commit/i },
15
+ ];
16
+ // The template's unfilled line: "[link or None]", "[yes or no]".
17
+ const UNFILLED_ANSWER_PATTERN = /\[[^\]]+ or [^\]]+\]/;
18
+ const TABLE_ROW_PATTERN = /^\|/;
19
+ const TABLE_SEPARATOR_PATTERN = /^\|[\s:|-]+\|$/;
20
+ const PLACEHOLDER_ROW_PATTERN = /^\|\s*\[/;
21
+ // The header row comes before the separator.
22
+ const HEADER_ROW_COUNT = 1;
23
+
24
+ const checkAgentAnswers = ({ projectDirectory }) => {
25
+ const markdown = readTextFile({
26
+ projectDirectory,
27
+ filePath: CODING_STANDARDS_PATH,
28
+ });
29
+ if (markdown === undefined) {
30
+ return [];
31
+ }
32
+ const details = readSection({ markdown, heading: "Details" })
33
+ .split("\n")
34
+ .filter((line) => !UNFILLED_ANSWER_PATTERN.test(line))
35
+ .join("\n");
36
+ return AGENT_ANSWERS.filter(
37
+ ({ pattern }) => !pattern.test(details),
38
+ ).map(({ name }) => ({
39
+ standard: "21",
40
+ message: `${CODING_STANDARDS_PATH} does not record ${name} under "Details". Ask the person, and write their answer down, even if it is "None" or "No"`,
41
+ page: "docs/Guides/setup.md#4-working-with-the-agent",
42
+ }));
43
+ };
44
+
45
+ const readPaletteRows = ({ section }) =>
46
+ section
47
+ .split("\n")
48
+ .map((line) => line.trim())
49
+ .filter((line) => TABLE_ROW_PATTERN.test(line))
50
+ .filter((line) => !TABLE_SEPARATOR_PATTERN.test(line))
51
+ .slice(HEADER_ROW_COUNT);
52
+
53
+ const checkPalette = ({ projectDirectory }) => {
54
+ const markdown = readTextFile({
55
+ projectDirectory,
56
+ filePath: DESIGN_SYSTEM_PATH,
57
+ });
58
+ if (markdown === undefined) {
59
+ return [];
60
+ }
61
+ const section = readSection({
62
+ markdown,
63
+ heading: "Colour palette",
64
+ });
65
+ const rows = readPaletteRows({ section });
66
+ const isFilledIn =
67
+ rows.length > 0 &&
68
+ rows.every((row) => !PLACEHOLDER_ROW_PATTERN.test(row));
69
+ return isFilledIn
70
+ ? []
71
+ : [
72
+ {
73
+ standard: "11",
74
+ message: `${DESIGN_SYSTEM_PATH} has no filled-in "## Colour palette" table. List each colour, its value, its class names and what it is for`,
75
+ page: "docs/Standards/styling.md#-colours-always-come-from-global-variables",
76
+ },
77
+ ];
78
+ };
79
+
80
+ export const checkRecordedAnswers = ({ projectDirectory }) => [
81
+ ...checkAgentAnswers({ projectDirectory }),
82
+ ...checkPalette({ projectDirectory }),
83
+ ];
@@ -1,19 +1,12 @@
1
- // Standards 12.1 and 18: the files every project has.
1
+ // Standards 18 and 21: the docs every project has.
2
2
  import { readdirSync, statSync } from "node:fs";
3
3
  import path from "node:path";
4
4
 
5
5
  import { CODING_STANDARDS_PATH } from "./projectFiles.mjs";
6
6
 
7
- const CONSTANTS_FILES = [
8
- "lib/constants/index.ts",
9
- "lib/constants/routes.ts",
10
- "lib/constants/strings.ts",
11
- "lib/constants/numbers.ts",
12
- ];
13
7
  // Setup renames this file after the project: what-is-launchpad.md.
14
8
  const RENAMED_OVERVIEW_PATH = "overview/what-is-it.md";
15
9
  const RENAMED_OVERVIEW_PATTERN = /^docs\/overview\/what-is-.+\.md$/;
16
- const COMPONENT_CONSTANTS_PATTERN = /(^|\/)constants\.tsx?$/;
17
10
 
18
11
  const listTemplateDocs = ({ directory, prefix = "" }) =>
19
12
  readdirSync(directory).flatMap((entry) => {
@@ -54,27 +47,6 @@ const checkDocsFiles = ({ templatesDirectory, projectFiles }) => {
54
47
  }));
55
48
  };
56
49
 
57
- const checkConstantsFiles = ({ projectFiles }) => {
58
- const projectFileSet = new Set(projectFiles);
59
- const missing = CONSTANTS_FILES.filter(
60
- (filePath) => !projectFileSet.has(filePath),
61
- ).map((filePath) => ({
62
- standard: "12.1",
63
- message: `${filePath} is missing`,
64
- page: "docs/Structure/folder-structure.md#constants",
65
- }));
66
- const componentConstants = projectFiles
67
- .filter((filePath) => !filePath.startsWith("lib/constants/"))
68
- .filter((filePath) => !filePath.startsWith("node_modules/"))
69
- .filter((filePath) => COMPONENT_CONSTANTS_PATTERN.test(filePath))
70
- .map((filePath) => ({
71
- standard: "12.1",
72
- message: `${filePath}: there is no component-level constants file. Move its values into r, s and numbers.ts in lib/constants/`,
73
- page: "docs/Structure/folder-structure.md#constants",
74
- }));
75
- return [...missing, ...componentConstants];
76
- };
77
-
78
50
  export const checkRequiredFiles = ({
79
51
  templatesDirectory,
80
52
  projectFiles,
@@ -91,6 +63,5 @@ export const checkRequiredFiles = ({
91
63
  return [
92
64
  ...codingStandards,
93
65
  ...checkDocsFiles({ templatesDirectory, projectFiles }),
94
- ...checkConstantsFiles({ projectFiles }),
95
66
  ];
96
67
  };
@@ -0,0 +1,79 @@
1
+ // Standard 13: components sit at most two levels deep, the component
2
+ // then its sub-components, and the homepage is in app/(homepage)/.
3
+ import path from "node:path";
4
+
5
+ const COMPONENT_FILE_PATTERN = /^[A-Z][A-Za-z0-9]*\.(?:tsx|jsx)$/;
6
+ const COMPONENTS_FOLDER = "components";
7
+ const UNGROUPED_HOMEPAGE_PATTERN =
8
+ /^(?:src\/)?app\/page\.(?:tsx|jsx)$/;
9
+ const NESTED_PAGE =
10
+ "docs/Structure/component-organization.md#nested-components";
11
+
12
+ // A component folder holds a PascalCase component file, Card.tsx.
13
+ const listComponentFolders = ({ projectFiles }) =>
14
+ new Set(
15
+ projectFiles
16
+ .filter((filePath) => !filePath.startsWith("node_modules/"))
17
+ .filter((filePath) =>
18
+ COMPONENT_FILE_PATTERN.test(path.posix.basename(filePath)),
19
+ )
20
+ .map((filePath) => path.posix.dirname(filePath)),
21
+ );
22
+
23
+ // The topmost component folder above this one, or undefined for a
24
+ // component that is not inside another.
25
+ const findRootComponent = ({ folder, componentFolders }) => {
26
+ const ancestors = [];
27
+ // eslint-disable-next-line no-restricted-syntax -- walks up one folder at a time
28
+ let parent = path.posix.dirname(folder);
29
+ while (parent !== ".") {
30
+ ancestors.push(parent);
31
+ parent = path.posix.dirname(parent);
32
+ }
33
+ return ancestors.findLast((ancestor) =>
34
+ componentFolders.has(ancestor),
35
+ );
36
+ };
37
+
38
+ // A sub-component's only home is its root component's components/
39
+ // folder: card/components/cardHeader/. Never card/cardHeader/,
40
+ // card/parts/cardHeader/ or card/components/cardHeader/components/.
41
+ const checkSubComponentFolders = ({ componentFolders }) =>
42
+ [...componentFolders]
43
+ .map((folder) => ({
44
+ folder,
45
+ rootComponent: findRootComponent({ folder, componentFolders }),
46
+ }))
47
+ .filter(({ rootComponent }) => rootComponent !== undefined)
48
+ .map(({ folder, rootComponent }) => ({
49
+ folder,
50
+ rootComponent,
51
+ flatFolder: path.posix.join(
52
+ rootComponent,
53
+ COMPONENTS_FOLDER,
54
+ path.posix.basename(folder),
55
+ ),
56
+ }))
57
+ .filter(({ folder, flatFolder }) => folder !== flatFolder)
58
+ .map(({ folder, rootComponent, flatFolder }) => ({
59
+ standard: "13",
60
+ message: `${folder} is not flat in ${rootComponent}/${COMPONENTS_FOLDER}/. Move it to ${flatFolder}`,
61
+ page: NESTED_PAGE,
62
+ }));
63
+
64
+ const checkHomepage = ({ projectFiles }) =>
65
+ projectFiles
66
+ .filter((filePath) => UNGROUPED_HOMEPAGE_PATTERN.test(filePath))
67
+ .map((filePath) => ({
68
+ standard: "13",
69
+ message: `${filePath} is the homepage outside its route group. Move it to app/(homepage)/`,
70
+ page: "docs/Structure/folder-structure.md#-where-components-live",
71
+ }));
72
+
73
+ export const checkStructure = ({ projectFiles }) => {
74
+ const componentFolders = listComponentFolders({ projectFiles });
75
+ return [
76
+ ...checkSubComponentFolders({ componentFolders }),
77
+ ...checkHomepage({ projectFiles }),
78
+ ];
79
+ };
@@ -7,7 +7,10 @@ import { checkAgentFiles } from "./checkAgentFiles.mjs";
7
7
  import { checkComponents } from "./checkComponents.mjs";
8
8
  import { checkConfigFiles } from "./checkConfigFiles.mjs";
9
9
  import { checkDocs } from "./checkDocs.mjs";
10
+ import { checkConstants } from "./checkConstants.mjs";
11
+ import { checkRecordedAnswers } from "./checkRecordedAnswers.mjs";
10
12
  import { checkRequiredFiles } from "./checkRequiredFiles.mjs";
13
+ import { checkStructure } from "./checkStructure.mjs";
11
14
  import {
12
15
  listProjectFiles,
13
16
  PACKAGE_DIRECTORY,
@@ -44,6 +47,9 @@ export const runChecks = ({ projectDirectory }) => {
44
47
  }),
45
48
  ...checkConfigFiles({ projectDirectory, templatesDirectory }),
46
49
  ...checkRequiredFiles({ templatesDirectory, projectFiles }),
50
+ ...checkConstants({ projectDirectory, projectFiles }),
51
+ ...checkStructure({ projectFiles }),
52
+ ...checkRecordedAnswers({ projectDirectory }),
47
53
  ...checkComponents({
48
54
  projectDirectory,
49
55
  projectFiles,
@@ -120,7 +120,7 @@ This is the version the code follows. It is the major version only: fixes such a
120
120
  Follow these rules in every change:
121
121
 
122
122
  - **Every function and component has a test file**, created in the same change. One test file tests one function or one component.
123
- - **No file longer than 300 lines.** Test files are exempt, and so are `routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` in `lib/constants/`, which hold data only.
123
+ - **No file longer than 300 lines.** Test files are exempt, and so are the seven constants files in `lib/constants/`, which hold data only.
124
124
  - **Every name is made of whole, human-readable words.** Variables, parameters, props, types, constants, form fields, files, folders, routes, database columns, scripts and environment variables — everything. No shortened words, no single letters (except `r` and `s`, below), no numbered names, not even for a loop counter or an event handler. Full rule: Human-Readable Names in the code standards (https://activatus-code-standards.vercel.app/docs/Standards/human-readable-names).
125
125
 
126
126
  | Never | Always |
@@ -145,8 +145,8 @@ Follow these rules in every change:
145
145
  - **Functions, never classes.**
146
146
  - **One parameter per function.** Use a single object when more than one value is needed.
147
147
  - **Return early.** Never nest more than three levels deep.
148
- - **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. Every named number goes in `lib/constants/numbers.ts`, even one only one file uses; config files keep theirs at the top. Put the unit in the name: `SESSION_TIMEOUT_MILLISECONDS`.
149
- - **Links, text and stand-in data live in `lib/constants/`**, never written straight into a component. `r` holds every link (pages, outside sites, `mailto:`, `tel:`, `sms:`). `s` holds every piece of static text, and its keys become the translation keys when the site gets more languages. `noData.ts` holds stand-in data named `NO_DATA_` plus the thing it replaces (`NO_DATA_INSIGHTS`), used only in local development when the real source can't be reached, never in production. Dummy values sit at the top of `noData.ts`, never in `s`. There is no component-level `constants.ts`: every link, piece of text and number goes in `lib/constants/`, even if one file uses it. `lib/constants/` never imports from `lib/types/`. Write each key out by name, `r.plans.starter`, never `r.plans[planId]`. No `"#"` placeholder links: show plain text with a `{/* TODO: … */}` until the page exists. Create `noData.ts` only once the data's shape is decided; stand-in data asked for before then carries `// Not the real schema: a basic shape to finish the task.` Import them all in one line, `import { NO_DATA_INSIGHTS, r, s } from "@/lib/constants";`. `r` and `s` are the only single-letter names allowed anywhere. Full rule: https://activatus-code-standards.vercel.app/docs/Structure/folder-structure#constants
148
+ - **No magic numbers or strings.** Use named constants. Only `-1`, `0` and `1` stay bare. Every loose named number goes in `lib/constants/numbers.ts`, even one only one file uses; config files keep theirs at the top. Put the unit in the name: `SESSION_TIMEOUT_MILLISECONDS`.
149
+ - **Links, text and stand-in data live in `lib/constants/`**, never written straight into a component. `r` holds every link (pages, outside sites, `mailto:`, `tel:`, `sms:`). `s` holds every piece of static text, and its keys become the translation keys when the site gets more languages. `noData.ts` holds stand-in data named `NO_DATA_` plus the thing it replaces (`NO_DATA_INSIGHTS`), used only in local development when the real source can't be reached, never in production. Dummy values sit at the top of `noData.ts`, never in `s`. `animation.ts` holds how things move and `artwork.ts` what is drawn and where, each object kept whole with its numbers named by their keys, never lifted out into `numbers.ts`. `classNames.ts` holds Tailwind class strings shared between files, only when a component cannot hold them and they still repeat; a class name one file uses stays inline. Create each of these three only once there is something to put in it. These seven files are the only ones in `lib/constants/`, each never split by topic. There is no component-level `constants.ts`: every value goes in `lib/constants/`, even if one file uses it. `lib/constants/` never imports from `lib/types/`. Write each key out by name, `r.plans.starter`, never `r.plans[planId]`, except inside a loop over the list, which looks each item up by an id typed `keyof typeof r.plans`. No separate id-to-link lookup objects such as `PLAN_ROUTES`: `r` already is the lookup. No `"#"` placeholder links: show plain text with a `{/* TODO: … */}` until the page exists. Create `noData.ts` only once the data's shape is decided; stand-in data asked for before then carries `// Not the real schema: a basic shape to finish the task.` Import them all in one line, `import { NO_DATA_INSIGHTS, r, s } from "@/lib/constants";`. `r` and `s` are the only single-letter names allowed anywhere. Full rule: https://activatus-code-standards.vercel.app/docs/Structure/folder-structure#constants
150
150
  - **No nested ternaries. No boolean flag parameters.**
151
151
  - **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
152
152
  - **Named exports only**, except where a tool requires a default export.
@@ -16,6 +16,8 @@ Every Activatus project follows the same standards, so people and agents can mov
16
16
 
17
17
  [For each standard this project skips or changes, at setup or later: its number and name from the setup list, what is different, why, and the date the person agreed. For example: "7. Prettier — skipped: the project uses Biome for formatting (2026-10-23)." Every rule in `eslint.overrides.mjs` has an entry here. If nothing differs, write "No differences".]
18
18
 
19
+ - Working with the agent: GitHub repo [link or None]; Linear project [project or None]; status circles [yes or no]; ask before every commit and push [yes or no] ([YYYY-MM-DD]).
20
+
19
21
  ## Components for the standards
20
22
 
21
23
  [Props-only components this project keeps in `components/ui/` that are not in the Design System Components list yet, each with its props, to be added in the next release of the standards. If there are none, write "None".]
@@ -121,8 +121,8 @@ const config = [
121
121
  rules: { "max-lines": "off", "no-magic-numbers": "off" },
122
122
  },
123
123
  {
124
- // r, s, numbers and noData are lists, not logic, so they can be long.
125
- files: ["lib/constants/{routes,strings,numbers,noData}.{js,mjs}"],
124
+ // The seven constants files are data, not logic, so they can be long.
125
+ files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.{js,mjs}"],
126
126
  rules: { "max-lines": "off" },
127
127
  },
128
128
  {
@@ -193,8 +193,8 @@ const config = [
193
193
  },
194
194
  },
195
195
  {
196
- // r, s, numbers and noData are lists, not logic, so they can be long.
197
- files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
196
+ // The seven constants files are data, not logic, so they can be long.
197
+ files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
198
198
  rules: { "max-lines": "off" },
199
199
  },
200
200
  {
@@ -195,8 +195,8 @@ const config = [
195
195
  },
196
196
  },
197
197
  {
198
- // r, s, numbers and noData are lists, not logic, so they can be long.
199
- files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
198
+ // The seven constants files are data, not logic, so they can be long.
199
+ files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
200
200
  rules: { "max-lines": "off" },
201
201
  },
202
202
  {
@@ -175,8 +175,8 @@ const config = [
175
175
  },
176
176
  },
177
177
  {
178
- // r, s, numbers and noData are lists, not logic, so they can be long.
179
- files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
178
+ // The seven constants files are data, not logic, so they can be long.
179
+ files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
180
180
  rules: { "max-lines": "off" },
181
181
  },
182
182
  {