@activatus/code-standards 3.1.0 → 3.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/docs/Guides/migrating.md +14 -0
  2. package/docs/Guides/setup.md +55 -20
  3. package/docs/Standards/documentation.md +17 -7
  4. package/docs/Standards/eslint.md +54 -14
  5. package/docs/Standards/lint-errors.md +4 -4
  6. package/docs/Standards/readable-code.md +4 -1
  7. package/docs/Standards/stylelint.md +9 -3
  8. package/docs/Standards/styling.md +5 -1
  9. package/docs/Standards/working-with-agents.md +5 -5
  10. package/docs/Structure/component-organization.md +30 -26
  11. package/docs/Structure/folder-structure.md +85 -32
  12. package/docs/Structure/import-organization.md +4 -4
  13. package/docs/design-system-components.md +16 -12
  14. package/docs/ontology.md +1 -1
  15. package/docs/templates.mdx +2 -2
  16. package/docs/version-history.md +48 -5
  17. package/package.json +1 -1
  18. package/static/templates/AGENTS.md +18 -9
  19. package/static/templates/docs/design/design-system.md +6 -0
  20. package/static/templates/docs/development/coding-standards.md +6 -2
  21. package/static/templates/docs/overview/how-it-works.md +1 -1
  22. package/static/templates/docs/product/ontology.md +32 -0
  23. package/static/templates/eslint/base/eslint.config.mjs +9 -0
  24. package/static/templates/eslint/nextjs/eslint.config.mjs +9 -0
  25. package/static/templates/eslint/react/eslint.config.mjs +9 -0
  26. package/static/templates/eslint/typescript/eslint.config.mjs +9 -0
  27. package/static/templates/eslint.overrides.mjs +18 -0
  28. package/static/templates/skills/codeReview.md +2 -1
  29. package/static/templates/stylelint/css/stylelint.config.mjs +3 -1
  30. package/static/templates/stylelint/scss/stylelint.config.mjs +3 -1
@@ -416,40 +416,42 @@ This makes it easy to spot component folders and keeps them consistent with file
416
416
 
417
417
  ## Nested Components
418
418
 
419
- For components with sub-components, give each sub-component its own folder:
419
+ For components with sub-components, give each sub-component its own folder, inside the parent's `components/` folder:
420
420
 
421
421
  ```text
422
422
  components/
423
423
  └── card/
424
424
  ├── Card.tsx
425
425
  ├── Card.test.tsx
426
- ├── cardHeader/
427
- │ ├── CardHeader.tsx
428
- │ ├── CardHeader.test.tsx
429
- │ ├── types.ts
430
- │ └── index.ts
431
- ├── cardBody/
432
- │ ├── CardBody.tsx
433
- │ ├── CardBody.test.tsx
434
- │ ├── types.ts
435
- │ └── index.ts
436
- ├── cardFooter/
437
- │ ├── CardFooter.tsx
438
- │ ├── CardFooter.test.tsx
439
- │ ├── types.ts
440
- │ └── index.ts
426
+ ├── components/
427
+ │ ├── cardHeader/
428
+ │ │ ├── CardHeader.tsx
429
+ │ │ ├── CardHeader.test.tsx
430
+ │ │ ├── types.ts
431
+ │ │ └── index.ts
432
+ │ ├── cardBody/
433
+ │ │ ├── CardBody.tsx
434
+ │ │ ├── CardBody.test.tsx
435
+ │ │ ├── types.ts
436
+ │ │ └── index.ts
437
+ │ └── cardTitleArrow/ # Used only by CardHeader, but sits beside it
438
+ │ ├── CardTitleArrow.tsx
439
+ │ ├── CardTitleArrow.test.tsx
440
+ │ ├── types.ts
441
+ │ └── index.ts
441
442
  ├── types.ts
442
- └── index.ts # Re-exports all sub-components
443
+ └── index.ts # Re-exports the card and its sub-components
443
444
  ```
444
445
 
446
+ **Every sub-component sits flat in the parent's one `components/` folder**, even one that only another sub-component uses, such as `cardTitleArrow`. There is never a `components/` folder inside a sub-component, so a component is at most two levels deep: the component, then its sub-components. Deeper folders are hard to find and make long import paths.
447
+
445
448
  ### `index.ts` for Nested Components
446
449
 
447
450
  ```typescript
448
451
  // Card/index.ts
449
452
  export { Card } from "./Card";
450
- export { CardHeader } from "./cardHeader";
451
- export { CardBody } from "./cardBody";
452
- export { CardFooter } from "./cardFooter";
453
+ export { CardHeader } from "./components/cardHeader";
454
+ export { CardBody } from "./components/cardBody";
453
455
  export type { CardProps } from "./types";
454
456
  ```
455
457
 
@@ -463,15 +465,17 @@ Inside a component's folder, import files directly. **Never import through the f
463
465
 
464
466
  ```typescript
465
467
  // card/Card.tsx — the parent imports its sub-components
466
- import { CardBody } from "./cardBody";
467
- import { CardHeader } from "./cardHeader";
468
+ import { CardBody } from "./components/cardBody";
469
+ import { CardHeader } from "./components/cardHeader";
468
470
  import type { CardProps } from "./types";
469
471
 
470
- // card/cardBody/CardBody.tsx — a sub-component imports types by file
471
- import type { CardProps } from "../types";
472
+ // card/components/cardHeader/CardHeader.tsx — a sub-component imports
473
+ // a sibling sub-component through its folder, and types by file
474
+ import { CardTitleArrow } from "../cardTitleArrow";
475
+ import type { CardProps } from "../../types";
472
476
 
473
477
  // ❌ Bad — a sub-component importing its parent through the index
474
- import { Card } from "..";
478
+ import { Card } from "../..";
475
479
  ```
