@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.
@@ -7,27 +7,44 @@ sidebar_label: "Version History"
7
7
 
8
8
  > What changed in each version of the standards, and exactly what a project has to do about it. Written for the AI agent doing the update.
9
9
 
10
- **Every change to the standards gets a new version number.** Each project records the version it follows in its `AGENTS.md`, under "Code standards":
10
+ **Every change to the standards gets a new version number.** Each project records the full version it last applied in its `AGENTS.md`, under "Code standards", so the project pairs with the package and knows where to start:
11
11
 
12
12
  ```md
13
- **Code standards version:** 2
13
+ **Code standards version:** 3.2.2
14
14
  ```
15
15
 
16
+ ## How versions are numbered
17
+
18
+ | Part that changes | Example | Means |
19
+ | ----------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
20
+ | First | 3.2.2 → 4.0.0 | A major update: it changes how most of a project's code is written, so every project reworks it |
21
+ | Middle | 3.2.2 → 3.3.0 | Files move: the update moves or renames files in a project. Plan it, and take a regression baseline first |
22
+ | Last | 3.2.2 → 3.2.3 | Changes inside files only. Nothing moves |
23
+
24
+ **The first number goes up only when most projects must rework most of their code**, such as a new framework or a standard replaced by a different one. A rule added, changed or clarified never bumps it. Every new number can ask for work, whichever part changed. 3.1.1 and 3.2.1 came out before this rule and moved files in a last-number update; their moves are listed under **Structural changes**.
25
+
16
26
  ## Updating a project to a new version
17
27
 
18
- **Read only the versions newer than the project's.** A project on version 1 that is updating to version 3 reads version 2 and version 3 on this page, and nothing else. Do not re-read every standard or check the whole codebase: each version lists every change that matters, and how to find the code it affects.
28
+ **Read only the entries newer than the project's version.** A project on 3.2.1 updating to 3.3.0 reads the 3.2.2 and 3.3.0 entries on this page, and nothing else. **A project that recorded only a major number, such as `3`,** first finds the full version it actually applied: the `@activatus/code-standards` version in `pnpm-lock.yaml` at the last commit that changed its `**Code standards version:**` line. Record that version in `AGENTS.md` and start from there. Only when it cannot tell does it read every entry of that major version from its start:
29
+
30
+ ```bash
31
+ git show "$(git log -1 --format=%h -G'Code standards version' -- AGENTS.md)":pnpm-lock.yaml \
32
+ | grep -o "@activatus/code-standards@[0-9.]*" | head -1
33
+ ```
34
+
35
+ Do not re-read every standard or check the whole codebase: each version lists every change that matters, and how to find the code it affects.
19
36
 
