@activatus/code-standards 3.1.0 → 3.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/Guides/migrating.md +93 -50
- package/docs/Guides/regression-checks.md +72 -0
- package/docs/Guides/setup.md +89 -21
- package/docs/Standards/documentation.md +54 -7
- package/docs/Standards/eslint.md +60 -18
- 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 +5 -5
- 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/ontology.md +1 -1
- package/docs/templates.mdx +12 -4
- package/docs/version-history.md +61 -6
- package/package.json +6 -2
- package/scripts/verifyStandards/checkAgentFiles.mjs +148 -0
- package/scripts/verifyStandards/checkComponents.mjs +129 -0
- package/scripts/verifyStandards/checkConfigFiles.mjs +230 -0
- package/scripts/verifyStandards/checkDocs.mjs +86 -0
- package/scripts/verifyStandards/checkRequiredFiles.mjs +96 -0
- package/scripts/verifyStandards/formatReport.mjs +76 -0
- package/scripts/verifyStandards/projectFiles.mjs +109 -0
- package/scripts/verifyStandards/runChecks.mjs +62 -0
- package/scripts/verifyStandards/verifyStandards.mjs +22 -0
- 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 +10 -2
- package/static/templates/docs/overview/how-it-works.md +1 -1
- package/static/templates/docs/overview/writing-docs.md +4 -0
- 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 +11 -1
- package/static/templates/eslint/react/eslint.config.mjs +11 -1
- 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
- package/static/templates/tests/visual/pageLayout.visual.ts +188 -0
- package/static/templates/tests/visual/playwright.config.mjs +65 -0
- package/static/templates/tests/visual/visualPages.mjs +3 -0
package/docs/Standards/eslint.md
CHANGED
|
@@ -30,7 +30,7 @@ pnpm add -D eslint@latest @eslint/js@latest
|
|
|
30
30
|
|
|
31
31
|
:::note[eslint-plugin-react on ESLint 10]
|
|
32
32
|
|
|
33
|
-
`eslint-plugin-react` 7.37 officially supports ESLint only up to 9.7, and on ESLint 10 it crashes when it tries to detect the React version by itself. The React and Next.js configs below avoid this by setting the version: `settings: { react: { version: "19.0" } }`. **Keep that setting
|
|
33
|
+
`eslint-plugin-react` 7.37 officially supports ESLint only up to 9.7, and on ESLint 10 it crashes when it tries to detect the React version by itself. The React and Next.js configs below avoid this by setting the version: `settings: { react: { version: "19.0" } }`. **Keep that setting.** A project on a React version other than 19 sets the number in `eslint.overrides.mjs`, `{ settings: { react: { version: "19.2" } } }`, never in `eslint.config.mjs`. pnpm warns about the unmet peer dependency on install; that warning is expected.
|
|
34
34
|
|
|
35
35
|
:::
|
|
36
36
|
|
|
@@ -80,6 +80,8 @@ import { flatConfigs as importX } from "eslint-plugin-import-x";
|
|
|
80
80
|
import unicorn from "eslint-plugin-unicorn";
|
|
81
81
|
import globals from "globals";
|
|
82
82
|
|
|
83
|
+
import { projectOverrides } from "./eslint.overrides.mjs";
|
|
84
|
+
|
|
83
85
|
// Code patterns that are errors in every file.
|
|
84
86
|
const RESTRICTED_SYNTAX = [
|
|
85
87
|
{
|
|
@@ -193,10 +195,17 @@ const config = [
|
|
|
193
195
|
files: ["**/*.test.{js,mjs}"],
|
|
194
196
|
rules: { "max-lines": "off", "no-magic-numbers": "off" },
|
|
195
197
|
},
|
|
198
|
+
{
|
|
199
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
200
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.{js,mjs}"],
|
|
201
|
+
rules: { "max-lines": "off" },
|
|
202
|
+
},
|
|
196
203
|
{
|
|
197
204
|
files: ["**/*.config.{js,mjs}"],
|
|
198
205
|
rules: { "import-x/no-default-export": "off" },
|
|
199
206
|
},
|
|
207
|
+
// This project's own changes: see eslint.overrides.mjs.
|
|
208
|
+
...projectOverrides,
|
|
200
209
|
prettier,
|
|
201
210
|
];
|
|
202
211
|
|
|
@@ -215,6 +224,8 @@ import unicorn from "eslint-plugin-unicorn";
|
|
|
215
224
|
import globals from "globals";
|
|
216
225
|
import { configs as typescript } from "typescript-eslint";
|
|
217
226
|
|
|
227
|
+
import { projectOverrides } from "./eslint.overrides.mjs";
|
|
228
|
+
|
|
218
229
|
// Code patterns that are errors in every file.
|
|
219
230
|
const RESTRICTED_SYNTAX = [
|
|
220
231
|
{
|
|
@@ -380,6 +391,11 @@ const config = [
|
|
|
380
391
|
"@typescript-eslint/no-magic-numbers": "off",
|
|
381
392
|
},
|
|
382
393
|
},
|
|
394
|
+
{
|
|
395
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
396
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
397
|
+
rules: { "max-lines": "off" },
|
|
398
|
+
},
|
|
383
399
|
{
|
|
384
400
|
files: ["**/*.config.{js,mjs,ts}", "**/*.stories.tsx"],
|
|
385
401
|
rules: { "import-x/no-default-export": "off" },
|
|
@@ -399,6 +415,8 @@ const config = [
|
|
|
399
415
|
],
|
|
400
416
|
},
|
|
401
417
|
},
|
|
418
|
+
// This project's own changes: see eslint.overrides.mjs.
|
|
419
|
+
...projectOverrides,
|
|
402
420
|
prettier,
|
|
403
421
|
];
|
|
404
422
|
|
|
@@ -423,6 +441,8 @@ import unicorn from "eslint-plugin-unicorn";
|
|
|
423
441
|
import globals from "globals";
|
|
424
442
|
import { configs as typescript } from "typescript-eslint";
|
|
425
443
|
|
|
444
|
+
import { projectOverrides } from "./eslint.overrides.mjs";
|
|
445
|
+
|
|
426
446
|
// Code patterns that are errors in every file.
|
|
427
447
|
const RESTRICTED_SYNTAX = [
|
|
428
448
|
{
|
|
@@ -495,7 +515,8 @@ const config = [
|
|
|
495
515
|
},
|
|
496
516
|
settings: {
|
|
497
517
|
// Keep this. eslint-plugin-react crashes on ESLint 10 if it has to detect the version itself.
|
|
498
|
-
//
|
|
518
|
+
// A project on another React version sets settings.react.version
|
|
519
|
+
// in eslint.overrides.mjs, never here.
|
|
499
520
|
react: { version: "19.0" },
|
|
500
521
|
"import-x/resolver-next": [createTypeScriptImportResolver()],
|
|
501
522
|
},
|
|
@@ -605,6 +626,11 @@ const config = [
|
|
|
605
626
|
"@typescript-eslint/no-magic-numbers": "off",
|
|
606
627
|
},
|
|
607
628
|
},
|
|
629
|
+
{
|
|
630
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
631
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
632
|
+
rules: { "max-lines": "off" },
|
|
633
|
+
},
|
|
608
634
|
{
|
|
609
635
|
files: ["**/*.config.{js,mjs,ts}", "**/*.stories.tsx"],
|
|
610
636
|
rules: { "import-x/no-default-export": "off" },
|
|
@@ -624,6 +650,8 @@ const config = [
|
|
|
624
650
|
],
|
|
625
651
|
},
|
|
626
652
|
},
|
|
653
|
+
// This project's own changes: see eslint.overrides.mjs.
|
|
654
|
+
...projectOverrides,
|
|
627
655
|
prettier,
|
|
628
656
|
];
|
|
629
657
|
|
|
@@ -632,7 +660,7 @@ export default config;
|
|
|
632
660
|
|
|
633
661
|
:::caution[Pin the React version]
|
|
634
662
|
|
|
635
|
-
|
|
663
|
+
Keep `settings.react.version` set rather than `"detect"`; change the number in `eslint.overrides.mjs`. On ESLint 10, `eslint-plugin-react` 7 crashes while detecting the version (`contextOrFilename.getFilename is not a function`).
|
|
636
664
|
|
|
637
665
|
:::
|
|
638
666
|
|
|
@@ -650,6 +678,8 @@ import { flatConfigs as importX } from "eslint-plugin-import-x";
|
|
|
650
678
|
import unicorn from "eslint-plugin-unicorn";
|
|
651
679
|
import globals from "globals";
|
|
652
680
|
|
|
681
|
+
import { projectOverrides } from "./eslint.overrides.mjs";
|
|
682
|
+
|
|
653
683
|
// Code patterns that are errors in every file.
|
|
654
684
|
const RESTRICTED_SYNTAX = [
|
|
655
685
|
{
|
|
@@ -722,7 +752,8 @@ const config = [
|
|
|
722
752
|
},
|
|
723
753
|
settings: {
|
|
724
754
|
// Keep this. eslint-plugin-react crashes on ESLint 10 if it has to detect the version itself.
|
|
725
|
-
//
|
|
755
|
+
// A project on another React version sets settings.react.version
|
|
756
|
+
// in eslint.overrides.mjs, never here.
|
|
726
757
|
react: { version: "19.0" },
|
|
727
758
|
"import-x/resolver-next": [createTypeScriptImportResolver()],
|
|
728
759
|
},
|
|
@@ -832,6 +863,11 @@ const config = [
|
|
|
832
863
|
"@typescript-eslint/no-magic-numbers": "off",
|
|
833
864
|
},
|
|
834
865
|
},
|
|
866
|
+
{
|
|
867
|
+
// r, s, numbers and noData are lists, not logic, so they can be long.
|
|
868
|
+
files: ["lib/constants/{routes,strings,numbers,noData}.ts"],
|
|
869
|
+
rules: { "max-lines": "off" },
|
|
870
|
+
},
|
|
835
871
|
{
|
|
836
872
|
files: [
|
|
837
873
|
"**/*.config.{js,mjs,ts}",
|
|
@@ -866,6 +902,8 @@ const config = [
|
|
|
866
902
|
],
|
|
867
903
|
},
|
|
868
904
|
},
|
|
905
|
+
// This project's own changes: see eslint.overrides.mjs.
|
|
906
|
+
...projectOverrides,
|
|
869
907
|
prettier,
|
|
870
908
|
];
|
|
871
909
|
|
|
@@ -882,23 +920,27 @@ Use the `globals` package rather than turning `no-undef` off or hand-writing a g
|
|
|
882
920
|
|
|
883
921
|
### Project-specific overrides
|
|
884
922
|
|
|
885
|
-
|
|
923
|
+
**Never change `eslint.config.mjs`.** It is copied from the standards unchanged, so an update can copy the new version straight over it. A project's own rule changes live in `eslint.overrides.mjs`, which the config reads just before `prettier`. Copy it from `static/templates/eslint.overrides.mjs`: it starts empty.
|
|
886
924
|
|
|
887
|
-
|
|
888
|
-
const config = [
|
|
889
|
-
// ...
|
|
890
|
-
{
|
|
891
|
-
rules: {
|
|
892
|
-
// project-specific overrides
|
|
893
|
-
"no-console": "off",
|
|
894
|
-
},
|
|
895
|
-
},
|
|
896
|
-
prettier,
|
|
897
|
-
];
|
|
925
|
+
**A change needs the person's yes first.** The standards are the project's base, so an agent never switches off, loosens or changes a rule on its own. Ask, then:
|
|
898
926
|
|
|
899
|
-
|
|
927
|
+
1. Record it in `docs/development/coding-standards.md`, under "Details": the standard's number and name, what is different, why, and the date.
|
|
928
|
+
2. Add it to `eslint.overrides.mjs`, with a comment naming the standard's number.
|
|
929
|
+
|
|
930
|
+
```js title="eslint.overrides.mjs"
|
|
931
|
+
export const projectOverrides = [
|
|
932
|
+
{
|
|
933
|
+
files: ["scripts/**/*.mjs"],
|
|
934
|
+
rules: {
|
|
935
|
+
// Standard 6: scripts print to the terminal.
|
|
936
|
+
"no-console": "off",
|
|
937
|
+
},
|
|
938
|
+
},
|
|
939
|
+
];
|
|
900
940
|
```
|
|
901
941
|
|
|
942
|
+
A rule change in `eslint.overrides.mjs` with no matching entry in `coding-standards.md` is a mistake: the codeReview skill flags it. The only changes made without asking are the single-line `let` and type-cast exceptions: see [the only allowed exceptions](/docs/Standards/lint-errors#the-only-allowed-exceptions).
|
|
943
|
+
|
|
902
944
|
Keep `prettier` last — it switches off every rule that would fight the formatter.
|
|
903
945
|
|
|
904
946
|
Add scripts to `package.json`:
|
|
@@ -981,7 +1023,7 @@ Every `eslint-disable` comment must say why, after `--`. A rule is never switche
|
|
|
981
1023
|
|
|
982
1024
|
### `max-lines: 300`
|
|
983
1025
|
|
|
984
|
-
No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt. See [Readable Code](/docs/Standards/readable-code#no-file-longer-than-300-lines).
|
|
1026
|
+
No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt, and so are `lib/constants/routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts`, which hold data only. See [Readable Code](/docs/Standards/readable-code#no-file-longer-than-300-lines).
|
|
985
1027
|
|
|
986
1028
|
### `max-depth: 3`
|
|
987
1029
|
|
|
@@ -63,10 +63,10 @@ This applies to everyone, **including AI agents**. An agent's work is not finish
|
|
|
63
63
|
|
|
64
64
|
## Files
|
|
65
65
|
|
|
66
|
-
| Rule | What you will see | What it means | How to fix it
|
|
67
|
-
| ----------------------- | ------------------------------------------------------- | ---------------------------------- |
|
|
68
|
-
| `max-lines` | `File has too many lines (312). Maximum allowed is 300` | The file is over 300 lines | Split it: move functions to `utils/`, sub-components to their own folders, types to `types.ts` |
|
|
69
|
-
| `unicorn/filename-case` | `Filename is not in camel case or pascal case` | The file name is in the wrong case | Rename it: camelCase for code files, PascalCase for component files
|
|
66
|
+
| Rule | What you will see | What it means | How to fix it |
|
|
67
|
+
| ----------------------- | ------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
68
|
+
| `max-lines` | `File has too many lines (312). Maximum allowed is 300` | The file is over 300 lines | Split it: move functions to `utils/`, sub-components to their own folders, types to `types.ts`. `routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` in `lib/constants/` never get this error |
|
|
69
|
+
| `unicorn/filename-case` | `Filename is not in camel case or pascal case` | The file name is in the wrong case | Rename it: camelCase for code files, PascalCase for component files |
|
|
70
70
|
|
|
71
71
|
## Types
|
|
72
72
|
|
|
@@ -43,6 +43,8 @@ A file over 300 lines is doing more than one job. Split it before it gets there:
|
|
|
43
43
|
|
|
44
44
|
Blank lines and comments do not count towards the limit. **Test files are exempt** — a thorough test file can run long.
|
|
45
45
|
|
|
46
|
+
**`routes.ts`, `strings.ts`, `numbers.ts` and `noData.ts` in `lib/constants/` are exempt too.** They are lists of data, not logic, and a big app has a lot of links and text. Splitting them would mean more places to look for one label. They stay data only: no functions in them. See [Constants](/docs/Structure/folder-structure#constants).
|
|
47
|
+
|
|
46
48
|
---
|
|
47
49
|
|
|
48
50
|
## Names are full English words
|
|
@@ -311,7 +313,7 @@ if (order.status === "shipped") {
|
|
|
311
313
|
|
|
312
314
|
**`-1`, `0` and `1` are allowed**, because they are part of how code works rather than a choice anyone makes: `0` is the start or nothing (`items[0]`, `length === 0`), `1` is one more or one less (`index + 1`), and `-1` is "not found" (`indexOf`). Any other number was chosen by someone, so its name says what it controls. Even `2` gets a name.
|
|
313
315
|
|
|
314
|
-
|
|
316
|
+
Every named number lives in `lib/constants/numbers.ts`, even one only one file uses. See [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic) for where they go, and [Naming Conventions](/docs/Structure/naming-conventions#constants) for how to name them.
|
|
315
317
|
|
|
316
318
|
---
|
|
317
319
|
|
|
@@ -422,6 +424,7 @@ await waitMilliseconds(1000);
|
|
|
422
424
|
|
|
423
425
|
- If a comment describes **what** the code does, rename things until the comment is not needed.
|
|
424
426
|
- **Never leave commented-out code.** Delete it — Git remembers.
|
|
427
|
+
- **Mark unfinished work with `// TODO: Message`**, or `{/* TODO: Message */}` in JSX. Editors with the TODO Highlight extension (Wayou Liu) list them automatically. A project can also list them under "Unfinished changes" in `docs/development/coding-standards.md`.
|
|
425
428
|
|
|
426
429
|
---
|
|
427
430
|
|
|
@@ -32,7 +32,7 @@ Create `stylelint.config.mjs` in your project root:
|
|
|
32
32
|
|
|
33
33
|
```js title="stylelint.config.mjs"
|
|
34
34
|
/** @type {import("stylelint").Config} */
|
|
35
|
-
|
|
35
|
+
const config = {
|
|
36
36
|
ignoreFiles: ["**/vendor/**"],
|
|
37
37
|
extends: [
|
|
38
38
|
"stylelint-config-standard",
|
|
@@ -71,13 +71,15 @@ export default {
|
|
|
71
71
|
},
|
|
72
72
|
],
|
|
73
73
|
};
|
|
74
|
+
|
|
75
|
+
export default config;
|
|
74
76
|
```
|
|
75
77
|
|
|
76
78
|
### SCSS
|
|
77
79
|
|
|
78
80
|
```js title="stylelint.config.mjs"
|
|
79
81
|
/** @type {import("stylelint").Config} */
|
|
80
|
-
|
|
82
|
+
const config = {
|
|
81
83
|
ignoreFiles: ["**/vendor/**"],
|
|
82
84
|
extends: [
|
|
83
85
|
"stylelint-config-standard-scss",
|
|
@@ -89,6 +91,8 @@ export default {
|
|
|
89
91
|
"color-function-notation": "modern",
|
|
90
92
|
},
|
|
91
93
|
};
|
|
94
|
+
|
|
95
|
+
export default config;
|
|
92
96
|
```
|
|
93
97
|
|
|
94
98
|
### Project-specific overrides
|
|
@@ -96,7 +100,7 @@ export default {
|
|
|
96
100
|
Add to the `rules` block:
|
|
97
101
|
|
|
98
102
|
```js
|
|
99
|
-
|
|
103
|
+
const config = {
|
|
100
104
|
// ...
|
|
101
105
|
rules: {
|
|
102
106
|
// ...
|
|
@@ -104,6 +108,8 @@ export default {
|
|
|
104
108
|
"selector-max-type": 3,
|
|
105
109
|
},
|
|
106
110
|
};
|
|
111
|
+
|
|
112
|
+
export default config;
|
|
107
113
|
```
|
|
108
114
|
|
|
109
115
|
Add a lint script to `package.json`:
|
|
@@ -149,7 +149,11 @@ Each project defines its colours once, in its global stylesheet:
|
|
|
149
149
|
|
|
150
150
|
Tailwind turns every `--color-*` variable in `@theme` into utility classes: `--color-brand-primary` becomes `bg-brand-primary`, `text-brand-primary`, `border-brand-primary` and so on.
|
|
151
151
|
|
|
152
|
-
|
|
152
|
+
**`globals.css` is only for project colours.** Tailwind's built-in colours (`bg-slate-900`) need nothing there. Add a colour to `@theme` only when the design needs one Tailwind does not have, such as the brand colours.
|
|
153
|
+
|
|
154
|
+
**The palette is listed in `docs/design/design-system.md`**, so anyone can see every colour without reading CSS: each colour's name, value, class names and what it is for. The project's other design decisions, the fonts and the spacing, are recorded in the same [Decision Doc](/docs/Standards/documentation).
|
|
155
|
+
|
|
156
|
+
To see each colour in the editor, install **Tailwind CSS IntelliSense** (Tailwind Labs). It shows a swatch of the actual colour beside each class name.
|
|
153
157
|
|
|
154
158
|
### ✅ Use the colours
|
|
155
159
|
|
|
@@ -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, 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#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`.
|
|
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
|
|
|
@@ -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
|