@activatus/code-standards 3.0.9 → 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 (33) hide show
  1. package/README.md +2 -2
  2. package/docs/Guides/migrating.md +14 -0
  3. package/docs/Guides/setup.md +70 -26
  4. package/docs/Standards/agent-specs.md +1 -1
  5. package/docs/Standards/documentation.md +17 -7
  6. package/docs/Standards/eslint.md +54 -14
  7. package/docs/Standards/lint-errors.md +4 -4
  8. package/docs/Standards/readable-code.md +4 -1
  9. package/docs/Standards/stylelint.md +9 -3
  10. package/docs/Standards/styling.md +5 -1
  11. package/docs/Standards/working-with-agents.md +8 -6
  12. package/docs/Structure/component-organization.md +30 -26
  13. package/docs/Structure/folder-structure.md +85 -32
  14. package/docs/Structure/import-organization.md +4 -4
  15. package/docs/design-system-components.md +16 -12
  16. package/docs/intro.md +1 -1
  17. package/docs/ontology.md +1 -1
  18. package/docs/templates.mdx +2 -2
  19. package/docs/version-history.md +58 -6
  20. package/package.json +1 -1
  21. package/static/templates/AGENTS.md +19 -10
  22. package/static/templates/docs/design/design-system.md +6 -0
  23. package/static/templates/docs/development/coding-standards.md +6 -2
  24. package/static/templates/docs/overview/how-it-works.md +1 -1
  25. package/static/templates/docs/product/ontology.md +32 -0
  26. package/static/templates/eslint/base/eslint.config.mjs +9 -0
  27. package/static/templates/eslint/nextjs/eslint.config.mjs +9 -0
  28. package/static/templates/eslint/react/eslint.config.mjs +9 -0
  29. package/static/templates/eslint/typescript/eslint.config.mjs +9 -0
  30. package/static/templates/eslint.overrides.mjs +18 -0
  31. package/static/templates/skills/codeReview.md +2 -1
  32. package/static/templates/stylelint/css/stylelint.config.mjs +3 -1
  33. package/static/templates/stylelint/scss/stylelint.config.mjs +3 -1
@@ -5,7 +5,7 @@ sidebar_label: "Working with Agents"
5
5
 
6
6
  # Working with Agents
7
7
 
8
- > How an AI agent links a project's work and reports on it. The GitHub repo, the Linear project and the status circles are all optional. [Setup](/docs/Guides/setup#working-with-the-agent) offers all three every time, so they take a moment to fill in, and a project can leave out any of them. They work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
8
+ > How an AI agent links a project's work, reports on it and asks before committing. The GitHub repo, the Linear project, the status circles and asking before every commit and push are all optional. [Setup](/docs/Guides/setup#4-working-with-the-agent) offers all four every time, so they take a moment to fill in, and a project can leave out any of them. They work the same with Claude Code, ChatGPT, Codex or any agent that reads `AGENTS.md`.
9
9
 
10
10
  Whatever the project chooses is written into the **Project workflow** section of its `AGENTS.md`, from the [template](/docs/templates#agents), so every agent in the project follows it.
11
11
 
@@ -13,10 +13,10 @@ Whatever the project chooses is written into the **Project workflow** section of
13
13
 
14
14
  Optional. A project records either link, both or neither, in **Project workflow**, and deletes the line for any link it does not use. An agent uses them to link tickets and Pull Requests, and to know where work belongs.
15
15
 
16
- | Link | Where it comes from |
17
- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
18
- | GitHub repo | Read it from `git remote get-url origin` and confirm it with the person. If there is no remote, ask |
19
- | Linear project | If the project's own docs already name it, read it from there and confirm it with the person. Otherwise ask. Write the workspace, the project and the ticket prefix, such as `activatus-life`, Launchpad, `ACT`, or "None" |
16
+ | Link | Where it comes from |
17
+ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
18
+ | GitHub repo | Read it from `git remote get-url origin` and confirm it with the person. If there is no remote, ask |
19
+ | Linear project | If the project's own docs already name it, read it from there and confirm it with the person. Otherwise ask. Write the workspace, the team and the project, such as `activatus-life`, team `ACT`, project Launchpad, or "None". The ticket prefix, such as `ACT`, is the team's: every project in that team shares it |
20
20
 
21
21
  **Never copy a Linear workspace or ticket prefix from another project.** Projects under the same organisation often live in different Linear workspaces or projects, and a guessed prefix files tickets in the wrong place. If `AGENTS.md` does not name the Linear project, ask before creating, linking or citing any ticket.
22
22
 
@@ -42,4 +42,6 @@ Optional. An agent reports the state of every ticket or piece of work as one lin
42
42
  - **No ticket is fine.** Work without one is just the circle and a short title.
43
43
  - **Only what the person needs.** Leave out anything they already know.
44
44
 
45
- Whether and when agents commit is not part of this. It is the project's own workflow, under **Who commits** in Project workflow.
45
+ ## Ask before committing
46
+
47
+ Optional. Setup asks: "Would you like AI to ask you before every commit and push to git?" A yes is written under **Who commits** in Project workflow: ask the person before every commit and push, and wait for a clear yes to that specific action. A yes covers one action only. A no means nothing is written, and the agent uses its own judgement.
@@ -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/intro.md CHANGED
@@ -22,7 +22,7 @@ This site documents the shared code standards used across all Activatus projects
22
22
  | EditorConfig | [`.editorconfig`](/docs/Standards/editorconfig) | Editor-level whitespace rules |
23
23
  | direnv + nvm | [`.envrc` / `.nvmrc`](/docs/Standards/direnv) | Automatic Node version switching on `cd` |
24
24
  | AGENTS.md | [`AGENTS.md`](/docs/Standards/agent-specs) | AI agent context and agent skills |
25
- | Working with Agents | [Optional](/docs/Standards/working-with-agents) | GitHub repo, Linear project and status circles: all optional, offered during setup |
25
+ | Working with Agents | [Optional](/docs/Standards/working-with-agents) | GitHub repo, Linear project, status circles and asking before commits: all optional |
26
26
  | CSS Styling | [Styling guide](/docs/Standards/styling) | Tailwind CSS, flexbox-first layout and global colour variables |
27
27
  | Tech Stack | [Tech stack](/docs/Standards/tech-stack) | The frameworks, libraries and versions we build on |
28
28
 
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