@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.
package/docs/Guides/setup.md
CHANGED
|
@@ -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
|
-
**
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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**:
|
|
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
|
package/docs/version-history.md
CHANGED
|
@@ -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.
|
|
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
|
-
- **
|
|
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.**
|