@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.
Files changed (44) hide show
  1. package/docs/Guides/migrating.md +93 -50
  2. package/docs/Guides/regression-checks.md +72 -0
  3. package/docs/Guides/setup.md +89 -21
  4. package/docs/Standards/documentation.md +54 -7
  5. package/docs/Standards/eslint.md +60 -18
  6. package/docs/Standards/lint-errors.md +4 -4
  7. package/docs/Standards/readable-code.md +4 -1
  8. package/docs/Standards/stylelint.md +9 -3
  9. package/docs/Standards/styling.md +5 -1
  10. package/docs/Standards/working-with-agents.md +5 -5
  11. package/docs/Structure/component-organization.md +30 -26
  12. package/docs/Structure/folder-structure.md +85 -32
  13. package/docs/Structure/import-organization.md +4 -4
  14. package/docs/design-system-components.md +16 -12
  15. package/docs/ontology.md +1 -1
  16. package/docs/templates.mdx +12 -4
  17. package/docs/version-history.md +61 -6
  18. package/package.json +6 -2
  19. package/scripts/verifyStandards/checkAgentFiles.mjs +148 -0
  20. package/scripts/verifyStandards/checkComponents.mjs +129 -0
  21. package/scripts/verifyStandards/checkConfigFiles.mjs +230 -0
  22. package/scripts/verifyStandards/checkDocs.mjs +86 -0
  23. package/scripts/verifyStandards/checkRequiredFiles.mjs +96 -0
  24. package/scripts/verifyStandards/formatReport.mjs +76 -0
  25. package/scripts/verifyStandards/projectFiles.mjs +109 -0
  26. package/scripts/verifyStandards/runChecks.mjs +62 -0
  27. package/scripts/verifyStandards/verifyStandards.mjs +22 -0
  28. package/static/templates/AGENTS.md +19 -10
  29. package/static/templates/docs/design/design-system.md +6 -0
  30. package/static/templates/docs/development/coding-standards.md +10 -2
  31. package/static/templates/docs/overview/how-it-works.md +1 -1
  32. package/static/templates/docs/overview/writing-docs.md +4 -0
  33. package/static/templates/docs/product/ontology.md +32 -0
  34. package/static/templates/eslint/base/eslint.config.mjs +9 -0
  35. package/static/templates/eslint/nextjs/eslint.config.mjs +11 -1
  36. package/static/templates/eslint/react/eslint.config.mjs +11 -1
  37. package/static/templates/eslint/typescript/eslint.config.mjs +9 -0
  38. package/static/templates/eslint.overrides.mjs +18 -0
  39. package/static/templates/skills/codeReview.md +2 -1
  40. package/static/templates/stylelint/css/stylelint.config.mjs +3 -1
  41. package/static/templates/stylelint/scss/stylelint.config.mjs +3 -1
  42. package/static/templates/tests/visual/pageLayout.visual.ts +188 -0
  43. package/static/templates/tests/visual/playwright.config.mjs +65 -0
  44. package/static/templates/tests/visual/visualPages.mjs +3 -0
@@ -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** and update the number when the project upgrades React. pnpm warns about the unmet peer dependency on install; that warning is expected.
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
- // Update the number when the project upgrades React.
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
- Set `settings.react.version` to the project's React version rather than `"detect"`. On ESLint 10, `eslint-plugin-react` 7 crashes while detecting the version (`contextOrFilename.getFilename is not a function`).
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
- // Update the number when the project upgrades React.
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
- Add a block before `prettier` to add or override rules:
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
- ```js
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
- export default config;
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
- A number used in one file is named at the top of that file. One shared across the app goes in `lib/constants/`, in a file named after its topic. See [Numbers](/docs/Structure/folder-structure#numbers-named-and-kept-by-topic) for where they go, and [Naming Conventions](/docs/Structure/naming-conventions#constants) for how to name them.
316
+ 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
- export default {
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
- export default {
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
- export default {
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
- The project's design decisions — what each colour is for, the fonts, the spacing — are recorded in its `docs/design/design-system.md` [Decision Doc](/docs/Standards/documentation).
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 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
 
@@ -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