20
- 1. **Find the project's version** in its `AGENTS.md`. If there is none, the project has never followed the standards: follow [Setup](/docs/Guides/setup) instead.
37
+ 1. **Find the project's version** in its `AGENTS.md`. If it is only a major number, find the full one first, as above. If there is none, the project has never followed the standards: follow [Setup](/docs/Guides/setup) instead.
21
38
  2. **Update the package:** `pnpm add -D @activatus/code-standards@latest`, never a typed version number. If pnpm refuses because the version is too new, add the package to `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`, as in [Setup](/docs/Guides/setup#1-install-the-standards). The entry is the plain package name, with no version. If pnpm wrote one with versions in it, such as `'@activatus/code-standards@3.0.4 || 3.0.5'`, replace it with the plain name: otherwise pnpm adds another version to it on every update. Then read this page from `node_modules/@activatus/code-standards/docs/version-history.md`.
22
- 3. **Read each version newer than the project's**, oldest first. Skip any change to a standard the project opted out of: they are listed in `docs/development/coding-standards.md`.
39
+ 3. **Read each entry newer than the project's version**, oldest first. For a middle-number entry, take the [regression check](/docs/Guides/regression-checks) baseline before any file moves. Skip any change to a standard the project opted out of: they are listed in `docs/development/coding-standards.md`.
23
40
  4. **For each change, do the "What to do" steps**, then run the "How to check" searches. A search that still finds something means the change is not finished. When a change says to copy a line from the `AGENTS.md` template, and the project's `AGENTS.md` records the standards in its own words instead, write the updated rule there in the project's own shape.
24
41
  5. **Strike out what the standard now covers.** After the changes, re-read the project's list of opted-out and changed standards in `docs/development/coding-standards.md`. Take off the list any exception the new version has made part of the standard, and update any rule it records for an old shape of the standard. A differences list that still describes the old standard sends the next agent wrong.
25
42
  6. **Run `pnpm lint`, `pnpm format:check`, `pnpm test` and the build** after each change. `format:check` checks every file git does not ignore; never narrow it to changed files.
26
43
  7. **Ask any [Working with the agent](/docs/Guides/setup#4-working-with-the-agent) question** whose answer is not recorded in `docs/development/coding-standards.md`, under "Details".
27
44
  8. **Run `pnpm standards:check`**, and fix what it finds. See [Checking a project](/docs/Guides/setup#checking-a-project).
28
- 9. **Update the version number** in `AGENTS.md` once every change is done.
45
+ 9. **Set the version** in `AGENTS.md` to the installed package's full version once every change is done.
29
46
 
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).
47
+ **A project already on the installed full version** has no version changes to make: follow [Already on this version](/docs/Guides/setup#already-on-this-version).
31
48
 
32
49
  **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
50
 
@@ -35,47 +52,133 @@ sidebar_label: "Version History"
35
52
 
36
53
  Anyone changing the standards adds a version, alongside the change:
37
54
 
38
- - **One version per release**, numbered one higher than the last. Whole numbers only. A version can collect several changes before it is released.
39
- - **Bump the package's major version to match** in `package.json`: version 3 is `3.0.0`. Then publish it to npm (npmjs.com) with `pnpm publish`. pnpm is the tool; npm is where the package lives, and projects install it from there with `pnpm add`.
55
+ - **Pick the number from [How versions are numbered](#how-versions-are-numbered).** A major update is `4.0.0`. An update that moves files bumps the middle number, `3.2.2` → `3.3.0`. An update that only changes the inside of files bumps the last, `3.2.2` → `3.2.3`. Set it in `package.json`, then publish it to npm (npmjs.com) with `pnpm publish`. pnpm is the tool; npm is where the package lives, and projects install it from there with `pnpm add`.
40
56
  - **For every change, write:** what changed, why, what to do in a project, and how to check it is done. Write it for an agent that has not read the rest of the standards.
41
57
  - **If a project has nothing to do, say so.**
42
58
  - **Newest version at the top.**
43
- - **Work in progress goes under `## Version N — not released yet`**, with a line saying projects should not apply it yet. Changes can be added to it over time. To release it: pilot it (below), drop "not released yet", add the **Released** date and **Updates from** line, set `package.json` to `N.0.0`, then publish.
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
- - **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
- - **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.
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.
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.
59
+ - **Work in progress on a major update goes under `## Version N — not released yet`**, with a line saying projects should not apply it yet. Changes can be added to it over time. To release it: drop "not released yet", add the **Released** date and **Updates from** line, set `package.json` to `N.0.0`, then publish.
60
+ - **Changing a released major version** goes under its version, newest at the top. Update the version's changes in place where they are now wrong. Write each entry so a project already on the version before it knows what to do.
61
+ - **Every entry is headed `**Fixes in 3.2.3.**`**, with its number, followed by "If the project already applied 3.2.2, check these:".
62
+ - **A middle-number entry adds `**Structural changes in 3.3.0.**` straight under its heading**, listing each change that moves or renames files in a project, with a rough size, such as "one move per file", so a project can plan the work and take a [regression check](/docs/Guides/regression-checks) baseline first. A last-number entry never moves files.
63
+ - **Every release commit is titled `docs: version N.N.N — <what changed>`**, such as `docs: version 3.2.2 — full version numbers`, so releases are easy to find in the git log.
64
+ - **Every number is published.** Publish each one to npm as soon as its entry is written. A Fixes entry for a version that was never published sends a project to install something that does not exist.
50
65
  - **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.
51
66
 
52
67
  ---
53
68
 
54
69
  ## Version 3
55
70
 
56
- **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.2.1
71
+ **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest:** 3.3.0
57
72
 
58
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.
59
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
+
119
+ **Fixes in 3.2.2.** If the project already applied 3.2.1, check these:
120
+
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.
122
+
123
+ **What to do:** if `AGENTS.md` records only a major number, find the full version the project applied from its lockfile, as in [Updating a project to a new version](#updating-a-project-to-a-new-version), and start this update from there. Copy the Code standards section of `AGENTS.md` from the template again. When the update is done, set the version to the installed package's full version.
124
+
125
+ - **The standards are the base, and agents build freely from there.** The `AGENTS.md` template now says so: most code is something the standards never mention, and the agent decides it and keeps it the same across the codebase. Only skipping, loosening or changing a standard needs the person's yes; the agent then records it and keeps going, never stopping to wait for a new version of the standards. Copied in with the section above.
126
+
127
+ - **Where each constant goes is the project's call.** The [Constants table](/docs/Structure/folder-structure#constants) says what each file is for, not where every value in every project goes. 3.2.1's examples and check named values from one project; they are now neutral, and `pnpm standards:check` no longer guesses a value's file from its name. It lists the file, and the project decides.
128
+
129
+ **What to do:** best practice is every value in `lib/constants/` in the file the table says fits, with ids and CSS following the two rules below. Bring the project's values in line with that. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`.
130
+
131
+ - **An id lives in the object that uses it.** A value that picks which item something acts on is a key inside that object, never a loose constant. A list of keys a loop runs over stays a list. See the [before and after](/docs/Structure/folder-structure#constants-rules).
132
+
133
+ **What to do:** move each loose id constant into the object that uses it.
134
+
135
+ - **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 media query the code reads, such as one an animation library matches, is not CSS: it stays in its object in `animation.ts`.
136
+
137
+ **What to do:** move any CSS string out of `lib/constants/` and components into `globals.css`.
138
+
139
+ - **`s` holds only text people see or hear.** Internal strings, such as ids, keys, event names and 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.
140
+
141
+ **What to do:** nothing, unless the project moved internal strings into `s`. Move those back beside the code that uses them.
142
+
143
+ - **`animation.ts` and `artwork.ts` are split by one question.** Where something ends up is artwork; how and when it gets there is animation. Drawing data the code reads goes in `artwork.ts`; a static drawing nothing reads goes in an `.svg` file or an icon component. `classNames.ts` can hold a set of class names keyed by variant, named `_CLASS_NAMES`. Nothing to move unless the project placed a value by the old wording.
144
+
145
+ - **The regression baseline comes first.** Take it before any file moves, then do the constants moves and the folder moves as separate steps, with a full regression run after each. See [Stage 0](/docs/Guides/migrating#stage-0--regression-check).
146
+
147
+ - **`pnpm standards:check` reports headings for standards 11 and 13**, which 3.2.1 printed blank. Nothing to do.
148
+
149
+ - **Setup asks a fifth agent question:** does the person want to be told about coding decisions the agent makes that the code standards do not cover? Someone who reads the code may want to hear each one; someone who does not may not care. See [Told about decisions](/docs/Standards/working-with-agents#told-about-decisions).
150
+
151
+ **What to do:** ask the person the question in [setup step 4](/docs/Guides/setup#4-working-with-the-agent), and add the answer to the "Working with the agent" line under "Details" in `coding-standards.md`. If they said yes, add the rule under **Decisions** in the Project workflow section of `AGENTS.md`.
152
+
153
+ **How to check:** `AGENTS.md` records the full installed version; `pnpm standards:check` passes, or lists only recorded exceptions; these searches find nothing, or only values the project has recorded:
154
+
155
+ ```bash
156
+ # CSS written in TypeScript, however it is quoted, on one line or many
157
+ grep -rnE "@media|@keyframes|!important|[a-z-]+: *[^;,]*(px|rem|none|auto|block|flex|grid);" \
158
+ lib/constants/ app/ components/ --include='*.ts' --include='*.tsx' --exclude='*.test.*'
159
+ # A loose id constant
160
+ grep -rnE "export const [A-Z_]+_ID = " lib/constants/
161
+ ```
162
+
60
163
  **Fixes in 3.2.1.** If the project already applied 3.2.0, check these:
61
164
 
62
165
  **Structural changes in 3.2.1.** These move files. Plan them, and run a [regression check](/docs/Guides/regression-checks) first:
63
166
 
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.
167
+ - Every component `constants.ts`, and every other file in `lib/constants/`, moves into the seven standard files: one move per file. `pnpm standards:check` lists them.
168
+ - Every sub-component folder that is not directly in its root component's `components/` folder moves there: one move per folder. If the project did 3.1.1's move, only folders inside a grouping folder are left. `pnpm standards:check` lists them.
66
169
 
67
170
  - **`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.
171
+ - **`animation.ts`**: how and when things move.
172
+ - **`artwork.ts`**: what is drawn, where it ends up, and how it is grouped.
173
+ - **`classNames.ts`**: Tailwind class names shared between files, only when a component cannot hold them and they still repeat. A class name one file uses stays inline.
71
174
 
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).
175
+ Each animation and artwork object stays whole, its values named by their keys. Never lift them out into `numbers.ts`, which keeps loose single numbers only: lifting them out makes long names and splits one object across files. Each file is one file, never split by topic. See [Constants](/docs/Structure/folder-structure#constants).
73
176
 
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.
177
+ **What to do:** move every component `constants.ts`, and every other file in `lib/constants/`, into the seven files. Where each value goes is the project's call: read the [Constants table](/docs/Structure/folder-structure#constants), decide each value's home. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`, and the work carries on. 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
178
 
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).
179
+ - **A loop over a list looks each item up by its key.** Write a key out by name when you mean one item, `r.plans.starter`. Inside a loop over the list, use the item's key, typed from `r`: `keyof typeof r.plans`. Delete separate lookup objects that map a key to its link: `r` already is that lookup. See [A list of items with links](/docs/Structure/folder-structure#a-list-of-items-with-links).
77
180
 
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.
181
+ - **`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 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
182
 
80
183
  - **Keep every docs folder.** 3.2.0's rule is final: no docs folder is deleted, even one that does not apply yet.
81
184
 
@@ -100,8 +203,8 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
100
203
 
101
204
  - The homepage moves into `app/(homepage)/`: `app/page.tsx` and the homepage's components. Small.
102
205
  - 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.
206
+ - Every component `constants.ts` moves into `lib/constants/`: one move per file. Follow the 3.2.1 rule, not this version's.
207
+ - Every nested sub-component folder moves flat into its parent's `components/` folder: one move per folder.
105
208
  - `r` or `s` split into several files only to stay under 300 lines goes back into one file. Small.
106
209
 
107
210
  - **`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:
@@ -132,7 +235,7 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
132
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._
133
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).
134
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`.
135
- - **`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._
136
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.`
137
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.
138
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.1",
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",
@@ -8,7 +8,9 @@ import { readTextFile } from "./projectFiles.mjs";
8
8
  const SECTION_START = "<!-- code-standards:start -->";
9
9
  const SECTION_END = "<!-- code-standards:end -->";
10
10
  const VERSION_LINE_START = "**Code standards version:**";
11
- const VERSION_PATTERN = /\*\*Code standards version:\*\*\s*(\d+)/;
11
+ const VERSION_PATTERN =
12
+ /\*\*Code standards version:\*\*\s*(\d+(?:\.\d+){0,2})/;
13
+ const VERSION_PART_COUNT = 3;
12
14
  const SKILL_FOLDERS = [".agents/skills", ".claude/commands"];
13
15
  const PAGE = "docs/Standards/agent-specs.md";
14
16
 
@@ -29,28 +31,68 @@ const readStandardsSection = (agentsText) => {
29
31
  : undefined;
30
32
  };
31
33
 
32
- const checkVersion = ({ agentsText, packageMajorVersion }) => {
34
+ const toVersionParts = (version) =>
35
+ Array.from({ length: VERSION_PART_COUNT }, (_unused, index) =>
36
+ Number(version.split(".")[index] ?? 0),
37
+ );
38
+
39
+ // Below zero when the project's version is older than the package's,
40
+ // above zero when it is newer, and zero when they match.
41
+ const compareVersions = ({ projectVersion, packageVersion }) => {
42
+ const projectParts = toVersionParts(projectVersion);
43
+ const packageParts = toVersionParts(packageVersion);
44
+ const differentIndex = projectParts.findIndex(
45
+ (part, index) => part !== packageParts[index],
46
+ );
47
+ return differentIndex === -1
48
+ ? 0
49
+ : projectParts[differentIndex] - packageParts[differentIndex];
50
+ };
51
+
52
+ const checkVersion = ({ agentsText, packageVersion }) => {
33
53
  const match = VERSION_PATTERN.exec(agentsText);
34
54
  if (!match) {
35
55
  return [
36
56
  {
37
57
  standard: "21",
38
58
  message:
39
- "AGENTS.md has no code standards version. Set **Code standards version:** to the major version the code follows",
59
+ "AGENTS.md has no code standards version. Set **Code standards version:** to the full version the code follows, such as 3.2.2",
40
60
  page: "docs/Guides/setup.md",
41
61
  },
42
62
  ];
43
63
  }
44
- const projectVersion = Number(match[1]);
45
- if (projectVersion < packageMajorVersion) {
64
+ const projectVersion = match[1];
65
+ if (projectVersion.split(".").length < VERSION_PART_COUNT) {
66
+ return [
67
+ {
68
+ standard: "21",
69
+ message: `AGENTS.md records version ${projectVersion}, not a full version. Record the full version the project last applied, such as 3.1.0: read the @activatus/code-standards version in pnpm-lock.yaml at the last commit that changed the version line, then update from there`,
70
+ page: "docs/version-history.md#updating-a-project-to-a-new-version",
71
+ },
72
+ ];
73
+ }
74
+ const comparison = compareVersions({
75
+ projectVersion,
76
+ packageVersion,
77
+ });
78
+ if (comparison < 0) {
46
79
  return [
47
80
  {
48
81
  standard: "21",
49
- message: `AGENTS.md says version ${projectVersion}, and the installed package is version ${packageMajorVersion}. Follow "Updating to a newer version"`,
82
+ message: `AGENTS.md says version ${projectVersion}, and the installed package is version ${packageVersion}. Follow "Updating to a newer version"`,
50
83
  page: "docs/Guides/setup.md#updating-to-a-newer-version",
51
84
  },
52
85
  ];
53
86
  }
87
+ if (comparison > 0) {
88
+ return [
89
+ {
90
+ standard: "21",
91
+ message: `AGENTS.md says version ${projectVersion}, newer than the installed package, version ${packageVersion}. Correct the version in AGENTS.md, or install the package with @latest`,
92
+ page: "docs/Guides/setup.md#2-work-out-where-the-project-is",
93
+ },
94
+ ];
95
+ }
54
96
  return [];
55
97
  };
56
98
 
@@ -125,7 +167,7 @@ const checkSkills = ({ projectDirectory, templatesDirectory }) => {
125
167
  export const checkAgentFiles = ({
126
168
  projectDirectory,
127
169
  templatesDirectory,
128
- packageMajorVersion,
170
+ packageVersion,
129
171
  }) => {
130
172
  const agentsText = readTextFile({
131
173
  projectDirectory,
@@ -141,7 +183,7 @@ export const checkAgentFiles = ({
141
183
  ];
142
184
  }
143
185
  return [
144
- ...checkVersion({ agentsText, packageMajorVersion }),
186
+ ...checkVersion({ agentsText, packageVersion }),
145
187
  ...checkStandardsSection({ agentsText, templatesDirectory }),
146
188
  ...checkSkills({ projectDirectory, templatesDirectory }),
147
189
  ];
@@ -1,7 +1,5 @@
1
1
  // Standard 12.1: lib/constants/ holds the seven standard files and
2
2
  // nothing else, and no component keeps its own constants file.
3
- import { readTextFile } from "./projectFiles.mjs";
4
-
5
3
  const REQUIRED_FILES = [
6
4
  "lib/constants/index.ts",
7
5
  "lib/constants/routes.ts",
@@ -18,67 +16,10 @@ const OPTIONAL_FILES = [
18
16
  const CONSTANTS_FOLDER = "lib/constants/";
19
17
  const COMPONENT_CONSTANTS_PATTERN = /(^|\/)constants\.tsx?$/;
20
18
  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
19
  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
- };
20
+ // Where each value goes is the project's call, made from the table.
21
+ const NEXT_STEP =
22
+ "Move each of its values into the file the Constants table says fits, and record any value that fits none in docs/development/coding-standards.md";
82
23
 
83
24
  const checkMissingFiles = ({ projectFileSet }) =>
84
25
  REQUIRED_FILES.filter(
@@ -89,7 +30,7 @@ const checkMissingFiles = ({ projectFileSet }) =>
89
30
  page: PAGE,
90
31
  }));
91
32
 
92
- const checkExtraFiles = ({ projectDirectory, projectFiles }) => {
33
+ const checkExtraFiles = ({ projectFiles }) => {
93
34
  const standardFiles = new Set([
94
35
  ...REQUIRED_FILES,
95
36
  ...OPTIONAL_FILES,
@@ -101,27 +42,24 @@ const checkExtraFiles = ({ projectDirectory, projectFiles }) => {
101
42
  .filter((filePath) => !standardFiles.has(filePath))
102
43
  .map((filePath) => ({
103
44
  standard: "12.1",
104
- message: `${filePath} is not one of the seven constants files. ${suggestHomes({ projectDirectory, filePath })}`,
45
+ message: `${filePath} is not one of the seven constants files. ${NEXT_STEP}`,
105
46
  page: PAGE,
106
47
  }));
107
48
  };
108
49
 
109
- const checkComponentFiles = ({ projectDirectory, projectFiles }) =>
50
+ const checkComponentFiles = ({ projectFiles }) =>
110
51
  projectFiles
111
52
  .filter((filePath) => !filePath.startsWith(CONSTANTS_FOLDER))
112
53
  .filter((filePath) => !filePath.startsWith("node_modules/"))
113
54
  .filter((filePath) => COMPONENT_CONSTANTS_PATTERN.test(filePath))
114
55
  .map((filePath) => ({
115
56
  standard: "12.1",
116
- message: `${filePath}: there is no component-level constants file. ${suggestHomes({ projectDirectory, filePath })}`,
57
+ message: `${filePath}: there is no component-level constants file. ${NEXT_STEP}`,
117
58
  page: PAGE,
118
59
  }));
119
60
 
120
- export const checkConstants = ({
121
- projectDirectory,
122
- projectFiles,
123
- }) => [
61
+ export const checkConstants = ({ projectFiles }) => [
124
62
  ...checkMissingFiles({ projectFileSet: new Set(projectFiles) }),
125
- ...checkExtraFiles({ projectDirectory, projectFiles }),
126
- ...checkComponentFiles({ projectDirectory, projectFiles }),
63
+ ...checkExtraFiles({ projectFiles }),
64
+ ...checkComponentFiles({ projectFiles }),
127
65
  ];
@@ -1,4 +1,4 @@
1
- // What setup asks the person and writes down: the four agent answers
1
+ // What setup asks the person and writes down: the five agent answers
2
2
  // (standard 21) and the colour palette (standard 11).
3
3
  import {
4
4
  CODING_STANDARDS_PATH,
@@ -12,6 +12,10 @@ const AGENT_ANSWERS = [
12
12
  { name: "the Linear project", pattern: /linear/i },
13
13
  { name: "the status circles", pattern: /status circles?/i },
14
14
  { name: "asking before committing", pattern: /commit/i },
15
+ {
16
+ name: "being told about decisions",
17
+ pattern: /told about decisions/i,
18
+ },
15
19
  ];
16
20
  // The template's unfilled line: "[link or None]", "[yes or no]".
17
21
  const UNFILLED_ANSWER_PATTERN = /\[[^\]]+ or [^\]]+\]/;
@@ -5,14 +5,16 @@ import path from "node:path";
5
5
  import { PACKAGE_DIRECTORY } from "./projectFiles.mjs";
6
6
 
7
7
  // The names from the numbered list in docs/Guides/setup.md.
8
- const STANDARD_NAMES = {
8
+ export const STANDARD_NAMES = {
9
9
  4: "Every function and component has a test file",
10
10
  6: "ESLint",
11
11
  7: "Prettier",
12
12
  8: "Stylelint",
13
13
  9: "EditorConfig",
14
14
  10: "Node version",
15
+ 11: "Styling",
15
16
  12.1: "Constants",
17
+ 13: "Components live where they are used",
16
18
  15: "Design System Components",
17
19
  18: "Docs",
18
20
  21: "AGENTS.md and the agent skills",
@@ -17,16 +17,12 @@ import {
17
17
  readRecordedExceptions,
18
18
  } from "./projectFiles.mjs";
19
19
 
20
- const readPackageMajorVersion = () => {
20
+ const readPackageVersion = () => {
21
21
  const packageText = readFileSync(
22
22
  path.join(PACKAGE_DIRECTORY, "package.json"),
23
23
  "utf8",
24
24
  );
25
- const [majorVersion] = JSON.parse(packageText).version.split(
26
- ".",
27
- 1,
28
- );
29
- return Number(majorVersion);
25
+ return JSON.parse(packageText).version;
30
26
  };
31
27
 
32
28
  export const runChecks = ({ projectDirectory }) => {
@@ -43,11 +39,11 @@ export const runChecks = ({ projectDirectory }) => {
43
39
  ...checkAgentFiles({
44
40
  projectDirectory,
45
41
  templatesDirectory,
46
- packageMajorVersion: readPackageMajorVersion(),
42
+ packageVersion: readPackageVersion(),
47
43
  }),
48
44
  ...checkConfigFiles({ projectDirectory, templatesDirectory }),
49
45
  ...checkRequiredFiles({ templatesDirectory, projectFiles }),
50
- ...checkConstants({ projectDirectory, projectFiles }),
46
+ ...checkConstants({ projectFiles }),
51
47
  ...checkStructure({ projectFiles }),
52
48
  ...checkRecordedAnswers({ projectDirectory }),
53
49
  ...checkComponents({
@@ -42,6 +42,7 @@
42
42
  [How this project runs its work. These are the project's own decisions, not part of the code standards. Say where they are written up (usually `docs/development/`), then list the rules an agent must follow:]
43
43
 
44
44
  - **Who commits**: [whether AI agents may commit, push or make branches, and when. If the person said yes to asking before committing during setup: "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, leave the asking rule out]
45
+ - **Decisions**: [Optional. If the person said yes to being told about decisions during setup: "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." Delete this line if they said no]
45
46
  - **Branches**: [how branches are named]
46
47
  - **Commit messages**: [the commit message format]
47
48
  - **Pull requests**: [review and CI requirements, and where Pull Requests merge to]
@@ -109,13 +110,15 @@ The project's docs are plain Markdown in `docs/`. **Every file is a Decision Doc
109
110
 
110
111
  This project follows the Activatus Code Standards. They are installed as the `@activatus/code-standards` dev dependency: **read them in `node_modules/@activatus/code-standards/docs/`**, which is the exact version this project uses. The same pages are at https://activatus-code-standards.vercel.app for people.
111
112
 
112
- **Code standards version:** [the major version of the installed `@activatus/code-standards` package when the standards were last applied]
113
+ **Code standards version:** [the full version of the installed `@activatus/code-standards` package when the standards were last applied, such as 3.2.2]
113
114
 
114
- This is the version the code follows. It is the major version only: fixes such as 3.1.1 keep it at 3, but can still ask for changes, so read the Fixes for the installed version on every update. When the package is updated, read only the newer versions in `node_modules/@activatus/code-standards/docs/version-history.md`, make the changes they list, then update this number. See "Updating to a newer version" in `docs/Guides/setup.md`.
115
+ This is the version the code follows, written in full so it pairs with the installed package. When the package is updated, read only the entries newer than this number in `node_modules/@activatus/code-standards/docs/version-history.md`, make the changes they list, then update this number. See "Updating to a newer version" in `docs/Guides/setup.md`.
116
+
117
+ **The standards are the base, and you build freely from there.** Most of a project's code is something the standards never mention: decide it yourself, and keep the decision the same across the codebase. This covers how the code is built: its structure, names, files and where each value goes. It never covers what the product does, says or shows: those are product decisions, and you ask. Only skipping, loosening or changing a standard needs the person's yes.
115
118
 
116
119
  **Standards this project skips or changes** are listed, by number, in `docs/development/coding-standards.md`. Follow every other standard.
117
120
 
118
- **The standards are this project's base. Never skip, loosen or change one on your own.** Ask the person first. If they agree, record it in `docs/development/coding-standards.md`, under "Details" (the standard's number and name, what is different, why, and the date), then make the change. ESLint changes go in `eslint.overrides.mjs` with a comment naming the standard's number. Never edit `eslint.config.mjs`: it is copied from the standards unchanged.
121
+ **The standards are this project's base. Never skip, loosen or change one on your own.** Ask the person first. If they agree, record it in `docs/development/coding-standards.md`, under "Details" (the standard's number and name, what is different, why, and the date), then make the change and keep going. Never stop the work to wait for a new version of the standards. ESLint changes go in `eslint.overrides.mjs` with a comment naming the standard's number. Never edit `eslint.config.mjs`: it is copied from the standards unchanged.
119
122
 
120
123
  Follow these rules in every change:
121
124
 
@@ -146,11 +149,11 @@ Follow these rules in every change:
146
149
  - **One parameter per function.** Use a single object when more than one value is needed.
147
150
  - **Return early.** Never nest more than three levels deep.
148
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`.
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
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
150
153
  - **No nested ternaries. No boolean flag parameters.**
151
154
  - **No `any`, no non-null `!`, no `as` cast without a comment saying why.**
152
155
  - **Named exports only**, except where a tool requires a default export.
153
- - **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>`.
154
157
  - **One component per file.** Server and client components live in separate files.
155
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.
156
159
  - **Component file order**: imports, component, variables, state, `useMemo` values, `useCallback` functions, effects, render. No inline functions in render.