@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.
- package/README.md +2 -2
- package/docs/Guides/migrating.md +14 -0
- package/docs/Guides/setup.md +70 -26
- package/docs/Standards/agent-specs.md +1 -1
- package/docs/Standards/documentation.md +17 -7
- package/docs/Standards/eslint.md +54 -14
- package/docs/Standards/lint-errors.md +4 -4
- package/docs/Standards/readable-code.md +4 -1
- package/docs/Standards/stylelint.md +9 -3
- package/docs/Standards/styling.md +5 -1
- package/docs/Standards/working-with-agents.md +8 -6
- package/docs/Structure/component-organization.md +30 -26
- package/docs/Structure/folder-structure.md +85 -32
- package/docs/Structure/import-organization.md +4 -4
- package/docs/design-system-components.md +16 -12
- package/docs/intro.md +1 -1
- package/docs/ontology.md +1 -1
- package/docs/templates.mdx +2 -2
- package/docs/version-history.md +58 -6
- package/package.json +1 -1
- package/static/templates/AGENTS.md +19 -10
- package/static/templates/docs/design/design-system.md +6 -0
- package/static/templates/docs/development/coding-standards.md +6 -2
- package/static/templates/docs/overview/how-it-works.md +1 -1
- package/static/templates/docs/product/ontology.md +32 -0
- package/static/templates/eslint/base/eslint.config.mjs +9 -0
- package/static/templates/eslint/nextjs/eslint.config.mjs +9 -0
- package/static/templates/eslint/react/eslint.config.mjs +9 -0
- package/static/templates/eslint/typescript/eslint.config.mjs +9 -0
- package/static/templates/eslint.overrides.mjs +18 -0
- package/static/templates/skills/codeReview.md +2 -1
- package/static/templates/stylelint/css/stylelint.config.mjs +3 -1
- 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
|
|
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
|
|
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
|
-
|
|
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
|
-
├──
|
|
427
|
-
│ ├──
|
|
428
|
-
│ ├── CardHeader.
|
|
429
|
-
│ ├──
|
|
430
|
-
│
|
|
431
|
-
|
|
432
|
-
│ ├──
|
|
433
|
-
│ ├── CardBody.
|
|
434
|
-
│ ├──
|
|
435
|
-
│
|
|
436
|
-
|
|
437
|
-
│
|
|
438
|
-
│
|
|
439
|
-
│
|
|
440
|
-
│
|
|
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
|
|
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/
|
|
471
|
-
|
|
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** →
|
|
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
|
-
│ ├──
|
|
42
|
-
│
|
|
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
|
-
│
|
|
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
|
|
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
|
-
| **
|
|
142
|
-
| **
|
|
143
|
-
| **
|
|
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
|
|
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
|
-
│
|
|
158
|
-
│
|
|
159
|
-
│
|
|
160
|
-
│
|
|
161
|
-
│
|
|
162
|
-
│
|
|
163
|
-
│
|
|
164
|
-
│
|
|
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
|
-
|
|
169
|
-
|
|
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
|
|
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
|
-
├──
|
|
284
|
-
├──
|
|
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
|
|
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
|
-
|
|
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/
|
|
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
|
-
- **
|
|
377
|
-
- **
|
|
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 "
|
|
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 "
|
|
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?**
|
|
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
|
|
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
|
|
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` |
|
package/docs/templates.mdx
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|