476
480
 
477
481
  ### From Other Components
@@ -495,7 +499,7 @@ import { Card, CardHeader, CardBody } from "@/components/ui/card";
495
499
 
496
500
  Consider creating separate component folders when:
497
501
 
498
- 1. **Used by more than one page** → Move to the section's `components/` folder, or `components/shared/`
502
+ 1. **Used by more than one page** → Copy it on the second use, and merge the copies into the section's `components/` folder or `components/shared/` on the third. See [Where components live](/docs/Structure/folder-structure#rules)
499
503
  2. **Complex logic** → Separate file for clarity
500
504
  3. **Multiple variants** → Sub-components in same folder
501
505
  4. **Shared styles** → Keep co-located
@@ -38,8 +38,10 @@ project-root/
38
38
  │ │ └── webhooks/
39
39
  │ │ └── stripe/
40
40
  │ │ └── route.ts
41
- │ ├── layout.tsx
42
- │ └── page.tsx
41
+ │ ├── (homepage)/ # The homepage, served at /
42
+ │ │ ├── components/ # Used only by the homepage
43
+ │ │ └── page.tsx
44
+ │ └── layout.tsx
43
45
  ├── components/ # React components
44
46
  │ ├── ui/ # Design System Components
45
47
  │ │ └── button/ # Example component structure
@@ -48,7 +50,8 @@ project-root/
48
50
  │ │ ├── Button.stories.tsx # Storybook stories
49
51
  │ │ ├── types.ts # Component types
50
52
  │ │ └── index.ts # Export file
51
- │ └── shared/ # Used by more than one page
53
+ │ ├── layout/ # The site frame: navigation, header, footer
54
+ │ └── shared/ # Used by three or more pages
52
55
  ├── lib/ # Outside connections and app-wide setup
53
56
  │ ├── permissions/ # Who may do what
54
57
  │ │ ├── index.ts # Main definitions
@@ -133,46 +136,65 @@ project-root/
133
136
 
134
137
  ## 🧩 Where components live
135
138
 
136
- **A component lives where it is used.** There are no feature folders: a component either belongs to one page, to one section, or is shared.
139
+ **A component lives where it is used.** There are no feature folders: a component belongs to one page or one section, is shared, or is part of the site frame.
137
140
 
138
141
  | Used by | Lives in | Example |
139
142
  | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------- |
140
143
  | **Every project the same way** — the [Design System Components](/docs/design-system-components) | `components/ui/` | `components/ui/button/` |
141
- | **More than one page** of this project | `components/shared/` | `components/shared/siteHeader/` |
142
- | **A few pages in one section** | A `components/` folder in that section's route group | `app/(billing)/components/invoiceTable/` |
143
- | **One page only** | A `components/` folder in that page's route folder | `app/account-settings/components/accountForm/` |
144
+ | **The site frame** — navigation, header, footer | `components/layout/` | `components/layout/siteHeader/` |
145
+ | **Three or more pages** of this project | `components/shared/` | `components/shared/pricingTable/` |
146
+ | **Three or more pages in one section** | A `components/` folder in that section's route group | `app/(billing)/components/invoiceTable/` |
147
+ | **One or two pages** | A `components/` folder in that page's route folder | `app/account-settings/components/accountForm/` |
148
+ | **The homepage** | `app/(homepage)/components/` | `app/(homepage)/components/heroSection/` |
144
149
 
145
150
  A route group is a folder in brackets, such as `(billing)`. It groups pages without changing their URLs: `app/(billing)/invoices/page.tsx` is served at `/invoices`.
146
151
 
152
+ **The homepage is a route group too: `app/(homepage)/`.** It holds the homepage's `page.tsx` and its own `components/` and `utils/` folders, and is served at `/`. Without it, the homepage's components sit loose in `app/components/` beside the root layout, with no clean place for the next page's. `app/` keeps only the root `layout.tsx` and the files Next.js needs there, such as `globals.css`. A folder inside `app/` is only a route when it holds a `page.tsx` or `route.ts`, so `components/` and `utils/` folders inside `app/` are safe: they never become URLs.
153
+
147
154
  ```text
148
155
  project-root/
149
156
  ├── app/
150
157
  │ ├── (billing)/ # A section: groups pages, not part of the URL
151
- │ │ ├── components/ # Used by more than one billing page
158
+ │ │ ├── components/ # Used by three or more billing pages
152
159
  │ │ │ └── invoiceTable/
153
160
  │ │ ├── invoices/
154
161
  │ │ │ └── page.tsx # /invoices
155
162
  │ │ └── payments/
156
163
  │ │ └── page.tsx # /payments
157
- │ └── account-settings/
158
- │ ├── components/ # Used only by this page
159
- │ │ └── accountForm/
160
- │ │ ├── AccountForm.tsx
161
- │ │ ├── AccountForm.test.tsx
162
- │ │ ├── types.ts
163
- │ │ └── index.ts
164
- │ └── page.tsx # /account-settings
164
+ │ ├── (homepage)/ # The homepage, served at /
165
+ │ │ ├── components/ # Used only by the homepage
166
+ │ │ │ └── heroSection/
167
+ │ │ └── page.tsx # /
168
+ │ ├── account-settings/
169
+ │ │ ├── components/ # Used only by this page
170
+ │ │ │ └── accountForm/
171
+ │ │ │ ├── AccountForm.tsx
172
+ │ │ │ ├── AccountForm.test.tsx
173
+ │ │ │ ├── types.ts
174
+ │ │ │ └── index.ts
175
+ │ │ └── page.tsx # /account-settings
176
+ │ └── layout.tsx # The root layout
165
177
  └── components/
166
178
  ├── ui/ # Design System Components: Button, Card, Modal
167
179
  │ └── button/
168
- └── shared/ # Used by more than one page of this project
169
- └── siteHeader/
180
+ ├── layout/ # The site frame: navigation, header, footer
181
+ │ ├── siteHeader/
182
+ │ └── siteFooter/
183
+ └── shared/ # Used by three or more pages of this project
184
+ └── pricingTable/
170
185
  ```
