@activatus/code-standards 3.2.2 → 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.
@@ -188,7 +188,7 @@ Applies setup standard 12.1. Move every link into `r`, every piece of text into
188
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
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
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
- - **Shared types move to `lib/types/`.** `lib/constants/` never imports from `lib/types/`.
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).
192
192
 
193
193
  ## Stage 5 — Components
194
194
 
@@ -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
 
@@ -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.
@@ -405,7 +405,7 @@ export const r = {
405
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:
406
406
 
407
407
  ```ts title="lib/types/index.ts"
408
- import type { r } from "@/lib/constants";
408
+ import type { r } from "@/lib/constants/routes";
409
409
 
410
410
  export type PlanIdType = keyof typeof r.plans;
411
411
  ```
@@ -514,6 +514,54 @@ export const SURFACE_CLASS_NAME =
514
514
  - **A class name used in one file stays inline in that file.**
515
515
  - **Name each export after what it styles, ending in `_CLASS_NAME`**, or `_CLASS_NAMES` for a set keyed by variant.
516
516
 
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
+
517
565
  ### Rules {#constants-rules}
518
566
 
519
567
  - **Named exports only:** `export const r`, `export const s`. No default exports.
@@ -539,7 +587,6 @@ export const SURFACE_CLASS_NAME =
539
587
 
540
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`.
541
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.
542
- - **`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.
543
590
 
544
591
  ---
545
592
 
@@ -68,10 +68,54 @@ Anyone changing the standards adds a version, alongside the change:
68
68
 
69
69
  ## Version 3
70
70
 
71
- **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.2.2
71
+ **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.0
72
72
 
73
73
  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.
74
74
 
75
+ **Fixes in 3.3.0.** If the project already applied 3.2.2, check these:
76
+
77
+ **Structural changes in 3.3.0.** These move files. Plan them, and take a [regression check](/docs/Guides/regression-checks) baseline first:
78
+
79
+ - Every type a constant needs moves into `lib/types/`, with the types it depends on: one move per type. A component's `types.ts` left empty is deleted.
80
+ - Every `as const` value found outside `lib/constants/` moves into the constants file that fits, with its type: one move per value. These stay where they are:
81
+
82
+ - values in tests
83
+ - internal strings, as a named constant at the top of the file that uses them
84
+ - a class name only one file uses
85
+ - numbers in config files
86
+
87
+ - **Constants get real types, from `lib/types/`.** Every constant except `r` and `s` is typed where it is declared, with a type from `lib/types/`. "`lib/constants/` never imports from `lib/types/`" is withdrawn: it only ever guarded against a loop of types, which `import type` removes at build, and it pushed projects into `as const` and into retyping values wherever they were read. `lib/types/` now reads a constant's type with `import type` straight from its file, never through `@/lib/constants`. See [Types for constants](/docs/Structure/folder-structure#types-for-constants).
88
+
89
+ **What to do:** change every import in `lib/types/` from `@/lib/constants` to the constant's own file, as `import type`. Give every constant except `r` and `s` a type from `lib/types/`, in files named by topic, and move the types it uses there with what they depend on. Point imports at `@/lib/types`, delete component `types.ts` files left empty, and remove imports left unused. Then remove the workarounds: values retyped where they are read, test values retyped or bent around missing properties. Make every list in a constant's type `readonly`, including lists inside an item. Copy the Code standards section of `AGENTS.md` from the template again.
90
+
91
+ - **No `as const` anywhere.** A written type is the contract; when the code needs exact values, they go in the type. Each constant's list type is `readonly`. A list that must hold every id is checked with a `Record` or a test. ESLint now reports `as const` as an error: `consistent-type-assertions` always let it through, so the configs ban it with `no-restricted-syntax`. See [No `as const`](/docs/Standards/readable-code#no-as-const).
92
+
93
+ **What to do:** copy the project's ESLint template over `eslint.config.mjs` again. Replace each `as const` with a real type where the value is declared. An `as const` value found outside `lib/constants/` moves into the matching constants file with its type. These stay where they are, each given a type:
94
+
95
+ - values in tests
96
+ - internal strings, as a named constant at the top of the file that uses them
97
+ - a class name only one file uses
98
+ - numbers in config files Copy `static/templates/skills/typescript.md` into `.agents/skills/` and `.claude/commands/` again. Where one `as const` is genuinely unavoidable, disable the rule on that line with the reason.
99
+
100
+ - **The regression test template has no `as const`**, and a frozen test may take a change that touches only types. A code standards update that changes only types may be applied to a frozen test with the person's yes. Nothing the test does changes, and the check must still pass against the existing baseline. See [Regression Checks](/docs/Guides/regression-checks).
101
+
102
+ **What to do:** if the project has a copy of `static/templates/tests/visual/pageLayout.visual.ts`, copy the new one over it. In a project's own visual test, replace any `as const` with a real type. Run the regression check against the existing baseline: it must pass unchanged.
103
+
104
+ **How to check:** `pnpm lint` and `pnpm typecheck` pass; these searches find nothing:
105
+
106
+ ```bash
107
+ # lib/types/ reading constants through the barrel
108
+ grep -rn 'from "@/lib/constants"' lib/types/
109
+ # as const anywhere in code we write
110
+ grep -rn "as const" --include='*.ts' --include='*.tsx' --exclude-dir=node_modules --exclude-dir=vendor .
111
+ ```
112
+
113
+ This search lists types in `lib/types/` with a list that is not `readonly`. Fix each hit that a constant uses; a type only props or parameters use can stay as it is:
114
+
115
+ ```bash
116
+ grep -rnE "(^|[^y] )[A-Z][A-Za-z]*Type\[\]" lib/types/
117
+ ```
118
+
75
119
  **Fixes in 3.2.2.** If the project already applied 3.2.1, check these:
76
120
 
77
121
  - **The project records the full version.** `**Code standards version:**` in `AGENTS.md` is now the full version last applied, such as `3.1.0`, not the major number alone, so the project and the package pair up and the next update knows where to start. Versions are now numbered by what they do: see [How versions are numbered](#how-versions-are-numbered). `pnpm standards:check` reads the full version, and flags a project that recorded only `3`, an older version, or a version newer than the installed package.
@@ -191,7 +235,7 @@ grep -rnE "export const [A-Z_]+_ID = " lib/constants/
191
235
  - **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._
192
236
  - **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).
193
237
  - **No `"#"` placeholder links.** Show the text without a link and put `{/* TODO: … */}` above it until the page exists. Unfinished work is marked `// TODO: Message`.
194
- - **`lib/constants/` never imports from `lib/types/`.** Move any type it imports from there beside the constant.
238
+ - **`lib/constants/` never imports from `lib/types/`.** Move any type it imports from there beside the constant. _Withdrawn in 3.3.0: constants now take their types from `lib/types/`. Do the 3.3.0 step instead._
195
239
  - **Create `noData.ts` only once the data's shape is decided.** An empty `noData.ts` can be deleted. Stand-in data asked for earlier carries the comment `// Not the real schema: a basic shape to finish the task.`
196
240
  - **A component's sub-components sit flat in its one `components/` folder**, two levels at most. Move any sub-component folder sitting directly in its parent, or nested inside another sub-component, into the parent's `components/` folder.
197
241
  - **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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@activatus/code-standards",
3
- "version": "3.2.2",
3
+ "version": "3.3.0",
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",
@@ -149,11 +149,11 @@ Follow these rules in every change:
149
149
  - **One parameter per function.** Use a single object when more than one value is needed.
150
150
  - **Return early.** Never nest more than three levels deep.
151
151
  - **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`.
152
- - **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 text people see or hear, 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 and when things move and `artwork.ts` what is drawn, where it ends up and how it is grouped, 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. Internal strings (ids, keys, event names, log messages) are not `s`: each is a key in the object that uses it, or a named constant at the top of the file that uses it. Where each value goes is the project's call: decide from the Constants table. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `docs/development/coding-standards.md`, and the work carries on. An id lives in the object that uses it, never as a loose constant; a list of keys a loop runs over stays a list. CSS goes in a stylesheet, never in a constant: styles for when JavaScript is off go in `globals.css` under `@media (scripting: none)`. A media query the code reads, such as one an animation library matches, is not CSS: it stays in its object in `animation.ts`. There is no component-level `constants.ts`: every value goes in `lib/constants/`, even if one file uses it, except internal strings, which stay with the code that uses them. `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 a key typed `keyof typeof r.plans`. No separate lookup objects that map a key to its link: `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
152
+ - **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 text people see or hear, 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 and when things move and `artwork.ts` what is drawn, where it ends up and how it is grouped, 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. Internal strings (ids, keys, event names, log messages) are not `s`: each is a key in the object that uses it, or a named constant at the top of the file that uses it. Where each value goes is the project's call: decide from the Constants table. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `docs/development/coding-standards.md`, and the work carries on. An id lives in the object that uses it, never as a loose constant; a list of keys a loop runs over stays a list. CSS goes in a stylesheet, never in a constant: styles for when JavaScript is off go in `globals.css` under `@media (scripting: none)`. A media query the code reads, such as one an animation library matches, is not CSS: it stays in its object in `animation.ts`. There is no component-level `constants.ts`: every value goes in `lib/constants/`, even if one file uses it, except internal strings, which stay with the code that uses them. Every constant except `r` and `s` gets a real type from `lib/types/`, in files named by topic. `lib/types/` reads a constant's type with `import type` straight from its file, never through `@/lib/constants`. 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 a key typed `keyof typeof r.plans`. No separate lookup objects that map a key to its link: `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
153
153
  - **No nested ternaries. No boolean flag parameters.**
154
154
  - **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
155
155
  - **Named exports only**, except where a tool requires a default export.
156
- - **Type names end in `Props` or `Type`**, and say what the thing is, not the job it does. A type that only describes one field of a function's props is written inside the `Props`: `StartAgentRunProps` holds its `dependencies`, with no separate `StartAgentRunDependenciesType`. Every function still has its own `Props` for its single object parameter, such as `LaunchSessionProps` for `launchSession`, used wherever that function is written: `async ({ worktreePath }: LaunchSessionProps) =>`. Type a value where it is declared, never afterwards with `satisfies`. The one exception is Storybook story files, which follow Storybook's docs: `satisfies Meta<typeof Component>`.
156
+ - **Type names end in `Props` or `Type`**, and say what the thing is, not the job it does. A type that only describes one field of a function's props is written inside the `Props`: `StartAgentRunProps` holds its `dependencies`, with no separate `StartAgentRunDependenciesType`. Every function still has its own `Props` for its single object parameter, such as `LaunchSessionProps` for `launchSession`, used wherever that function is written: `async ({ worktreePath }: LaunchSessionProps) =>`. Type a value where it is declared, never afterwards with `satisfies`, and never `as const`: when the code needs exact values, put them in the type. A constant's list type is `readonly`. The one exception is Storybook story files, which follow Storybook's docs: `satisfies Meta<typeof Component>`.
157
157
  - **One component per file.** Server and client components live in separate files.
158
158
  - **A component's children sit flat in its own `components/` folder**, `accordion/components/item/` and `accordion/components/ctaArrow/`, even when one child is only used by another. Never a `components/` folder inside a child: two levels at most.
159
159
  - **Component file order**: imports, component, variables, state, `useMemo` values, `useCallback` functions, effects, render. No inline functions in render.
@@ -56,6 +56,14 @@ const NO_SATISFIES = {
56
56
  "Type a value where it is declared, not with satisfies afterwards.",
57
57
  };
58
58
 
59
+ // Give a value a real type instead. consistent-type-assertions always
60
+ // lets `as const` through, so it is banned here.
61
+ const NO_AS_CONST = {
62
+ selector: "TSAsExpression[typeAnnotation.typeName.name='const']",
63
+ message:
64
+ "Give the value a real type where it is declared, not as const.",
65
+ };
66
+
59
67
  const config = [
60
68
  {
61
69
  ignores: [
@@ -111,6 +119,7 @@ const config = [
111
119
  "no-restricted-syntax": [
112
120
  "error",
113
121
  NO_SATISFIES,
122
+ NO_AS_CONST,
114
123
  ...RESTRICTED_SYNTAX,
115
124
  ...SINGLE_OBJECT_PARAMETER,
116
125
  ],
@@ -215,6 +224,7 @@ const config = [
215
224
  rules: {
216
225
  "no-restricted-syntax": [
217
226
  "error",
227
+ NO_AS_CONST,
218
228
  ...RESTRICTED_SYNTAX,
219
229
  ...SINGLE_OBJECT_PARAMETER,
220
230
  ],
@@ -227,6 +237,7 @@ const config = [
227
237
  "no-restricted-syntax": [
228
238
  "error",
229
239
  NO_SATISFIES,
240
+ NO_AS_CONST,
230
241
  ...RESTRICTED_SYNTAX,
231
242
  ],
232
243
  },
@@ -57,6 +57,14 @@ const NO_SATISFIES = {
57
57
  "Type a value where it is declared, not with satisfies afterwards.",
58
58
  };
59
59
 
60
+ // Give a value a real type instead. consistent-type-assertions always
61
+ // lets `as const` through, so it is banned here.
62
+ const NO_AS_CONST = {
63
+ selector: "TSAsExpression[typeAnnotation.typeName.name='const']",
64
+ message:
65
+ "Give the value a real type where it is declared, not as const.",
66
+ };
67
+
60
68
  const config = [
61
69
  {
62
70
  ignores: [
@@ -113,6 +121,7 @@ const config = [
113
121
  "no-restricted-syntax": [
114
122
  "error",
115
123
  NO_SATISFIES,
124
+ NO_AS_CONST,
116
125
  ...RESTRICTED_SYNTAX,
117
126
  ...SINGLE_OBJECT_PARAMETER,
118
127
  ],
@@ -213,6 +222,7 @@ const config = [
213
222
  rules: {
214
223
  "no-restricted-syntax": [
215
224
  "error",
225
+ NO_AS_CONST,
216
226
  ...RESTRICTED_SYNTAX,
217
227
  ...SINGLE_OBJECT_PARAMETER,
218
228
  ],
@@ -55,6 +55,14 @@ const NO_SATISFIES = {
55
55
  "Type a value where it is declared, not with satisfies afterwards.",
56
56
  };
57
57
 
58
+ // Give a value a real type instead. consistent-type-assertions always
59
+ // lets `as const` through, so it is banned here.
60
+ const NO_AS_CONST = {
61
+ selector: "TSAsExpression[typeAnnotation.typeName.name='const']",
62
+ message:
63
+ "Give the value a real type where it is declared, not as const.",
64
+ };
65
+
58
66
  const config = [
59
67
  {
60
68
  ignores: [
@@ -102,6 +110,7 @@ const config = [
102
110
  "no-restricted-syntax": [
103
111
  "error",
104
112
  NO_SATISFIES,
113
+ NO_AS_CONST,
105
114
  ...RESTRICTED_SYNTAX,
106
115
  ...SINGLE_OBJECT_PARAMETER,
107
116
  ],
@@ -193,6 +202,7 @@ const config = [
193
202
  rules: {
194
203
  "no-restricted-syntax": [
195
204
  "error",
205
+ NO_AS_CONST,
196
206
  ...RESTRICTED_SYNTAX,
197
207
  ...SINGLE_OBJECT_PARAMETER,
198
208
  ],
@@ -11,11 +11,13 @@ Replace loose types with precise ones in the given files.
11
11
  2. Find every loose type in scope:
12
12
  - `any`, written or implied
13
13
  - Non-null assertions (`value!`)
14
- - Type casts (`value as SomeType`), except `as const`
14
+ - Type casts (`value as SomeType`)
15
+ - `as const`
15
16
  3. Fix each one:
16
17
  - Replace `any` with the real type, or with `unknown` narrowed by a check
17
18
  - Replace `value!` with a check that the value exists
18
19
  - Replace a cast with validation or a properly typed source
20
+ - Replace `as const` with a real type where the value is declared, from `lib/types/` for a constant, putting any exact values in the type
19
21
  4. Follow the naming rule for every type you add or rename: the name ends in `Props` (the object parameter of a component or function) or `Type` (everything else).
20
22
  5. Run `pnpm typecheck`, then `pnpm lint`. Fix any errors your changes caused.
21
23
  6. Report each change: the file, what the type was, and what it is now. List anything you could not tighten, and why.
@@ -28,6 +28,14 @@ type ElementMeasurementType = {
28
28
  opacity: number;
29
29
  };
30
30
 
31
+ // The sides of a box that must not move.
32
+ const BOX_SIDES: readonly (keyof ElementMeasurementType)[] = [
33
+ "x",
34
+ "y",
35
+ "width",
36
+ "height",
37
+ ];
38
+
31
39
  type PageProps = { page: Page };
32
40
 
33
41
  type ScrollStopType = {
@@ -116,7 +124,7 @@ const describeDifferences = ({
116
124
  differences.push(`${key} is missing`);
117
125
  continue;
118
126
  }
119
- const isBoxMoved = (["x", "y", "width", "height"] as const).some(
127
+ const isBoxMoved = BOX_SIDES.some(
120
128
  (side) =>
121
129
  Math.abs(before[side] - after[side]) > BOX_TOLERANCE_PIXELS,
122
130
  );