@activatus/code-standards 3.2.1 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -52,6 +52,8 @@ The standards apply to **code we write**, not to packages we pull in. Do not lin
52
52
 
53
53
  Optional, and recommended when Stages 4 to 6 will move a lot of code. Set up the [regression check](/docs/Guides/regression-checks) and take its baseline from the **live production site**, before anything changes. Every later stage must pass it unchanged.
54
54
 
55
+ **Take the baseline first, then move one kind of thing at a time.** The constants moves (Stage 4) and the folder moves (Stage 5a) are separate steps, each followed by a full regression run. When a run fails, only one kind of move can have caused it.
56
+
55
57
  ## Stage 1 — Formatting
56
58
 
57
59
  Applies setup standards 7, 9 and 10. Three commits, in this order:
@@ -181,9 +183,12 @@ Applies setup standard 12.1. Move every link into `r`, every piece of text into
181
183
 
182
184
  - **Move the values, nothing else.** The page must look and work exactly as before.
183
185
  - **No component-level `constants.ts` survives this stage.**
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`.
186
- - **Shared types move to `lib/types/`.** `lib/constants/` never imports from `lib/types/`.
186
+ - **Move animation and artwork objects whole.** Never pull their numbers out into `numbers.ts`. Any other file in `lib/constants/` is folded into the standard file that fits.
187
+ - **Where each value goes is the project's call.** Read the [Constants table](/docs/Structure/folder-structure#constants) and decide. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`.
188
+ - **An id moves into the object that uses it.** **CSS written as a string moves to `globals.css`**, never into a constants file. A media query the code reads stays in its object in `animation.ts`.
189
+ - **Only text people see or hear goes in `s`.** Internal strings, such as ids, keys and log messages, stay where they are used: a key in the object that uses them, or a named constant at the top of the file.
190
+ - **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 key: see [the example](/docs/Structure/folder-structure#a-list-of-items-with-links). Delete any separate lookup object that maps a key to its link.
191
+ - **Every constant except `r` and `s` gets a real type from `lib/types/`**, never `as const`. Move the types it uses there too. `lib/types/` reads a constant's type with `import type` straight from its file. See [Types for constants](/docs/Structure/folder-structure#types-for-constants).
187
192
 
188
193
  ## Stage 5 — Components
189
194
 
@@ -207,7 +212,7 @@ Applies setup standard 21.
207
212
 
208
213
  1. Copy the [AGENTS.md template](/docs/templates#agents) to the project root and replace every `[placeholder]`. It describes the final layout, so it goes last.
209
214
  2. Copy the eight [standard skill files](/docs/templates#skills) into `.agents/skills/`, and again into `.claude/commands/`.
210
- 3. Set `**Code standards version:**` from the [Version History](/docs/version-history).
215
+ 3. Set `**Code standards version:**` to the installed package's full version, such as `3.2.2`.
211
216
  4. Run the [standards check](/docs/Guides/setup#checking-a-project), and fix what it finds.
212
217
 
213
218
  ## Tips
@@ -66,6 +66,7 @@ It builds the project and starts the production build on port 3100, then measure
66
66
  - **It runs against a production build**, on its own port, never against `pnpm dev`.
67
67
  - **An agent never updates the baseline without the person's yes.** A failing check means something visible changed. Find out what, and fix the code. Updating the baseline to make it pass hides the change.
68
68
  - **The test files are frozen** for the whole refactor: an agent never edits them to make a check pass.
69
+ - **A code standards update that changes only types may still be applied to a frozen test**, such as replacing `as const` with a real type, with the person's yes. A copy of the template takes the new template whole; a project's own test takes just the typing change. Nothing the test does may change, and the check must still pass against the **existing** baseline, never a new one: passing proves nothing changed.
69
70
 
70
71
  ## The blind spot
71
72
 
@@ -51,7 +51,7 @@ The standards are now in `node_modules/@activatus/code-standards/`:
51
51
  | `docs/version-history.md` | What changed in each version, and what a project has to do about it |
52
52
  | `static/templates/` | The config files to copy: `AGENTS.md`, ESLint, Prettier, Stylelint and the rest |
53
53
 
54
- **Read the standards from `node_modules`, not the website.** The installed package is the exact version the project uses. The package version is the standards version: `2.0.0` is version 2.
54
+ **Read the standards from `node_modules`, not the website.** The installed package is the exact version the project uses. The package version is the standards version, and a project records it in full: `3.2.2`.
55
55
 
56
56
  ## 2. Work out where the project is
57
57
 
@@ -121,7 +121,7 @@ The list has nothing about branches or commit messages. Those are the project's
121
121
 
122
122
  ## 4. Working with the agent
123
123
 
124
- Do this step every time, straight after step 3. Once the standards are agreed, offer the four [Working with Agents](/docs/Standards/working-with-agents) options. All four are optional: offer every one, every time, so the person can fill them in quickly and keep going.
124
+ Do this step every time, straight after step 3. Once the standards are agreed, offer the five [Working with Agents](/docs/Standards/working-with-agents) options. All five are optional: offer every one, every time, so the person can fill them in quickly and keep going.
125
125
 
126
126
  First the **project links**. Find each one yourself, then ask the person to confirm it or say "None":
127
127
 
@@ -148,7 +148,14 @@ 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", 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).
151
+ Then **told about decisions**. **Print this to the person exactly as it is written**:
152
+
153
+ ```text
154
+ Would you like AI to tell you about each coding decision
155
+ it makes that the code standards do not cover? Yes or no?
156
+ ```
157
+
158
+ **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. If they said yes to being told about decisions, write under **Decisions**: "Tell the person about each coding decision you make that the code standards do not cover, in the summary at the end of the task." If they said no, delete the Decisions line. Write all five 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]; told about decisions [yes or no] ([date]).` See [Working with Agents](/docs/Standards/working-with-agents).
152
159
 
153
160
  ## 5. Apply the standards
154
161
 
@@ -174,12 +181,12 @@ The other standards are rules for how code is written. There is nothing to insta
174
181
 
175
182
  **Finish by:**
176
183
 
177
- 1. Setting `**Code standards version:**` in `AGENTS.md` to the installed package's major version. See [Finishing a change later](#finishing-a-change-later) if anything is left to do.
184
+ 1. Setting `**Code standards version:**` in `AGENTS.md` to the installed package's full version, such as `3.2.2`. See [Finishing a change later](#finishing-a-change-later) if anything is left to do.
178
185
  2. Running `pnpm lint`, `pnpm format:check`, the tests and the [standards check](#checking-a-project), and fixing what they find.
179
186
  3. **Printing this to the person**, filled in, so every project's handover reads the same:
180
187
 
181
188
  ```text
182
- Code standards set up: version [N] ([package version]).
189
+ Code standards set up: version [full package version].
183
190
 
184
191
  Set up: [the standards applied, by number]
185
192
  Skipped: [numbers and reasons, or "None"]
@@ -195,12 +202,11 @@ anything that is wrong.
195
202
 
196
203
  ## Already on this version
197
204
 
198
- The project's `AGENTS.md` has the same major version as the installed package, such as 3. That does not mean there is nothing to do: a newer patch, such as 3.1.1, can still ask for changes.
205
+ The project's `AGENTS.md` has the same full version as the installed package, such as 3.2.2. There are no version changes to make.
199
206
 
200
- 1. **Read the version's Fixes** in `node_modules/@activatus/code-standards/docs/version-history.md`, and do anything they ask.
201
- 2. **Check `docs/development/coding-standards.md`, under "Details",** for the [step 4](#4-working-with-the-agent) answers: the GitHub repo, the Linear project, the status circles and asking before committing. Ask the person any that are not recorded, and record them as step 4 says.
202
- 3. **Run the [standards check](#checking-a-project)**, and fix what it finds.
203
- 4. **Tell the person** what you changed, or that the project was already up to date.
207
+ 1. **Check `docs/development/coding-standards.md`, under "Details",** for the [step 4](#4-working-with-the-agent) answers: the GitHub repo, the Linear project, the status circles, asking before committing and being told about decisions. Ask the person any that are not recorded, and record them as step 4 says.
208
+ 2. **Run the [standards check](#checking-a-project)**, and fix what it finds.
209
+ 3. **Tell the person** what you changed, or that the project was already up to date.
204
210
 
205
211
  ---
206
212
 
@@ -208,23 +214,23 @@ The project's `AGENTS.md` has the same major version as the installed package, s
208
214
 
209
215
  The project already follows the standards, and a newer version is out.
210
216
 
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.
217
+ **Every new number can ask for work**, whichever part changed. What each part means is in [How versions are numbered](/docs/version-history#how-versions-are-numbered).
212
218
 
213
- 1. **Note the project's version.** Read `**Code standards version:**` in `AGENTS.md`. This is the version the code follows.
219
+ 1. **Note the project's version.** Read `**Code standards version:**` in `AGENTS.md`. This is the version the code last applied. If it is only a major number, such as `3`, find the full version first: see [Updating a project to a new version](/docs/version-history#updating-a-project-to-a-new-version).
214
220
  2. **Update the package:**
215
221
 
216
222
  ```bash
217
223
  pnpm add -D @activatus/code-standards@latest
218
224
  ```
219
225
 
220
- Its major version is now the newest version. If pnpm refuses because the version is too new, or `pnpm format:check` now fails on `pnpm-workspace.yaml`, see [1. Install the standards](#1-install-the-standards). Check `minimumReleaseAgeExclude` in `pnpm-workspace.yaml` is the plain name, `"@activatus/code-standards"`, with no version in it.
226
+ Its version is now the newest. If pnpm refuses because the version is too new, or `pnpm format:check` now fails on `pnpm-workspace.yaml`, see [1. Install the standards](#1-install-the-standards). Check `minimumReleaseAgeExclude` in `pnpm-workspace.yaml` is the plain name, `"@activatus/code-standards"`, with no version in it.
221
227
 
222
- 3. **Read `node_modules/@activatus/code-standards/docs/version-history.md`**, but only the versions newer than the project's. Do not re-read the rest of the standards.
228
+ 3. **Read `node_modules/@activatus/code-standards/docs/version-history.md`**, but only the entries newer than the project's version. Do not re-read the rest of the standards.
223
229
  4. **Skip any change to a standard the project opted out of.** The opt-outs are listed in `docs/development/coding-standards.md`.
224
230
  5. **Do every other change** as its "What to do" says, and run its "How to check" search.
225
231
  6. **Ask any [step 4](#4-working-with-the-agent) question** whose answer is not recorded in `docs/development/coding-standards.md`, under "Details".
226
232
  7. **Run the [standards check](#checking-a-project)**, and fix what it finds.
227
- 8. **Set `**Code standards version:**`** in `AGENTS.md` to the new version, and tell the person what changed. If a change is being finished later, record it first: see [Finishing a change later](#finishing-a-change-later).
233
+ 8. **Set `**Code standards version:**`** in `AGENTS.md` to the installed package's full version, and tell the person what changed. If a change is being finished later, record it first: see [Finishing a change later](#finishing-a-change-later).
228
234
 
229
235
  See the [Version History](/docs/version-history) for the full update rules.
230
236
 
@@ -254,7 +260,7 @@ It reports, and never changes a file. Each finding gives the standard's number a
254
260
  | 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
261
  | 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
262
  | 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" |
263
+ | 21 | `docs/development/coding-standards.md` records the five agent answers under "Details" |
258
264
  | 11 | `docs/design/design-system.md` has a filled-in Colour palette table |
259
265
  | 15 | Every `components/ui/` component is on the Design System Components list, or recorded under "Components for the standards" |
260
266
  | 4 | Every file that exports a function or component has a test file beside it |
@@ -272,6 +272,14 @@ const NO_SATISFIES = {
272
272
  "Type a value where it is declared, not with satisfies afterwards.",
273
273
  };
274
274
 
275
+ // Give a value a real type instead. consistent-type-assertions always
276
+ // lets `as const` through, so it is banned here.
277
+ const NO_AS_CONST = {
278
+ selector: "TSAsExpression[typeAnnotation.typeName.name='const']",
279
+ message:
280
+ "Give the value a real type where it is declared, not as const.",
281
+ };
282
+
275
283
  const config = [
276
284
  {
277
285
  ignores: [
@@ -319,6 +327,7 @@ const config = [
319
327
  "no-restricted-syntax": [
320
328
  "error",
321
329
  NO_SATISFIES,
330
+ NO_AS_CONST,
322
331
  ...RESTRICTED_SYNTAX,
323
332
  ...SINGLE_OBJECT_PARAMETER,
324
333
  ],
@@ -410,6 +419,7 @@ const config = [
410
419
  rules: {
411
420
  "no-restricted-syntax": [
412
421
  "error",
422
+ NO_AS_CONST,
413
423
  ...RESTRICTED_SYNTAX,
414
424
  ...SINGLE_OBJECT_PARAMETER,
415
425
  ],
@@ -489,6 +499,14 @@ const NO_SATISFIES = {
489
499
  "Type a value where it is declared, not with satisfies afterwards.",
490
500
  };
491
501
 
502
+ // Give a value a real type instead. consistent-type-assertions always
503
+ // lets `as const` through, so it is banned here.
504
+ const NO_AS_CONST = {
505
+ selector: "TSAsExpression[typeAnnotation.typeName.name='const']",
506
+ message:
507
+ "Give the value a real type where it is declared, not as const.",
508
+ };
509
+
492
510
  const config = [
493
511
  {
494
512
  ignores: [
@@ -545,6 +563,7 @@ const config = [
545
563
  "no-restricted-syntax": [
546
564
  "error",
547
565
  NO_SATISFIES,
566
+ NO_AS_CONST,
548
567
  ...RESTRICTED_SYNTAX,
549
568
  ...SINGLE_OBJECT_PARAMETER,
550
569
  ],
@@ -645,6 +664,7 @@ const config = [
645
664
  rules: {
646
665
  "no-restricted-syntax": [
647
666
  "error",
667
+ NO_AS_CONST,
648
668
  ...RESTRICTED_SYNTAX,
649
669
  ...SINGLE_OBJECT_PARAMETER,
650
670
  ],
@@ -727,6 +747,14 @@ const NO_SATISFIES = {
727
747
  "Type a value where it is declared, not with satisfies afterwards.",
728
748
  };
729
749
 
750
+ // Give a value a real type instead. consistent-type-assertions always
751
+ // lets `as const` through, so it is banned here.
752
+ const NO_AS_CONST = {
753
+ selector: "TSAsExpression[typeAnnotation.typeName.name='const']",
754
+ message:
755
+ "Give the value a real type where it is declared, not as const.",
756
+ };
757
+
730
758
  const config = [
731
759
  {
732
760
  ignores: [
@@ -782,6 +810,7 @@ const config = [
782
810
  "no-restricted-syntax": [
783
811
  "error",
784
812
  NO_SATISFIES,
813
+ NO_AS_CONST,
785
814
  ...RESTRICTED_SYNTAX,
786
815
  ...SINGLE_OBJECT_PARAMETER,
787
816
  ],
@@ -886,6 +915,7 @@ const config = [
886
915
  rules: {
887
916
  "no-restricted-syntax": [
888
917
  "error",
918
+ NO_AS_CONST,
889
919
  ...RESTRICTED_SYNTAX,
890
920
  ...SINGLE_OBJECT_PARAMETER,
891
921
  ],
@@ -898,6 +928,7 @@ const config = [
898
928
  "no-restricted-syntax": [
899
929
  "error",
900
930
  NO_SATISFIES,
931
+ NO_AS_CONST,
901
932
  ...RESTRICTED_SYNTAX,
902
933
  ],
903
934
  },
@@ -1078,13 +1109,13 @@ Names are full English words: `btn` must be `button`, `e` must be `error` or `ev
1078
1109
 
1079
1110
  The `!` operator tells the compiler a value exists without checking. Check it instead.
1080
1111
 
1081
- ### `no-restricted-syntax`: type first, never `satisfies`
1112
+ ### `no-restricted-syntax`: type first, never `satisfies` or `as const`
1082
1113
 
1083
- A value gets its type where it is declared: `const config: ConfigType = { … }`. `satisfies` attaches the type afterwards, so it is an error in the TypeScript, React and Next.js configs, except in story files (`*.stories.{ts,tsx}`), which follow Storybook's docs. The rule lists live in `RESTRICTED_SYNTAX` and `NO_SATISFIES` at the top of each config, so story files use every other restriction without repeating it. See [Type first, never `satisfies`](/docs/Standards/readable-code#type-first-never-satisfies).
1114
+ A value gets its type where it is declared: `const config: ConfigType = { … }`. `satisfies` attaches the type afterwards, so it is an error in the TypeScript, React and Next.js configs, except in story files (`*.stories.{ts,tsx}`), which follow Storybook's docs. `as const` is an error everywhere, story files included: see [No `as const`](/docs/Standards/readable-code#no-as-const). The rule lists live in `RESTRICTED_SYNTAX`, `NO_SATISFIES` and `NO_AS_CONST` at the top of each config, so story files use every other restriction without repeating it. See [Type first, never `satisfies`](/docs/Standards/readable-code#type-first-never-satisfies).
1084
1115
 
1085
1116
  ### `@typescript-eslint/consistent-type-assertions: never`
1086
1117
 
1087
- `as` casts are errors (`as const` is still allowed). When a cast is genuinely needed, disable the rule on that line **with the reason** — which is exactly the comment the [standard](/docs/Standards/readable-code#no-any-no--no-unexplained-as) requires:
1118
+ `as` casts are errors. This rule always lets `as const` through, so `NO_AS_CONST` in `no-restricted-syntax` stops it instead. When a cast is genuinely needed, disable the rule on that line **with the reason** — which is exactly the comment the [standard](/docs/Standards/readable-code#no-any-no--no-unexplained-as) requires:
1088
1119
 
1089
1120
  ```ts
1090
1121
  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- the API returns untyped JSON; validated by parseUser below
@@ -456,7 +456,7 @@ const getUserName = (user: any) => {
456
456
  };
457
457
  ```
458
458
 
459
- `as const` is fine. See the [ESLint configuration](/docs/Standards/eslint#typescript-eslintconsistent-type-assertions-never) for how to record the reason for a cast.
459
+ `as const` is never used either: see [No `as const`](#no-as-const). See the [ESLint configuration](/docs/Standards/eslint#typescript-eslintconsistent-type-assertions-never) for how to record the reason for a cast.
460
460
 
461
461
  ---
462
462
 
@@ -595,6 +595,35 @@ ESLint reports `satisfies` as an error.
595
595
 
596
596
  ---
597
597
 
598
+ ### No `as const` {#no-as-const}
599
+
600
+ **Give a value a real type where it is declared, never `as const`.** `as const` makes the value the source of truth and leaves TypeScript to work out the type. A written type is the contract a reader sees first, and the value is checked against it.
601
+
602
+ ```ts
603
+ // ✅ Good — the exact values are in the type
604
+ type RoleType = "admin" | "editor";
605
+
606
+ interface AccessType {
607
+ roles: readonly RoleType[];
608
+ }
609
+
610
+ const ACCESS: AccessType = { roles: ["admin", "editor"] };
611
+ ```
612
+
613
+ ```ts
614
+ // ❌ Bad — the type is worked out from the value
615
+ const ACCESS = { roles: ["admin", "editor"] } as const;
616
+ ```
617
+
618
+ - **A written type widens each value to the type.** When the code needs the exact values, put them in the type, as `RoleType` does above.
619
+ - **A constant's list is `readonly` in its type**, so nothing changes it by accident. Lists in props, parameters and state need not be.
620
+ - **A list that must hold every value** is checked with a `Record` over the values' type, or with a test. A typed list checks that each item is a real value, not that none is missing.
621
+ - **`r` and `s` are never typed by hand.** Their types are read from their values (`keyof typeof r.plans`), and they need no `as const` either.
622
+
623
+ ESLint reports `as const` as an error. If one is genuinely unavoidable, disable the rule on that line with the reason, as for a cast: `// eslint-disable-next-line no-restricted-syntax -- <reason>`.
624
+
625
+ ---
626
+
598
627
  ## Error messages say what happened and what to do
599
628
 
600
629
  An error message is read by someone in the middle of a problem. Tell them what went wrong and how to fix it.
@@ -5,7 +5,7 @@ sidebar_label: "Working with Agents"
5
5
 
6
6
  # Working with Agents
7
7
 
8
- > How an AI agent links a project's work, reports on it and asks before committing. The GitHub repo, the Linear project, the status circles and asking before every commit and push are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all four every time, so they take a moment to fill in, and a project can leave out any of them. They work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
8
+ > How an AI agent links a project's work, reports on it, asks before committing and tells the person about its decisions. The GitHub repo, the Linear project, the status circles, asking before every commit and push, and being told about decisions are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all five every time, so they take a moment to fill in, and a project can leave out any of them. They work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
9
9
 
10
10
  Whatever the project chooses is written into the **Project workflow** section of its `AGENTS.md`, from the [template](/docs/templates#agents), so every agent in the project follows it.
11
11
 
@@ -45,3 +45,7 @@ Optional. An agent reports the state of every ticket or piece of work as one lin
45
45
  ## Ask before committing
46
46
 
47
47
  Optional. Setup asks: "Would you like AI to ask you before every commit and push to git?" A yes is written under **Who commits** in Project workflow: ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only. A no means nothing is written, and the agent uses its own judgement.
48
+
49
+ ## Told about decisions
50
+
51
+ Optional. Setup asks: "Would you like AI to tell you about each coding decision it makes that the code standards do not cover?" The code standards are the base, and the agent builds freely from them, so it makes many calls of its own. A person who reads the code may want to hear each one; a person who does not may not care. A yes is written under **Decisions** in Project workflow: the agent lists each such decision in its summary at the end of the task. A no means nothing is written, and the agent decides without reporting.
@@ -301,7 +301,7 @@ Add the export to `utils/index.ts` whenever you add a function.
301
301
 
302
302
  ## 🔤 Constants: `r`, `s`, numbers, noData, animation, artwork and class names {#constants}
303
303
 
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.
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. Internal strings people never see are the one exception: see [`s`: strings](#s-strings).
305
305
 
306
306
  ```text
307
307
  lib/constants/
@@ -315,18 +315,20 @@ lib/constants/
315
315
  └── index.ts # Exports all of them
316
316
  ```
317
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.
318
+ **These seven files are the only ones.** Each is one file, never split by topic. `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
319
 
320
320
  | A value that is… | Goes in |
321
321
  | ----------------------------------------------------------- | ------------------- |
322
322
  | A link | `r` in `routes.ts` |
323
- | Text shown on screen | `s` in `strings.ts` |
323
+ | Text people see or hear | `s` in `strings.ts` |
324
324
  | A single number with one job | `numbers.ts` |
325
325
  | Fake data shaped like a real response | `noData.ts` |
326
326
  | A group of values that together say how something moves | `animation.ts` |
327
327
  | A group of values that together say what is drawn and where | `artwork.ts` |
328
328
  | A Tailwind class string used by more than one file | `classNames.ts` |
329
329
 
330
+ **This table is the base, and where each value goes is the project's call.** The table says what each file is for, not where every value in every project goes. The project reads its own values, decides which file each one belongs in, and keeps that choice the same across the codebase. A value that fits none of them goes in the closest file, with a comment naming its entry under "Details" in `docs/development/coding-standards.md`, where the project records why. It is a coding decision, so the work carries on without waiting for a yes.
331
+
330
332
  A file outside the folder imports everything it needs in one line:
331
333
 
332
334
  ```tsx
@@ -355,7 +357,7 @@ export const r = {
355
357
 
356
358
  ### `s`: strings
357
359
 
358
- **`s` holds every piece of static text** shown on screen: headings, buttons, labels, aria-labels, page titles and descriptions, and longer Markdown copy.
360
+ **`s` holds every piece of text people see or hear**: headings, buttons, labels, aria-labels, page titles and descriptions, and longer Markdown copy.
359
361
 
360
362
  ```ts title="lib/constants/strings.ts"
361
363
  export const s = {
@@ -369,6 +371,7 @@ export const s = {
369
371
 
370
372
  - **The keys of `s` are the site's translation keys.** When a site gets more languages, each key is translated into each language. Name each key after what the text says or does, and never use one key for two different jobs.
371
373
  - **Only real copy goes in `s`.** Dummy text belongs in `noData.ts`.
374
+ - **Internal strings are not `s`.** Ids, keys, event names, log messages and media queries are never shown to people. Each is a key in the object that uses it, or a named constant at the top of the file that uses it, such as `const CLOSE_EVENT = "close";`. The code is never pulled apart to move them into `lib/constants/`.
372
375
 
373
376
  ### A list of items with links
374
377
 
@@ -399,24 +402,24 @@ export const r = {
399
402
 
400
403
  **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
404
 
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:
405
+ **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 key, typed from `r` itself:
403
406
 
404
407
  ```ts title="lib/types/index.ts"
405
- import type { r } from "@/lib/constants";
408
+ import type { r } from "@/lib/constants/routes";
406
409
 
407
- export type SourceIdType = keyof typeof r.sources;
410
+ export type PlanIdType = keyof typeof r.plans;
408
411
  ```
409
412
 
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}
413
+ ```tsx
414
+ {planIds.map((planId) => (
415
+ <Link key={planId} href={r.plans[planId]}>
416
+ {s.plans[planId].action}
414
417
  </Link>
415
418
  ))}
416
419
  ```
417
420
 
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.
421
+ - **The type comes from `r`**, so a missing or misspelt key fails the type check.
422
+ - **No separate lookup objects** that map a key to its link. `r` already is that lookup: a second one is a copy that drifts out of step.
420
423
 
421
424
  ### noData: stand-in data for local development
422
425
 
@@ -460,75 +463,130 @@ const insights =
460
463
  export const COOKIE_DURATION_DAYS = 30;
461
464
  export const MAXIMUM_RETRY_ATTEMPTS = 3;
462
465
  export const SESSION_TIMEOUT_MILLISECONDS = 900_000;
463
- export const TOOLTIP_SIDE_OFFSET_PIXELS = 8;
464
466
  ```
465
467
 
466
468
  - **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`.
469
+ - **Loose numbers only.** A number that only means something beside other values stays inside its object in `animation.ts` or `artwork.ts`. It is never lifted out into `numbers.ts`.
468
470
  - **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.
469
471
  - **Put the unit in the name**: `_MILLISECONDS`, `_DAYS`, `_PIXELS`.
470
472
 
471
473
  ### Animation: how things move
472
474
 
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.
475
+ **`animation.ts` holds every object that says how and when something moves.**
474
476
 
475
477
  ```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,
478
+ export const ENTRANCE_ANIMATION = {
479
+ delaySeconds: 0.1,
480
+ durationSeconds: 0.4,
481
+ offsetPixels: 24,
484
482
  };
485
-
486
- export const REDUCED_MOTION_QUERY =
487
- "(prefers-reduced-motion: reduce)";
488
483
  ```
489
484
 
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`.
485
+ - **Each object stays whole.** Values that only mean something together stay in one object, named by their keys. Never lift its numbers out into `numbers.ts`.
486
+ - **Values the animation library reads are not text on screen**, so they stay in the object, never in `s`.
487
+ - **Put the unit in the key**: `durationSeconds`, `offsetPixels`.
488
+ - **Media queries the animation reads stay in its object**, such as `reducedMotionQuery: "(prefers-reduced-motion: reduce)"`. They are read by code, not CSS, so they never move to `globals.css`.
493
489
 
494
490
  ### Artwork: what is drawn and where
495
491
 
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.
492
+ **`artwork.ts` holds every object that says what is drawn, where it ends up, and how it is grouped.** Where something ends up is artwork; how and when it gets there is animation.
497
493
 
498
494
  ```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
- ];
495
+ export const ILLUSTRATION_LAYOUT = {
496
+ heightPixels: 600,
497
+ widthPixels: 800,
498
+ };
505
499
  ```
506
500
 
507
501
  - **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.
502
+ - **Drawing data the code reads goes here.** A static drawing that nothing reads goes in an `.svg` file in `public/` or in an icon component.
509
503
 
510
504
  ### Class names shared between files
511
505
 
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.
506
+ **`classNames.ts` holds Tailwind class names that more than one file uses**: a single class string, or a set of them keyed by variant.
513
507
 
514
508
  ```ts title="lib/constants/classNames.ts"
515
- export const CARD_FACE_CLASS_NAME =
516
- "rounded-2xl border border-border bg-card shadow-sm";
509
+ export const SURFACE_CLASS_NAME =
510
+ "rounded-2xl border border-border bg-card";
517
511
  ```
518
512
 
519
513
  - **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
514
  - **A class name used in one file stays inline in that file.**
521
- - **Name each export after what it styles, ending in `_CLASS_NAME`.**
515
+ - **Name each export after what it styles, ending in `_CLASS_NAME`**, or `_CLASS_NAMES` for a set keyed by variant.
522
516
 
523
- ### Rules
517
+ ### Types for constants {#types-for-constants}
518
+
519
+ **Every constant gets a real type where it is declared, from `lib/types/`.** `r` and `s` are the exception: their types are read from their values, such as `keyof typeof r.plans`, so they are never typed by hand.
520
+
521
+ ```ts title="lib/types/animation.ts"
522
+ export interface EntranceAnimationType {
523
+ delaySeconds: number;
524
+ durationSeconds: number;
525
+ offsetPixels: number;
526
+ }
527
+ ```
528
+
529
+ ```ts title="lib/constants/animation.ts"
530
+ import type { EntranceAnimationType } from "@/lib/types";
531
+
532
+ export const ENTRANCE_ANIMATION: EntranceAnimationType = {
533
+ delaySeconds: 0.1,
534
+ durationSeconds: 0.4,
535
+ offsetPixels: 24,
536
+ };
537
+ ```
538
+
539
+ - **Types live in `lib/types/`, in files named by topic**, such as `animation.ts` and `artwork.ts`. A types file is not exempt from the 300-line limit: split it by topic when it grows.
540
+ - **A type a constant needs lives in `lib/types/`**, with every type it depends on. Components import it from `@/lib/types`.
541
+ - **`lib/types/` reads a constant's type straight from its file**: `import type { r } from "@/lib/constants/routes";`, never through `@/lib/constants`. It is the one exception to importing constants in one line. `import type` is removed at build, so the two folders reading each other's types never makes a real loop.
542
+ - **No `as const`.** When the code needs the exact values, they go in the type, such as an id typed by its id type: `planId: PlanIdType`. Otherwise use plain `string`, `number` and `boolean`. See [No `as const`](/docs/Standards/readable-code#no-as-const).
543
+ - **A list gets a type for one item, and is read-only**: `ENTRANCE_STEPS: readonly EntranceStepType[]`. A list inside a list item gets its own item type too, and is read-only as well.
544
+ - **A map keyed by id uses `Record` over the id type**: `PLAN_BADGES: Record<PlanIdType, PlanBadgeType>`, so a missing id fails the type check. When only some ids have a value, use `Partial<Record<PlanIdType, PlanBadgeType>>`.
545
+ - **A lookup inside `r` or `s` that only some ids have** cannot be typed there, because `r` and `s` are never typed by hand. Declare it as a typed constant above `r` or `s` in the same file, then place it inside by name:
546
+
547
+ ```ts title="lib/constants/routes.ts"
548
+ import type { FeatureIdType } from "@/lib/types";
549
+
550
+ const FEATURE_GUIDE_LINKS: Partial<Record<FeatureIdType, string>> = {
551
+ sharing: "/guides/sharing",
552
+ };
553
+
554
+ export const r = {
555
+ featureGuideLinks: FEATURE_GUIDE_LINKS,
556
+ };
557
+ ```
558
+
559
+ The id type must not be read from the object the lookup sits in: TypeScript rejects that as a loop. Here `FeatureIdType` is `keyof typeof s.features`, read from `s`, so it can be used inside `r`.
560
+
561
+ - **A list that must hold every id** is checked with a `Record`, or with a test. A typed list checks that each item is a real id, not that none is missing.
562
+ - **A `.map` that builds typed items gets a return type**: `planIds.map((planId): PlanBadgeType => ({ … }))`, never a cast on a field.
563
+ - **When a function's `Props` and a constant share a shape**, the shape is a type in `lib/types/` and the `Props` is an alias of it: `export type GetFramePathProps = FrameShapeType;`.
564
+
565
+ ### Rules {#constants-rules}
524
566
 
525
567
  - **Named exports only:** `export const r`, `export const s`. No default exports.
526
568
  - **Files outside `lib/constants/` import from `@/lib/constants`**, all in one import line.
527
569
  - **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).
528
570
  - **`r` and `s` are the only single-letter names allowed anywhere.** See [Human-Readable Names](/docs/Standards/human-readable-names#r-and-s).
529
571
  - **Other constants**, such as numbers, are `SCREAMING_SNAKE_CASE`: see [Naming Conventions](/docs/Structure/naming-conventions#constants).
572
+ - **An id lives in the object that uses it.** A value that picks which item something acts on, such as which item an animation moves to, is a key inside that object, never a loose constant of its own:
573
+
574
+ ```ts
575
+ // Before
576
+ export const HIGHLIGHTED_PLAN_ID = "team";
577
+ export const HIGHLIGHT_ANIMATION = { durationSeconds: 0.3 };
578
+
579
+ // After
580
+ export const HIGHLIGHT_ANIMATION = {
581
+ durationSeconds: 0.3,
582
+ planId: "team",
583
+ };
584
+ ```
585
+
586
+ A list of keys a loop runs over, such as `planIds` in [A list of items with links](#a-list-of-items-with-links), is not a loose id: it stays a list.
587
+
588
+ - **CSS belongs in a stylesheet, never in a constant.** Styles written as a string in TypeScript move to `globals.css`. Styles for when JavaScript is off go there under `@media (scripting: none)`; a browser without that query misses the fallback, and the standard accepts that. **A media query the code reads is not CSS**, such as the one an animation library matches to switch motion off: it stays in its object in `animation.ts`.
530
589
  - **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.
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.
532
590
 
533
591
  ---
534
592