@activatus/code-standards 3.3.7 → 3.3.8

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.
@@ -92,6 +92,7 @@ Tell me the numbers to skip or change, or say "all good".
92
92
  15. Design System Components: every project builds the standard components with the same props
93
93
  16. Imports: no circular imports, import from folders not files
94
94
  17. API routes: one folder per route, kebab-case
95
+ 17.1. Sitemap: a project with public pages keeps app/sitemap.ts in sync as it routes
95
96
  18. Docs: every file in docs/ is a Decision Doc, shown at /docs by the docs site
96
97
  19. Removed in version 3: commit messages are the project's own workflow
97
98
  20. Removed in version 3: branch names are the project's own workflow
@@ -125,6 +126,8 @@ Then wait for the answer.
125
126
 
126
127
  **Every path after `for` goes in backticks**: a `for` with none fails the check, because it would otherwise cover every file. **Start no other line under "Details" with a number.** The [standards check](#checking-a-project) reads a line that starts with a number as an exception to that standard, and fails on one it cannot read. Use bullet points for anything else. If nothing is different, write "No differences". Copy the file from `static/templates/docs/development/coding-standards.md` if it does not exist.
127
128
 
129
+ **Biome.** If the project already lints or formats with Biome, ask the person: keep Biome, or move to the standards' ESLint and Prettier? Keeping it is recorded as two exception lines, `6. ESLint — skipped` and `7. Prettier — skipped`, with the reason. A project that keeps Biome runs it by its own setup — the standards ship no Biome config. If the project has no Biome, use ours and ask nothing: do not offer Biome to a project that does not have it.
130
+
128
131
  The list has nothing about branches or commit messages. Those are the project's own workflow. Ask the person how they work, and write it in the "Project workflow" section of `AGENTS.md`. See [Project workflow](/docs/Standards/agent-specs#project-workflow).
129
132
 
130
133
  **Then go straight to step 4.** Setup is not finished until the person has answered it.
@@ -29,7 +29,7 @@ export const Button = () => {
29
29
 
30
30
  **Build every layout with flexbox.** Reach for `flex` first, and split the layout into child components so each one styles only itself.
31
31
 
32
- **Only use CSS grid when it is specifically asked for.**
32
+ **Use CSS grid only when it is genuinely the better tool — and say so when you do.** It is rare: almost everything is a one-dimensional run of boxes, and flexbox aligns it. When a layout is genuinely two-dimensional — a card grid, an aligned table of panels — use grid, and tell the person why grid fits this case. **The [Card Grid](/docs/design-system-components#cta-forms) Design System Component is the standing exception**: when the design asks for a Card Grid, that is the ask, and it uses grid.
33
33
 
34
34
  ### ✅ Flex parent, child components
35
35
 
@@ -96,13 +96,13 @@ export const PageHeader = () => {
96
96
  - **The parent positions, the child styles itself.** A parent sets direction, spacing and alignment. Each child component owns its own padding, colour and typography.
97
97
  - **Split into child components** rather than growing one long `className` or a deep tree of `div`s. Each child gets [its own folder](/docs/Structure/component-organization#nested-components).
98
98
  - **Space with `gap`**, not margins on the children.
99
- - **Grid only when asked.** Do not choose CSS grid on your own — use it only when the task specifically asks for a grid.
99
+ - **Grid only when it is the better tool.** Flexbox covers almost every layout. Use CSS grid when the layout is genuinely two-dimensional — a card grid, an aligned table of panels — and flag the choice: tell the person grid fits this case, or leave a comment saying why.
100
100
 
101
101
  ---
102
102
 
103
103
  ## ❌ Avoid These
104
104
 
105
- - ❌ **CSS grid**, unless it was specifically asked for
105
+ - ❌ **CSS grid for a one-dimensional run of boxes** — flexbox aligns it; grid only when the layout is genuinely two-dimensional, with the choice flagged
106
106
 
107
107
  - ❌ **Hard-coded colours** — hex, `rgb()` or named colours anywhere outside the theme
108
108
  - ❌ **Arbitrary colour values** (`bg-[#3b82f6]`) — if the colour is not in the palette, it is not used
@@ -192,7 +192,7 @@ Tailwind's built-in colours are variables too — `white` is `var(--color-white)
192
192
  ### Tailwind utilities
193
193
 
194
194
  - **Use for**: All component styling
195
- - **Layout**: Flexbox first; grid only when specifically asked
195
+ - **Layout**: Flexbox first; grid when it is genuinely the better tool, flagged to the person
196
196
  - **Colours**: Global palette only — Tailwind colours and project colours from `@theme` — never arbitrary values
197
197
  - **Long class lists**: Extract a component, not a CSS class
198
198
  - **Conditional classes**: Use `clsx`
@@ -11,13 +11,17 @@ Standard technology choices for Activatus projects.
11
11
  ## 📋 Standard Stack
12
12
 
13
13
  - **Framework**: Next.js 16 (App Router)
14
- - **Language**: TypeScript 7
14
+ - **Language**: TypeScript, latest stable — 7 at the time of writing
15
15
  - **Package Manager**: pnpm (monorepo: workspaces)
16
16
  - **Styling**: Tailwind CSS
17
17
  - **Node Version**: `^22.11 || ^24 || >=26`
18
18
  - **Build Tool**: Turbopack (Next.js built-in)
19
19
 
20
- ### TypeScript 7
20
+ ### The latest TypeScript
21
+
22
+ **A project uses the latest stable TypeScript.** The standards do not pin a
23
+ major: when a new one ships and the tooling around it has caught up, a project
24
+ moves up. The notes below describe 7, the latest at the time of writing.
21
25
 
22
26
  TypeScript 7 is the compiler rewritten in Go. It is a drop-in replacement for
23
27
  the JavaScript implementation for compiling and type-checking, but two things
@@ -134,7 +138,7 @@ See `package.json` for specific version requirements. Key dependencies:
134
138
 
135
139
  ## 🔧 Development Tools
136
140
 
137
- - **Linting**: ESLint 9+
141
+ - **Linting**: ESLint 10.4 or later — the standard config needs it
138
142
  - **Formatting**: Prettier
139
143
  - **Monorepo**: Turborepo
140
144
  - **Documentation**: Docusaurus
@@ -152,6 +156,6 @@ See `package.json` for specific version requirements. Key dependencies:
152
156
 
153
157
  ### TypeScript
154
158
 
155
- - **Version**: 5.0+
159
+ - **Version**: the latest stable — 7 at the time of writing, run side by side with the TypeScript 6 API for linting until `typescript-eslint` supports 7 (see the [note on the ESLint page](/docs/Standards/eslint#installation))
156
160
  - **Strict Mode**: Enabled
157
161
  - **Target**: ES2022+
@@ -136,6 +136,16 @@ Functions written for one route handler follow the [utils ladder](/docs/Structur
136
136
 
137
137
  ---
138
138
 
139
+ ## 🗺️ The sitemap travels with the routes {#sitemap}
140
+
141
+ **A project with public pages keeps `app/sitemap.ts` in sync as it routes** — never as a cleanup at the end. When a public page is added, its URL goes into the sitemap in the same change; when one is renamed or removed, its line changes or goes in the same change. The sitemap is how search engines learn the pages exist, so a page that is routed but not listed is a page nobody is told about.
142
+
143
+ - **Build it with the routing, not after it.** Adding the page and updating `app/sitemap.ts` is one change, not two.
144
+ - **Public pages only.** Pages behind sign-in, API routes and route handlers that redirect are not listed.
145
+ - **A project with no public pages has no sitemap**, and that is correct — build one the day the first public page arrives.
146
+
147
+ ---
148
+
139
149
  ## 📚 Related Documentation
140
150
 
141
151
  - [Folder Structure](/docs/Structure/folder-structure) - Overall project structure
@@ -74,6 +74,36 @@ Anyone changing the standards adds a version, alongside the change:
74
74
 
75
75
  Install it with `pnpm add -D @activatus/code-standards@latest`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
76
76
 
77
+ ## Version 3.3.8 — not released yet
78
+
79
+ Do not apply this version yet. Changes are added to it over time.
80
+
81
+ **Fixes in 3.3.8.** If the project already applied 3.3.7, check these:
82
+
83
+ - **The version contradictions are fixed.** The Tech Stack page said "Linting: ESLint 9+" while the standard config needs ESLint 10.4 or later, and said "TypeScript 7" in its stack list while its version requirements said "5.0+". Both now agree. **What to do:** nothing — this fixes the site's words, not any config a project copies.
84
+
85
+ - **TypeScript is "latest stable", not a pinned major.** The stack said "TypeScript 7", which read as a mandate for a major the linting ecosystem had not caught up with. Now said: **a project uses the latest stable TypeScript** — 7 at the time of writing — and moves up when a new major ships and its tooling has caught up. A project that stays on an older major records it as an exception with the reason. **What to do:** nothing, if the project is on the latest stable that its tooling supports. If it is on an older major on purpose, record the exception; if it can move up, do.
86
+
87
+ - **Grid is allowed when it is genuinely better — flagged.** The rule was "only use CSS grid when it is specifically asked for", which read as a ban, but some layouts are genuinely two-dimensional and grid is the right tool for them. Now said: **flexbox first, always; use grid when the layout is genuinely two-dimensional — a card grid, an aligned table of panels — and say so when you do**, to the person or in a comment. The [Card Grid](/docs/design-system-components#cta-forms) Design System Component is the standing exception: a design that asks for one is the ask. See [Layout: Flexbox First](/docs/Standards/styling#-layout-flexbox-first).
88
+
89
+ **What to do:** nothing — this loosens the rule, so no project has anything to unwind. The `AGENTS.md` copy from 3.3.7 carries the new wording into the project.
90
+
91
+ - **A new standard, 17.1: the sitemap travels with the routes.** A project with public pages keeps `app/sitemap.ts` in sync as it routes: a public page added, renamed or removed changes the sitemap in the same change, never as a cleanup at the end. Public pages only — pages behind sign-in, API routes and redirecting handlers are not listed. A project with no public pages has no sitemap until the first one arrives. See [The sitemap travels with the routes](/docs/Structure/api-routes#sitemap).
92
+
93
+ **What to do:** if the project has public pages, check `app/sitemap.ts` exists and lists every one of them; build or complete it if not. If it has none, nothing. The `AGENTS.md` copy from 3.3.7 carries the rule into the project.
94
+
95
+ - **Setup asks about Biome when the project already has it.** A project that already lints or formats with Biome is asked at setup: keep Biome, or move to the standards' ESLint and Prettier? Keeping it is recorded as `6. ESLint — skipped` and `7. Prettier — skipped`, with the reason, and it runs by its own setup — the standards ship no Biome config. A project with no Biome gets no question: it uses ours. See [Agree the standards](/docs/Guides/setup#3-agree-the-standards).
96
+
97
+ **What to do:** for a project set up before this version that uses Biome, check the two exception lines are recorded in `docs/development/coding-standards.md`; ask and record them if not. Every other project: nothing.
98
+
99
+ **How to check:** `pnpm standards:check` passes, or lists only recorded exceptions; a project with public pages has an `app/sitemap.ts` that lists them; a project using Biome has its two exception lines recorded.
100
+
101
+ ## Version 3.3.9 — not released yet
102
+
103
+ Do not apply this version yet. Changes are added to it over time.
104
+
105
+ - **A second package in the repo.** The standards and `pnpm standards:check` only look at the project root, so a second package — a Cloudflare Worker beside the app, a second app in a monorepo — is uncharted. A future version says when a repo carries a second package, what follows the standards and what gets a recorded exception. Requested by a project whose repo carries a worker beside the app.
106
+
77
107
  **Fixes in 3.3.7.** If the project already applied 3.3.6, check these:
78
108
 
79
109
  - **A new word, "ship", and a sixth setup question.** "Ship" means: commit the current change, push it, and open a Pull Request whose description says why the change was made, what changed, how it was checked, with the results, and what the reviewer should look at closely, and links the ticket. It is the yes for those three steps, for that one change only. It is a project workflow choice, not a code standard, so setup now asks it in [step 4](/docs/Guides/setup#4-working-with-the-agent) beside the other five, and `pnpm standards:check` reports a project whose answers do not include it. See [Ship](/docs/Standards/working-with-agents#ship) and the [ontology](/docs/ontology).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@activatus/code-standards",
3
- "version": "3.3.7",
3
+ "version": "3.3.8",
4
4
  "description": "The Activatus code standards: the rules as Markdown, and the config files to copy. Install it so an AI agent can read the standards from node_modules.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -157,7 +157,8 @@ Follow these rules in every change:
157
157
  - **Custom hooks live in a `hooks/` folder the same way** — global, section or component level — one folder per hook, named after it, with its test and an `index.ts`. Move a hook up a level when a second user needs it. Never a hook inside the component file.
158
158
  - **Components live where they are used:** Design System Components in `components/ui/`, plus any props-only component not on the list yet, recorded under "Components for the standards" in `docs/development/coding-standards.md`; the site frame (navigation, header, footer) in `components/layout/`; the homepage's components in `app/(homepage)/components/`; components used on three or more pages in `components/shared/`; components used by three or more pages in one section in that section's route group (`app/(billing)/components/`); everything else in its page's `components/` folder. Start a new component beside its page. When a second page needs it, copy it there: one copy only, and each copy has a comment naming the other. When a third page needs it, merge the copies into one shared component, with props designed from all three uses. No `components/features/` folder.
159
159
  - **Code file names are camelCase**; component files are PascalCase. **Anything that becomes a URL is kebab-case**: route folders and documentation folders and files (`docs/architecture/background-jobs.md`). CSS variables are kebab-case too.
160
- - **Lay out with flexbox first**, and split layouts into child components. Only use CSS grid when specifically asked.
160
+ - **The sitemap travels with the routes.** When a public page is added, renamed or removed, its line in `app/sitemap.ts` changes in the same change — never as a cleanup at the end. Public pages only: pages behind sign-in, API routes and redirecting handlers are not listed. A project with no public pages has no sitemap until the first one arrives.
161
+ - **Lay out with flexbox first**, and split layouts into child components. **Use CSS grid only when it is genuinely the better tool** — a card grid, two-dimensional alignment — and say so when you do: tell the person grid fits this case. The Card Grid Design System Component is the standing exception: when the design asks for one, that is the ask.
161
162
  - **Style with Tailwind.** Colours come from the global colour palette in `app/globals.css` only — never a hard-coded or arbitrary colour. The design decisions are in `docs/design/design-system.md`.
162
163
  - **Comments explain why, not what.** Never leave commented-out code. Mark unfinished work with `// TODO: Message` (`{/* TODO: Message */}` in JSX).
163
164
  - **Error messages say what happened and what to do.**