@activatus/code-standards 3.3.1 โ†’ 3.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -32,9 +32,9 @@ pnpm add -D @activatus/code-standards@latest
32
32
 
33
33
  Then tell your agent: **"Follow the Activatus Code Standards. Start with `node_modules/@activatus/code-standards/docs/Guides/setup.md`."** It prints a numbered list of the standards, you say which ones you don't want, and it sets up the rest. You never touch the terminal.
34
34
 
35
- The package version is the standards version: `3.0.0` is version 3.
35
+ The package version is the standards version, and a project records it in full, such as `3.3.2`, so the agent always knows where the project's up to.
36
36
 
37
- > ๐Ÿ”ข **Updating a project to newer standards?** Run `pnpm add -D @activatus/code-standards@latest`, then point the agent at the **[Version History](https://activatus-code-standards.vercel.app/docs/version-history)**: it reads only the versions newer than the project's, does exactly what each one says, and bumps the number. Cheaper than shouting the whole pub a round.
37
+ > ๐Ÿ”ข **Updating a project to newer standards?** Run `pnpm add -D @activatus/code-standards@latest`, then point the agent at the **[Version History](https://activatus-code-standards.vercel.app/docs/version-history)**: it reads only the entries newer than the project's version, does exactly what each one says, and records the new version. Cheaper than shouting the whole pub a round.
38
38
 
39
39
  ---
40
40
 
@@ -90,6 +90,7 @@ The full detail's on the site. This is the version you'd tell someone over a sch
90
90
  - ๐Ÿ—ฃ๏ธ **Every name is real English words.** Variables, props, form fields, types, files, folders, the lot. `button`, not `btn`. We're not paying by the letter. The one exception: names someone else owns, like Linear's `id` or Node's `cwd` option.
91
91
  - ๐Ÿ”’ **Always `const`.** Need `let`? Fine, but leave a comment saying why, or the linter knocks it back.
92
92
  - ๐Ÿน **Arrow functions everywhere.** `const Button = () => {}`. The word `function` is clutter, so we don't use it.
93
+ - ๐Ÿงน **Imports sort themselves.** Prettier puts them in order every time you format, so nobody burns an afternoon shuffling them by hand.
93
94
  - ๐Ÿ”„ **No circular imports. Ever.** If two files import each other, pull the shared bit into a third file.
94
95
  - ๐ŸŽฏ **A function does one thing.** If you need the word "and" to describe it, it's two functions.
95
96
  - ๐Ÿงช **Every function and component gets a test file.** One test file, one thing tested. No test, not finished.
@@ -97,6 +98,7 @@ The full detail's on the site. This is the version you'd tell someone over a sch
97
98
  - ๐Ÿ“ฆ **One parameter per function.** Need more? Pass an object, so the call explains itself.
98
99
  - ๐Ÿšช **Return early.** Deal with the dodgy cases up top instead of nesting four `if`s deep like a set of Russian dolls.
99
100
  - ๐Ÿ”ข **No magic numbers.** `MAXIMUM_RETRY_ATTEMPTS`, not a random `3` sitting there like it owns the place.
101
+ - ๐Ÿ—ƒ๏ธ **Links go in `r`, words people see go in `s`.** Everything else sits at the top of the file that uses it until something else needs it too. Not sure where a value goes? The agent parks it in `unsortedValues.ts` and asks you at the end, instead of stopping the job to have a yarn about it.
100
102
  - ๐Ÿท๏ธ **Type names end in `Props` or `Type`.** So you can tell what you're looking at.
101
103
  - ๐Ÿ’ฌ **Comments explain why, not what.** And no commented-out code. Git remembers, you don't have to.
102
104
 
@@ -116,6 +118,28 @@ The full detail's on the site. This is the version you'd tell someone over a sch
116
118
 
117
119
  - ๐Ÿงญ **Branches, commit messages, Pull Requests and whether AI agents may commit are up to each project.** Every team runs its work differently, so it goes in the project's own `AGENTS.md` and docs, not here. These standards are the base for the code itself.
118
120
 
121
+ ### ๐Ÿšฆ Status circles
122
+
123
+ Setup asks if you want them. Say yes, and the agent reports every ticket or piece of work as one line, with a circle that tells you at a glance whether you need to lift a finger:
124
+
125
+ | Circle | Means |
126
+ | ------ | ---------------------------------------------------------------------------- |
127
+ | โœ… | Merged, in UAT or done. Nothing to do |
128
+ | ๐ŸŸข | Pull Request ready for you to review and merge. The link is the Pull Request |
129
+ | ๐ŸŸฃ | The agent's working on it |
130
+ | ๐ŸŸก | Done and checked, but not committed yet. You commit it, or tell the agent to |
131
+ | ๐ŸŸ  | Waiting on another ticket or Pull Request first |
132
+ | ๐Ÿ”ด | Blocked, or you need to do something. It says what |
133
+ | โšช | Not started |
134
+
135
+ A line looks like this:
136
+
137
+ ```text
138
+ ๐ŸŸข ACT-12 Short title: #19
139
+ ```
140
+
141
+ The ticket ID links to the ticket and the number links to the Pull Request. Only what you need to act on makes the list: no essay about what it did while you were at smoko. Full detail in [Working with Agents](https://activatus-code-standards.vercel.app/docs/Standards/working-with-agents#status-circles).
142
+
119
143
  ### ๐Ÿ“ฆ Third-party code
120
144
 
121
145
  - ๐Ÿ“ฆ **Third-party code is exempt.** Anything in `node_modules/` or `vendor/` isn't ours. Don't lint it, don't tidy it, leave it be.
@@ -144,6 +168,7 @@ static/templates/
144
168
  โ”œโ”€โ”€ eslint/ # ๐Ÿšจ Four flavours: base, typescript, react, nextjs
145
169
  โ”œโ”€โ”€ stylelint/ # ๐Ÿ’… CSS and SCSS
146
170
  โ”œโ”€โ”€ prettier.config.mjs # โœจ Formatting
171
+ โ”œโ”€โ”€ .prettierignore # ๐Ÿ™ˆ What Prettier leaves alone
147
172
  โ”œโ”€โ”€ globals.css # ๐ŸŽจ Tailwind + starter colour palette
148
173
  โ”œโ”€โ”€ .editorconfig # โŒจ๏ธ Editor whitespace rules
149
174
  โ””โ”€โ”€ .nvmrc / .envrc # ๐ŸŸข Node version switching
@@ -180,7 +205,7 @@ Reckon a rule's wrong, or there's one missing? Good. Standards that never change
180
205
  1. ๐ŸŒฟ **Branch off `main`**, named after the ticket (`ACT-14-update-eslint-page`), or `type/short-description` if there's no ticket (`docs/update-eslint-page`).
181
206
  2. ๐Ÿ“ **Edit or add a Markdown file in `docs/`.** Name it in kebab-case (`naming-conventions.md`, not `namingConventions.md`), because the file name becomes the page's URL. Yes, we follow our own rules here.
182
207
  3. ๐Ÿ“‹ **Changing a config?** Edit the file in `static/templates/` and the matching page in `docs/Standards/` so the two don't drift apart. For an ESLint config, run `pnpm check:eslint-templates`: it lints each config against itself and fails if the ESLint page shows an old copy. Add `--update-docs` to copy the configs onto the page.
183
- 4. ๐Ÿ”ข **Add a version** to `docs/version-history.md`: what changed, and what a project has to do about it. Bump the major version in `package.json` to match (version 3 is `3.0.0`), and publish it to npm (npmjs.com) once it's merged. We use pnpm for everything, so that's `pnpm publish`, which lands in the same npm registry as `npm publish`. Projects read only the new versions, so if it's not in there, nobody hears about it.
208
+ 4. ๐Ÿ”ข **Add a version** to `docs/version-history.md`: what changed, and what a project has to do about it. Bump `package.json` to match: the first number when most projects rework most of their code, the middle when files move, the last when only the inside of files changes. See [How versions are numbered](https://activatus-code-standards.vercel.app/docs/version-history#how-versions-are-numbered). Publish it to npm (npmjs.com) once it's merged. We use pnpm for everything, so that's `pnpm publish`, which lands in the same npm registry as `npm publish`. Projects read only the new versions, so if it's not in there, nobody hears about it.
184
209
  5. ๐Ÿ”จ **Run `pnpm build`.** It fails on broken links, so you'll know quick smart if you've stuffed one.
185
210
  6. ๐Ÿš€ **Open a pull request** and say why the change makes life better.
186
211
 
@@ -61,7 +61,7 @@ Applies setup standards 7, 9 and 10. Three commits, in this order:
61
61
  1. **The config files.** Rename every config to `.mjs` ([why](/docs/Guides/setup#5-apply-the-standards)). Add `prettier.config.mjs` from the [Prettier page](/docs/Standards/prettier), with its `format` and `format:check` scripts, `.editorconfig`, `.nvmrc` and `.envrc`. Do not reformat anything yet.
62
62
 
63
63
  ```bash
64
- pnpm add -D prettier prettier-plugin-tailwindcss
64
+ pnpm add -D prettier @ianvs/prettier-plugin-sort-imports prettier-plugin-tailwindcss
65
65
  ```
66
66
 
67
67
  2. **The reformat, on its own.** Run `pnpm format` and commit the result with nothing else in it. Every file changes, and none of it changes behaviour.
@@ -179,16 +179,16 @@ node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs --list rena
179
179
 
180
180
  ## Stage 4 โ€” Constants
181
181
 
182
- Applies setup standard 12.1. Move every link into `r`, every piece of text into `s`, every loose number into `numbers.ts`, motion into `animation.ts`, drawing layouts into `artwork.ts`, and class names shared between files into `classNames.ts`, all in `lib/constants/`. See [Constants](/docs/Structure/folder-structure#constants).
182
+ Applies setup standard 12.1. Move every link into `r` and every piece of text people see or hear into `s`, in `lib/constants/`. Every other value stays with the code that uses it until more than one file needs it; a shared value moves to the file in `lib/constants/` that fits. See [Constants](/docs/Structure/folder-structure#constants).
183
183
 
184
184
  - **Move the values, nothing else.** The page must look and work exactly as before.
185
- - **No component-level `constants.ts` survives this stage.**
186
- - **Move animation and artwork objects whole.** Never pull their numbers out into `numbers.ts`. Any other file in `lib/constants/` is folded into the standard file that fits.
187
- - **Where each value goes is the project's call.** Read the [Constants table](/docs/Structure/folder-structure#constants) and decide. A value that fits none goes in the closest file, with a comment naming its entry under "Details" in `coding-standards.md`.
185
+ - **A value one file uses moves to the top of that file.** A component's own constants file is folded into the files that use it, or into `lib/constants/` for the values more than one file shares.
186
+ - **Move animation and artwork objects whole.** Never pull their numbers out into `numbers.ts`.
187
+ - **Where each value goes is the project's call.** Read the [Constants table](/docs/Structure/folder-structure#constants) and decide. When it is not clear, put the value in `lib/constants/unsortedValues.ts`, carry on, and ask the person at the end of the stage: see [When it is not clear where a value goes](/docs/Structure/folder-structure#unsorted-values).
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
- - **Every object and list constant except `r` and `s` gets a real type from `lib/types/`**, never `as const`. A single number or string needs none. 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).
191
+ - **Every object and list constant in `lib/constants/` except `r` and `s` gets a real type from `lib/types/`**, never `as const`. A constant at the top of the file that uses it is typed from that file's own `.types.ts`. A single number or string needs none. 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
 
@@ -72,8 +72,17 @@ It builds the project and starts the production build on port 3100, then measure
72
72
  - **It runs against a production build**, on its own port, never against `pnpm dev`.
73
73
  - **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.
74
74
  - **The test files are frozen** for the whole refactor: an agent never edits them to make a check pass.
75
+ - **Record a check only after it has run.** `docs/testing/regression.md` says what was decided, and gets the baseline's source and each result only once they exist. Never write a URL, commit, date or "passed" for a check that has not happened yet.
75
76
  - **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.
76
77
 
78
+ ## Comparing two local servers instead
79
+
80
+ A project that skips Playwright can still compare the page before and after: run the last known-good commit and the branch side by side, each with `next dev` on its own port, and compare their rendered HTML or screenshots.
81
+
82
+ - **Export the old commit to its own folder**, such as with `git worktree add ../before-refactor <commit>`.
83
+ - **Copy `node_modules` into it. Never symlink it.** Turbopack refuses a `node_modules` that points outside the project folder. On macOS, `cp -Rc node_modules ../before-refactor/` makes a copy-on-write clone in seconds that takes almost no extra disk space.
84
+ - **Record what was compared, and the result, only once it has run**, the same as the Playwright check.
85
+
77
86
  ## The blind spot
78
87
 
79
88
  **A frozen clock only samples fixed moments.** The check measures each scroll stop after moving the clock on by the same amount every time. A change to the timing between those moments, such as an animation that now runs slower but ends in the same place, passes. When a refactor touches animation timing, check those parts by eye as well.
@@ -37,10 +37,13 @@ minimumReleaseAgeExclude:
37
37
 
38
38
  Newer pnpm versions may add this exclusion for you when you run `pnpm add`. Check the file either way, and add it if it is not there: an update hits the same check when a new version of the standards has only just been published. 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.
39
39
 
40
- **pnpm owns `pnpm-workspace.yaml`** and rewrites it on every install, with single quotes, so `pnpm format:check` would fail after every update. Add the file to `.prettierignore`:
40
+ **Copy `static/templates/.prettierignore`** to the project root, or add its lines to the project's own. pnpm owns `pnpm-workspace.yaml` and rewrites it on every install, with single quotes, so `pnpm format:check` would fail after every update. `AGENTS.md` and the agent skills are copied from the standards and compared word for word by the [standards check](#checking-a-project), so Prettier must leave them alone too:
41
41
 
42
42
  ```text title=".prettierignore"
43
43
  pnpm-workspace.yaml
44
+ AGENTS.md
45
+ .agents/skills/
46
+ .claude/commands/
44
47
  ```
45
48
 
46
49
  The standards are now in `node_modules/@activatus/code-standards/`:
@@ -83,8 +86,8 @@ Tell me the numbers to skip or change, or say "all good".
83
86
  10. Node version set by .nvmrc and direnv
84
87
  11. Styling: Tailwind, flexbox first, colours only from the global palette
85
88
  12. Folder structure: folders at the project root; reusable helper functions in utils/ (no business rules, no outside calls)
86
- 12.1. Constants: r for every link, s for every piece of text, every loose number in numbers.ts, noData for stand-in data, animation, artwork and shared class names in their own files, all in lib/constants/
87
- 13. Components live where they are used: components/ui/, components/shared/, or beside their page
89
+ 12.1. Constants: r for every link and s for every piece of text, in lib/constants/; other values stay with the code that uses them until they are shared
90
+ 13. Components live where they are used: components/ui/, components/layout/, components/shared/, or beside their page
88
91
  14. Component files in a fixed order, with index.ts exports, and server and client code in separate files
89
92
  15. Design System Components: every project builds the standard components with the same props
90
93
  16. Imports: no circular imports, import from folders not files
@@ -113,7 +116,14 @@ Then wait for the answer.
113
116
  | "Change 7: we use Biome for formatting" | Apply 7 as they describe it |
114
117
  | Something unclear | Ask. Do not guess |
115
118
 
116
- **Record the answer** in `docs/development/coding-standards.md`, under "Details". For each skipped or changed standard, write its number, its name, what is different, and the reason the person gave. If nothing is different, write "No differences". Copy the file from `static/templates/docs/development/coding-standards.md` if it does not exist.
119
+ **Record the answer** in `docs/development/coding-standards.md`, under "Details". For each skipped or changed standard, write one line with its number and name from the list, then what is different and the reason the person gave. An exception that covers only some files names them, in backticks, after `for`:
120
+
121
+ ```text
122
+ - 7. Prettier โ€” skipped: the project uses Biome for formatting (2026-10-23).
123
+ - 4. Every function and component has a test file โ€” changed for `app/api/**`: legacy routes, tested when each is replaced (2026-10-27).
124
+ ```
125
+
126
+ **Every path after `for` goes in backticks**: a `for` with none fails the check, because it would otherwise cover every file. **Start no other line under "Details" with a number.** The [standards check](#checking-a-project) reads a line that starts with a number as an exception to that standard, and fails on one it cannot read. Use bullet points for anything else. If nothing is different, write "No differences". Copy the file from `static/templates/docs/development/coding-standards.md` if it does not exist.
117
127
 
118
128
  The list has nothing about branches or commit messages. Those are the project's own workflow. Ask the person how they work, and write it in the "Project workflow" section of `AGENTS.md`. See [Project workflow](/docs/Standards/agent-specs#project-workflow).
119
129
 
@@ -165,17 +175,17 @@ Do only the standards the person agreed to. Copy every file from `node_modules/@
165
175
 
166
176
  **An existing project with code already in it** also needs its code brought up to the standards. Do that with [Migrating an Existing Project](/docs/Guides/migrating), one stage at a time, after the config files below are in place.
167
177
 
168
- | Standard | What to set up |
169
- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
170
- | 6. ESLint | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`, and copy `static/templates/eslint.overrides.mjs` beside it. Install the packages listed on the [ESLint page](/docs/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"` |
171
- | 7. Prettier | `pnpm add -D prettier prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the `format` and `format:check` scripts exactly as on the [Prettier page](/docs/Standards/prettier#usage) |
172
- | 8. Stylelint | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/docs/Standards/stylelint) |
173
- | 9. EditorConfig | Copy `static/templates/.editorconfig` |
174
- | 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv) |
175
- | 11. Styling | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette |
176
- | 12.1. Constants | Create `lib/constants/` with `routes.ts` (`r`), `strings.ts` (`s`), `numbers.ts` and an `index.ts` that exports them. Create `noData.ts` later, once the data's shape is decided, and `animation.ts`, `artwork.ts` and `classNames.ts` once there is something to put in them. If the project keeps them somewhere else, such as `app/constants/`, move them. See [Constants](/docs/Structure/folder-structure#constants) |
177
- | 18. Docs | Copy `static/templates/docs/` to `docs/` and `static/templates/docsSite/` to `docsSite/`. Add the `/docs` route from `static/templates/next.config.mjs`. See [Setting it up](/docs/Standards/documentation#-setting-it-up) |
178
- | 21. AGENTS.md and skills | Copy `static/templates/AGENTS.md` to the project root and fill in every `[placeholder]`. If the framework wrote its own `AGENTS.md` (Next.js does), keep any instruction it gives about reading the framework's own docs. Copy `static/templates/skills/` into `.agents/skills/`, and again into `.claude/commands/`. Add the `standards:check` script: see [Checking a project](#checking-a-project) |
178
+ | Standard | What to set up |
179
+ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
180
+ | 6. ESLint | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`, and copy `static/templates/eslint.overrides.mjs` beside it. Install the packages listed on the [ESLint page](/docs/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"` |
181
+ | 7. Prettier | `pnpm add -D prettier @ianvs/prettier-plugin-sort-imports prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the `format` and `format:check` scripts exactly as on the [Prettier page](/docs/Standards/prettier#usage) |
182
+ | 8. Stylelint | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/docs/Standards/stylelint) |
183
+ | 9. EditorConfig | Copy `static/templates/.editorconfig` |
184
+ | 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv) |
185
+ | 11. Styling | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette |
186
+ | 12.1. Constants | Create `lib/constants/` with `routes.ts` (`r`), `strings.ts` (`s`) and an `index.ts` that exports them. Create `noData.ts` once the data's shape is decided, and `numbers.ts`, `animation.ts`, `status.ts` and the others once more than one file shares a value. If the project keeps them somewhere else, such as `app/constants/`, move them. See [Constants](/docs/Structure/folder-structure#constants) |
187
+ | 18. Docs | Copy `static/templates/docs/` to `docs/` and `static/templates/docsSite/` to `docsSite/`. Add the `/docs` route from `static/templates/next.config.mjs`. See [Setting it up](/docs/Standards/documentation#-setting-it-up) |
188
+ | 21. AGENTS.md and skills | Copy `static/templates/AGENTS.md` to the project root and fill in every `[placeholder]`. If the framework wrote its own `AGENTS.md` (Next.js does), keep any instruction it gives about reading the framework's own docs. Copy `static/templates/skills/` into `.agents/skills/`, and again into `.claude/commands/`. Add the `standards:check` script: see [Checking a project](#checking-a-project) |
179
189
 
180
190
  The other standards are rules for how code is written. There is nothing to install for them: follow them in every change.
181
191
 
@@ -258,15 +268,15 @@ It reports, and never changes a file. Each finding gives the standard's number a
258
268
  | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
259
269
  | 21 | `AGENTS.md` has the code standards version and an unchanged Code standards section; the skills match the templates |
260
270
  | 6 to 10 | `eslint.config.mjs`, `prettier.config.mjs`, `stylelint.config.mjs`, `.editorconfig` and `.envrc` match the templates; `eslint.overrides.mjs`, `.nvmrc` and the format scripts are in place |
261
- | 12.1 | `lib/constants/` has `index.ts`, `routes.ts`, `strings.ts` and `numbers.ts`, no component has its own `constants.ts`, and no other file sits beside the seven standard ones |
262
- | 13 | Every sub-component sits flat in its root component's `components/` folder, and the homepage is in `app/(homepage)/` |
263
- | 21 | `docs/development/coding-standards.md` records the five agent answers under "Details" |
271
+ | 12.1 | `lib/constants/` has `index.ts`, `routes.ts` and `strings.ts`, and no `unsortedValues.ts` is left waiting |
272
+ | 13 | `components/` holds only `ui/`, `layout/` and `shared/`, every sub-component sits flat in its root component's `components/` folder, and the homepage is in `app/(homepage)/` |
273
+ | 21 | `docs/development/coding-standards.md` records the five agent answers under "Details", and every numbered line there is a well-formed exception |
264
274
  | 11 | `docs/design/design-system.md` has a filled-in Colour palette table |
265
275
  | 15 | Every `components/ui/` component is on the Design System Components list, or recorded under "Components for the standards" |
266
276
  | 4 | Every file that exports a function or component has a test file beside it |
267
277
  | 18 | Every doc template is in place, and every doc has one "Group โ€” Menu item" title matching its file name, a Status line, and Decision, Why and Related sections |
268
278
 
269
- **It follows the project's own rules, not only the standard ones.** A finding for a standard recorded as skipped or changed in `docs/development/coding-standards.md` is listed as a recorded exception to check by hand, and does not fail the check. The project's ESLint changes live in `eslint.overrides.mjs`, which it never compares. It also lists any Unfinished changes.
279
+ **It follows the project's own rules, not only the standard ones.** A finding for a standard recorded as skipped or changed in `docs/development/coding-standards.md` is listed as a recorded exception to check by hand, and does not fail the check. An exception that names files covers only those files. A numbered line under "Details" that is not shaped like an exception fails the check, because it would otherwise switch a standard off by accident. The project's ESLint changes live in `eslint.overrides.mjs`, which it never compares. It also lists any Unfinished changes.
270
280
 
271
281
  **The check is a helper, not the standard.** Passing it does not mean every rule is followed: names, the order inside a component and much more still need reading. And a finding that is wrong for the project is not fixed by bending the code to the script: record the exception in `coding-standards.md`, with the person's yes.
272
282
 
@@ -357,5 +357,6 @@ Converting a doc does not change its decision, so the **Updated** date stays as
357
357
  - **Read the files directly.** Do not start the docs site to read them.
358
358
  - **Check the Status.** `Decided` is settled. `Current plan` may change. `Under evaluation` and `Not started` are **not decisions** โ€” do not treat them as one, and do not invent one. Ask.
359
359
  - **Update the docs in the same change** as the code, and change the **Updated** date.
360
+ - **Record a check only after it has run.** Never write a URL, commit, date or "passed" for a check that has not happened yet. Write what was decided, and add the result once it exists.
360
361
  - **Write into the matching file.** Create a new file only when a topic has no home, in kebab-case, using the [doc format](#-the-doc-format).
361
362
  - **Do not edit anything in `docsSite/`** unless the task is about the docs viewer itself.
@@ -196,8 +196,8 @@ const config = [
196
196
  rules: { "max-lines": "off", "no-magic-numbers": "off" },
197
197
  },
198
198
  {
199
- // The seven constants files are data, not logic, so they can be long.
200
- files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.{js,mjs}"],
199
+ // The constants files are data, not logic, so they can be long.
200
+ files: ["lib/constants/*.{js,mjs}"],
201
201
  rules: { "max-lines": "off" },
202
202
  },
203
203
  {
@@ -401,8 +401,8 @@ const config = [
401
401
  },
402
402
  },
403
403
  {
404
- // The seven constants files are data, not logic, so they can be long.
405
- files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
404
+ // The constants files are data, not logic, so they can be long.
405
+ files: ["lib/constants/*.ts"],
406
406
  rules: { "max-lines": "off" },
407
407
  },
408
408
  {
@@ -646,8 +646,8 @@ const config = [
646
646
  },
647
647
  },
648
648
  {
649
- // The seven constants files are data, not logic, so they can be long.
650
- files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
649
+ // The constants files are data, not logic, so they can be long.
650
+ files: ["lib/constants/*.ts"],
651
651
  rules: { "max-lines": "off" },
652
652
  },
653
653
  {
@@ -893,8 +893,8 @@ const config = [
893
893
  },
894
894
  },
895
895
  {
896
- // The seven constants files are data, not logic, so they can be long.
897
- files: ["lib/constants/{routes,strings,numbers,noData,animation,artwork,classNames}.ts"],
896
+ // The constants files are data, not logic, so they can be long.
897
+ files: ["lib/constants/*.ts"],
898
898
  rules: { "max-lines": "off" },
899
899
  },
900
900
  {
@@ -1054,7 +1054,7 @@ Every `eslint-disable` comment must say why, after `--`. A rule is never switche
1054
1054
 
1055
1055
  ### `max-lines: 300`
1056
1056
 
1057
- No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt, and so are the seven constants files in `lib/constants/` (`routes.ts`, `strings.ts`, `numbers.ts`, `noData.ts`, `animation.ts`, `artwork.ts` and `classNames.ts`), which hold data only. See [Readable Code](/docs/Standards/readable-code#no-file-longer-than-300-lines).
1057
+ No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt, and so are the files in `lib/constants/`, which hold data only. See [Readable Code](/docs/Standards/readable-code#no-file-longer-than-300-lines).
1058
1058
 
1059
1059
  ### `max-depth: 3`
1060
1060
 
@@ -1091,7 +1091,7 @@ Named exports only. Default exports are allowed where a tool requires them: conf
1091
1091
 
1092
1092
  ### Import order is not linted
1093
1093
 
1094
- There is deliberately no import-**order** rule (circular imports are a different matter โ€” see above). Follow the [Import Organization](/docs/Structure/import-organization) pattern for consistency, but ESLint will not complain about it.
1094
+ There is deliberately no import-**order** rule (circular imports are a different matter โ€” see above). Prettier sorts imports instead, every time a file is formatted: see [Import sorting](/docs/Standards/prettier#import-sorting).
1095
1095
 
1096
1096
  ### `unicorn/filename-case: camelCase or PascalCase`
1097
1097
 
@@ -10,7 +10,7 @@ A single shared Prettier config keeps formatting consistent and eliminates "styl
10
10
  ## Installation
11
11
 
12
12
  ```bash
13
- pnpm add -D prettier prettier-plugin-tailwindcss
13
+ pnpm add -D prettier @ianvs/prettier-plugin-sort-imports prettier-plugin-tailwindcss
14
14
  ```
15
15
 
16
16
  ## Usage
@@ -18,7 +18,7 @@ pnpm add -D prettier prettier-plugin-tailwindcss
18
18
  Create `prettier.config.mjs` in your project root:
19
19
 
20
20
  ```js title="prettier.config.mjs"
21
- /** @type {import("prettier").Config & import("prettier-plugin-tailwindcss").PluginOptions} */
21
+ /** @type {import("prettier").Config & import("@ianvs/prettier-plugin-sort-imports").PluginConfig & import("prettier-plugin-tailwindcss").PluginOptions} */
22
22
  const config = {
23
23
  // Short lines, so code reads well on a phone.
24
24
  printWidth: 70,
@@ -32,7 +32,25 @@ const config = {
32
32
  arrowParens: "always",
33
33
  semi: true,
34
34
  endOfLine: "lf",
35
- plugins: ["prettier-plugin-tailwindcss"],
35
+ // The Tailwind plugin must stay last.
36
+ plugins: [
37
+ "@ianvs/prettier-plugin-sort-imports",
38
+ "prettier-plugin-tailwindcss",
39
+ ],
40
+ // Node's own modules, packages, the project's @/ aliases, then
41
+ // ../ and ./, with a blank line between groups. Side-effect
42
+ // imports, such as CSS, never move.
43
+ importOrder: [
44
+ "<BUILTIN_MODULES>",
45
+ "",
46
+ "<THIRD_PARTY_MODULES>",
47
+ "",
48
+ "^@/",
49
+ "",
50
+ "^[.][.]/",
51
+ "",
52
+ "^[.]/",
53
+ ],
36
54
  tailwindStylesheet: "./app/globals.css",
37
55
  overrides: [
38
56
  {
@@ -72,11 +90,15 @@ Both scripts work on the same list of files: every file git tracks, plus every n
72
90
  | One person's local tool files, such as `.claude/settings.local.json` | That person's `.git/info/exclude` or global git ignore. Never `.prettierignore` |
73
91
  | Files the whole project keeps out of git, such as `build/` | `.gitignore` |
74
92
  | Files in git that Prettier must not format, such as `pnpm-workspace.yaml` | `.prettierignore`, shared by the whole project |
93
+ | `AGENTS.md`, `.agents/skills/` and `.claude/commands/` | `.prettierignore`, shared by the whole project |
75
94
 
76
- pnpm rewrites `pnpm-workspace.yaml` in its own style on every install, so it always goes in `.prettierignore`:
95
+ pnpm rewrites `pnpm-workspace.yaml` in its own style on every install, so it always goes in `.prettierignore`. So do `AGENTS.md` and the agent skills: they are copied from the standards, and `pnpm standards:check` compares them word for word, so a Prettier rewrite would fail it. The template has all four: copy `static/templates/.prettierignore`.
77
96
 
78
97
  ```text title=".prettierignore"
79
98
  pnpm-workspace.yaml
99
+ AGENTS.md
100
+ .agents/skills/
101
+ .claude/commands/
80
102
  ```
81
103
 
82
104
  ## Tailwind class sorting
@@ -93,7 +115,36 @@ The config includes [`prettier-plugin-tailwindcss`](https://github.com/tailwindl
93
115
 
94
116
  - **It is part of the standard**, not a project extra. Every project that uses Tailwind has it.
95
117
  - **`tailwindStylesheet` points at the project's global stylesheet**, so the plugin knows the project's own colours. Change the path if `globals.css` lives somewhere else.
96
- - **A project with no Tailwind** (a plain Node.js service) removes the `plugins` and `tailwindStylesheet` lines.
118
+ - **A project with no Tailwind** (a plain Node.js service) removes `prettier-plugin-tailwindcss` from `plugins`, and the `tailwindStylesheet` line.
119
+
120
+ ## Import sorting {#import-sorting}
121
+
122
+ The config includes [`@ianvs/prettier-plugin-sort-imports`](https://github.com/IanVS/prettier-plugin-sort-imports). It sorts the imports of every file when the file is formatted, so **nobody sorts imports by hand, and agents never reorder them themselves**: `pnpm format`, or saving in the editor, does it.
123
+
124
+ ```tsx
125
+ "use client";
126
+
127
+ import { readFileSync } from "node:fs";
128
+
129
+ import Link from "next/link";
130
+ import { useState } from "react";
131
+
132
+ import { Button } from "@/components/ui";
133
+ import { r, s } from "@/lib/constants";
134
+
135
+ import { formatDate } from "../utils/formatDate";
136
+
137
+ import type { SampleProps } from "./Sample.types";
138
+
139
+ import "./sample.css";
140
+ ```
141
+
142
+ - **The groups, in order:** Node's own modules (`node:fs`), packages, the project's `@/` aliases, parent folders (`../`), then the same folder (`./`). Each group is alphabetical, with a blank line between groups.
143
+ - **Directives such as `"use client"` stay at the top.**
144
+ - **Side-effect imports never move**, such as `import "./globals.css";`, because the order they load in can matter. The plugin sorts the imports above and below one separately. **Put them after every other import**, so the rest sort as one block. Never add a setting that moves them.
145
+ - **Type imports stay on their own line**, `import type { CardProps } from "./Card.types";`. Leave `importOrderTypeScriptVersion` unset: setting it to 4.5 or above merges type imports into value imports.
146
+ - **`prettier-plugin-tailwindcss` stays last in `plugins`.** The Tailwind plugin needs that to work beside other plugins.
147
+ - **Switching it on reorders the imports in most files.** Do it in a commit of its own, with nothing else in it, so the reordering never hides a real change in a review.
97
148
 
98
149
  ## Settings reference
99
150
 
@@ -43,7 +43,7 @@ A file over 300 lines is doing more than one job. Split it before it gets there:
43
43
 
44
44
  Blank lines and comments do not count towards the limit. **Test files are exempt** โ€” a thorough test file can run long.
45
45
 
46
- **The seven constants files in `lib/constants/` are exempt too**: `routes.ts`, `strings.ts`, `numbers.ts`, `noData.ts`, `animation.ts`, `artwork.ts` and `classNames.ts`. They are lists of data, not logic, and a big app has a lot of links, text and motion. Splitting them would mean more places to look for one label. They stay data only: no functions in them. See [Constants](/docs/Structure/folder-structure#constants).
46
+ **The files in `lib/constants/` are exempt too**, such as `routes.ts`, `strings.ts` and `numbers.ts`. They are lists of data, not logic, and a big app has a lot of links, text and motion. Splitting them would mean more places to look for one label. They stay data only: no functions in them. See [Constants](/docs/Structure/folder-structure#constants).
47
47
 
48
48
  ---
49
49
 
@@ -313,7 +313,7 @@ if (order.status === "shipped") {
313
313
 
314
314
  **`-1`, `0` and `1` are allowed**, because they are part of how code works rather than a choice anyone makes: `0` is the start or nothing (`items[0]`, `length === 0`), `1` is one more or one less (`index + 1`), and `-1` is "not found" (`indexOf`). Any other number was chosen by someone, so its name says what it controls. Even `2` gets a name.
315
315
 
316
- Every loose named number lives in `lib/constants/numbers.ts`, even one only one file uses. Numbers that only mean something together, such as the steps of an animation, stay whole as one object in `animation.ts` or `artwork.ts`. See [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic) for where they go, and [Naming Conventions](/docs/Structure/naming-conventions#constants) for how to name them.
316
+ A number only one file uses is a named constant at the top of that file; a number more than one file uses lives in `lib/constants/numbers.ts`. Numbers that only mean something together, such as the steps of an animation, stay whole as one object in `animation.ts` or `artwork.ts`. See [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic) for where they go, and [Naming Conventions](/docs/Structure/naming-conventions#constants) for how to name them.
317
317
 
318
318
  ---
319
319