171
186
 
172
187
  ### Rules
173
188
 
174
- - **Start where it is used, and move it when it is shared.** A new component goes in its page's `components/` folder. When a second page in the same section needs it, move it to the section's `components/` folder. When a page in another section needs it, move it to `components/shared/`.
189
+ - **Start where it is used, and share it on the third use.** Two uses are not enough to see which props really change from one use to the next. Three are.
190
+ 1. **First use:** a new component goes in its page's `components/` folder.
191
+ 2. **Second use:** copy it into the second page's `components/` folder. Only one copy, and each copy has a comment naming the other: `// Copy of app/invoices/components/invoiceSummary/. Merge on the third use.`
192
+ 3. **Third use:** merge the copies into one component. Design its props from all three uses, move it to the section's `components/` folder if all three pages are in one section, or to `components/shared/` if not, and delete the copies.
193
+ - **This is the only copying allowed.** A third copy is a mistake. It does not apply to [Design System Components](/docs/design-system-components), which are shared from the start, or to constants, which always live in `lib/constants/`.
175
194
  - **`components/ui/` is only for [Design System Components](/docs/design-system-components).** They take everything through props and import nothing from the project, so they can be copied into another project unchanged. See [Reusable by design](/docs/Structure/component-organization#reusable-by-design).
195
+ - **A props-only component that is not on the list yet stays in `components/ui/`.** A project cannot edit the standards, so it cannot add the component to the list itself. If a component takes everything through props and imports nothing from the project, keep it in `components/ui/` and record it in `docs/development/coding-standards.md`, under "Components for the standards", with its props. Tell the person, so it is added to the list in the next release.
196
+ - **`components/layout/` is the site frame**: the navigation, header, footer and anything else that frames the pages. It is this project's own code, so it may read `r` and `s`, and usually wraps Design System Components such as Navigation Bar and Footer. It does not have to be on every page, and it does not have to be rendered from a `layout.tsx` file. **Layout primitives, such as Duplex and Section Wrapper, are Design System Components**: they go in `components/ui/`, never `components/layout/`.
197
+ - **`components/shared/` is everything else used by three or more pages.** The difference from `components/layout/` is what it is, not how often it is used: a footer is layout even on one page, and a pricing table used on three pages is shared.
176
198
  - **A page or shared component wraps Design System Components.** It holds this project's logic and data, and passes props down.
177
199
  - **Never group by type** (`atoms/`, `molecules/`, `organisms/`). Group by where a component is used.
178
200
 
@@ -265,6 +287,7 @@ Add the export to `utils/index.ts` whenever you add a function.
265
287
  ### Rules
266
288
 
267
289
  - **Start local, promote when shared.** A function begins in the component's `utils/`. When another component in the same section needs it, move its folder to the section's `utils/`. When anything outside the section needs it, move it to the global `utils/`.
290
+ - **Sort, find, get, filter and format functions are utils from the start.** A function that only works on the data passed to it goes in a `utils/` folder the first time it is written, never inside the component, even with one user.
268
291
  - **One function per folder**, with the folder and file named after the function (`formatCurrency/formatCurrency.ts`), plus its test file and an `index.ts`.
269
292
  - **Every function has a test file** in the same folder. See [Readable Code](/docs/Standards/readable-code#every-function-and-component-has-a-test-file).
270
293
  - **Import from the `utils` folder**, never from the files inside it.
@@ -274,14 +297,14 @@ Add the export to `utils/index.ts` whenever you add a function.
274
297
 
275
298
  ## 🔤 Constants: `r`, `s`, noData and numbers {#constants}
276
299
 
277
- Every link, every piece of text on screen and every piece of stand-in data lives in `lib/constants/`, never written straight into a component:
300
+ Every link, every piece of text on screen, every named number and every piece of stand-in data lives in `lib/constants/`, never written straight into a component. **There is no component-level `constants.ts`**: even a value only one file uses goes here, so every piece of text is in one place when the site is translated into other languages, and every number is named the same way.
278
301
 
279
302
  ```text
280
303
  lib/constants/
281
304
  ├── routes.ts # r: every link
282
305
  ├── strings.ts # s: every piece of static text
283
- ├── noData.ts # Stand-in data for local development
284
- ├── durations.ts # Shared numbers, one file per topic
306
+ ├── numbers.ts # Every named number
307
+ ├── noData.ts # Stand-in data, once the data's shape is decided
285
308
  └── index.ts # Exports all of them
286
309
  ```
287
310
 
@@ -309,6 +332,7 @@ export const r = {
309
332
 
310
333
  - **A dynamic route starts from its `r` route.** Build the changing part where it is used: `` `${r.insights}/${insight.slug}` ``.
311
334
  - **Name each key after the place it goes**, in camelCase: `r.myStory`, `r.linkedIn`.
335
+ - **No `"#"` placeholder links.** A link with nowhere to go yet is shown as plain text, without a link, with a TODO above it: `{/* TODO: Link to the pricing page once it exists */}`. A `"#"` link is a bug a user can click.
312
336
 
313
337
  ### `s`: strings
314
338
 
@@ -327,10 +351,41 @@ export const s = {
327
351
  - **The keys of `s` are the site's translation keys.** When a site gets more languages, each key is translated into each language. Name each key after what the text says or does, and never use one key for two different jobs.
328
352
  - **Only real copy goes in `s`.** Dummy text belongs in `noData.ts`.
329
353
 
354
+ ### A list of items with links
355
+
356
+ Each item's words go in `s` and its link goes in `r`, under the same key, so the words can be translated and the link stays with the other links. The component reads each one by name:
357
+
358
+ ```ts title="lib/constants/strings.ts"
359
+ export const s = {
360
+ plans: {
361
+ starter: { title: "Starter", action: "Start free" },
362
+ team: { title: "Team", action: "Talk to us" },
363
+ },
364
+ };
365
+ ```
366
+
367
+ ```ts title="lib/constants/routes.ts"
368
+ export const r = {
369
+ plans: {
370
+ starter: "/signup?plan=starter",
371
+ team: "/contact",
372
+ },
373
+ };
374
+ ```
375
+
376
+ ```tsx title="app/(homepage)/components/pricingPlans/PricingPlans.tsx"
377
+ <Link href={r.plans.starter}>{s.plans.starter.action}</Link>
378
+ <Link href={r.plans.team}>{s.plans.team.action}</Link>
379
+ ```
380
+
381
+ **Write each key out by name**, `r.plans.starter`, never a key held in a variable such as `r.plans[planId]`. A reader can see exactly which words and which link each line uses.
382
+
330
383
  ### noData: stand-in data for local development
331
384
 
332
385
  **`noData.ts` stands in for outside data while you work locally**, when the CMS, database or API can't be reached, such as when you have no internet. Every page still renders with something that looks real.
333
386
 
387
+ **Create it once the project has decided how its data comes in**, the shape of the CMS, database or API response. Not before: the shape may still change. If the person asks for stand-in data before then, such as a list of fake users, put it in `noData.ts` with a comment above it: `// Not the real schema: a basic shape to finish the task.`
388
+
334
389
  ```ts title="lib/constants/noData.ts"
335
390
  const DUMMY_HEADING = "A heading for local development";
336
391
  const DUMMY_SLUG = "/insights";
@@ -357,24 +412,20 @@ const insights =
357
412
  - **Dummy values sit at the top of `noData.ts`** as their own constants, `DUMMY_HEADING` and the rest. They are never added to `s`.
358
413
  - **noData is for the whole site.** All of it lives in this one file.
359
414
 
360
- ### Numbers: named, and kept by topic
415
+ ### Numbers: named, in one file {#numbers-named-and-kept-by-topic}
361
416
 
362
417
  **A number other than `-1`, `0` or `1` gets a name**, such as `MAXIMUM_RETRY_ATTEMPTS`. Those three mean "nothing", "one more" and "not found", so they read clearly as they are. Any other number was chosen by someone, and its name says what it controls. ESLint checks this with `no-magic-numbers`.
363
418
 
364
- There is no `n` object. Text and links are one kind of thing each, but numbers are not: a retry limit, a cookie lifetime and a page size have nothing in common. Put each number where its meaning lives:
365
-
366
- | Used by | Where it goes | Example |
367
- | ------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------- |
368
- | One file | At the top of that file | `const MAXIMUM_NESTING_DEPTH = 3;` in `eslint.config.mjs` |
369
- | More than one file | `lib/constants/`, in a file named after its topic | `lib/constants/durations.ts`, `lib/constants/limits.ts`, `lib/constants/httpStatus.ts` |
419
+ **Every named number lives in `lib/constants/numbers.ts`**, even one that only one file uses, so every project finds its numbers in the same place. There is no `n` object: each number is its own `SCREAMING_SNAKE_CASE` export.
370
420
 
371
- ```ts title="lib/constants/durations.ts"
421
+ ```ts title="lib/constants/numbers.ts"
372
422
  export const COOKIE_DURATION_DAYS = 30;
423
+ export const MAXIMUM_RETRY_ATTEMPTS = 3;
373
424
  export const SESSION_TIMEOUT_MILLISECONDS = 900_000;
374
425
  ```
375
426
 
376
- - **Start in the file that uses it**, and move it to `lib/constants/` when a second file needs it.
377
- - **Never a `numbers.ts`** or any other file of unrelated values. Name the file after the topic.
427
+ - **One file, never split by topic.** `numbers.ts` can run past 300 lines, like `r` and `s`.
428
+ - **Config files and scripts outside the app**, such as `eslint.config.mjs`, keep their numbers at the top of the file: they are not part of the app and do not import from it.
378
429
  - **Put the unit in the name**: `_MILLISECONDS`, `_DAYS`, `_PIXELS`.
379
430
 
380
431
  ### Rules
@@ -384,6 +435,8 @@ export const SESSION_TIMEOUT_MILLISECONDS = 900_000;
384
435
  - **Files inside `lib/constants/` import each other directly**, `import { s } from "./strings";`, never through `index.ts`. See [Inside a folder, import files directly](/docs/Structure/import-organization#2-inside-a-folder-import-files-directly).
385
436
  - **`r` and `s` are the only single-letter names allowed anywhere.** See [Human-Readable Names](/docs/Standards/human-readable-names#r-and-s).
386
437
  - **Other constants**, such as numbers, are `SCREAMING_SNAKE_CASE`: see [Naming Conventions](/docs/Structure/naming-conventions#constants).
438
+ - **`routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` can run past 300 lines.** They are data only, so ESLint does not apply `max-lines` to them. Keep each one a single file: never split them to get under the limit.
439
+ - **`lib/constants/` never imports from `lib/types/`.** `lib/types/` reads some of its types from the constants (`typeof s`), so an import the other way makes a loop. When a constant needs a type, write the type beside the constant, or read it from the constant.
387
440
 
388
441
  ---
389
442
 
@@ -101,19 +101,19 @@ Enforced by ESLint `import-x/no-cycle`.
101
101
  **A folder's `index.ts` is for code outside the folder.** Code inside the folder imports its neighbours by file, never through the folder's own `index.ts`. Importing through your own index is the most common way a circular import is created by accident.
102
102
 
103
103
  ```ts
104
- // card/cardHeader/CardHeader.tsx
104
+ // card/components/cardHeader/CardHeader.tsx
105
105
 
106
106
  // ✅ Good — import the file directly
107
- import type { CardProps } from "../types";
107
+ import type { CardProps } from "../../types";
108
108
 
109
109
  // ❌ Bad — the card index imports CardHeader, so this is a circle
110
- import { Card } from "..";
110
+ import { Card } from "../..";
111
111
  ```
112
112
 
113
113
  | Importing from | Import through |
114
114
  | ---------------------- | ---------------------------------------------------------------------- |
115
115
  | **Outside** the folder | The folder's `index.ts`: `import { Card } from "@/components/ui/card"` |
116
- | **Inside** the folder | The file itself: `import type { CardProps } from "../types"` |
116
+ | **Inside** the folder | The file itself: `import type { CardProps } from "../../types"` |
117
117
 
118
118
  A parent component imports its sub-components. **A sub-component never imports its parent.** If a child needs something from the parent, the parent passes it as a prop.
119
119
 
@@ -13,7 +13,7 @@ We do not share component code between projects yet, so this page is what keeps
13
13
 
14
14
  - **Before building a component, look it up here.** If it is listed, build it with these variants and props — the same names, the same meaning. Do not invent your own.
15
15
  - **Do not rename, remove or repurpose a listed prop.** Projects differ in how a component looks, never in [how it works](/docs/Guides/component-library-workflow#same-component-different-paint).
16
- - **Building a component that is not listed?** Add it to this page in the same piece of work, so the next project builds it the same way.
16
+ - **Building a component that is not listed?** If it takes everything through props and imports nothing from the project, keep it in the project's `components/ui/` and record it, with its props, in the project's `docs/development/coding-standards.md`, under "Components for the standards". Tell the person: it is added to this page in the next release, so the next project builds it the same way. Working in the standards repo itself? Add it here in the same piece of work.
17
17
  - **A project needs something a listed component does not do?** Add the prop or variant here first, then build it. The reference changes before the code does.
18
18
  - **How to write each component** — its folder, files, the order inside the file, tests and stories — is in [Component Organization](/docs/Structure/component-organization). This page says _what_ each component takes; that page says _how_ every component is written.
19
19
 
@@ -21,17 +21,19 @@ This applies to everyone building components, **including AI agents**.
21
21
 
22
22
  ## Global / Navigation
23
23
 
24
- | # | Component | Variants | Key props |
25
- | --- | ------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
26
- | 1 | **NavigationBar** | default, large | logo (asset)<br />navigationItems (link[])<br />callToAction (Button)<br />sticky (boolean)<br />transparent (boolean) |
27
- | 2 | **Expanded Menu** | — | columns (linkGroup[])<br />featured (blok[])<br />trigger (text) |
28
- | 3 | **Hamburger Menu** | — | icon<br />menuItems (link[])<br />icon (asset)<br />position (left/right) |
29
- | 4 | **Search Bar** | inline, overlay | placeholder<br />scope (text)<br />showSuggestions (boolean) |
30
- | 5 | **Promo Bar** | — | text (richtext)<br />link<br />dismissible (boolean)<br />startDate<br />endDate |
31
- | 6 | **Breadcrumbs** | — | items (link[])<br />separator (text)<br />showHome (boolean) |
32
- | 7 | **Sidebar** | — | items (link[])<br />position (left/right)<br />collapsible (boolean)<br />width |
33
- | 8 | **Pagination** | numbered, load-more, infinite | totalPages (number)<br />current (number)<br />showPrevNext (boolean) |
34
- | 9 | **Footer** | slim, default, large | logo<br />columns (linkGroup[])<br />socialLinks (link[])<br />legalLinks (link[])<br />copyright (text) |
24
+ | # | Component | Variants | Key props |
25
+ | --- | ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
+ | 1 | **NavigationBar** | default, large | logo (asset)<br />navigationItems (link[])<br />callToAction (Button)<br />sticky (boolean)<br />transparent (boolean) |
27
+ | 2 | **Expanded Menu** | — | columns (linkGroup[])<br />featured (blok[])<br />trigger (text) |
28
+ | 3 | **Hamburger Menu** | — | icon<br />menuItems (link[])<br />icon (asset)<br />position (left/right) |
29
+ | 4 | **Search Bar** | inline, overlay | placeholder<br />scope (text)<br />showSuggestions (boolean) |
30
+ | 5 | **Promo Bar** | — | text (richtext)<br />link<br />dismissible (boolean)<br />startDate<br />endDate |
31
+ | 6 | **Breadcrumbs** | — | items (link[])<br />separator (text)<br />showHome (boolean) |
32
+ | 7 | **Sidebar** | — | items (link[])<br />position (left/right)<br />collapsible (boolean)<br />width |
33
+ | 8 | **Pagination** | numbered, load-more, infinite | totalPages (number)<br />current (number)<br />showPrevNext (boolean) |
34
+ | 9 | **Footer** | slim, default, large | logo<br />columns (linkGroup[])<br />socialLinks (link[])<br />legalLinks (link[])<br />copyright (text) |
35
+ | 62 | **Brand Logo** | — | className (Tailwind classes, usually a size such as `size-8`)<br />Each project inlines its own logo SVG, coloured from the palette and hidden from screen readers: the link around it names it |
36
+ | 65 | **Dropdown Menu** | — | Radix UI's Dropdown Menu props, unchanged (shadcn/ui)<br />parts: Dropdown Menu Trigger, Dropdown Menu Content, Dropdown Menu Item |
35
37
 
36
38
  ## Auth / Account
37
39
 
@@ -48,6 +50,7 @@ This applies to everyone building components, **including AI agents**.
48
50
  | --- | --------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
49
51
  | 14 | **Hero Banner** | Image, Video | heading<br />subheading<br />body (richtext)<br />media (asset/video)<br />buttons (Button[])<br />alignment<br />overlay (boolean) |
50
52
  | 15 | **Banner** | — | eyebrow<br />heading<br />subheading (richtext)<br />alignment |
53
+ | 64 | **Scroll Cue** | — | label (text) |
51
54
 
52
55
  ## Layout primitives
53
56
 
@@ -72,6 +75,7 @@ This applies to everyone building components, **including AI agents**.
72
75
  | 46 | **Review** | — | author<br />rating (number)<br />date<br />body<br />avatar<br />verified (boolean) |
73
76
  | 20 | **Card** | default, image, icon | image (asset)<br />title<br />body (richtext)<br />link<br />button (Button) |
74
77
  | 24 | **Accordion** | — | items array (title, content)<br />allowMultiple (boolean) |
78
+ | 63 | **Notification Card** | — | notifications array (title, message, timeLabel), front card first<br />className |
75
79
 
76
80
  ## Media
77
81
 
package/docs/ontology.md CHANGED
@@ -78,7 +78,7 @@ The words stay the same everywhere. Only the casing changes, to match where the
78
78
  | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
79
  | `component` | One piece of the user interface that does one job. Its file is PascalCase (`InvoiceTable.tsx`) inside a camelCase folder (`invoiceTable/`). See [Component Organization](/docs/Structure/component-organization) |
80
80
  | `design_system_component` | A standard component that every project builds the same way, with the same name, variants and props, such as Button or Card. Each one is listed on the [Design System Components](/docs/design-system-components) page and lives in `components/ui/`. It takes everything through props and imports nothing from the project, so it can be copied into another project unchanged |
81
- | `shared_component` | A component this project uses on more than one page, built from Design System Components. It lives in `components/shared/` |
81
+ | `shared_component` | A component this project uses on three or more pages, built from Design System Components. It lives in `components/shared/` |
82
82
  | `page_component` | A component used by one page, or by a few pages in one section. It lives in a `components/` folder beside that page, or in the section's route group. See [Where components live](/docs/Structure/folder-structure#-where-components-live) |
83
83
  | `props` | The values a component takes. `props` is a [dictionary word](/docs/Standards/human-readable-names#dictionary). Their type is named after the component and ends in `Props`: `ButtonProps` |
84
84
  | `type` | A TypeScript type or interface. Its name ends in `Props` or `Type` |
@@ -367,9 +367,9 @@ The full set of Decision Docs for a new project: every [reusable folder](/docs/S
367
367
  | `overview/` | [`/templates/docs/overview/what-is-it.md`](pathname:///templates/docs/overview/what-is-it.md) |
368
368
  | `architecture/` | [`/templates/docs/architecture/system.md`](pathname:///templates/docs/architecture/system.md) |
369
369
  | `scope/` | [`/templates/docs/scope/core.md`](pathname:///templates/docs/scope/core.md) |
370
- | …and 13 more | Each file is served at `/templates/docs/<folder>/<file>.md` |
370
+ | …and 14 more | Each file is served at `/templates/docs/<folder>/<file>.md` |
371
371
 
372
- After copying, rename `overview/what-is-it.md` after the project and update its title.
372
+ After copying, rename `overview/what-is-it.md` after the project, update its title, and update the link to it in `overview/writing-docs.md`. Then ask the person to review `product/ontology.md`.
373
373
 
374
374
  ### Decision Doc format {#doc-format}
375
375
 
@@ -23,9 +23,10 @@ sidebar_label: "Version History"
23
23
  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
24
  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
25
  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
- 7. **Update the version number** in `AGENTS.md` once every change is done.
26
+ 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
+ 8. **Update the version number** in `AGENTS.md` once every change is done.
27
28
 
28
- **A patch keeps the same version number.** When only the last or middle number changes, such as 3.0.0 → 3.0.1 or 3.0.9 → 3.1.0, the project's version in `AGENTS.md` stays the same, but there may still be work to do. Update the package, then read that version's **Fixes** list and do anything it asks for the project's version. Check it every time the package is updated, even when the version number has not changed.
29
+ **A patch keeps the same version number.** When only the last or middle number changes, such as 3.0.0 → 3.0.1 or 3.0.9 → 3.1.0, the project's version in `AGENTS.md` stays the same, but there may still be work to do. Update the package, then read that version's **Fixes** list and do anything it asks for the project's version. Check it every time the package is updated, even when the version number has not changed. A project already on the installed major version is never "nothing to do": follow [Already on this version](/docs/Guides/setup#already-on-this-version).
29
30
 
30
31
  **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.
31
32
 
@@ -50,15 +51,57 @@ Anyone changing the standards adds a version, alongside the change:
50
51
 
51
52
  ## Version 3
52
53
 
53
- **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.1.0
54
+ **Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.1.1
54
55
 
55
56
  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.
56
57
 
58
+ **Fixes in 3.1.1.** If the project already applied 3.1.0, check these:
59
+
60
+ - **`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:
61
+
62
+ ```js
63
+ {
64
+ // r, s, numbers and noData are lists, not logic, so they can be long.
65
+ files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
66
+ rules: { "max-lines": "off" },
67
+ },
68
+ ```
69
+
70
+ In a JavaScript project, the file pattern ends `.{js,mjs}` instead of `.ts`. If the project already split `r` or `s` into several files only to get under 300 lines, put each back into one file. Update the 300-line rule in `AGENTS.md` from the template.
71
+
72
+ - **Setup's agent questions are now their own step**, [step 4](/docs/Guides/setup#4-working-with-the-agent), and every setup and update asks them. Agents were skipping them after the standards list. If `docs/development/coding-standards.md` does not record all four answers (the GitHub repo, the Linear project, the status circles and asking before committing), ask the person the missing ones and record them.
73
+
74
+ - **The standards are the project's base, and changing one needs the person's yes.** An agent never skips, loosens or changes a standard on its own. It asks first, records the change in `docs/development/coding-standards.md`, under "Details" (number, name, what is different, why, and the date), then makes it. Copy the new rule into `AGENTS.md` from the template, under Code standards.
75
+ - **ESLint changes live in `eslint.overrides.mjs`.** `eslint.config.mjs` is now an unchanged copy of the template, so an update can copy it straight over. Copy `static/templates/eslint.overrides.mjs` to the project root. Move every rule the project added or changed in `eslint.config.mjs` into it, each with a comment naming the standard's number, and check each has an entry in `coding-standards.md`. Ask the person about any that do not. Then copy the project's template from `static/templates/eslint/` over `eslint.config.mjs`. See [Project-specific overrides](/docs/Standards/eslint#project-specific-overrides).
76
+ - **Components are shared on the third use, not the second.** On the second use, copy the component into the second page's `components/` folder, with a comment in each copy naming the other. On the third use, merge them into the section's `components/` folder or `components/shared/`, with props designed from all three uses. Nothing to move in the project: components already shared stay where they are. Update the components rule in `AGENTS.md` from the template. See [Where components live](/docs/Structure/folder-structure#rules).
77
+ - **Sort, find, get, filter and format functions go in `utils/` from the start**, even with one user. Move any such function written inside a component into that component's `utils/` folder.
78
+ - **The codeReview skill checks for these.** Copy `static/templates/skills/codeReview.md` into `.agents/skills/` and `.claude/commands/` again.
79
+
80
+ - **The homepage is a route group, `app/(homepage)/`.** It holds the homepage's `page.tsx` and its own `components/` and `utils/`, and is still served at `/`. Move `app/page.tsx` there, and move the homepage's components out of `app/components/` into `app/(homepage)/components/`. See [Where components live](/docs/Structure/folder-structure#-where-components-live).
81
+ - **The site frame lives in `components/layout/`**: navigation, header, footer and anything else that frames the pages. It may read `r` and `s`. Move those components there from `components/shared/` or `app/components/`. Layout primitives such as Duplex stay in `components/ui/`.
82
+ - **A props-only component that is not on the Design System Components list stays in `components/ui/`.** Record it, with its props, in `docs/development/coding-standards.md`, under a new "Components for the standards" heading (copy it from the template), and tell the person. Move back into `components/ui/` any such component that was moved out only because it was not listed.
83
+ - **Four components joined the list:** Brand Logo, Notification Card, Scroll Cue and Dropdown Menu. If the project has them, check their props match the [list](/docs/design-system-components).
84
+ - **Every named number lives in `lib/constants/numbers.ts`**, even one only one file uses, in one file that is never split. Move numbers from the tops of app files and from any topic files (`durations.ts`, `limits.ts`) into it. Config files and scripts outside the app keep theirs at the top.
85
+ - **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`.
86
+ - **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).
87
+ - **No `"#"` placeholder links.** Show the text without a link and put `{/* TODO: … */}` above it until the page exists. Unfinished work is marked `// TODO: Message`.
88
+ - **`lib/constants/` never imports from `lib/types/`.** Move any type it imports from there beside the constant.
89
+ - **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.`
90
+ - **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.
91
+ - **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.
92
+ - **AGENTS.md: the Code standards section sits between `<!-- code-standards:start -->` and `<!-- code-standards:end -->`**, and an update replaces everything between them. Copy the section from the template, markers included. Move any project exception written into it into `docs/development/coding-standards.md`, and anything else the project added, such as a framework's block, outside the markers.
93
+ - **Docs:** copy the new `docs/product/ontology.md` template if the project has none, and ask the person to review it. Fix the link in `overview/writing-docs.md` if `what-is-it.md` was renamed. Retitle `how-it-works.md` "Overview — How It Works". Delete any version 2 leftovers: `_category_.json`, the `sidebar_position`, `sidebar_label`, `slug`, `status` and `lastReviewed` front matter, and `docs/index.md`.
94
+ - **Decision Docs are confirmed with the person** before an agent creates, changes or deletes one, unless `AGENTS.md` names an agent that manages them. A folder that cannot apply may be deleted with the person's yes, recorded in `coding-standards.md`. Moving or reformatting a doc does not change its Updated date.
95
+ - **Stylelint configs name their export:** `const config = { … }; export default config;`. Change the project's `stylelint.config.mjs` to match.
96
+ - **The Linear ticket prefix is the team's, not the project's.** In `AGENTS.md`, Project workflow, write the Linear workspace, team and project, such as `activatus-life`, team `ACT`, project Launchpad.
97
+
98
+ **How to check:** `pnpm lint` passes with `routes.ts`, `strings.ts`, `numbers.ts` or `noData.ts` over 300 lines; `app/page.tsx` has moved to `app/(homepage)/page.tsx`; `lib/constants/` has `numbers.ts` and no component has its own `constants.ts`; `AGENTS.md` has the code-standards markers; the navigation, header and footer are in `components/layout/`; `eslint.config.mjs` matches the template exactly, with `eslint.overrides.mjs` beside it; every rule in `eslint.overrides.mjs` has an entry in `coding-standards.md`; `lib/constants/` has no `strings/` or `routes/` folder made only to stay under the limit; `docs/development/coding-standards.md` records all four agent answers.
99
+
57
100
  **Fixes in 3.1.0.** If the project already applied 3.0.9, check these:
58
101
 
59
102
  - **Install and update with `@latest`.** Use `pnpm add -D @activatus/code-standards@latest`, never a typed version number. `package.json` keeps whatever version pnpm writes. Nothing to change in the project.
60
103
  - **`minimumReleaseAgeExclude` is the plain package name.** In `pnpm-workspace.yaml`, the entry is `"@activatus/code-standards"`, with no version. If it has 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 on every update.
61
- - **Setup asks whether AI should ask before every commit and push.** It is optional, a yes or no, recorded under **Who commits** in Project workflow. Ask the person the [question](/docs/Guides/setup#working-with-the-agent). A yes is written under Who commits; a no writes nothing, and the agent uses its own judgement. Write their answer in `docs/development/coding-standards.md`, under "Details".
104
+ - **Setup asks whether AI should ask before every commit and push.** It is optional, a yes or no, recorded under **Who commits** in Project workflow. Ask the person the [question](/docs/Guides/setup#4-working-with-the-agent). A yes is written under Who commits; a no writes nothing, and the agent uses its own judgement. Write their answer in `docs/development/coding-standards.md`, under "Details".
62
105
 
63
106
  **How to check:** `minimumReleaseAgeExclude` lists `"@activatus/code-standards"` with no version, running `pnpm add -D @activatus/code-standards@latest` again leaves `pnpm-workspace.yaml` unchanged, and if the person said yes, Who commits in `AGENTS.md` has the asking rule.
64
107
 
@@ -93,7 +136,7 @@ Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 firs
93
136
  **Fixes in 3.0.7.** New, optional: [Working with Agents](/docs/Standards/working-with-agents). Setup now asks for the project's GitHub repo and Linear project, and offers status circles. (3.0.7 also offered asking before every commit and push. 3.0.8 removed it.) If the project already applied 3.0.5:
94
137
 
95
138
  - Offer the **GitHub repo** and the **Linear project**, both optional, and add each one the person confirms to the Project workflow section of `AGENTS.md`, from the [template](/docs/templates#agents). Read the repo from `git remote get-url origin` and confirm it with the person. Read the Linear project from the project's own docs if they name it, and confirm it; otherwise ask. Never copy it from another project.
96
- - Print the [status circles](/docs/Guides/setup#working-with-the-agent) question to the person. If they say yes, copy the Status circles section from the template into Project workflow. Write their answer in `docs/development/coding-standards.md`, under "Details". If `AGENTS.md` already has status circles in the project's own words, keep that.
139
+ - Print the [status circles](/docs/Guides/setup#4-working-with-the-agent) question to the person. If they say yes, copy the Status circles section from the template into Project workflow. Write their answer in `docs/development/coding-standards.md`, under "Details". If `AGENTS.md` already has status circles in the project's own words, keep that.
97
140
 
98
141
  **How to check:** Project workflow in `AGENTS.md` names each link the person confirmed, and `docs/development/coding-standards.md` records the answer for each option.
99
142
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@activatus/code-standards",
3
- "version": "3.1.0",
3
+ "version": "3.1.1",
4
4
  "description": "The Activatus code standards: the rules as Markdown, and the config files to copy. Install it so an AI agent can read the standards from node_modules.",
5
5
  "repository": {
6
6
  "type": "git",